docs: add crawl-walk-run-fly adoption guide

[maruiz93]

Closes #4969

Summary

• Adds docs/guides/user/adoption.md — an incremental adoption guide that walks teams through four stages (Crawl, Walk, Run, Fly) of fullsend usage, from observing default agents to progressive auto-merge and custom agents
• Adds the guide as the first entry under "User guides" in docs/guides/README.md
• Based on the fullsend team's own dogfooding experience; framed as suggestions, not requirements

Test plan

• Verify all 13 relative cross-reference links resolve correctly in the rendered doc site
• Confirm adoption guide appears first in the User guides list on the guides index page
• Review tone and framing with the team (no automation anxiety, stages are optional, defaults work well out of the box)

🤖 Generated with Claude Code

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 11:18 PM UTC · Completed 11:31 PM UTC
Commit: 452187b · View workflow run →

[qodo-code-review]

PR Summary by Qodo

Docs: add crawl-walk-run-fly incremental adoption guide

📝 Documentation 🕐 20-40 Minutes

AI Description

• Add a Crawl/Walk/Run/Fly playbook for incrementally adopting fullsend agents and automation.
• Link the new adoption guide as the first entry in the User guides index.
• Provide stage-specific enablement steps, signals, and pointers to deeper docs.

Diagram

graph TD
  A["Guides index (README)"] --> B["Adoption guide"]
  B --> C["Getting started"] --> D["Repo customization"]
  B --> E["Agent docs"] --> F["Bugfix workflow"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold content into existing Getting Started docs

• ➕ Keeps onboarding content in one place
• ➕ Reduces navigation surface area (one fewer top-level guide)
• ➖ Blurs the distinction between setup mechanics vs adoption strategy and trust-building
• ➖ Getting Started may become long and harder to scan for first-time installers

2. Provide a checklist-style playbook per stage (with repo-specific templates)

• ➕ More actionable for teams rolling out in a programmatic way
• ➕ Easier to track progress and standardize across many repos
• ➖ More maintenance burden as features/agents evolve
• ➖ May feel prescriptive vs the current "map, not manual" framing

Recommendation: Keep the new standalone adoption guide and prominent index placement. It cleanly separates "how to install" from "how to progressively adopt automation," while using cross-links to reuse existing setup/customization detail. If teams later ask for more operational rigor, consider adding optional stage checklists/templates as an appendix rather than merging into Getting Started.

Files changed (2) +170 / -0

Documentation (2) +170 / -0

README.mdAdd adoption guide as first User guides entry +1/-0

Add adoption guide as first User guides entry

• Adds a new top entry linking to the staged adoption guide. Positions it ahead of other user guides to make incremental rollout guidance discoverable.

docs/guides/README.md

adoption.mdIntroduce Crawl/Walk/Run/Fly fullsend adoption guide +169/-0

Introduce Crawl/Walk/Run/Fly fullsend adoption guide

• Adds a new guide describing four incremental adoption stages, including what to enable, what to observe, and signals to progress. Includes practical prep guidance (AGENTS.md, CI, tests, branch protections) and cross-references to getting started, customization, and agent/workflow docs.

docs/guides/user/adoption.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. What you do not numbered ✓ Resolved 📜 Skill insight ✧ Quality

Description

The guide contains procedural instructions written as prose paragraphs instead of numbered steps.
This makes procedures harder to follow and violates the required format for procedural content.

Code

docs/guides/user/adoption.md[R48-55]

+**What you do:**
+
+Watch agent output for a few weeks. Are triage labels accurate? Are review findings useful? Are priorities reasonable?
+
+Identify where agents lack context — are they misunderstanding your architecture, coding conventions, or domain? Note what's missing for the next stage.
+
+Talk to your team — do people find the feedback helpful or noisy?
+

Relevance

●●● Strong

Team often accepts converting procedural prose into numbered steps for docs consistency (PR #2277,
#2663).

PR-#2277
PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062079 requires procedures to use numbered steps rather than prose paragraphs. The
**What you do:** section in Crawl provides action instructions as unnumbered prose lines.

docs/guides/user/adoption.md[48-55]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Several sections provide step-by-step actions as prose paragraphs (e.g., under `**What you do:**`) rather than using numbered lists.

## Issue Context
Compliance requires procedural content in guides to be expressed as ordered (numbered) steps.

## Fix Focus Areas
- docs/guides/user/adoption.md[48-55]
- docs/guides/user/adoption.md[68-71]
- docs/guides/user/adoption.md[123-130]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. adoption.md missing prerequisites heading ✗ Dismissed 📜 Skill insight ✧ Quality

Description

The new adoption guide starts procedural setup steps without a clearly labeled Prerequisites
section. This violates the guide structure requirement and can cause readers to miss required
access/tools before starting step 1.

Code

docs/guides/user/adoption.md[R11-21]

+## Before You Start
+
+### Install fullsend
+
+Before enabling any agents, you need to get fullsend running in your environment:
+
+1. [Enroll](../getting-started/) your org or repo in a token mint
+2. [Provision inference access](../getting-started/getting-inference.md)
+3. [Configure GitHub](../getting-started/configuring-github.md) — Apps, permissions, webhooks
+4. Optionally set up [org mode](../getting-started/org-mode.md) for multi-repo management
+

Relevance

●●● Strong

Team previously accepted adding explicit “Prerequisites” sections before procedures in docs guides
(PR #2277, #2663).

PR-#2277
PR-#2663

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062078 requires a clearly labeled prerequisites section before procedural steps.
In adoption.md, numbered steps start at line 17 under ### Install fullsend with no preceding
Prerequisites section.

docs/guides/user/adoption.md[11-21]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/user/adoption.md` includes numbered setup steps (`### Install fullsend`) but does not include a clearly labeled `Prerequisites` section before those steps.

## Issue Context
Compliance requires each guide procedure to list prerequisites (access, accounts, tooling) before step 1 so readers can validate readiness.

## Fix Focus Areas
- docs/guides/user/adoption.md[11-22]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. token mint undefined jargon ✗ Dismissed 📜 Skill insight ✧ Quality

Description

The guide introduces domain-specific terms without linking to the glossary or defining them inline
on first use. This can confuse new readers and violates the jargon-definition requirement.

Code

docs/guides/user/adoption.md[R15-20]

+Before enabling any agents, you need to get fullsend running in your environment:
+
+1. [Enroll](../getting-started/) your org or repo in a token mint
+2. [Provision inference access](../getting-started/getting-inference.md)
+3. [Configure GitHub](../getting-started/configuring-github.md) — Apps, permissions, webhooks
+4. Optionally set up [org mode](../getting-started/org-mode.md) for multi-repo management

Relevance

●● Moderate

Mixed evidence: they accept defining unfamiliar terms (PR #665), but rejected some “define term”
asks (PR #2756).

PR-#665
PR-#2756
PR-#136

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062083 requires jargon to be linked to the glossary or defined inline on first
use. The term token mint is introduced in the first numbered setup step without a definition or
glossary link, and org mode is similarly introduced as a term without definition.

docs/guides/user/adoption.md[15-20]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/user/adoption.md` uses domain jargon (e.g., `token mint`, `org mode`) without a first-use definition or a link to `docs/glossary.md`.

## Issue Context
Compliance requires jargon to be defined on first use via a glossary link or inline definition.

## Fix Focus Areas
- docs/guides/user/adoption.md[15-21]
- docs/guides/user/adoption.md[34-38]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

High

• [technical accuracy] docs/guides/user/adoption.md:149 — The Fly section claims auto-merge is controlled via CODE_AUTO_MERGE and CODE_AUTO_MERGE_METHOD environment variables, but neither exists anywhere in the codebase. The actual mechanism is a YAML config field auto_merge (boolean) under defaults in the org config (internal/config/config.go). The merge method is hardcoded to squash (internal/forge/github/github.go) — there is no CODE_AUTO_MERGE_METHOD equivalent. The code agent's documentation (docs/agents/code.md) explicitly states "Variables: None." Teams following this guide will set non-functional environment variables.
  Remediation: Replace the env var claims with accurate documentation of the defaults.auto_merge YAML config field. Remove or correct the merge method configurability claim.

Low

• [design-direction] docs/guides/user/adoption.md — The guide targets both "team leads evaluating how to roll out fullsend" and "developers who want to understand what to expect." Per ADR 0023, user/ is for "developers working in repositories where fullsend is active." The team-lead audience partially overlaps with getting-started/. Reasonable editorial choice — noting for future information architecture consideration.

• [incomplete-doc] docs/guides/user/adoption.md — The Crawl section documents the --agents flag and links to configuring-github.md, but later stages (Walk: "Enable the retro agent", Run: "What you enable") use the same "enable" phrasing without cross-referencing the mechanism. A brief callback or link would help readers jumping directly to later stages.

---

Next steps:

• /fs-fix — agent addresses review findings automatically
• /fs-fix <your instruction> — agent fixes with your specific guidance
• Push commits directly — review re-runs automatically on push
• /fs-fix-stop — disable automatic fix runs for this PR

Previous run

Re-review at 3f14520. Content unchanged since prior approval at 2409654 (rebase only). All prior medium-severity findings remain resolved. Issue #4969 linked, authorizing scope.

Technical claims re-verified by correctness sub-agent: code agent scoping (bugs, docs, performance), fix agent bot-authored PR auto-trigger, retro agent post-script issue filing, CODEOWNERS-based auto-merge mechanism, /fs-fix coder app requirement — all accurate against current agent documentation. All 13 cross-reference links resolve. No secrets, injection patterns, or suspicious Unicode.

Remaining notes (non-blocking)

1. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents without explaining the mechanism. A brief inline note or link to the --agents flag on fullsend github setup (documented in configuring-github.md) would help teams follow the staged approach.

2. Guide audience partially overlaps with getting-started — low

File: docs/guides/user/adoption.md

The guide explicitly targets "team leads evaluating how to roll out fullsend, and for developers who want to understand what to expect as usage evolves." Per ADR 0023, user/ is for "developers working in repositories where fullsend is active." The developer-facing half fits user/, but the team-lead-facing half aligns more with getting-started/. This is a reasonable editorial choice — noting for future information architecture consideration.

Previous run (2)

Re-review at 2409654. Content unchanged since prior approval at 1b5d691 (rebase only). All prior medium-severity findings remain resolved. Issue #4969 now linked, resolving the prior "no linked issue" note.

Technical claims re-verified: code agent scoping (bugs, docs, performance), fix agent bot-authored PR auto-trigger, retro agent post-script issue filing, CODEOWNERS-based auto-merge mechanism — all accurate against current agent documentation. All 13 cross-reference links resolve. No secrets, injection patterns, or suspicious Unicode.

Remaining notes (non-blocking)

1. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents without explaining the mechanism. A brief inline note or link to the --agents flag on fullsend github setup (documented in configuring-github.md) would help teams follow the staged approach.

Previous run

Review — approve

Re-review at 1b5d691. All four medium-severity findings from the original review are now resolved across commits 26f8bb7 and 1b5d691:

• ✅ Code agent scoping — correctly says "bugs, docs, and performance issues" (fixed in 26f8bb7)
• ✅ Fix agent framing — correctly describes bot-authored PR auto-trigger (fixed in 26f8bb7)
• ✅ Retro agent issue filing — correctly references the post-script (fixed in 26f8bb7)
• ✅ Missing VitePress sidebar entry — added { text: "Adopting Fullsend Incrementally", link: "/guides/user/adoption" } to the User Guides section (fixed in 1b5d691)

The new commit also adds a note that /fs-fix requires the coder GitHub App — verified accurate against fix.md (the fix agent reuses the coder app identity and its post-script pushes commits).

All 13 cross-reference links resolve correctly. No secrets, injection patterns, or suspicious Unicode detected. Technical claims verified against authoritative agent documentation. Sidebar and README entries follow established formatting patterns.

Remaining notes (non-blocking)

1. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents without explaining the mechanism. A brief inline note or link to the --agents flag on fullsend github setup (documented in configuring-github.md) would help teams follow the staged approach.

2. No linked issue — low

File: docs/guides/user/adoption.md

This is a 173-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

Previous run (3)

Review — comment

Re-review at 26f8bb7. The prior review (at 452187b) identified four medium-severity and three low-severity findings. The author addressed three of the four medium findings in commit 26f8bb7:

• ✅ Code agent scoping — now correctly says "bugs, docs, and performance issues" instead of just "bug fixes," matching triage's ready-to-code label behavior (verified against triage.md and code.md)
• ✅ Fix agent framing — now correctly describes bot-authored PR auto-trigger instead of a misleading "automatic mode" toggle (verified against fix.md lines 119–130)
• ✅ Retro agent issue filing — now correctly references the post-script instead of a non-existent "filing issues skill" (verified against retro.md line 14)

All three fixes verified against the actual agent documentation. The technical accuracy of the guide is solid.

One medium-severity finding from the prior review remains unaddressed. No new issues introduced.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry, the adoption guide won't appear in the website sidebar navigation — it will only be reachable via the README link or direct URL.

Remediation: Add { text: "Adoption Guide", link: "/guides/user/adoption" } to the User Guides items array in website/.vitepress/config.ts.

2. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The guide links to configuring-github.md and customizing-agents.md, but a brief inline note or link to the specific enable/disable mechanism would help teams follow the staged approach without navigating away.

3. No linked issue — low

File: docs/guides/user/adoption.md

This is a 172-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

All cross-reference links (13 total) resolve correctly. No security concerns (no secrets, injection patterns, or suspicious Unicode). Documentation formatting follows established patterns in the user guides directory.

Previous run

Review — comment

Useful documentation contribution that provides a clear incremental adoption path. The crawl-walk-run-fly framing is well-structured and the tone is appropriate (suggestions, not requirements). All 12 unique cross-reference link targets resolve correctly.

Four medium-severity findings relate to a missing VitePress sidebar entry and three technical accuracy issues that could mislead teams following the guide. None are blocking, but fixing them would improve the guide's discoverability and reliability.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry like { text: "Adoption Guide", link: "/guides/user/adoption" }, the new guide won't appear in the website sidebar navigation. It will only be reachable via the README link or direct URL.

2. "Scoped to bug fixes by default" contradicts preceding sentence — medium

File: docs/guides/user/adoption.md (Run stage, code agent bullet)

The code agent bullet first correctly states the ready-to-code label is applied by triage for "bugs, docs, and performance issues," then immediately narrows to "it's scoped to bug fixes by default." Per the triage agent and code agent docs, ready-to-code covers bug, documentation, and performance issue categories. The second sentence should match: "scoped to bugs, docs, and performance issues by default."

3. Fix agent "automatic mode" framing is misleading — medium

File: docs/guides/user/adoption.md (Run stage, fix agent bullet)

The guide describes the fix agent as having an "automatic mode" that gets enabled in the Run stage. In reality, the fix agent always auto-triggers on bot-authored PRs when the review agent requests changes. What changes in the Run stage is that the code agent starts producing bot-authored PRs, making auto-fix behavior visible. For human-authored PRs, automatic fixing requires the fullsend-fix label. The current framing as a mode toggle may lead teams to expect auto-fix on their human-authored PRs.

4. "Filing issues skill" for retro agent does not exist — medium

File: docs/guides/user/adoption.md (Walk stage, retro paragraph)

The guide says to "pair [the retro agent] with a filing issues skill." The retro agent's harness defines skills retro-analysis, finding-agent-runs, agent-scaffolding, and autonomy-readiness — there is no "filing issues" skill. The repo's skills/filing-issues/SKILL.md is a Claude Code interactive skill, not an agent skill. Issue filing from retro proposals is handled by the post-script (scripts/post-retro.sh). A team following this guidance would look for a non-existent skill to configure.

5. /fs-fix in Crawl requires coder app not mentioned — low

File: docs/guides/user/adoption.md (Crawl stage, optional fix paragraph)

The Crawl stage suggests using /fs-fix on-demand, but the fix agent uses the coder GitHub App. If a team follows Crawl's guidance (triage, prioritize, review only), the coder app may not be installed yet. Consider noting that /fs-fix requires the coder app.

6. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md (multiple stages)

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The --agents flag on fullsend github setup (documented in configuring-github.md) controls this. A brief note or link to the setup mechanism would help teams follow the staged approach.

7. No linked issue for non-trivial change — low

File: docs/guides/user/adoption.md

This is a 170-line addition with no linked issue. While documentation contributions from external contributors commonly lack a pre-authorized issue, the intent is clearly aligned with the project's goals. Consider linking to or filing an issue for traceability.

---

Labels: PR adds user-facing documentation under docs/guides/user/

Previous run (4)

Review — comment

Re-review at 26f8bb7. The prior review (at 452187b) identified four medium-severity and three low-severity findings. The author addressed three of the four medium findings in commit 26f8bb7:

• ✅ Code agent scoping — now correctly says "bugs, docs, and performance issues" instead of just "bug fixes," matching triage's ready-to-code label behavior (verified against triage.md and code.md)
• ✅ Fix agent framing — now correctly describes bot-authored PR auto-trigger instead of a misleading "automatic mode" toggle (verified against fix.md lines 119–130)
• ✅ Retro agent issue filing — now correctly references the post-script instead of a non-existent "filing issues skill" (verified against retro.md line 14)

All three fixes verified against the actual agent documentation. The technical accuracy of the guide is solid.

One medium-severity finding from the prior review remains unaddressed. No new issues introduced.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry, the adoption guide won't appear in the website sidebar navigation — it will only be reachable via the README link or direct URL.

Remediation: Add { text: "Adoption Guide", link: "/guides/user/adoption" } to the User Guides items array in website/.vitepress/config.ts.

2. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The guide links to configuring-github.md and customizing-agents.md, but a brief inline note or link to the specific enable/disable mechanism would help teams follow the staged approach without navigating away.

3. No linked issue — low

File: docs/guides/user/adoption.md

This is a 172-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

All cross-reference links (13 total) resolve correctly. No security concerns (no secrets, injection patterns, or suspicious Unicode). Documentation formatting follows established patterns in the user guides directory.

Previous run (5)

Review — comment

Useful documentation contribution that provides a clear incremental adoption path. The crawl-walk-run-fly framing is well-structured and the tone is appropriate (suggestions, not requirements). All 12 unique cross-reference link targets resolve correctly.

Four medium-severity findings relate to a missing VitePress sidebar entry and three technical accuracy issues that could mislead teams following the guide. None are blocking, but fixing them would improve the guide's discoverability and reliability.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry like { text: "Adoption Guide", link: "/guides/user/adoption" }, the new guide won't appear in the website sidebar navigation. It will only be reachable via the README link or direct URL.

2. "Scoped to bug fixes by default" contradicts preceding sentence — medium

File: docs/guides/user/adoption.md (Run stage, code agent bullet)

The code agent bullet first correctly states the ready-to-code label is applied by triage for "bugs, docs, and performance issues," then immediately narrows to "it's scoped to bug fixes by default." Per the triage agent and code agent docs, ready-to-code covers bug, documentation, and performance issue categories. The second sentence should match: "scoped to bugs, docs, and performance issues by default."

3. Fix agent "automatic mode" framing is misleading — medium

File: docs/guides/user/adoption.md (Run stage, fix agent bullet)

The guide describes the fix agent as having an "automatic mode" that gets enabled in the Run stage. In reality, the fix agent always auto-triggers on bot-authored PRs when the review agent requests changes. What changes in the Run stage is that the code agent starts producing bot-authored PRs, making auto-fix behavior visible. For human-authored PRs, automatic fixing requires the fullsend-fix label. The current framing as a mode toggle may lead teams to expect auto-fix on their human-authored PRs.

4. "Filing issues skill" for retro agent does not exist — medium

File: docs/guides/user/adoption.md (Walk stage, retro paragraph)

The guide says to "pair [the retro agent] with a filing issues skill." The retro agent's harness defines skills retro-analysis, finding-agent-runs, agent-scaffolding, and autonomy-readiness — there is no "filing issues" skill. The repo's skills/filing-issues/SKILL.md is a Claude Code interactive skill, not an agent skill. Issue filing from retro proposals is handled by the post-script (scripts/post-retro.sh). A team following this guidance would look for a non-existent skill to configure.

5. /fs-fix in Crawl requires coder app not mentioned — low

File: docs/guides/user/adoption.md (Crawl stage, optional fix paragraph)

The Crawl stage suggests using /fs-fix on-demand, but the fix agent uses the coder GitHub App. If a team follows Crawl's guidance (triage, prioritize, review only), the coder app may not be installed yet. Consider noting that /fs-fix requires the coder app.

6. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md (multiple stages)

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The --agents flag on fullsend github setup (documented in configuring-github.md) controls this. A brief note or link to the setup mechanism would help teams follow the staged approach.

7. No linked issue for non-trivial change — low

File: docs/guides/user/adoption.md

This is a 170-line addition with no linked issue. While documentation contributions from external contributors commonly lack a pre-authorized issue, the intent is clearly aligned with the project's goals. Consider linking to or filing an issue for traceability.

---

Labels: PR adds user-facing documentation under docs/guides/user/

Previous run (6)

Re-review at 2409654. Content unchanged since prior approval at 1b5d691 (rebase only). All prior medium-severity findings remain resolved. Issue #4969 now linked, resolving the prior "no linked issue" note.

Technical claims re-verified: code agent scoping (bugs, docs, performance), fix agent bot-authored PR auto-trigger, retro agent post-script issue filing, CODEOWNERS-based auto-merge mechanism — all accurate against current agent documentation. All 13 cross-reference links resolve. No secrets, injection patterns, or suspicious Unicode.

Remaining notes (non-blocking)

1. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents without explaining the mechanism. A brief inline note or link to the --agents flag on fullsend github setup (documented in configuring-github.md) would help teams follow the staged approach.

Previous run (7)

Review — approve

Re-review at 1b5d691. All four medium-severity findings from the original review are now resolved across commits 26f8bb7 and 1b5d691:

• ✅ Code agent scoping — correctly says "bugs, docs, and performance issues" (fixed in 26f8bb7)
• ✅ Fix agent framing — correctly describes bot-authored PR auto-trigger (fixed in 26f8bb7)
• ✅ Retro agent issue filing — correctly references the post-script (fixed in 26f8bb7)
• ✅ Missing VitePress sidebar entry — added { text: "Adopting Fullsend Incrementally", link: "/guides/user/adoption" } to the User Guides section (fixed in 1b5d691)

The new commit also adds a note that /fs-fix requires the coder GitHub App — verified accurate against fix.md (the fix agent reuses the coder app identity and its post-script pushes commits).

All 13 cross-reference links resolve correctly. No secrets, injection patterns, or suspicious Unicode detected. Technical claims verified against authoritative agent documentation. Sidebar and README entries follow established formatting patterns.

Remaining notes (non-blocking)

1. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents without explaining the mechanism. A brief inline note or link to the --agents flag on fullsend github setup (documented in configuring-github.md) would help teams follow the staged approach.

2. No linked issue — low

File: docs/guides/user/adoption.md

This is a 173-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

Previous run (8)

Review — comment

Re-review at 26f8bb7. The prior review (at 452187b) identified four medium-severity and three low-severity findings. The author addressed three of the four medium findings in commit 26f8bb7:

• ✅ Code agent scoping — now correctly says "bugs, docs, and performance issues" instead of just "bug fixes," matching triage's ready-to-code label behavior (verified against triage.md and code.md)
• ✅ Fix agent framing — now correctly describes bot-authored PR auto-trigger instead of a misleading "automatic mode" toggle (verified against fix.md lines 119–130)
• ✅ Retro agent issue filing — now correctly references the post-script instead of a non-existent "filing issues skill" (verified against retro.md line 14)

All three fixes verified against the actual agent documentation. The technical accuracy of the guide is solid.

One medium-severity finding from the prior review remains unaddressed. No new issues introduced.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry, the adoption guide won't appear in the website sidebar navigation — it will only be reachable via the README link or direct URL.

Remediation: Add { text: "Adoption Guide", link: "/guides/user/adoption" } to the User Guides items array in website/.vitepress/config.ts.

2. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The guide links to configuring-github.md and customizing-agents.md, but a brief inline note or link to the specific enable/disable mechanism would help teams follow the staged approach without navigating away.

3. No linked issue — low

File: docs/guides/user/adoption.md

This is a 172-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

All cross-reference links (13 total) resolve correctly. No security concerns (no secrets, injection patterns, or suspicious Unicode). Documentation formatting follows established patterns in the user guides directory.

Previous run

Review — comment

Useful documentation contribution that provides a clear incremental adoption path. The crawl-walk-run-fly framing is well-structured and the tone is appropriate (suggestions, not requirements). All 12 unique cross-reference link targets resolve correctly.

Four medium-severity findings relate to a missing VitePress sidebar entry and three technical accuracy issues that could mislead teams following the guide. None are blocking, but fixing them would improve the guide's discoverability and reliability.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry like { text: "Adoption Guide", link: "/guides/user/adoption" }, the new guide won't appear in the website sidebar navigation. It will only be reachable via the README link or direct URL.

2. "Scoped to bug fixes by default" contradicts preceding sentence — medium

File: docs/guides/user/adoption.md (Run stage, code agent bullet)

The code agent bullet first correctly states the ready-to-code label is applied by triage for "bugs, docs, and performance issues," then immediately narrows to "it's scoped to bug fixes by default." Per the triage agent and code agent docs, ready-to-code covers bug, documentation, and performance issue categories. The second sentence should match: "scoped to bugs, docs, and performance issues by default."

3. Fix agent "automatic mode" framing is misleading — medium

File: docs/guides/user/adoption.md (Run stage, fix agent bullet)

The guide describes the fix agent as having an "automatic mode" that gets enabled in the Run stage. In reality, the fix agent always auto-triggers on bot-authored PRs when the review agent requests changes. What changes in the Run stage is that the code agent starts producing bot-authored PRs, making auto-fix behavior visible. For human-authored PRs, automatic fixing requires the fullsend-fix label. The current framing as a mode toggle may lead teams to expect auto-fix on their human-authored PRs.

4. "Filing issues skill" for retro agent does not exist — medium

File: docs/guides/user/adoption.md (Walk stage, retro paragraph)

The guide says to "pair [the retro agent] with a filing issues skill." The retro agent's harness defines skills retro-analysis, finding-agent-runs, agent-scaffolding, and autonomy-readiness — there is no "filing issues" skill. The repo's skills/filing-issues/SKILL.md is a Claude Code interactive skill, not an agent skill. Issue filing from retro proposals is handled by the post-script (scripts/post-retro.sh). A team following this guidance would look for a non-existent skill to configure.

5. /fs-fix in Crawl requires coder app not mentioned — low

File: docs/guides/user/adoption.md (Crawl stage, optional fix paragraph)

The Crawl stage suggests using /fs-fix on-demand, but the fix agent uses the coder GitHub App. If a team follows Crawl's guidance (triage, prioritize, review only), the coder app may not be installed yet. Consider noting that /fs-fix requires the coder app.

6. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md (multiple stages)

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The --agents flag on fullsend github setup (documented in configuring-github.md) controls this. A brief note or link to the setup mechanism would help teams follow the staged approach.

7. No linked issue for non-trivial change — low

File: docs/guides/user/adoption.md

This is a 170-line addition with no linked issue. While documentation contributions from external contributors commonly lack a pre-authorized issue, the intent is clearly aligned with the project's goals. Consider linking to or filing an issue for traceability.

---

Labels: PR adds user-facing documentation under docs/guides/user/

Previous run (9)

Review — comment

Re-review at 26f8bb7. The prior review (at 452187b) identified four medium-severity and three low-severity findings. The author addressed three of the four medium findings in commit 26f8bb7:

• ✅ Code agent scoping — now correctly says "bugs, docs, and performance issues" instead of just "bug fixes," matching triage's ready-to-code label behavior (verified against triage.md and code.md)
• ✅ Fix agent framing — now correctly describes bot-authored PR auto-trigger instead of a misleading "automatic mode" toggle (verified against fix.md lines 119–130)
• ✅ Retro agent issue filing — now correctly references the post-script instead of a non-existent "filing issues skill" (verified against retro.md line 14)

All three fixes verified against the actual agent documentation. The technical accuracy of the guide is solid.

One medium-severity finding from the prior review remains unaddressed. No new issues introduced.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry, the adoption guide won't appear in the website sidebar navigation — it will only be reachable via the README link or direct URL.

Remediation: Add { text: "Adoption Guide", link: "/guides/user/adoption" } to the User Guides items array in website/.vitepress/config.ts.

2. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The guide links to configuring-github.md and customizing-agents.md, but a brief inline note or link to the specific enable/disable mechanism would help teams follow the staged approach without navigating away.

3. No linked issue — low

File: docs/guides/user/adoption.md

This is a 172-line addition with no linked issue. The content clearly aligns with project goals and the contribution is well-structured. Consider linking to or filing an issue for traceability.

---

All cross-reference links (13 total) resolve correctly. No security concerns (no secrets, injection patterns, or suspicious Unicode). Documentation formatting follows established patterns in the user guides directory.

Previous run (10)

Review — comment

Useful documentation contribution that provides a clear incremental adoption path. The crawl-walk-run-fly framing is well-structured and the tone is appropriate (suggestions, not requirements). All 12 unique cross-reference link targets resolve correctly.

Four medium-severity findings relate to a missing VitePress sidebar entry and three technical accuracy issues that could mislead teams following the guide. None are blocking, but fixing them would improve the guide's discoverability and reliability.

Findings

1. Missing VitePress sidebar entry — medium

File: website/.vitepress/config.ts (not modified)

Per AGENTS.md: "When adding a new doc under docs/, check website/.vitepress/config.ts sidebar config. Sections using getMarkdownFiles() are auto-discovered. All other sections need a manual { text, link } entry."

The "User Guides" sidebar section (config.ts lines 218–232) uses manual entries, not getMarkdownFiles(). Without a new entry like { text: "Adoption Guide", link: "/guides/user/adoption" }, the new guide won't appear in the website sidebar navigation. It will only be reachable via the README link or direct URL.

2. "Scoped to bug fixes by default" contradicts preceding sentence — medium

File: docs/guides/user/adoption.md (Run stage, code agent bullet)

The code agent bullet first correctly states the ready-to-code label is applied by triage for "bugs, docs, and performance issues," then immediately narrows to "it's scoped to bug fixes by default." Per the triage agent and code agent docs, ready-to-code covers bug, documentation, and performance issue categories. The second sentence should match: "scoped to bugs, docs, and performance issues by default."

3. Fix agent "automatic mode" framing is misleading — medium

File: docs/guides/user/adoption.md (Run stage, fix agent bullet)

The guide describes the fix agent as having an "automatic mode" that gets enabled in the Run stage. In reality, the fix agent always auto-triggers on bot-authored PRs when the review agent requests changes. What changes in the Run stage is that the code agent starts producing bot-authored PRs, making auto-fix behavior visible. For human-authored PRs, automatic fixing requires the fullsend-fix label. The current framing as a mode toggle may lead teams to expect auto-fix on their human-authored PRs.

4. "Filing issues skill" for retro agent does not exist — medium

File: docs/guides/user/adoption.md (Walk stage, retro paragraph)

The guide says to "pair [the retro agent] with a filing issues skill." The retro agent's harness defines skills retro-analysis, finding-agent-runs, agent-scaffolding, and autonomy-readiness — there is no "filing issues" skill. The repo's skills/filing-issues/SKILL.md is a Claude Code interactive skill, not an agent skill. Issue filing from retro proposals is handled by the post-script (scripts/post-retro.sh). A team following this guidance would look for a non-existent skill to configure.

5. /fs-fix in Crawl requires coder app not mentioned — low

File: docs/guides/user/adoption.md (Crawl stage, optional fix paragraph)

The Crawl stage suggests using /fs-fix on-demand, but the fix agent uses the coder GitHub App. If a team follows Crawl's guidance (triage, prioritize, review only), the coder app may not be installed yet. Consider noting that /fs-fix requires the coder app.

6. No explanation of how to selectively enable agents — low

File: docs/guides/user/adoption.md (multiple stages)

Each stage says to "enable" specific agents (e.g., "Enable the retro agent" in Walk) without explaining the mechanism. The --agents flag on fullsend github setup (documented in configuring-github.md) controls this. A brief note or link to the setup mechanism would help teams follow the staged approach.

7. No linked issue for non-trivial change — low

File: docs/guides/user/adoption.md

This is a 170-line addition with no linked issue. While documentation contributions from external contributors commonly lack a pre-authorized issue, the intent is clearly aligned with the project's goals. Consider linking to or filing an issue for traceability.

---

Labels: PR adds user-facing documentation under docs/guides/user/

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 7:33 AM UTC · Ended 7:36 AM UTC
Commit: 5cd495a · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:36 AM UTC · Completed 7:46 AM UTC
Commit: 26f8bb7 · View workflow run →

[maruiz93]

Finding 1 (VitePress sidebar): Addressed in 1b5d691 — added { text: "Adopting Fullsend Incrementally", link: "/guides/user/adoption" } to the User Guides sidebar section.

[fullsend-ai-review]

🤖 Review · ❌ Terminated · Started 9:36 AM UTC · Ended 9:44 AM UTC
Commit: 5cd495a · View workflow run →

[maruiz93]

Findings 2-4 addressed in 26f8bb7:

Finding 2 (code agent scoping): Updated to "scoped to bugs, docs, and performance issues by default" — reflects all ready-to-code issue types, not just bugs.

Finding 3 (fix agent mode): Reframed as "Fix agent on bot-authored PRs" — clarifies auto-trigger behavior on bot PRs vs. label/command requirement on human PRs.

Finding 4 (filing issues skill): Changed to "Its post-script files issues from retro findings automatically" — correctly attributes issue filing to the retro agent's post-script, not a separate skill.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:36 AM UTC · Completed 9:44 AM UTC
Commit: 1b5d691 · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:02 AM UTC · Completed 10:15 AM UTC
Commit: 2409654 · View workflow run →

[rh-hemartin]

@maruiz93 could you take a look?

[maruiz93]

Re: @waynesun09's review noting the triage bot's blocking claim on #4969 — the auto-merge capability has since been implemented: CODE_AUTO_MERGE env var (agents#491) enables GitHub auto-merge on code agent PRs, and PR risk assessment scoring (agents#861, ADR 0089) provides the composite risk signal for gating auto-merge eligibility. The guide is being updated in this pass to reflect these as available features. The triage bot's comment was not referenced by any maintainer as a blocking requirement for this PR.

[maruiz93]

/fs-fix rebase onto main first (2,122 commits behind, VitePress sidebar will conflict). After rebase, verify filenames — several guides were renamed from customizing-* to configuring-* on main. CODE_AUTO_MERGE env var is in agents repo docs/code.md, ADR 0089 covers risk assessment.

[maruiz93]

/fs-fix rebase onto main first — all other changes depend on post-rebase file state and link targets

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:25 AM UTC · Completed 10:44 AM UTC

Commit: beefcf4 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.72

[fullsend-ai-review]

Risk Assessment: moderate (2/5)

Details

Docs-only PR from a known contributor adding a new adoption guide (178 lines) plus single-line additions to VitePress config and guides index. No production code, CI, dependency, security, or protected-path changes. Multi-author contention on navigation files slightly elevates git-history tier.

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:09 PM UTC · Ended 2:28 PM UTC

Commit: aa1aa3a · View workflow run →

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 2:30 PM UTC · Ended 2:32 PM UTC

Commit: c5b41af · View workflow run →

[github-actions]

Site preview

Preview: https://e176abe9-site.fullsend-ai.workers.dev

Commit: 1f648a7e66febbb46c8922961562011f84b0d363

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 2:34 PM UTC · Completed 2:53 PM UTC

Commit: 1f648a7 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $5.24

[fullsend-ai-review]

Review skipped — this PR is already merged.

The /fs-review command only reviews open PRs/MRs.

_{Posted by fullsend post-review check}