maestro-flow 0.3.21 → 0.3.23

package/workflows/roadmap.md

@@ -1,355 +1,190 @@
-# Workflow: roadmap
-
-Interactive roadmap creation with iterative refinement. Lightweight path from requirements to roadmap without full specification documents.
-
----
-
-## Worktree Guard
-
-Block if `.workflow/worktree-scope.json` exists — must run from main worktree.
-
-## Step 1: Session Initialization
-
-Parse flags from `$ARGUMENTS`:
-- `--yes` / `-y` → auto mode
-- `--continue` / `-c` → resume from last state
-- `--mode` / `-m` → `progressive|direct|auto` (default: auto)
-- `--from-brainstorm <SESSION-ID>` → import brainstorm session
-- Remaining text → requirement (slugified for directory name)
-
-**Session directory**: `.workflow/.roadmap/RMAP-{slug}-{date}/`
-
-**Continue mode**: If `-c` and session exists, resume from last state.
-
-**Brainstorm import**: If `--from-brainstorm`, read `guidance-specification.md` for enriched context (problem statement, features, non-goals, terminology).
-
----
-
-## Step 1.5: Load Project Context
-
-### 1.5.1: Load Specs
-```
-specs_content = maestro spec load --category arch
-```
-Ensure phases in Step 2 respect architectural constraints.
-
-### 1.5.2: Load Project History (if `.workflow/` exists)
-
-Read project artifacts to understand what has already been built and what carries forward:
-
-- `project.md` → already_shipped (Validated), current_scope (Active), project_history (Context), locked_decisions (Key Decisions)
-- `state.json.accumulated_context` → deferred[] (candidate reqs), key_decisions[] (constraints), blockers[] (risks)
-- `.workflow/codebase/` → feature inventory from codebase docs
-
-**Context assembly** — pass to Step 2 as `project_context`:
-```json
-{
-  "already_shipped": ["REQ-001: User auth", "REQ-002: API layer"],
-  "current_scope": ["REQ-003: Payments", "REQ-004: i18n"],
-  "deferred_from_previous": ["Internationalization deferred from v1.0"],
-  "locked_decisions": ["JWT stateless auth", "PostgreSQL"],
-  "learnings": ["JWT has perf issues at scale — consider caching"],
-  "project_history": "Milestone v1.0 completed 2026-03-15: auth + API layer shipped"
-}
-```
-
-**Rules**:
-- NEVER re-plan features listed in `already_shipped` — they are done
-- `deferred_from_previous` items are HIGH PRIORITY candidates for new phases
-- `locked_decisions` constrain technology choices in decomposition
-- `learnings` inform risk assessment and phase sizing
-
----
-
-## Step 2: Requirement Understanding & Strategy
-
-**Objective**: Parse requirement, assess uncertainty, select decomposition strategy.
-
-1. **Parse Requirement**
-   - Extract: goal, constraints, stakeholders, keywords
-   - If `--from-brainstorm`: enrich from guidance-specification.md
-   - If `project_context` loaded (Step 1.5.2): merge into requirement analysis
-     - Cross-reference requirement against `already_shipped` — flag overlaps as "already done"
-     - Promote `deferred_from_previous` items into active requirement scope
-     - Apply `locked_decisions` as constraints
-
-2. **Codebase Exploration (conditional)**
-   - Detect if project has source files
-   - If yes: spawn `cli-explore-agent` for context discovery
-     - If `project_context.already_shipped` exists: include as "feature audit" directive —
-       agent should verify which shipped features are present in code and identify integration points for new work
-   - Output: relevant files, patterns, tech stack, feature_audit (existing capabilities mapped to shipped requirements)
-
-3. **External Research — API & Technology Details (Optional)**
-
-   Spawn `workflow-external-researcher` agent when requirement mentions specific technologies, APIs, or external services.
-
-   **Trigger**: Technology keywords detected in requirement or codebase exploration found external dependencies. Auto-trigger in auto mode (`-y`). Skip if requirement is purely organizational.
-
-   Extract named technologies/APIs/frameworks/protocols from requirement + codebase exploration.
-
-   If topics found → spawn `workflow-external-researcher` agent for API research:
-   - Per technology: stable version, core API surface, auth model, integration patterns, limitations, effort signals
-   - Focus on details affecting phase decomposition and dependency ordering
-   - Output → `apiResearchContext` (in-memory)
-
-   If no topics or research fails → `apiResearchContext = null`, continue.
-
-   `apiResearchContext` is passed into:
-   - Step 3 (Decomposition): technology complexity informs phase sizing and ordering
-   - Step 4 (Refinement): API constraints surface realistic dependency chains
-
-   If research fails: `apiResearchContext = null`, continue without external context.
-
-4. **Assess Uncertainty**
-   - Factors: scope_clarity, technical_risk, dependency_unknown, domain_familiarity, requirement_stability (each: low/medium/high)
-   - >=3 high → progressive, >=3 low → direct, else → ask
-
-5. **Strategy Selection** (skip if `-m` specified or `-y`)
-   - Present uncertainty assessment
-   - User selects: Progressive or Direct
-   - `-y`: use recommended strategy
-
----
-
-## Step 3: Decomposition
-
-**Objective**: Break requirement into phases via CLI-assisted analysis.
-
-Spawn `cli-roadmap-plan-agent`.
-If `apiResearchContext` is set: include as "External API Research" context in the agent prompt — technology complexity, API constraints, and integration effort inform phase sizing and dependency ordering.
-
-### Minimum-Phase Principle (MANDATORY)
-
-**Core rule: Phase = synchronization barrier.** Each Phase triggers a full plan→execute→verify→transition serial cycle. More phases = slower delivery. The wave DAG inside each Phase already handles task ordering and parallelism, so only create a new Phase when tasks **cannot** start until a previous Phase's entire output exists.
-
-**Default: 1 Phase.** Put everything into a single Phase unless a hard dependency forces a split.
-
-| Rule | Constraint |
-|------|-----------|
-| **Default** | **1 Phase**. All work in one plan→execute cycle; wave DAG handles internal ordering. |
-| **Maximum** | **2 Phases**. Only when a hard dependency boundary exists that cannot be resolved. |
-| **Exceptional** | **3 Phases**. Must explicitly justify why 2 is insufficient. |
-| **Minimum tasks per phase** | 5 tasks. If a phase would have fewer, merge it into an adjacent phase. |
-| **Merge principle** | Same-module, same-concern, or tightly-coupled work belongs in ONE phase. Infra + core logic + API in one phase is fine. |
-| **Split principle** | Only split when ALL three hard-dependency conditions are met (see below). |
-
-**Hard dependency — all three conditions required to justify a Phase split:**
-1. **Runtime dependency**: Phase B code at runtime MUST call Phase A's real output (cannot mock/stub).
-2. **Not parallelizable**: A and B cannot develop concurrently via contract/interface/type agreement.
-3. **Full barrier**: ALL of Phase A's tasks must complete before ANY of Phase B's tasks can start.
-
-If only 1-2 conditions are met → keep in the same Phase, use wave dependencies instead.
-
-**Phase sizing checklist (applied after decomposition, before presenting to user):**
-1. Count total phases. If > 2 → justify each split against the 3 hard-dependency conditions, merge if unjustified.
-2. Count estimated tasks per phase. Any phase < 5 tasks → merge into neighbor.
-3. Verify each phase has a meaningful deliverable boundary (not just "setup" or "cleanup").
-
-**Scope escalation:**
-- **Single project** (any size): 1-2 Phases. Use wave DAG for internal parallelism.
-- **Large scope** (monorepo with 2+ independently deployable services): Use **Milestones** to divide scope. Each Milestone follows the 1-2 Phase limit independently.
-
-**Progressive mode**:
-- Progressive layers (MVP → Usable → Refined) map to **Milestones**, not Phases.
-- Each Milestone contains 1-2 Phases following the minimum-phase principle.
-- MVP must be self-contained (no external dependencies)
-- Each feature in exactly ONE milestone (no overlap)
-
-**Direct mode**:
-- Topologically-sorted task sequence
-- Each task: title, type, scope, inputs, outputs, convergence, depends_on
-- parallel_group for truly independent tasks
-
-**Phase format** (both modes):
-```markdown
-### Phase {N}: {Title}
-- **Goal**: <what this phase achieves>
-- **Depends on**: <prerequisite phases or "Nothing">
-- **Requirements**: <REQ-IDs mapped from project.md Active requirements>
-- **Success Criteria** (what must be TRUE):
-  1. <observable behavior from user perspective>
-  2. <observable behavior from user perspective>
-```
-
-Phase numbering: integers (1, 2, 3) for planned work, decimals (2.1, 2.2) for inserted phases.
-Decimal phases count toward the total phase limit.
-Phase directories use `{NN}-{slug}` format (e.g., `01-auth`, `02-api`).
-
-**Requirements traceability**: Every Active requirement from project.md MUST appear in exactly one phase's Requirements field. If a requirement maps to no phase, surface it as a gap.
-
----
-
-## Step 4: Iterative Refinement
-
-**Objective**: Multi-round user feedback to refine roadmap.
-
-1. **Present Roadmap**
-   - Phase count, milestone structure, dependency graph
-   - Key success criteria per phase
-
-2. **Gather Feedback** (skip if `-y` or `config.gates.confirm_roadmap == false`)
-   - Options: Approve / Adjust Scope / Reorder / Split-Merge / Re-decompose
-   - Max 5 rounds
-
-3. **Process Feedback**
-   - **Approve**: Run minimum-phase checklist (Step 3 rules) before accepting. If violations found, auto-merge and inform user.
-   - **Adjust Scope**: Move features between milestones, modify criteria
-   - **Reorder**: Change phase sequencing
-   - **Split/Merge**: Break large phases or combine small ones (enforce min 5 tasks, max 2 phases)
-   - **Re-decompose**: Return to Step 3 with new strategy
-
-4. **Loop** until approved or max rounds reached
-
----
-
-## Step 5: Write Outputs
-
-1. **Write roadmap.md** to `.workflow/roadmap.md` using @templates/roadmap.md:
-   ```markdown
-   # Roadmap: {project_name}
-
-   ## Overview
-   <one paragraph describing the journey>
-
-   ## Phases
-   - [ ] **Phase 1: {Title}** - {one-line description}
-   - [ ] **Phase 2: {Title}** - {one-line description}
-
-   ## Phase Details
-
-   ### Phase 1: {Title}
-   **Goal**: {what this phase delivers}
-   **Depends on**: Nothing (first phase)
-   **Requirements**: {REQ-IDs from project.md Active requirements}
-   **Success Criteria** (what must be TRUE):
-     1. {observable behavior from user perspective}
-     2. {observable behavior from user perspective}
-
-   ### Phase 2: {Title}
-   **Goal**: {what this phase delivers}
-   **Depends on**: Phase 1
-   **Requirements**: {REQ-IDs}
-   **Success Criteria** (what must be TRUE):
-     1. {observable behavior}
-
-   ## Scope Decisions
-   - In scope: <included>
-   - Deferred: <later milestones>
-   - Out of scope: <excluded>
-
-   ## Progress
-   | Phase | Status | Completed |
-   |-------|--------|-----------|
-   | 1. {Title} | Not started | - |
-   ```
-
-   **Requirements traceability**: Cross-check that every Active requirement from project.md maps to exactly one phase. Surface unmapped requirements as gaps.
-
-2. **Ensure scratch directory**: `mkdir -p .workflow/scratch/`
-
-3. **Update state.json** (if exists): set milestones from roadmap, set `current_milestone` to first milestone
-
----
-
-## Step 6: Handoff
-
-Display summary and offer next steps:
-
-Display summary (strategy, phase count, milestones, roadmap path) and offer next steps:
-- `maestro-init` — set up project (if not yet initialized)
-- `maestro-plan 1` — plan first phase
-- `maestro-brainstorm 1` — explore first phase ideas
-- `manage-status` — view project dashboard
-
----
-
-## Mode: Revise (`--revise [instructions]`)
-
-Revise an existing roadmap while preserving completed phase progress.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-- `.workflow/state.json` exists (for progress tracking)
-
-**Execution flow:**
-
-1. **Load current state**
-   - Read `.workflow/roadmap.md` — parse milestones, phases, dependencies, progress markers
-   - Read `.workflow/state.json` — get artifact registry, current milestone
-   - Identify completed vs in-progress vs pending phases
-
-2. **Obtain revision instructions**
-   - If `--revise "instructions text"` provided → use directly as change directive
-   - If `--revise` without instructions → use AskUserQuestion to ask user what to change
-     - Show current roadmap summary with phase statuses
-     - Present options: add/remove/reorder phases, modify scope/criteria/deps, move between milestones
-     - Capture change instructions from response
-
-3. **Impact analysis**
-   - For each proposed change, assess impact on:
-     - Phase dependency chain (re-validate no circular deps)
-     - Requirement coverage (every Active requirement still mapped)
-     - Completed phases (warn if change invalidates completed work)
-     - Existing plan artifacts (warn if plan exists for affected phase)
-   - Present impact summary for confirmation
-
-4. **Apply revisions**
-   - Update `.workflow/roadmap.md` preserving:
-     - Completed phase progress markers (checkmarks, completion dates)
-     - Phase numbering for completed phases (renumber only pending phases)
-     - Cross-references from state.json artifacts
-   - Update `state.json` if milestone structure changed
-   - Add revision log entry to roadmap.md metadata section
-
-5. **Post-revision validation**
-   - Re-check dependency integrity (no circular deps)
-   - Re-check requirement coverage (every Active req mapped)
-   - Verify completed phases unaffected
-
-**Next-step routing on completion:**
-- Phases changed, need re-analysis → `/maestro-analyze {phase}`
-- Phases changed, ready to plan → `/maestro-plan {phase}`
-- Only pending phases adjusted → `/maestro-plan` (continue from where left off)
-
----
-
-## Mode: Review (`--review`)
-
-Read-only health assessment of the current roadmap.
-
-**Pre-conditions:**
-- `.workflow/roadmap.md` exists
-
-**Execution flow:**
-
-1. **Load roadmap + execution history**
-   - Read `.workflow/roadmap.md` — full structure
-   - Read `.workflow/state.json` — artifact registry, milestone progress
-   - Cross-reference: for each phase, check ANL/PLN/EXC/VRF artifact status
-
-2. **Assessment dimensions**
-   - **Progress tracking**: Actual vs planned per phase, milestone velocity
-   - **Drift detection**: Completed phases deviating from original scope (via verify/audit findings)
-   - **Relevance check**: Pending phases still aligned with current project goals (from project.md)
-   - **Dependency health**: Pending phase dependencies still valid given completed work
-   - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
-
-3. **Produce review report**
-   - Write to `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
-   - Format:
-     ```
-     === ROADMAP REVIEW ===
-     Milestone: {current}
-     Progress: {completed}/{total} phases ({percentage}%)
-     Drift: {none|minor|significant} | Risk: {low|medium|high}
-
-     Phase Assessment:
-       [done] Phase 1: {name} — completed, on-scope
-       [~]    Phase 2: {name} — in-progress, {notes}
-       [ ]    Phase 3: {name} — pending, {risk/notes}
-
-     Suggested: /maestro-roadmap --revise | /maestro-plan {phase} | /manage-status
-     ```
-
-**No state modifications.** Pure assessment + recommendations.
+# Workflow: Roadmap (Light Mode)
+
+Lightweight path from requirements to roadmap without full specification documents.
+
+**Shared logic**: `@roadmap-common.md` (worktree guard, context loading, codebase exploration, external research, minimum-phase principle, roadmap write logic)
+
+---
+
+## Step 1: Session Initialization
+
+Parse flags from `$ARGUMENTS`:
+- `--yes` / `-y` → auto mode
+- `--continue` / `-c` → resume from last state
+- `--mode` / `-m` → `progressive|direct|auto` (default: auto)
+- `--from-brainstorm <SESSION-ID>` → import brainstorm session
+- Remaining text → requirement (slugified for directory name)
+
+**Session directory**: `.workflow/.roadmap/RMAP-{slug}-{date}/`
+
+**Continue mode**: If `-c` and session exists, resume from last state.
+
+**Brainstorm import**: If `--from-brainstorm`, read `guidance-specification.md` for enriched context (problem statement, features, non-goals, terminology).
+
+---
+
+## Step 2: Requirement Understanding & Strategy
+
+**Objective**: Parse requirement, assess uncertainty, select decomposition strategy.
+
+1. **Parse Requirement**
+   - Extract: goal, constraints, stakeholders, keywords
+   - If `--from-brainstorm`: enrich from guidance-specification.md
+   - If `project_context` loaded: merge into requirement analysis
+     - Cross-reference requirement against `already_shipped` — flag overlaps as "already done"
+     - Promote `deferred_from_previous` items into active requirement scope
+     - Apply `locked_decisions` as constraints
+
+2. **Codebase Exploration** — follow roadmap-common.md
+
+3. **External Research** — follow roadmap-common.md
+
+   `apiResearchContext` is passed into:
+   - Step 3 (Decomposition): technology complexity informs phase sizing and ordering
+   - Step 4 (Refinement): API constraints surface realistic dependency chains
+
+4. **Assess Uncertainty**
+   - Factors: scope_clarity, technical_risk, dependency_unknown, domain_familiarity, requirement_stability (each: low/medium/high)
+   - >=3 high → progressive, >=3 low → direct, else → ask
+
+5. **Strategy Selection** (skip if `-m` specified or `-y`)
+   - Present uncertainty assessment
+   - User selects: Progressive or Direct
+   - `-y`: use recommended strategy
+
+---
+
+## Step 3: Decomposition
+
+**Objective**: Break requirement into phases via CLI-assisted analysis.
+
+Spawn `cli-roadmap-plan-agent`.
+If `apiResearchContext` is set: include as "External API Research" context in the agent prompt.
+
+Apply **Minimum-Phase Principle** from roadmap-common.md.
+
+---
+
+## Step 4: Iterative Refinement
+
+**Objective**: Multi-round user feedback to refine roadmap.
+
+1. **Present Roadmap** — phase count, milestone structure, dependency graph, key success criteria
+2. **Gather Feedback** (skip if `-y` or `config.gates.confirm_roadmap == false`)
+   - Options: Approve / Adjust Scope / Reorder / Split-Merge / Re-decompose
+   - Max 5 rounds
+3. **Process Feedback**
+   - **Approve**: Run minimum-phase checklist before accepting. If violations found, auto-merge and inform user.
+   - **Adjust Scope**: Move features between milestones, modify criteria
+   - **Reorder**: Change phase sequencing
+   - **Split/Merge**: Break large phases or combine small ones (enforce min 5 tasks, max 2 phases)
+   - **Re-decompose**: Return to Step 3 with new strategy
+4. **Loop** until approved or max rounds reached
+
+---
+
+## Step 5: Write Outputs
+
+Follow roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state.json update, scratch directory).
+
+---
+
+## Step 6: Handoff
+
+Display summary (strategy, phase count, milestones, roadmap path) and offer next steps:
+- `maestro-init` — set up project (if not yet initialized)
+- `maestro-plan 1` — plan first phase
+- `maestro-brainstorm 1` — explore first phase ideas
+- `manage-status` — view project dashboard
+
+---
+
+## Mode: Revise (`--revise [instructions]`)
+
+Revise an existing roadmap while preserving completed phase progress.
+
+**Pre-conditions:**
+- `.workflow/roadmap.md` exists
+- `.workflow/state.json` exists (for progress tracking)
+
+**Execution flow:**
+
+1. **Load current state**
+   - Read `.workflow/roadmap.md` — parse milestones, phases, dependencies, progress markers
+   - Read `.workflow/state.json` — get artifact registry, current milestone
+   - Identify completed vs in-progress vs pending phases
+
+2. **Obtain revision instructions**
+   - If `--revise "instructions text"` provided → use directly as change directive
+   - If `--revise` without instructions → use AskUserQuestion to ask user what to change
+     - Show current roadmap summary with phase statuses
+     - Present options: add/remove/reorder phases, modify scope/criteria/deps, move between milestones
+     - Capture change instructions from response
+
+3. **Impact analysis**
+   - For each proposed change, assess impact on:
+     - Phase dependency chain (re-validate no circular deps)
+     - Requirement coverage (every Active requirement still mapped)
+     - Completed phases (warn if change invalidates completed work)
+     - Existing plan artifacts (warn if plan exists for affected phase)
+   - Present impact summary for confirmation
+
+4. **Apply revisions**
+   - Update `.workflow/roadmap.md` preserving:
+     - Completed phase progress markers (checkmarks, completion dates)
+     - Phase numbering for completed phases (renumber only pending phases)
+     - Cross-references from state.json artifacts
+   - Update `state.json` if milestone structure changed
+   - Add revision log entry to roadmap.md metadata section
+
+5. **Post-revision validation**
+   - Re-check dependency integrity (no circular deps)
+   - Re-check requirement coverage (every Active req mapped)
+   - Verify completed phases unaffected
+
+**Next-step routing on completion:**
+- Phases changed, need re-analysis → `/maestro-analyze {phase}`
+- Phases changed, ready to plan → `/maestro-plan {phase}`
+- Only pending phases adjusted → `/maestro-plan` (continue from where left off)
+
+---
+
+## Mode: Review (`--review`)
+
+Read-only health assessment of the current roadmap.
+
+**Pre-conditions:**
+- `.workflow/roadmap.md` exists
+
+**Execution flow:**
+
+1. **Load roadmap + execution history**
+   - Read `.workflow/roadmap.md` — full structure
+   - Read `.workflow/state.json` — artifact registry, milestone progress
+   - Cross-reference: for each phase, check ANL/PLN/EXC/VRF artifact status
+
+2. **Assessment dimensions**
+   - **Progress tracking**: Actual vs planned per phase, milestone velocity
+   - **Drift detection**: Completed phases deviating from original scope (via verify/audit findings)
+   - **Relevance check**: Pending phases still aligned with current project goals (from project.md)
+   - **Dependency health**: Pending phase dependencies still valid given completed work
+   - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
+
+3. **Produce review report**
+   - Write to `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
+   - Format:
+     ```
+     === ROADMAP REVIEW ===
+     Milestone: {current}
+     Progress: {completed}/{total} phases ({percentage}%)
+     Drift: {none|minor|significant} | Risk: {low|medium|high}
+
+     Phase Assessment:
+       [done] Phase 1: {name} — completed, on-scope
+       [~]    Phase 2: {name} — in-progress, {notes}
+       [ ]    Phase 3: {name} — pending, {risk/notes}
+
+     Suggested: /maestro-roadmap --revise | /maestro-plan {phase} | /manage-status
+     ```
+
+**No state modifications.** Pure assessment + recommendations.