review-plan

/magi:review-plan — MAGI plan review

You are the coordinator. Have N CLIs review the user's PLAN/SPEC in parallel, then consolidate their findings using MAGI weighted voting.

0. Preflight

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[[ -z "$PLUGIN_ROOT" ]] && PLUGIN_ROOT="$(cd "$(dirname "$BASH_SOURCE[0]")/../.." 2>/dev/null && pwd)"
USER_CONFIG="$HOME/.config/magi-workflow/config.json"

Run a lightweight preflight; if $USER_CONFIG missing or empty xreview.reviewers, tell the user to run /magi:setup.

Read references/MAGI_VOTING.md (in the plugin root) for the consensus rules. You will follow Steps 1–8 of that document.

0.5. State preflight (auto-refuse if not allowed)

STATE_JSON=$(bash "$PLUGIN_ROOT/scripts/shared/detect-state.sh")
blocked=$(jq -r '.disallowed_skills["review-plan"] // empty' <<<"$STATE_JSON")
if [[ -n "$blocked" ]]; then
  reason=$(jq -r '.disallowed_skills["review-plan"].reason' <<<"$STATE_JSON")
  suggest=$(jq -r '.disallowed_skills["review-plan"].suggest' <<<"$STATE_JSON")
  echo "Cannot run /magi:review-plan: $reason"
  echo "Suggested: $suggest"
  exit 1
fi

--force skips preflight. Note this skill is optional — the user can always skip it entirely by going straight to /magi:tasks.

1. Locate the document

Find the sprint folder (same logic as /magi:tasks). Read its PLAN.md or SPEC.md. If neither exists, abort and tell the user to run /magi:plan first.

2. Build the reviewer prompt

Write a prompt file at <sprint_dir>/.xreview-prompt.md (use .gitignore if needed) containing:

You are reviewing a software engineering plan. Apply skepticism and
domain expertise. Your output must be structured for downstream
consensus aggregation.

[Project context]
- TECHSTACK: see magi/TECHSTACK.md (read it)
- Conventions: see CLAUDE.md / AGENTS.md (read if available)

[Document under review]
<full content of PLAN.md or SPEC.md, with file path header>

[Your task]
Identify issues. For each issue, output a section in this format:

  ## Issue: <one-line subject>
  Severity: Critical | Important | Note
  Where: <file:line or section>
  Description: <2–6 sentences>
  Suggested fix: <1–3 sentences>

Then end with:

  ## Verdict
  <one of: APPROVE | APPROVE-WITH-NITS | REQUEST-CHANGES>
  <one paragraph rationale>

Do not produce any other output sections. Do not edit files.

[Special focus — Spec deltas section]
If the document under review contains a `## Spec deltas` section
declaring modifications to project-level living documents (root SPEC.md,
root CLAUDE.md, magi/PRD.md, magi/TECHSTACK.md), evaluate it critically:

- Are the declared modifications justified by the design described above?
- Are there obvious omissions — impacts the design implies but no delta
  lists (e.g., the plan adds a CLI flag but does not declare a delta to
  the SPEC.md flag table)?
- Does any declared modification break a contract documented elsewhere
  in the targeted file (e.g., contradicting an existing ADR)?

Surface delta-related concerns as standard `## Issue:` blocks and prefix
the subject with `[deltas]` so downstream consensus aggregation can
group them. If the deltas look correct, do not invent issues — silence
is a valid signal.

If `## Spec deltas` is missing entirely from a PLAN.md or SPEC.md, raise
one Important `[deltas]` issue saying so. (TICKET.md and HOTFIX.md never
contain this section — do not raise the issue against those.)

[Feasibility assessment]
Examine the plan for assumptions about development effort, complexity, or
tool/framework ergonomics that have not been validated by prototype or
prior experience. Examples:
- "vanilla TS state management is sufficient" — has this been prototyped?
- "migration will take ~2 hours" — based on what evidence?
- "no external dependencies needed" — are there hidden complexities?

For each such assumption, output:

  ## Spike candidate: <one-line assumption>
  Risk: <what could go wrong if this assumption is false>
  Validation: <how to validate — small prototype, benchmark, or PoC>

If no feasibility assumptions need validation, write:
  ## Spike candidates
  (none identified)