maestro-flow 0.3.14 → 0.3.16

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

@@ -141,68 +141,31 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Initialization
 
 ```javascript
-const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
-
-// Parse flags
-const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
-const continueMode = $ARGUMENTS.includes('--continue')
-const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
-const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 4
-
-// Parse plan-specific flags
-const autoMode = $ARGUMENTS.includes('--auto')
-const gapsMode = $ARGUMENTS.includes('--gaps')
-const dirMatch = $ARGUMENTS.match(/--dir\s+(\S+)/)
-const specMatch = $ARGUMENTS.match(/--spec\s+(SPEC-\S+)/)
-const collabMode = $ARGUMENTS.includes('--collab')
-
-// Clean phase text
-const phaseArg = $ARGUMENTS
-  .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|--auto|--gaps|--parallel|--collab|--dir\s+\S+|--spec\s+\S+/g, '')
-  .trim()
-
-// Auto-bootstrap state.json if missing
-if (!fileExists('.workflow/state.json')) {
-  Bash('mkdir -p .workflow/scratch/')
-  writeMinimalStateJson()
-}
-
-// Scope determination (per scratch-milestone-architecture)
-const state = JSON.parse(Read('.workflow/state.json'))
-let scope, phaseNum = null, phaseSlug, contextDir
-
-if (dirMatch) {
-  contextDir = dirMatch[1]
-  phaseSlug = contextDir.split('/').pop()
-  // Inherit scope from parent artifact if registered
-  const parentArtifact = state.artifacts.find(a => a.path === contextDir)
-  scope = parentArtifact?.scope || 'standalone'
-} else if (phaseArg === '') {
-  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
-    scope = 'milestone'
-    phaseSlug = slugify(state.milestones.find(m => m.id === state.current_milestone)?.name || state.current_milestone)
-    // Find latest analyze artifact for this milestone
-    contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.status === 'completed').pop()?.path
-  } else {
-    ERROR('E001: No args and no roadmap')
-  }
-} else if (/^\d+$/.test(phaseArg)) {
-  scope = 'phase'
-  phaseNum = parseInt(phaseArg)
-  phaseSlug = resolvePhaseSlugFromRoadmap(phaseNum)
-  contextDir = state.artifacts.filter(a => a.type === 'analyze' && a.milestone === state.current_milestone && a.phase === phaseNum && a.status === 'completed').pop()?.path
-} else {
-  scope = state.current_milestone ? 'adhoc' : 'standalone'
-  phaseSlug = phaseArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
-}
-
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `${dateStr}-plan-P${phaseArg}-${phaseSlug}`
-const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/${dateStr}-plan-P${phaseArg}-${phaseSlug}`
-
-Bash(`mkdir -p ${sessionFolder}`)
-Bash(`mkdir -p ${scratchDir}/.task/`)
+// Parse from $ARGUMENTS:
+//   AUTO_YES      <- --yes | -y
+//   continueMode  <- --continue
+//   maxConcurrency <- --concurrency N | -c N  (default: 4)
+//   autoMode      <- --auto
+//   gapsMode      <- --gaps
+//   dirMatch      <- --dir <path>
+//   specMatch     <- --spec SPEC-xxx
+//   collabMode    <- --collab
+//   phaseArg      <- remaining text after stripping all flags
+
+// Auto-bootstrap .workflow/state.json if missing
+
+// Scope determination from state.json (priority order):
+//   --dir given       → scope from parent artifact or 'standalone'
+//   phaseArg empty    → 'milestone' (requires current_milestone + roadmap.md) or ERROR E001
+//   phaseArg is digit → 'phase', resolve slug from roadmap, find latest completed analyze artifact
+//   phaseArg is text  → 'adhoc' (if milestone active) or 'standalone', slugify phaseArg
+
+// Session IDs (UTC+8):
+//   sessionId    = {YYYYMMDD}-plan-P{phaseArg}-{phaseSlug}
+//   sessionFolder = .workflow/.csv-wave/{sessionId}
+//   scratchDir    = .workflow/scratch/{sessionId}
+
+// Create: sessionFolder, scratchDir/.task/
 ```
 
 ### Phase 1: Phase Resolution -> CSV
@@ -266,21 +229,13 @@ spawn_agents_on_csv({
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
+  output_schema: { // required: id, status, findings
+    id: "string", status: "completed|failed", findings: "string", error: "string"
   }
 })
 ```
 
-6. Read `wave-1-results.csv`, merge into master `tasks.csv`
-7. Delete `wave-1.csv`
+6. Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`
 
 #### Wave 2: Plan Generation (Sequential)
 
@@ -303,123 +258,44 @@ spawn_agents_on_csv({
   instruction: buildPlanningInstruction(sessionFolder, phaseDir, {
     contextMd, indexJson, specRef, docIndex, designRef, gapsContext
   }),
-  max_concurrency: 1,  // Sequential — single planning agent
+  max_concurrency: 1,  // Single planning agent
   max_runtime_seconds: 900,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: {
-    type: "object",
-    properties: {
-      id: { type: "string" },
-      status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      error: { type: "string" }
-    },
-    required: ["id", "status", "findings"]
+  output_schema: { // required: id, status, findings
+    id: "string", status: "completed|failed", findings: "string", error: "string"
   }
 })
 ```
 
-6. Merge results into master `tasks.csv`
-7. Delete `wave-2.csv`
+6. Merge `wave-2-results.csv` into master `tasks.csv`, delete `wave-2.csv`
 
 **Planning agent responsibilities** (embedded in instruction):
-- Decompose phase goal into concrete tasks (TASK-001, TASK-002, ...)
-- Determine dependencies and group into execution waves
-- Apply Deep Work Rules:
-  - Every task has `read_first[]` with file being modified + source of truth files
-  - Every task has `convergence.criteria[]` with grep-verifiable conditions
-  - Every `action` has concrete values (never "align X with Y")
-  - Every `implementation` step has specific values
-- Write `plan.json` to `{PHASE_DIR}/plan.json`
-- Write `.task/TASK-{NNN}.json` files to `{PHASE_DIR}/.task/`
-- If `--gaps`: create fix tasks from gap context, link to issues
-- If `--collab`: pre-allocate ID ranges for parallel planners
+- Decompose phase goal → TASK-001..N with dependencies grouped into execution waves
+- Apply Deep Work Rules: `read_first[]` includes modified file + source of truth; `convergence.criteria[]` are grep-verifiable; all actions/steps have concrete values
+- Write `plan.json` to `{PHASE_DIR}/plan.json` and `.task/TASK-{NNN}.json` to `{PHASE_DIR}/.task/`
+- `--gaps`: create fix tasks from gap context, link to issues; `--collab`: pre-allocate ID ranges
 
 ### Phase 3: Plan Checking + Confirmation
 
 **Objective**: Validate plan quality, revise if needed, present to user.
 
 1. **Plan checking** (inline, not a separate wave):
-   - Read generated `plan.json` + all `.task/TASK-*.json`
-   - Validate dimensions:
-
-| Check | Criteria |
-|-------|----------|
-| Requirements coverage | Every success_criterion maps to at least one task |
-| Feasibility | Referenced files exist or can be created |
-| Dependency correctness | No circular deps, deps exist, wave ordering valid |
-| Convergence criteria quality | Grep-verifiable, no subjective language |
-| read_first completeness | Every task has read_first[] with modified file |
-| Action concreteness | No vague "align X with Y" |
-| Wave structure | Parallel tasks have no conflicting file modifications |
+   Read `plan.json` + all `.task/TASK-*.json`. Validate: requirements coverage, file feasibility, dependency correctness (no cycles, valid wave order), grep-verifiable convergence criteria, read_first completeness, action concreteness, no parallel file conflicts.
 
 2. **Revision loop** (max 3 rounds): If critical issues found, regenerate affected tasks.
 
 3. **Export results**:
    - Export `results.csv` from master `tasks.csv`
-   - Generate `context.md`:
-
-```markdown
-# Plan Report -- Phase {phase}
-
-## Summary
-- Phase: {phase_name}
-- Tasks: {task_count} in {wave_count} waves
-- Complexity: {complexity}
-- Explorations: {exploration_count} angles explored
-
-## Exploration Findings
+   - Generate `context.md`: summary (phase, task count, wave count, complexity, exploration count), exploration findings per angle, plan overview (approach, task IDs, waves), next steps
 
-### {angle}: {title}
-{findings}
-
-## Plan Overview
-- Approach: {plan.approach}
-- Task IDs: {task_ids}
-- Waves: {wave_structure}
-
-## Next Steps
-{suggested actions}
-```
-
-4. **Update index.json**:
-   ```json
-   {
-     "status": "planning",
-     "plan": {
-       "task_ids": ["TASK-001", "TASK-002"],
-       "task_count": N,
-       "complexity": "moderate",
-       "waves": [[...], [...]]
-     },
-     "updated_at": "<ISO>"
-   }
-   ```
+4. **Update index.json**: set `status: "planning"`, `plan: { task_ids, task_count, complexity, waves }`, `updated_at`
 
 5. **Issue linking** (if --gaps):
-   For each created TASK-{NNN}.json that has `issue_id`:
-   - Update corresponding issue in `.workflow/issues/issues.jsonl`:
-     - `task_refs`: append TASK-{NNN} to array
-     - `task_plan_dir`: relative path to `.task/` directory
-     - `status`: "planned"
-     - `updated_at`: now()
-   - Append history entry: `{ action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }`
-   This ensures bidirectional issue <-> TASK traceability for dashboard display.
+   For each TASK with `issue_id`: update issue in `issues.jsonl` (`task_refs` += TASK-NNN, `task_plan_dir`, `status: "planned"`, `updated_at`) + append history entry. Ensures bidirectional issue-TASK traceability.
 
 6. **Display summary + options** (skip options if AUTO_YES):
-   ```
-   === PLAN READY ===
-   Phase: {phase_name}
-   Tasks: {task_count} tasks in {wave_count} waves
-   Check: {checker_status}
-
-   Plan: {scratch_dir}/plan.json
-   Tasks: {scratch_dir}/.task/TASK-*.json
-
-   Next steps:
-     Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
-     Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
-   ```
+   Show phase name, task/wave counts, checker status, output file paths.
+   Next steps: `maestro-execute "{phase}"` (execute) or `maestro-plan "{phase}"` (re-plan).
 
 ### Shared Discovery Board Protocol
 

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

@@ -0,0 +1,323 @@
+---
+name: maestro-player
+description: Workflow template player — load JSON template, bind variables, execute DAG nodes wave-by-wave via spawn_agents_on_csv, persist state at checkpoints, support resume. Coordinator assembles skill_call from template nodes — never executes skills directly.
+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
+---
+
+<purpose>
+Wave-based template executor using `spawn_agents_on_csv`. Loads a workflow template
+(produced by maestro-composer), binds context variables, converts DAG nodes into
+CSV waves via topological sort, executes wave-by-wave with barrier/non-barrier grouping.
+
+Aligned with maestro codex coordinator pattern:
+- ALL skill execution via `spawn_agents_on_csv` — coordinator never executes directly
+- Barrier nodes (checkpoints + artifact-producing skills) execute solo
+- Non-barrier nodes grouped into parallel waves
+- Session state at `.workflow/.maestro-coordinate/{session-id}/`
+- Resume from last completed wave via `-c`
+
+```
+Load Template → Bind Variables → Build Wave CSV → spawn → read results →
+(barrier: read artifacts, update context) → next wave → report
+```
+</purpose>
+
+<invariants>
+1. **ALL skills via spawn_agents_on_csv**: Every node execution goes through spawn. Coordinator NEVER directly executes any skill.
+2. **Coordinator = prompt assembler only**: Load template → resolve refs → build CSV → spawn → read results → assemble next CSV.
+3. **Barrier = solo wave**: Checkpoint nodes and artifact-producing skills execute alone (wave size = 1).
+4. **Non-barriers can parallel**: Consecutive non-barrier nodes grouped into one wave.
+5. **Wave-by-wave**: Never start wave N+1 before wave N results are read and analyzed.
+6. **Coordinator owns context**: Sub-agents never read prior results — coordinator assembles full `skill_call` with resolved args.
+7. **Resume from wave**: `-c` finds last completed wave, resumes from next pending step.
+</invariants>
+
+<context>
+$ARGUMENTS — template slug/path, or flags.
+
+**Flags:**
+- `--context key=value` — Bind context variables (repeatable)
+- `-c` / `--continue [session-id]` — Resume paused/interrupted session
+- `--list` — List available templates
+- `--dry-run` — Show wave plan without executing
+
+**Entry routing:**
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| List | `--list` | handleList |
+| Resume | `-c [session-id]` | Phase 0: Resume |
+| Dry run | `--dry-run` | Phase 1 + 2, print plan, exit |
+| Normal | Template slug/path | Phase 1 |
+| No args | Empty | handleList + AskUserQuestion |
+
+**Session tracking (aligned with maestro codex):**
+
+| Constant | Value |
+|----------|-------|
+| Session prefix | `MCP` (Maestro Composer Player) |
+| Session dir | `.workflow/.maestro-coordinate/MCP-<YYYYMMDD>-<HHmmss>/` |
+| State file | `state.json` |
+| Wave CSV | `wave-{N}.csv` |
+| Wave results | `wave-{N}-results.csv` |
+| Template dir | `~/.maestro/templates/workflows/` |
+| Template index | `~/.maestro/templates/workflows/index.json` |
+
+**Barrier nodes** (solo wave, coordinator reads artifacts after):
+
+| Node type | Artifacts to Read | Context Updates |
+|-----------|------------------|-----------------|
+| `checkpoint` | — (state save only) | `last_checkpoint` |
+| `maestro-plan` | `plan.json`, `.task/TASK-*.json` | `plan_dir`, `task_count` |
+| `maestro-execute` | `results.csv` | `exec_status`, `completed_tasks` |
+| `maestro-analyze` | `context.md` | `analysis_dir`, `gaps`, `phase` |
+| `maestro-brainstorm` | `.brainstorming/` | `brainstorm_dir` |
+| `maestro-spec-generate` | `specs/` | `spec_session_id` |
+
+All other skill nodes are **non-barrier** (groupable into parallel waves).
+
+**state.json schema:**
+
+```json
+{
+  "id": "MCP-<YYYYMMDD>-<HHmmss>",
+  "intent": "<template_name> with context",
+  "chain": "<template_id>",
+  "template_path": "~/.maestro/templates/workflows/<slug>.json",
+  "template_name": "<name>",
+  "auto_yes": false,
+  "status": "in_progress | paused | completed | aborted",
+  "started_at": "<ISO>",
+  "context": {
+    "goal": "...", "scope": "...",
+    "phase": null, "plan_dir": null, "analysis_dir": null,
+    "last_checkpoint": null
+  },
+  "waves": [],
+  "steps": [
+    {
+      "step_n": 1, "node_id": "N-001",
+      "skill": "<executor>", "args": "<args_template>",
+      "type": "skill | cli | checkpoint",
+      "is_barrier": true,
+      "status": "pending | completed | failed | skipped",
+      "wave_n": null, "findings": null, "artifacts": null
+    }
+  ]
+}
+```
+</context>
+
+<execution>
+
+### handleList
+
+Scan `~/.maestro/templates/workflows/index.json`. Display:
+```
+Available workflow templates:
+  feature-tdd-review    [feature, complex]   3 work nodes, 2 checkpoints
+  quick-bugfix          [bugfix, simple]     2 work nodes, 1 checkpoint
+
+Run: $maestro-player <slug> --context goal="..."
+```
+
+If not found: "No templates. Create with $maestro-composer"
+
+---
+
+### Phase 0: Resume
+
+**Trigger**: `-c [session-id]`
+
+Load session state by explicit ID or most recent `MCP-*/state.json` with `status = "in_progress" | "paused"`. Error E005 if none found. Resume from next pending step after last completed wave → jump to Phase 3.
+
+---
+
+### Phase 1: Load & Bind
+
+1. **Resolve template**: absolute path → as-is, slug → lookup in `~/.maestro/templates/workflows/index.json`, partial → confirm, not found → show `--list`
+2. **Parse** `--context key=value` pairs into `bound_context`
+3. **Load and validate** template JSON
+4. **Collect missing** required variables via AskUserQuestion
+5. **Bind** `{variable_name}` in all `args_template` strings. Leave `{N-xxx.field}` and `{prev_*}` unresolved (runtime Phase 3)
+6. If `--dry-run`: print wave plan and exit
+
+---
+
+### Phase 2: Init Session & Build Wave Plan
+
+1. Generate session ID: `MCP-<YYYYMMDD>-<HHmmss>`
+2. Topological sort (Kahn's algorithm) on template nodes + edges
+3. Classify barrier vs non-barrier: barriers = checkpoint nodes + `maestro-analyze`, `maestro-plan`, `maestro-brainstorm`, `maestro-spec-generate`, `maestro-execute`
+4. Group into waves: barrier nodes → solo wave, non-barrier nodes → accumulate into parallel wave
+5. Build steps array from waves, write `state.json`
+
+**Step 2.6** — Display start banner:
+```
+============================================================
+  MAESTRO PLAYER
+============================================================
+  Template: <template.name>
+  Session:  <session_id>
+  Context:  goal="<value>"
+
+  Wave Plan:
+    [W1] N-001 maestro-plan          "{goal}"       [BARRIER]
+    [W2] N-002 maestro-execute       {phase}        [BARRIER]
+    [W3] N-003 quality-test          {phase}
+         N-004 quality-review        {phase}
+============================================================
+```
+
+**`--dry-run`**: Display above and exit.
+
+---
+
+### Phase 3: Wave Execution Loop
+
+Loop while any step has `status === 'pending'`:
+
+**3a. Resolve runtime references** in each step's args:
+- `{key}` → lookup from `context[key]`
+- `{N-xxx.field}` → lookup from completed step with matching `node_id`
+- `{prev_field}` → lookup from most recently completed non-checkpoint step
+
+**3b. Handle checkpoint nodes** (no CSV spawn needed):
+- Save checkpoint snapshot to `checkpoints/{node_id}.json` (session state + context)
+- Update `context.last_checkpoint`, mark completed
+- If `auto_continue === false`: prompt user (Continue / Pause / Abort)
+
+**3c. Build wave CSV** for skill nodes:
+Write `wave-{N}.csv` with columns `id,skill_call,topic`. Each row: resolved `$${step.skill} ${args}`.
+
+**3d. Spawn agents**:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionDir}/wave-${waveNum}.csv`,
+  id_column: "id",
+  instruction: PLAYER_INSTRUCTION,
+  max_workers: waveSteps.length,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionDir}/wave-${waveNum}-results.csv`,
+  output_schema: RESULT_SCHEMA
+})
+```
+
+**3e. Read results**: Map each result row back to its step — update status, findings, artifacts, wave_n.
+
+**3f. Barrier analysis**: If barrier wave, read artifacts and update context (see barrier node table in `<context>`).
+
+**3g. Persist + abort check**: Append wave record to `state.waves[]`, persist `state.json`. If any result failed → set `state.status = 'aborted'`, mark remaining steps as skipped.
+
+### Sub-Agent Instruction Template
+
+```
+你是 CSV job 子 agent。
+
+先原样执行这一段技能调用：
+{skill_call}
+
+然后基于结果完成这一行任务说明：
+{topic}
+
+限制：
+- 不要修改 .workflow/.maestro-coordinate/ 下的 state 文件
+- skill 内部有自己的 session 管理，按 skill SKILL.md 执行即可
+
+最后必须调用 `report_agent_job_result`，返回 JSON：
+{"status":"completed|failed","skill_call":"{skill_call}","summary":"一句话结果","artifacts":"产物路径或空字符串","error":"失败原因或空字符串"}
+```
+
+### Result Schema
+
+```javascript
+const RESULT_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { type: "string", enum: ["completed", "failed"] },
+    skill_call: { type: "string" },
+    summary: { type: "string" },
+    artifacts: { type: "string" },
+    error: { type: "string" }
+  },
+  required: ["status", "skill_call", "summary", "artifacts", "error"]
+};
+```
+
+---
+
+### Phase 4: Completion Report
+
+```
+============================================================
+  MAESTRO PLAYER SESSION COMPLETE
+============================================================
+  Session:   <session_id>
+  Template:  <template_name> (<template_id>)
+  Waves:     <N> executed
+  Steps:     <completed>/<total>
+  Context:   goal="<value>"
+
+  WAVE RESULTS:
+    [W1] $maestro-plan "{goal}"         →  ✓  plan created
+    [W2] $maestro-execute {phase}       →  ✓  12/12 tasks
+    [W3] $quality-test {phase}          →  ✓  all tests pass
+         $quality-review {phase}        →  ✓  no issues
+
+  State:    .workflow/.maestro-coordinate/<session_id>/state.json
+  Resume:   $maestro-player -c
+============================================================
+```
+
+Update `state.status = "completed"`, write final `state.json`.
+</execution>
+
+<csv_schema>
+### wave-{N}.csv (Per-Wave Input)
+
+```csv
+id,skill_call,topic
+"1","$maestro-plan \"implement user auth\"","Template \"feature-plan-test\" step 1/5"
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Step number (string) |
+| `skill_call` | Full skill invocation with resolved context args |
+| `topic` | Brief description for the agent |
+
+### wave-{N}-results.csv (Per-Wave Output)
+
+Written by `spawn_agents_on_csv`. Contains result per agent.
+</csv_schema>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Template not found | Show --list, suggest closest match |
+| E002 | error | Template JSON invalid | Point to file for fix |
+| E003 | error | Required variable missing, user declined | Cannot proceed |
+| E004 | error | DAG cycle in template | Suggest $maestro-composer --edit |
+| E005 | error | Resume session not found | List sessions |
+| E006 | error | Wave timeout | Mark failed, abort chain |
+| E007 | error | Barrier artifact not found | Retry wave once, then abort |
+| W001 | warning | Runtime reference resolved to empty | Log, continue |
+| W002 | warning | Barrier artifact partial | Continue with available context |
+</error_codes>
+
+<success_criteria>
+- [ ] Template loaded from `~/.maestro/templates/workflows/` and validated
+- [ ] All required context variables bound
+- [ ] Session dir at `.workflow/.maestro-coordinate/MCP-*/` with `state.json`
+- [ ] DAG nodes converted to waves (barrier=solo, non-barrier=parallel)
+- [ ] Every skill invocation goes through `spawn_agents_on_csv` — none in coordinator
+- [ ] Checkpoint nodes handled inline (state save, optional user pause)
+- [ ] Barrier artifacts read and context updated before next wave
+- [ ] Runtime references ({N-xxx.field}, {prev_*}) resolved before each wave CSV
+- [ ] Failed step → remaining marked skipped → abort reported
+- [ ] `--dry-run` shows wave plan with [BARRIER] markers, no execution
+- [ ] `-c` resumes from last completed wave
+- [ ] Completion report with per-wave status
+</success_criteria>

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

@@ -49,30 +49,11 @@ Extract from arguments:
 
 ### Step 2: Load Project Context
 
-```bash
-cat .workflow/state.json 2>/dev/null
-cat .workflow/project.md 2>/dev/null
-```
-
-If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
+Read `.workflow/state.json` and `.workflow/project.md` if they exist. If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
 
 ### Step 3: Create Scratch Directory
 
-Generate slug from task description (lowercase, hyphens, max 40 chars).
-
-```bash
-mkdir -p .workflow/scratch/{slug}
-```
-
-Write `config.json` with task metadata:
-```json
-{
-  "task": "<description>",
-  "flags": { "discuss": false, "full": false },
-  "created_at": "<ISO timestamp>",
-  "status": "active"
-}
-```
+Generate slug from task description (lowercase, hyphens, max 40 chars). Create `.workflow/scratch/{slug}/`. Write `config.json` with: `task`, `flags` (discuss, full), `created_at` (ISO), `status` ("active").
 
 ### Step 4: Discussion Phase (if --discuss)
 
@@ -113,37 +94,13 @@ Update plan.json task statuses as completed.
 
 ### Step 8: Verification (if --full)
 
-**Only when `--full` is set.**
-
-Run convergence criteria checks:
-```bash
-# For each task, verify convergence_criteria via grep/test commands
-```
-
-If gaps found (W001): attempt single fix iteration, then report remaining gaps.
+**Only when `--full` is set.** Run convergence criteria checks for each task via grep/test commands. If gaps found (W001): attempt single fix iteration, then report remaining gaps.
 
 ### Step 9: Commit and Report
 
-```bash
-git add -A
-git commit -m "quick: {slug} - {short description}"
-```
-
-Update `.workflow/state.json` scratch task entry (if state.json exists).
+Commit all changes: `git add -A && git commit -m "quick: {slug} - {short description}"`. Update `.workflow/state.json` scratch task entry (if state.json exists).
 
-```
-=== QUICK TASK COMPLETE ===
-Task:    {description}
-Scratch: .workflow/scratch/{slug}/
-Status:  {completed|completed-with-gaps}
-
-Tasks: {completed}/{total}
-Files modified: {count}
-
-{if --full}
-Verification: {PASS|GAPS}
-{endif}
-```
+Display report: task description, scratch path, status (completed/completed-with-gaps), tasks completed/total, files modified count. If `--full`: include verification result (PASS/GAPS).
 
 </execution>