pi-maestro-flow 0.2.0

package/skills/maestro-overlay/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: maestro-overlay
+description: "Create or edit command overlays from natural language Arguments: <intent> — 描述要添加的规则或步骤，如 'always verify after execute'"
+allowed-tools: Read Write Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Turn natural-language instructions into command overlays — JSON patch files that augment
+`.claude/commands/*.md` non-invasively. Auto-applied by `maestro install`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+**Overlay model**:
+- JSON file: `name`, `targets[]` (command names), `patches[]`
+- Patch: `section` (XML tag), `mode` (append/prepend/replace/new-section), `content`
+- Apply: hashed HTML-comment markers (idempotent, surgical removal)
+
+**Where overlays live**
+- User overlays: `~/.maestro/overlays/*.json` — created by this skill
+- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
+- Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit
+
+**Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
+
+**Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `completion`, `invariants`, `error_codes`, `success_criteria`.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. Command file patching is handled by `maestro overlay add` — this skill NEVER modifies `.claude/commands/*.md` directly.
+</context>
+
+<invariants>
+1. **Non-invasive** — overlays MUST use hashed HTML-comment markers for injection; NEVER edit command file content directly outside the overlay system
+2. **Idempotent** — re-running `maestro overlay apply` with the same overlay JSON MUST produce no file changes
+3. **Creation only** — this skill MUST only create overlays; listing and removal are handled by `maestro overlay list` (ink TUI)
+4. **Pristine source preferred** — injection point analysis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals) first, fall back to `~/.claude/commands/` only if pristine unavailable
+5. **User approval before write** — overlay JSON MUST be shown and approved via AskUserQuestion before writing to disk; NEVER auto-install without confirmation
+6. **Chain skip option mandatory** — if a skill chain is configured, the injected content MUST include a "Skip" option in AskUserQuestion; NEVER force the user into a chain
+</invariants>
+
+<execution>
+### 1. Parse user intent
+
+Treat the argument as natural-language intent. If unclear, ask up to 2 questions with AskUserQuestion: (a) which command(s) to target, (b) where in the command flow the injection should happen.
+
+### 2. Identify targets, injection points, and visualize
+
+For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred — untouched by overlays) or fall back to `~/.claude/commands/<name>.md`. Inspect the XML sections and pick the right one:
+
+- **New step after execution** → `section: execution`, `mode: append`
+- **Required reading** → `section: required_reading`, `mode: append`
+- **Preconditions / gating** → `section: context`, `mode: append`
+- **Output quality gate** → `section: success_criteria`, `mode: append`
+
+If the user wants a whole new section, use `mode: new-section` with `afterSection: execution` (or whichever anchor makes sense).
+
+**Injection point preview** — after selecting section + mode, render the target command's section map showing existing overlays and the new injection point:
+
+```
+=== maestro-execute.md (1 overlay exists) ===
+
+  <purpose>
+  <required_reading>
+  <context>
+  <execution>
+     ├─ [existing] cli-verify #1  "CLI Verification step"
+     >>> NEW: append here (your overlay)
+  <success_criteria>
+```
+
+Use AskUserQuestion to confirm:
+- **"Confirm"** — proceed with this injection point
+- **"Pick different section"** — re-select section/mode
+- **"Cancel"** — abort
+
+### 2.5. Skill chain configuration
+
+After confirming the injection point, ask whether this overlay should chain to another skill upon completion. This enables the overlay's injected content to hand off to a skill via AskUserQuestion at runtime, using `Skill({ skill: "...", args: "..." })` syntax.
+
+Use AskUserQuestion:
+- **"No chain"** — standard overlay, no skill handoff
+- **"Chain to skill"** → ask for the target skill name (e.g., `quality-review`, `maestro-execute`, `quality-test`)
+- **"Chain with alternatives"** → ask for primary skill + 1-2 alternative skills
+
+If chain is selected, record the skill name(s) for use in Step 3.
+
+### 3. Draft the overlay JSON
+
+Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary of what and why>",
+  "targets": ["maestro-execute"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n```\nccw cli -p \"PURPOSE: ...\" --mode analysis --rule analysis-review-code-quality\n```"
+    }
+  ]
+}
+```
+
+**Content guidelines**
+- Lead the injected block with a heading that includes `(overlay)` so readers see it's machine-injected
+- Keep content concise — overlays should add a step, not rewrite the command
+- `@~/.maestro/...` references are encouraged for pointing at docs
+- Escape `\n` in JSON strings; use a HEREDOC via Bash if content is long
+
+**Skill chain content** — if a chain was configured in Step 2.5, append a Skill Handoff block at the end of the patch `content`. The handoff uses AskUserQuestion so the user controls whether to proceed:
+
+```markdown
+---
+
+**Skill Handoff** (overlay)
+
+After the above step completes, use AskUserQuestion:
+- "Proceed to /quality-review" — Hand off to quality review
+- "Skip" — Continue with current command flow
+- "Alternative: /maestro-execute" — Run execution with built-in verification instead
+
+On user selection:
+- Proceed → Skill({ skill: "quality-review", args: "{phase}" })
+- Alternative → Skill({ skill: "maestro-execute", args: "{phase}" })
+- Skip → continue normally
+```
+
+Handoff rules:
+- Always include a **"Skip"** option — the user can always decline the chain
+- Use `Skill({ skill: "<name>", args: "..." })` syntax for handoff calls
+- Mark handoff heading with `(overlay)` tag
+- Support runtime variable placeholders: `{phase}`, `{description}`, `{session_id}`
+- Keep handoff block under 10 lines of markdown
+
+### 3.5. Content approval
+
+Display the full overlay JSON to the user. AskUserQuestion:
+- **"Approve & install"** — proceed to installation
+- **"Edit"** — user provides corrections, re-draft
+- **"Cancel"** — discard overlay, do not write
+
+Only write the overlay JSON file to `~/.maestro/overlays/<slug>.json` after user approval.
+
+### 4. Install via `maestro overlay add`
+
+Run:
+
+```bash
+maestro overlay add ~/.maestro/overlays/<slug>.json
+```
+
+### 5. Report
+
+Show the user:
+- Path of the saved overlay JSON
+- Which targets were patched and which were skipped (missing/disabled)
+- Skill chain info (if configured)
+- A reminder that `maestro install` will auto-reapply on every run
+- How to remove: `maestro overlay remove <slug>`
+
+**Report format**
+
+```
+=== OVERLAY INSTALLED ===
+Name:    <slug>
+Path:    ~/.maestro/overlays/<slug>.json
+Targets: maestro-execute (applied), maestro-plan (skipped: missing)
+Chain:   quality-review (via AskUserQuestion) | none
+Scopes:  [global]
+
+Re-apply: maestro overlay apply
+Remove:   maestro overlay remove <slug>
+Inspect:  maestro overlay list
+```
+
+After the report, remind the user they can run `maestro overlay list` for the interactive TUI showing section maps and overlay management.
+</execution>
+
+<success_criteria>
+- [ ] Overlay JSON written to `~/.maestro/overlays/<slug>.json` and validates
+- [ ] `maestro overlay add` exited successfully and applied to at least one scope
+- [ ] Target command file(s) contain `<!-- maestro-overlay:<slug>#N hash=... -->` markers
+- [ ] Re-running `maestro overlay apply` produces no file changes (idempotent)
+- [ ] User shown the report with target list and removal instructions
+- [ ] Injection point preview shown (with existing overlays + `>>>` marker) and confirmed before drafting
+- [ ] If chain configured, `content` includes Skill Handoff block with AskUserQuestion + Skip option + `Skill()` calls
+</success_criteria>
+
+<completion>
+### Next-step routing
+| Condition | Suggestion |
+|-----------|-----------|
+| Overlay installed | `maestro overlay list` for interactive management |
+| Want to create another | `/maestro-overlay "<intent>"` |
+| Want to remove | `maestro overlay remove <slug>` |
+</completion>

package/skills/maestro-plan/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: maestro-plan
+description: "Use when creating, revising, or verifying an execution plan for a milestone or task Arguments: [milestone] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Create, revise, or verify execution plans (5-stage pipeline).
+Produces plan.json + TASK files; registers PLN artifact in state.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — milestone number, or no args for current milestone, with optional flags.
+
+Scope routing, base flags (`--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+
+**Command-level flags** (extensions beyond workflow base):
+- `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
+  - `analyze:ANL-xxx` → CONTEXT_DIR = artifact path, scope = "standalone"
+  - `blueprint:BLP-xxx` → CONTEXT_DIR = blueprint path, scope = "standalone"
+  - `@file` or `path/` → load context-package.json from path
+- `--tdd` — Enable TDD mode: generate test-first task structure (Red-Green-Refactor). See workflow `plan.md` § TDD Mode for task generation rules.
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
+
+**Upstream context (resolution priority):**
+1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
+2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
+3. `--dir <path>` → explicit context directory (unchanged)
+4. Numeric arg → scope = "milestone", resolve from roadmap
+5. No args + roadmap → scope = "current_milestone"
+6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
+
+**Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
+
+**`--from analyze:*` / `blueprint:*`**: scope=standalone → skip adhoc milestone auto-creation.
+
+### Role Knowledge
+`maestro search --category arch` → select relevant → `maestro load --type knowhow --id`
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Plan Agent Model
+
+Plan automatically selects agent mode based on milestone scope:
+
+**Single agent mode** (default):
+- Milestone involves ≤3 modules
+- 1 workflow-planner agent, max 8 TASK JSON output
+- Directly produces plan.json
+
+**2+1 agent mode** (auto-triggered):
+- Milestone involves >3 modules
+- 2 parallel workflow-planner agents, each scoped to 2-3 modules
+- Each agent produces max 8 TASK JSON (total max 16)
+- +1 synthesis agent:
+  - Merges TASK JSON from both agents
+  - DAG analysis: dependency correctness, cycle detection, cross-module conflicts
+  - Terminology consistency check
+  - Wave ordering optimization
+  - Produces unified plan.json
+
+Module count is derived from milestone phase definitions and analyze upstream context.
+
+### Phase Gates (MANDATORY, BLOCKING — Create mode only)
+
+**GATE P1 → P2: Context Collection → Clarification**
+- REQUIRED: Context files loaded (roadmap, analyze artifact, or --from source).
+- REQUIRED: Codebase docs read if available (ARCHITECTURE.md, FEATURES.md).
+- REQUIRED: Wiki searched for prior knowledge related to phase keywords.
+- BLOCKED if missing: no context source found — cannot plan without upstream input (E001).
+
+**GATE P2 → P3: Clarification → Plan Generation**
+- REQUIRED: Ambiguous requirements resolved via AskUserQuestion (<=3 rounds).
+- BLOCKED if: unresolved ambiguities remain after 3 clarification rounds — escalate to user before proceeding.
+
+**GATE P3 → P4: Plan Generation → Plan Check**
+- REQUIRED: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written.
+- REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
+- BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.
+
+**GATE P3.5 → P4: Boundary Grill → Plan Check**
+- REQUIRED: Boundary grill executed per workflow boundary-grill.md.
+- NON-BLOCKING: conflicts logged as warnings, not hard stops.
+
+**GATE P4 → P5: Plan Check → User Confirmation**
+- REQUIRED: Plan-checker passed (or minor issues acknowledged).
+- REQUIRED: Boundary grill completed.
+- REQUIRED: Confidence scored with 5-dimension factor model.
+- REQUIRED: Pressure pass completed on highest-complexity task.
+- REQUIRED: UI plans have `[UI-observable]` convergence criteria per wave (details in workflow).
+- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage.
+
+**GATE P5 → Completion: User Confirmation → Done**
+- REQUIRED: User confirmation captured (execute/modify/cancel).
+- REQUIRED: PLN artifact registered in state.json.
+- BLOCKED if missing: no user confirmation — do not register artifact or report completion.
+
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== PLAN READY ===
+Milestone: {milestone_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
+```
+
+Status verdicts:
+- **DONE** — Plan created/revised and confirmed → next step picks up automatically
+- **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
+- **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
+- **BLOCKED** — External hard blocker (e.g., upstream artifact missing, dependency unavailable); pass `--reason "..."`
+
+> Ambiguous requirements are NOT a completion status — resolve them in-place via `AskUserQuestion` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Plan confirmed for execution | `/maestro-execute` |
+| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
+| Re-plan with modifications | `/maestro-plan {milestone}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide milestone number or topic, or create roadmap |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-execute first (verification is built-in) |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] UI plans: each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical slice; verified at runtime by ralph frontend-verify gate)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Boundary grill executed in P3.5 (skip if no conflicts detected)
+- [ ] Boundary grill results written to plan.json `boundary_grill` section (if conflicts found)
+- [ ] DEC conflicts reflected in confidence `boundary_warning` factor
+- [ ] Plan confidence scored in P4 with 5-dimension factor model
+- [ ] Plan readiness gate checked before P4.5 collision detection
+- [ ] Pressure pass completed on highest-complexity task
+- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>

package/skills/maestro-player/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: maestro-player
+description: "Play workflow templates with checkpoint resume Arguments: <template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion Skill
+---
+
+<purpose>
+Load workflow template (from maestro-composer) → bind context variables → execute DAG nodes in topological order → persist state at checkpoints → support resume.
+
+Session: `.workflow/.maestro/player-{YYYYMMDD-HHmmss}/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS — template slug/path, or flags.
+
+**Flags**:
+- `--context key=value`: Bind context variables (repeatable)
+- `-c [session-id]`: Resume paused/interrupted session
+- `--list`: List available templates from index.json
+- `--dry-run`: Show execution plan without executing
+
+**Node execution mechanisms**:
+
+| Node type | Mechanism | Blocking |
+|-----------|-----------|----------|
+| skill | `Skill(skill, args)` | sync |
+| command | `Skill(skill, args)` | sync |
+| cli | `maestro delegate --to tool --mode mode` via `Bash(run_in_background: true)` | async, STOP + wait |
+| agent | `Agent(subagent_type, prompt)` — any registered subagent_type (see `.claude/agents/`); defaults to `"general-purpose"` if omitted or unrecognized. | configurable |
+| checkpoint | State save + optional user pause | — |
+
+**Runtime reference resolution** in args_template:
+
+| Reference | Resolves to |
+|-----------|-------------|
+| `{variable}` | session context[variable] |
+| `{N-001.session_id}` | node's session_id |
+| `{N-001.output_path}` | node's output_path |
+| `{prev_session_id}` | previous non-checkpoint node's session_id |
+| `{prev_output_path}` | previous non-checkpoint node's output_path |
+
+**Session schema** (status.json):
+```json
+{
+  "session_id": "player-<YYYYMMDD>-<HHmmss>",
+  "status": "running|paused|completed|failed|aborted",
+  "template_id": "wft-<slug>-<date>",
+  "template_path": "<path>",
+  "auto_mode": false,
+  "context": { "goal": "..." },
+  "steps": [{
+    "index": 0, "node_id": "N-001", "skill": "<executor>",
+    "args": "<resolved>", "type": "skill|cli|agent|checkpoint",
+    "status": "pending|running|completed|skipped|failed",
+    "session_id": null, "output_path": null, "artifacts": []
+  }],
+  "current_step": 0,
+  "last_checkpoint": null
+}
+```
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/player-*/` (session status.json + step outputs) only. Template files (`~/.maestro/templates/workflows/`) are read-only. NEVER modify source code or `.claude/commands/` files.
+</context>
+
+<invariants>
+1. **Resume-safe** — status.json MUST be updated after every step change; an interrupted session MUST be resumable from the last checkpoint via `-c`
+2. **One step at a time** — execution loop MUST process steps sequentially in topological order; parallel steps share a batch index but NEVER run concurrently within the player
+3. **CLI nodes async** — cli-type nodes MUST use `Bash(run_in_background: true)` + STOP pattern; NEVER block the main thread on delegate execution
+4. **Templates read-only** — player MUST NOT modify template JSON files; runtime state belongs in status.json only
+5. **Failure requires user decision** — on step failure without explicit `on_fail`, player MUST prompt via AskUserQuestion (Retry/Skip/Abort); NEVER silently skip or auto-abort
+6. **Reference resolution at runtime** — `{N-xxx.field}` and `{prev_*}` references MUST be resolved at execution time from status.json step results, NEVER pre-resolved during init
+</invariants>
+
+<state_machine>
+
+<states>
+S_ROUTE        — 入口路由（list/resume/dry-run/normal）     PERSIST: —
+S_RESUME       — 恢复已暂停 session                         PERSIST: —
+S_LOAD         — 加载模板、收集变量、绑定引用                 PERSIST: —
+S_INIT         — 创建 session、拓扑排序、初始化 steps         PERSIST: status.json
+S_EXEC_LOOP    — 逐步执行（核心循环）                        PERSIST: status.json (每步更新)
+S_COMPLETE     — 标记完成、输出摘要                           PERSIST: status.json (final)
+</states>
+
+<transitions>
+
+S_ROUTE:
+  → handleList    WHEN: --list                              DO: scan index.json, display templates
+  → S_RESUME      WHEN: -c flag
+  → S_LOAD        WHEN: template slug/path provided
+  → handleList    WHEN: no args                             DO: display templates + AskUserQuestion
+
+S_RESUME:
+  → S_EXEC_LOOP   WHEN: session found                      DO: A_RESUME_SESSION
+  → ERROR(E004)   WHEN: no session found
+
+S_LOAD:
+  → S_INIT        DO: A_LOAD_AND_BIND
+
+S_INIT:
+  → END           WHEN: --dry-run                           DO: display execution plan
+  → S_EXEC_LOOP   DO: A_INIT_SESSION (topological sort → steps[], write status.json, display banner)
+
+S_EXEC_LOOP:
+  → S_EXEC_LOOP   WHEN: step completed, more steps          DO: A_EXECUTE_STEP → advance current_step
+  → S_COMPLETE     WHEN: all steps completed
+  → END           WHEN: checkpoint pause                    DO: set status=paused, display resume command
+  → END           WHEN: abort chosen                        DO: set status=aborted, save progress
+  GUARD: cli nodes → Bash(run_in_background: true) + STOP, wait for callback
+  GUARD: on failure → on_fail: skip (log, advance) | retry (once) | abort (AskUserQuestion: Retry/Skip/Abort). Default on_fail when not specified: `abort` (prompt user via AskUserQuestion).
+  GUARD: after step 3+ → display context hint "可随时 /maestro-player -c 恢复"
+
+S_COMPLETE:
+  → END           DO: A_COMPLETE_SESSION
+
+</transitions>
+
+<actions>
+
+### A_RESUME_SESSION
+
+1. If session-id: load status.json. If none: scan player-*/status.json for running|paused.
+2. Reset any "running" steps to "pending" (interrupted mid-execution)
+3. Set current_step to resume point after last_checkpoint
+4. Enter S_EXEC_LOOP
+
+### A_LOAD_AND_BIND
+
+1. Resolve template: absolute path → as-is; relative → from cwd; slug → index.json lookup
+2. Parse `--context key=value` pairs
+3. Validate template (template_id, nodes, edges, context_schema required)
+4. Collect missing required variables via AskUserQuestion
+5. Bind {variable} placeholders (leave {N-xxx.field} and {prev_*} for runtime)
+
+### A_INIT_SESSION
+
+1. Generate session_id: player-{YYYYMMDD-HHmmss}
+2. Topological sort (Kahn's algorithm) → flatten to steps[] (parallel nodes share batch index)
+3. All steps status: "pending"
+4. Write status.json
+
+### A_EXECUTE_STEP
+
+1. Resolve runtime references ({N-xxx.field}, {prev_*}) in args
+2. Set step status="running", write status.json
+3. Execute by type:
+   - **skill/command**: `Skill(skill, resolved_args)` → extract session_id, output_path, artifacts
+   - **cli**: `Bash(run_in_background: true)` → STOP, wait for callback → `maestro delegate output <id>`
+   - **agent**: `Agent(subagent_type, resolved_args)`
+   - **checkpoint**: write checkpoint snapshot. If auto_continue==false:
+     AskUserQuestion (single-select, header: "Checkpoint"):
+     - **Continue** — proceed to next step
+     - **Pause** — save progress, exit (resume with `-c`)
+     - **Abort** — stop workflow
+4. Set step status="completed" (or "skipped"/"failed"), write status.json
+
+### A_COMPLETE_SESSION
+
+Set status="completed", completed_at. Display summary: session, template, steps completed, context, per-step results, artifacts, session dir.
+AskUserQuestion (single-select, header: "完成"):
+- **Keep session** — preserve artifacts for reference
+- **Run again** — re-execute with same template
+- **Done** — clean up and exit
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Template not found | Show --list, suggest closest match |
+| E002 | Template JSON invalid (missing template_id/nodes/edges) | Point to template file for fix |
+| E004 | Resume session not found | List available player-*/ sessions |
+| E005 | DAG cycle in template | Point to template, suggest --edit |
+| E006 | Node execution failed + abort chosen | Save state, suggest `-c` resume |
+</error_codes>
+
+<success_criteria>
+- [ ] Template loaded, variables bound, session created with topological steps
+- [ ] status.json written after every step change (resume-safe)
+- [ ] CLI nodes use Bash(run_in_background) + STOP pattern
+- [ ] Checkpoints saved, resume via -c works
+</success_criteria>