pi-maestro-flow 0.2.0

package/skills/maestro/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: maestro
+description: "Auto-route intent to optimal command chain Arguments: <intent> [-y] [-c] [--dry-run] [--super]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion TodoWrite
+---
+
+<purpose>
+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>
+- [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` → `Skill("manage-status")`
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation, auto-skip on errors
+- `-c` / `--continue` — Resume previous session. **`-c` is reserved for `--continue` across all maestro commands** — downstream skills MUST NOT redefine `-c` for other purposes to prevent collision via transparent forwarding.
+- `--dry-run` — Show chain without executing
+- `--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 flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args
+4. **Decomposition contract — maestro owns** — `source=="maestro"` 的 session 由 maestro 拥有分解契约（`decomposition_owner="maestro"`）：S_DECOMPOSE 产出 additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)，下游 ralph 只消费不覆盖（当 `decomposition_owner == "maestro"` 时跳过二次提问，仅做 shape 校验 + 缺省字段补齐）
+5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
+6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `Skill("maestro-ralph")` handoff
+7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
+8. **Grill `-y` 透传** — `-y` auto mode 透传 `-y` 到 grill args（grill 自身 Auto mode 用代码代答），不删除 grill stage；grill 仍产出 grill-report/terminology/context-package 供下游 brainstorm
+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` 写入
+11. **schema** — `ralph_protocol_version: "2"` 标记 CLI-driven session；新增字段全部可选
+12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
+13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
+14. **禁止以上下文消耗为由中断执行** — harness 自动处理 context compression，以"上下文不足"或"避免 context overflow"为由中断属于 invariant violation
+15. **控制权优先级（范式治理）** — FSM（maestro/maestro-ralph）独占 session 生命周期 + step 排序 + cross-step decision 节点；Pipeline（plan/execute/analyze）只拥有自身 artifact GATE，由 ralph dispatch 时 GATE 失败 → `complete BLOCKED|NEEDS_RETRY`、自身 GATE 全过 → DONE；Router（maestro-next）只单次推荐，不得出现在 FSM step 内。
+</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: Skill({ skill: "maestro-ralph-execute" })
+
+S_FALLBACK:
+  → S_CLASSIFY    WHEN: user provides new intent           DO: AskUserQuestion
+  → 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 task_type via chain catalog (semantic)
+3. Select chain from chainMap，遵循拓扑约束：
+   - 压力测试/拷问/验证假设/grill/stress-test → `grill`（**-y 模式透传 `-y` 到 grill，grill 以 Auto mode 执行，不跳过**）
+   - 头脑风暴/探索 → `brainstorm`
+   - 学习/阅读代码/跟读/follow → `Skill("learn-follow")`；调查/为什么/investigate → `Skill("learn-investigate")`；分解/模式/decompose → `Skill("learn-decompose")`；评审/挑战/second-opinion → `Skill("learn-second-opinion")`；回顾/retro → `Skill("quality-retrospective")`
+   - 正式规格/spec-generate/7-phase → `blueprint`
+   - 项目初始化 → `init`
+   - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
+   - 数字 milestone 上下文 → `analyze {milestone}` → `plan {milestone}` → `execute {milestone}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → quality pipeline
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → quality pipeline
+4. 执行 step：`Bash("maestro ralph skills --platform claude --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
+
+### A_CLARIFY
+
+1. `AskUserQuestion` with parsed intent + available chain options
+2. Re-classify with user response
+
+### A_DECOMPOSE_TASKS
+
+设 `session.decomposition_owner = "maestro"`。下游 ralph 只消费不二次提问（invariant 4）。Condensed:
+
+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（execute/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
+6. **输出 `/goal` 绑定提示词（不阻塞，用户可在执行过程中随时输入）：**
+   ```
+   📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：
+
+   /goal 完成以下子目标：
+   {for each G in task_decomposition:}
+   - {G.id}: {G.goal} — 完成条件: {G.done_when}
+   {end for}
+   达成条件: {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
+
+0. **Specs 预检**：当 chain 包含 `analyze-macro` / `analyze` / `plan` / `execute` 等执行 stage 且 `.workflow/specs/` 目录不存在时，在 steps 最前面插入 `spec-setup`（stage=`spec-setup`，无 decision）。确保下游可获得项目约束规则注入。chain ∈ {grill, brainstorm, blueprint, init, status, quick} 时跳过
+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",
+     "ralph_protocol_version": "2", "active_step_index": null,
+     "phase", "phase_is_new": false, "milestone": "",
+     "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
+     "auto_mode": false, "decomposition_owner": "maestro", "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, "skill": "", "args": "",
+       "stage": "", "scope": null, "decision": null,
+       "command_scope": "global|project|missing|null", "command_path": "<abs> | null",
+       "milestone_id": null, "source_artifact_ref": null,
+       "status": "pending", "goal_ref": null,
+       "completion_confirmed": false, "completion_status": null,
+       "completion_evidence": null,
+       "completion_summary": null, "completion_decisions": null,
+       "completion_caveats": null, "completion_deferred": null,
+       "completed_at": null,
+       "deferred_reads": [], "load": null
+     }],
+     "waves": [], "current_step": 0, "status": "running",
+     "boundary_contract": {}, "execution_criteria": [],
+     "task_decomposition": [{ "status": "pending|done|superseded",
+       "superseded_by": null, "superseded_at": null, "origin": null }],
+     "task_decomposition_all_done": false,
+     "goal_changelog": []
+   }
+   ```
+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>
+
+</state_machine>
+
+<appendix>
+
+### 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 |
+| 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 |
+
+### Success Criteria
+
+- [ ] Intent classified with task_type, complexity, clarity_score
+- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / quality pipeline
+- [ ] `-y` 模式透传 `-y` 到 grill（grill 以 Auto mode 代码代答执行，stage 不跳过）
+- [ ] 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 为判据
+- [ ] Specs 预检：chain 含执行 stage + `.workflow/specs/` 不存在 → steps 最前面插入 `spec-setup`
+- [ ] Chain selected and confirmed (or auto-confirmed)
+- [ ] Session dir created with status.json before execution; decomposition fields additive-only
+- [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识
+- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global）
+- [ ] Session schema 含 `ralph_protocol_version: "2"` + `active_step_index: null` + step.load 占位
+- [ ] 用户传入 `-y` 时透传到 skill args
+- [ ] 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/skills/maestro-amend/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: maestro-amend
+description: "Generate overlays to fix workflow command deficiencies Arguments: [description] [--from-verify <dir>] [--from-review <dir>] [--from-session <id>] [--from-issues ISS-xxx,...] [--scan] [--dry-run] [-y]"
+allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+---
+
+<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.
+</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`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. NEVER modify `.claude/commands/*.md` directly — overlay installation is handled by `maestro overlay add`.
+</context>
+
+<invariants>
+1. **Non-invasive only** — amendments MUST use the overlay system (`~/.maestro/overlays/*.json`); direct edits to `.claude/commands/*.md` are NEVER permitted
+2. **Idempotent patches** — re-running the same amendment MUST produce identical overlay JSON; overlay markers prevent duplicate injection
+3. **Pristine source reads** — signal diagnosis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals), not installed copies
+4. **Code bugs excluded** — signals classified as code bugs MUST be routed to `/maestro-quick` or `/maestro-plan --gaps`, NEVER patched via overlay
+5. **User confirmation before install** — overlay JSON MUST be previewed and confirmed by the user before `maestro overlay add` runs (unless `-y`)
+6. **Section existence verified** — target section MUST be confirmed to exist in the pristine source before drafting a patch; missing sections trigger `new-section` mode
+</invariants>
+
+<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 |
+| Wrong/missing next-step routing | completion | replace / append |
+| Missing/wrong invariant | invariants | 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>

package/skills/maestro-analyze/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: maestro-analyze
+description: "Use when a topic needs structured multi-dimensional investigation before planning or decision-making Arguments: [milestone|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Multi-dimensional analysis of a proposal, decision, or architecture choice via CLI-assisted exploration and interactive discussion. Produces analysis.md (6-dimension scoring), context.md (Locked/Free/Deferred decisions), conclusions.json, and discussion.md with Go/No-Go recommendation. Use `--gaps` for issue root cause analysis feeding `plan --gaps`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/analyze.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (between Phase 4 and Phase 5)
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- milestone number for micro mode, topic text for macro/adhoc mode, no args for current milestone.
+
+**Dual-layer mode:**
+- **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
+- **Micro mode** (numeric argument): Milestone-level deep analysis within an existing roadmap. Covers all phases under the milestone. Same analysis depth, broader scope. `analyze 1` = Milestone 1.
+
+**Disambiguation rule (mode selection):**
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as milestone number)
+- First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
+- No positional arg → current milestone micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 milestone"` is treated as text → macro mode (only bare numerics trigger micro)
+
+**Flags:**
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive scoping, use recommended defaults, auto-deepen | false |
+| `-c` / `--continue` | Resume from existing session (auto-detect session folder + discussion.md) | false |
+| `-q` / `--quick` | Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only). **Precedence**: when combined with `-c`, the resumed session preserves its original mode (full or quick); `-q` does NOT override a resumed full session to quick mode. | false |
+| `--from <source>` | Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path) | — |
+| `--gaps [ISS-ID]` | Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl | — |
+
+**Scope routing:**
+| Input | Mode | Scope |
+|-------|------|-------|
+| Pure digits (e.g. `1`, `42`) | micro | Milestone-level deep analysis |
+| Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
+| No positional arg + roadmap | micro | Current milestone |
+| No positional arg + no roadmap | macro | Fallback |
+| `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
+
+Output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Output Structure section).
+
+### Pre-load
+
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro load --type spec --category arch` — load architecture constraints
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. All optional — proceed without if unavailable (log warning)
+
+### Role Knowledge
+`maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
+</context>
+
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold
+**Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
+**Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
+**Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
+**Additional skip conditions**: input is already specific (explicit milestone number or unambiguous topic)
+**Exit condition**: all decision points settled → finalize session metadata
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/analyze.md' completely.
+
+### --gaps Mode
+
+When `--gaps` is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard pipeline.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== ANALYSIS READY ===
+Artifact: ANL-{id}
+Scope: {micro|macro|adhoc|gaps}
+Go/No-Go: {GO|NO-GO|CONDITIONAL}
+Confidence: {high|medium|low}
+Outputs: analysis.md, context.md, conclusions.json, discussion.md
+Session dir: {output_dir}
+===
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {milestone}` |
+| Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
+| Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
+| Need more exploration | `/maestro-analyze {topic} -c` |
+| Gaps scope, issues analyzed | `/maestro-plan --gaps` |
+| Gaps scope, need more context | `/maestro-analyze --gaps {ISS-ID}` |
+
+### Session seal
+
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Prompt user for topic text or create roadmap first |
+| W001 | warning | CLI exploration failed | Continue with available context, note limitation |
+| W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
+| W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
+| W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+| E_NO_ISSUES | error | --gaps but no open/registered issues found | Suggest `/manage-issue-discover` or `/manage-issue create` |
+| E_ISSUE_NOT_FOUND | error | --gaps with ISS-ID but issue not found | Suggest `/manage-issue list` to find valid IDs |
+</error_codes>
+
+<success_criteria>
+Full mode:
+- [ ] CLI exploration completed with code anchors and call chains
+- [ ] discussion.md created with full timeline, TOC, Current Understanding
+- [ ] analysis.md written with all 6 dimensions scored with evidence
+- [ ] conclusions.json created with recommendations and decision trail
+- [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
+- [ ] Confidence tracking initialized (Step 4.6) and re-scored each round (Step 5.8)
+- [ ] Readiness gate checked before synthesis (Step 5.10)
+- [ ] Pressure pass completed ≥ 1 time before Step 6
+- [ ] Boundary grill executed between Phase 4 and Phase 5 (skip if no conflicts detected)
+- [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
+- [ ] Confidence summary with factor decomposition written to analysis.md
+
+Gaps mode:
+- [ ] Issues loaded from issues.jsonl (all open/registered, or single ISS-ID)
+- [ ] CLI exploration executed per issue with codebase context
+- [ ] Analysis record attached to each issue in issues.jsonl
+- [ ] context.md written with aggregated root causes for plan --gaps
+
+Both modes (full + quick):
+- [ ] Interactive mode: interview decision table written to `discussion.md` and mirrored into `context.md` "Interview Decisions"
+- [ ] context.md written with all decisions classified as Locked/Free/Deferred
+- [ ] Gray areas identified through phase-specific analysis
+- [ ] Decision Recording Protocol applied to all decisions
+- [ ] Scope creep redirected to Deferred section
+- [ ] Deferred items auto-created as issues (if any)
+- [ ] Artifact registered in state.json with correct scope/milestone
+- [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
+- [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
+</success_criteria>