#404 Require documentation updates when API changes

packages/agents/content/skills/design-and-plan/SKILL.md

@@ -103,6 +103,8 @@ When the ticket needs work, produce or update it to capture the agreed design:
 
 **Test criterion convention:** when a ticket involves code changes to testable behavior, the acceptance criteria must include a test criterion (e.g., "New/modified behavior in this change is covered by tests"). Omit the test criterion only when the change falls entirely within the carve-outs defined in the `testing-conventions` skill.
 
+**Documentation criterion convention:** when a ticket involves changes that add, remove, or rename user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), the acceptance criteria must include corresponding updates to documentation, help text, and usage examples — including removal of references to anything that no longer exists.
+
 Present the ticket to the user. Revise until approved.
 
 **Remote issue update** — offer to update the remote issue only when the source was a remote ticket (URL or shorthand reference). This is a shared-state action — do not update without explicit consent.
@@ -153,6 +155,8 @@ Produce a plan that gives a competent coder everything they need — and enough
 
 Apply the same test criterion convention here: when a task creates or modifies testable behavior, include a test criterion in its acceptance criteria. This ensures the test requirement propagates from the ticket through to the plan's per-task level, where the coder and reviewers consume it.
 
+Apply the same documentation criterion convention here: when a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), include a criterion for updating documentation, help text, and usage examples — including removal of references to anything that no longer exists.
+
 ### Task 2: {Name}
 
 ...

packages/agents/content/subagents/orchestrated-planner.md

@@ -39,6 +39,7 @@ You will receive:
 - **Quality gates are explicit steps**: include steps for type-checking, linting, and tests — don't assume the coder will do these automatically
 - **Include file paths**: every step must list the specific files it touches
 - **Test coverage in acceptance criteria**: when a step creates or modifies testable behavior, its acceptance criteria must include test coverage. See the `testing-conventions` skill for what constitutes testable behavior and the narrow carve-outs where tests may be omitted.
+- **Documentation coverage in acceptance criteria**: when a step adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include corresponding updates to documentation, help text, and usage examples — including removal of references to anything that no longer exists.
 
 ## Output: plan (Markdown)
 

packages/agents/content/subagents/plan-reviewer.md

@@ -47,11 +47,12 @@ Each finding is tagged with a resolution type:
 
 ### Completeness criteria (C findings)
 
-| Focus                    | Check                                                | Resolution                                               |
-| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------- |
-| UX specification         | Interactions, layouts, states, user flows specified? | `user` -- UX decisions are preference-based              |
-| Technical decisions      | Patterns, data structures, API shapes specified?     | `auto` if codebase pattern applies; `user` if ambiguous  |
-| Behavioral specification | Edge cases, defaults, failure modes specified?       | `auto` if conventions dictate; `user` if domain-specific |
+| Focus                    | Check                                                                          | Resolution                                               |
+| ------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
+| UX specification         | Interactions, layouts, states, user flows specified?                           | `user` -- UX decisions are preference-based              |
+| Technical decisions      | Patterns, data structures, API shapes specified?                               | `auto` if codebase pattern applies; `user` if ambiguous  |
+| Behavioral specification | Edge cases, defaults, failure modes specified?                                 | `auto` if conventions dictate; `user` if domain-specific |
+| Documentation coverage   | Steps touching user-facing surface include doc updates in acceptance criteria? | `auto` if doc files identifiable; `user` if ambiguous    |
 
 ### Correctness criteria (X findings)
 

packages/agents/content/subagents/planner.md

@@ -5,6 +5,7 @@ tools: [Read, Grep, Glob, Bash, Write]
 maxTurns: 40
 skills:
   - development-workflows
+  - testing-conventions
 ---
 
 # Story Planner
@@ -37,6 +38,8 @@ You will receive:
 - **Order by dependency**: If step B depends on step A, list B after A and declare the dependency explicitly.
 - **Right-sized**: A simple story might have 2-3 steps; a complex one might have 8-10. Don't over-plan — if the story is straightforward, keep it simple.
 - **Identify risks and questions**: Surface anything you cannot resolve from codebase analysis alone. These go to the user for input.
+- **Test coverage in acceptance criteria**: when a step creates or modifies testable behavior, its acceptance criteria must include test coverage. See the `testing-conventions` skill for what constitutes testable behavior and the narrow carve-outs where tests may be omitted.
+- **Documentation coverage in acceptance criteria**: when a step adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include corresponding updates to documentation, help text, and usage examples — including removal of references to anything that no longer exists.
 
 ## Output: orchestration-plan.json