maestro-flow 0.5.1 → 0.5.3

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

@@ -1,113 +1,113 @@
----
-name: learn-retro
-description: Retrospective of git activity and decision quality
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Unified retrospective combining git activity analysis and decision quality evaluation.
-Two lenses, usable independently or together:
-- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
-- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
-
-Works on raw git history and wiki/spec data — does not require completed phase artifacts.
-</purpose>
-
-<context>
-$ARGUMENTS — lens selection and scope flags.
-
-**Lens:** `--lens git` | `--lens decision` | `--lens all` (default)
-
-**Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
-**Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
-
-**Output**: `.workflow/knowhow/KNW-retro-{date}.md` + `KNW-retro-{date}.json`
-</context>
-
-<execution>
-
-### Phase 1: Parse + Select Lenses
-
-### Phase 2: Git Lens (skip if --lens decision)
-**Sequential data gathering** (parallel git commands):
-- Commit stats with shortstat
-- Per-commit numstat for test/production LOC split
-- Timestamps for session detection (>2hr gap clustering)
-- File hotspots (most frequently changed)
-- Per-author commit counts
-
-**Compute**: commits, LOC, test ratio, churn rate, active days, sessions, per-author breakdown.
-**Trend comparison** if prior `retro-*.json` exists.
-
-### Phase 3: Decision Lens (skip if --lens git)
-**3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
-**3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
-
-**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
-
-| id | perspective | focus |
-|----|------------|-------|
-| 1 | technical | Implementation vs intent, context drift. Grade: sound/degraded/violated |
-| 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
-| 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
-
-**output_schema**:
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "id":            { "type": "string" },
-    "result_status": { "type": "string", "enum": ["completed", "failed"] },
-    "perspective":   { "type": "string", "enum": ["technical", "cost", "hindsight"] },
-    "grade":         { "type": "string" },
-    "findings":      { "type": "string", "maxLength": 500 },
-    "error":         { "type": "string" }
-  },
-  "required": ["id", "result_status", "grade", "findings"]
-}
-```
-
-Merge: `result_status` → master `status`; copy `perspective`, `grade`, `findings`, `error`.
-
-**Shared termination contract** (embed in every instruction):
-```
-You MUST call report_agent_job_result EXACTLY ONCE before exiting.
-- Success → result_status=completed with concrete grade
-- Failure → result_status=failed with error message
-- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
-- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
-- Read-only analysis. Do NOT modify source files.
-Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
-```
-
-**3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
-
-### Phase 4: Unified Report
-Write `KNW-retro-{date}.md` + `KNW-retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
-
-### Phase 5: Persist
-Append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
-
-**Next steps:** `/learn-follow <path>`, `/quality-auto-test <area>`, `/learn-investigate <question>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Not inside git repo (git lens) | Navigate to git repo |
-| E002 | error | No commits in time window | Increase --days |
-| E003 | error | No decisions found (decision lens) | Check wiki/specs content |
-| W001 | warning | .workflow/knowhow/ not found | Auto-bootstrap |
-| W002 | warning | No prior retro for comparison | First retro establishes baseline |
-| W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
-</error_codes>
-
-<success_criteria>
-- [ ] Lens selection parsed correctly
-- [ ] Git lens: metrics computed, sessions detected, hotspots identified
-- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
-- [ ] Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json
-- [ ] .workflow/specs/learnings.md appended with insights (stable INS-ids)
-</success_criteria>
+---
+name: learn-retro
+description: Retrospective of git activity and decision quality
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation.
+Two lenses, usable independently or together:
+- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
+- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
+
+Works on raw git history and wiki/spec data — does not require completed phase artifacts.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens:** `--lens git` | `--lens decision` | `--lens all` (default)
+
+**Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
+**Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
+
+**Output**: `.workflow/knowhow/KNW-retro-{date}.md` + `KNW-retro-{date}.json`
+</context>
+
+<execution>
+
+### Phase 1: Parse + Select Lenses
+
+### Phase 2: Git Lens (skip if --lens decision)
+**Sequential data gathering** (parallel git commands):
+- Commit stats with shortstat
+- Per-commit numstat for test/production LOC split
+- Timestamps for session detection (>2hr gap clustering)
+- File hotspots (most frequently changed)
+- Per-author commit counts
+
+**Compute**: commits, LOC, test ratio, churn rate, active days, sessions, per-author breakdown.
+**Trend comparison** if prior `retro-*.json` exists.
+
+### Phase 3: Decision Lens (skip if --lens git)
+**3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
+**3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
+
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
+
+| id | perspective | focus |
+|----|------------|-------|
+| 1 | technical | Implementation vs intent, context drift. Grade: sound/degraded/violated |
+| 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
+| 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
+
+**output_schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "perspective":   { "type": "string", "enum": ["technical", "cost", "hindsight"] },
+    "grade":         { "type": "string" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "grade", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `perspective`, `grade`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete grade
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+**3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
+
+### Phase 4: Unified Report
+Write `KNW-retro-{date}.md` + `KNW-retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
+
+### Phase 5: Persist
+Append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
+
+**Next steps:** `$learn-follow <path>`, `$quality-auto-test <area>`, `$learn-investigate <question>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Not inside git repo (git lens) | Navigate to git repo |
+| E002 | error | No commits in time window | Increase --days |
+| E003 | error | No decisions found (decision lens) | Check wiki/specs content |
+| W001 | warning | .workflow/knowhow/ not found | Auto-bootstrap |
+| W002 | warning | No prior retro for comparison | First retro establishes baseline |
+| W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
+</error_codes>
+
+<success_criteria>
+- [ ] Lens selection parsed correctly
+- [ ] Git lens: metrics computed, sessions detected, hotspots identified
+- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
+- [ ] Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json
+- [ ] .workflow/specs/learnings.md appended with insights (stable INS-ids)
+</success_criteria>

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

@@ -1,116 +1,116 @@
----
-name: learn-second-opinion
-description: Get alternative perspectives -- review, challenge, or consult
-argument-hint: "[-y|--yes] [-c|--concurrency 3] [--continue] \"<target> [--mode review|challenge|consult]\""
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Structured second-opinion for code, decisions, or plans. Three modes:
-- **review** (default): 3 parallel persona agents independently assess target via spawn_agents_on_csv
-- **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
-- **consult**: interactive Q&A (no CSV wave — direct orchestration)
-
-Findings persist to `.workflow/specs/learnings.md`. Decoupled from phase lifecycle.
-</purpose>
-
-<context>
-$ARGUMENTS — target and optional flags.
-
-**Target resolution (auto-detected):**
-- File path → analyze file content
-- Wiki ID (`type-slug`) → fetch via `maestro wiki get`
-- `HEAD` / `staged` → analyze git diff
-- Phase number → analyze phase plan
-
-**Flags:**
-- `--mode review` — 3-persona parallel review (default)
-- `--mode challenge` — Adversarial single-agent analysis
-- `--mode consult` — Interactive Q&A session
-
-**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{date}.md`
-</context>
-
-<execution>
-
-### Phase 1: Resolve Target + Load Context
-Resolve target to content. Load specs, `maestro search`, prior lessons for context brief.
-
-### Phase 2: Execute Mode
-
-#### Review Mode (spawn_agents_on_csv)
-
-| id | persona | focus | grading |
-|----|---------|-------|---------|
-| 1 | pragmatist | Simplicity, YAGNI, maintenance cost, readability | complexity score, abstraction depth |
-| 2 | purist | Correctness, type safety, edge cases, error handling | error paths, type completeness |
-| 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
-| 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
-
-Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`). Wave 2: synthesis agent with wave 1 findings as prev_context.
-
-**output_schema** (both waves):
-
-```json
-{
-  "type": "object",
-  "properties": {
-    "id":            { "type": "string" },
-    "result_status": { "type": "string", "enum": ["completed", "failed"] },
-    "persona":       { "type": "string" },
-    "verdict":       { "type": "string", "enum": ["approve", "concern", "reject", ""] },
-    "confidence":    { "type": "string", "description": "0-100" },
-    "findings":      { "type": "string", "description": "JSON array of {severity, description, location, suggestion}, max 500 chars summary" },
-    "summary":       { "type": "string", "maxLength": 500 },
-    "error":         { "type": "string" }
-  },
-  "required": ["id", "result_status", "findings", "summary"]
-}
-```
-
-Merge: `result_status` → master `status`; copy `persona`, `verdict`, `confidence`, `findings`, `summary`, `error`.
-
-**Shared termination contract** (embed in every instruction):
-```
-You MUST call report_agent_job_result EXACTLY ONCE before exiting.
-- Success → result_status=completed with concrete verdict
-- Failure → result_status=failed with error message
-- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
-- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
-- Read-only analysis. Do NOT modify source files.
-Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
-```
-
-#### Challenge Mode
-Single agent via spawn_agents_on_csv (max_concurrency: 1) with the same `output_schema` + termination contract above. Adversarial analysis with forcing questions:
-- "What assumption would invalidate this entire approach?"
-- "What's the simplest thing that breaks this?"
-- "What's the implicit contract that isn't enforced?"
-
-#### Consult Mode
-Interactive loop via AskUserQuestion. Agent studies target, answers questions with code references. Compile Q&A into report on exit.
-
-### Phase 3: Persist
-1. Write `KNW-opinion-{slug}-{date}.md` with per-persona findings + synthesis
-2. Append non-trivial findings to `.workflow/specs/learnings.md` (source: "second-opinion")
-3. Display summary with verdict and next steps
-
-**Next steps:** `/manage-issue create`, `/learn-decompose <path>`, `/learn-follow <path>`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Target not resolvable | Verify path/ID |
-| E002 | error | Unknown --mode value | Use: review, challenge, consult |
-| W001 | warning | Persona agent failed — partial perspectives | Proceed with available agents |
-| W003 | warning | Git diff empty for HEAD/staged | Use file path instead |
-</error_codes>
-
-<success_criteria>
-- [ ] Target resolved and context loaded
-- [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
-- [ ] Synthesis produced with agreements, disagreements, verdict
-- [ ] Report written to `KNW-opinion-{slug}-{date}.md`
-- [ ] Non-trivial findings appended to `.workflow/specs/learnings.md`
-</success_criteria>
+---
+name: learn-second-opinion
+description: Get alternative perspectives -- review, challenge, or consult
+argument-hint: "[-y|--yes] [-c|--concurrency 3] [--continue] \"<target> [--mode review|challenge|consult]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Structured second-opinion for code, decisions, or plans. Three modes:
+- **review** (default): 3 parallel persona agents independently assess target via spawn_agents_on_csv
+- **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
+- **consult**: interactive Q&A (no CSV wave — direct orchestration)
+
+Findings persist to `.workflow/specs/learnings.md`. Decoupled from phase lifecycle.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → analyze file content
+- Wiki ID (`type-slug`) → fetch via `maestro wiki get`
+- `HEAD` / `staged` → analyze git diff
+- Phase number → analyze phase plan
+
+**Flags:**
+- `--mode review` — 3-persona parallel review (default)
+- `--mode challenge` — Adversarial single-agent analysis
+- `--mode consult` — Interactive Q&A session
+
+**Output**: `.workflow/knowhow/KNW-opinion-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Phase 1: Resolve Target + Load Context
+Resolve target to content. Load specs, `maestro search`, prior lessons for context brief.
+
+### Phase 2: Execute Mode
+
+#### Review Mode (spawn_agents_on_csv)
+
+| id | persona | focus | grading |
+|----|---------|-------|---------|
+| 1 | pragmatist | Simplicity, YAGNI, maintenance cost, readability | complexity score, abstraction depth |
+| 2 | purist | Correctness, type safety, edge cases, error handling | error paths, type completeness |
+| 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
+| 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
+
+Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`). Wave 2: synthesis agent with wave 1 findings as prev_context.
+
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "persona":       { "type": "string" },
+    "verdict":       { "type": "string", "enum": ["approve", "concern", "reject", ""] },
+    "confidence":    { "type": "string", "description": "0-100" },
+    "findings":      { "type": "string", "description": "JSON array of {severity, description, location, suggestion}, max 500 chars summary" },
+    "summary":       { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings", "summary"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `persona`, `verdict`, `confidence`, `findings`, `summary`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete verdict
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+#### Challenge Mode
+Single agent via spawn_agents_on_csv (max_concurrency: 1) with the same `output_schema` + termination contract above. Adversarial analysis with forcing questions:
+- "What assumption would invalidate this entire approach?"
+- "What's the simplest thing that breaks this?"
+- "What's the implicit contract that isn't enforced?"
+
+#### Consult Mode
+Interactive loop via request_user_input. Agent studies target, answers questions with code references. Compile Q&A into report on exit.
+
+### Phase 3: Persist
+1. Write `KNW-opinion-{slug}-{date}.md` with per-persona findings + synthesis
+2. Append non-trivial findings to `.workflow/specs/learnings.md` (source: "second-opinion")
+3. Display summary with verdict and next steps
+
+**Next steps:** `$manage-issue create`, `$learn-decompose <path>`, `$learn-follow <path>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Verify path/ID |
+| E002 | error | Unknown --mode value | Use: review, challenge, consult |
+| W001 | warning | Persona agent failed — partial perspectives | Proceed with available agents |
+| W003 | warning | Git diff empty for HEAD/staged | Use file path instead |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved and context loaded
+- [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
+- [ ] Synthesis produced with agreements, disagreements, verdict
+- [ ] Report written to `KNW-opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `.workflow/specs/learnings.md`
+</success_criteria>

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

@@ -2,7 +2,7 @@
 name: maestro
 description: Auto-route intent to optimal command chain
 argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--super]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -120,7 +120,7 @@ S_ABORTED:
   → END           DO: A_ABORT_REPORT
 
 S_FALLBACK:
-  → S_CLASSIFY    WHEN: user provides new intent            DO: AskUserQuestion
+  → S_CLASSIFY    WHEN: user provides new intent            DO: request_user_input
   → END           WHEN: user cancels
 
 </transitions>
@@ -259,7 +259,7 @@ Read `.workflow/state.json` and route by condition:
 
 ### A_CLARIFY_INTENT
 
-1. `AskUserQuestion` with available chain types
+1. `request_user_input` with available chain types
 2. Re-classify with user response
 
 ### A_DECOMPOSE_TASKS
@@ -267,7 +267,7 @@ Read `.workflow/state.json` and route by condition:
 与 maestro-ralph `A_DECOMPOSE_TASKS` 共享分解契约。Condensed:
 
 1. 分类意图广度。narrow / 单步 / `{status,init,quick}` 链跳过
-2. broad/medium → `AskUserQuestion` ≤3 轮：Scope / Constraints / Definition of Done
+2. broad/medium → `request_user_input` ≤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 产出步骤后、milestone-complete/close-out 前）追加 `decision:post-goal-audit`。S_DECISION_EVAL 据此动态生长 `steps[]`
@@ -282,7 +282,10 @@ Read `.workflow/state.json` and route by condition:
 
 1. Read `.workflow/state.json` 获取 phase / milestone（D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`；读最新 blueprint artifact 注入 `blueprint_id`
 2. Resolve chain's skill list from Chain Map (see appendix)
-3. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）:
+3. **Prevalidate via `Bash("maestro ralph skills --platform codex --json --quiet")`** 一次性拉取所有可用 codex skills（global `~/.codex/skills/` + project `.codex/skills/`，project 覆盖 global），匹配 skill 名得到：
+   - 命中 → `command_scope = "global" | "project"`，`command_path = <绝对 SKILL.md 路径>`
+   - 未命中 → `command_scope = "missing"`, `command_path = null`
+4. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）:
    ```json
    {
      "session_id", "source": "maestro", "intent", "task_type", "chain_name",
@@ -296,7 +299,7 @@ Read `.workflow/state.json` and route by condition:
        "skill": "", "args": "",
        "stage": "", "scope": null,
        "command_scope": "global|project|missing|null",
-       "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+       "command_path": "~/.codex/skills/{name}/SKILL.md | .codex/skills/{name}/SKILL.md | null",
        "milestone_id": null, "source_artifact_ref": null,
        "status": "pending", "goal_ref": null,
        "completion_confirmed": false, "completion_status": null,
@@ -310,8 +313,8 @@ Read `.workflow/state.json` and route by condition:
    }
    ```
    Decomposition fields written ONLY if A_DECOMPOSE_TASKS produced them (additive)
-4. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 列出缺失 skill
-5. Initialize tracking:
+5. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 列出缺失 skill
+6. Initialize tracking:
    - If decomposed: goal already registered by A_DECOMPOSE_TASKS. Else: `create_goal({ objective: "Maestro {chain}: {N} steps [{skill list}]" })`
    - `update_plan({ plan: steps.map(step => ({ step, status: "pending" })) })`
 

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

@@ -7,7 +7,7 @@ allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
 <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.
+Differs from `$maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
 </purpose>
 
 <required_reading>
@@ -29,7 +29,7 @@ $ARGUMENTS — optional description and/or source flags.
 | `--scan` | Auto-scan .workflow/ | Discover all workflow-related signals |
 | _(positional text)_ | User description | Direct observation |
 
-Multiple combinable. No flags + no description → interactive (scan + AskUserQuestion).
+Multiple combinable. No flags + no description → interactive (scan + request_user_input).
 
 **Control**: `--dry-run` (preview, don't install), `-y` (skip confirmations)
 
@@ -112,7 +112,7 @@ Per signal, determine:
 | 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).
+Classify: command deficiency → proceed; code bug → skip (suggest $maestro-quick).
 
 ### A_GROUP_OVERLAYS
 
@@ -142,7 +142,7 @@ On validation failure: fix JSON, retry (max 2).
 | 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 |
+| 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 |

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

@@ -2,7 +2,7 @@
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
 argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
-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>
@@ -36,7 +36,7 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 <interview_protocol>
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--continue`, or input is already specific (explicit phase number or unambiguous topic).
 
-- One decision per turn via AskUserQuestion with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
+- One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
 - Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro search`, Grep, Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately appended/updated in `context.md` "Interview Decisions" (and mirrored into `analysis.md` in full mode). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.

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

@@ -82,10 +82,10 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Need codebase analysis | /maestro-analyze {topic} --from blueprint:BLP-xxx |
-| Ready for roadmap | /maestro-roadmap --from blueprint:BLP-xxx |
-| Small scope, direct plan | /maestro-plan --from blueprint:BLP-xxx |
-| Need project setup | /maestro-init |
+| Need codebase analysis | $maestro-analyze {topic} --from blueprint:BLP-xxx |
+| Ready for roadmap | $maestro-roadmap --from blueprint:BLP-xxx |
+| Small scope, direct plan | $maestro-plan --from blueprint:BLP-xxx |
+| Need project setup | $maestro-init |
 </execution>
 
 <invariants>

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

@@ -1,8 +1,8 @@
 ---
 name: maestro-companion
-description: Knowledge companion — load context, record companion doc, capture insights, route to skills
+description: "Knowledge companion — load context, record companion doc, capture insights, route to skills"
 argument-hint: "[before|note|after|route] [--task <description>] [--type <task_type>] [--category <cat>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -414,8 +414,8 @@ If promotable entries exist, ask user:
 
 | Selection | Action |
 |-----------|--------|
-| Spec | `Skill({ skill: "spec-add" })` — guide user through category + content |
-| Knowhow | `Skill({ skill: "manage-knowhow-capture" })` — guide through type + content |
+| Spec | `$spec-add` — guide user through category + content |
+| Knowhow | `$manage-knowhow-capture` — guide through type + content |
 | Both | `spec-add` first, then `manage-knowhow-capture` |
 | Skip | Proceed to Step 4 |
 
@@ -449,7 +449,7 @@ Extract intent text from $ARGUMENTS after removing the `route` keyword.
 ### Step 2: Delegate to maestro-next
 
 ```
-Skill({ skill: "maestro-next", args: "<intent_text>" })
+$maestro-next "<intent_text>"
 ```
 
 Reuses maestro-next routing table and scoring logic to recommend the best single command.