maestro-flow 0.4.11 → 0.4.12

package/.claude/skills/maestro-help/phases/03-workflow-guide.md

@@ -33,36 +33,46 @@ const taskPatterns = [
 
 #### Step 4.2: 推荐工作流
 
-**新项目** (复杂度: 高):
+**新项目 — Path A** (复杂度: 高):
 
 ```markdown
 ## 新项目工作流
 
-### 路径 1: 最简路径（适合快速启动）
-1. `/maestro-init` — 初始化 .workflow/ 目录
-2. `/maestro-roadmap "项目目标" -y` — 生成路线图
-3. 按里程碑执行: analyze → plan → execute → verify
+### 路径 A: 完整新项目
+1. `/maestro-brainstorm "项目描述"` — 发散探索，多角色创意
+2. `/maestro-blueprint` — (可选) 7-phase 正式规格文档化
+3. `/maestro-init --from brainstorm:ID`
+4. `/maestro-analyze "topic"` — 宏观分析，探索影响面 → scope_verdict
+5. `/maestro-roadmap --from analyze:ANL-xxx` — 纯编排，Milestone > Phase 分解
+6. `/maestro-analyze 1` — 微观分析，Phase 级深入
+7. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
 
-### 路径 2: 从头脑风暴开始（适合需要创意探索）
-1. `/maestro-brainstorm "项目描述"` — 多角色头脑风暴
-2. `/maestro-init --from-brainstorm ANL-xxx` — 基于分析初始化
-3. `/maestro-roadmap "创建路线图" -y`
+### 路径 E: 纯规格文档（不进执行链）
+1. `/maestro-blueprint "project idea"` — 供人阅读和决策
 
-### 路径 3: 完整规范链（适合大型项目）
-1. `/maestro-init`
-2. `/maestro-spec-generate` — 7 阶段规范生成
+### 路径 F: 纯探索（不进执行链）
+1. `/maestro-brainstorm "idea"` — 供人决策
 ```
 
-**功能开发** (复杂度: 中):
+**旧项目大功能 — Path B** (复杂度: 高):
 
 ```markdown
-## 功能开发工作流
+## 旧项目大功能工作流
 
-### 主干管线（标准流程）
-1. `/maestro-analyze [phase]` — 分析需求和现有代码
-2. `/maestro-plan [phase]` — 生成执行计划
-3. `/maestro-execute [phase]` — 执行实现
-4. `/maestro-verify [phase]` — 验证成果
+1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=large
+2. `/maestro-roadmap --from analyze:ANL-xxx` — Milestone > Phase 分解
+3. `/maestro-analyze 1` — 微观分析
+4. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+```
+
+**中等功能 — Path C** (复杂度: 中，跳过 roadmap):
+
+```markdown
+## 中等功能工作流
+
+1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=medium
+2. `/maestro-plan --from analyze:ANL-xxx` — 直达规划，跳过 roadmap
+3. `/maestro-execute` → `/maestro-verify`
 
 ### 快速渠道（简单功能）
 1. `/maestro-quick "功能描述"` — 一键完成
@@ -71,13 +81,22 @@ const taskPatterns = [
 1. `/maestro -y "功能描述"` — 自动选择并执行完整流程
 ```
 
-**Bug 修复** (复杂度: 低-中):
+**小改动 — Path D** (复杂度: 低):
 
 ```markdown
-## Bug 修复工作流
+## 小改动工作流
+
+1. `/maestro-plan "fix auth bug"` — 直接规划
+2. `/maestro-execute` → `/maestro-verify`
 
 ### 快速修复（已知问题）
 1. `/maestro-quick "修复 Bug 描述"`
+```
+
+**Bug 追踪** (Issue 闭环):
+
+```markdown
+## Bug 追踪工作流
 
 ### Issue 闭环（需要追踪）
 1. `/manage-issue-discover by-prompt "问题描述"` — 发现 Issue
@@ -109,7 +128,10 @@ const taskPatterns = [
 对需要全景视角的用户，展示 Mermaid 图：
 
 ```
-主干管线: analyze → plan → execute → verify → quality (review/test) → milestone-audit → milestone-complete
+上游起源: brainstorm(发散) | blueprint(收敛) → 可选
+理解层:   analyze "topic"(宏观) → scope_verdict 路由
+编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
+执行层:   plan → execute → verify → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
 全自动: /maestro -y → (自动路由)
@@ -122,11 +144,16 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 ```markdown
 ## 核心概念
 
-- **Milestone**: 项目阶段，包含多个 Phase
-- **Phase**: 单个工作单元，走 analyze → plan → execute → verify 生命周期
+- **Roadmap**: 项目级常驻规划文档，包含多个 Milestone
+- **Milestone**: 可独立交付的版本节点（v0.1.0-rc1），包含多个 Phase
+- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute → verify 生命周期
+- **Task**: Phase 内的具体代码修改单元（wave DAG 管理并行）
+- **Blueprint**: 正式规格文档化命令（7-phase 收敛），与 brainstorm 并列作为上游起源
+- **Analyze 双层**: 宏观(文本参数)探索影响面产出 scope_verdict；微观(数字参数)Phase 级深入分析
+- **scope_verdict**: analyze 宏观完成后的路由建议 — large→roadmap, medium/small→直达 plan
 - **Overlay**: 非侵入式命令补丁，扩展命令行为而不修改源文件
 - **Delegate**: 将子任务委派给外部 AI 工具（Gemini/Claude/Codex）
-- **Spec**: 项目规范，自动注入到工作流中作为约束
+- **Spec**: 项目约束规则（coding/arch/debug/test），自动注入到工作流
 - **Wiki**: 知识图谱，存储详细技术文档
 - **Ralph**: 自适应决策引擎，动态调整执行链
 ```
@@ -146,14 +173,14 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 |---|------|------|---------|
 | 1 | `/maestro` | 智能协调器 | 不确定用哪个命令时，告诉它你的目标 |
 | 2 | `/maestro-init` | 初始化项目 | 首次使用，创建 .workflow/ 结构 |
-| 3 | `/maestro-roadmap` | 生成路线图 | 初始化后，规划里程碑 |
-| 4 | `/maestro-analyze` | 分析 | 开始一个 Phase 的分析 |
-| 5 | `/maestro-plan` | 规划 | 分析完成后，生成执行计划 |
-| 6 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
-| 7 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
-| 8 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
-| 9 | `/quality-review` | 代码审查 | 执行后进行质量检查 |
-| 10 | `/manage-issue` | Issue 管理 | 追踪和解决 Bug |
+| 3 | `/maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
+| 4 | `/maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
+| 5 | `/maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
+| 6 | `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
+| 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
+| 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
+| 9 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
+| 10 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
 ```
 
 #### Step 5.2: 快速入门路径

package/.claude/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -77,7 +77,7 @@ After codebase exploration, scan results for context-aware trigger signals (base
 
 ## Phase 4: Context Packaging
 
-1. Write spec-config.json → <session>/spec/
+1. Write blueprint-config.json → <session>/spec/
 2. Write discovery-context.json → <session>/spec/
 3. Inline Discuss (DISCUSS-001):
    - Artifact: <session>/spec/discovery-context.json

package/.claude/skills/team-lifecycle-v4/roles/reviewer/commands/review-spec.md

@@ -22,7 +22,7 @@
 2. Load quality gate thresholds from specs/quality-gates.md
 3. Score each dimension
 4. Run cross-document validation
-5. Generate readiness-report.md + spec-summary.md
+5. Generate readiness-report.md + blueprint-summary.md
 6. Run DISCUSS-003:
    - Artifact: <session>/spec/readiness-report.md
    - Perspectives: product, technical, quality, risk, coverage
@@ -41,4 +41,4 @@
 
 Write to <session>/artifacts/:
 - readiness-report.md: Dimension scores, issue list, traceability matrix
-- spec-summary.md: Executive summary of all spec docs
+- blueprint-summary.md: Executive summary of all spec docs

package/.claude/skills/team-lifecycle-v4/roles/writer/role.md

@@ -50,7 +50,7 @@ Template-driven document generation with progressive dependency loading.
 
 ### Inputs
 - Template from routing table
-- spec-config.json from <session>/spec/
+- blueprint-config.json from <session>/spec/
 - discovery-context.json from <session>/spec/
 - Prior decisions from context_accumulator (inner loop)
 - Discussion feedback from <session>/discussions/ (if exists)

package/.claude/skills/team-lifecycle-v4/templates/architecture.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
 ---
@@ -246,9 +246,9 @@ date: {timestamp}
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | ADR/requirement number |
 | `{slug}` | Auto-generated | Kebab-case from decision title |
-| `{has_codebase}` | spec-config.json | Whether existing codebase exists |
+| `{has_codebase}` | blueprint-config.json | Whether existing codebase exists |

package/.claude/skills/team-lifecycle-v4/templates/epics.md

@@ -32,7 +32,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
   - ../requirements/_index.md
   - ../architecture/_index.md
@@ -187,7 +187,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{EPIC}` | Auto-increment | Epic number (3 digits) |

package/.claude/skills/team-lifecycle-v4/templates/product-brief.md

@@ -23,7 +23,7 @@ generated_at: {timestamp}
 stepsCompleted: []
 version: 1
 dependencies:
-  - spec-config.json
+  - blueprint-config.json
 ---
 
 # Product Brief: {product_name}
@@ -117,7 +117,7 @@ dependencies:
 
 ## References
 
-- Derived from: [spec-config.json](spec-config.json)
+- Derived from: [blueprint-config.json](blueprint-config.json)
 - Next: [Requirements PRD](requirements.md)
 ```
 
@@ -125,7 +125,7 @@ dependencies:
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | Seed analysis | Product/feature name |
 | `{executive_summary}` | CLI synthesis | 2-3 sentence summary |

package/.claude/skills/team-lifecycle-v4/templates/requirements.md

@@ -36,7 +36,7 @@ status: draft
 generated_at: {timestamp}
 version: 1
 dependencies:
-  - ../spec-config.json
+  - ../blueprint-config.json
   - ../product-brief.md
 ---
 
@@ -215,7 +215,7 @@ status: draft
 
 | Variable | Source | Description |
 |----------|--------|-------------|
-| `{session_id}` | spec-config.json | Session identifier |
+| `{session_id}` | blueprint-config.json | Session identifier |
 | `{timestamp}` | Runtime | ISO8601 generation timestamp |
 | `{product_name}` | product-brief.md | Product/feature name |
 | `{NNN}` | Auto-increment | Requirement number (zero-padded 3 digits) |

package/.codex/skills/maestro/SKILL.md

@@ -40,11 +40,14 @@ $ARGUMENTS — user intent text, or special flags.
 <invariants>
 1. **Skills invoked DIRECTLY in-context** — coordinator runs `$skill {resolved_args}` itself, sequentially. NO spawn_agents_on_csv, NO wave/CSV/worker.
 2. **Coordinator owns the loop** — classify → decompose → resolve chain → for each step: resolve args → invoke skill → read result → persist → next.
-3. **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`. Reference maestro-ralph `A_DECOMPOSE_TASKS`; do not duplicate logic.
-4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused.
-5. **Status JSON: schema-additive + step-dynamic** — decomposition fields OPTIONAL (absent → old flat-chain behavior); `steps[]` is a living array grown at runtime by `post-goal-audit`. `goal_ref` traces dynamically-added steps. Never remove/rename existing fields. `waves` kept as empty array for backward-compat (spawning removed).
-6. **Sequential execution** — one step at a time in index order; each step's result read before the next starts.
-7. **Abort on failure** — failed step → mark remaining skipped → report (goal stays bound for `--continue`).
+3. **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`
+4. **Goal is tool-created** — `A_DECOMPOSE_TASKS` calls `create_goal` with sub-goal success criteria. `update_goal` on convergence; held while aborted/paused
+5. **status.json 唯一真源** — 不生成 `goal-checklist.md`；step 含 `command_scope` + `command_path` + `completion_confirmed`
+6. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro(text) / analyze(numeric) / roadmap / plan(三路径) / execute / verify / ...
+7. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
+8. **schema 向后兼容** — decomposition 字段可选；`steps[]` 由 post-goal-audit 动态生长（goal_ref tagged）；既有字段不删不改；`waves` 保留空数组
+9. **Sequential execution** — one step at a time in index order; each step's result read before the next starts
+10. **Abort on failure** — failed step → mark remaining skipped → report (goal stays bound for `--continue`)
 </invariants>
 
 <state_machine>
@@ -152,9 +155,13 @@ Extract:
 | task_type | When user intent is about... |
 |-----------|---------------------------|
 | `quick` | Simple/small task, add a feature, quick change |
+| `blueprint` | Formal spec generation (Product Brief / PRD / Architecture / Epics) |
+| `analyze_macro` | Broad/medium intent w/o numeric phase — explore impact, produce scope_verdict |
+| `plan_from_analyze` | Plan directly from analyze artifact (no roadmap, scope=standalone) |
+| `plan_from_blueprint` | Plan directly from blueprint artifact (scope=standalone) |
 | `plan` | Plan, design, architect a phase |
 | `execute` | Implement, develop, code a phase |
-| `analyze` | Understand, investigate, evaluate code |
+| `analyze` | Understand, investigate, evaluate code (numeric phase) |
 | `verify` | Check goals met, validate results |
 | `review` | Code quality review |
 | `test` | Run or create tests, UAT |
@@ -200,11 +207,16 @@ Extract:
 **Selection priorities:**
 1. `issue_id` present → prefer issue chains
 2. UI/design/界面/页面/原型 → prefer `ui_design`
-3. Multiple lifecycle steps implied → prefer multi-step chains
-4. Single specific action → prefer single-step chains
-5. "问题" describing broken behavior → `debug`; tracked item with ISS-ID → `issue`; ambiguous → `debug`
-6. Simple task, no lifecycle context → `quick`
-7. Global fallback → `quick`
+3. 正式规格/spec-generate/7-phase → `blueprint` (single-step) 或 `blueprint-driven`
+4. 头脑风暴/探索 → `brainstorm-driven`
+5. Broad/medium intent + 无数字 phase → `analyze_macro`（产 scope_verdict）；后续 large→roadmap链；medium/small→`plan_from_analyze`
+6. 已有 analyze artifact 直达 plan → `plan_from_analyze`
+7. 已有 blueprint artifact 直达 plan → `plan_from_blueprint`
+8. Multiple lifecycle steps implied → prefer multi-step chains
+9. Single specific action → prefer single-step chains
+10. "问题" describing broken behavior → `debug`; tracked item with ISS-ID → `issue`
+11. Simple task, no lifecycle context → `quick`
+12. Global fallback → `quick`
 
 **Clarity scoring**: 3=task_type+scope+phase, 2=task_type+scope, 1=task_type only, 0=empty.
 If `clarity < 2` and not `auto_mode` → transition to A_CLARIFY_INTENT.
@@ -251,13 +263,13 @@ Read `.workflow/state.json` and route by condition:
 
 ### A_DECOMPOSE_TASKS
 
-与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约 —— 引用该规范，不重复。Condensed:
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
 1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
-2. broad/medium → `AskUserQuestion` ≤3 轮：Scope（in/out）| Constraints（兼容/API/perf/test）| Definition of Done
-3. 派生 `execution_criteria`（3-6 条命令式规则）+ `task_decomposition`（outcome 子目标，`done_when` 可校验，绑定到 ralph evidence 产物）
-4. **status.json 为唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition` / `goal_checklist_path`；从 status.json 投影渲染 `{session_dir}/goal-checklist.md`（同 maestro-ralph Sync Rule，含 Resume 区块指向 `$maestro --continue`）
-5. 链路末尾（evidence 产出步骤后、milestone-complete/close-out 前）追加 `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }`。S_DECISION_EVAL 在该节点动态生长 `steps[]`
+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 产出步骤后、milestone-complete/close-out 前）追加 `decision:post-goal-audit`。S_DECISION_EVAL 据此动态生长 `steps[]`
 6. **Register goal via `create_goal`:**
    ```
    create_goal({ objective: "Maestro {chain}: {intent} — converge {N} sub-goals within boundary",
@@ -267,24 +279,38 @@ Read `.workflow/state.json` and route by condition:
 
 ### A_CREATE_SESSION
 
-1. Read `.workflow/state.json` for project context (current phase, milestone, workflow_name)
+1. Read `.workflow/state.json` 获取 phase / milestone（D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`；读最新 blueprint artifact 注入 `blueprint_id`
 2. Resolve chain's skill list from Chain Map (see appendix)
-3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）:
    ```json
-   { "session_id", "source": "maestro", "intent", "task_type", "chain_name",
-     "phase", "milestone", "auto_mode", "context": { "issue_id", "scratch_dir",
-     "plan_dir", "analysis_dir", "brainstorm_dir" },
-     "steps": [{ "index", "type": "skill|decision", "skill", "args", "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,
+     "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null,
+       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null },
+     "steps": [{
+       "index": 0, "type": "skill|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 → flat-chain behavior",
      "boundary_contract": {}, "execution_criteria": [],
-     "task_decomposition": [{ "id": "G1", "goal": "", "done_when": "", "evidence": "", "status": "pending|done", "completed_at": null }],
-     "task_decomposition_all_done": false,
-     "goal_checklist_path": "", "goal_checklist_synced_at": null }
+     "task_decomposition": [{ "id": "G1", "goal": "", "done_when": "", "evidence": "",
+       "status": "pending|done", "completion_confirmed": false, "completed_at": null }],
+     "task_decomposition_all_done": false
+   }
    ```
    Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive)
-4. goal-checklist.md 是 status.json 的投影：从 task_decomposition 渲染（同 maestro-ralph Sync Rule）；Resume 区块写入 `$maestro --continue`
-4. Initialize tracking:
+4. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 列出缺失 skill
+5. Initialize tracking:
    - If decomposed: goal already registered by A_DECOMPOSE_TASKS. Else: `create_goal({ objective: "Maestro {chain}: {N} steps [{skill list}]" })`
    - `update_plan({ plan: steps.map(step => ({ step, status: "pending" })) })`
 
@@ -328,10 +354,9 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 ### A_APPLY_GOAL_DONE
 
-1. status.json（真源）：全部 `task_decomposition[*].status="done"` + `completed_at=now` + `task_decomposition_all_done=true`
-2. 从 status.json 重渲染 `goal-checklist.md`（见 Sync Rule）；文件末追加 `ALL_GOALS_DONE`
-3. `update_goal({ status: "complete" })` —— 释放分解 goal
-4. 继续到 chain 的终结步骤
+1. status.json：全部 `task_decomposition[*].status="done"` + `completion_confirmed=true` + `completed_at=now` + `task_decomposition_all_done=true`
+2. `update_goal({ status: "complete" })`
+3. 继续到 chain 的终结步骤
 
 ### A_FINALIZE
 
@@ -361,9 +386,13 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 |-------|---------------|
 | `status` | `manage-status` |
 | `init` | `maestro-init` |
+| `blueprint` | `maestro-blueprint "{intent}"` |
+| `analyze_macro` | `maestro-analyze "{intent}"` |
 | `analyze` | `maestro-analyze {phase}` |
 | `ui_design` | `maestro-impeccable build "{phase}"` |
 | `plan` | `maestro-plan {phase}` |
+| `plan_from_analyze` | `maestro-plan --from analyze:{analyze_macro_id}` |
+| `plan_from_blueprint` | `maestro-plan --from blueprint:{blueprint_id}` |
 | `execute` | `maestro-execute {phase}` |
 | `verify` | `maestro-verify {phase}` |
 | `test_gen` | `quality-auto-test {phase}` |
@@ -413,7 +442,8 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `feature` | [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → maestro-verify |
 | `deploy` | maestro-verify → maestro-milestone-release |
-| `spec-driven` | maestro-init → [B] maestro-roadmap --mode full → [B] maestro-plan → [B] maestro-execute → maestro-verify |
+| `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → maestro-verify |
+| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → maestro-verify |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → maestro-verify |
 | `roadmap-driven` | maestro-init → [B] maestro-roadmap → [B] maestro-plan → [B] maestro-execute → maestro-verify |
@@ -436,15 +466,17 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 
 | taskType | Chain |
 |----------|-------|
-| `spec_generate` | `spec-driven` |
+| `spec_generate` | `blueprint-driven` |
+| `spec-driven` | `blueprint-driven` |
 | `brainstorm` | `brainstorm-driven` |
 | `issue_execute` | `issue-full` |
+| `analyze_macro` | `analyze-macro-driven` |
 
 ### Auto-Yes Flag Map
 
 | Skill | Flag |
 |-------|------|
-| maestro-init, maestro-analyze, maestro-brainstorm, maestro-impeccable, maestro-roadmap | `-y` |
+| maestro-init, maestro-analyze, maestro-brainstorm, maestro-blueprint, maestro-impeccable, maestro-roadmap | `-y` |
 | maestro-plan, maestro-execute, maestro-milestone-complete | `-y` |
 | quality-auto-test, quality-retrospective | `-y` |
 | quality-test | `-y --auto-fix` |
@@ -462,15 +494,20 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | E003 | error | Step skill invocation failed | auto_mode retry once, then abort chain |
 | E004 | error | Context artifact not found | Retry step once, then abort |
 | E005 | error | --continue: no session found | List sessions, prompt |
+| E006 | error | command_scope == "missing" for one or more steps | List missing skills, abort build |
 | W001 | warning | Context artifact partial | Continue with available context |
 
 ### Success Criteria
 
 - [ ] Intent classified and chain resolved
-- [ ] Broad lifecycle intents decomposed (S_DECOMPOSE, ≤3 boundary questions) sharing maestro-ralph contract; narrow/single-step skip
+- [ ] Chain catalog 覆盖 blueprint / analyze_macro / plan_from_analyze / plan_from_blueprint / blueprint-driven / analyze-macro-driven 等新拓扑路径
+- [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查；写入 step
+- [ ] plan step args 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
+- [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
 - [ ] Goal registered via built-in `create_goal`; status.json decomposition fields additive-only
-- [ ] status.json 为唯一真源；goal-checklist.md 是从 JSON 重渲染的投影视图（Resume 区块指向 `$maestro --continue`）
-- [ ] post-goal-audit node appended as final node (after evidence-producing steps); unmet sub-goals dynamically grow steps[] (goal_ref tagged)
+- [ ] status.json 唯一真源；无 markdown 清单
+- [ ] 每个 step 含 `command_scope` + `command_path` + `completion_confirmed` 字段
+- [ ] post-goal-audit node appended as final node; unmet sub-goals dynamically grow steps[] (goal_ref tagged)
 - [ ] Session dir initialized with status.json before first step
 - [ ] Every skill invoked DIRECTLY in-context — NO spawn_agents_on_csv, NO wave/CSV/worker
 - [ ] Sequential execution; status.json + update_plan persisted after every step

package/.codex/skills/maestro-amend/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: maestro-amend
+description: Generate overlays to fix workflow command deficiencies
+argument-hint: "[description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run]"
+allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
+---
+<purpose>
+Signal-driven overlay generator — collect workflow deficiency signals from multiple sources, diagnose which commands need amendment, batch-generate targeted overlays. All amendments use overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
+
+Differs from `/maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+$ARGUMENTS — optional description and/or source flags.
+
+**Signal sources**:
+
+| Flag | Source | Collects |
+|------|--------|----------|
+| `--from-verify <dir>` | verification.json | Workflow gaps from verify failures |
+| `--from-review <dir>` | review.json | Process deficiencies from code review |
+| `--from-session <id>` | Session artifacts | Problems during workflow execution |
+| `--from-issues ISS-xxx,...` | issues.jsonl | Issues tracing to command deficiency |
+| `--scan` | Auto-scan .workflow/ | Discover all workflow-related signals |
+| _(positional text)_ | User description | Direct observation |
+
+Multiple combinable. No flags + no description → interactive (scan + AskUserQuestion).
+
+**Control**: `--dry-run` (preview, don't install), `-y` (skip confirmations)
+
+**CLI targeting**: `"cli": "claude"` (default, patches .claude/commands/), `"codex"` (patches .codex/skills/), `"both"` (both paths)
+
+**Output**: `~/.maestro/overlays/amend-{slug}.json` + optional `~/.maestro/overlays/docs/amend-{slug}.md`
+</context>
+
+<state_machine>
+
+<states>
+S_COLLECT      — 收集信号（从 flags / scan / description）    PERSIST: —
+S_DIAGNOSE     — 映射信号到命令补丁                           PERSIST: —
+S_GROUP        — 分组、规划 overlay 粒度                      PERSIST: —
+S_PREVIEW      — 展示注入点地图、用户确认                     PERSIST: —
+S_DRAFT        — 生成 overlay JSON                            PERSIST: overlay files
+S_INSTALL      — 安装 overlay                                 PERSIST: command files
+S_REPORT       — 报告摘要 + post-patch routing                PERSIST: —
+</states>
+
+<transitions>
+
+S_COLLECT:
+  → S_DIAGNOSE    WHEN: signals found                      DO: A_COLLECT_SIGNALS
+  → ERROR(E001)   WHEN: no signals from any source
+
+S_DIAGNOSE:
+  → S_GROUP       WHEN: command deficiencies identified     DO: A_DIAGNOSE_SIGNALS
+  → ERROR(E003)   WHEN: all signals are code bugs (not command gaps)
+
+S_GROUP:
+  → S_PREVIEW     DO: A_GROUP_OVERLAYS
+
+S_PREVIEW:
+  → S_DRAFT       WHEN: user confirms "Apply all" or selects patches
+  → S_PREVIEW     WHEN: user selects "Edit"                DO: modify signal target/section
+  → END           WHEN: user cancels
+
+S_DRAFT:
+  → S_INSTALL     WHEN: not --dry-run                      DO: A_DRAFT_OVERLAYS
+  → END           WHEN: --dry-run                          DO: display JSON + section map preview
+
+S_INSTALL:
+  → S_REPORT      DO: A_INSTALL_OVERLAYS (`maestro overlay add`, retry max 2 on validation failure)
+
+S_REPORT:
+  → END           DO: display summary (signals collected/applied/skipped, overlay details, skipped code-bug routing)
+
+</transitions>
+
+<actions>
+
+### A_COLLECT_SIGNALS
+
+**If source flags**: extract signals from each specified source.
+**If --scan or interactive**: scan .workflow/ for:
+- verification.json → must_have_failures, anti_patterns (filter for command gap direction)
+- review.json → findings tagged "process" or "workflow"
+- debug understanding.md → root causes with workflow/command cause_type
+- issues.jsonl → status=open AND tags include "workflow"/"command"
+- execution summaries → plan deviations suggesting missing command step
+
+**If only description**: parse for affected command(s), what's missing, expected behavior.
+
+### A_DIAGNOSE_SIGNALS
+
+Per signal, determine:
+- signal_id, source, description, target_command, target_section, patch_mode, fix_direction, severity
+
+**Section mapping**:
+
+| Signal pattern | Section | Mode |
+|---------------|---------|------|
+| Missing pre-check/gate | execution | prepend |
+| Missing post-step/verification | execution | append |
+| Missing reading/context | required_reading / deferred_reading | append |
+| Incomplete success criteria | success_criteria | append |
+| Missing error handling | error_codes | append |
+| Scope/context gap | context | append |
+| Entirely new concern | _(new section)_ | new-section |
+
+Read pristine source from `$PKG_ROOT/.claude/commands/<name>.md` to confirm section.
+Classify: command deficiency → proceed; code bug → skip (suggest /maestro-quick).
+
+### A_GROUP_OVERLAYS
+
+Group by target command + section (merge same command+section).
+Granularity: 1-2 signals → `patch-{command}-{slug}.json`; 3+ cross-command → `amend-{slug}.json`.
+Read target commands to verify sections exist, check existing overlays.
+
+Display section map with injection points per target command.
+
+### A_DRAFT_OVERLAYS
+
+Build overlay JSON per schema: name, description, targets[], cli, priority (60), enabled, patches[{section, mode, content}].
+Content rules: heading includes `(patch: SIG-NNN)`, concise, supplementary doc to `~/.maestro/overlays/docs/` if >10 lines.
+
+### A_INSTALL_OVERLAYS
+
+```bash
+maestro overlay add ~/.maestro/overlays/amend-{slug}.json
+```
+On validation failure: fix JSON, retry (max 2).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | No signals from any source | Verify artifact paths or provide description |
+| E003 | All signals are code bugs, not command gaps | Use /maestro-quick or /maestro-plan --gaps |
+| E004 | Overlay validation failed after 2 retries | Review JSON manually |
+| W001 | Some signals skipped (code bugs) | Route to appropriate fix command |
+| W002 | Target command has >= 3 existing overlays | Consider consolidating |
+</error_codes>
+
+<success_criteria>
+- [ ] Signals classified: command deficiency vs code bug
+- [ ] Pristine command sources read to verify injection points
+- [ ] Section map with injection points confirmed by user
+- [ ] Overlay JSON installed successfully; command files contain overlay markers
+- [ ] Skipped code-bug signals routed to alternatives
+</success_criteria>