review-plan
Review a plan by running internal reviews and a peer review in parallel and returning combined findings. Use when the user asks to "review my plan", "check my plan", "critique my plan", or wants feedback on a plan.
Install
npx skills add https://github.com/tobihagemann/turbo/tree/main/codex/skills/review-plan
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tobihagemann-turbo@llmmart
git clone https://github.com/tobihagemann/turbo.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole tobihagemann/turbo collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Review Plan
Review a plan against structure and scope criteria. Runs internal reviews and $peer-review in parallel by default. Returns combined structured findings.
Step 1: Resolve the Plan
- Plan text in conversation — use it
- Explicit path — read it
- Explicit slug — resolve to
.turbo/plans/<slug>.md - Single file — Glob
.turbo/plans/*.md. If exactly one file exists, use it - Most recent — most recently modified file
- Legacy fallback —
.turbo/plan.mdif.turbo/plans/does not exist - Nothing found — stop and state that no plan was found to review
When the plan came from a file, state the resolved path before continuing.
Unless the plan came from conversation text, or an explicit path or slug was passed, check whether the resolved plan still describes work that remains to be done. Report a frontmatter status: of done alongside the path.
Step 2: Run Reviews in Parallel
Two reference files carry the criteria, one per internal review:
Skip peer review when instructed (e.g., "without peer review", "no peer", "internal only").
When a list of already-adjudicated findings was supplied (one line each: the finding, its verdict, and the recorded reason), include it in every branch prompt, internal and peer, labeled as decisions already reached on proposed revisions rather than as established properties of the plan. Direct each branch to treat a finding as listed when it matches one on both location and substance, to raise such a finding again only on evidence its recorded reason does not already account for, and to judge any other finding at the same location on its own merits.
Run the review branches independently. Launch them with spawn_agent / wait_agent using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. That is three branches when peer review is active (two internal + one peer), or two branches when peer review is skipped. Every branch prompt must direct it to treat the shared working tree and its git index as read-only and to assess findings by reading and reasoning. HEAD stays where it is: read other refs with git show <ref>:<path> rather than git checkout or git switch. For a check that requires mutating code, the branch works in an isolated git worktree created under $TMPDIR and discarded afterward. Refer to that worktree by absolute path in every command and join chained steps with &&, so a failed step cannot leave the rest running in the shared checkout. Run teardown and verification as their own commands. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. A check that runs in the shared checkout invokes an already-installed runner directly wherever a package-manager wrapper would front it, since such a wrapper reads as read-only while reconciling the shared install before it runs. Confine dependency installs and reconciliation to an isolated worktree. Every test runner the branch starts, in a worktree or in the shared checkout, runs in its own process group under a timeout enforced from outside the runner. Before teardown, the branch stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the branch verifies that git worktree list no longer shows the worktree, that git status --short is clean, and that HEAD is still on the branch it started on. It also confirms that no process from those groups, and none whose command line names the worktree path, if any, is still running, and reports by PID any process it could not stop. When it cannot list processes, it reports that check as unrun and names those process groups and the worktree path, if any. After any check, in a worktree or in the shared checkout, it verifies that the shared tree's dependency directory still resolves (a destroyed install leaves git status clean, since it is gitignored). Damage the branch cannot repair is reported with the exact repair command in place of findings.
- Structure branch: The branch prompt must include the plan text, the path to the structure reference file (
~/.agents/skills/review-plan/references/plan-structure-review.md), the output format below, and this directive: read that reference file directly, apply its determination criteria as the bar for a real finding, then report every finding that clears that bar tagged with its priority and withinternal (structure). Coverage is the goal at this stage, so surface everything that qualifies and let the priority tags convey severity. The branch must also return the Overall Verdict block for its dimension. - Scope branch: Same, with the scope reference file (
~/.agents/skills/review-plan/references/plan-scope-review.md) and findings taggedinternal (scope). - Peer review branch (unless skipping): Spawn a Codex sub-agent and instruct it to read and follow
$peer-reviewfrom the installed skill directory, with a request describing: (a) the plan under review; (b) the criteria live in~/.agents/skills/review-plan/references/plan-structure-review.mdand~/.agents/skills/review-plan/references/plan-scope-review.md— the reviewer should read both files directly and cover every criterion in one single-pass review, applying each file's determination criteria and priority scale to the findings in that file's domain; (c) the Overall Verdict should use theReadiness: <ready | needs revision>label; (d) the already-adjudicated findings list when one was supplied, framed as described above. The branch prompt must also state explicitly that the sub-agent's final message must contain the verbatim findings text$peer-reviewproduced.
Aggregate findings with attribution (reviewer: "internal" or "peer", each with its "structure" or "scope" dimension). Present them in the output format below.
Then call update_plan to mark this step completed and continue with the next step of the active workflow.
Output Format
Format each finding as:
### [P<N>] <title (imperative, ≤80 chars)>
**Section:** <plan section>
**Reviewer:** <internal | peer> (<structure | scope>)
<one paragraph explaining the issue and its impact>
After all findings, place the Overall Verdict block each internal branch returned for its dimension, then a single combined block for the peer review:
## Overall Verdict: <Structure | Scope>
**Readiness:** <ready | needs revision>
<1-3 sentence assessment>
## Peer Review Verdict
**Readiness:** <ready | needs revision>
<1-3 sentence assessment>
If there are no qualifying findings, state so and explain briefly.
Rules
- Present findings grouped by priority.
Files (turbo)
-
references
-
plan-scope-review.md 2.8 KB
# Plan Scope Review Reference ## Review Instructions Read project context (AGENTS.md and files mentioned in the plan) to understand what already exists. Review whether the plan builds more than its acceptance criteria and stated bounds justify. Identify the plan's acceptance criteria and its stated bounds (Context or the original ask) before judging any step. A step is in scope when a criterion or bound calls for it. ## What to Review - **Scope** — Acceptance criteria addressed without creep - **YAGNI** — Steps that build something no acceptance criterion asks for: unrequested features, premature abstractions, or scaffolding for anticipated work - **Design Direction** — Whether the chosen approach is the simplest safe option. Challenge assumptions the plan depends on and flag when a different approach would be safer or simpler - **Proportionality** — Steps whose machinery (leases, locks, queues, versioning schemes, state machines, new persistent entities) exceeds the failure modes and scale the plan's Context admits - **Self-Referential Justification** — Mechanism justified by a failure mode that exists only because that mechanism is present. Trace each justification back to a criterion or bound; when the chain closes on itself, test whether cutting the mechanism removes its dependents rather than judging each link alone ## Determination Criteria Flag an issue only when ALL of these hold: 1. The plan builds something its acceptance criteria and stated bounds do not justify, or takes an approach a safer or simpler one would replace 2. The issue is discrete and actionable, naming the cut, the merge, or the alternative approach 3. The finding cites the criterion or bound that fails to justify the work, or the concrete advantage the alternative approach holds A deliberate design choice is in range here: name the choice and the evidence against it rather than treating the author's intent as settling the question. ## Priority Levels - **P0** — The approach as a whole builds substantially more than the acceptance criteria ask for - **P1** — A step or abstraction no acceptance criterion stands behind, or an approach a materially safer or simpler one would replace - **P2** — Machinery disproportionate to the stated bounds, or a step that folds into a neighbor - **P3** — Minor simplification ## What to Ignore - Alternative approaches without evidence of concrete advantages over the chosen one - A step the dependency chain or a stated constraint requires, even when folding it into a neighbor would shorten the plan; a dependency the reviewed mechanism itself creates does not count as such a constraint - Input validation at trust boundaries, error handling that prevents data loss, security controls, and accessibility affordances; these stay even when the acceptance criteria do not name them -
plan-structure-review.md 4.2 KB
# Plan Structure Review Reference ## Review Instructions Read project context (AGENTS.md and files mentioned in the plan) to understand the codebase. Review whether the plan holds together and can be executed. ## What to Review - **Structural completeness** — Context states the deployment's bounds, and the plan carries acceptance criteria (or Verification records that the change has no observable behavior). Every acceptance criterion with observable behavior is exercised by the Verification section - **Completeness** — Missing steps, undefined behavior, unaddressed acceptance criteria or edge cases - **Feasibility** — Technically unsound approaches, ignored constraints, missing dependencies - **Ordering** — Step dependency issues, missing prerequisites, circular dependencies - **Buildability** — Steps specific enough to execute without getting stuck. No logical gaps between steps - **Concreteness** — Every step references a concrete anchor (file/line, function, symbol, or file to create), and named symbols/types are verifiable in the codebase. Flag vague directives or placeholder language - **Codebase accuracy** — Concrete claims the plan makes about current code (named functions, file paths, type shapes, module boundaries, existing API surfaces) must match what is in the repo. Spot-check by opening the cited files. Flag wrong citations, misdescribed seams, and nonexistent-but-assumed APIs — these mislead implementation the most - **Consistency** — Internal contradictions between sections (e.g., Implementation Steps disagree with Verification, two steps describe the same call differently) - **Verification** — The plan has a verification section that describes how to confirm the change works. Flag if missing, or if it is vague ("run tests" without naming which tests or what to look for) - **Test efficacy** — When the plan proposes, keeps, or reshapes a test as a regression net, check that the test can fail when the behavior it guards breaks. Flag an assertion that reads a surface the code under test does not write, or a case where a mechanism other than the one under test produces the same observable - **Pattern Alignment** — Proposed approach follows existing codebase patterns where applicable. Deviations from established patterns are justified - **Side effects** — Other consumers, callers, or co-firing components affected by changes to shared surfaces (helpers, lifecycle hooks, globals) - **Failure Modes** — How the design handles partial failure, race conditions, stale state, rollback, data loss, and degraded dependencies. Limit this to scenarios reachable in the deployment the plan's Context describes: when it bounds the system (a single operator, no concurrent writers, a handful of invited users), a scenario that bound rules out is not a gap ## Determination Criteria Flag an issue only when ALL of these hold: 1. It would cause an implementer to build the wrong thing or get stuck 2. The issue is discrete and actionable (not a vague concern or general suggestion) 3. The author would likely fix the issue if made aware of it 4. The issue is clearly not an intentional design choice, OR it challenges a design choice with evidence of concrete failure modes or a simpler alternative ## Priority Levels - **P0** — Plan is fundamentally flawed. Wrong approach or missing core acceptance criterion - **P1** — Significant gap that will likely cause implementation problems - **P2** — Moderate issue that should be addressed before implementation - **P3** — Minor improvement ## What to Ignore - Wording, stylistic, or cosmetic preferences that don't affect buildability - Alternative approaches without evidence of concrete advantages over the chosen one - Suggestions that add complexity without clear implementation value - Missing execution-wrapper content (skill invocations, task tracking, or finalize/commit steps) when the workflow that produced the plan forbids that content in plan files, the execution wrapper already discovers the required capability from the plan's substantive work, and the plan carries concrete acceptance criteria for that outcome. Still flag when the wrapper cannot discover the capability, or when the plan lacks substantive behavior or verification for the intended outcome.
-
-
SKILL.md 7.2 KB
--- name: review-plan description: "Review a plan by running internal reviews and a peer review in parallel and returning combined findings. Use when the user asks to \"review my plan\", \"check my plan\", \"critique my plan\", or wants feedback on a plan." --- # Review Plan Review a plan against structure and scope criteria. Runs internal reviews and `$peer-review` in parallel by default. Returns combined structured findings. ## Step 1: Resolve the Plan 1. **Plan text in conversation** — use it 2. **Explicit path** — read it 3. **Explicit slug** — resolve to `.turbo/plans/<slug>.md` 4. **Single file** — Glob `.turbo/plans/*.md`. If exactly one file exists, use it 5. **Most recent** — most recently modified file 6. **Legacy fallback** — `.turbo/plan.md` if `.turbo/plans/` does not exist 7. **Nothing found** — stop and state that no plan was found to review When the plan came from a file, state the resolved path before continuing. Unless the plan came from conversation text, or an explicit path or slug was passed, check whether the resolved plan still describes work that remains to be done. Report a frontmatter `status:` of `done` alongside the path. ## Step 2: Run Reviews in Parallel Two reference files carry the criteria, one per internal review: - [references/plan-structure-review.md](references/plan-structure-review.md) - [references/plan-scope-review.md](references/plan-scope-review.md) Skip peer review when instructed (e.g., "without peer review", "no peer", "internal only"). When a list of already-adjudicated findings was supplied (one line each: the finding, its verdict, and the recorded reason), include it in every branch prompt, internal and peer, labeled as decisions already reached on proposed revisions rather than as established properties of the plan. Direct each branch to treat a finding as listed when it matches one on both location and substance, to raise such a finding again only on evidence its recorded reason does not already account for, and to judge any other finding at the same location on its own merits. Run the review branches independently. Launch them with `spawn_agent` / `wait_agent` using inherited model defaults, issuing every call in one batch. Do not issue one and await its result before issuing the rest. That is three branches when peer review is active (two internal + one peer), or two branches when peer review is skipped. Every branch prompt must direct it to treat the shared working tree and its git index as read-only and to assess findings by reading and reasoning. HEAD stays where it is: read other refs with `git show <ref>:<path>` rather than `git checkout` or `git switch`. For a check that requires mutating code, the branch works in an isolated `git worktree` created under `$TMPDIR` and discarded afterward. Refer to that worktree by absolute path in every command and join chained steps with `&&`, so a failed step cannot leave the rest running in the shared checkout. Run teardown and verification as their own commands. Give that worktree its own dependency install rather than reaching the shared tree's install by any route: removing a worktree deletes through symlinks, and a redirected suite writes into the shared install. When its own install is not possible, the check is left unrun and reported as such. A check that runs in the shared checkout invokes an already-installed runner directly wherever a package-manager wrapper would front it, since such a wrapper reads as read-only while reconciling the shared install before it runs. Confine dependency installs and reconciliation to an isolated worktree. Every test runner the branch starts, in a worktree or in the shared checkout, runs in its own process group under a timeout enforced from outside the runner. Before teardown, the branch stops the process group of every runner it started, since stopping a runner can leave the processes it spawned alive. Afterward the branch verifies that `git worktree list` no longer shows the worktree, that `git status --short` is clean, and that HEAD is still on the branch it started on. It also confirms that no process from those groups, and none whose command line names the worktree path, if any, is still running, and reports by PID any process it could not stop. When it cannot list processes, it reports that check as unrun and names those process groups and the worktree path, if any. After any check, in a worktree or in the shared checkout, it verifies that the shared tree's dependency directory still resolves (a destroyed install leaves `git status` clean, since it is gitignored). Damage the branch cannot repair is reported with the exact repair command in place of findings. - **Structure branch:** The branch prompt must include the plan text, the path to the structure reference file (`~/.agents/skills/review-plan/references/plan-structure-review.md`), the output format below, and this directive: read that reference file directly, apply its determination criteria as the bar for a real finding, then report every finding that clears that bar tagged with its priority and with `internal (structure)`. Coverage is the goal at this stage, so surface everything that qualifies and let the priority tags convey severity. The branch must also return the Overall Verdict block for its dimension. - **Scope branch:** Same, with the scope reference file (`~/.agents/skills/review-plan/references/plan-scope-review.md`) and findings tagged `internal (scope)`. - **Peer review branch (unless skipping):** Spawn a Codex sub-agent and instruct it to read and follow `$peer-review` from the installed skill directory, with a request describing: (a) the plan under review; (b) the criteria live in `~/.agents/skills/review-plan/references/plan-structure-review.md` and `~/.agents/skills/review-plan/references/plan-scope-review.md` — the reviewer should read both files directly and cover every criterion in one single-pass review, applying each file's determination criteria and priority scale to the findings in that file's domain; (c) the Overall Verdict should use the `Readiness: <ready | needs revision>` label; (d) the already-adjudicated findings list when one was supplied, framed as described above. The branch prompt must also state explicitly that the sub-agent's final message must contain the verbatim findings text `$peer-review` produced. Aggregate findings with attribution (reviewer: "internal" or "peer", each with its "structure" or "scope" dimension). Present them in the output format below. Then call `update_plan` to mark this step completed and continue with the next step of the active workflow. ## Output Format Format each finding as: ``` ### [P<N>] <title (imperative, ≤80 chars)> **Section:** <plan section> **Reviewer:** <internal | peer> (<structure | scope>) <one paragraph explaining the issue and its impact> ``` After all findings, place the Overall Verdict block each internal branch returned for its dimension, then a single combined block for the peer review: ``` ## Overall Verdict: <Structure | Scope> **Readiness:** <ready | needs revision> <1-3 sentence assessment> ``` ``` ## Peer Review Verdict **Readiness:** <ready | needs revision> <1-3 sentence assessment> ``` If there are no qualifying findings, state so and explain briefly. ## Rules - Present findings grouped by priority.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.