maestro-flow-one 0.2.17 → 0.2.19

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,24 @@ $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" 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`

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,68 @@ 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. The user controls termination — keep interviewing until convergence; they can interrupt naturally or via `Other` at any time.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
+- 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 explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
+`| # | 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 +99,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/manage/harvest.md

@@ -47,6 +47,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 1. **Read-only until Stage 6** — extraction and classification happen in-memory.
 2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
 3. **Never modify source artifacts** — harvest is purely extractive.
+4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 

package/maestro-flow/commands/manage/issue-discover.md

@@ -46,7 +46,7 @@ $ARGUMENTS -- optional. Parse first token to determine mode.
 - `--depth=standard|deep` -- exploration depth (by-prompt only, default: `standard`)
 
 **State files:**
-- `.workflow/issues/issues.jsonl` -- issues appended here
+- `.workflow/issues/issues.jsonl` -- issues appended here (set `source: "discover"` on each row so concurrent writers like `manage-harvest` with `source: "harvest"` can be distinguished and deduplicated)
 - `.workflow/issues/discoveries/{SESSION_ID}/` -- session artifacts
 
 ### Pre-load specs

package/maestro-flow/commands/manage/knowhow.md

@@ -53,7 +53,7 @@ Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
 | E002 | error | Entry ID or filename not found | execute_view, execute_delete |
 | E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |

package/maestro-flow/commands/manage/learn.md

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
+- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
@@ -47,19 +47,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `specs/learnings.md` | show |
+| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
+- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/knowhow/`
+- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </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/milestone/release.md

@@ -44,7 +44,7 @@ $ARGUMENTS -- optional explicit version string and flags.
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/release.md' completely.
+Follow '~/.maestro/workflows/milestone-release.md' completely.
 
 **High-level flow:**
 1. Validate preconditions (milestone completed, clean tree, audit PASS)

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)
@@ -40,13 +40,13 @@ Phase or task: $ARGUMENTS (required — phase number)
 
 **Intelligent routing** (auto-detected from project state):
 
-| Priority | Condition | Route | Equivalent to |
-|----------|-----------|-------|---------------|
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
 | 1 | Active session exists (state.json status=running) | Resume | — |
 | 2 | --re-run flag + previous failures | Re-run | — |
-| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test |
-| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen |
-| 5 | Default | code | quality-integration-test |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
 
 Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
 

package/maestro-flow/commands/quality/refactor.md

@@ -46,7 +46,7 @@ After successful refactoring, ask user once: "Record refactoring pattern as codi
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug {scope}`
+- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
 - No test suite available → `/quality-auto-test {phase}`
 </execution>
 

package/maestro-flow/commands/quality/retrospective.md

@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,7 +70,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
 - [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library

package/maestro-flow/commands/spec/remove.md

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id>"
+argument-hint: "<entry-id> [--cascade]"
 allowed-tools:
   - Read
   - Write
@@ -26,6 +26,9 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 **Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
 
 **Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
 </context>
 
 <execution>
@@ -47,5 +50,6 @@ Follow '~/.maestro/workflows/specs-remove.md' completely.
 - [ ] User confirmed removal (unless -y flag)
 - [ ] Entry removed from container file via `maestro wiki remove-entry`
 - [ ] Wiki index auto-updated
-- [ ] Confirmation displayed with removed entry details
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "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"