plan-review-loop

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})"