plan-review

Plan Review: Validate & Prepare for Execution

Language

Read blueprint/.config.yml → language. If auto, detect from the user's messages. All generated content MUST be in the detected language. Skill instructions stay in English — only output changes.

Review, validate, and prepare a plan for execution. This is the pre-flight check before /plan-approved — it ensures the plan is complete, tasks are complexity-marked, and the execution strategy maximizes throughput.

/plan → /plan-review → /plan-approved → /plan-check → /pr → /finish
                     ↑ context clear only if context usage > 30% after plan-review
/plan → /plan-review -wt → [worktree created] → cd worktree → /plan-approved → ...

Critical Rules

These are non-negotiable:

1. Read plan + team-execution.md in parallel. Step 1 reads both via blueprint meta + bundled reference. Never fabricate plan details.
2. Use sequential thinking. Call mcp__sequential-thinking__sequentialthinking at Step 2 for validation. Never skip it.
3. Mark ALL tasks. Every task gets [H]/[S]/[O] at Step 3. No unmarked tasks allowed.
4. Teams are the default for phases with [S]/[O] tasks. Parallel subagents are the default for all-[H] phases. Multiple teams can run in parallel across independent phases.
5. Follow step order. Steps build on each other.
6. Plan file ONLY. Do NOT modify application source code, config files, or any file outside blueprint/. This skill edits ONLY the plan markdown file.
7. Preserve plan structure. Do NOT create new phases, remove phases, or reorganize the plan. "Fix issues directly" means refining task descriptions, adding missing test tasks within existing phases, and clarifying acceptance criteria — NOT redesigning the plan.

---

Step 1: Parallel Data Gather

echo "🔷 BP: plan-review [1/3] reading plan + team-execution ref"
# Primary: CLI-first plan discovery
~/.blueprint/bin/blueprint meta

# Fallback if CLI unavailable: find active plan manually
# ls blueprint/live/[0-9]*-*.md

# Also read config for staging_branch and stack info — use the Read tool:
# Read("blueprint/.config.yml")

Primary: ~/.blueprint/bin/blueprint meta returns JSON with branch, base_branch, plan_file, project, etc. Derive PLAN_NUM from the leading digits in plan_file. If $ARGUMENTS is a path or number, use that instead.

Fallback: If the CLI is unavailable, use ls blueprint/live/[0-9]*-*.md to find the active plan. Also read blueprint/.config.yml for staging_branch and stack info needed in later steps.

Run these simultaneously in a single step (do not wait between them):

1. READ the full plan file — required before Step 2
2. Read references/team-execution.md (bundled) — needed for Steps 3-4 (complexity tiers + delegation strategy)

Do NOT proceed to Step 2 until you have read both.

Step 2: Validate Plan

echo "🔷 BP: plan-review [2/3] running sequential thinking validation"

You MUST use mcp__sequential-thinking__sequentialthinking here. This is MANDATORY — never skip it, even for small plans. Use it to validate:

• Completeness: Does each phase have clear, actionable tasks?
• Dependencies: Are phases ordered correctly? Build a dependency chain.
• Vague tasks: Refine task descriptions to be specific and implementable (do NOT add new phases or restructure)
• Missing tests: Every phase that touches code MUST have corresponding tests — add test tasks within the existing phase if missing
• Missing acceptance criteria: Add if absent
• File conflicts: Two phases modifying same file → must be sequential or same worker
• Feasibility: Spot-check key codebase files (use Explore agents for deeper dives)
• Plan size: With 1M context, large plans are fine — the coordinator only orchestrates. No need to split.
• Phase dependency validation: Verify no phase depends on output from a later phase
• Cross-phase file conflict detection: List files touched per phase, flag overlaps explicitly
• Stale references: Spot-check that key files/classes referenced in the plan actually exist in the codebase (use Glob/Grep). Flag any stale references for the user.
• Partial execution: If any tasks are already marked [x], note them as completed and adjust the execution strategy to only cover remaining [ ] tasks.

Refine existing tasks directly — do NOT create new phases, split phases, or restructure the plan.

Step 2B: Auto-Detect Tech Stack Versions (parallel with Step 2)

During Step 2's sequential thinking, also detect the project's tech stack. Read config FIRST (already populated by /start or /bp-context), only detect from project files if config is empty:

Read blueprint/.config.yml using the Read tool (already fetched in Step 1) and check the stack: section. If stack is not in config, detect from project files:

# If stack not in config, detect from project files
if [ -f composer.lock ]; then
    grep -A1 '"name": "laravel/framework"\|"livewire/livewire"' composer.lock | grep '"version"'
elif [ -f package-lock.json ]; then
    grep -E '"(next|react|vue|angular|svelte)":' package.json
elif [ -f go.mod ]; then
    head -5 go.mod
fi

Add a brief ## Tech Stack Versions section to the plan (3-5 lines). Workers need this to avoid framework compatibility issues.

Step 3: Mark Task Complexity + Update Frontmatter

Update the plan frontmatter status from todo → awaiting-review at the start of this step. Add strategy and reviews fields to frontmatter at Step 5 (after determining strategy).

Mark ALL tasks in the Phases section:

Marker	Tier	When to Use
[H]	Fast/small	CRUD, config, i18n, migrations, styling, renaming, views, constants
[S]	Balanced	Business logic, services, API integration, complex tests, dynamic components
[O]	Strong reasoning	Architecture, multi-system coordination — rare

Default to [H]. Escalate to [S] only when the task needs real reasoning. [O] is almost never needed.

Verification Phase Rule — CRITICAL

NEVER mark "verify + fix" phases as Leader Direct. If a phase is labeled "verify and fix stragglers", "fix remaining failures", or similar:

1. Split it into two distinct phases:

   • Phase N: Verification (Leader Direct — just run tests, collect results, zero fixing)
   • Phase N+1: Fix Stragglers (Parallel Subagents — one agent per failure category)

2. Reserve Leader Direct ONLY for purely mechanical tasks — run formatter, update a config line, bump a version number, update a constant. If there's any chance of failures to investigate, it MUST be delegated.

3. Verification phases that may reveal failures should always use Parallel Subagents with the note: "If verification reveals failures, coordinator dispatches N agents = N failure categories found."

This forces the plan to account for parallel fix dispatch upfront, rather than the coordinator improvising when failures appear and burning 70%+ of context debugging inline.

Note: This is the ONE exception to the "no new phases" rule — verification+fix phases MUST be split for correct execution.

Step 4: Determine Execution Strategy

The goal is MAXIMUM THROUGHPUT — finish the plan as fast as possible.

Quick Plan Profile

Before entering the decision tree, extract:

Metric	Value
Total open tasks	count [ ] items
Phase count	number of ### phase headings
Max task complexity	highest marker: H / S / O
Parallel potential	any phases with zero file overlap? yes / no

Size Thresholds (override decision tree for small plans)

Condition	Override
≤3 total open tasks, all [H]	→ Leader Direct — no spawn needed
≤8 total open tasks, all [H]	→ Single Subagent — no team overhead
≤5 total open tasks, any [S]/[O]	→ Mode C: Single Team — team adds value for reasoning
>8 tasks OR any [S]/[O] with >5 tasks	→ Continue to Step 5A normally

Execution Modes

Mode	Name	When
A	Parallel Subagents	2+ independent phases, all [H] — fire and forget
B	Parallel Teams	2+ independent phases with [S]/[O] — N team-lead subagents
C	Single Team	1 phase with [S]/[O] — leader gives full attention
D	Mixed Dispatch	1 active team + parallel [H] subagents simultaneously
E	Coordinated Team	Tasks within a team need sequential handoff
F	Single Subagent	1 phase, all [H], sequential
G	Leader Direct	≤3 [H] tasks, no spawn needed

Key constraint: each team-lead can only manage ONE team. Parallel = N separate team-leads, not 1 leader managing N teams.

Step 4A: Build Phase Dependency Graph

This is the biggest speed win — which phases can run simultaneously?

1. List each phase's files/directories it touches
2. Identify phases that touch different codebases (e.g., backend vs frontend, models vs views)
3. Identify phases with no data dependencies (Phase B doesn't need Phase A's output)
4. Check for file conflicts — two phases touching the same file must be same worker or sequential
5. Group independent phases into parallel Rounds

Common parallel patterns:

• API + Mobile/Frontend → always parallelizable (different codebases)
• Backend models + Frontend components → parallelizable
• Tests that only read code → parallelizable with everything except what they test
• Phases touching same file → combine into one worker

File-Touch Matrix

Build an explicit file-touch matrix to identify parallelism opportunities:

| Phase | Files/Dirs Touched | Depends On |
|-------|-------------------|------------|
| Phase 1 | app/Models/X.php, app/Resources/XResource/ | — |
| Phase 2 | app/Models/Y.php, app/Resources/YResource/ | — |
| Phase 3 | app/Services/ZService.php, app/Models/Z.php | Phase 1 |

Rules:

• If two phases have ZERO file overlap AND no data dependency → mark as parallel
• If two phases touch the same directory but different files → usually parallel (verify no shared imports)
• If two phases touch the same file → MUST be sequential or assigned to same worker
• Document the parallelism analysis explicitly — never skip this step

This matrix MUST be included in the ## Execution Strategy section so /plan-approved can verify parallel dispatch is safe.

Step 4B: Choose Mode Per Round

2+ independent phases (run in parallel)?
├─ YES → Any phase has [S]/[O] tasks?
│         ├─ YES → Mode B: Parallel Teams
│         └─ NO (all [H]) → Mode A: Parallel Subagents
│         ★ Mixed: [S]/[O] phase as team-lead + [H] phase as subagent — dispatched together
└─ NO (1 phase or sequential)
          ├─ Any [S]/[O] tasks?
          │   ├─ YES → Tasks within team need handoff?
          │   │         ├─ YES → Mode E: Coordinated Team
          │   │         └─ NO  → Mode C: Single Team
          │   └─ NO (all [H]) → ≤ 3 tasks?
          │               ├─ YES → Mode G: Leader Direct
          │               └─ NO  → Mode F: Single Subagent
          └─ Sequential [S]/[O] + concurrent [H] phases → Mode D: Mixed dispatch

Model per worker (based on hardest task in their assignment):

• All [H] tasks → Sonnet (faster output for simple/mechanical tasks)
• Any [S] or [O] task → Opus (maximum quality — speed comes from parallelism, not weaker models)

Workers are identified by sequential IDs (worker-1, worker-2, etc.) within each team round.

Step 4C: Maximize Parallelism

• Dispatch all at once — spawn every worker in ONE message
• Leader can manage ONE active team while subagents run in parallel — but NEVER 2 active teams at once
• Never serialize what can run in parallel

Common Profiles

#	Profile	Recommended Strategy
1	1 phase, ≤3 tasks, all [H]	Leader Direct
2	2+ phases, all [H], zero file overlap	Mode A: Parallel Subagents
3	2+ phases, any [S]/[O], zero file overlap	Mode B: Parallel Teams
4	1 phase, [S]/[O] tasks, sequential	Mode C: Single Team
5	1 team needed + concurrent [H] phases	Mode D: Mixed Dispatch

Step 5: Update Plan File — Execution Strategy Section

Add the ## Execution Strategy section to the plan. The format depends on the mode chosen. Read references/team-execution.md for worker IDs and delegation details.

Header Block (always present)

## Execution Strategy

> **Approach:** `/plan-approved` with <actual strategy>
> **Total Tasks:** N (H: X, S: Y, O: Z)
> **Estimated Rounds:** N (X parallel, Y sequential)

Round Formats by Mode

Parallel Subagents (Mode A):

### Round 1: Phase 1 + Phase 2 → Parallel Subagents (2 workers, dispatched together)
Independent phases — Phase 1 touches `app/Services/`, Phase 2 touches `resources/views/`.

| Phase | Model | Tasks | Notes |
|-------|-------|-------|-------|
| Phase 1: Service layer | Opus | 1.1, 1.2, 1.3 (1x[S] + 2x[H]) | Business logic needs quality |
| Phase 2: Views | Sonnet | 2.1, 2.2 (2x[H]) | Simple tasks, fast model |

Single Team (Mode C):

### Round 2: Phase 3 → Single Team (depends on Round 1)

| Task | Model | Worker | Notes |
|------|-------|--------|-------|
| 3.1 Wire service | [S] | worker-1 | Integration logic |
| 3.2 Feature tests | [S] | worker-2 | Tests for integration |

Mixed Dispatch (Mode D):

### Round 2: Phase 3 (team) + Phase 4 (subagent) → Mixed dispatch

| Phase | Mode | Model | Tasks | Notes |
|-------|------|-------|-------|-------|
| Phase 3: Complex service | Team | Opus | 3.1, 3.2 (2x[S]) | Leader manages |
| Phase 4: Config | Subagent | Sonnet | 4.1, 4.2 (2x[H]) | Simple tasks, fast model |

Coordinated Team (Mode E):

### Round 3: Phase 5 → Coordinated Team (handoff required)

| Task | Model | Worker | Notes |
|------|-------|--------|-------|
| 5.1 Build interface | [S] | worker-1 | Writes handoff |
| 5.2 Implement consumer | [S] | worker-2 | Waits for handoff |

Leader Direct (Mode G):

### Round 4: Phase 6 → Leader Direct
3 trivial config changes. Tasks: 6.1 update .env.example, 6.2 add constant, 6.3 update README

Also update the frontmatter in the same edit (save a tool call):

• Set status: approved (from awaiting-review)
• Add strategy: <chosen-mode> (e.g., parallel-teams, single-subagent, leader-direct)
• Add reviews: array with any corrections/findings from validation (empty array [] if none)
• Do NOT add phases_total, tasks_total, sessions, or blockquote status bars — these are v1 fields

Step 6: Pre-Commit Checklist

echo "🔷 BP: plan-review [3/3] verifying pre-commit checklist"

Verify ALL items before committing:

• ALL tasks have [H]/[S]/[O] complexity markers
• Each round has the correct mode label
• Parallel all-[H] phases use regular subagents (fire-and-forget)
• Parallel [S]/[O] phases use team-lead subagents (each manages own team)
• Sequential [S]/[O] phases use Single Team with sequential worker IDs
• Coordinated Team justified — tasks WITHIN a team need sequential handoff
• Mixed rounds dispatch team + subagents in ONE message
• Task counts per phase in round descriptions
• Model selection justified per worker
• Cross-phase parallelism was explicitly analyzed (not skipped)
• If all-sequential: documented why no parallelism is possible
• No [S]/[O] tasks in Leader Direct rounds — Leader Direct is ONLY for all-[H] mechanical tasks
• Approach line reflects actual mode used
• Only the plan file in blueprint/ was modified — no application source code changes

Step 7: Commit and Output

git add blueprint/ && git commit -m "📋 plan: review NNNN-<description>"

This review commit is the BASELINE — it contains the full task list with complexity markers and execution strategy.

Worktree Creation (if -wt or --worktree flag)

If the flag is present, create a lightweight worktree:

REPO_NAME=$(basename "$PWD")
PARENT_DIR=$(dirname "$PWD")
PLAN_NUM_SHORT=$(echo "$PLAN_NUM" | sed 's/^0*//')
WORKTREE_PATH="${PARENT_DIR}/${REPO_NAME}${PLAN_NUM_SHORT}"

git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
git worktree list | grep "$WORKTREE_PATH"
git -C "$WORKTREE_PATH" rebase "$BASE_BRANCH"
code "$WORKTREE_PATH"

No .env copying, no dependency installs — just the isolated working directory.

Output Summary

Plan Review Complete!
Plan: blueprint/live/NNNN-type-description.md
Status: Ready for Approval

Execution Rounds:
  Round 1 → Parallel Teams: Phase 1 (Sonnet) + Phase 2 (Sonnet) [spawned together]
  Round 2 → Single Team: Phase 3 (Sonnet) [depends on Round 1]

Totals: N tasks, M rounds (~X parallel savings)

[if -wt]
Worktree: /path/to/repoNN   ← cd here, then run /plan-approved

STOP. Use AskUserQuestion here.

Context clear decision — based on actual context usage, not plan size. The coordinator only orchestrates (delegates to subagents), so even moderate remaining context is enough:

Context used	Recommendation
< 30%	Continue directly — plenty of headroom for orchestration
30-50%	Suggest clear — "Context clear recommended but you can continue"
> 50%	Recommend clear — "Clear context for maximum headroom"

• Question (< 30% context, no worktree): "Plan reviewed and committed. Context is light — continuing directly to /plan-approved."
  • Option 1: "Continue — run /plan-approved now"
  • Option 2: "Clear context first, then /plan-approved"
  • Option 3: "Let me adjust the plan first"
• Question (30-50% context, no worktree): "Plan reviewed and committed. Context at ~X% — clearing recommended but optional."
  • Option 1: "Continue anyway — run /plan-approved now"
  • Option 2: "Clear context first, then /plan-approved"
  • Option 3: "Let me adjust the plan first"
• Question (> 50% context, no worktree): "Plan reviewed and committed. Context at ~X% — recommend clearing for maximum headroom."
  • Option 1: "Got it — clearing context now"
  • Option 2: "Continue anyway — run /plan-approved now"
  • Option 3: "Let me adjust the plan first"
• Question (with -wt): "Plan reviewed. Worktree ready at /path/to/repoNN."
  • Option 1: "Got it — opening worktree terminal now"
  • Option 2: "Let me adjust the plan first"

Flags

• --worktree / -wt: Create lightweight worktree after commit
• --no-worktree / -nw: Skip worktree creation (default)

Use $ARGUMENTS as plan file path or flags.

Rules

• Plan file ONLY — do NOT modify application source code, config, or any file outside blueprint/
• Preserve structure — do NOT create new phases, remove phases, or reorganize the plan (exception: splitting verify+fix phases per the Verification Phase Rule)
• Parallel all-[H] phases → regular subagents (fire-and-forget, dispatch all at once)
• Parallel [S]/[O] phases → team-lead subagents (each manages own team internally)
• Sequential [S]/[O] phase → Single Team with sequential worker IDs (worker-1, worker-2, etc.)
• Mixed dispatch is valid — 1 team + N subagents launched in same message
• Coordinated Team is for tasks WITHIN a team that need sequential handoff (not cross-phase)
• File conflict = combine into one worker or make sequential
• Always look for cross-phase parallelism first
• Use sequential thinking to analyze — don't rubber-stamp
• Refine existing tasks, preserve existing plan content
• Keep your own context lean for the /plan-approved that follows

CLI Acceleration Opportunities

These operations could be delegated to blueprint CLI in future versions:

• blueprint validate <plan-file> — automated completeness check (missing tests, unmarked tasks, stale file refs)
• blueprint plan-profile <plan-file> — extract Quick Plan Profile metrics (task count, complexity distribution, parallel potential)
• blueprint file-matrix <plan-file> — generate file-touch matrix from plan task descriptions

These would make Step 2-4 faster by pre-computing what the model currently does manually.