maestro-flow 0.3.9 → 0.3.10

package/.claude/commands/maestro-analyze.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Multi-dimensional analysis with CLI exploration, decision extraction, and intent tracking
-argument-hint: "[phase|topic] [-y] [-c] [-q]"
+argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
 allowed-tools:
   - Read
   - Write
@@ -18,6 +18,8 @@ Perform multi-dimensional analysis of a technical proposal, decision, or archite
 Combines structured 6-dimension scoring with iterative deepening and decision extraction. Replaces both analysis and decision-capture workflows — produces analysis.md (scoring) AND context.md (Locked/Free/Deferred decisions for plan).
 
 Use `-q` for quick decision extraction only (skip exploration + scoring).
+
+Use `--gaps` for issue-focused root cause analysis (replaces manage-issue-analyze). Loads issues from issues.jsonl, performs CLI exploration against issue context/location, synthesizes root cause into issue.analysis, and outputs context.md for downstream `plan --gaps`.
 </purpose>
 
 <required_reading>
@@ -26,6 +28,7 @@ Use `-q` for quick decision extraction only (skip exploration + scoring).
 
 <deferred_reading>
 - [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [issue-gaps-analyze.md](~/.maestro/workflows/issue-gaps-analyze.md) — read when --gaps is triggered
 </deferred_reading>
 
 <context>
@@ -35,6 +38,7 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 - `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
 - `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
 - `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
+- `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
 **Scope routing (per architecture):**
 
@@ -44,8 +48,10 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 | `analyze 1` | init + roadmap | phase | Analyze phase 1 only |
 | `analyze "topic"` (has milestone) | none | adhoc | Analyze topic, affiliated with current milestone |
 | `analyze "topic"` (no milestone) | none | standalone | Analyze topic, no milestone affiliation |
+| `analyze --gaps` | issues.jsonl exists | gaps | Load open issues, explore root causes, write analysis records |
+| `analyze --gaps ISS-xxx` | issue exists | gaps | Analyze single issue root cause |
 
-**Scope detection rule**: Text argument + `state.json.current_milestone` non-null → adhoc. Text argument + no milestone → standalone. No args + no roadmap → error (need topic or roadmap).
+**Scope detection rule**: Text argument + `state.json.current_milestone` non-null → adhoc. Text argument + no milestone → standalone. No args + no roadmap → error (need topic or roadmap). `--gaps` → gaps scope (bypasses standard scope routing).
 
 **Output directory**: `scratch/analyze-{slug}-{date}/` (relative to `.workflow/`)
 
@@ -80,7 +86,32 @@ $ARGUMENTS -- phase number for milestone-scoped, topic text for adhoc/standalone
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
-**Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions).
+### --gaps Mode (Issue Root Cause Analysis)
+
+When `--gaps` flag is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard analyze pipeline:
+
+```
+Phase 1: Load issues from .workflow/issues/issues.jsonl
+  - If ISS-ID provided: load single issue
+  - If no ISS-ID: filter issues where status = open | registered
+  - Validate: at least 1 issue loaded, else error E_NO_ISSUES
+
+Phase 2: CLI exploration per issue
+  - For each issue: build exploration prompt from issue.title, description, context, related_files
+  - Run maestro delegate --to gemini --mode analysis with codebase context
+  - Gather affected files, call chains, root cause evidence
+
+Phase 3: Root cause synthesis → write issue.analysis
+  - Parse CLI output into analysis record: { root_cause, affected_files, impact_scope, fix_direction, confidence, analyzed_at, tool, depth }
+  - Write analysis record to issue in issues.jsonl
+  - Append history entry: { action: "analyzed", at: <ISO>, by: "maestro-analyze --gaps" }
+
+Phase 4: Output context.md for downstream plan --gaps
+  - Aggregate all analyzed issues into context.md with root causes and fix directions
+  - Register ANL artifact in state.json
+```
+
+**Handoff:** context.md is consumed by maestro-plan (loads Locked/Free/Deferred decisions). In --gaps mode, context.md contains issue root causes for `plan --gaps` consumption.
 
 **Next-step routing on completion:**
 
@@ -92,6 +123,10 @@ Phase/Milestone scope:
 Adhoc/Standalone scope:
 - Ready to plan → `/maestro-plan --dir {scratch_dir}`
 - Need more exploration → `/maestro-analyze {topic} -c`
+
+Gaps scope:
+- Issues analyzed → `/maestro-plan --gaps` (plan fix tasks linked to issues)
+- Need more context → `/maestro-analyze --gaps {ISS-ID}` (re-analyze specific issue)
 </execution>
 
 <error_codes>
@@ -102,6 +137,8 @@ Adhoc/Standalone scope:
 | W002 | warning | CLI analysis timeout | Retry with shorter prompt, or skip perspective |
 | W003 | warning | Insufficient evidence for scoring dimensions | Note low-confidence dimensions, proceed with available evidence |
 | W004 | warning | Max rounds reached (5) | Force synthesis, offer continuation option |
+| E_NO_ISSUES | error | --gaps but no open/registered issues found | Suggest `/manage-issue-discover` or `/manage-issue create` |
+| E_ISSUE_NOT_FOUND | error | --gaps with ISS-ID but issue not found | Suggest `/manage-issue list` to find valid IDs |
 </error_codes>
 
 <success_criteria>
@@ -112,6 +149,12 @@ Full mode:
 - [ ] conclusions.json created with recommendations and decision trail
 - [ ] Intent Coverage tracked and verified (no unresolved ❌ items)
 
+Gaps mode:
+- [ ] Issues loaded from issues.jsonl (all open/registered, or single ISS-ID)
+- [ ] CLI exploration executed per issue with codebase context
+- [ ] Analysis record attached to each issue in issues.jsonl
+- [ ] context.md written with aggregated root causes for plan --gaps
+
 Both modes (full + quick):
 - [ ] context.md written with all decisions classified as Locked/Free/Deferred
 - [ ] Gray areas identified through phase-specific analysis

package/.claude/commands/maestro-execute.md

@@ -96,6 +96,20 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/execute.md' completely.
 
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+
+```
+For each completed/failed TASK with issue_id:
+  Read issue from issues.jsonl by issue_id
+  Collect all task_refs[] statuses for that issue:
+    all task_refs completed → issue.status = "resolved"
+    any task_ref failed    → issue.status = "in_progress"
+  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
+  Write updated issue back to issues.jsonl
+```
+
 **Report format on completion:**
 
 ```

package/.claude/commands/maestro-plan.md

@@ -108,6 +108,22 @@ ELSE:
   wiki_context = structured block for downstream stages
 ```
 
+### Issue Linkback (--gaps mode)
+
+After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
+
+```
+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 issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
+
 **Report format on completion:**
 
 ```

package/.claude/commands/manage-harvest.md

@@ -17,7 +17,7 @@ Extract knowledge fragments from workflow artifacts (analysis results, brainstor
 
 Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
 
-**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, manage-issue-plan).
+**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
 </purpose>
 
 <required_reading>

package/.claude/commands/manage-issue-discover.md

@@ -20,7 +20,7 @@ Automated issue discovery via multi-perspective codebase analysis (8 perspective
 
 For CRUD operations (create, list, update, close, link), use `/manage-issue`.
 
-After discovery, use `/manage-issue-analyze <ISS-ID>` to perform root cause analysis on individual findings.
+After discovery, use `/maestro-analyze --gaps <ISS-ID>` to perform root cause analysis on individual findings.
 </purpose>
 
 <required_reading>
@@ -73,5 +73,5 @@ Follow '~/.maestro/workflows/issue-discover.md' completely.
 - [ ] Findings deduplicated before issue creation
 - [ ] Issues appended to issues.jsonl with correct schema
 - [ ] Discovery session fully traceable via session directory
-- [ ] Next step routing: `/manage-issue-analyze <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
+- [ ] Next step routing: `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
 </success_criteria>

package/.claude/commands/manage-issue.md

@@ -16,7 +16,7 @@ Issue lifecycle management for the project issue tracker. Supports create, list,
 
 For automated issue discovery, use `/manage-issue-discover`.
 
-**Closed-loop workflow**: After creating an issue, use `/manage-issue-analyze` for root cause analysis, `/manage-issue-plan` for solution planning, and `/manage-issue-execute` for execution.
+**Closed-loop workflow**: After creating an issue, use `/maestro-analyze --gaps <ISS-ID>` for root cause analysis, `/maestro-plan --gaps` for solution planning, and `/maestro-execute` for execution.
 </purpose>
 
 <required_reading>
@@ -48,8 +48,8 @@ Parse subcommand from first token of $ARGUMENTS.
 Follow '~/.maestro/workflows/issue.md' completely.
 
 **Next-step routing on completion:**
-- create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
-- list → `/manage-issue-analyze <ISS-ID>` for any open issue
+- create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+- list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
 - close → `/manage-status`
 </execution>
 

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

@@ -0,0 +1,463 @@
+---
+name: maestro
+description: Intelligent coordinator — analyze intent, read project state, select chain, execute wave-by-wave via spawn_agents_on_csv. Barrier skills trigger coordinator-side artifact analysis between waves to dynamically assemble subsequent skill_call args. Each wave can be 1 or N parallel tasks.
+argument-hint: "\"intent text\" [-y] [-c|--continue] [--dry-run] [--chain <name>]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+## Auto Mode
+
+When `-y` or `--yes`: Skip clarification and confirmation prompts. Pass `-y` through to each step's skill invocation.
+
+# Maestro
+
+## Usage
+
+```bash
+$maestro "implement user authentication with JWT"
+$maestro -y "refactor the payment module"
+$maestro --continue
+$maestro --dry-run "add rate limiting to API endpoints"
+$maestro --chain feature "add dark mode toggle"
+```
+
+**Flags**:
+- `-y, --yes` — Auto mode: skip all prompts; propagate `-y` to each skill
+- `--continue` — Resume latest paused session from last incomplete wave
+- `--dry-run` — Display planned chain without executing
+- `--chain <name>` — Force a specific chain (skips intent classification)
+
+**Session state**: `.workflow/.maestro-coordinate/{session-id}/`
+**Core Output**: `tasks.csv` (master) + `wave-{N}-results.csv` (per wave) + `context.md` (report)
+
+---
+
+## Overview
+
+Wave-based pipeline coordinator. The coordinator loop builds one wave CSV at a time, calls `spawn_agents_on_csv`, then performs **coordinator-side artifact analysis** before assembling the next wave. Barrier skills produce artifacts (plan.json, analysis results, etc.) that the coordinator reads to dynamically resolve args for subsequent steps.
+
+```
+Intent → Resolve Chain → [Wave Loop]:
+  ┌─────────────────────────────────────────────────┐
+  │ 1. Identify next wave (1 or N parallel steps)   │
+  │ 2. Build wave-{N}.csv with skill_call per row   │
+  │ 3. spawn_agents_on_csv(wave-{N}.csv)            │
+  │ 4. Read wave-{N}-results.csv                    │
+  │ 5. If barrier skill: analyze artifacts,         │
+  │    update context for subsequent steps           │
+  │ 6. Merge into master tasks.csv                  │
+  └─────────────────────────────────────────────────┘
+  → Report
+```
+
+---
+
+## Barrier Skills
+
+Skills that produce artifacts requiring **coordinator-side analysis** before the next wave can be assembled. After a barrier skill completes, the coordinator reads its output and updates the execution context.
+
+| Skill | Artifacts to Read | Context Updates |
+|-------|------------------|-----------------|
+| `maestro-analyze` | `.workflow/.csv-wave/*/context.md`, `state.json` | `gaps`, `phase`, `analysis_dir` |
+| `maestro-plan` | `{phase_dir}/plan.json`, `{phase_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
+| `maestro-brainstorm` | `.workflow/.csv-wave/*/.brainstorming/` | `brainstorm_dir`, `features` |
+| `maestro-spec-generate` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
+| `maestro-execute` | `.workflow/.csv-wave/*/results.csv` | `exec_status`, `completed_tasks`, `failed_tasks` |
+
+**Non-barrier skills** (can be grouped into multi-task waves): `maestro-verify`, `quality-review`, `quality-test`, `quality-debug`, `quality-refactor`, `quality-sync`, `manage-*`
+
+---
+
+## Chain Map
+
+| Intent keywords | Chain | Steps (skills, in order) |
+|----------------|-------|--------------------------|
+| fix, bug, error, broken, crash | `quality-fix` | $maestro-analyze --gaps → $maestro-plan --gaps → $maestro-execute → $maestro-verify |
+| test, spec, coverage | `quality-test` | $quality-test |
+| refactor, cleanup, debt | `quality-refactor` | $quality-refactor |
+| feature, implement, add, build | `feature` | $maestro-plan → $maestro-execute → $maestro-verify |
+| review, check, audit | `quality-review` | $quality-review |
+| deploy, release, ship | `deploy` | $maestro-verify → $maestro-execute |
+
+---
+
+## Implementation
+
+> **Full implementation reference**: The complete `detectTaskType`, `detectNextAction`, and `chainMap` definitions (35+ intent patterns, 40+ chain types) are in `~/.maestro/workflows/maestro.codex.md`. Read that file for authoritative logic before executing any step.
+
+### Session Initialization
+
+```javascript
+const dateStr = new Date().toISOString().substring(0, 10).replace(/-/g, '')
+const timeStr = new Date().toISOString().substring(11, 19).replace(/:/g, '')
+const sessionId = `MCC-${dateStr}-${timeStr}`
+const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`
+
+Bash(`mkdir -p ${sessionDir}`)
+```
+
+### Phase 1: Resolve Intent and Chain
+
+**`--continue` mode**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted by name desc; load the most recent; resume from first pending wave.
+
+**Fresh mode**:
+
+1. Read `.workflow/state.json` for project context (`current_phase`, `workflow_name`)
+2. If `--chain` is given, use it directly
+3. Otherwise, classify intent with keyword heuristics (see Chain Map above)
+4. If no keyword matches and not `AUTO_YES`: ask one clarifying question via `AskUserQuestion`
+5. Resolve the chain's skill list from Chain Map
+6. Write `state.json`:
+
+```javascript
+Write(`${sessionDir}/state.json`, JSON.stringify({
+  id: sessionId,
+  intent,
+  chain: resolvedChain,
+  auto_yes: AUTO_YES,
+  status: "in_progress",
+  started_at: new Date().toISOString(),
+  context: {
+    phase: resolvedPhase,
+    plan_dir: null,
+    analysis_dir: null,
+    brainstorm_dir: null,
+    spec_session_id: null,
+    gaps: null
+  },
+  waves: [],   // populated as waves execute
+  steps: chain.map((skill, i) => ({
+    step_n: i + 1,
+    skill: skill.cmd,
+    args: skill.args ?? '',
+    status: "pending",
+    wave_n: null
+  }))
+}, null, 2))
+```
+
+**`--dry-run`**: Display the chain plan and stop.
+
+```
+Chain:  <resolvedChain>
+Steps:
+  1. $<cmd> <args>
+  2. $<cmd> <args>  [BARRIER]
+  3. $<cmd> <args>
+```
+
+**User confirmation** (skip if `AUTO_YES`): Display the plan above and prompt `Proceed? (yes/no)`.
+
+---
+
+### Phase 2: Wave Execution Loop
+
+The coordinator iterates over pending steps, grouping them into waves and executing one wave at a time.
+
+#### Wave Grouping Rules
+
+1. A **barrier skill** is always alone in its wave (wave size = 1)
+2. Consecutive **non-barrier skills** with no inter-dependencies are grouped into one wave (wave size = N)
+3. After a barrier wave completes → coordinator analyzes artifacts → updates context → re-assembles subsequent step args
+
+#### Per-Wave Execution
+
+```javascript
+let waveNum = 0;
+
+while (state.steps.some(s => s.status === 'pending')) {
+  waveNum++;
+
+  // 1. Determine wave contents
+  const waveSteps = buildNextWave(state.steps);
+
+  // 2. Assemble skill_call for each step (with latest context)
+  const waveCsv = waveSteps.map((step, i) => ({
+    id: String(step.step_n),
+    skill_call: buildSkillCall(step, state.context),
+    topic: `Chain "${state.chain}" step ${step.step_n}/${state.steps.length}`
+  }));
+
+  // 3. Write wave CSV
+  const csvContent = 'id,skill_call,topic\n' + waveCsv.map(r =>
+    `"${r.id}","${r.skill_call.replace(/"/g, '""')}","${r.topic}"`
+  ).join('\n');
+  Write(`${sessionDir}/wave-${waveNum}.csv`, csvContent);
+
+  // 4. Execute wave
+  spawn_agents_on_csv({
+    csv_path: `${sessionDir}/wave-${waveNum}.csv`,
+    id_column: "id",
+    instruction: WAVE_INSTRUCTION,
+    max_workers: waveSteps.length > 1 ? waveSteps.length : 1,
+    max_runtime_seconds: 1800,
+    output_csv_path: `${sessionDir}/wave-${waveNum}-results.csv`,
+    output_schema: RESULT_SCHEMA
+  });
+
+  // 5. Read results, update step status
+  const results = readCSV(`${sessionDir}/wave-${waveNum}-results.csv`);
+  for (const row of results) {
+    const step = state.steps.find(s => s.step_n === parseInt(row.id));
+    step.status = row.status;
+    step.findings = row.findings;
+    step.wave_n = waveNum;
+  }
+
+  // 6. Barrier analysis (if wave contained a barrier skill)
+  if (isBarrier(waveSteps[0].skill)) {
+    analyzeBarrierArtifacts(waveSteps[0], results[0], state.context);
+  }
+
+  // 7. Persist state
+  state.waves.push({ wave_n: waveNum, steps: waveSteps.map(s => s.step_n), results });
+  Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+
+  // 8. Abort on failure
+  if (results.some(r => r.status === 'failed')) {
+    state.status = 'aborted';
+    state.steps.filter(s => s.status === 'pending').forEach(s => s.status = 'skipped');
+    Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+    break;
+  }
+}
+```
+
+---
+
+### Instruction Template (Simple)
+
+```
+你是 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"]
+};
+```
+
+---
+
+### Barrier Analysis Logic
+
+After a barrier skill completes, the coordinator reads its artifacts and updates `state.context`:
+
+```javascript
+function analyzeBarrierArtifacts(step, result, ctx) {
+  const artifactPath = result.artifacts;
+
+  switch (step.skill) {
+    case 'maestro-analyze':
+      // Read analysis conclusions → extract gaps, phase info
+      const contextMd = Read(`${artifactPath}/context.md`);
+      ctx.analysis_dir = artifactPath;
+      ctx.gaps = extractGaps(contextMd);  // grep for gap/issue markers
+      if (!ctx.phase) ctx.phase = extractPhase(contextMd);
+      break;
+
+    case 'maestro-plan':
+      // Read plan.json → know task structure for execute
+      const planJson = JSON.parse(Read(`${artifactPath}/plan.json`));
+      ctx.plan_dir = artifactPath;
+      ctx.task_count = planJson.tasks?.length ?? 0;
+      ctx.wave_count = planJson.waves?.length ?? 0;
+      break;
+
+    case 'maestro-brainstorm':
+      // Read brainstorm output → features for plan
+      ctx.brainstorm_dir = artifactPath;
+      break;
+
+    case 'maestro-spec-generate':
+      ctx.spec_session_id = extractSpecId(artifactPath);
+      break;
+
+    case 'maestro-execute':
+      // Read execution results → completed/failed counts
+      const execResults = Read(`${artifactPath}/results.csv`);
+      ctx.exec_completed = countStatus(execResults, 'completed');
+      ctx.exec_failed = countStatus(execResults, 'failed');
+      break;
+  }
+}
+```
+
+### Skill Call Assembly
+
+The coordinator builds each `skill_call` with resolved context — sub-agents just execute verbatim:
+
+```javascript
+const BARRIER_SKILLS = new Set([
+  'maestro-analyze', 'maestro-plan', 'maestro-brainstorm',
+  'maestro-spec-generate', 'maestro-execute'
+]);
+
+const AUTO_FLAG_MAP = {
+  'maestro-analyze': '-y', 'maestro-brainstorm': '-y',
+  'maestro-ui-design': '-y', 'maestro-plan': '--auto',
+  'maestro-spec-generate': '-y', 'quality-test': '--auto-fix',
+  'quality-retrospective': '--auto-yes',
+};
+
+function buildSkillCall(step, ctx) {
+  let args = (step.args ?? '')
+    .replace(/{phase}/g, ctx.phase ?? '')
+    .replace(/{description}/g, state.intent ?? '')
+    .replace(/{issue_id}/g, ctx.issue_id ?? '')
+    .replace(/{plan_dir}/g, ctx.plan_dir ?? '')
+    .replace(/{analysis_dir}/g, ctx.analysis_dir ?? '')
+    .replace(/{brainstorm_dir}/g, ctx.brainstorm_dir ?? '')
+    .replace(/{spec_session_id}/g, ctx.spec_session_id ?? '');
+
+  if (state.auto_yes) {
+    const flag = AUTO_FLAG_MAP[step.skill];
+    if (flag && !args.includes(flag)) args = args ? `${args} ${flag}` : flag;
+  }
+
+  return `$${step.skill} ${args}`.trim();
+}
+
+function buildNextWave(steps) {
+  const pending = steps.filter(s => s.status === 'pending');
+  if (!pending.length) return [];
+
+  const first = pending[0];
+  // Barrier skill → solo wave
+  if (BARRIER_SKILLS.has(first.skill)) return [first];
+
+  // Group consecutive non-barriers
+  const wave = [first];
+  for (let i = 1; i < pending.length; i++) {
+    if (BARRIER_SKILLS.has(pending[i].skill)) break;
+    wave.push(pending[i]);
+  }
+  return wave;
+}
+```
+
+---
+
+### Phase 3: Completion Report
+
+```javascript
+state.status = state.steps.every(s => s.status === 'completed') ? 'completed' : state.status;
+state.completed_at = new Date().toISOString();
+Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
+```
+
+Generate `context.md`:
+
+```markdown
+# Coordinate Report — {chain}
+
+## Summary
+- Session: {sessionId}
+- Chain: {chain}
+- Waves: {waveNum} executed
+- Steps: {completed}/{total} completed
+
+## Wave Results
+### Wave {N} (barrier: {skill})
+| Step | Skill Call | Status | Summary |
+|------|-----------|--------|---------|
+| {step_n} | {skill_call} | {status} | {summary} |
+
+Artifacts: {artifacts}
+Context update: {what changed}
+```
+
+Display:
+
+```
+=== COORDINATE COMPLETE ===
+Session:  <sessionId>
+Chain:    <chain>
+Waves:    <N> executed
+Steps:    <completed>/<total>
+
+WAVE RESULTS:
+  [W1] $maestro-analyze --gaps  →  ✓  found 3 gaps
+  [W2] $maestro-plan --gaps     →  ✓  12 tasks in 3 waves
+  [W3] $maestro-execute         →  ✓  12/12 tasks done
+  [W4] $maestro-verify          →  ✓  all criteria met
+
+State:    .workflow/.maestro-coordinate/<sessionId>/state.json
+Resume:   $maestro --continue
+```
+
+---
+
+## CSV Schema
+
+### wave-{N}.csv (Per-Wave Input)
+
+```csv
+id,skill_call,topic
+"1","$maestro-analyze --gaps \"fix auth\" -y","Chain \"quality-fix\" step 1/4"
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Step number from chain (string) |
+| `skill_call` | Full skill invocation assembled by coordinator with resolved context |
+| `topic` | Brief description for the agent |
+
+### tasks.csv (Master State)
+
+```csv
+id,skill,args,wave_n,status,findings,artifacts,error
+```
+
+Accumulated across all waves. Updated after each wave completes.
+
+---
+
+## Error Handling
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Intent unclassifiable after clarification | Default to `feature` chain |
+| E002 | error | `--chain` value not in chain map | List valid chains, abort |
+| E003 | error | Wave timeout (max_runtime_seconds) | Mark step `failed`, abort chain |
+| E004 | error | Barrier artifact not found | Retry wave once, then abort |
+| E005 | error | `--continue`: no session found | List sessions, prompt |
+| W001 | warning | Barrier artifact partial | Continue with available context |
+
+---
+
+## Core Rules
+
+1. **Start Immediately**: Init session dir and write `state.json` before any wave
+2. **Wave-by-wave**: Never start wave N+1 before wave N results are read and analyzed
+3. **Barrier = solo wave**: A barrier skill always executes alone; coordinator analyzes its artifacts before proceeding
+4. **Non-barriers can parallel**: Consecutive non-barrier skills in the same wave execute with `max_workers = N`
+5. **Coordinator owns context**: Sub-agents never read prior results — coordinator assembles the full `skill_call` with resolved args
+6. **Simple instruction**: Sub-agent instruction is minimal — just "execute {skill_call}, report result"
+7. **Abort on failure**: Failed step → mark remaining as skipped → report
+8. **State.json tracks waves**: Each wave is recorded with step IDs and results for resume
+9. **Dry-run is read-only**: Display chain with [BARRIER] markers, no execution
+10. **Resume from wave**: `--continue` finds last completed wave and resumes from next pending step