Use this Skill to execute a two-phase workflow:
- Plan loop:
plannerWrite or reviseplan.md,plan-reviewerreview it. - Code loop: after the user confirms the plan,
coderimplement the confirmed plan,code-reviewerreview the resulting diff.
This workflow must use real planner, reviewer, and coder sub-Agents. If the current environment cannot create new native sub-Agents, stop and inform the user that this session cannot run review-loop. In Codex and Claude Code, all four roles use host-native sub-Agents.
Required preparation
Before starting the task:
- Read
references/protocol.md、references/state-machine.mdandreferences/role-contracts.md。 - Depending on the current platform, read
references/codex.mdorreferences/claude-code.md。 - Create the task ID.
- Run
scripts/init-workspace.js, create.agent-workflows/review-loop/<task-id>/。 - Run
scripts/prepare-agent-roles.js, prepare the real sub-Agent roles for the current platform. - Before proceeding with the workflow, run
scripts/validate-state.js。
maxRounds defaults to 3. If the user specifies a maximum number of loop rounds, pass it to init-workspace.js。
Mandatory rules
- Do not implement code before the plan loop ends and the user explicitly confirms the plan.
- All natural-language intermediate artifacts intended for the user or requiring user confirmation must be in Chinese, including technical plans, review summaries and conclusions, issue descriptions and change suggestions, plan revision records, code execution records, role logs, verification result descriptions, remaining risks, and the summary and questions at confirmation checkpoints. Commands, paths, code symbols, Markdown fixed field names, protocol enum values, and raw tool output may remain in their original form.
- The reviewer role must not modify repository files. The Reviewer only returns a Markdown document conforming to the fixed format; the orchestrator uses
scripts/review-manager.js --finalizeto parse, persist, and validate that document. plan-reviewerandcode-reviewerFor each round of review, a brand-new, independent native sub-Agent instance must be created; even if the role and review type are the same, no reviewer created in any previous round may be resumed or reused, and no context from the parent session, planner, or coder may be inherited.review-manager.js --finalizerejects--agent-id。plannerandcodermay reuse the respective sub-Agent instance created in a previous round across rounds, to preserve plan revision or code implementation context; the two must not reuse each other's instances.- In Codex or Claude Code, run
scripts/review-manager.js --prepare, hand the returned path-only prompt to a new native reviewer sub-Agent, save its sole pure Markdown response to a temporary file outside the repository, then runscripts/review-manager.js --finalize --input <file> --agent-id <id>. Prepare binds all inputs and the Git tree; finalize rejects drift, directly validates the Markdown, writes an immutable reviewer-run, and persists the canonical review asreviews/*-review-N.md. Do not callscripts/persist-review-markdown.js。 - For subsequent read-only re-verification, use
scripts/validate-review-markdown.js, which directly parses and validates the.mddocument. - After each round of code implementation and verification is complete, directly execute
coder-complete. This conversion only verifies that the initial baseline and the current worktree can be safely reconstructed; it does not generate diff files or round-range files. - Prepare writes the complete diff from the initial baseline to the bound worktree into
diffs/code-diff-N.patch, as a review handoff artifact used jointly by the code reviewer and humans, and binds a summary of its contents to the reviewer request. - Incremental patches between adjacent code rounds must not be generated, passed, or recorded;
code-diff-N.patchalways represents the diff from the initial baseline to the current review version. - Prepare binds the current worktree summary in the reviewer-run; if the code changes during review, finalize will reject the result, and the current review round must be restarted.
- All state transitions use
scripts/advance-state.js; do not manually editstate.json。 - Stop the current loop when the reviewer returns
approvedor the loop reachesstate.json.maxRounds. - When stopping because
maxRoundsis reached, summarize the remaining issues in Chinese and ask the user whether to continue, accept, or revise. - While waiting at a confirmation node, if the reviewed plan or code has changed, prefer starting a new review round. Only when the user's current message explicitly accepts the changes may this be overridden, passing
--accept-changed-inputs trueand a non-empty--override-reason. The conversion records the accepted drift tostate.json.confirmationOverrides。 - Only at the
max_rounds_reachedconfirmation node maymaxRoundsbe increased; after rejecting the result at that node, drafting can only resume if the user's current message explicitly gives a higher limit. Pass--user-confirmed true; do not reuse earlier vague instructions to bypass the configured limit. - In
plan.md, keep a revision record for each round, and write the record contents in Chinese.
Workflow roles
The four required roles are:
plannerplan-reviewercodercode-reviewer
Use the templates under templates/roles/ as role definitions. In Codex and Claude Code, all four roles must be native sub-agents. Planner/coder may continue using their existing instances in subsequent rounds; plan-reviewer/code-reviewer must create a new instance each round and disable inheritance of parent session context.
User confirmation nodes
After the plan loop ends, present the following to the user in Chinese:
plan.mdpath- Reason the plan loop terminated
- Review summary organized by round
- Unaccepted issues and reasons
Ask the user in Chinese whether to enter the code loop. Only after the user explicitly confirms, run advance-state.js --event confirm-plan。
After the code loop ends, present the following to the user in Chinese:
plan.mdpath- Diff summary
- Reason the code loop terminated
- Verification commands and results
- Remaining risks
Ask the user in Chinese whether to accept the final result. Only after the user explicitly confirms, run advance-state.js --event confirm-final。