maestro-flow 0.4.10 → 0.4.12

package/.claude/commands/maestro-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/.claude/commands/maestro.md

@@ -49,8 +49,13 @@ $ARGUMENTS — user intent text, or special keywords.
 1. **All chains dispatch via maestro-ralph-execute** — maestro never executes steps directly
 2. **Session before execution** — status.json created before any step runs
 3. **Auto flags only to supporting commands** — unlisted commands execute as-is
-4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`, `goal_checklist_path`) + `goal-checklist.md`, then EMIT the `/goal` bind prompt. Reference maestro-ralph `A_DECOMPOSE_TASKS` for the full spec; do not duplicate logic
-5. **Status JSON: schema-additive + step-dynamic** — decomposition fields OPTIONAL (absent → old flat-chain behavior); `steps[]` is a living array grown at runtime by ralph-execute's `post-goal-audit`. Never remove/rename existing fields
+4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
+5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
+6. **Default step type = internal** — chain 内每个 step 解析 `command_scope`/`command_path`（全局优先 `~/.claude/commands/{name}.md`，fallback 项目）
+7. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro(text) / analyze(numeric phase) / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 路由由 ralph 在 `post-analyze-scope` 决定
+8. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查得出
+9. **每个 step 必须 `completion_confirmed: true`** — 基于 `--- COMPLETION STATUS ---` 的 `STATUS: DONE`
+10. **schema 向后兼容** — 新增字段全部可选；既有字段名不删不改
 </invariants>
 
 <state_machine>
@@ -127,9 +132,16 @@ S_FALLBACK:
 ### A_CLASSIFY_INTENT
 
 1. Read `~/.maestro/workflows/maestro.md` from deferred_reading
-2. Match intent to best task_type via chain catalog (semantic, AI-driven)
-3. Select chain from chainMap
-4. Determine per-step type: `internal` (Skill) or `external` (delegate)
+2. Match intent to task_type via chain catalog (semantic)
+3. Select chain from chainMap，遵循拓扑约束：
+   - 头脑风暴/探索 → `brainstorm`
+   - 正式规格/spec-generate/7-phase → `blueprint`
+   - 项目初始化 → `init`
+   - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
+   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
+4. 每个 step 默认 `type: "internal"`；解析 `command_scope` + `command_path`（全局优先 fallback 项目）；写入 `step.stage` / `step.scope` / `step.source_artifact_ref`（如 `--from` 注入时）
 
 ### A_CLARIFY
 
@@ -138,34 +150,52 @@ S_FALLBACK:
 
 ### A_DECOMPOSE_TASKS
 
-Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — **reference that spec; do not duplicate the table logic here.** Condensed:
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
-1. Classify intent breadth (broad: 重构/全面/重写/迁移/overhaul/migrate/rewrite; narrow: single file/function/bug). Skip entirely for narrow / single-step / {status,init,quick} chains
-2. Broad/medium → `AskUserQuestion` ≤3 rounds: Scope (in/out) | Constraints (compat/API/perf/test bar) | Definition of Done
-3. Derive `execution_criteria` (3-6 imperative rules) + `task_decomposition` (outcome sub-goals, each `done_when` objectively verifiable and mapped to a ralph evidence artifact: verification.json / review.json / uat.md / test path)
-4. Write `{session_dir}/goal-checklist.md` (same template as maestro-ralph) with `ALL_GOALS_DONE` sentinel; set `goal_checklist_path`
-5. Append a `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }` node as the FINAL node — after the last evidence-producing step (verify/review/test), before a milestone-complete/close-out step if the chain ends with one. (Audit needs evidence artifacts to exist.) ralph-execute then dynamically grows `steps[]` for unmet sub-goals
-6. **Emit the `/goal` bind prompt:**
+1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
+2. broad/medium → `AskUserQuestion` ≤3 轮：Scope / Constraints / Definition of Done
+3. 派生 `execution_criteria` + `task_decomposition`（每个 sub-goal 含 `done_when` + `evidence` + `lifecycle` + `completion_confirmed: false`）
+4. **status.json 唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition`；不生成 markdown 清单
+5. 在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
+6. **输出 `/goal` 绑定提示词：**
    ```
-   📋 任务分解完成。复制下面一行设定目标(推荐)：
-   /goal 当 {session_dir}/goal-checklist.md 中子目标全 [x] 且含 ALL_GOALS_DONE 时达成；否则按执行准则继续推进且不越边界契约
+   📋 任务分解完成。复制下面一行设定目标，会话在子目标全部达成前不停：
+
+   /goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
    ```
 
 ### A_CREATE_SESSION
 
-1. Read `.workflow/state.json` for project context (phase, milestone)
-2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+1. Read `.workflow/state.json` 获取 phase / milestone（含 D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`（如存在）；读最新 blueprint artifact 注入 `blueprint_id`
+2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）：
    ```json
-   { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
-     "phase", "milestone", "auto_mode", "exec_mode", "cli_tool",
-     "context": { ... }, "steps": [{ "index", "skill", "args", "type", "status": "pending", "goal_ref": null }],
+   {
+     "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "phase", "phase_is_new": false, "milestone": "",
+     "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
+     "auto_mode": false, "exec_mode": "auto", "cli_tool": "claude",
+     "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null,
+       "brainstorm_dir": null, "blueprint_dir": null, "issue_id": null },
+     "steps": [{
+       "index": 0, "type": "internal|external|decision",
+       "skill": "", "args": "",
+       "stage": "", "scope": null,
+       "command_scope": "global|project|missing|null",
+       "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+       "milestone_id": null, "source_artifact_ref": null,
+       "status": "pending", "goal_ref": null,
+       "completion_confirmed": false, "completion_status": null,
+       "completion_evidence": null, "completed_at": null
+     }],
      "waves": [], "current_step": 0, "status": "running",
-     "_comment": "↓ OPTIONAL additive block — present only if S_DECOMPOSE ran; absent → old flat-chain behavior",
-     "boundary_contract": {}, "execution_criteria": [], "task_decomposition": [], "goal_checklist_path": "" }
+     "boundary_contract": {}, "execution_criteria": [],
+     "task_decomposition": [], "task_decomposition_all_done": false
+   }
    ```
-   Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive; never break flat-chain readers)
-3. Initialize tracking via `TodoWrite`. The decomposition goal is bound by the user via the emitted `/goal` prompt
-4. If `--super`: read `maestro-super.md`, follow it completely
+   Decomposition 字段仅在 A_DECOMPOSE_TASKS 产出时写入（additive）
+3. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E005 列出缺失 skill
+4. Initialize tracking via `TodoWrite`
+5. If `--super`: read `maestro-super.md`, follow it completely
 
 </actions>
 
@@ -180,6 +210,7 @@ Shares the decomposition contract with maestro-ralph `A_DECOMPOSE_TASKS` — **r
 | maestro-init | `-y` | Skip interactive questioning |
 | maestro-analyze | `-y` | Skip scoping, auto-deepen |
 | maestro-brainstorm | `-y` | Skip questions, use defaults |
+| maestro-blueprint | `-y` | Skip interview, use recommended defaults |
 | maestro-roadmap | `-y` | Skip questions (create/revise/review) |
 | maestro-impeccable | `-y` | Auto-select design variant + skip confirmations |
 | maestro-plan | `-y` | Skip confirmations and clarification |
@@ -199,6 +230,7 @@ Unlisted commands have no auto flags.
 | E002 | error | Clarity too low after 2 rounds | Show parsed intent, ask rephrase |
 | E003 | error | Chain step failed + user abort | Record partial, suggest -c resume |
 | E004 | error | Resume session not found | Show available sessions |
+| E005 | error | command_scope == "missing" for one or more steps | List missing skills, abort build |
 | W001 | warning | Ambiguous intent, multiple chains | Present options |
 | W002 | warning | Step completed with warnings | Log and continue |
 | W003 | warning | State suggests different chain | Show discrepancy |
@@ -206,11 +238,15 @@ Unlisted commands have no auto flags.
 ### Success Criteria
 
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Broad lifecycle intents decomposed (S_DECOMPOSE, ≤3 boundary questions) sharing maestro-ralph contract; narrow/single-step skip
-- [ ] Decomposition writes additive block + goal-checklist.md + post-goal-audit node; emits /goal bind prompt (no self-call, no phantom create_goal)
+- [ ] Chain catalog 覆盖 brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / quality pipeline
+- [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
+- [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）
+- [ ] plan 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径；`source_artifact_ref` 写入 step
+- [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
+- [ ] status.json 唯一真源；无 markdown 清单；post-goal-audit 节点在 decomposed 时追加；/goal 提示词以 status.json 为判据
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
-- [ ] Tracking via TodoWrite (Claude); status.json steps[] grown dynamically by ralph-execute post-goal-audit
+- [ ] 每个 step 含 `command_scope` + `command_path` + `completion_confirmed` 字段
 - [ ] Auto flags propagated to supporting commands only
 - [ ] All chains dispatched via maestro-ralph-execute
 - [ ] Low-complexity intents routed to maestro-quick

package/.claude/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/.claude/skills/maestro-help/SKILL.md

@@ -47,7 +47,7 @@ Single source of truth: **[index/catalog.json](index/catalog.json)**
 
 | Field | Purpose |
 |-------|---------|
-| `commands[]` | 55 个 slash 命令，含分类和描述 |
+| `commands[]` | 56 个 slash 命令，含分类和描述 |
 | `skills[]` | 10 个 Skill，含分类和描述 |
 | `agents[]` | 22 个 Agent，含分类和描述 |
 | `cli_commands[]` | 21 个终端命令 |
@@ -175,24 +175,25 @@ $ARGUMENTS → Parse:
 
 ## Command Catalog Quick Reference
 
-### 核心工作流 (core)
+### 上游起源 + 核心 (core)
 
 | 命令 | 用途 |
 |------|------|
 | `/maestro` | 智能协调器，自动路由 |
 | `/maestro-init` | 项目初始化 |
-| `/maestro-roadmap` | 路线图生成 |
+| `/maestro-brainstorm` | 头脑风暴 — 发散探索，多角色创意 |
+| `/maestro-blueprint` | 正式规格文档化 — 7-phase 收敛规格链 |
+| `/maestro-roadmap` | 路线图编排 — 消费上游 context，纯 Milestone > Phase 分解 |
 | `/maestro-quick` | 快速任务 |
-| `/maestro-brainstorm` | 头脑风暴 |
 | `/maestro-overlay` | Overlay 管理 |
 | `/maestro-amend` | 修正补丁 |
 
-### Phase 管线 (pipeline)
+### 理解层 + 执行管线 (pipeline)
 
 | 命令 | 用途 |
 |------|------|
-| `/maestro-analyze` | 多维分析 |
-| `/maestro-plan` | 任务规划 |
+| `/maestro-analyze` | 双层分析 — 宏观(文本参数)探索影响面 / 微观(数字参数)Phase 级深入 |
+| `/maestro-plan` | 任务规划 — 支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 任务执行 |
 | `/maestro-verify` | 验证确认 |
 
@@ -220,11 +221,44 @@ $ARGUMENTS → Parse:
 
 ## Workflow Mapping
 
-| 任务类型 | 推荐工作流 | 命令序列 |
-|---------|-----------|---------|
-| 新项目 | 初始化路径 | `/maestro-init` → `/maestro-roadmap` |
-| 正常开发 | 主干管线 | `/maestro-analyze` → `/maestro-plan` → `/maestro-execute` → `/maestro-verify` |
-| 快速修复 | 快速渠道 | `/maestro-quick "修复描述"` |
+### 层级模型
+
+```
+Roadmap > Milestone > Phase > Task
+```
+
+- **Roadmap** = 项目级常驻规划文档
+- **Milestone** = 可独立交付的版本节点（v0.1.0-rc1, v0.2.0）
+- **Phase** = Milestone 内的同步屏障执行阶段
+- **Task** = Phase 内的具体代码修改单元（wave DAG 管理并行）
+
+### 命令拓扑
+
+```
+上游起源层（并列，可选）
+  brainstorm（发散/轻量）  |  blueprint（收敛/重型）
+
+理解层
+  analyze 双层: 宏观(文本参数) → scope_verdict | 微观(数字参数) → Phase 级决策
+
+编排层（可选）
+  roadmap — 消费上游 context，纯 Milestone > Phase 分解
+
+执行层
+  plan → execute → verify
+```
+
+### 合法路径
+
+| 路径 | 场景 | 命令序列 |
+|------|------|---------|
+| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
+| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
+| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify` |
+| Path D | 小改动 | `plan "fix auth bug"` → `execute` → `verify` |
+| Path E | 纯规格文档 | `blueprint "project idea"` → (供人阅读) |
+| Path F | 纯探索 | `brainstorm "idea"` → (供人决策) |
+| 快速修复 | 已知简单问题 | `/maestro-quick "修复描述"` |
 | Bug 追踪 | Issue 闭环 | `/manage-issue-discover` → `/manage-issue create` → analyze/plan/execute → close |
 | 全自动 | /maestro 入口 | `/maestro -y "任务描述"` |
 | 代码审查 | 质量管线 | `/quality-review` → `/quality-auto-test` → `/quality-test` |
@@ -256,9 +290,9 @@ $ARGUMENTS → Parse:
 
 ## Statistics
 
-- **Slash 命令**: 55 个（7 个分类）
+- **Slash 命令**: 56 个（7 个分类）
 - **CLI 命令**: 21 个
 - **Skills**: 10 个（3 个分类）
 - **Agents**: 22 个（5 个分类）
 - **Guide 文档**: 17 个
-- **工作流**: 4 个主要模板
+- **工作流路径**: 6 个合法路径 (Path A-F) + 3 个辅助流程

package/.claude/skills/maestro-help/index/catalog.json

@@ -7,10 +7,11 @@
   "commands": [
     {"name": "maestro", "command": "/maestro", "category": "core", "description": "智能协调器 — 根据意图和项目状态自动选择最优命令链", "source": "../../commands/maestro.md"},
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
-    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图生成 — 基于目标创建里程碑和 Phase 分解", "source": "../../commands/maestro-roadmap.md"},
-    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "多角色头脑风暴 — 生成分析文档和功能规格", "source": "../../commands/maestro-brainstorm.md"},
-    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "多维度分析 — Phase 分析、CLI 辅助探索、gap 分析", "source": "../../commands/maestro-analyze.md"},
-    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 生成执行计划、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "头脑风暴 — 发散探索，多角色创意，上游起源命令", "source": "../../commands/maestro-brainstorm.md"},
+    {"name": "maestro-blueprint", "command": "/maestro-blueprint", "category": "core", "description": "正式规格文档化 — 7-phase 收敛规格链，上游起源命令，产出 .workflow/blueprint/", "source": "../../commands/maestro-blueprint.md"},
+    {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
+    {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
     {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
     {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
@@ -149,16 +150,33 @@
   "essential_commands": [
     "/maestro",
     "/maestro-init",
-    "/maestro-roadmap",
+    "/maestro-brainstorm",
+    "/maestro-blueprint",
     "/maestro-analyze",
+    "/maestro-roadmap",
     "/maestro-plan",
     "/maestro-execute",
     "/maestro-verify",
-    "/maestro-quick",
-    "/quality-review",
-    "/manage-issue"
+    "/maestro-quick"
   ],
   "workflows": {
+    "topology": {
+      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "layers": {
+        "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "orchestration": "roadmap (可选，消费上游 context)",
+        "execution": ["plan", "execute", "verify"]
+      }
+    },
+    "paths": {
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
+      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → verify",
+      "D_small_fix": "plan → execute → verify",
+      "E_spec_only": "blueprint → (供人阅读)",
+      "F_explore_only": "brainstorm → (供人决策)"
+    },
     "main_pipeline": {
       "name": "主干管线",
       "phases": ["analyze", "plan", "execute", "verify"],
@@ -176,9 +194,9 @@
     },
     "init_paths": {
       "name": "初始化路径",
-      "minimal": "/maestro-init → /maestro-roadmap",
-      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from-brainstorm → /maestro-roadmap",
-      "full_spec": "/maestro-init → /maestro-spec-generate"
+      "from_brainstorm": "/maestro-brainstorm → /maestro-init --from brainstorm:<id> → /maestro-analyze 宏观",
+      "from_blueprint": "/maestro-blueprint → /maestro-init → /maestro-analyze 宏观",
+      "direct": "/maestro-init → /maestro-analyze 宏观"
     }
   }
 }

package/.claude/skills/maestro-help/phases/01-parse-intent.md

@@ -59,7 +59,7 @@ const commandPrefixes = ["/", "maestro-", "manage-", "quality-", "spec-", "learn
 // Known command names from catalog (without prefix)
 const knownCommands = [
   "maestro", "analyze", "plan", "execute", "verify", "init", "roadmap",
-  "brainstorm", "quick", "overlay", "amend", "fork", "merge", "collab",
+  "brainstorm", "blueprint", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
   "composer", "player", "ralph", "ralph-execute", "learn",
   "impeccable", "ui-codify", "update",

package/.claude/skills/maestro-help/phases/02-search-present.md

@@ -70,7 +70,7 @@
 | 命令 | Guide 文档 |
 |------|-----------|
 | maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
-| maestro-init/roadmap | `guide/quick-start-guide.md` |
+| maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` |
 | maestro-ralph | `guide/maestro-ralph-guide.md` |
 | maestro (协调器) | `guide/maestro-coordinator-guide.md` |
 | manage-* | `guide/command-usage-guide.md` (管理) |
@@ -91,9 +91,11 @@
 | 当前状态 | 推荐命令 | 原因 |
 |---------|---------|------|
 | 无 .workflow/ | `/maestro-init` | 项目未初始化，需要先创建工作区 |
-| init 完成，无 roadmap | `/maestro-roadmap` | 需要路线图指导后续 Phase |
-| roadmap 完成，phase=pending | `/maestro-analyze` | 准备开始分析阶段 |
-| analyze 完成 | `/maestro-plan` | 分析完成，进入规划 |
+| init 完成，无上游 context | `/maestro-brainstorm` 或 `/maestro-analyze "topic"` | 先探索再规划；brainstorm 用于发散，analyze 宏观用于代码库分析 |
+| analyze 完成，scope_verdict=large | `/maestro-roadmap --from analyze:ANL-xxx` | 大范围需求，需要 Milestone > Phase 分解 |
+| analyze 完成，scope_verdict=medium/small | `/maestro-plan --from analyze:ANL-xxx` | 跳过 roadmap，直接规划（Path C） |
+| roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
+| analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
 | plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
 | execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
 | verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |