---
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:
  - ask_question
  - define_subagent
  - grep_search
  - invoke_subagent
  - manage_subagents
  - replace_file_content
  - run_command
  - send_message
  - view_file
  - write_to_file
---
<purpose>
Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.

Supports three modes:
- **Create** (default): Build plan from analysis context or phase requirements
- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan

All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
</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
</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
- `--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".

**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".

### Role Knowledge
`maestro wiki list --category arch` → select relevant → `maestro wiki load`
</context>

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

Before starting the plan pipeline, run:
```
run_command("maestro collab preflight --phase <phase-number>")
```
If exit code is 1, present warnings and ask whether to proceed.

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

### Codebase Docs Loading (P1 addition)

During P1 Context Collection, after loading context files, load codebase documentation if available:

```
IF exists(.workflow/codebase/doc-index.json):
  codebase_ctx = view_file(.workflow/codebase/ARCHITECTURE.md) + view_file(.workflow/codebase/FEATURES.md)
  Pass codebase_ctx to planner agent as structural context
ELSE:
  display "W004: Codebase docs unavailable, continuing with code exploration only"
```

### Wiki Knowledge Search (P1 addition)

During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:

```
phase_keywords = extract key terms from goal/title (2-5 terms)
wiki_result = run_command("maestro wiki search ${phase_keywords} --json 2>/dev/null")

IF wiki_result exit code != 0 OR empty:
  display "W003: Wiki search unavailable, continuing without prior knowledge"
ELSE:
  entries = JSON.parse(wiki_result).entries (limit to first 10)
  wiki_context = structured block for downstream stages
```

### Issue Linkback (--gaps mode)

After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:

```
For each created TASK-{NNN}.json that has issue_id:
  Update corresponding issue in .workflow/issues/issues.jsonl:
    task_refs: append TASK-{NNN} to array
    task_plan_dir: relative path to .task/ directory
    status: "planned"
    updated_at: now()
  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
```

This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.

**Report format on completion:**

```
=== 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

Next steps:
  /maestro-execute              -- Execute the plan
  /maestro-execute --dir {dir}  -- Execute specific plan
  /maestro-plan {phase}         -- Re-plan with modifications
```

**Completion (when invoked from ralph):**
End the step by calling the CLI (no `--- COMPLETION STATUS ---` text block):
```
maestro ralph complete <idx> --status DONE [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
```

STATUS verdicts (CLI-enforced enum):
- **DONE** — Plan created/revised and confirmed → next step picks up automatically
- **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
- **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
- **BLOCKED** — External hard blocker (e.g., upstream artifact missing, dependency unavailable); pass `--reason "..."`

> Ambiguous requirements are NOT a completion status — resolve them in-place via `ask_question` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.

### Mode: Revise / Check

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

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
| E005 | error | Plan directory not found (--check) | Check path, use --dir |
| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
</error_codes>

<success_criteria>
- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
- [ ] .task/TASK-*.json files created for each task
- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
- [ ] Plan confidence scored in P4 with 5-dimension factor model
- [ ] Plan readiness gate checked before P4.5 collision detection
- [ ] Pressure pass completed on highest-complexity task
- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
- [ ] Collision detection executed against same-milestone plans (non-blocking)
- [ ] Plan-checker passed (or minor issues acknowledged)
- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
</success_criteria>
