maestro-flow 0.5.0 → 0.5.2

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.
@@ -234,7 +234,7 @@ Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specif
 1. Export results.csv
 2. **Confidence scoring** (full mode): factors -- findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Thresholds: <60% deeper, 60-80% optional, 80-95% converging, >95% converge.
 3. Auto-create issues from Deferred items -> issues.jsonl
-4. Spec enrichment: Locked decisions -> `maestro spec add arch`; code patterns -> `maestro spec add coding`
+4. Spec enrichment: Locked decisions -> `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`; code patterns -> `maestro spec add coding "<title>" "<content>" --keywords <kw> --description "<summary>"`
 5. Register artifact in state.json (type: analyze, includes context_package field pointing to context-package.json)
 6. Copy outputs to scratchDir, display summary
 7. **Next-step routing** (D-003 §5.3 — macro scope uses `scope_verdict` for downstream chain selection):

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-collab/SKILL.md

@@ -275,7 +275,7 @@ Generate 3 output files from cross-verify results:
 
 1. Copy outputs to scratchDir
 2. Register CLB artifact in state.json (type: collab, scope: adhoc)
-3. Spec enrichment: for each Locked decision → `maestro spec add arch`
+3. Spec enrichment: for each Locked decision → `maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>"`
 4. `update_plan` all steps completed
 5. Display summary:
    ```

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

@@ -2,7 +2,7 @@
 name: maestro-companion
 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.

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

@@ -1,217 +1,217 @@
----
-name: maestro-composer
-description: Compose reusable workflow templates from natural language
-argument-hint: "\"workflow description\" [--resume] [--edit <template-path>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Interactive workflow template composer. Parses natural language into a reusable DAG template
-via 5 phases with user confirmation at each boundary. Templates saved globally at
-`~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
-
-Sequential interactive flow (no spawn_agents_on_csv — this is design, not execution):
-```
-Parse NL → [confirm] → Resolve to nodes → [confirm] → Inject checkpoints → Confirm pipeline → Persist
-```
-
-Three entry modes:
-1. **New design**: Phase 1-5
-2. **Resume design**: Load draft from `.workflow/templates/design-drafts/`
-3. **Edit template**: Load existing, modify, re-save
-</purpose>
-
-<context>
-$ARGUMENTS — natural language workflow description, or flags.
-
-**Flags:**
-- `--resume` — Resume in-progress design session
-- `--edit <template-path>` — Edit an existing template
-
-**Shared constants:**
-
-| Constant | Value |
-|----------|-------|
-| Session prefix | `WFD` |
-| Template dir (global) | `~/.maestro/templates/workflows/` |
-| Template index (global) | `~/.maestro/templates/workflows/index.json` |
-| Design drafts dir (local) | `.workflow/templates/design-drafts/` |
-| Template ID format | `wft-<slug>-<YYYYMMDD>` |
-| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
-| Max nodes | 20 |
-
-**Entry routing:**
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Resume | `--resume` or existing WFD session | Phase 0: Resume |
-| Edit | `--edit <path>` | Phase 0: Load + Edit |
-| New | Default | Phase 1: Parse |
-
-**Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
-**Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
-
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
-2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
-3. Optional — proceed without if unavailable.
-</context>
-
-<execution>
-
-### Phase 0: Resume / Edit (conditional)
-
-**Resume** (`--resume`):
-1. Scan `.workflow/templates/design-drafts/WFD-*/` for in-progress designs
-2. Multiple → AskUserQuestion for selection
-3. Load draft → skip to last incomplete phase
-
-**Edit** (`--edit <path>`):
-1. Load template JSON
-2. Show pipeline visualization (Phase 4 format)
-3. AskUserQuestion: which nodes to modify/add/remove
-4. Re-enter at Phase 3
-
----
-
-### Phase 1: Parse — Semantic Intent Extraction
-
-**Step 1.1** — Parse `$ARGUMENTS`. If empty, AskUserQuestion:
-```
-"Describe the workflow you want to automate.
-Include: what steps to run, in what order, and what varies each time.
-Example: 'analyze the code, then plan, implement, and test the feature'"
-```
-
-**Step 1.2** — Extract sequential actions as candidate nodes:
-
-| Signal | Candidate Type |
-|--------|---------------|
-| "analyze", "review", "explore" | analysis (cli) |
-| "plan", "design", "spec" | planning (skill) |
-| "implement", "build", "code", "fix" | execution (skill) |
-| "test", "validate", "verify" | testing (skill) |
-| "brainstorm", "ideate" | brainstorm (skill) |
-| "review code" | review (skill) |
-| "then", "next", "after" | sequential edge |
-| "parallel", "simultaneously" | parallel edge |
-
-**Step 1.3** — Extract variables (inputs that vary per run).
-
-**Step 1.4** — Classify task type: `bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap | refactor | integration-test | quick-task | custom`
-
-**Step 1.5** — Assess complexity: `simple` (1-3 nodes), `medium` (4-7), `complex` (8+)
-
-**Step 1.6** — Write `intent.json` to `.workflow/templates/design-drafts/WFD-<slug>-<date>/`.
-
-**Step 1.7 — Interactive confirmation**: Display description, task type, complexity, detected steps (numbered with type_hint), and variables. AskUserQuestion: `Continue to resolution` / `Edit steps` / `Add a step` / `Cancel`
-
----
-
-### Phase 2: Resolve — Map Steps to Executor Nodes
-
-**Read deferred**: `~/.maestro/templates/workflows/specs/node-catalog.md`
-
-If spec not found, use built-in fallback:
-
-| type_hint | executor type | executor |
-|-----------|--------------|----------|
-| `planning` | skill | `maestro-plan` |
-| `execution` | skill | `maestro-execute` |
-| `testing` | skill | `quality-test` |
-| `review` | skill | `quality-review` |
-| `brainstorm` | skill | `maestro-brainstorm` |
-| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
-| `refactor` | skill | `quality-refactor` |
-| `debug` | skill | `quality-debug` |
-| `spec` | skill | `maestro-blueprint` |
-| `checkpoint` | checkpoint | — |
-
-**Step 2.1** — Load `intent.json`, map each step to executor.
-
-**Step 2.2** — Build `args_template` with variable placeholders and context injection:
-- Planning after analysis → `--context {prev_output_path}`
-- Execution after planning → inherit phase
-- Testing after execution → inherit phase
-
-**Step 2.3** — Assign `parallel_group` for parallel steps.
-
-**Step 2.4** — Write `nodes.json`.
-
-**Step 2.5 — Interactive confirmation**: Display resolved nodes table (ID, type, executor, args) and parallel groups. AskUserQuestion: `Continue to checkpoint injection` / `Change executor` / `Change node type` / `Back to intent` / `Cancel`
-
----
-
-### Phase 3: Enrich — Inject Checkpoints + Build DAG
-
-**Step 3.1** — Load `nodes.json`. Build sequential edges. For parallel groups: fan-out/fan-in.
-
-**Step 3.2** — Auto-inject checkpoint nodes:
-
-| Rule | Condition |
-|------|-----------|
-| Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
-| Execution gate | Target executor contains `execute` |
-| Agent spawn | Target type is `agent` |
-| Long-running | Target is maestro-plan, maestro-roadmap |
-| User-defined | Step had `type_hint: checkpoint` |
-| Post-testing | Source executor contains `test` or `integration-test` |
-
-Set `auto_continue: false` for checkpoints before user-facing deliverables.
-
-**Step 3.3** — Finalize `context_schema`, validate DAG (no cycles, no orphans).
-
-**Step 3.4** — Write `dag.json`. → Proceed to Phase 4.
-
----
-
-### Phase 4: Confirm — Visualize + User Approval
-
-**Step 4.1** — Render ASCII pipeline: vertical node chain with `|` connectors showing each node (ID, type, executor, args) and checkpoint nodes (auto-continue vs pause-for-user). Footer: required variables, checkpoint counts, node counts.
-
-**Step 4.2** — AskUserQuestion: `Confirm & Save` / `Edit a node` / `Add a node` / `Remove a node` / `Rename template` / `Re-run checkpoint injection` / `Cancel`
-
-**Step 4.3** — Loop edits until Confirm or Cancel.
-
----
-
-### Phase 5: Persist — Assemble + Save Template
-
-**Read deferred**: `~/.maestro/templates/workflows/specs/template-schema.md`
-
-**Step 5.1** — Load `intent.json` + `dag.json`. Assemble template JSON.
-
-**Step 5.2** — Determine slug (kebab-case). If exists, append `-v2`.
-
-**Step 5.3** — Write `~/.maestro/templates/workflows/<slug>.json`.
-
-**Step 5.4** — Update `~/.maestro/templates/workflows/index.json`.
-
-**Step 5.5** — Output summary: path, template ID, node/checkpoint counts, required variables. Include usage commands: `$maestro-player <slug> --context goal="..."`, `$maestro-composer --edit <path>`, `$maestro-player --list`.
-
-**Step 5.6** — Clean up design draft directory.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Empty description and no flags | AskUserQuestion for description |
-| E002 | error | 0 steps extracted | Ask to rephrase with action verbs |
-| E003 | error | Node count exceeds 20 | Suggest splitting into sub-workflows |
-| E004 | error | DAG cycle detected | Show cycle, ask to resolve |
-| E005 | error | Resume session not found | Show available drafts |
-| E006 | error | Edit template not found | Show available templates |
-| W001 | warning | Ambiguous executor mapping | Show candidates, let user choose |
-| W002 | warning | No checkpoint rules triggered | Warn, offer manual add |
-| W003 | warning | Deferred spec not found | Use built-in fallback |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent parsed and confirmed by user (Phase 1 gate)
-- [ ] Nodes resolved and confirmed by user (Phase 2 gate)
-- [ ] DAG built with auto-injected checkpoints
-- [ ] Pipeline visualized and confirmed by user (Phase 4 gate)
-- [ ] Template JSON written to `~/.maestro/templates/workflows/<slug>.json`
-- [ ] Template index updated
-- [ ] Deferred specs loaded only when phase needs them
-</success_criteria>
+---
+name: maestro-composer
+description: Compose reusable workflow templates from natural language
+argument-hint: "\"workflow description\" [--resume] [--edit <template-path>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Interactive workflow template composer. Parses natural language into a reusable DAG template
+via 5 phases with user confirmation at each boundary. Templates saved globally at
+`~/.maestro/templates/workflows/`. Progressive disclosure — specs loaded only when phase needs them.
+
+Sequential interactive flow (no spawn_agents_on_csv — this is design, not execution):
+```
+Parse NL → [confirm] → Resolve to nodes → [confirm] → Inject checkpoints → Confirm pipeline → Persist
+```
+
+Three entry modes:
+1. **New design**: Phase 1-5
+2. **Resume design**: Load draft from `.workflow/templates/design-drafts/`
+3. **Edit template**: Load existing, modify, re-save
+</purpose>
+
+<context>
+$ARGUMENTS — natural language workflow description, or flags.
+
+**Flags:**
+- `--resume` — Resume in-progress design session
+- `--edit <template-path>` — Edit an existing template
+
+**Shared constants:**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `WFD` |
+| Template dir (global) | `~/.maestro/templates/workflows/` |
+| Template index (global) | `~/.maestro/templates/workflows/index.json` |
+| Design drafts dir (local) | `.workflow/templates/design-drafts/` |
+| Template ID format | `wft-<slug>-<YYYYMMDD>` |
+| Node ID format | `N-<seq>` (e.g. N-001), `CP-<seq>` for checkpoints |
+| Max nodes | 20 |
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Resume | `--resume` or existing WFD session | Phase 0: Resume |
+| Edit | `--edit <path>` | Phase 0: Load + Edit |
+| New | Default | Phase 1: Parse |
+
+**Node catalog**: Read `~/.maestro/templates/workflows/specs/node-catalog.md` at Phase 2 (deferred).
+**Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
+</context>
+
+<execution>
+
+### Phase 0: Resume / Edit (conditional)
+
+**Resume** (`--resume`):
+1. Scan `.workflow/templates/design-drafts/WFD-*/` for in-progress designs
+2. Multiple → request_user_input for selection
+3. Load draft → skip to last incomplete phase
+
+**Edit** (`--edit <path>`):
+1. Load template JSON
+2. Show pipeline visualization (Phase 4 format)
+3. request_user_input: which nodes to modify/add/remove
+4. Re-enter at Phase 3
+
+---
+
+### Phase 1: Parse — Semantic Intent Extraction
+
+**Step 1.1** — Parse `$ARGUMENTS`. If empty, request_user_input:
+```
+"Describe the workflow you want to automate.
+Include: what steps to run, in what order, and what varies each time.
+Example: 'analyze the code, then plan, implement, and test the feature'"
+```
+
+**Step 1.2** — Extract sequential actions as candidate nodes:
+
+| Signal | Candidate Type |
+|--------|---------------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "brainstorm", "ideate" | brainstorm (skill) |
+| "review code" | review (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+**Step 1.3** — Extract variables (inputs that vary per run).
+
+**Step 1.4** — Classify task type: `bugfix | feature | tdd | review | brainstorm | spec-driven | roadmap | refactor | integration-test | quick-task | custom`
+
+**Step 1.5** — Assess complexity: `simple` (1-3 nodes), `medium` (4-7), `complex` (8+)
+
+**Step 1.6** — Write `intent.json` to `.workflow/templates/design-drafts/WFD-<slug>-<date>/`.
+
+**Step 1.7 — Interactive confirmation**: Display description, task type, complexity, detected steps (numbered with type_hint), and variables. request_user_input: `Continue to resolution` / `Edit steps` / `Add a step` / `Cancel`
+
+---
+
+### Phase 2: Resolve — Map Steps to Executor Nodes
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/node-catalog.md`
+
+If spec not found, use built-in fallback:
+
+| type_hint | executor type | executor |
+|-----------|--------------|----------|
+| `planning` | skill | `maestro-plan` |
+| `execution` | skill | `maestro-execute` |
+| `testing` | skill | `quality-test` |
+| `review` | skill | `quality-review` |
+| `brainstorm` | skill | `maestro-brainstorm` |
+| `analysis` | cli | `maestro delegate --role analyze --mode analysis` |
+| `refactor` | skill | `quality-refactor` |
+| `debug` | skill | `quality-debug` |
+| `spec` | skill | `maestro-blueprint` |
+| `checkpoint` | checkpoint | — |
+
+**Step 2.1** — Load `intent.json`, map each step to executor.
+
+**Step 2.2** — Build `args_template` with variable placeholders and context injection:
+- Planning after analysis → `--context {prev_output_path}`
+- Execution after planning → inherit phase
+- Testing after execution → inherit phase
+
+**Step 2.3** — Assign `parallel_group` for parallel steps.
+
+**Step 2.4** — Write `nodes.json`.
+
+**Step 2.5 — Interactive confirmation**: Display resolved nodes table (ID, type, executor, args) and parallel groups. request_user_input: `Continue to checkpoint injection` / `Change executor` / `Change node type` / `Back to intent` / `Cancel`
+
+---
+
+### Phase 3: Enrich — Inject Checkpoints + Build DAG
+
+**Step 3.1** — Load `nodes.json`. Build sequential edges. For parallel groups: fan-out/fan-in.
+
+**Step 3.2** — Auto-inject checkpoint nodes:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source output_ports: plan, spec, analysis, review-findings |
+| Execution gate | Target executor contains `execute` |
+| Agent spawn | Target type is `agent` |
+| Long-running | Target is maestro-plan, maestro-roadmap |
+| User-defined | Step had `type_hint: checkpoint` |
+| Post-testing | Source executor contains `test` or `integration-test` |
+
+Set `auto_continue: false` for checkpoints before user-facing deliverables.
+
+**Step 3.3** — Finalize `context_schema`, validate DAG (no cycles, no orphans).
+
+**Step 3.4** — Write `dag.json`. → Proceed to Phase 4.
+
+---
+
+### Phase 4: Confirm — Visualize + User Approval
+
+**Step 4.1** — Render ASCII pipeline: vertical node chain with `|` connectors showing each node (ID, type, executor, args) and checkpoint nodes (auto-continue vs pause-for-user). Footer: required variables, checkpoint counts, node counts.
+
+**Step 4.2** — request_user_input: `Confirm & Save` / `Edit a node` / `Add a node` / `Remove a node` / `Rename template` / `Re-run checkpoint injection` / `Cancel`
+
+**Step 4.3** — Loop edits until Confirm or Cancel.
+
+---
+
+### Phase 5: Persist — Assemble + Save Template
+
+**Read deferred**: `~/.maestro/templates/workflows/specs/template-schema.md`
+
+**Step 5.1** — Load `intent.json` + `dag.json`. Assemble template JSON.
+
+**Step 5.2** — Determine slug (kebab-case). If exists, append `-v2`.
+
+**Step 5.3** — Write `~/.maestro/templates/workflows/<slug>.json`.
+
+**Step 5.4** — Update `~/.maestro/templates/workflows/index.json`.
+
+**Step 5.5** — Output summary: path, template ID, node/checkpoint counts, required variables. Include usage commands: `$maestro-player <slug> --context goal="..."`, `$maestro-composer --edit <path>`, `$maestro-player --list`.
+
+**Step 5.6** — Clean up design draft directory.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Empty description and no flags | request_user_input for description |
+| E002 | error | 0 steps extracted | Ask to rephrase with action verbs |
+| E003 | error | Node count exceeds 20 | Suggest splitting into sub-workflows |
+| E004 | error | DAG cycle detected | Show cycle, ask to resolve |
+| E005 | error | Resume session not found | Show available drafts |
+| E006 | error | Edit template not found | Show available templates |
+| W001 | warning | Ambiguous executor mapping | Show candidates, let user choose |
+| W002 | warning | No checkpoint rules triggered | Warn, offer manual add |
+| W003 | warning | Deferred spec not found | Use built-in fallback |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and confirmed by user (Phase 1 gate)
+- [ ] Nodes resolved and confirmed by user (Phase 2 gate)
+- [ ] DAG built with auto-injected checkpoints
+- [ ] Pipeline visualized and confirmed by user (Phase 4 gate)
+- [ ] Template JSON written to `~/.maestro/templates/workflows/<slug>.json`
+- [ ] Template index updated
+- [ ] Deferred specs loaded only when phase needs them
+</success_criteria>

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

@@ -11,7 +11,7 @@ Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; b
 
 Codex specifics:
 - **No agent spawning** — codebase exploration runs directly via Glob/Grep/Read in coordinator context.
-- **request_user_input** replaces AskUserQuestion for Socratic Q&A.
+- **request_user_input** replaces request_user_input for Socratic Q&A.
 - **CLI delegation** for auto mode: `exec_command("maestro delegate ... --role analyze --mode analysis")`.
 </purpose>