maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/learn-retro/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: learn-retro
+description: Retrospective of git activity and decision quality
+argument-hint: "[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
+
+All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
+
+**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
+**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
+
+**Storage write**:
+- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
+- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
+- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE       — 解析 lens + flags                           PERSIST: —
+S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
+S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
+S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
+S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
+  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
+
+S_GIT:
+  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
+  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
+
+S_DECISION:
+  → S_REPORT      DO: A_DECISION_ANALYSIS
+
+S_REPORT:
+  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
+
+S_PERSIST:
+  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
+
+</transitions>
+
+<actions>
+
+### A_GIT_ANALYSIS
+
+**Parallel git commands**:
+```bash
+git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
+git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
+git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
+git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+git shortlog --since="{start}" -sn --no-merges
+```
+Apply --author and --area filters.
+
+**Compute metrics**:
+
+| Metric | Formula |
+|--------|---------|
+| Test ratio | test_insertions / total_insertions * 100% |
+| Churn rate | files changed >2x / total unique files |
+| Sessions | Cluster commits by >2hr gaps in timestamps |
+| LOC/session-hour | net_loc / total_session_hours |
+
+**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
+
+**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
+
+**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
+
+### A_DECISION_ANALYSIS
+
+**Collect** (parallel):
+```bash
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json
+git log --oneline --all --grep="decision\|chose\|decided" -20
+```
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Apply --phase/--tag/--id filters.
+
+**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
+
+**Evaluate** — spawn 3 Agents in single message:
+
+| Agent | Dimension | Grades |
+|-------|-----------|--------|
+| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
+| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
+| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
+
+**Classify lifecycle**:
+
+| Status | Criteria |
+|--------|---------|
+| Validated | sound + low/acceptable + confirmed |
+| Aging | sound + expensive + confirmed |
+| Questionable | degraded/violated + questionable |
+| Stale | any + should-revisit |
+| Reversed | code contradicts decision |
+
+**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Not in git repo (git lens) | Navigate to git repo |
+| E002 | No commits in window (git lens) | Increase --days |
+| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
+| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
+| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
+| W003 | One perspective agent failed | Proceed with available perspectives |
+</error_codes>
+
+<success_criteria>
+- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
+- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
+- [ ] Unified report + structured JSON written
+- [ ] specs/learnings.md appended with stable INS-ids
+</success_criteria>
+
+<next_step_routing>
+- Browse insights → `/manage-learn list --tag retro`
+- Deep dive churn → `/learn-follow <path>`
+- Fix test gaps → `/quality-auto-test <area>`
+- Investigate stale decision → `/learn-investigate <question>`
+</next_step_routing>

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

@@ -0,0 +1,124 @@
+---
+name: learn-second-opinion
+description: Get alternative perspectives — review, challenge, or consult
+argument-hint: "<target> [--mode review|challenge|consult]"
+allowed-tools:
+  - read_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- 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 `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 wiki 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 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 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 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

@@ -0,0 +1,224 @@
+---
+name: maestro
+description: Auto-route intent to optimal command chain
+argument-hint: "<intent> [-y] [-c] [--dry-run] [--exec auto|cli|internal] [--tool <name>] [--super]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+  - track_tasks
+---
+<!-- 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`
+</purpose>
+
+<deferred_reading>
+- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start for intent analysis + chain selection
+- [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag active
+</deferred_reading>
+
+<context>
+$ARGUMENTS — user intent text, or special keywords.
+
+**Keywords:** `continue`/`next`/`go` → state-based routing; `status` → `invoke_skill("manage-status")`
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors
+- `-c` / `--continue` — Resume previous session
+- `--dry-run` — Show chain without executing
+- `--exec <mode>` — `auto` (default), `cli`, `internal`
+- `--tool <name>` — CLI tool for delegates (default: claude)
+- `--super` — Read and follow `maestro-super.md`
+</context>
+
+<invariants>
+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
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE         — 解析参数、检测 flags                PERSIST: —
+S_RESUME        — 扫描已有 session、恢复执行           PERSIST: —
+S_CLASSIFY      — 意图分类、chain 选择                 PERSIST: —
+S_DECOMPOSE     — 边界澄清、写执行准则+子目标清单       PERSIST: session.boundary_contract, .execution_criteria, .task_decomposition
+S_CREATE        — 创建 session + status.json           PERSIST: session (全量)
+S_DRY_RUN       — 显示 chain 后结束                    PERSIST: —
+S_CONFIRM       — 用户确认（auto_mode 跳过）            PERSIST: —
+S_DISPATCH      — 移交 maestro-ralph-execute           PERSIST: —
+S_FALLBACK      — 意图无法分类、请求输入                PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_RESUME      WHEN: -c / --continue flag
+  → S_CLASSIFY    WHEN: intent text present
+  → S_CLASSIFY    WHEN: keyword "continue"/"next"/"go"    DO: A_STATE_BASED_ROUTE
+  → S_FALLBACK    WHEN: no intent AND no flags
+
+S_RESUME:
+  → S_DISPATCH    WHEN: session found                     DO: A_LOCATE_SESSION
+  → S_FALLBACK    WHEN: no session found
+
+S_CLASSIFY:
+  → S_DECOMPOSE   WHEN: chain resolved                    DO: A_CLASSIFY_INTENT
+  → S_FALLBACK    WHEN: no match AND auto_mode
+  → S_CLASSIFY    WHEN: no match AND not auto_mode        DO: A_CLARIFY
+                   GUARD: max 2 clarification rounds → S_FALLBACK
+
+S_DECOMPOSE:
+  → S_CREATE      DO: A_DECOMPOSE_TASKS
+                   GUARD: broad intent (重构/全面/重写/迁移/overhaul/migrate/rewrite) on a multi-step lifecycle chain → MUST clarify even if auto_mode
+                   GUARD: single-step chain OR narrow intent OR chain ∈ {status,init,quick} → skip decomposition (pass through)
+
+S_CREATE:
+  → S_DRY_RUN     WHEN: --dry-run flag                    DO: A_CREATE_SESSION
+  → S_CONFIRM     WHEN: not auto_mode                     DO: A_CREATE_SESSION
+  → S_DISPATCH    WHEN: auto_mode                         DO: A_CREATE_SESSION
+
+S_DRY_RUN:
+  → END           DO: display chain with step types
+
+S_CONFIRM:
+  → S_DISPATCH    WHEN: user confirms
+  → S_PARSE       WHEN: user wants to modify
+  → END           WHEN: user cancels
+
+S_DISPATCH:
+  → END           DO: invoke_skill({ skill: "maestro-ralph-execute" })
+
+S_FALLBACK:
+  → S_CLASSIFY    WHEN: user provides new intent           DO: ask_user
+  → END           WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_STATE_BASED_ROUTE
+
+1. Read `.workflow/state.json` → determine next logical step
+2. Convert to equivalent intent for chain classification
+
+### A_LOCATE_SESSION
+
+1. Scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC
+2. Take most recent; if not found → 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)
+
+### A_CLARIFY
+
+1. `ask_user` with parsed intent + available chain options
+2. Re-classify with user response
+
+### A_DECOMPOSE_TASKS
+
+与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约 —— 引用该规范，不重复表格。Condensed:
+
+1. 分类意图广度（broad: 重构/全面/重写/迁移/overhaul/migrate/rewrite；narrow: 单文件/函数/bug）。narrow / 单步 / `{status,init,quick}` 链直接跳过
+2. broad/medium → `ask_user` ≤3 轮：Scope（in/out）| Constraints（兼容/API/perf/test）| Definition of Done
+3. 派生 `execution_criteria`（3-6 条命令式规则）+ `task_decomposition`（outcome 子目标，`done_when` 客观可校验，绑定到 ralph 产物：verification.json / review.json / uat.md / test path）
+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-ralph continue`）
+5. 在链路末尾（evidence 产出步骤之后、milestone-complete/close-out 之前）追加 `{ type: "decision", decision: "post-goal-audit", retry_count: 0, max_retries: 2 }`。ralph-execute 在该节点动态生长 `steps[]` 以收敛未达成子目标
+6. **输出 `/goal` 绑定提示词（参考文档 + 内嵌 ralph 调用）：**
+   ```
+   📋 任务分解完成。复制下面一行设定目标，会话在子目标全部达成前不停：
+
+   /goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status 全部为 "done"（等价: {session_dir}/goal-checklist.md 末尾含 ALL_GOALS_DONE）。未达成时: 阅读 {session_dir}/goal-checklist.md 取得"执行准则/边界契约/子目标"作为行动手册, 然后调用 /maestro-ralph continue 推进下一步; 严禁手动执行 skill 或越界。
+   ```
+   `/goal` 仅用户可输入；判据以 status.json 为权威，哨兵为等价信号。
+
+### A_CREATE_SESSION
+
+1. Read `.workflow/state.json` for project context (phase, milestone)
+2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`:
+   ```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 }],
+     "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": "" }
+   ```
+   Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive; never break flat-chain readers)
+3. Initialize tracking via `track_tasks`. The decomposition goal is bound by the user via the emitted `/goal` prompt
+4. If `--super`: read `maestro-super.md`, follow it completely
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Auto-Yes Flag Map
+
+| Command | Auto Flag | Effect |
+|---------|-----------|--------|
+| maestro-init | `-y` | Skip interactive questioning |
+| maestro-analyze | `-y` | Skip scoping, auto-deepen |
+| maestro-brainstorm | `-y` | Skip questions, use 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 |
+| maestro-execute | `-y` | Skip confirmations, blocked auto-continue |
+| quality-auto-test | `-y` | Skip plan confirmation |
+| quality-test | `-y --auto-fix` | Auto-trigger gap-fix loop |
+| quality-retrospective | `-y` | Accept all routing recommendations |
+| maestro-milestone-complete | `-y` | Skip knowledge promotion |
+
+Unlisted commands have no auto flags.
+
+### Error Codes
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and project not initialized | Prompt or suggest maestro-init |
+| 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 |
+| 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 |
+
+### 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
+- [ ] status.json 为唯一真源；goal-checklist.md 为投影视图（Resume 区块内嵌 `/maestro-ralph continue`）；post-goal-audit 节点追加；/goal 提示词内含"读 checklist + 调 /maestro-ralph continue"双重指引
+- [ ] Chain selected and confirmed (or auto-confirmed)
+- [ ] Session dir created with status.json before execution; decomposition fields additive-only
+- [ ] Tracking via track_tasks (Claude); status.json steps[] grown dynamically by ralph-execute post-goal-audit
+- [ ] Auto flags propagated to supporting commands only
+- [ ] All chains dispatched via maestro-ralph-execute
+- [ ] Low-complexity intents routed to maestro-quick
+- [ ] (super) Requirements validated before roadmap
+- [ ] (super) Each milestone scored >= 80%
+
+</appendix>

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

@@ -0,0 +1,165 @@
+---
+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_file
+  - write_file
+  - shell
+  - find_files
+  - search
+  - ask_user
+---
+<!-- 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 |
+| 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>