diff --git a/packages/agents/content/skills/design-and-plan/SKILL.md b/packages/agents/content/skills/design-and-plan/SKILL.md index afa9bd7c..659fa83c 100644 --- a/packages/agents/content/skills/design-and-plan/SKILL.md +++ b/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} ... diff --git a/packages/agents/content/subagents/orchestrated-planner.md b/packages/agents/content/subagents/orchestrated-planner.md index 75bf5abc..f618b34a 100644 --- a/packages/agents/content/subagents/orchestrated-planner.md +++ b/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) diff --git a/packages/agents/content/subagents/plan-reviewer.md b/packages/agents/content/subagents/plan-reviewer.md index 4f8244ce..abf23a7c 100644 --- a/packages/agents/content/subagents/plan-reviewer.md +++ b/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) diff --git a/packages/agents/content/subagents/planner.md b/packages/agents/content/subagents/planner.md index 49aeece6..f4f37079 100644 --- a/packages/agents/content/subagents/planner.md +++ b/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