maestro-flow 0.3.10 → 0.3.12

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

@@ -0,0 +1,86 @@
+---
+name: learn-second-opinion
+description: Multi-perspective analysis via CSV wave pipeline. Review mode spawns 3 parallel persona agents (pragmatist, purist, strategist), then synthesis agent merges verdicts. Also supports challenge and consult modes. Persists findings to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency 3] [--continue] \"<target> [--mode review|challenge|consult]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Structured second-opinion for code, decisions, or plans. Three modes:
+- **review** (default): 3 parallel persona agents independently assess target via spawn_agents_on_csv
+- **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
+- **consult**: interactive Q&A (no CSV wave — direct orchestration)
+
+Findings persist to `lessons.jsonl`. Decoupled from phase lifecycle.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → analyze file content
+- Wiki ID (`type-slug`) → fetch via `maestro wiki get`
+- `HEAD` / `staged` → analyze git diff
+- Phase number → analyze phase plan
+
+**Flags:**
+- `--mode review` — 3-persona parallel review (default)
+- `--mode challenge` — Adversarial single-agent analysis
+- `--mode consult` — Interactive Q&A session
+
+**Output**: `.workflow/learning/opinion-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Phase 1: Resolve Target + Load Context
+Resolve target to content. Load specs, wiki search, prior lessons for context brief.
+
+### Phase 2: Execute Mode
+
+#### Review Mode (spawn_agents_on_csv)
+
+| id | persona | focus | grading |
+|----|---------|-------|---------|
+| 1 | pragmatist | Simplicity, YAGNI, maintenance cost, readability | complexity score, abstraction depth |
+| 2 | purist | Correctness, type safety, edge cases, error handling | error paths, type completeness |
+| 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
+| 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
+
+Wave 1: 3 persona agents in parallel. Wave 2: synthesis agent with wave 1 findings as prev_context.
+
+Each persona returns: `{ persona, verdict: approve|concern|reject, confidence, findings: [{severity, description, location, suggestion}], summary }`
+
+#### Challenge Mode
+Single agent via spawn_agents_on_csv (1 worker). Adversarial analysis with forcing questions:
+- "What assumption would invalidate this entire approach?"
+- "What's the simplest thing that breaks this?"
+- "What's the implicit contract that isn't enforced?"
+
+#### Consult Mode
+Interactive loop via AskUserQuestion. Agent studies target, answers questions with code references. Compile Q&A into report on exit.
+
+### Phase 3: Persist
+1. Write `opinion-{slug}-{date}.md` with per-persona findings + synthesis
+2. Append non-trivial findings to `lessons.jsonl` (source: "second-opinion")
+3. Display summary with verdict and next steps
+
+**Next steps:** `/manage-issue create`, `/learn-decompose <path>`, `/learn-follow <path>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Verify path/ID |
+| E002 | error | Unknown --mode value | Use: review, challenge, consult |
+| W001 | warning | Persona agent failed — partial perspectives | Proceed with available agents |
+| W003 | warning | Git diff empty for HEAD/staged | Use file path instead |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved and context loaded
+- [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
+- [ ] Synthesis produced with agreements, disagreements, verdict
+- [ ] Report written to `opinion-{slug}-{date}.md`
+- [ ] Non-trivial findings appended to `lessons.jsonl`
+</success_criteria>

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

@@ -1,75 +1,51 @@
 ---
 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.
+description: Intelligent coordinator — analyze intent, read project state, select chain, execute wave-by-wave via spawn_agents_on_csv. Coordinator only assembles prompts and reads artifacts — never executes skills directly.
 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
+<purpose>
+Wave-based pipeline coordinator. All skill execution happens exclusively in spawned sub-agents
+via `spawn_agents_on_csv` — the coordinator never executes skills directly.
 
-When `-y` or `--yes`: Skip clarification and confirmation prompts. Pass `-y` through to each step's skill invocation.
+Coordinator loop: classify intent → resolve chain → build wave CSV → spawn → read results →
+(barrier: read artifacts, update context, assemble next skill_call args) → next wave → report.
 
-# Maestro
+Each wave = 1 barrier task (solo) or N parallel non-barrier tasks.
+</purpose>
 
-## Usage
+<required_reading>
+@~/.maestro/workflows/maestro.codex.md — authoritative `detectTaskType`, `detectNextAction`, `chainMap` (35+ intent patterns, 40+ chain types). Read before executing any step.
+</required_reading>
 
-```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"
-```
+<context>
+$ARGUMENTS — user intent text, or special flags.
 
-**Flags**:
+**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)
+- `--chain <name>` — Force 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
-
+**Core output**: `tasks.csv` (master) + `wave-{N}-results.csv` (per wave) + `context.md` (report)
+</context>
+
+<invariants>
+1. **ALL skills via spawn_agents_on_csv**: Every skill invocation — barrier or non-barrier — MUST go through `spawn_agents_on_csv`. Coordinator NEVER directly executes any skill. No exceptions.
+2. **Coordinator = prompt assembler only**: Classify intent → build CSV → spawn → read results → assemble next CSV. It never runs skill logic itself.
+3. **Barrier ≠ execution**: Barrier designation only means the coordinator **pauses after the wave** to read artifacts and assemble the next wave's prompt args. Coordinator role at barrier: **discover artifacts → read → update context → assemble next skill_call args**. Nothing more.
+4. **Barrier = solo wave**: A barrier skill always executes alone in its wave (wave size = 1).
+5. **Non-barriers can parallel**: Consecutive non-barrier skills grouped into one wave (`max_workers = N`).
+6. **Wave-by-wave**: Never start wave N+1 before wave N results are read and analyzed.
+7. **Coordinator owns context**: Sub-agents never read prior results — coordinator assembles the full `skill_call` with resolved args.
+8. **Simple instruction**: Sub-agent instruction is minimal — just "execute {skill_call}, report result".
+9. **Abort on failure**: Failed step → mark remaining as skipped → report.
+10. **Resume from wave**: `--continue` finds last completed wave, resumes from next pending step.
+</invariants>
+
+<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 |
@@ -78,142 +54,131 @@ Skills that produce artifacts requiring **coordinator-side analysis** before the
 | 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 |
+</chain_map>
 
----
+<barrier_skills>
+Skills that produce artifacts the coordinator must read before assembling the next wave.
+After a barrier skill completes **in its spawned sub-agent**, coordinator reads output and updates `state.context`.
 
-## Implementation
+| 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` |
 
-> **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.
+**Non-barrier skills** (groupable into multi-task waves): `maestro-verify`, `quality-review`, `quality-test`, `quality-debug`, `quality-refactor`, `quality-sync`, `manage-*`
 
-### Session Initialization
+### Barrier Analysis Logic
 
 ```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}`)
+function analyzeBarrierArtifacts(step, result, ctx) {
+  const artifactPath = result.artifacts;
+  switch (step.skill) {
+    case 'maestro-analyze':
+      const contextMd = Read(`${artifactPath}/context.md`);
+      ctx.analysis_dir = artifactPath;
+      ctx.gaps = extractGaps(contextMd);
+      if (!ctx.phase) ctx.phase = extractPhase(contextMd);
+      break;
+    case 'maestro-plan':
+      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':
+      ctx.brainstorm_dir = artifactPath;
+      break;
+    case 'maestro-spec-generate':
+      ctx.spec_session_id = extractSpecId(artifactPath);
+      break;
+    case 'maestro-execute':
+      const execResults = Read(`${artifactPath}/results.csv`);
+      ctx.exec_completed = countStatus(execResults, 'completed');
+      ctx.exec_failed = countStatus(execResults, 'failed');
+      break;
+  }
+}
 ```
+</barrier_skills>
+
+<execution>
 
 ### 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.
+**`--continue`**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted desc; load 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
+2. If `--chain` given, use directly
+3. Otherwise classify intent via keyword heuristics (see chain_map)
+4. No match + not AUTO_YES → one clarifying question via `AskUserQuestion`
+5. Resolve chain's skill list
 6. Write `state.json`:
 
 ```javascript
+const sessionId = `MCC-${dateStr}-${timeStr}`;
+const sessionDir = `.workflow/.maestro-coordinate/${sessionId}`;
+
 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
+  id: sessionId, intent, chain: resolvedChain, auto_yes: AUTO_YES,
+  status: "in_progress", started_at: new Date().toISOString(),
+  context: { phase: null, plan_dir: null, analysis_dir: null,
+             brainstorm_dir: null, spec_session_id: null, gaps: null },
+  waves: [],
   steps: chain.map((skill, i) => ({
-    step_n: i + 1,
-    skill: skill.cmd,
-    args: skill.args ?? '',
-    status: "pending",
-    wave_n: null
+    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>
+}, null, 2));
 ```
 
-**User confirmation** (skip if `AUTO_YES`): Display the plan above and prompt `Proceed? (yes/no)`.
+**`--dry-run`**: Display chain with `[BARRIER]` markers, stop.
 
----
+**User confirmation** (skip if AUTO_YES): Display plan, 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}"`
+  // Build CSV — coordinator assembles skill_call, sub-agent executes verbatim
+  const csvContent = 'id,skill_call,topic\n' + waveSteps.map(step =>
+    `"${step.step_n}","${buildSkillCall(step, state.context).replace(/"/g, '""')}","Chain \"${state.chain}\" step ${step.step_n}/${state.steps.length}"`
   ).join('\n');
   Write(`${sessionDir}/wave-${waveNum}.csv`, csvContent);
 
-  // 4. Execute wave
+  // Spawn — ALL execution via spawn_agents_on_csv, never direct
   spawn_agents_on_csv({
     csv_path: `${sessionDir}/wave-${waveNum}.csv`,
-    id_column: "id",
-    instruction: WAVE_INSTRUCTION,
+    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
+  // Read results, update 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;
+    step.status = row.status; step.findings = row.findings; step.wave_n = waveNum;
   }
 
-  // 6. Barrier analysis (if wave contained a barrier skill)
+  // Barrier: read artifacts, update context (NOT execute — skill already ran in sub-agent)
   if (isBarrier(waveSteps[0].skill)) {
     analyzeBarrierArtifacts(waveSteps[0], results[0], state.context);
   }
 
-  // 7. Persist state
+  // Persist + abort check
   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');
@@ -223,99 +188,13 @@ while (state.steps.some(s => s.status === 'pending')) {
 }
 ```
 
----
-
-### 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',
@@ -332,25 +211,18 @@ function buildSkillCall(step, ctx) {
     .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];
+  if (BARRIER_SKILLS.has(pending[0].skill)) return [pending[0]];
+  const wave = [pending[0]];
   for (let i = 1; i < pending.length; i++) {
     if (BARRIER_SKILLS.has(pending[i].skill)) break;
     wave.push(pending[i]);
@@ -359,38 +231,42 @@ function buildNextWave(steps) {
 }
 ```
 
----
-
-### Phase 3: Completion Report
+### Sub-Agent Instruction Template
 
-```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));
 ```
+你是 CSV job 子 agent。
 
-Generate `context.md`:
+先原样执行这一段技能调用：
+{skill_call}
 
-```markdown
-# Coordinate Report — {chain}
+然后基于结果完成这一行任务说明：
+{topic}
 
-## Summary
-- Session: {sessionId}
-- Chain: {chain}
-- Waves: {waveNum} executed
-- Steps: {completed}/{total} completed
+限制：
+- 不要修改 .workflow/.maestro-coordinate/ 下的 state 文件
+- skill 内部有自己的 session 管理，按 skill SKILL.md 执行即可
 
-## Wave Results
-### Wave {N} (barrier: {skill})
-| Step | Skill Call | Status | Summary |
-|------|-----------|--------|---------|
-| {step_n} | {skill_call} | {status} | {summary} |
+最后必须调用 `report_agent_job_result`，返回 JSON：
+{"status":"completed|failed","skill_call":"{skill_call}","summary":"一句话结果","artifacts":"产物路径或空字符串","error":"失败原因或空字符串"}
+```
 
-Artifacts: {artifacts}
-Context update: {what changed}
+### 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"]
+};
 ```
 
-Display:
+### Phase 3: Completion Report
 
 ```
 === COORDINATE COMPLETE ===
@@ -408,11 +284,9 @@ WAVE RESULTS:
 State:    .workflow/.maestro-coordinate/<sessionId>/state.json
 Resume:   $maestro --continue
 ```
+</execution>
 
----
-
-## CSV Schema
-
+<csv_schema>
 ### wave-{N}.csv (Per-Wave Input)
 
 ```csv
@@ -433,11 +307,9 @@ id,skill,args,wave_n,status,findings,artifacts,error
 ```
 
 Accumulated across all waves. Updated after each wave completes.
+</csv_schema>
 
----
-
-## Error Handling
-
+<error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Intent unclassifiable after clarification | Default to `feature` chain |
@@ -446,18 +318,18 @@ Accumulated across all waves. Updated after each wave completes.
 | 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
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain resolved (keyword heuristics or `--chain`)
+- [ ] Session dir initialized with `state.json` before first wave
+- [ ] Every skill invocation goes through `spawn_agents_on_csv` — none executed in coordinator
+- [ ] Barrier skills execute solo in their wave; coordinator only reads artifacts afterward
+- [ ] Non-barrier skills grouped into parallel waves where possible
+- [ ] Each wave: CSV built → spawned → results read → state updated
+- [ ] Barrier artifacts read and context updated before assembling next wave's skill_call args
+- [ ] Failed step → remaining marked skipped → abort reported
+- [ ] Completion report with per-wave status written to `context.md`
+- [ ] `--dry-run` shows chain with [BARRIER] markers, no execution
+- [ ] `--continue` resumes from last incomplete wave
+</success_criteria>