Ship a mandatory Tests section in every implementation plan that specifies real-world application tests — actual unit, integration, E2E, and other test files written for the application or feature, run by the project's test runner, and committed to the codebase. Every plan must also include an objective-verification mock/smoke test: a real test file that runs against the application and confirms the plan's stated goal is actually accomplished. The section uses a two-tier system : Tier 1 (code-touching plans) requires all applicable test sub-sections; Tier 2 (non-code plans like docs or file-move chores) requires only the mandatory objective-verification test. The author selects the tier based on what the steps actually do, not the type: field.
Read and implement all steps in the plan at docs/plans/add-tests-section-to-plans.md — Add Tests section to implementation plans. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-tests-section-to-plans.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Achieve this goal: Add Tests section to implementation plans. The plan at docs/plans/add-tests-section-to-plans.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-tests-section-to-plans.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run a workflow to implement the plan at docs/plans/add-tests-section-to-plans.md — Add Tests section to implementation plans. Brief subagents with the plan file at docs/plans/add-tests-section-to-plans.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-tests-section-to-plans.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
add-tests-section-to-plans.html
docs/plans/add-tests-section-to-plans.html
docs/plans/add-tests-section-to-plans.md
Context
The story behind this plan — what prompted the work and why it matters now.
The current implementation plan template ( plan-mode.md , reference/SKELETON.md , and the HTML SKELETON.html ) defines a robust verification chain: per-step verification confirms each step ran correctly, acceptance criteria confirm the plan meets the definition of done, and end-to-end verification confirms the whole plan executed correctly. However, none of these layers require real application tests — they are all prose-based assertions written inside the plan document itself.
This gap means a plan can be marked "completed" without any automated proof that the changes actually work in the running application. A developer could implement all steps, check all criteria boxes, and ship code that has zero test coverage. The missing layer is a Tests section that specifies real-world tests — actual test files (unit, integration, E2E) that are written for the application or feature, run by the project's test runner, and ship with the codebase. These are not plan-level prose checks; they are the same tests a developer would write and commit alongside feature code.
Additionally, every plan must include a mandatory objective-verification test — a real mock or smoke test that runs against the actual application and directly asserts the plan's stated objective is accomplished. Like all tests in this section, the objective-verification test is a real executable test file, not a prose assertion in the plan document. This closes the loop between "what we said we'd do" and "what the application actually does."
Tier decision (resolved): Investigation of 22 existing plans (17 feature, 4 chore, 1 fix, 1 refactor, 0 docs) showed that chore plans span a wide spectrum — from pure file moves ( clean-up-docs ) to code-mutating changes ( enable-model-invocation ). A conditionally-present rule (skip Tests for docs/chore) would either under-test code-touching chores or force a fuzzy "is this code-touching?" classification on every author. Instead, the Tests section is always present with a two-tier depth model: Tier 1 (code-touching plans) includes all applicable sub-sections (unit, integration, E2E) plus the mandatory objective-verification test; Tier 2 (non-code plans: docs, file-move chores) requires only the objective-verification test, with other sub-sections omitted entirely rather than left as empty stubs. The author selects the tier based on what the steps actually do, not the type: frontmatter field — a type: chore plan that changes import paths is Tier 1, while a type: chore plan that moves directories is Tier 2.
Files that change
Every file this plan touches, and what happens to each one.
~/.claude/rules/plan-mode.mdmodified add tests to Required Structure~/.claude/rules/reference/SKELETON.mdmodified add Tests section templatekit/plugins/plan-agent/skills/implementation-plan/SKILL.mdmodified add Tests to Required Structure and HTML Outputreference/SKELETON.htmlmodified add Tests section HTML, CSS, and nav link
Steps
The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.
Definition of done
The plan counts as done when every statement below is true — check each one off as you verify it.
Final check
One last pass to confirm the whole change works end to end.
After implementing all steps, generate a new plan using /plan-agent:implementation-plan for any feature objective (e.g. "Add a search bar to the dashboard"). Open the resulting HTML plan and confirm:
A Tests section appears between Steps and Acceptance Criteria in the rendered page.
The section contains at least one test card for the applicable test types — each describing a real test file to be written for the application (the search-bar plan should include unit tests for the search logic, integration tests for the API, and E2E tests for the user flow).
An objective-verification test hero card is always present, visually distinct, positioned first in the Tests section (before any unit/integration/E2E sub-sections), and describes a real mock/smoke test file that runs against the application and asserts the plan's objective statement is accomplished.
The sidebar navigation includes a "Tests" link that scrolls to the correct section.
Tier 1 verification: Generating a plan for a feature or fix (e.g. "Add a search bar") produces a Tier 1 Tests section with unit/integration/E2E sub-sections populated based on step analysis, plus the mandatory objective-verification test.
Tier 2 verification: Generating a plan for a non-code change (e.g. a docs-only plan or a file-move chore) produces a Tier 2 Tests section with only the mandatory objective-verification test — unit/integration/E2E sub-sections are omitted entirely, not rendered as empty stubs.
Tier boundary test: Generating a type: chore plan whose steps modify application source files (e.g. "Bump dependency and update import paths") correctly selects Tier 1, not Tier 2 — confirming tier is driven by step content, not the type: field.
Separately, create a markdown plan using the updated SKELETON.md and confirm the ## Tests section template renders with all four test-type placeholders.
Wrapping up
Three gates that must all pass before this plan is marked completed.
Completion Report
No items to report — all requirements met.