maestro-flow-one 0.2.17 → 0.2.18

package/maestro-flow/commands/lifecycle/brainstorm.md

@@ -1,116 +1,132 @@
----
-name: maestro-brainstorm
-description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/brainstorm.md
-</required_reading>
-
-<deferred_reading>
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
-- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
-
-**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
-**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
-**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
-**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
-2. Optional — proceed without if unavailable.
-
-### Role Knowledge
-1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
-2. Analyze the index, identify entries relevant to the current task
-3. Load selected documents:
-   `maestro wiki load <id1> [id2] [id3...]`
-4. Review loaded knowledge before proceeding
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-roadmap", args: "--mode full --from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
-- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
-| E002 | error | No active session for single role mode | Guide user to run auto mode first |
-| E003 | error | Invalid role name | Show valid roles list |
-| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
-| W002 | warning | Project context (.workflow/) not found | Continue without project context |
-| W003 | warning | Role template not found | Use generic analysis structure |
-| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
-| W005 | warning | External research agent failed | Continue without designResearchContext |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] design-research.md persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
-- [ ] Spec Review Gate passed (Step 3.5) or `--yes` bypassed
-- [ ] Role analysis files for each selected NON-UI role in `.brainstorming/{role}/`
-- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
-- [ ] If `ui-designer` in selected_roles: `ui-designer/analysis.md` exists with UX analysis (interaction flows, state design, information architecture)
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] UI-bearing feature specs reference DESIGN.md for visual constraints in Section 3 (Interface Contract)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] Final Output Gate passed (Step 5.5) or `--yes` bypassed
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-- [ ] Confidence scored per role completion and after cross-role analysis
-- [ ] Readiness gate checked before spec generation
-- [ ] Pressure pass completed on at least 1 feature spec
-- [ ] Confidence summary appended to synthesis-changelog.md
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+- [brainstorm-visualize.md](~/.maestro/workflows/brainstorm-visualize.md) — read when html-prototypes/ produced and user wants to browse them
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`.
+**Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
+**Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
+**Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for multi-role analysis — ensures roles respect documented decisions.
+2. Optional — proceed without if unavailable.
+
+### Role Knowledge
+1. Browse accumulated knowledge for this role:
+   `maestro wiki list --category arch`
+2. Analyze the index, identify entries relevant to the current task
+3. Load selected documents:
+   `maestro wiki load <id1> [id2] [id3...]`
+4. Review loaded knowledge before proceeding
+</context>
+
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `--yes/-y`, `--skip-questions`, `--session` (existing session), or input is already specific.
+
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
+- Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
+
+Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
+
+Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need formal spec package → Skill({ skill: "maestro-blueprint", args: "--from brainstorm:{artifact_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from brainstorm:{artifact_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic} --from brainstorm:{artifact_id}" })
+- `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
+- DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| E006 | error | `--review-only` but no `{role}/analysis.md` found | Run auto or single-role mode first |
+| E007 | error | `--review-only` but `guidance-specification.md` missing | Run auto mode to generate guidance first |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+| W006 | warning | Reviewer patch_targets heading drift (no match) | Skip that patch; report in final summary |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] Interactive mode: interview decision table written to `guidance-specification.md` §11 and session metadata
+- [ ] `guidance-specification.md` with RFC 2119 keywords, terminology, non-goals, feature decomposition (§10), decision tracking (§11), cross-role resolutions placeholder (§12)
+- [ ] `design-research.md` persisted when Step 1.7 external research ran (fail-soft: absence not a failure)
+- [ ] If `ui-designer` in selected_roles AND Step 3.5 ran: `.workflow/impeccable/DESIGN.md` exists (visual style established via impeccable explore)
+- [ ] `{role}/analysis.md` written for each selected role, containing §2 Decision Digest (4 tables) + §3 Cross-Cutting Foundations + §4 File Index
+- [ ] `{role}/analysis-F-{id}-{slug}.md` written per feature (one file per feature, < 2000 words)
+- [ ] `system-architect/analysis.md` §3 includes Data Model + State Machine when system-architect is selected
+- [ ] `ui-designer/analysis.md` references DESIGN.md visual constraints when ui-designer is selected
+- [ ] Each `{role}/analysis.md` §2 Decisions table has ≥ 1 row per feature
+- [ ] Cross-role review (Step 4.5) executed; reviewer compares §2 Decision Digests; output includes `patch_targets[]` for every finding
+- [ ] If findings exist: each accepted resolution applied via Edit (annotate / strikeout / append) AND logged in `guidance-specification.md` §12 "Cross-Role Resolutions"
+- [ ] If zero findings: final report explicitly states "No cross-role issues detected"; guidance §12 unchanged
+- [ ] Heading-drift patch failures surfaced in final report (if any)
+- [ ] Session metadata updated with completion status (review_findings_count, resolutions_applied, patches_skipped)
+
+**Single role mode**:
+- [ ] `{role}/analysis.md` written with §2 Decision Digest + §4 File Index
+- [ ] `{role}/analysis-F-*.md` written when guidance §10 feature list available
+- [ ] §2 Decisions table references guidance decision IDs
+- [ ] Session metadata updated
+</success_criteria>

package/maestro-flow/commands/lifecycle/init.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-init
 description: Initialize project with auto state detection
-argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+argument-hint: "[-y] [--from <source>]"
 allowed-tools:
   - Read
   - Write
@@ -25,7 +25,7 @@ Initialize a new project through auto state detection and unified flow. Invoked
 <context>
 **Flags:**
 - `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+- `--from <source>` -- Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm`
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
@@ -63,7 +63,7 @@ Other commands:
 |------|----------|-----------|----------|
 | E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
 | E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| E003 | error | Context source not found (--from / --from-brainstorm) | Check arguments format, re-run with correct input |
 | W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
 </error_codes>
 

package/maestro-flow/commands/lifecycle/plan.md

@@ -1,7 +1,7 @@
 ---
 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>] [--revise [instructions]] [--check <plan-dir>]"
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - Read
   - Write
@@ -39,12 +39,22 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 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:**
-- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
-- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+**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" 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".
 
 ### Role Knowledge
 `maestro wiki list --category arch` → select relevant → `maestro wiki load`

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
-description: Generate roadmap from requirements (light or full mode)
-argument-hint: "<requirement> [--mode light|full] [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
+description: Generate roadmap with milestone/phase structure from requirements or upstream context
+argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from <source>] [--revise [instructions]] [--review]"
 allowed-tools:
   - Read
   - Write
@@ -13,16 +13,14 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Unified roadmap generation with two execution paths:
+Generate a milestone/phase roadmap from requirements or upstream context. Produces `.workflow/roadmap.md` with Milestone > Phase hierarchy ready for maestro-analyze and maestro-plan.
 
-- **Light mode** (default): Directly from requirements to roadmap. No specification documents.
-- **Full mode** (`--mode full`): 7-phase document chain (Product Brief → PRD → Architecture → Epics → Roadmap) producing a complete specification package in `.workflow/.spec/` plus `.workflow/roadmap.md`.
-
-Additional operation modes (light mode only):
+Operation modes:
+- **Create** (default): Build roadmap from requirements or upstream context
 - **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
 - **Review** (`--review`): Health assessment of current roadmap (read-only)
 
-Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
+For formal specification documents (Product Brief, PRD, Architecture, Epics), use `/maestro-blueprint` instead.
 </purpose>
 
 <required_reading>
@@ -31,73 +29,67 @@ Both modes produce `.workflow/roadmap.md` with milestone/phase structure ready f
 </required_reading>
 
 <deferred_reading>
-- [roadmap.md](~/.maestro/workflows/roadmap.md) — read when mode is light (default)
-- [spec-generate.md](~/.maestro/workflows/spec-generate.md) — read when mode is full
-- [spec-config.json](~/.maestro/templates/spec-config.json) — read when initializing spec configuration (full mode)
+- [roadmap.md](~/.maestro/workflows/roadmap.md) — read for roadmap generation workflow
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- requirement text, @file reference, or brainstorm session reference.
+$ARGUMENTS -- requirement text, @file reference, or upstream context source.
 
-**Flags (shared):**
-- `--mode light|full`: Execution path (default: light)
+**Flags:**
 - `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
 - `-c` / `--continue`: Resume from last checkpoint
-- `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
-
-**Flags (light mode only):**
 - `-m progressive|direct|auto`: Decomposition strategy (default: 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`
-- Brainstorm import: `--from-brainstorm WFS-xxx`
+- 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`
 
 **Pipeline position:**
 ```
-maestro-brainstorm (optional upstream)
-        ↓ guidance-specification.md
-maestro-init (project setup)
-        ↓ project.md, state.json, config.json
-maestro-roadmap [--mode light]     → roadmap.md directly
-maestro-roadmap --mode full        → spec package + roadmap.md
+maestro-brainstorm ─┐
+maestro-blueprint  ─┤ (optional upstream, parallel)
+maestro-analyze    ─┘ context-package.json
+        ↓
+maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
         ↓
-maestro-plan → maestro-execute → maestro-verify
+maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 ```
 
-**Note (full mode):** `maestro-init` MUST run before `--mode full`. It creates the `.workflow/` directory and project context.
-
 ### Pre-load specs
 1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
 2. Optional — proceed without if unavailable.
 </context>
 
-<execution>
+<interview_protocol>
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
 
-### Mode routing
+- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option.
+- Never ask what code can verify — resolve via `state.json`, existing `roadmap.md`, `project.md`, or `maestro spec load`.
+- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
+- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
 
-1. Read `@~/.maestro/workflows/roadmap-common.md` (always — shared logic)
-2. Parse `--mode` flag:
-   - `light` or omitted → read `@~/.maestro/workflows/roadmap.md`, follow its process
-   - `full` → read `@~/.maestro/workflows/spec-generate.md`, follow its process
-3. If `--revise` or `--review` present → force light mode (these are light-mode-only operations)
+Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
 
-### Light mode (default)
+Exit: on consensus or `Proceed now`, append the table below to a `Roadmap Decisions` section at the top of `.workflow/roadmap.md`:
+`| # | Decision | Choice | Source (user / code / default) |`
+</interview_protocol>
 
-Follow `~/.maestro/workflows/roadmap.md` completely.
+<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
+- **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
 
-### Full mode (`--mode full`)
-
-Follow `~/.maestro/workflows/spec-generate.md` completely.
-
 ### Next-step routing on completion
 
 | Condition | Suggestion |
@@ -106,63 +98,32 @@ Follow `~/.maestro/workflows/spec-generate.md` completely.
 | Simple project, ready to plan | /maestro-plan 1 |
 | Need UI design first | /maestro-impeccable build |
 | View project dashboard | /manage-status |
-| Need project setup (full mode) | /maestro-init |
+| Need formal spec documents | /maestro-blueprint |
 </execution>
 
 <error_codes>
-
-**Shared:**
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Requirement/idea text or @file required | Prompt user for input |
-| E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
-| W001 | warning | CLI analysis failed, using fallback | Continue with available data |
-| W005 | warning | External research agent failed | Continue without apiResearchContext |
-
-**Light mode:**
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
+| 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 |
 | W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
-
-**Full mode:**
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E006 | error | `.workflow/` not initialized | Run maestro-init first |
-| E007 | error | Phase 6 readiness Fail after 2 auto-fix iterations | Present manual fix options |
-| W002 | warning | Codebase exploration failed | Continue without codebase context |
-| W003 | warning | Glossary has < 5 terms | Note in readiness check |
-| W004 | warning | Review-level readiness score (60-79%) | Proceed with caveats |
+| W005 | warning | External research agent failed | Continue without apiResearchContext |
 </error_codes>
 
 <success_criteria>
-
-**Light mode:**
+- [ ] Interactive mode: interview decision table appended to `.workflow/roadmap.md` "Roadmap Decisions" section
 - [ ] Requirement parsed with goal, constraints, stakeholders
+- [ ] Milestones defined with deliverable targets and version tags
 - [ ] Decomposition strategy selected (progressive or direct)
-- [ ] Phases defined with success criteria, dependencies, and requirement mappings
+- [ ] Phases defined within milestones with success criteria, dependencies, and requirement mappings
 - [ ] Every Active requirement from project.md mapped to exactly one phase
 - [ ] No circular dependencies in phase ordering
 - [ ] User approved roadmap (or auto-approved with -y)
-- [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
+- [ ] `.workflow/roadmap.md` written with Milestone > Phase hierarchy, scope decisions, and progress table
 - [ ] No phase directories created (phases are labels in roadmap, not directories)
-
-**Full mode (in addition to light mode criteria for roadmap):**
-- [ ] `spec-config.json` created with session metadata and phase tracking
-- [ ] `product-brief.md` with vision, goals, scope, multi-perspective synthesis
-- [ ] `glossary.json` with 5+ core terms for cross-document consistency
-- [ ] `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files
-- [ ] All requirements have RFC 2119 keywords and acceptance criteria
-- [ ] `architecture/` directory with `_index.md` + individual `ADR-*.md` files
-- [ ] Architecture includes state machine, config model, error handling, observability (service type)
-- [ ] `epics/` directory with `_index.md` + individual `EPIC-*.md` files
-- [ ] Cross-Epic dependency map (Mermaid) and MVP subset tagged
-- [ ] `readiness-report.md` with 4-dimension quality scores and traceability matrix
-- [ ] `spec-summary.md` with one-page executive summary
-- [ ] All documents have valid YAML frontmatter with session_id
-- [ ] Glossary terms used consistently across all documents
-- [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
-- [ ] `.workflow/roadmap.md` written
+- [ ] Artifact registered in state.json with milestone entries
 </success_criteria>

package/maestro-flow/commands/milestone/audit.md

@@ -34,8 +34,10 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 
 **Data source:**
 - `.workflow/state.json` — artifacts[], current_milestone, milestones[]
-- `.workflow/roadmap.md` — milestone-to-phase mapping
+- `.workflow/roadmap.md` — milestone-to-phase mapping (standard milestones only)
 - Plan scratch dirs — for task status verification
+
+**Adhoc milestone support (D-008):** When the target milestone has `type == "adhoc"` (or `type` field is missing, defaulting to `"standard"`), the audit skips roadmap.md parsing and phase coverage checks. It only validates artifact chain completeness (PLN→EXC exists) and runs integration checks.
 </context>
 
 <execution>
@@ -59,8 +61,8 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 </error_codes>
 
 <success_criteria>
-- [ ] All phases in milestone identified from roadmap
-- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] All phases in milestone identified from roadmap (standard) or milestone_obj.phases (adhoc)
+- [ ] Artifact chains verified: ANL→PLN→EXC per phase (standard) or PLN→EXC exists (adhoc)
 - [ ] Ad-hoc artifacts checked for completion
 - [ ] Integration check completed (shared interfaces, data contracts)
 - [ ] Audit report written with clear PASS/FAIL verdict

package/maestro-flow/commands/milestone/complete.md

@@ -26,8 +26,8 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 **Requires:** `/maestro-milestone-audit` should have passed.
 
 **State files:**
-- `.workflow/state.json` — artifacts[], milestones[], current_milestone, milestone_history[]
-- `.workflow/roadmap.md` — milestone structure
+- `.workflow/state.json` — artifacts[], milestones[] (with `type` field: `"standard"` | `"adhoc"`), current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure (standard milestones only; adhoc milestones may not have roadmap)
 - `.workflow/milestones/{milestone}/audit-report.md` — audit results
 </context>
 
@@ -52,8 +52,10 @@ If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category>
 
 **Next-step routing on completion:**
 - Cut a release → `/maestro-milestone-release`
-- Next milestone → `/maestro-analyze` or `/maestro-plan 1`
+- Next milestone → `/maestro-analyze` or `/maestro-plan 1` (standard milestones only)
 - View state → `/manage-status`
+
+**Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
 </execution>
 
 <error_codes>
@@ -69,7 +71,7 @@ If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category>
 - [ ] Scratch artifacts moved to milestones/{M}/artifacts/
 - [ ] Artifact entries archived to milestone_history
 - [ ] Knowhow extracted to specs/learnings.md
-- [ ] state.json updated: next milestone as current, artifacts[] cleared
-- [ ] Roadmap snapshot saved
+- [ ] state.json updated: next milestone as current (standard) or current_milestone=null (adhoc), artifacts[] cleared
+- [ ] Roadmap snapshot saved (standard only; adhoc skips)
 - [ ] project.md Context updated with milestone summary
 </success_criteria>

package/maestro-flow/commands/quality/auto-test.md

@@ -15,7 +15,7 @@ allowed-tools:
 Run unified automated testing via CSV layer pipeline. Reads project state to auto-select the optimal scenario source — PRD specs (when spec package exists), coverage gaps (when Nyquist audit found gaps), or code exploration (default). All sources converge into a CSV pipeline: discover infrastructure → plan → build scenarios.csv → write tests per layer (spawn_agents_on_csv parallel) → execute → diagnose failures (spawn_agents_on_csv parallel) → iterate → report.
 
 Key mechanisms:
-- **Intelligent routing**: Reads `.tests/`, `.workflow/.spec/`, `verification.json` to auto-select source — no mode flag needed
+- **Intelligent routing**: Reads `.tests/`, `.workflow/blueprint/`, `verification.json` to auto-select source — no mode flag needed
 - **CSV parallel test writing**: Per-layer `spawn_agents_on_csv` — each agent writes one test file independently
 - **CSV parallel failure diagnosis**: Failed scenarios dispatched via `spawn_agents_on_csv` for classification + fix
 - **Unified iteration engine**: Nested inner loop (fix test_defects via diagnosis CSV, max 3/layer) + outer loop (adaptive strategy, max N iterations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"