Maestro Plan

---
name: maestro-plan
description: Use when creating, revising, or verifying an execution plan for a phase or task
argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---
<purpose>
Create, revise, or verify execution plans (5-stage pipeline).
Produces plan.json + TASK files; registers PLN artifact in state.json.
</purpose>

<required_reading>
@~/.maestro/workflows/plan.md
</required_reading>

<deferred_reading>
- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
- [task.json](~/.maestro/templates/task.json) — read when generating task files
- [state.json](~/.maestro/templates/state.json) — read when registering artifact
- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
</deferred_reading>

<context>
$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.

Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.

**Command-level flags** (extensions beyond workflow base):
- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
  - `analyze:ANL-xxx` → CONTEXT_DIR = artifact path, scope = "standalone"
  - `blueprint:BLP-xxx` → CONTEXT_DIR = blueprint path, scope = "standalone"
  - `@file` or `path/` → load context-package.json from path
- `--tdd` — Enable TDD mode: generate test-first task structure (Red-Green-Refactor). See workflow `plan.md` § TDD Mode for task generation rules.
- `--revise [instructions]` -- See workflow plan.md § Revise Mode
- `--check <plan-dir>` -- See workflow plan.md § Check Mode

**Upstream context (resolution priority):**
1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
3. `--dir <path>` → explicit context directory (unchanged)
4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
5. No args + roadmap → scope = "milestone" (unchanged)
6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone

**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".

**`--from analyze:*` / `blueprint:*`**: scope=standalone → skip adhoc milestone auto-creation.

### Role Knowledge
`maestro search --category arch` → select relevant → `maestro load --type knowhow --id`
</context>

<execution>
### Pre-flight: team conflict check

Before starting the plan pipeline, run:

Bash("maestro collab preflight --phase ")

If exit code is 1, present warnings and ask whether to proceed.

Follow '~/.maestro/workflows/plan.md' completely.

### Phase Gates (MANDATORY, BLOCKING — Create mode only)

**GATE P1 → P2: Context Collection → Clarification**
- REQUIRED: Context files loaded (roadmap, analyze artifact, or --from source).
- REQUIRED: Codebase docs read if available (ARCHITECTURE.md, FEATURES.md).
- REQUIRED: Wiki searched for prior knowledge related to phase keywords.
- BLOCKED if missing: no context source found — cannot plan without upstream input (E001).

**GATE P2 → P3: Clarification → Plan Generation**
- REQUIRED: Ambiguous requirements resolved via AskUserQuestion (<=3 rounds).
- BLOCKED if: unresolved ambiguities remain after 3 clarification rounds — escalate to user before proceeding.

**GATE P3 → P4: Plan Generation → Plan Check**
- REQUIRED: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written.
- REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
- BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.

**GATE P3.5 → P4: Boundary Grill → Plan Check**
- REQUIRED: Boundary grill executed per workflow boundary-grill.md.
- NON-BLOCKING: conflicts logged as warnings, not hard stops.

**GATE P4 → P5: Plan Check → User Confirmation**
- REQUIRED: Plan-checker passed (or minor issues acknowledged).
- REQUIRED: Boundary grill completed.
- REQUIRED: Confidence scored with 5-dimension factor model.
- REQUIRED: Pressure pass completed on highest-complexity task.
- REQUIRED: UI plans have `[UI-observable]` convergence criteria per wave (details in workflow).
- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage.

**GATE P5 → Completion: User Confirmation → Done**
- REQUIRED: User confirmation captured (execute/modify/cancel).
- REQUIRED: PLN artifact registered in state.json.
- BLOCKED if missing: no user confirmation — do not register artifact or report completion.

### Mode: Revise / Check

Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
</execution>

<completion>
### Standalone report

=== PLAN READY === Phase: {phase_name} Tasks: {task_count} tasks in {wave_count} waves Check: {checker_status} (iteration {check_count}/{max_checks}) Collision: {collision_status}

Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json

### Ralph-invoked completion

End the step by calling the CLI (no text block output):

maestro ralph complete --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]

Status verdicts:
- **DONE** — Plan created/revised and confirmed → next step picks up automatically
- **DONE_WITH_CONCERNS** — Plan produced but wi