maestro-flow 0.5.3 → 0.5.31

package/workflows/roadmap.md

@@ -1,8 +1,6 @@
 # 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)
+Lightweight requirements-to-roadmap path. Shared logic: `@roadmap-common.md`.
 
 ---
 
@@ -19,31 +17,15 @@ Parse flags from `$ARGUMENTS`:
 
 **Continue mode**: If `-c` and session exists, resume from last state.
 
-**Context import**: If `--from`, resolve source to `context-package.json`:
-  - `brainstorm:ID` → `state.json.artifacts[type=brainstorm, id=ID].context_package` → load
-  - `@file` → create import session → delegate extraction → load context-package.json
-  - `path/` → load `path/context-package.json` (generate if missing)
-  - `--from-brainstorm SESSION-ID` → alias for `--from brainstorm:{resolve(SESSION-ID)}`
+**Context import**: `--from` resolves to `context-package.json` (`brainstorm:ID` / `@file` / `path/` / `--from-brainstorm` alias).
 
 ---
 
 ## Step 2: Requirement Understanding & Strategy
 
-**Objective**: Parse requirement, assess uncertainty, select decomposition strategy.
-
-1. **Parse Requirement**
-   - Extract: goal, constraints, stakeholders, keywords
-   - If `--from`: enrich from context-package.json
-     - `requirements[]` → feature list for decomposition input
-     - `constraints[locked]` → immutable constraints for phase planning
-     - `domain` → problem statement, terminology, audience context
-     - `non_goals[]` → explicit exclusions from scope
-     - `insights[]` → role analysis insights (data models, architecture decisions)
-     - `open_questions[]` → items needing further investigation
-   - 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
+1. **Parse Requirement** — Extract goal, constraints, stakeholders, keywords
+   - `--from`: enrich from context-package (`requirements`, `constraints[locked]`, `domain`, `non_goals`, `insights`, `open_questions`)
+   - `project_context`: cross-reference `already_shipped`, promote `deferred` items, apply `locked_decisions`
 
 2. **Codebase Exploration** — follow roadmap-common.md
 
@@ -53,43 +35,24 @@ Parse flags from `$ARGUMENTS`:
    - 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
+4. **Assess Uncertainty** — 5 factors (scope_clarity, technical_risk, dependency_unknown, domain_familiarity, requirement_stability). >=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
+5. **Strategy Selection** (skip if `-m` or `-y`) — Present assessment, user selects Progressive or Direct
 
 ---
 
 ## 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.
+Spawn `cli-roadmap-plan-agent` (include `apiResearchContext` if set). 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
+1. **Present Roadmap**
+2. **Gather Feedback** (skip if `-y`): Approve / Adjust Scope / Reorder / Split-Merge / Re-decompose. Max 5 rounds.
+3. **Process**: Approve (run minimum-phase checklist first) | Adjust | Reorder | Split/Merge (min 5 tasks, max 2 phases) | Re-decompose (→ Step 3)
+4. **Loop** until approved or max rounds
 
 ---
 
@@ -101,100 +64,40 @@ Follow roadmap-common.md **Roadmap Write Logic** (overwrite vs edit rules, state
 
 ## Step 6: Handoff
 
-Display summary (strategy, phase count, milestones, roadmap path) and offer next steps:
-- `maestro-blueprint` — generate formal spec package for the roadmap (if heavier spec is needed)
-- `maestro-plan 1` — plan first phase
-- `maestro-brainstorm 1` — explore first phase ideas
-- `manage-status` — view project dashboard
+Display summary and next steps: `maestro-blueprint` | `maestro-plan 1` | `maestro-brainstorm 1` | `manage-status`
 
 ---
 
 ## 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)
+1. **Load state** — roadmap.md + state.json, identify completed/in-progress/pending
+2. **Get instructions** — from flag text or AskUserQuestion
+3. **Impact analysis** — dependency chain, requirement coverage, completed phases, existing plans. Confirm.
+4. **Apply** — preserve completed phase markers/numbering, update state.json if milestone changed
+5. **Validate** — no circular deps, requirement coverage intact, completed phases unaffected
+
+Next: `/maestro-analyze {phase}` | `/maestro-plan {phase}` | `/maestro-plan`
 
 ---
 
 ## 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)
+Read-only health assessment. No state modifications.
 
-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}
+1. **Load** — roadmap.md + state.json, cross-reference artifact statuses
+2. **Assess** — progress tracking, drift detection, relevance, dependency health, risk
+3. **Report** → `.workflow/scratch/{YYYYMMDD}-roadmap-review.md`
 
-     Phase Assessment:
-       [done] Phase 1: {name} — completed, on-scope
-       [~]    Phase 2: {name} — in-progress, {notes}
-       [ ]    Phase 3: {name} — pending, {risk/notes}
+```
+=== ROADMAP REVIEW ===
+Milestone: {current}
+Progress: {completed}/{total} phases ({percentage}%)
+Drift: {none|minor|significant} | Risk: {low|medium|high}
 
-     Suggested: /maestro-roadmap --revise | /maestro-plan {phase} | /manage-status
-     ```
+Phase Assessment:
+  [done] Phase 1: {name} — completed, on-scope
+  [~]    Phase 2: {name} — in-progress, {notes}
+  [ ]    Phase 3: {name} — pending, {risk/notes}
 
-**No state modifications.** Pure assessment + recommendations.
+Suggested: /maestro-roadmap --revise | /maestro-plan {phase} | /manage-status
+```