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,19 @@
+# Out-of-the-Box Agents
+
+Reference documentation for the agents shipped in fullsend's default harness.
+All agents below are enabled by default. The set of OOTB 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 |
+
+## Bring Your Own Agent (BYOA)
+
+Support for adding your own custom agents to the fullsend pipeline is coming
+soon.

docs/agents/code.md

@@ -0,0 +1,48 @@
+# Code Agent
+
+<img src="icons/coder.png" alt="Code agent icon" width="80">
+
+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
+
+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.
+2. **Sandbox** — the agent reads the issue, explores the codebase, writes code, runs tests and linters, and commits locally. It has no network access to push or create PRs (enforced by `disallowedTools`).
+3. **Post-script** runs on the runner with elevated permissions: it performs protected-path checks, secret scanning, 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 does not accept arguments. 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. |
+
+## Configuration and extension
+
+Detailed harness-level customization is coming soon. Today, the best way to
+influence how the code agent behaves on your repository is by adding
+instructions and skills to the repo itself. See
+[Customizing Agents 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,60 @@
+# 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 the pre-fetched review body, understands each finding, implements targeted fixes, and verifies them against tests and linters. Like the code agent, it cannot push or create PRs.
+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
+
+Detailed harness-level customization is coming soon. Today, the best way to
+influence how the fix agent behaves on your repository is by adding
+instructions and skills to the repo itself. See
+[Customizing Agents 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,141 @@
+# 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
+
+The prioritize agent is triggered after triage. It 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.
+
+The agent runs in a read-only sandbox. It cannot modify issues or push code — it only produces a scored result.
+
+## 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
+
+Detailed harness-level customization is coming soon. Today, the best way to
+influence how the prioritize agent behaves on your repository is by adding
+instructions and skills to the repo itself. See
+[Customizing Agents with Skills](../guides/user/customizing-with-skills.md).
+
+### Example: Providing a customer-research skill
+
+The prioritize agent looks for a `customer-research` skill and, when available,
+uses it to inform Reach and Impact scores. This is not a command — it's an
+agent skill that the prioritize agent invokes automatically during scoring.
+
+To provide one, create a skill directory in your target repository at
+`.claude/skills/customer-research/` with a `SKILL.md` and any helper scripts
+the agent can run to dynamically gather data:
+
+```
+your-repo/
+  .claude/skills/customer-research/
+    SKILL.md
+    query-salesforce.sh
+    search-drive.sh
+```
+
+**`.claude/skills/customer-research/SKILL.md`:**
+
+```markdown
+---
+name: customer-research
+description: >-
+  Gather customer context from Salesforce and Google Drive to inform
+  RICE prioritization scoring.
+---
+
+# Customer Research
+
+Research customer context for the issue being prioritized.
+
+## Step 1: Check Salesforce for affected accounts
+
+Run the Salesforce query script to find accounts with support cases
+related to this issue's feature area:
+
+    bash .claude/skills/customer-research/query-salesforce.sh "SEARCH_TERM"
+
+The script returns a JSON summary of affected accounts by tier
+(Strategic, Enterprise, Growth). Strategic accounts should
+significantly increase the Reach score.
+
+## Step 2: Search Google Drive for strategy and interview documents
+
+Run the Drive search script to find relevant customer interviews,
+roadmap documents, and competitive analysis:
+
+    bash .claude/skills/customer-research/search-drive.sh "SEARCH_TERM"
+
+Look for:
+- Customer interview transcripts mentioning the problem.
+- Strategy or roadmap documents that call out this area.
+- Competitive analysis where this feature is a differentiator.
+
+## Step 3: Summarize findings
+
+Return a short summary (under 500 characters) describing:
+- How many and which tier of customers are affected.
+- Whether this aligns with current strategic priorities.
+- Any direct customer quotes or requests that strengthen the case.
+```
+
+**`.claude/skills/customer-research/query-salesforce.sh`:**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+TERM="$1"
+curl -sf -H "Authorization: Bearer $SFDC_TOKEN" \
+  "$SFDC_URL/services/data/v59.0/query/" \
+  --data-urlencode "q=SELECT Account.Name, Account.Tier__c, Count(Id) cnt
+    FROM Case WHERE Subject LIKE '%${TERM}%'
+    GROUP BY Account.Name, Account.Tier__c
+    ORDER BY cnt DESC LIMIT 20"
+```
+
+**`.claude/skills/customer-research/search-drive.sh`:**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+TERM="$1"
+curl -sf -H "Authorization: Bearer $GDRIVE_TOKEN" \
+  "https://www.googleapis.com/drive/v3/files" \
+  --data-urlencode "q=fullText contains '${TERM}' and mimeType='application/vnd.google-apps.document'" \
+  -d "fields=files(name,modifiedTime,webViewLink)" \
+  -d "orderBy=modifiedTime desc" \
+  -d "pageSize=5"
+```
+
+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. The
+scripts run dynamically during each prioritization, so scores reflect current
+customer data.
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/prioritize.yaml`](../../internal/scaffold/fullsend-repo/harness/prioritize.yaml)

docs/agents/retro.md

@@ -0,0 +1,55 @@
+# 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 is read-only — it 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 as `RETRO_COMMENT` — the agent treats this 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. Its output is
+structured proposals that the post-script files as new GitHub issues, which
+then enter the normal [triage](triage.md)/[prioritize](prioritize.md) pipeline.
+
+## Configuration and extension
+
+Detailed harness-level customization is coming soon. Today, the best way to
+influence how the retro agent behaves on your repository is by adding
+instructions and skills to the repo itself. See
+[Customizing Agents with Skills](../guides/user/customizing-with-skills.md).
+
+## Source
+
+[`internal/scaffold/fullsend-repo/harness/retro.yaml`](../../internal/scaffold/fullsend-repo/harness/retro.yaml)