maestro-flow 0.5.0 → 0.5.2

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

@@ -2,7 +2,7 @@
 name: maestro-help
 description: Maestro Flow command help system — search, browse, recommend commands, skills, agents, CLI tools, and workflows
 argument-hint: "[search <keyword>|workflow|skills|agents|cli|新手|下一步|<command-name>]"
-allowed-tools: Read, Grep, Glob, AskUserQuestion
+allowed-tools: Read, Grep, Glob, request_user_input
 ---
 
 <purpose>
@@ -79,10 +79,10 @@ Mode 3 (Smart Recommendations) 需要检测项目状态：
 ```
 找到 N 个匹配命令：
 
-/maestro-analyze — 多维度分析
+$maestro-analyze — 多维度分析
   分类: pipeline | 查看详情 →
 
-/maestro-plan — 任务规划
+$maestro-plan — 任务规划
   分类: pipeline | 查看详情 →
 ...
 ```
@@ -90,7 +90,7 @@ Mode 3 (Smart Recommendations) 需要检测项目状态：
 ### Mode 2: Command Documentation
 
 1. 在 `catalog.json` commands[] 中定位命令
-2. 通过 `source` 路径读取命令源文件（如 `../../commands/maestro-analyze.md`）
+2. 通过 `source` 路径读取命令源文件（如 `../../commands$maestro-analyze.md`）
 3. 提取 `<purpose>`、`argument-hint`、`<context>` 中的用法示例
 4. 如有对应 guide 文档，读取相关段落
 
@@ -108,16 +108,16 @@ Guide 映射：
 
 | 当前状态 | 推荐命令 | 原因 |
 |---------|---------|------|
-| 无 .workflow/ | `/maestro-init` | 项目未初始化 |
-| init 完成，无上游 context | `/maestro-brainstorm` 或 `/maestro-analyze "topic"` | 先探索再规划；brainstorm 发散，analyze 宏观探索影响面 |
-| analyze 完成，scope_verdict=large | `/maestro-roadmap --from analyze:ANL-xxx` | 大范围需求，需要 Milestone > Phase 分解 |
-| analyze 完成，scope_verdict=medium/small | `/maestro-plan --from analyze:ANL-xxx` | 跳过 roadmap 直达规划（Path C） |
-| roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
-| analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
-| plan 完成 | `/maestro-execute` | 开始执行 |
-| execute 完成 | `/quality-review` | 进入质量管线 |
-| quality 全通过 | `/maestro-milestone-audit` | 里程碑审计 |
-| 所有 Phase 完成 | `/maestro-milestone-complete` | 关闭里程碑 |
+| 无 .workflow/ | `$maestro-init` | 项目未初始化 |
+| init 完成，无上游 context | `$maestro-brainstorm` 或 `$maestro-analyze "topic"` | 先探索再规划；brainstorm 发散，analyze 宏观探索影响面 |
+| analyze 完成，scope_verdict=large | `$maestro-roadmap --from analyze:ANL-xxx` | 大范围需求，需要 Milestone > Phase 分解 |
+| analyze 完成，scope_verdict=medium/small | `$maestro-plan --from analyze:ANL-xxx` | 跳过 roadmap 直达规划（Path C） |
+| roadmap 完成，phase=pending | `$maestro-analyze 1` | 微观分析：Phase 级深入探索 |
+| analyze (微观) 完成 | `$maestro-plan 1` | Phase 级规划 |
+| plan 完成 | `$maestro-execute` | 开始执行 |
+| execute 完成 | `$quality-review` | 进入质量管线 |
+| quality 全通过 | `$maestro-milestone-audit` | 里程碑审计 |
+| 所有 Phase 完成 | `$maestro-milestone-complete` | 关闭里程碑 |
 
 ### Mode 4: Workflow Guide
 
@@ -134,7 +134,7 @@ Guide 映射：
 
 **Path D — 小改动**:
 - `plan "fix auth bug"` → `execute` → `quality-review`
-- 快速: `/maestro-quick "功能描述"`
+- 快速: `$maestro-quick "功能描述"`
 - 全自动: `/maestro -y "功能描述"`
 
 **Path E/F — 纯文档/纯探索**:
@@ -142,12 +142,12 @@ Guide 映射：
 - `brainstorm "idea"` → (供人决策)
 
 **Bug 修复**:
-- 快速: `/maestro-quick "Bug 描述"`
+- 快速: `$maestro-quick "Bug 描述"`
 - Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
 
 **代码审查**:
-- `/quality-review` → `/quality-auto-test` → `/quality-test`
-- 失败循环: `/quality-debug` → `/maestro-plan --gaps` → `/maestro-execute`
+- `$quality-review` → `$quality-auto-test` → `$quality-test`
+- 失败循环: `$quality-debug` → `$maestro-plan --gaps` → `$maestro-execute`
 
 ### Mode 5: Beginner Onboarding
 
@@ -155,20 +155,20 @@ Guide 映射：
 
 | 命令 | 用途 | 何时使用 |
 |------|------|---------|
-| `/maestro` | 智能协调器 | 不确定用哪个命令时 |
-| `/maestro-init` | 初始化项目 | 首次使用 |
-| `/maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
-| `/maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
-| `/maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
-| `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
-| `/maestro-plan` | 规划 | 分析完成后，支持 `--from analyze:ANL-xxx` 直达 |
-| `/maestro-execute` | 执行 | 计划完成后 |
-| `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| `$maestro` | 智能协调器 | 不确定用哪个命令时 |
+| `$maestro-init` | 初始化项目 | 首次使用 |
+| `$maestro-brainstorm` | 头脑风暴 | 新项目发散探索、多角色创意 |
+| `$maestro-blueprint` | 规格文档化 | 正式 7-phase 收敛规格链 |
+| `$maestro-analyze` | 双层分析 | 宏观: `"topic"` 探索影响面；微观: `1` Phase 级深入 |
+| `$maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
+| `$maestro-plan` | 规划 | 分析完成后，支持 `--from analyze:ANL-xxx` 直达 |
+| `$maestro-execute` | 执行 | 计划完成后 |
+| `$maestro-quick` | 快速任务 | 简单任务跳过管线 |
 
 快速上手路径：
 1. `maestro install --force`
-2. `/maestro-init`
-3. `/maestro "任务描述"` — 自动选择最佳工作流
+2. `$maestro-init`
+3. `$maestro "任务描述"` — 自动选择最佳工作流
 
 ### Mode 6: Skill & Agent Browsing
 
@@ -208,7 +208,7 @@ Guide 映射：
 | E001 | error | catalog.json 读取失败 | 回退到 Glob 扫描 .claude/commands/*.md |
 | W001 | warning | 搜索无结果 | 模糊匹配最近命令，建议查看全部 |
 | W002 | warning | Source 文件不存在 | 仅展示 catalog 描述 |
-| W003 | warning | 项目未初始化 | 推荐先运行 /maestro-init |
+| W003 | warning | 项目未初始化 | 推荐先运行 $maestro-init |
 </error_codes>
 
 <success_criteria>

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

@@ -123,7 +123,7 @@ Write collected configuration to `.workflow/config.json`.
 Run `Bash("maestro spec init")` to create empty seed files in `.workflow/specs/`.
 
 If project state is **code** (existing source files detected in Step 2):
-- Auto-trigger `Skill({ skill: "spec-setup" })` to scan codebase and populate specs with detected conventions
+- Auto-trigger `$spec-setup` to scan codebase and populate specs with detected conventions
 - This runs unconditionally for `code` state — existing source means conventions can be extracted
 
 If project state is **empty** (greenfield, no source files found in Step 2):

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

@@ -1,80 +1,80 @@
----
-name: maestro-learn
-description: Route learning intent to learn-* commands
-argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain.
-Executes commands sequentially with session tracking.
-
-```
-Intent → Route to Chain → Execute Steps → Session Summary
-```
-</purpose>
-
-<context>
-$ARGUMENTS — learning intent text, or flags.
-
-**Flags:**
-- `-y, --yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force specific chain
-
-**Chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer "how/why" questions |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Session state:** `.workflow/knowhow/.maestro-learn/{session_id}/status.json`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-**Intent routing:**
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| read, follow, walk through, understand | `follow` |
-| why, how, what if, investigate | `investigate` |
-| pattern, decompose, catalog | `decompose` |
-| opinion, review, challenge, consult | `second-opinion` |
-| retro, git, commit, decision | `retro` |
-| thorough, deep | `deep-understand` |
-
-No match → present menu via AskUserQuestion. Max 1 clarification.
-
-### Step 2: Resolve Target & Build Args
-Map chain to skill invocations. Extract target and flags from arguments.
-
-### Step 3: Confirm & Execute
-- `--dry-run`: display chain and exit
-- Not `-y`: show plan, ask confirmation
-- Execute each step sequentially. On failure: retry/skip/abort
-- Write session `status.json`, display summary
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No intent provided | Provide learning goal or use --chain |
-| E002 | error | Cannot determine intent | Rephrase or use --chain |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous | Present options |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed
-- [ ] Session summary displayed with next-step routing
-</success_criteria>
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain.
+Executes commands sequentially with session tracking.
+
+```
+Intent → Route to Chain → Execute Steps → Session Summary
+```
+</purpose>
+
+<context>
+$ARGUMENTS — learning intent text, or flags.
+
+**Flags:**
+- `-y, --yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force specific chain
+
+**Chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer "how/why" questions |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Session state:** `.workflow/knowhow/.maestro-learn/{session_id}/status.json`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+**Intent routing:**
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| read, follow, walk through, understand | `follow` |
+| why, how, what if, investigate | `investigate` |
+| pattern, decompose, catalog | `decompose` |
+| opinion, review, challenge, consult | `second-opinion` |
+| retro, git, commit, decision | `retro` |
+| thorough, deep | `deep-understand` |
+
+No match → present menu via request_user_input. Max 1 clarification.
+
+### Step 2: Resolve Target & Build Args
+Map chain to skill invocations. Extract target and flags from arguments.
+
+### Step 3: Confirm & Execute
+- `--dry-run`: display chain and exit
+- Not `-y`: show plan, ask confirmation
+- Execute each step sequentially. On failure: retry/skip/abort
+- Write session `status.json`, display summary
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent provided | Provide learning goal or use --chain |
+| E002 | error | Cannot determine intent | Rephrase or use --chain |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous | Present options |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed
+- [ ] Session summary displayed with next-step routing
+</success_criteria>

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

@@ -1,76 +1,76 @@
----
-name: maestro-merge
-description: Merge milestone worktree branch back to main
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Merge a completed milestone worktree branch back into main, sync scratch artifacts,
-and reconcile artifact registry. Two-phase approach: git merge first (source code),
-artifact sync second (only after git succeeds). Prevents partial state corruption
-when merge conflicts occur.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS — milestone number and optional flags.
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number
-- `--force`: Merge even if milestone has incomplete artifacts
-- `--dry-run`: Show what would be merged
-- `--no-cleanup`: Keep worktree and branch after merge
-- `--continue`: Resume merge paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check → 2. Milestone artifact completeness validation →
-3. Pre-merge rebase → 4. Git merge (source) → 5. Scratch artifact sync →
-6. Artifact registry reconciliation → 7. Cleanup
-
-**Phase 2 detail:**
-- Copy worktree `scratch/*` to main `.workflow/scratch/`
-- Merge `state.json.artifacts[]` entries (worktree wins for same id)
-- Remove milestone `"forked"` flag in main state.json
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Knowledge inquiry on completion:**
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `maestro spec add learning "<title>" "<insight>" --keywords <kw1>,<kw2> --description "<summary>"`.
-
-**Next steps:**
-- View dashboard → `$manage-status`
-- Audit milestone → `$maestro-milestone-audit`
-</execution>
-
-<invariants>
-**Phase order enforcement** — git merge MUST complete before artifact sync. Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
-</invariants>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number | Provide `-m <N>` |
-| W001 | warning | Stale registry entries | Auto-cleaned |
-| W002 | warning | Incomplete artifacts without --force | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed
-- [ ] Pre-merge rebase successful
-- [ ] Git merge completed (or conflicts resolved via --continue)
-- [ ] Scratch artifacts synced to main `.workflow/scratch/`
-- [ ] `state.json.artifacts[]` reconciled (worktree entries merged)
-- [ ] Milestone `"forked"` flag removed
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated
-</success_criteria>
+---
+name: maestro-merge
+description: Merge milestone worktree branch back to main
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Merge a completed milestone worktree branch back into main, sync scratch artifacts,
+and reconcile artifact registry. Two-phase approach: git merge first (source code),
+artifact sync second (only after git succeeds). Prevents partial state corruption
+when merge conflicts occur.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--force`: Merge even if milestone has incomplete artifacts
+- `--dry-run`: Show what would be merged
+- `--no-cleanup`: Keep worktree and branch after merge
+- `--continue`: Resume merge paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check → 2. Milestone artifact completeness validation →
+3. Pre-merge rebase → 4. Git merge (source) → 5. Scratch artifact sync →
+6. Artifact registry reconciliation → 7. Cleanup
+
+**Phase 2 detail:**
+- Copy worktree `scratch/*` to main `.workflow/scratch/`
+- Merge `state.json.artifacts[]` entries (worktree wins for same id)
+- Remove milestone `"forked"` flag in main state.json
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Knowledge inquiry on completion:**
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `maestro spec add learning "<title>" "<insight>" --keywords <kw1>,<kw2> --description "<summary>"`.
+
+**Next steps:**
+- View dashboard → `$manage-status`
+- Audit milestone → `$maestro-milestone-audit`
+</execution>
+
+<invariants>
+**Phase order enforcement** — git merge MUST complete before artifact sync. Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
+</invariants>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| W001 | warning | Stale registry entries | Auto-cleaned |
+| W002 | warning | Incomplete artifacts without --force | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed
+- [ ] Pre-merge rebase successful
+- [ ] Git merge completed (or conflicts resolved via --continue)
+- [ ] Scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged)
+- [ ] Milestone `"forked"` flag removed
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] Registry updated
+</success_criteria>

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

@@ -1,74 +1,74 @@
----
-name: maestro-milestone-release
-description: Bump version, generate changelog, tag milestone
-argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Package a completed milestone into a releasable version. Bumps project version in manifest,
-generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
-git tag, optionally pushes to remote. Runs after `/maestro-milestone-complete`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-release.md
-</required_reading>
-
-<context>
-$ARGUMENTS — optional explicit version and flags.
-
-**Flags:**
-- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
-- `--bump patch|minor|major` — Semver bump (default: `minor`)
-- `--dry-run` — Compute version + changelog without writing
-- `--no-tag` — Skip git tag creation
-- `--no-push` — Skip `git push --follow-tags`
-
-**Preconditions:**
-- Current milestone completed (audit PASS + milestone-complete run)
-- Working tree clean (no uncommitted changes) unless `--dry-run`
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-release.md' completely.
-
-**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
-Bump manifest → Commit → Tag → Push
-
-**Report:**
-```
-=== RELEASE COMPLETE ===
-Version:   v{previous} → v{new}
-Milestone: {name}
-Tag:       v{new} {pushed|local-only}
-Changelog: {N} entries
-```
-</execution>
-
-<invariants>
-**Prerequisite enforcement** — milestone MUST be completed (audit PASS + milestone-complete run). Working tree MUST be clean. Artifact verification: CHANGELOG.md entry, version manifest update, release commit, git tag (unless --no-tag) all MUST exist before reporting completion.
-</invariants>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
-| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
-| E003 | error | Working tree not clean | Commit or stash changes |
-| E004 | error | Version manifest not found | Add manifest or pass explicit version |
-| E005 | error | Version not greater than current | Choose higher version |
-| W001 | warning | No changes since last tag | Confirm release is desired |
-| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
-</error_codes>
-
-<success_criteria>
-- [ ] Preconditions validated
-- [ ] Target version computed and greater than previous
-- [ ] Version manifest(s) updated
-- [ ] CHANGELOG.md entry with milestone summary + grouped changes
-- [ ] Release commit created
-- [ ] Annotated git tag created (unless --no-tag)
-- [ ] Pushed to remote (unless --no-push)
-- [ ] state.json updated with last_release_version
-</success_criteria>
+---
+name: maestro-milestone-release
+description: Bump version, generate changelog, tag milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps project version in manifest,
+generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
+git tag, optionally pushes to remote. Runs after `$maestro-milestone-complete`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS — optional explicit version and flags.
+
+**Flags:**
+- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
+- `--bump patch|minor|major` — Semver bump (default: `minor`)
+- `--dry-run` — Compute version + changelog without writing
+- `--no-tag` — Skip git tag creation
+- `--no-push` — Skip `git push --follow-tags`
+
+**Preconditions:**
+- Current milestone completed (audit PASS + milestone-complete run)
+- Working tree clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-release.md' completely.
+
+**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
+Bump manifest → Commit → Tag → Push
+
+**Report:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries
+```
+</execution>
+
+<invariants>
+**Prerequisite enforcement** — milestone MUST be completed (audit PASS + milestone-complete run). Working tree MUST be clean. Artifact verification: CHANGELOG.md entry, version manifest update, release commit, git tag (unless --no-tag) all MUST exist before reporting completion.
+</invariants>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
+| E003 | error | Working tree not clean | Commit or stash changes |
+| E004 | error | Version manifest not found | Add manifest or pass explicit version |
+| E005 | error | Version not greater than current | Choose higher version |
+| W001 | warning | No changes since last tag | Confirm release is desired |
+| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated
+- [ ] CHANGELOG.md entry with milestone summary + grouped changes
+- [ ] Release commit created
+- [ ] Annotated git tag created (unless --no-tag)
+- [ ] Pushed to remote (unless --no-push)
+- [ ] state.json updated with last_release_version
+</success_criteria>

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

@@ -2,7 +2,7 @@
 name: maestro-player
 description: Play workflow templates with checkpoint resume
 argument-hint: "<template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -123,7 +123,7 @@ S_COMPLETE:
 
 1. Resolve template: absolute/relative/slug → index.json lookup
 2. Parse --context key=value, validate template JSON
-3. Collect missing required vars via AskUserQuestion
+3. Collect missing required vars via request_user_input
 4. Bind {variable} placeholders (leave {N-xxx.field}/{prev_*} for runtime)
 
 ### A_INIT_SESSION
@@ -135,7 +135,7 @@ S_COMPLETE:
 
 ### A_EXECUTE_WAVE
 
-1. **Checkpoint**: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: AskUserQuestion (Continue/Pause/Abort).
+1. **Checkpoint**: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: request_user_input (Continue/Pause/Abort).
 
 2. **Skill nodes**: resolve runtime references → write wave-{N}.csv (only rows with status == "pending") → spawn:
 ```