Plan Review Loop

Adversarial review loop for implementation plans, modeled on the review-loop plugin's implement → independent review → address cycle, but targeting plans instead of code. A plan defect costs an hour of review now or a day of wrong implementation later.

Core principle: A plan is only as good as its worst instruction executed by someone with zero context. Reviewers must never have seen the planning conversation — fresh context is the independence guarantee.

Lifecycle

setup → locate-or-author → independent review → address with judgment → [confirm] → cleanup

State lives in .claude/plan-review-loop.local.md. Reviews are written to reviews/plan-review-<id>.md. On any tooling error, fail open: report the problem and continue without the loop rather than trapping the user.

Enforcement: the inkstone stop hook (hooks/stop-hook.sh) will not let the session stop while this loop's state file says the review is incomplete, findings are undispositioned, or a required confirmation round is pending. Keep the state file's phase: accurate as you progress — it is the contract with the hook.

Coexistence with the original review-loop plugin: the setup block below refuses to start while a code review loop (.claude/review-loop.local.md) is active, and the stop hook defers entirely to that plugin whenever its state file exists. Run doc loops and code loops sequentially, never concurrently.

Phase 0 — Setup

If the argument is cancel: read .claude/plan-review-loop.local.md if it exists, report its phase and review id, delete it, and stop (note that any existing reviews/plan-review-<id>.md survives cancellation). If absent, report "No active plan review loop."

Otherwise run this setup command verbatim:

set -e && mkdir -p .claude reviews && if [ -f .claude/review-loop.local.md ]; then echo "Error: the original review-loop is active. Finish it or run /review-loop:cancel-review first." && exit 1; fi && if [ -f .claude/plan-review-loop.local.md ]; then echo "Error: a plan review loop is already active. Run plan-review-loop with argument cancel first." && exit 1; fi && REVIEW_ID="$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 3 2>/dev/null || head -c 3 /dev/urandom | od -An -tx1 | tr -d ' \n')" && cat > .claude/plan-review-loop.local.md << STATE_EOF
---
active: true
phase: locate
review_id: ${REVIEW_ID}
started_at: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
target: (pending)
spec: (pending)
---

$ARGUMENTS
STATE_EOF
echo "Plan Review Loop activated (ID: ${REVIEW_ID})"

Update phase:, target:, and spec: in the state file as the loop progresses. If the session is interrupted and resumed, read this file to pick up where the loop left off.

Phase 1 — Locate or Author

If the argument is a file path: that's the target plan. Read it fully.

If the argument names an existing plan loosely ("the migration plan"): search these locations, newest first:

• docs/superpowers/plans/*.md (superpowers writing-plans output)
• docs/plans/, plans/, docs/planning/
• task_plan.md at repo root (planning-with-files)
• .kiro/specs/*/tasks.md
• PLAN.md, IMPLEMENTATION.md at repo root or under docs/

If the argument is a task with no existing plan: author one first — follow the project's planning convention if one exists (for superpowers projects, the writing-plans structure: header with Goal/Architecture/Global Constraints, bite-sized tasks with exact Files/Interfaces/steps/commands), save it to the conventional location (default docs/superpowers/plans/YYYY-MM-DD-<feature>.md), then enter review. Write it as if it were final.

Find the source spec. A plan usually implements a spec or requirements doc (check the plan's own references, docs/superpowers/specs/, or ask the user). Record both paths in the state file. If no spec exists, note that in the state file — Lane 2 reviews grounding against the codebase only, and the missing spec itself becomes a finding candidate.

Set phase: review.

Phase 2 — Independent Review

Pick a reviewer backend, in order of preference. The shared backend mechanics are in reviewer-backends.md in the installed codex-review skill directory (its sibling in an Inkstone installation); this is a required dependency. Locate it through skill discovery and read it before dispatching. Log which backend ran and why earlier ones were skipped. If the dependency is missing, or no backend qualifies, log the failure, delete this loop's .claude/plan-review-loop.local.md, preserve the plan and review artifacts, and report review incomplete. Do not enter addressing or leave an incomplete loop for the Stop hook to exhaust its block budget.

Set the absolute REVIEW_FILE to reviews/plan-review-<id>.md before dispatch; apply the shared fresh-output and validation contract. The reviewer writes findings and never revises the target plan. The caller adds dispositions and edits the plan only in Phase 3.

1. Codex CLI (if command -v codex succeeds): first ensure multi-agent is enabled by running this bootstrap verbatim (idempotent; identical to the original review-loop's):

   CODEX_CONFIG="${HOME}/.codex/config.toml" && if [ ! -f "$CODEX_CONFIG" ]; then mkdir -p "${HOME}/.codex" && printf '[features]\nmulti_agent = true\n' > "$CODEX_CONFIG" && echo "Created ~/.codex/config.toml with multi_agent enabled"; elif ! grep -qE '^\s*multi_agent\s*=\s*true' "$CODEX_CONFIG"; then if grep -qE '^\[features\]' "$CODEX_CONFIG"; then if [ "$(uname)" = "Darwin" ]; then sed -i '' '/^\[features\]/a\'$'\n''multi_agent = true' "$CODEX_CONFIG"; else sed -i '/^\[features\]/a multi_agent = true' "$CODEX_CONFIG"; fi; else printf '\n[features]\nmulti_agent = true\n' >> "$CODEX_CONFIG"; fi && echo "Enabled multi_agent in ~/.codex/config.toml"; else echo "Codex multi-agent: already enabled"; fi

   Run codex --sandbox read-only exec --output-last-message "$REVIEW_FILE" "<prompt>" < /dev/null non-interactively. Ask for the complete consolidated review as its final Markdown message; the CLI writes that message to the artifact. Do not ask model tools to write it. Record independence from the actual author and reviewer models/vendors.

   A hung Codex never exits — never wait on exit alone. Codex can block on startup (auth refresh, dead network call) and burn an hour producing nothing. Three mandatory rules:

   • Redirect, never pipe. Launch in the background with output to a file — pipes (| tail, | head) buffer until exit and make a dead process indistinguishable from a working one:

     touch .claude/plan-review-codex-launch
     # Run this entire supervisor block as ONE backgrounded tool invocation.
     # Substitute the absolute paths recorded at setup in this invocation.
     PID_FILE="/absolute/per-attempt-run/reviewer.pid"
     EXIT_FILE="/absolute/per-attempt-run/reviewer.exit"
     codex --sandbox read-only exec --output-last-message "$REVIEW_FILE" "<prompt>" < /dev/null > .claude/plan-review-codex-run.log 2>&1 &
     REVIEW_PID=$!
     printf '%s\n' "$REVIEW_PID" > "$PID_FILE"
     if wait "$REVIEW_PID"; then REVIEW_EXIT=0; else REVIEW_EXIT=$?; fi
     printf '%s\n' "$REVIEW_EXIT" > "$EXIT_FILE"

   • Liveness probe at ~90s. A healthy Codex writes a rollout file within seconds of starting a session. About 90 seconds after launch, check:

     find "$HOME/.codex/sessions/$(date +%Y/%m/%d)" -name 'rollout-*.jsonl' -newer .claude/plan-review-codex-launch 2>/dev/null | head -1

     No rollout file → the run is dead on arrival. Read this attempt's PID from PID_FILE, terminate it, log backend=codex DEAD (no rollout within 90s), and fall back to backend 2 immediately. The supervisor owns wait and writes EXIT_FILE; later tool calls read those files rather than relying on shell variables surviving.

   • Watchdog. Hard cap ~15 minutes total; also treat "run log unchanged for 5 consecutive minutes" as a hang (poll while waiting — do not idle to a stop). On either trigger, or if Codex exits without producing the review file: kill the process, log the failure, fall back to backend 2.
2. opencode (if installed and a model has quota): prepare and inspect the report-scoped inkstone-reviewer agent from reviewer-backends.md. Run OPENCODE_CONFIG_CONTENT="$(cat "$REVIEW_CONFIG")" opencode run --pure --agent inkstone-reviewer -m <provider/model> --title "plan review <id>" "<prompt>" < /dev/null through the shared supervisor block, with its own fresh PID/exit files and .claude/plan-review-opencode-run.log. It reads the plan/spec with file tools and writes the consolidated review directly to REVIEW_FILE; shell and delegation are disabled. Record the model and validate the artifact before advancing. Liveness: the log should grow within the first minute; unchanged for 5 minutes is a hang; hard cap ~15 minutes. On failure, log it and fall back to backend 3.
3. Context-blind subagents: dispatch three parallel subagents, one per lane, with the restricted tools and host output capture specified in reviewer-backends.md. Each prompt contains ONLY the plan path, source spec path (Lane 2), repo root, lane criteria from plan-review-dimensions.md, and finding format. Never include planning reasoning or conversation history. Capture their final findings verbatim as lane reports, then consolidate: deduplicate, sort by severity, write reviews/plan-review-<id>.md. Record actual model identity and label same-model when applicable. If the host cannot enforce the shared contract, report review incomplete.

Whichever backend ran, the review file records the tool and model, and which backends were skipped and why.

The three review lanes (full criteria in plan-review-dimensions.md — read it before dispatching):

1. Zero-Context Executability — role-play an engineer with no codebase knowledge executing the plan literally; flag every point where they'd have to guess
2. Grounding & Traceability — verify every referenced path/API/command against the actual repo; verify the plan covers its source spec completely and invents nothing beyond it
3. Structure & Risk — task granularity and ordering, dependency correctness, per-task verification, missing failure/rollback handling

Finding format (same shape as review-loop code findings):

- **[severity: critical|high|medium|low] [lane]** <task/step or line reference>
  <description of the problem>
  Suggested fix: <concrete, actionable rewrite or addition>

The review file ends with a summary: total findings, breakdown by severity, lanes run, and an overall verdict (ready to execute / needs revision / re-plan against spec).

Set phase: addressing.

Phase 3 — Address With Judgment

Read the review file carefully. For each finding, independently decide if you agree — do not blindly accept every suggestion:

• Agree → revise the plan document directly.
• Disagree → do not change the plan; record why.
• Findings that change scope or contradict the spec's intent → surface to the user rather than deciding unilaterally.

Work critical and high severity first. Before appending the disposition log, decide whether a confirmation round is owed: if any critical finding is being FIXED, set phase: confirm in the state file first, so the stop hook knows the loop is not done at disposition time. If no critical finding was fixed, leave the phase at addressing (the hook treats disposition-in-addressing as completion). Then append the disposition log to the bottom of the review file:

## Disposition (<UTC timestamp>)
- Finding 1: FIXED — <one line on the change>
- Finding 2: SKIPPED — <one line on why>
- Finding 3: ESCALATED to user — <the question>

Phase 4 — Confirm (conditional)

If any critical finding was fixed (i.e., the state file now says phase: confirm), run exactly one confirmation round: re-dispatch one fresh context-blind reviewer with the revised plan and the prior review file, asking only "are the critical findings resolved, and did the revisions introduce new problems?" The same backend rules apply, including Codex/OpenCode liveness probes and watchdogs — on backend failure, fall back to the next backend rather than skipping confirmation. Give this reviewer a fresh separate confirmation-artifact path and scope its write access to that file, leaving the prior review readable. Validate its output, then append its verdict to the original review as a ## Confirmation section (the stop hook looks for this exact heading before allowing exit from the confirm phase). Do not loop beyond this single round.

Phase 5 — Cleanup

Delete .claude/plan-review-loop.local.md. Report to the user: plan path, review file path, findings fixed/skipped/escalated, and the final verdict. If the verdict is ready to execute, suggest the appropriate execution route (e.g., superpowers:executing-plans or superpowers:subagent-driven-development for superpowers plans).

Rules

• Keep the state file's phase: truthful at every transition — the stop hook enforces the loop through it (locate/review → review file required; addressing → disposition required; confirm → ## Confirmation required) and fails open (abandons the loop) after repeated blocks with no progress
• Never pipe a reviewer process's output; redirect to a file and poll for growth — a pipe hides the difference between working and dead
• Log notable events (backend chosen, fallbacks, phase transitions, watchdog kills) to .claude/plan-review-loop.log as timestamped lines, matching the hook's format
• Complete the plan fully before entering review — no stopping mid-draft to "let the review catch it"
• Reviewers never see planning context; dispatch prompts are built from the documents and the dimensions file only
• Never fabricate findings or a review file — if the backend fails, say so and fall back
• The plan document is the single source of truth; all accepted fixes land in the plan itself, not in the review file