pi-maestro-flow 0.2.0

package/skills/maestro-milestone-complete/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: maestro-milestone-complete
+description: "Archive completed milestone and prepare for next Arguments: [<milestone>]"
+allowed-tools: Read Write Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Archive passed milestone: validate, archive artifacts, extract knowhow, advance state.
+Requires audit PASS; produces milestone archive and learnings.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-complete.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when updating milestone_history and advancing state
+</deferred_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+If $ARGUMENTS is empty AND current_milestone is null → raise E001 with message "No milestone specified and no current_milestone set in state.json. Provide a milestone identifier as argument."
+
+**Requires:** `/maestro-milestone-audit` should have passed.
+
+**State files:**
+- `.workflow/state.json` — artifacts[], milestones[] (with `type` field: `"standard"` | `"adhoc"`), current_milestone, milestone_history[]
+- `.workflow/roadmap.md` — milestone structure (standard milestones only; adhoc milestones may not have roadmap)
+- `.workflow/milestones/{milestone}/audit-report.md` — audit results
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-complete.md' completely.
+
+Archive flow steps (validation, directory archival, artifact history, knowhow extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Validation → Archival**
+- REQUIRED: Audit report verified as PASS (E002 if not).
+- REQUIRED: No incomplete artifacts remain (E003 if any).
+- BLOCKED if: audit not passed (E002) or incomplete artifacts remain (E003) — cannot archive unvalidated milestone.
+
+**GATE 2: Archival → Knowhow Extraction**
+- REQUIRED: Scratch artifacts moved to `milestones/{M}/artifacts/`.
+- REQUIRED: Artifact entries archived to milestone_history in state.json.
+- BLOCKED if missing: artifacts not moved or history not updated — knowhow extraction needs archived artifacts as input.
+
+**GATE 3: Knowhow Extraction → State Advancement**
+- REQUIRED: Knowhow extraction attempted (may produce 0 entries — W001).
+- REQUIRED: `project.md` Context updated with milestone summary.
+- BLOCKED if missing: knowhow extraction not attempted or project.md not updated — state advancement requires completed knowledge capture.
+
+**GATE 4: State Advancement → Completion**
+- REQUIRED: AskUserQuestion confirmation before state.json advancement — show current milestone, next milestone (or null for adhoc), and artifacts to clear. User must confirm or abort.
+- REQUIRED: state.json updated — next milestone as current (standard) or current_milestone=null (adhoc) (after confirmation).
+- REQUIRED: Roadmap snapshot saved (standard only).
+- BLOCKED if missing: state.json not advanced — project remains stuck on completed milestone.
+
+### Knowledge Promotion Inquiry
+
+After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
+
+1. **High-frequency pattern detection**: Scan all `<spec-entry>` entries with `roles="implement"` for keyword overlap (≥2 entries sharing keywords):
+   → Ask: "Keyword '{keyword}' appears in {N} knowhow entries. Should this be promoted to a formal coding convention? (`/spec-add coding`)"
+
+2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
+   → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
+
+3. **Wiki island check**: AskUserQuestion "Run wiki-connect --fix to link newly extracted knowledge?" — execute `manage-wiki connect --fix` only if user confirms.
+
+Each promotion candidate requires explicit user confirmation via AskUserQuestion before writing:
+- **"Promote"** → invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
+- **"Skip"** → do not promote this candidate; proceed to next.
+- **"Skip all"** → skip remaining candidates.
+
+**Adhoc milestone (D-008):** When completing an adhoc milestone, skip roadmap snapshot and do not advance to next milestone. Set `current_milestone = null`, `status = "idle"`. Adhoc milestones are self-contained — no successor in roadmap chain.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== MILESTONE COMPLETE ===
+Milestone: {milestone_id}
+Status: ARCHIVED
+Artifacts archived: {count}
+Knowhow extracted: {count} entries
+Next milestone: {next_id | "none (adhoc)"}
+==============================
+```
+
+### 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 |
+|-----------|-----------|
+| Cut a release | `/maestro-milestone-release` |
+| Next milestone (standard) | `/maestro-analyze {next_milestone}` or `/maestro-plan {next_milestone}` |
+| View state | `/manage-status` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments |
+| E002 | error | Audit not passed | Run maestro-milestone-audit first |
+| E003 | error | Incomplete artifacts remain | Complete remaining work first |
+| W001 | warning | Knowhow extraction produced 0 entries | Review milestone work for missed learnings |
+| W002 | warning | Wiki-connect found unlinked knowledge islands | Run `manage-wiki connect --fix` manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Audit report verified as PASS
+- [ ] Scratch artifacts moved to milestones/{M}/artifacts/
+- [ ] Artifact entries archived to milestone_history
+- [ ] Knowhow extracted to specs/learnings.md
+- [ ] state.json updated: next milestone as current (standard) or current_milestone=null (adhoc), artifacts[] cleared
+- [ ] Roadmap snapshot saved (standard only; adhoc skips)
+- [ ] project.md Context updated with milestone summary
+</success_criteria>

package/skills/maestro-milestone-release/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: maestro-milestone-release
+description: "Bump version, generate changelog, tag milestone Arguments: [<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Package a completed milestone into a releasable version: version bump → changelog → tag → push.
+
+Pipeline position: downstream of `/maestro-milestone-complete`. Terminal command.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional explicit version string and flags.
+
+**Flags:**
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `<version>` | Explicit version (e.g. `1.2.0`). If omitted, version is derived from `--bump` or prompted | — |
+| `--bump patch\|minor\|major` | Semver bump relative to the current version | `minor` |
+| `--dry-run` | Compute the next version, changelog diff, and tag name without writing files or creating tags | `false` |
+| `--no-tag` | Skip git tag creation (version bump + changelog only) | `false` |
+| `--no-push` | Skip `git push --follow-tags` after tagging | `false` |
+
+**State files:**
+- `.workflow/state.json` -- milestone_history (last completed milestone), previous release version
+- `.workflow/milestones/{milestone}/summary.md` -- milestone summary (from `maestro-milestone-complete`)
+- `.workflow/milestones/{milestone}/audit-report.md` -- audit verdict (must be PASS)
+- `CHANGELOG.md` -- release notes file (created if missing)
+- Version manifest -- `package.json` / `pyproject.toml` / `Cargo.toml` / etc. (auto-detected)
+
+**Preconditions:**
+- Current milestone must be completed (audit PASS + `/maestro-milestone-complete` run)
+- Working tree must be clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Decision points**: version bump type (major / minor / patch / custom), changelog review and confirmation
+**Scope guard**: only release decisions; do not prejudge next milestone scope
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-release.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Validation → Version Bump**
+- REQUIRED: Target milestone identified from `state.json.milestone_history` (last entry with `status == "completed"`) or explicit `[milestone]` argument. E001 if no completed milestone found.
+- REQUIRED: Working tree clean (no uncommitted changes). E003 if dirty.
+
+**GATE 2: Version Bump → Changelog**
+- REQUIRED: Target version computed and greater than previous (E005 if not).
+- REQUIRED: Version manifest file(s) identified and accessible.
+
+**GATE 3: Changelog → Tag/Push**
+- REQUIRED: CHANGELOG.md entry written with milestone summary + grouped changes.
+- REQUIRED: AskUserQuestion confirmation before creating release commit — show version, changelog diff, and files to be committed. User must confirm or abort.
+- REQUIRED: Release commit created with conventional message (after confirmation).
+
+**GATE 4: Tag → Push → Completion**
+- REQUIRED: AskUserQuestion confirmation before git tag creation — show tag name and annotation (unless --no-tag). User must confirm or abort.
+- REQUIRED: Annotated git tag created (unless --no-tag) (after confirmation).
+- REQUIRED: AskUserQuestion confirmation before git push — show remote and refs to push (unless --no-push). User must confirm or abort.
+- REQUIRED: state.json updated with last_release_version + last_release_at.
+
+For `--dry-run`: print computed version, changelog diff, and tag name without side effects.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {milestone_name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries written to CHANGELOG.md
+Manifest:  {file_path} updated
+```
+
+### 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 |
+|-----------|-----------|
+| Release successful, starting next milestone | `/maestro-plan {next_milestone}` |
+| Want to view project dashboard | `/manage-status` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Current milestone not completed (no milestone-complete run) | Run `/maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `/maestro-milestone-audit` and resolve findings |
+| E003 | error | Working tree not clean (uncommitted changes) | Commit or stash changes, then retry |
+| E004 | error | Version manifest not found / unsupported | Add supported manifest or pass `<version>` explicitly with `--no-tag` |
+| E005 | error | Target version not greater than current (would break semver monotonicity) | Choose a higher version or run with explicit `<version>` |
+| W001 | warning | No changes detected since last release tag | Confirm whether release is still desired |
+| W002 | warning | Remote push failed (network / auth) | Retry manually with `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated (milestone complete, audit PASS, clean tree)
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated with new version
+- [ ] CHANGELOG.md contains new entry with milestone summary + grouped changes
+- [ ] Release commit created with conventional message
+- [ ] Annotated git tag created (unless `--no-tag`)
+- [ ] Commit + tag pushed to remote (unless `--no-push` or push failed → W002)
+- [ ] User confirmed before each destructive git operation (commit, tag, push) via AskUserQuestion
+- [ ] state.json updated with last_release_version + last_release_at timestamp (after AskUserQuestion confirmation)
+</success_criteria>

package/skills/maestro-next/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: maestro-next
+description: "Single-command recommendation — pick the best next command from the pool and execute it Arguments: <intent> [-y] [--dry-run] [--top N] [--list]"
+allowed-tools: Read Bash Glob Grep Skill AskUserQuestion
+---
+
+<purpose>
+解析 intent + project state → 路由表评分 → 推荐单个原子命令 → 确认后 `Skill()` 执行。
+不创建 session、不构建 chain、不写 status.json。
+</purpose>
+
+<context>
+$ARGUMENTS — 意图文本 + 可选 flags。
+
+**Flags:**
+- `-y` / `--yes` — 跳过确认，直接执行 top pick
+- `--dry-run` — 仅显示推荐结果，不执行
+- `--top N` — 显示前 N 个候选（默认 3）
+- `--list` — 仅列出可推荐命令池，不做推荐
+
+**候选池：** 仅 A_SCORE_CANDIDATES 路由表中列出的命令。管线编排器（`maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer`）**永远不在候选池**。
+</context>
+
+<invariants>
+1. **不创建 session / 不写 status.json / 不触发后续 chain** — 单次原子执行，产出由目标命令自行管理
+2. **管线编排器不在候选池** — 仅推荐原子命令
+3. **空 intent 或 "继续/下一步/next/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
+4. **字面命中路由表优先** — lifecycle 仅作加分；命中失败时 lifecycle 上升为决定性信号
+5. **参数传递** — 默认 intent 原文作为第一个 arg；用户可在确认环节修改；`-y` 仅当用户传入时透传到 skill args
+6. **`--list` 模式跳过 lifecycle 推断与评分**，仅按 workflow 簇分组列出全部候选
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE     — 解析 ARGUMENTS、提取 flags                       PERSIST: —
+S_STATE     — 读 project state、推断 lifecycle_position         PERSIST: —
+S_RANK      — 路由表评分、生成 top-N candidates                 PERSIST: —
+S_LIST      — `--list` 模式：分组展示候选池                     PERSIST: —
+S_PRESENT   — 显示 top pick + 备选 + 推荐理由 + 执行参数        PERSIST: —
+S_CONFIRM   — AskUserQuestion 选择/修改参数（auto_mode 跳过）    PERSIST: —
+S_EXECUTE   — `Skill({ skill, args })` 单次调用                 PERSIST: —
+S_FALLBACK  — intent 空且 clarification 失败                    PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_LIST       WHEN: --list flag
+  → S_STATE      WHEN: intent text present
+  → S_STATE      WHEN: keyword "continue"/"next"/"go"/"继续"/"下一步"/"接下来"
+  → S_PARSE      WHEN: no intent (max 1 clarify round)    DO: AskUserQuestion
+  → S_FALLBACK   WHEN: clarification empty
+
+S_STATE:
+  → S_RANK       DO: A_INFER_LIFECYCLE
+
+S_RANK:
+  → S_PRESENT    DO: A_SCORE_CANDIDATES
+
+S_LIST:
+  → END          DO: 按 workflow 簇分组列出全部候选 + description
+
+S_PRESENT:
+  → END          WHEN: --dry-run
+  → S_EXECUTE    WHEN: -y / --yes
+  → S_CONFIRM    WHEN: not auto_mode
+
+S_CONFIRM:
+  → S_EXECUTE    WHEN: 用户确认 top pick / 选备选 / 改参数
+  → END          WHEN: 用户取消
+
+S_EXECUTE:
+  → END          DO: Skill({ skill: <chosen>, args: <args> }) → 输出 "✅ 已执行 /<command>"
+
+S_FALLBACK:
+  → END          DO: raise E001
+
+</transitions>
+
+<actions>
+
+### A_INFER_LIFECYCLE
+
+读 project state 推断 `lifecycle_position`（核心信号）：
+
+```bash
+cat .workflow/state.json 2>/dev/null              # phase / milestone / artifacts
+ls -la .workflow/scratch/ 2>/dev/null | head -10  # 最近 artifact (mtime DESC)
+ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
+```
+
+**项目状态 → lifecycle_position → 自然下一步：**
+
+| 项目状态 | lifecycle_position | 自然下一步 |
+|---------|-------------------|-----------|
+| 无 `.workflow/` + 无源码 | brainstorm | `maestro-brainstorm` |
+| 无 `.workflow/` + 有源码 | init | `maestro-init` |
+| 有 state.json，无 roadmap，无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
+| 有 macro analyze artifact，无 roadmap | roadmap | `maestro-roadmap` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {milestone}` |
+| 最新 artifact = analyze | plan | `maestro-plan {milestone}` |
+| 最新 artifact = plan | execute | `maestro-execute {milestone}` |
+| 最新 artifact = execute | review | `quality-review {milestone}` |
+| review verdict=PASS | test-gen | `quality-auto-test {milestone}` |
+| 测试全绿 + current_milestone 存在 | milestone-audit | `maestro-milestone-audit` |
+| 测试全绿 + current_milestone=null (standalone) | review-done | 回退到 `quality-review` 或 `manage-status`（无 milestone 上下文时不推荐 milestone 命令） |
+| 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
+| 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
+
+**Maestro Lifecycle 主线：**
+```
+init → {grill | brainstorm | blueprint | analyze-macro} → roadmap
+   → [per milestone] analyze → plan → execute (includes verification)
+   → [quality gate] review → auto-test → test
+   → milestone-audit → milestone-complete → milestone-release
+```
+
+**quality vs odyssey 选型：**
+
+| 场景 | 推荐 | 原因 |
+|------|------|------|
+| Phase 工件链内的 bug/review/test | `quality-*` | 只读诊断，修复回流 plan→execute 主循环，保持 artifact 链完整 |
+| 独立探索性 bug、跨 phase 问题、非当前 milestone 问题 | `odyssey-debug` | 自带修复+泛化，scratch session 独立于 artifact 链 |
+| Phase 级代码审查（只读报告） | `quality-review` | 输出 verdict + issues，不改代码 |
+| 审查后要求零残留修复 | `odyssey-review-test-fix` | 自带 fix 循环直到零 finding |
+| Phase 级安全专项审计 | `security-audit` | OWASP Top 10 + STRIDE 全覆盖 |
+| 多维运行时质量改进 | `odyssey-improve` | 6 维并行审计 + 泛化 |
+| UI 视觉优化 | `odyssey-ui` | 含发散探索（Polish/Delight） |
+
+### A_SCORE_CANDIDATES
+
+**评分信号**（高→低）：
+
+| 信号 | 权重 | 说明 |
+|------|------|------|
+| intent 命中路由表关键词 | 高 | 字面匹配主依据 |
+| **lifecycle 自然下一步** | **高** | 空 intent / "继续" / "next" 时为决定性 |
+| `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
+| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
+| Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
+| **前置条件不满足** | **禁止** | 候选命令的前置条件未满足时，直接从候选池移除（如 `maestro-milestone-*` 在 `current_milestone=null` 时移除） |
+
+**前置条件检查（评分前执行，不满足则移除候选）：**
+
+| 命令 | 前置条件 |
+|------|---------|
+| `maestro-milestone-audit` | `current_milestone` 存在且非 null |
+| `maestro-milestone-complete` | `current_milestone` 存在且非 null |
+| `maestro-milestone-release` | `current_milestone` 存在且非 null |
+| `maestro-merge` | 存在活跃的 fork 分支 |
+
+**特殊意图处理：**
+
+| Intent 模式 | top pick |
+|------------|---------|
+| 空 / "继续" / "下一步" / "next" / "接下来" | lifecycle 自然下一步 |
+| "什么状态" / "现在到哪了" / "status" | `manage-status` |
+| 字面命中路由表 | 路由表优先（lifecycle 仅加分） |
+| 无任何匹配 | lifecycle 下一步 + raise W002 |
+
+**意图 → 命令路由表**（候选池）：
+
+| 意图关键词 | 推荐命令 |
+|-----------|---------|
+| 头脑风暴 / 探索 / brainstorm / ideate | `maestro-brainstorm` |
+| 规格 / 正式文档 / spec-generate / blueprint | `maestro-blueprint` |
+| 分析 / analyze / 多维度调研 | `maestro-analyze` |
+| 规划 / plan / 任务分解 | `maestro-plan` |
+| 实现 / 执行 / execute | `maestro-execute` |
+| 验证 / verify / 验收 | `maestro-execute` |
+| 调试 / debug / 排查 / bug | `quality-debug` |
+| 审查 / review / 代码审查 | `quality-review` |
+| 测试 / test / UAT | `quality-test` / `quality-auto-test` |
+| 重构 / refactor / 技术债 | `quality-refactor` |
+| 同步文档 / sync docs | `quality-sync` |
+| 回顾 / retro | `quality-retrospective` |
+| issue / 缺陷管理 | `manage-issue` / `manage-issue-discover` |
+| wiki / 知识图谱 | `manage-wiki` (含 connect/digest 子命令) |
+| spec / 规则 / 约束 | `spec-load` / `spec-add` / `spec-setup` |
+| 项目初始化 / init | `maestro-init` |
+| 状态 / status / 仪表盘 | `manage-status` |
+| 文档重建 / codebase 文档 | `manage-codebase-rebuild` / `quality-sync` |
+| 安全 / security / OWASP | `security-audit` |
+| 跟读 / 学习 / 阅读源码 | `learn-follow` / `learn-investigate` |
+| 第二意见 / challenge / consult | `learn-second-opinion` |
+| 提取知识 / harvest | `manage-harvest` / `manage-knowhow-capture` |
+| 设计 / UI / 前端打磨 | `maestro-impeccable` |
+| 里程碑 / milestone | `maestro-milestone-audit` / `maestro-milestone-release` / `maestro-milestone-complete` |
+| fork / 分支 / 并行开发 | `maestro-fork` / `maestro-merge` |
+| 覆盖层 / overlay / amend | `maestro-overlay` / `maestro-amend` |
+
+**辅助 workflow 簇**（场景触发，非主线）：
+
+| 簇 | 触发 | 主推链路 |
+|----|------|---------|
+| Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
+| Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
+| Wiki | 知识图谱整理 | `manage-wiki health` → `manage-wiki connect` → `manage-wiki digest` |
+| Issue | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
+| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-rebuild` (if major) |
+| 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
+| 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
+| 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
+
+输出 ranked candidates，取 top N（默认 3）。
+
+</actions>
+
+</state_machine>
+
+<presentation>
+
+### `--list` 模式
+
+按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示全部候选 + description，结束。
+
+### 正常模式
+
+```
+🎯 推荐 (top pick): /<command-name>
+   <description>
+   推荐理由: <命中规则 + lifecycle 位置一句话>
+
+备选:
+  2. /<alt-1> — <description>
+  3. /<alt-2> — <description>
+
+执行参数: <args>
+```
+
+`--dry-run` 展示后结束；`-y` 直接 S_EXECUTE；否则：
+
+AskUserQuestion (single-select, header: "执行确认"):
+- **执行推荐** (Recommended) — run top pick with shown args
+- **选择备选** — pick from alternative commands
+- **修改参数** — adjust args before executing
+- **取消** — do nothing
+
+</presentation>
+
+<appendix>
+
+### Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | intent 空且 clarification 后仍空 | 提供意图描述或使用 `--list` 浏览 |
+| E002 | error | 候选池为空（`.claude/commands/` 缺失或无 .md） | 检查 commands 目录 |
+| E003 | error | 选定命令名无法解析为有效 skill | 列出有效命令重选 |
+| W001 | warning | top1 与 top2 得分差距 < 阈值 | 强制展示前 3 让用户裁决 |
+| W002 | warning | intent 与所有候选匹配度均低 | 提示考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
+
+### Success Criteria
+
+- [ ] Intent 解析 + flags 提取完成
+- [ ] 读取 `.workflow/state.json` + scratch artifacts 推断 lifecycle_position
+- [ ] 候选池等于路由表（管线编排器不在）
+- [ ] 评分综合：intent 字面匹配 + lifecycle 下一步 + workflow 簇 + recent activity
+- [ ] 空 intent / "继续" / "下一步" → 直接采用 lifecycle 推断的下一步
+- [ ] top pick 展示附"推荐理由"（命中规则 + lifecycle 位置）
+- [ ] `--dry-run` 仅展示，不执行
+- [ ] `-y` 自动执行 top pick；用户传入时透传到 skill args
+- [ ] 非自动模式通过 AskUserQuestion 确认或选备选
+- [ ] 选定命令通过单次 `Skill()` 调用执行
+- [ ] 不创建 session / 不生成 status.json / 不触发后续 chain
+- [ ] `--list` 模式按 workflow 簇分组展示
+
+</appendix>