<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 — read when generating plan output
task.json — read when generating task files
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):

--from analyze:ANL-xxx → uses analyze conclusions.implementation_scope directly
--from blueprint:BLP-xxx → uses blueprint requirements + architecture
--dir <path> → explicit context directory (unchanged)
Numeric arg → scope = "phase", resolve from roadmap (unchanged)
No args + roadmap → scope = "milestone" (unchanged)
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:

Bash("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 = Read(.workflow/codebase/ARCHITECTURE.md) + Read(.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 = Bash("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 AskUserQuestion 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>

maestro-plan

details

Role Knowledge

Codebase Docs Loading (P1 addition)

Wiki Knowledge Search (P1 addition)

Issue Linkback (--gaps mode)

Mode: Revise / Check

technical

related