docs: per-agent reference with icons, commands, and labels

.pre-commit-config.yaml

@@ -100,3 +100,10 @@ repos:
         language: script
         files: ^internal/scaffold/fullsend-repo/(\.github/workflows/|templates/)
         pass_filenames: false
+
+      - id: lint-agent-docs
+        name: lint agent doc references
+        entry: ./hack/lint-agent-docs
+        language: script
+        files: ^(internal/scaffold/fullsend-repo/harness/|docs/agents/)
+        pass_filenames: false

docs/agents/README.md

@@ -0,0 +1,27 @@
+# Default Agents
+
+Reference documentation for the default agents shipped by fullsend.
+All agents below are enabled by default. The set of default agents is defined by
+the YAML files in [`internal/scaffold/fullsend-repo/harness/`](../../internal/scaffold/fullsend-repo/harness/).
+
+| Agent | Summary |
+|-------|---------|
+| [Triage](triage.md) | Inspects new issues and produces structured triage decisions |
+| [Prioritize](prioritize.md) | Scores issues using the RICE framework for project board ranking |
+| [Code](code.md) | Implements fixes and features from triaged issues |
+| [Review](review.md) | Reviews pull requests for correctness, security, and intent alignment |
+| [Fix](fix.md) | Addresses review feedback on open PRs |
+| [Retro](retro.md) | Analyzes completed workflows and proposes system improvements |
+
+## Customization
+
+All agents can be customized by adding instructions and skills to your
+repository. Changes to `AGENTS.md` affect every agent; skills let you tune how
+a specific agent performs a specific task. See
+[Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
+[Customizing with Skills](../guides/user/customizing-with-skills.md).
+
+## Custom Agents
+
+Support for adding your own custom agents to the fullsend pipeline is coming
+soon.

docs/agents/code.md

@@ -0,0 +1,49 @@
+# Code Agent
+
+![Code agent icon](icons/coder.png)
+
+Implementation specialist that reads triaged GitHub issues, implements fixes or features following repository conventions, runs tests and linters, and commits to a local feature branch.
+
+## How the agent works
+
+Triggered when the `ready-to-code` label is applied to an issue or via `/fs-code`.
+
+The code agent follows a three-phase pipeline: pre-script, sandbox execution, post-script.
+
+1. **Pre-script** validates inputs on the runner before sandbox creation. It also checks for open PRs linked to the issue.
+2. **Sandbox** — the agent reads the issue, explores the codebase, writes code, runs tests and linters, and commits locally. It has no network access (enforced by OpenShell).
+3. **Post-script** runs on the runner: it performs protected path checks, secret scanning, pre-commit checks, pushes the branch, and creates the PR.
+
+This separation ensures the agent never has direct write access to the repository.
+
+## How it helps
+
+- Triaged issues can go from "ready" to "PR open" without human involvement.
+- Implementation follows repo conventions because the agent reads existing code, tests, and linter configs before writing.
+- The sandboxed execution model means a misbehaving agent cannot push arbitrary code — the post-script gates everything.
+
+## Commands
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/fs-code` | Issue comment | Triggers the code agent on the issue |
+
+The `/fs-code` command accepts an optional `--force` flag. It can only be used
+on issues (not PRs). The code agent is also triggered automatically when the
+`ready-to-code` label is applied to an issue.
+
+## Control labels
+
+| Label | Meaning |
+|-------|---------|
+| `ready-to-code` | Triggers the code agent. Applied by the [triage](triage.md) post-script for low-risk categories (bug, documentation, performance), or manually by a human for feature work after prioritization. |
+| `ready-for-review` | Applied by the code agent's post-script after pushing a PR. Signals the [review agent](review.md) to evaluate the change. |
+
+## Configuration and extension
+
+See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
+[Customizing with Skills](../guides/user/customizing-with-skills.md).
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/code.yaml`](../../internal/scaffold/fullsend-repo/harness/code.yaml)

docs/agents/fix.md

@@ -0,0 +1,58 @@
+# Fix Agent
+
+<img src="icons/coder.png" alt="Fix agent icon" width="80">
+
+Review-feedback specialist that reads review comments on open PRs, implements targeted fixes, runs tests and linters, and commits the result.
+
+## How the agent works
+
+The fix agent is triggered when the [review agent](review.md) requests changes or when a human issues a `/fs-fix` command on a PR. It follows the same sandboxed pipeline as the [code agent](code.md).
+
+1. **Pre-script** validates inputs and checks the iteration cap (preventing infinite fix loops).
+2. **Sandbox** — the agent reads each review finding, implements targeted fixes, and verifies them against tests and linters.
+3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
+4. **Post-script** pushes the commit and posts a summary comment on the PR.
+
+## How it helps
+
+- Review feedback is addressed quickly — often before the reviewer checks back.
+- Fixes are scoped to exactly what the review requested, reducing churn.
+- The iteration cap prevents the fix and [review](review.md) agents from looping indefinitely.
+
+## Commands
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/fs-fix` | PR comment | Triggers the fix agent on the PR |
+| `/fs-fix-stop` | PR comment | Disables the fix agent for this PR |
+
+The `/fs-fix` command accepts optional free-text instructions after the
+command. The text is passed to the agent as a human instruction, giving you
+direct control over what to fix:
+
+- `/fs-fix` — fix whatever the [review agent](review.md) flagged
+- `/fs-fix you forgot to update the docs here`
+- `/fs-fix the error handling in processItem needs to distinguish between retryable and fatal errors`
+
+The fix agent also triggers automatically when the [review agent](review.md) submits a
+"changes requested" review on a same-repo PR (fork PRs are blocked).
+
+`/fs-fix-stop` adds the `fullsend-no-fix` label to the PR, preventing any
+further bot-triggered fix runs. Human-triggered `/fs-fix` commands still work.
+Remove the label or use `/fs-fix` to re-engage.
+
+## Control labels
+
+| Label | Meaning |
+|-------|---------|
+| `fullsend-no-fix` | Prevents bot-triggered fix runs on this PR. Applied by `/fs-fix-stop`. Human `/fs-fix` commands are unaffected. |
+| `needs-human` | The fix agent is approaching its iteration cap and needs human direction. Applied automatically when the fix iteration reaches the warning threshold. |
+
+## Configuration and extension
+
+See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
+[Customizing with Skills](../guides/user/customizing-with-skills.md).
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/fix.yaml`](../../internal/scaffold/fullsend-repo/harness/fix.yaml)

docs/agents/icons/COLORS.md

@@ -0,0 +1,18 @@
+# Icon Circle Colors
+
+Original background circle color for each agent icon.
+
+| Icon | Hex | RGB |
+|------|-----|-----|
+| bootstrap | `#1d4f5d` | 29, 79, 93 |
+| coder | `#8b687d` | 139, 104, 125 |
+| discovery | `#b7cc63` | 183, 204, 99 |
+| prioritize | `#f08175` | 240, 129, 117 |
+| refinement | `#916b7c` | 145, 107, 124 |
+| retro | `#e9b240` | 233, 178, 64 |
+| review | `#b4c651` | 180, 198, 81 |
+| scribe | `#eb8176` | 235, 129, 118 |
+| tech-research | `#1d4d5a` | 29, 77, 90 |
+| triage | `#c95d36` | 201, 93, 54 |
+| upstream | `#4b737c` | 75, 115, 124 |
+| user-research | `#f08276` | 240, 130, 118 |

docs/agents/prioritize.md

@@ -0,0 +1,60 @@
+# Prioritize Agent
+
+<img src="icons/prioritize.png" alt="Prioritize agent icon" width="80">
+
+Scores a GitHub issue using the RICE framework (Reach, Impact, Confidence, Effort) and produces structured scores with reasoning for project board ranking.
+
+## How the agent works
+
+Triggered on a schedule (the prioritize scheduler polls the project board for unscored or stale issues) or on-demand via `/fs-prioritize`.
+
+The prioritize agent fetches the issue and all its context, then evaluates it across the four RICE dimensions. It can invoke customer-research skills to gather additional signal about reach and impact. The output is a structured JSON result with per-dimension scores and written reasoning, which the post-script uses to update the project board.
+
+## How it helps
+
+- Issues are ranked consistently using the same framework, reducing bias from whoever happens to see them first.
+- Scoring reasoning is transparent and auditable — anyone can read why an issue was ranked the way it was.
+- Project boards stay sorted by value, so humans can focus on the highest-impact work first.
+
+## Commands
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/fs-prioritize` | Issue comment | Runs RICE scoring on the issue |
+
+The `/fs-prioritize` command does not accept arguments. It scores the issue
+using the current content, comments, and any available `customer-research`
+skill data.
+
+## Control labels
+
+The prioritize agent does not apply or consume control labels. It reads the
+issue content and produces a structured score — the post-script updates the
+project board directly.
+
+## Configuration and extension
+
+### Skill: `customer-research`
+
+The prioritize agent looks for a `customer-research` skill and, when available,
+uses it to inform Reach and Impact scores. To provide it, create a skill directory
+in your target repository at `.agents/skills/customer-research/` with a `SKILL.md` and
+any helper scripts organized in a `scripts/` subdirectory. Then symlink `.claude/skills`
+to `.agents/skills` so the skill is discoverable by both Fullsend and any local
+agent tooling:
+
+```
+your-repo/
+  .agents/skills/customer-research/
+    SKILL.md
+    scripts/
+  .claude/skills -> ../.agents/skills
+```
+
+This gives the prioritize agent concrete data to distinguish between "one user
+wants this" (Reach 0.25) and "three strategic accounts have filed support cases
+about it" (Reach 2.0), instead of guessing from the issue text alone.
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/prioritize.yaml`](../../internal/scaffold/fullsend-repo/harness/prioritize.yaml)

docs/agents/retro.md

@@ -0,0 +1,51 @@
+# Retro Agent
+
+<img src="icons/retro.png" alt="Retro agent icon" width="80">
+
+Performs retrospectives on agent workflows — analyzes what happened, identifies improvement opportunities, and proposes changes as structured GitHub issues.
+
+## How the agent works
+
+The retro agent is triggered after a workflow completes (PR merged or closed), or on-demand via `/fs-retro`. It reconstructs the full workflow graph — [triage](triage.md), [code](code.md), [review](review.md), [fix](fix.md), and human interactions — by fetching issue and PR timelines, agent run logs, and review threads.
+
+1. **Pre-script** gathers metadata about the originating PR or issue.
+2. **Sandbox** — the agent reads the full workflow history, identifies patterns (wasted cycles, missed context, repeated failures), and writes structured proposals. It uses the retro-analysis and finding-agent-runs skills. The agent cannot write files or edit code in the target repo.
+3. **Validation loop** — output is checked against a schema, with up to 2 retries.
+4. **Post-script** creates GitHub issues from the agent's proposals.
+
+When triggered via `/fs-retro`, the human's comment is passed to the agent as high-signal direction about what to focus on.
+
+## How it helps
+
+- Every workflow gets a post-mortem, not just the ones that failed badly enough for someone to notice.
+- Improvement proposals are filed as issues with context, so they enter the normal triage/prioritize pipeline.
+- Patterns across multiple retros surface systemic issues (e.g., a skill that consistently underperforms).
+
+## Commands
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/fs-retro` | PR or issue comment | Triggers a retrospective analysis |
+
+The `/fs-retro` command accepts optional free-text instructions after the
+command. The text is passed to the agent as high-signal direction about what
+to focus on:
+
+- `/fs-retro` — general retrospective on the workflow
+- `/fs-retro figure out why the review agent approved this and make sure it never happens again`
+- `/fs-retro the code agent spent 30 minutes on a 2-line fix, what went wrong`
+
+The retro agent also runs automatically when a PR is closed (merged or not).
+
+## Control labels
+
+The retro agent does not apply or consume control labels.
+
+## Configuration and extension
+
+See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
+[Customizing with Skills](../guides/user/customizing-with-skills.md).
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/retro.yaml`](../../internal/scaffold/fullsend-repo/harness/retro.yaml)

docs/agents/review.md

@@ -0,0 +1,58 @@
+# Review Agent
+
+<img src="icons/review.png" alt="Review agent icon" width="80">
+
+Code review specialist that evaluates pull requests for correctness, security, intent alignment, style, and documentation currency.
+
+## How the agent works
+
+The review agent is triggered when a PR is opened or updated. It follows the same pre-script / sandbox / post-script pipeline as the other agents.
+
+1. **Pre-script** validates inputs and fetches PR metadata.
+2. **Sandbox** — the agent reads the PR diff, the linked issue (if any), and the surrounding codebase. It applies three review skills (code-review, pr-review, docs-review) to evaluate the change across multiple dimensions. It produces a structured JSON review result. The agent cannot push files, edit code, or push — it is strictly read-only.
+3. **Validation loop** — the output is checked against a schema, with up to 2 retry iterations if the output is malformed.
+4. **Post-script** posts the review on the PR.
+
+If a prior review exists (e.g., re-review after fixes), it is injected into the sandbox so the agent can assess whether previous findings were addressed.
+
+## How it helps
+
+- Every PR gets a thorough review within minutes, regardless of team availability.
+- Reviews cover security, correctness, intent alignment, and docs staleness — dimensions humans sometimes skip under time pressure.
+- The structured output format makes it easy to see what was flagged and why.
+
+## Commands
+
+| Command | Where | Effect |
+|---------|-------|--------|
+| `/fs-review` | Issue or PR comment | Triggers a review |
+
+The `/fs-review` command does not accept arguments. The review agent also runs
+automatically when a PR is opened, synchronized (new commits pushed), or moved
+out of draft.
+
+## Control labels
+
+These labels are applied by the review post-script based on the review outcome.
+
+| Label | Meaning |
+|-------|---------|
+| `ready-for-review` | Signals the review agent to evaluate the PR. Applied by the [code agent](code.md) post-script. |
+| `ready-for-merge` | The review agent approved the PR. No blocking findings. |
+| `requires-manual-review` | The review agent found issues that require human judgment — it could not confidently approve or reject. |
+| `rejected` | The review agent rejected the PR and the post-script closed it. |
+
+When the review agent requests changes (without rejecting), no outcome label is
+applied — the `pull_request_review` event triggers the [fix agent](fix.md) directly.
+
+Stale outcome labels from prior review runs are removed before the new one is
+applied.
+
+## Configuration and extension
+
+See [Customizing with AGENTS.md](../guides/user/customizing-with-agents-md.md) and
+[Customizing with Skills](../guides/user/customizing-with-skills.md).
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/review.yaml`](../../internal/scaffold/fullsend-repo/harness/review.yaml)