maestro-roadmap

<purpose>
Generate milestone/phase roadmap from requirements or upstream context. Three modes: create (default), revise (`--revise`), review (`--review`). For formal spec documents, use `/maestro-blueprint`.

Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {phase} → plan → execute.
</purpose>

<required_reading>
@~/.maestro/workflows/roadmap-common.md
@~/.maestro/templates/roadmap.md
</required_reading>

<deferred_reading>
- [roadmap.md](~/.maestro/workflows/roadmap.md) — read for roadmap generation workflow
</deferred_reading>

<context>
$ARGUMENTS -- requirement text, @file reference, or upstream context source.

**Flags:**

| Flag | Effect | Default |
|------|--------|---------|
| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
| `-c` / `--continue` | Resume from last checkpoint | false |
| `-m progressive\|direct\|auto` | Decomposition strategy | auto |
| `--from <source>` | Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json | — |
| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
| `--revise [instructions]` | Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress. | — |
| `--review` | Roadmap health assessment (read-only) | — |

**Input types:**
- Direct text: `"Implement user authentication system with OAuth and 2FA"`
- File reference: `@requirements.md`
- Context import: `--from brainstorm:BRN-001` or `--from analyze:ANL-xxx` or `--from blueprint:BLP-xxx`
- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`

### Pre-load

1. **Specs**: `maestro load --type spec --category arch` — load architecture constraints for phase decomposition
2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge
3. All optional — proceed without if unavailable
</context>

<interview_protocol>
Follows @~/.maestro/workflows/interview-mechanics.md standard.

**Interaction mode**: convergent menu-driven
**Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
**Scope guard**: only roadmap shape; do not pre-resolve intra-phase task breakdown (belongs to plan)
**Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
**Additional skip conditions**: --revise, --review (skip to respective mode)
**Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section
</interview_protocol>

<execution>

1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
2. Read `@~/.maestro/workflows/roadmap.md`, follow its process

Sub-modes:
- **Create** (default): Build roadmap from requirements or upstream context
- **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
- **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section

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

**GATE 1: Input → Decomposition**
- REQUIRED: Requirement parsed with goal, constraints, stakeholders.
- REQUIRED: Upstream context loaded via --from (if specified).
- BLOCKED if missing: cannot decompose without parsed requirement.

**GATE 2: Decomposition → Refinement**
- REQUIRED: Milestones defined with deliverable targets.
- REQUIRED: Phases defined within milestones with dependencies.
- REQUIRED: Every Active requirement from project.md mapped to exactly one phase.
- REQUIRED: No circular dependencies in phase ordering (E003 if detected).
- BLOCKED if incomplete: finish milestone/phase decomposition before refinement.

**GATE 3: Refinement → Completion**
- REQUIRED: User approved roadmap (or auto-approved with -y).
- REQUIRED: `.workflow/roadmap.md` written with Milestone > Phase hierarchy.
- REQUIRED: Artifact registered in state.json with milestone entries.
- BLOCKED if missing: do not report completion without written roadmap.

### Artifact Verification (before completion)

```
REQUIRED_ARTIFACTS = [
  ".workflow/roadmap.md"    // Milestone > Phase hierarchy with progress table
]
```
If missing: DO NOT report completion.

</execution>

<completion>
### Standalone report

```
=== ROADMAP READY ===
Milestones: {count}
Phases: {total_phases}
Strategy: {progressive|direct|auto}
Output: .workflow/roadmap.md
--- COMPLETION STATUS ---
Status: {DONE|DONE_WITH_CONCERNS}
Concerns: {if any}
```

### Ralph-invoked completion

End the step by calling the CLI (no text block output):
```
maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
```

Status verdicts:
- **DONE** — Normal completion
- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
- **BLOCKED** — External hard blocker; pass `--reason`

### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| Roadmap approved, need analysis | `/maestro-analyze 1` |
| Simple project, ready to plan | `/maestro-plan 1` |
| Need UI design first | `/maestro-impeccable build` |
| View project dashboard | `/manage-status` |
| Need formal spec documents | `/maestro-blueprint` |
</completion>

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | Requirement/idea text or @file required | Prompt user for input |
| E002 | error | Context source not found (--from / --from-brainstorm) | Show available sessions/sources |
| E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
| W001 | warning | CLI analysis failed, using fallback | Continue with available data