Plans

Add a "Review the plan" option to the plan exit step

Medium completed
2026-06-08 agentics feature Medium effort
Objective

Give every freshly-generated plan a one-click path to a full critique: add a "Review the plan" option to the implementation-plan skill's Step 8 exit menu that invokes the review-plan Agent Team on the current plan, then returns to the menu so the user can review-then-implement without leaving the flow.

Implement Read and implement all steps in the plan at docs/plans/add-review-plan-option-to-exit-step.md — Add a "Review the plan" option to the plan exit step. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/add-review-plan-option-to-exit-step.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
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Add a "Review the plan" option to the plan exit step. The plan at docs/plans/add-review-plan-option-to-exit-step.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-review-plan-option-to-exit-step.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 as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/add-review-plan-option-to-exit-step.md — Add a "Review the plan" option to the plan exit step. Brief subagents with the plan file at docs/plans/add-review-plan-option-to-exit-step.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-review-plan-option-to-exit-step.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.
File add-review-plan-option-to-exit-step.html
Path docs/plans/add-review-plan-option-to-exit-step.html
Spec docs/plans/add-review-plan-option-to-exit-step.md
Definition of done 0 / 7 done

Context

The story behind this plan — what prompted the work and why it matters now.

The implementation-plan skill ends its workflow at Step 8 ("Implement, Edit, or Exit"), where an AskUserQuestion offers the user what to do next with the plan it just generated. Today the choices are Implement now , Run as workflow (only when a workflow prompt was generated), Edit the plan , and Exit . There is no way to send the plan straight into review.

The sibling review-plan skill already exists: it orchestrates a seven-reviewer Agent Team (five core + two UI-conditional), synthesizes findings, and applies improvements in place . It is invoked via the Skill tool — already declared in implementation-plan 's allowed-tools — and accepts an explicit plan path ( /plan-agent:review-plan <file.html> ). Wiring the two together is low-risk: the exit step already knows the plan's resolved path, so it can hand that path to review-plan directly.

One hard constraint shapes the design: AskUserQuestion allows a maximum of four options. The "workflow prompt present" menu is already at four , so a fifth slot is impossible there. The chosen resolution (an adaptive swap ) keeps the new Review the plan option always available and drops Edit the plan from the top menu only in the workflow-present case. The review-plan skill hard-stops when Agent Teams are unavailable (Claude Code < 2.1.32 or the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS flag unset); the new handler must degrade gracefully when that happens.

Files that change

Every file this plan touches, and what happens to each one.

agentics/
  • .claude-plugin/marketplace.json modified bump plan-agent 1.10.0 → 1.11.0
  • kit/plugins/plan-agent/
    • CHANGELOG.md modified add 1.11.0 entry
    • README.md modified document the Review option
  • kit/plugins/plan-agent/skills/implementation-plan/SKILL.md modified add Review option + handler to Step 8
  • tests/plugins/test-step8-review-option.sh new smoke test for the option + handler

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done Add Review the plan to both Step 8 option lists in kit/plugins/plan-agent/skills/implementation-plan/SKILL.md .
Why
In the "no workflow prompt" list (currently 3 options) insert Review the plan between Implement now and Edit the plan → 4 options. In the "workflow prompt exists" list (already at the 4-option AskUserQuestion ceiling) replace Edit the plan with Review the plan → Implement now / Run as workflow / Review the plan / Exit . This is the adaptive-swap decision: the cap forbids a 5th option, so Edit yields its slot only when a workflow prompt is present.
Verify
Re-read Step 8. The no-workflow list shows exactly 4 options including Review the plan and still containing Edit the plan ; the workflow list shows exactly 4 options including Run as workflow and Review the plan but not Edit the plan . Each option keeps a one-line description.
2
done Add the "If the user chooses Review the plan " handler block to Step 8.
Why
Place it alongside the other choice handlers (after Run as workflow , before where Edit the plan would be). The handler must: (1) first ask a one-question AskUserQuestion sub-prompt — "Run the review now, or dispatch it in the background?" — with two options: (a) Run now (foreground) invokes the review-plan skill via the Skill tool — Skill(skill: "review-plan", args: "<plan path>") — passing the current plan's relative path (resolved when the plan was created) so review targets this plan instead of globbing; (b) Background invokes Skill(skill: "plan-agent:review-plan", args: "<plan path> --background") — the --background flag puts review-plan in detached mode so the team runs without blocking the session; (2) handle review-plan 's hard-stop when Agent Teams are unavailable (Claude Code < 2.1.32 or CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS unset) — relay its guidance and return to the menu without error; (3) after a foreground run completes, re-render the now-updated plan in the browser via the Step 7 sub-steps, then loop back to Step 8 and ask again (mirroring the Edit the plan loop); after a background dispatch, return to the menu immediately and note the user can reopen the plan to see changes once the detached run finishes; (4) leave the plan status at todo across all three representations, because reviewing is not implementing.
Verify
Re-read Step 8. A Review the plan handler exists that (a) offers a foreground-vs-background sub-choice; (b) foreground invokes Skill(skill: "plan-agent:review-plan", args: "<path>") , background invokes Skill(skill: "plan-agent:review-plan", args: "<path> --background") ; (c) handles the Agent-Teams hard-stop gracefully; (d) re-renders and loops back to the menu after a foreground run (returns immediately after a background dispatch); and (e) leaves status at todo . Confirm Skill is present in the skill's allowed-tools line (it already is — no change needed).
3
done Document the new option in kit/plugins/plan-agent/README.md .
Why
Update the implementation-plan skill section (near the Step 8 / next-action and "Workflow prompt" descriptions) to list the Review the plan exit option, state that it runs the review-plan team on the current plan (with a foreground-or-background choice), and note the adaptive-swap behavior ( Edit the plan drops off the top menu when a workflow prompt is present). Project CLAUDE.md requires docs to be updated alongside plugin changes.
Verify
grep -n "Review the plan" kit/plugins/plan-agent/README.md returns a sentence describing the new Step 8 option and its review-plan behavior, including the adaptive-swap note.
4
done Add a ## 1.11.0 entry to kit/plugins/plan-agent/CHANGELOG.md .
Why
Insert a new ## 1.11.0 — Review option in the plan exit step (2026-06-08) section below the # Changelog heading with an ### Added bullet (the Step 8 Review the plan option that runs review-plan on the current plan, foreground or background) and a ### Changed bullet (workflow-variant menu swaps out Edit the plan for Review the plan to stay within the 4-option limit). If the pending "Unreleased — Add background mode to review-plan" item ships in the same release, fold its bullet into 1.11.0; otherwise leave it untouched. marketplace.md requires a CHANGELOG entry for every plugin change.
Verify
head -20 kit/plugins/plan-agent/CHANGELOG.md shows a ## 1.11.0 section dated 2026-06-08 with an Added bullet (Review option) and a Changed bullet (adaptive swap).
5
done Bump the plan-agent version in .claude-plugin/marketplace.json from 1.10.0 to 1.11.0 .
Why
A new skill option is a MINOR change per .claude/rules/marketplace.md . Set version only in marketplace.json — never add it to plugin.json . There is no CI auto-bump, so the value committed here is what ships. The .claude/settings.json post-edit hook validates marketplace.json JSON syntax automatically.
Verify
python3 -c "import json; m=json.load(open('.claude-plugin/marketplace.json')); print([p['version'] for p in m['plugins'] if p['name']=='plan-agent'])" prints ['1.11.0'] and the file parses without a JSON error.

Tests

The tests that prove the change does what it promises.

Tier 2 — skill-instruction + docs/metadata change; objective smoke test only
Objective Step 8 offers "Review the plan" and targets the current plan File: tests/plugins/test-step8-review-option.sh Type: smoke test — grep-based, matching the repo's tests/pages/*.sh PASS/FAIL convention (no JS/TS runner exists for skill markdown). Asserts: in kit/plugins/plan-agent/skills/implementation-plan/SKILL.md Step 8 — (1) Review the plan appears in the option lists; (2) the no-workflow variant still contains Edit the plan while the workflow variant's option set is Implement now / Run as workflow / Review the plan / Exit (no Edit the plan ); (3) a Review the plan handler block offers a foreground/background sub-choice and invokes Skill(skill: "plan-agent:review-plan", args: "<path>") for foreground and Skill(skill: "plan-agent:review-plan", args: "<path> --background") for background — no separate review-plan-bg command dispatch. Exits non-zero on any failed assertion. Run: bash tests/plugins/test-step8-review-option.sh Why this is the objective test: it directly proves the plan's goal — that the exit step now offers a Review option wired to review-plan on the current plan — and is the same shell-smoke style the repo already uses to validate non-runtime spec files.

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.

Automated: run bash tests/plugins/test-step8-review-option.sh — every assertion prints PASS and the script exits 0. Run python3 -c "import json; json.load(open('.claude-plugin/marketplace.json'))" to confirm valid JSON, and confirm the printed plan-agent version is 1.11.0 .

End-to-end (manual): invoke /plan-agent:implementation-plan <any objective> and reach Step 8. For a simple plan (no workflow prompt) confirm the menu shows Implement now / Review the plan / Edit the plan / Exit. For a complex plan (workflow prompt generated) confirm the menu shows Implement now / Run as workflow / Review the plan / Exit with Edit the plan absent. Choose Review the plan and confirm the review-plan skill announces "Reviewing plan: <this plan's path>", runs against the current plan, then control returns to the Step 8 menu with status still todo .

Graceful degradation: with Agent Teams disabled (unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ), choosing Review the plan surfaces review-plan 's "Agent Teams are disabled" guidance and returns to the menu without crashing the planning flow.

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

Add an in-plan "Review" copy row to saved plans

Paste this prompt into Claude to execute this follow-up:

In kit/plugins/plan-agent/skills/implementation-plan/reference/SKELETON.html and the HTML Output Requirements section of that skill's SKILL.md, add a ".plan-review" row directly beneath the ".plan-implement" row. It shows a copyable command "/plan-agent:review-plan {plan-path}" in a <code id="review-cmd"> element with a Copy button, mirroring the existing .plan-implement / copyCmd pattern (add a copyReview() function). This lets someone reopening a saved plan launch a review without re-entering Step 8. Document the row in kit/plugins/plan-agent/README.md, bump the plan-agent version a MINOR step in .claude-plugin/marketplace.json, and add a CHANGELOG.md entry.
Auto-route complex plans through review before Step 8 Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Paste this prompt into Claude to execute this follow-up:

Explore adding an opt-in setting (planAgent.autoReview) to the plan-agent plugin so that, when a freshly-generated plan meets the workflow-complexity heuristic, the implementation-plan skill automatically runs the review-plan Agent Team once before presenting the Step 8 menu, then surfaces the improved plan. Recommend whether this should default on, default off, or prompt per-plan, weigh the token/latency cost against the quality gain, and draft the SKILL.md changes plus a settings-read step.