maestro-flow 0.5.2 → 0.5.31

package/.agents/skills/learn-second-opinion/SKILL.md

@@ -13,112 +13,108 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<purpose>
-Structured second-opinion on code, decisions, or plans. Three modes:
-- **review** (default): 3 parallel agents (pragmatist, purist, strategist)
-- **challenge**: single adversarial agent — break assumptions, propose alternatives
-- **consult**: interactive Q&A — agent studies target, answers your questions
-
-Findings persist to `.workflow/specs/learnings.md` as `<spec-entry>` blocks.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional mode flag.
-
-**Target resolution** (auto-detected):
-| Input | Resolution |
-|-------|-----------|
-| File path | Read file content |
-| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
-| Phase number | Resolve via state.json.artifacts[] → plan.json |
-
-**Flags**: `--mode review|challenge|consult` (default: review)
-
-**Pre-load** (optional): `invoke_skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
-
-**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
-</context>
-
-<state_machine>
-
-<states>
-S_RESOLVE    — 解析 target                          PERSIST: —
-S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
-S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
-S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
-S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
-</states>
-
-<transitions>
-
-S_RESOLVE:
-  → S_CONTEXT     WHEN: target resolved                DO: read target content
-  → S_RESOLVE     WHEN: unresolvable                   DO: ask_user for clarification
-
-S_CONTEXT:
-  → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
-
-S_EXECUTE:
-  → S_SYNTHESIZE  WHEN: mode == review                 DO: A_REVIEW
-  → S_SYNTHESIZE  WHEN: mode == challenge              DO: A_CHALLENGE
-  → S_SYNTHESIZE  WHEN: mode == consult                DO: A_CONSULT
-
-S_SYNTHESIZE:
-  → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
-
-S_PERSIST:
-  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
-
-</transitions>
-
-<actions>
-
-### A_REVIEW
-Spawn 3 Agents in single message:
-
-| Agent | Focus | Question |
-|-------|-------|----------|
-| Pragmatist | simplicity, YAGNI, maintenance | "Simplest thing that works? Maintenance burden?" |
-| Purist | correctness, edge cases, type safety | "What assumptions can be violated?" |
-| Strategist | scalability, architecture alignment | "Supports future growth? Fits architecture?" |
-
-Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.
-
-### A_CHALLENGE
-Spawn 1 adversarial Agent:
-- Find weakest assumption
-- Propose concrete breaking scenario
-- Identify single biggest risk
-- Suggest alternative approach
-- Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"
-
-### A_CONSULT
-Interactive loop:
-1. Agent studies target
-2. Display "Target loaded. What would you like to know?"
-3. ask_user → Agent answers with code refs → repeat until "done"
-4. Compile Q&A into report
-
-</actions>
-
-</state_machine>
-
-<error_codes>
-| Code | Condition | Recovery |
-|------|-----------|----------|
-| E002 | Unknown --mode value | Use: review, challenge, or consult |
-| W001 | One review agent failed | Proceed with available perspectives |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
-- [ ] Synthesis with agreements, disagreements, verdict
-- [ ] Report written + findings appended to .workflow/specs/learnings.md
-</success_criteria>
-
-<next_step_routing>
-- Create issue → `/manage-issue create <description>`
-- Decompose patterns → `/learn-decompose <path>`
-- Follow code → `/learn-follow <path>`
-</next_step_routing>
+<purpose>
+Structured second-opinion on code, decisions, or plans via three modes: review (3 parallel agents),
+challenge (adversarial), or consult (interactive Q&A). Findings persist to learnings.md.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional mode flag.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path | Read file content |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
+| Phase number | Resolve via state.json.artifacts[] → plan.json |
+
+**Flags**: `--mode review|challenge|consult` (default: review)
+
+**Pre-load** (optional): `invoke_skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
+
+**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE    — 解析 target                          PERSIST: —
+S_CONTEXT    — 加载 specs/wiki 上下文                PERSIST: —
+S_EXECUTE    — 按 mode 执行分析                      PERSIST: —
+S_SYNTHESIZE — 综合观点、生成报告                     PERSIST: outputs
+S_PERSIST    — 写文件、append .workflow/specs/learnings.md      PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved                DO: read target content
+  → S_RESOLVE     WHEN: unresolvable                   DO: ask_user for clarification
+
+S_CONTEXT:
+  → S_EXECUTE     DO: load specs + wiki search (optional, proceed without)
+
+S_EXECUTE:
+  → S_SYNTHESIZE  WHEN: mode == review                 DO: A_REVIEW
+  → S_SYNTHESIZE  WHEN: mode == challenge              DO: A_CHALLENGE
+  → S_SYNTHESIZE  WHEN: mode == consult                DO: A_CONSULT
+
+S_SYNTHESIZE:
+  → S_PERSIST     DO: merge perspectives → agreements, disagreements, verdict, top 3 recommendations
+
+S_PERSIST:
+  → END           DO: write KNW-opinion + append <spec-entry> blocks to .workflow/specs/learnings.md
+
+</transitions>
+
+<actions>
+
+### A_REVIEW
+Spawn 3 Agents in single message:
+
+| Agent | Focus | Question |
+|-------|-------|----------|
+| Pragmatist | simplicity, YAGNI, maintenance | "Simplest thing that works? Maintenance burden?" |
+| Purist | correctness, edge cases, type safety | "What assumptions can be violated?" |
+| Strategist | scalability, architecture alignment | "Supports future growth? Fits architecture?" |
+
+Each returns: persona, verdict (approve/concern/reject), confidence, findings[{severity, description, location, suggestion}], summary.
+
+### A_CHALLENGE
+Spawn 1 adversarial Agent:
+- Find weakest assumption
+- Propose concrete breaking scenario
+- Identify single biggest risk
+- Suggest alternative approach
+- Apply forcing questions: "What invalidates this?", "Simplest thing that breaks this?", "What would you regret in 6 months?", "What implicit contract isn't enforced?"
+
+### A_CONSULT
+Interactive loop:
+1. Agent studies target
+2. Display "Target loaded. What would you like to know?"
+3. ask_user → Agent answers with code refs → repeat until "done"
+4. Compile Q&A into report
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | Unknown --mode value | Use: review, challenge, or consult |
+| W001 | One review agent failed | Proceed with available perspectives |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode executed: review (3 parallel agents) / challenge (adversarial) / consult (interactive Q&A)
+- [ ] Synthesis with agreements, disagreements, verdict
+- [ ] Report written + findings appended to .workflow/specs/learnings.md
+</success_criteria>
+
+<next_step_routing>
+- Create issue → `/manage-issue create <description>`
+- Decompose patterns → `/learn-decompose <path>`
+- Follow code → `/learn-follow <path>`
+</next_step_routing>

package/.agents/skills/maestro/SKILL.md

@@ -16,16 +16,8 @@ allowed-tools:
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
 <purpose>
-Orchestrate all maestro commands based on user intent and project state.
-Classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.
-
-Entry points:
-- **`/maestro "intent"`** — Intent-based: classify → chain → execute
-- **`/maestro -c`** — Resume previous session
-- **`/maestro --dry-run "intent"`** — Show chain, no execution
-- **`/maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
-
-**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `maestro-{YYYYMMDD-HHmmss}`（本 command 创建，静态链）或 `ralph-{YYYYMMDD-HHmmss}`（`/maestro-ralph` 创建，自适应链）。两类都由 `/maestro-ralph-execute` 推进；schema 与 ralph 共用（含 `ralph_protocol_version: "1"` + `active_step_index`）。
+Orchestrate all maestro commands: classify intent → select chain → create session → dispatch to `maestro-ralph-execute`.
+Session: `.workflow/.maestro/{session_id}/status.json`.
 </purpose>
 
 <deferred_reading>
@@ -52,7 +44,7 @@ $ARGUMENTS — user intent text, or special keywords.
 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. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform agent --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `invoke_skill("maestro-ralph")` handoff
-7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
+7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
 8. **Grill is interactive-only** — `-y` auto mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
@@ -143,9 +135,9 @@ S_FALLBACK:
    - 正式规格/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
+   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → quality pipeline
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → quality pipeline
 4. 执行 step：`shell("maestro ralph skills --platform agent --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
@@ -161,7 +153,7 @@ S_FALLBACK:
 2. broad/medium → `ask_user` ≤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[]`
+5. 在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
 6. **输出 `/goal` 绑定提示词（不阻塞，用户可在执行过程中随时输入）：**
    ```
    📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：
@@ -223,7 +215,7 @@ S_FALLBACK:
 ### Success Criteria
 
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / quality pipeline
+- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / quality pipeline
 - [ ] `-y` 模式不触发 grill（交互式压力测试不支持自动模式，跳过直接走 brainstorm）
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
 - [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）

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

@@ -12,155 +12,155 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<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 + ask_user).
-
-**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 |
-| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
-| 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>
+<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 + ask_user).
+
+**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 |
+| E002 | Signal source path invalid or unreadable | Check `--from-*` path; ensure artifact exists |
+| 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>