maestro-flow 0.4.6 → 0.4.7

package/.codex/skills/team-coordinate/SKILL.md

@@ -1,235 +1,462 @@
----
-name: team-coordinate
-description: Universal team coordination with dynamic role generation
-allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__maestro-tools__team_msg(*)
----
-
-<purpose>
-Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** as lightweight role-spec files and spawned via the `team-worker` agent.
-
-```
-+---------------------------------------------------+
-|  Skill(skill="team-coordinate")                 |
-|  args="task description"                           |
-+-------------------+-------------------------------+
-                    |
-         Orchestration Mode (auto -> coordinator)
-                    |
-              Coordinator (built-in)
-              Phase 0-5 orchestration
-                    |
-    +-------+-------+-------+-------+
-    v       v       v       v       v
- [team-worker agents, each loaded with a dynamic role-spec]
-  (roles generated at runtime from task analysis)
-
-  CLI Tools (callable by any worker):
-    maestro delegate --mode analysis  - analysis and exploration
-    maestro delegate --mode write     - code generation and modification
-```
-
-</purpose>
-
-<context>
-### Delegation Lock
-
-**Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.**
-
-Before calling ANY tool, apply this check:
-
-| Tool Call | Verdict | Reason |
-|-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
-| `list_agents` | ALLOWED | Agent health check |
-| `request_user_input` | ALLOWED | User interaction |
-| `mcp__maestro-tools__team_msg` | ALLOWED | Message bus |
-| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
-| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading own instructions |
-| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
-| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
-| `Bash("maestro delegate ...")` | BLOCKED | Only workers call CLI |
-| `Bash` running build/test/lint commands | BLOCKED | Delegate to worker |
-
-**If a tool call is BLOCKED**: STOP. Create a task, spawn a worker.
-
-**No exceptions for "simple" tasks.** Even a single-file read-and-report MUST go through spawn_agent. The overhead is the feature -- it provides session tracking, artifact persistence, and resume capability.
-
-### Shared Constants
-
-| Constant | Value |
-|----------|-------|
-| Session prefix | `TC` |
-| Session path | `.workflow/.team/TC-<slug>-<date>/` |
-| Worker agent | `team-worker` |
-| Message bus | `mcp__maestro-tools__team_msg(session_id=<session-id>, ...)` |
-| CLI analysis | `maestro delegate --mode analysis` |
-| CLI write | `maestro delegate --mode write` |
-| Max roles | 5 |
-
-### Role Router
-
-This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
-
-Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
-
-### Role Registry
-
-Only coordinator is statically registered. All other roles are dynamic, stored as role-specs in session.
-
-| Role | File | Type |
-|------|------|------|
-| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | built-in orchestrator |
-| (dynamic) | `<session>/role-specs/<role-name>.md` | runtime-generated role-spec |
-
-### CLI Tool Usage
-
-Workers can use CLI tools for analysis and code operations:
-
-| Tool | Purpose |
-|------|---------|
-| maestro delegate --mode analysis | Analysis, exploration, pattern discovery |
-| maestro delegate --mode write | Code generation, modification, refactoring |
-
-### Orchestration Mode
-
-**Invocation**: `Skill(skill="team-coordinate", args="task description")`
-
-**Lifecycle**: Phase 1 (task analysis, dependency graph) -> Phase 2 (generate role-specs, init session) -> Phase 3 (create task chain) -> Phase 4 (spawn workers, STOP) -> callback loop -> Phase 5 (report + completion).
-
-**User Commands** (wake paused coordinator):
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | Output execution status graph, no advancement |
-| `resume` / `continue` | Check worker states, advance next step |
-| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
-| `feedback <text>` | Inject feedback into active pipeline |
-| `improve [dimension]` | Auto-improve weakest quality dimension |
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent with role-spec path. Message includes: role, role_spec path, session folder, session_id, requirement, inner_loop flag, task context (id, title, description, pipeline_phase), and upstream context from prior tasks.
-
-After spawning: `wait_agent` (30 min timeout). On timeout: STATUS_CHECK via followup_task (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out, close agent.
-
-**Inner Loop**: Set `inner_loop: true` for roles with 2+ serial same-prefix tasks. Single-task roles: `inner_loop: false`.
-
-### Model Selection Guide
-
-Map each role's `responsibility_type` (from `team-session.json#roles`) to reasoning effort:
-
-| responsibility_type | reasoning_effort |
-|---------------------|-------------------|
-| exploration | medium |
-| analysis | high |
-| implementation | high |
-| synthesis | medium |
-| review | high |
-
-Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
-
-### v4 Agent Coordination
-
-**Message Semantics**: `send_message` to queue supplementary info to downstream workers (non-interrupting). `list_agents` for health checks. `followup_task` not used (all workers are one-shot).
-
-**fork_turns**: Default `"none"`. Use `"all"` only when task requires deep familiarity with full conversation context (decided per-task in Phase 4).
-
-**Agent Health Check**: On resume/complete, reconcile `team-session.json.active_workers` with `list_agents({})`. Reset orphaned tasks (in_progress but agent gone) to pending.
-
-**Named Targeting**: Workers spawned with `task_name: "<task-id>"` for `send_message`/`close_agent` by name.
-
-### Completion Action
-
-Present interactive choice via `request_user_input`: **Archive & Clean** (recommended -- mark completed, output summary), **Keep Active** (mark paused, output resume command), **Export Results** (prompt target path, copy artifacts, then archive).
-
-### Specs Reference
-
-| Spec | Purpose |
-|------|---------|
-| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
-| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
-| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
-| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
-
-### Session Directory
-
-```
-.workflow/.team/TC-<slug>-<date>/
-+-- team-session.json           # Session state + dynamic role registry
-+-- task-analysis.json          # Phase 1 output: capabilities, dependency graph
-+-- role-specs/                 # Dynamic role-spec definitions (generated Phase 2)
-|   +-- <role-1>.md             # Lightweight: frontmatter + Phase 2-4 only
-|   +-- <role-2>.md
-+-- artifacts/                  # All MD deliverables from workers
-|   +-- <artifact>.md
-+-- .msg/                       # Team message bus + state
-|   +-- messages.jsonl          # Message log
-|   +-- meta.json               # Session metadata + cross-role state
-+-- wisdom/                     # Cross-task knowledge
-|   +-- learnings.md
-|   +-- decisions.md
-|   +-- issues.md
-+-- explorations/               # Shared explore cache
-|   +-- cache-index.json
-|   +-- explore-<angle>.json
-+-- discussions/                # Inline discuss records
-|   +-- <round>.md
-```
-
-#### team-session.json Schema
-
-```json
-{
-  "session_id": "TC-<slug>-<date>",
-  "task_description": "<original user input>",
-  "status": "active | paused | completed",
-  "team_name": "<team-name>",
-  "roles": [
-    {
-      "name": "<role-name>",
-      "prefix": "<PREFIX>",
-      "responsibility_type": "<type>",
-      "inner_loop": false,
-      "role_spec": "role-specs/<role-name>.md"
-    }
-  ],
-  "pipeline": {
-    "dependency_graph": {},
-    "tasks_total": 0,
-    "tasks_completed": 0
-  },
-  "active_workers": [],
-  "completed_tasks": [],
-  "completion_action": "interactive",
-  "created_at": "<timestamp>"
-}
-```
-
-### Session Resume
-
-Scan `TC-*/team-session.json` for active/paused sessions (prompt if multiple). Reconcile state: reset interrupted tasks to pending, rebuild team, spawn needed workers, resume Phase 4 loop.
-</context>
-
-<error_codes>
-
-| Scenario | Resolution |
-|----------|------------|
-| Unknown command | Error with available command list |
-| Dynamic role-spec not found | Error, coordinator may need to regenerate |
-| Command file not found | Fallback to inline execution |
-| CLI tool fails | Worker proceeds with direct implementation, logs warning |
-| Explore cache corrupt | Clear cache, re-explore |
-| Fast-advance spawns wrong task | Coordinator reconciles on next callback |
-| capability_gap reported | Coordinator generates new role-spec via handleAdapt |
-| Completion action fails | Default to Keep Active, log warning |
-</error_codes>
-
-<success_criteria>
-- [ ] Task analysis produces dependency graph and role definitions
-- [ ] Role-spec files generated in session directory
-- [ ] Workers spawned via team-worker agent with correct role-spec paths
-- [ ] Pipeline executes wave-by-wave respecting dependency graph
-- [ ] Session state persisted in team-session.json after each wave
-- [ ] Completion action presented and handled correctly
-- [ ] Session resumable after interruption
-</success_criteria>
+---
+name: team-coordinate
+description: Universal team coordination with dynamic role generation
+argument-hint: "[task description] [-y|--yes] [-c|--concurrency N] [--continue]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Wave-based multi-role coordination via `spawn_agents_on_csv`. Dynamic role generation + linear wave execution with per-wave evaluation gates.
+
+**Core difference from other team skills**: Roles are NOT predefined — they are dynamically generated from task analysis at runtime. Each role's behavioral instructions are encoded directly into the CSV `description` column, eliminating the need for role-spec files.
+
+**Core workflow**: Analyze Task → Generate Dynamic Roles → Build CSV → Wave-by-Wave Execution with Evaluation → Aggregate Results
+
+```
++-------------------------------------------------------------------+
+|                  TEAM-COORDINATE CSV WAVE WORKFLOW                  |
++-------------------------------------------------------------------+
+|                                                                     |
+|  Phase 1: Task Analysis + CSV Generation                           |
+|     +-- Parse task description (text-level only)                   |
+|     +-- Signal detection → capability inference                    |
+|     +-- Dynamic role generation (max 5 roles)                      |
+|     +-- Wave assignment (4-tier linear topology)                   |
+|     +-- Evaluation criteria per task                               |
+|     +-- Build tasks.csv with role instructions in description      |
+|     +-- User validates (skip if -y)                                |
+|                                                                     |
+|  Phase 2: Wave Execution Engine                                    |
+|     +-- For each wave N (sequential):                              |
+|     |   +-- EVALUATE: check evaluation_criteria vs findings        |
+|     |   +-- Skip wave if all tasks evaluated out                   |
+|     |   +-- Build prev_context from upstream findings              |
+|     |   +-- spawn_agents_on_csv(wave-N.csv)                        |
+|     |   +-- Merge results → master tasks.csv                       |
+|     |   +-- Cascading skip on failure                              |
+|     |   +-- Cleanup temp files                                     |
+|     +-- discoveries.ndjson shared across all waves                 |
+|                                                                     |
+|  Phase 3: Results Aggregation                                      |
+|     +-- Export results.csv                                         |
+|     +-- Generate context.md                                        |
+|     +-- Display summary with deliverables                          |
+|                                                                     |
++-------------------------------------------------------------------+
+```
+
+</purpose>
+
+<context>
+```bash
+$team-coordinate "design and implement auth module"
+$team-coordinate -y -c 3 "analyze performance bottlenecks"
+$team-coordinate --continue "20260518-team-auth-system"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 5)
+- `--continue`: Resume existing session
+
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-team-{slug}/`
+**Output**: tasks.csv, results.csv, discoveries.ndjson, context.md
+
+### Pre-load specs (optional)
+
+1. `maestro spec load --category arch` — architecture constraints
+2. `maestro wiki search "<topic>"` — relevant knowhow
+3. Proceed without if unavailable.
+
+### Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/role-catalog.md](specs/role-catalog.md) | Signal detection, role definitions, wave tiers, evaluation criteria, quality gates |
+</context>
+
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,role,deps,context_from,wave,evaluation_criteria
+"RESEARCH-001","Explore auth patterns","PURPOSE: Investigate authentication patterns in codebase | Success: Documented patterns with file references\nTASK:\n  - Scan src/ for existing auth implementations\n  - Identify JWT/session/OAuth patterns\n  - Document integration points\nCONTEXT:\n  - Key files: src/auth/**, src/middleware/**\nEXPECTED: Research findings with evidence\nCONSTRAINTS: Read-only analysis","researcher","","","1","always"
+"DESIGN-001","Design auth architecture","PURPOSE: Design authentication module architecture | Success: Architecture doc with data model and API design\nTASK:\n  - Design token lifecycle\n  - Define middleware chain\n  - Specify error handling\nCONTEXT:\n  - Upstream: RESEARCH-001 findings\nEXPECTED: Architecture document\nCONSTRAINTS: Follow existing patterns","designer","RESEARCH-001","RESEARCH-001","2","if wave_1 findings indicate architecture decisions needed"
+"IMPL-001","Implement auth module","PURPOSE: Implement authentication module | Success: Working auth with tests\nTASK:\n  - Create auth middleware\n  - Implement JWT utilities\n  - Add integration tests\nCONTEXT:\n  - Upstream: DESIGN-001 architecture\nEXPECTED: Source files + test coverage\nCONSTRAINTS: Follow design spec","developer","DESIGN-001","DESIGN-001","3","if wave_2 produced design artifacts"
+"TEST-001","Validate auth implementation","PURPOSE: Validate auth module quality | Success: All tests pass, security checks clear\nTASK:\n  - Run full test suite\n  - Security audit on auth paths\n  - Verify error handling\nCONTEXT:\n  - Upstream: IMPL-001 files_modified\nEXPECTED: Test report + security findings\nCONSTRAINTS: No code modifications","tester","IMPL-001","IMPL-001","4","if wave_3 produced testable artifacts (files_modified non-empty)"
+```
+
+**Input columns** (present in initial tasks.csv and wave-N.csv):
+
+| Column | Description |
+|--------|-------------|
+| `id` | Task ID: `{PREFIX}-{NNN}` (dynamic prefix from role catalog) |
+| `title` | Short task title |
+| `description` | **Full role-specific instructions** — PURPOSE, TASK steps, CONTEXT, EXPECTED, CONSTRAINTS. This replaces role-spec files. |
+| `role` | Dynamic role name (from Phase 1 signal detection) |
+| `deps` | Semicolon-separated dependency task IDs |
+| `context_from` | Semicolon-separated task IDs whose findings needed as context |
+| `wave` | Wave number (1-4) |
+| `evaluation_criteria` | Condition: `always` or conditional expression |
+
+**Lifecycle columns** (initialized in tasks.csv Phase 1, updated during execution):
+
+| Column | Initial Value | Description |
+|--------|--------------|-------------|
+| `status` | `pending` | Task lifecycle: pending → completed/failed/blocked/skipped |
+| `findings` | `""` | Populated from output_schema `result_status` merge |
+| `files_modified` | `""` | Populated from output_schema merge |
+| `error` | `""` | Populated from output_schema merge |
+
+**Output columns** (returned exclusively via `output_schema`, NOT in wave CSV):
+
+| Column | Description |
+|--------|-------------|
+| `result_status` | completed / failed / blocked (maps to master `status` during merge) |
+| `findings` | Key findings summary (max 500 chars) |
+| `files_modified` | Semicolon-separated file paths |
+| `error` | Error message if failed |
+
+**Column separation rule**: Input columns and output_schema MUST NOT share names. Wave CSV contains Input columns + `prev_context` (dynamic, built from upstream findings). Output columns returned via `output_schema` using `result_status` (not `status`). Merge mapping: `result_status` → master `status`.
+
+**prev_context format** (added to wave-N.csv only):
+```
+--- TASK-ID: RESEARCH-001 ---
+{findings from RESEARCH-001}
+--- TASK-ID: DESIGN-001 ---
+{findings from DESIGN-001}
+```
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates `wave-{N}.csv` with Input columns + `prev_context` (populated from upstream task findings).
+
+### Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `wave-{N}-results.csv` | Per-wave output (uses `result_status`) | Created by spawn_agents_on_csv, deleted after merge |
+| `results.csv` | Final export of all task results | Created in Phase 3 |
+| `discoveries.ndjson` | Shared exploration board | Append-only across waves |
+| `context.md` | Human-readable report | Created in Phase 3 |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-team-{slug}/
++-- tasks.csv
++-- results.csv
++-- discoveries.ndjson
++-- context.md
++-- wave-{N}.csv (temporary)
++-- wave-{N}-results.csv (temporary)
+```
+</csv_schema>
+
+<invariants>
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave N+1 before wave N completes and results merge
+3. **CSV is Source of Truth**: Master tasks.csv holds all execution state
+4. **Column Separation Rule**: Input columns and output_schema MUST NOT share names
+5. **Context Propagation**: prev_context built from master CSV findings, not from memory
+6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
+7. **Evaluate Before Execute**: Wave 2+ tasks MUST pass evaluation gate before inclusion
+8. **Cascading Skip on Failure**: Failed/blocked tasks cascade skip to all dependents
+9. **Cleanup Temp Files**: Delete `wave-{N}.csv` AND `wave-{N}-results.csv` after merge
+10. **DO NOT STOP**: Continuous execution until all waves complete or user stops
+11. **Max 5 Roles**: Dynamic role count capped at 5; merge overlapping if exceeded
+12. **Dynamic Roles in CSV**: Role instructions encoded in `description` column, not in separate files
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE      — Parse arguments, detect mode (new/continue)       PERSIST: —
+S_ANALYZE    — Signal detection, role generation, task decomp     PERSIST: —
+S_CSV_GEN    — Generate tasks.csv with dynamic roles              PERSIST: tasks.csv
+S_EVAL_W1    — Evaluate Wave 1 (always passes)                    PERSIST: —
+S_WAVE_1     — Execute Wave 1 (Analysis/Research)                 PERSIST: findings in master CSV
+S_EVAL_W2    — Evaluate Wave 2 participation                      PERSIST: skipped tasks if any
+S_WAVE_2     — Execute Wave 2 (Design/Planning)                   PERSIST: findings in master CSV
+S_EVAL_W3    — Evaluate Wave 3 participation                      PERSIST: skipped tasks if any
+S_WAVE_3     — Execute Wave 3 (Implementation)                    PERSIST: findings in master CSV
+S_EVAL_W4    — Evaluate Wave 4 participation                      PERSIST: skipped tasks if any
+S_WAVE_4     — Execute Wave 4 (Validation/Testing)                PERSIST: findings in master CSV
+S_AGGREGATE  — Generate report, export results                    PERSIST: context.md, results.csv
+</states>
+
+<transitions>
+S_PARSE → S_ANALYZE       WHEN: new session
+S_PARSE → S_EVAL_W{N}     WHEN: --continue (resume at first pending wave)
+S_ANALYZE → S_CSV_GEN
+S_CSV_GEN → S_EVAL_W1
+
+S_EVAL_W{N} → S_WAVE_{N}      WHEN: tasks qualify after evaluation
+S_EVAL_W{N} → S_EVAL_W{N+1}   WHEN: all tasks skipped or no tasks in wave
+S_WAVE_{N} → S_EVAL_W{N+1}    WHEN: wave complete, N < 4
+
+S_EVAL_W4 → S_AGGREGATE       WHEN: after Wave 4 eval (regardless of skip)
+S_WAVE_4 → S_AGGREGATE        WHEN: Wave 4 complete
+</transitions>
+
+<actions>
+
+### Session Initialization (S_PARSE)
+
+```
+Parse from $ARGUMENTS:
+  AUTO_YES        ← --yes | -y
+  continueMode    ← --continue
+  maxConcurrency  ← --concurrency | -c N  (default: 5)
+  taskDescription ← remaining text after flag removal
+
+Derive:
+  dateStr        ← UTC+8 YYYYMMDD
+  slug           ← first 3 meaningful words, kebab-case
+  sessionId      ← "{dateStr}-team-{slug}"
+  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"
+
+mkdir -p {sessionFolder}
+```
+
+### Session Resume (S_PARSE → S_EVAL_W{N})
+
+When `--continue`:
+1. Scan `.workflow/.csv-wave/*-team-*/tasks.csv` for sessions with pending tasks
+2. Single match → resume. Multiple → `request_user_input` for selection.
+3. Read master tasks.csv → find first wave with pending tasks → jump to S_EVAL_W{N}
+
+### Phase 1: Task Analysis + CSV Generation (S_ANALYZE → S_CSV_GEN)
+
+**TEXT-LEVEL analysis only. No codebase reading.**
+
+1. **Parse task description**
+
+2. **Clarify if ambiguous** (skip if `-y`):
+   - Scope? (specific files, module, project-wide)
+   - Deliverables? (documents, code, reports)
+   - Constraints? (technology, style)
+
+3. **Signal detection** — scan keywords against `specs/role-catalog.md` §1 Signal Detection Table:
+   - Match keywords → capabilities → roles
+   - No match → single `general` role
+
+4. **Role minimization**:
+   - Merge overlapping capabilities (e.g., "research + analysis" → single analyst)
+   - Cap at 5 roles
+   - Compute complexity score (§9 of role-catalog.md)
+
+5. **Task decomposition** — for each role, create 1-3 tasks:
+   - Generate structured `description` with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS
+   - This description IS the role instruction — no separate role-spec file
+   - Infer key files from keywords (§8 of role-catalog.md)
+
+6. **Wave assignment** — map roles to waves via §2 Wave Tier Mapping
+
+7. **Evaluation criteria** — assign per task:
+   - Wave 1: `"always"`
+   - Wave 2+: conditional from §3 Evaluation Criteria Templates
+
+8. **Dependency + context_from** — tasks in wave N depend on relevant tasks in wave N-1
+
+9. **Write `tasks.csv`** with all rows (Input columns only, no status/findings)
+
+10. **Write empty `discoveries.ndjson`**
+
+11. **User validation** (skip if `-y`):
+    - Display: role count, task count per wave, evaluation criteria summary
+    - `request_user_input`: Proceed / Revise / Abort
+
+### Phase 2: Wave Execution Engine (S_EVAL_W{N} → S_WAVE_{N})
+
+For each wave N in ascending order (1 through 4):
+
+#### Step 1: Evaluate (S_EVAL_W{N})
+
+For each task in wave N with status=pending:
+1. **Cascading check first**: if any task in `deps` OR `context_from` is failed/blocked/skipped → skip this task too
+2. Read `evaluation_criteria` from master tasks.csv
+3. If `"always"` → include
+4. If conditional → read accumulated `findings` + `files_modified` from completed tasks in master CSV:
+   - Evaluate condition as a natural language check against accumulated context
+   - The coordinator interprets conditions semantically (e.g., "if wave_1 findings indicate design needed" → check if Wave 1 findings mention design/architecture keywords)
+   - Condition met → include
+   - Not met → set `status=skipped`, `error="evaluation: {criteria} not met"`
+
+If no tasks qualify → skip to S_EVAL_W{N+1}. If ALL wave 1 tasks fail → abort pipeline, jump to S_AGGREGATE.
+
+#### Step 2: Build prev_context
+
+For each qualifying task:
+- Read `context_from` task IDs
+- Extract their `findings` from master CSV
+- Concatenate as `prev_context` string
+
+#### Step 3: Write wave-{N}.csv
+
+Extract qualifying rows from master CSV. Add `prev_context` column.
+
+#### Step 4: Execute (S_WAVE_{N})
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-${N}.csv`,
+  id_column: "id",
+  instruction: /* see Instruction Builder section below */,
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
+  output_schema: {
+    id,              // mandatory: links to master CSV
+    result_status,   // mandatory: completed | failed | blocked
+    findings,        // key findings (max 500 chars)
+    files_modified,  // semicolon-separated paths
+    error            // error message if not completed
+  }
+})
+```
+
+#### Step 5: Merge results
+
+1. Read `wave-{N}-results.csv`
+2. For each row: map `result_status` → master `status`, copy `findings`, `files_modified`, `error`
+3. Update master `tasks.csv`
+
+#### Step 6: Cascading skip
+
+For each failed/blocked task in this wave:
+- Find all downstream tasks (any task with this task in `deps`)
+- Set their `status=skipped`, `error="upstream {id} failed"`
+
+#### Step 7: Cleanup
+
+Delete `wave-{N}.csv` AND `wave-{N}-results.csv`.
+
+#### Step 8: Continue
+
+Proceed to S_EVAL_W{N+1} (or S_AGGREGATE if N=4).
+
+### Phase 3: Results Aggregation (S_AGGREGATE)
+
+1. **Export results.csv** — copy master tasks.csv as final results
+
+2. **Generate context.md**:
+```markdown
+# Team Coordinate Report: {taskDescription}
+
+## Summary
+- Roles: {role list with prefixes}
+- Tasks: {completed}/{total} ({percent}%)
+- Waves executed: {list of non-skipped waves}
+
+## Wave Results
+### Wave {N}: {stage name}
+| Task | Role | Status | Findings |
+|------|------|--------|----------|
+| {id} | {role} | {status} | {findings} |
+
+## Files Modified
+{aggregated files_modified across all tasks}
+
+## Discovery Board Summary
+{key entries from discoveries.ndjson}
+
+## Next Steps
+{suggestions based on findings}
+```
+
+3. **Display completion report** with session path and deliverable locations
+
+### Instruction Builder
+
+The `instruction` parameter for `spawn_agents_on_csv` — shared behavioral contract:
+
+```
+You are a team-coordinate agent. Your role is specified in your CSV row's 'role' column.
+
+## Your Task
+Read your CSV row's 'description' column for full task instructions (PURPOSE, TASK, CONTEXT, EXPECTED, CONSTRAINTS).
+
+## Context
+- Session: {sessionFolder}
+- Discovery board: {sessionFolder}/discoveries.ndjson (read before work, append findings)
+- Previous wave context: read your CSV row's 'prev_context' column
+
+## Role Behavior
+Adopt the perspective and expertise matching your role:
+- researcher: systematic investigation, evidence-based findings, hypothesis testing
+- developer: implementation, code modification, testing, convergence verification
+- analyst: multi-dimensional evaluation, scoring, gap identification
+- designer: architecture, data models, interface design, component structure
+- tester: validation, test creation, regression checking, security scanning
+- planner: decomposition, sequencing, risk assessment, prioritization
+- writer: documentation, content creation, clarity, consistency
+- general: adapt to task requirements
+
+## Quality Contract
+1. Files claimed as created → verify they exist (Read)
+2. Files claimed as modified → verify content changed (Read)
+3. Verification fails → retry execution (max 2 retries)
+4. Still fails → report result_status=blocked with error details
+5. NEVER report completed without verification
+
+## Discovery Board Protocol
+Read {sessionFolder}/discoveries.ndjson before starting work.
+Append findings as NDJSON lines:
+{"ts":"<ISO>","worker":"<TASK-ID>","type":"<TYPE>","data":{...}}
+Types: code_pattern, integration_point, convention, blocker, key_finding, decision
+
+## Output
+Return via output_schema:
+- result_status: completed | failed | blocked
+- findings: key findings summary (max 500 chars, be specific and actionable)
+- files_modified: semicolon-separated paths of created/modified files
+- error: error message if result_status is not completed
+```
+
+</actions>
+</state_machine>
+
+<discovery_board>
+
+| Type | Dedup Key | Data |
+|------|-----------|------|
+| code_pattern | pattern_name | {name, location, description, usage} |
+| integration_point | endpoint | {endpoint, consumers[], producers[], protocol} |
+| convention | name | {name, description, examples[], scope} |
+| blocker | issue | {issue, severity, affected_tasks[], workaround} |
+| key_finding | topic | {topic, evidence, implications, confidence} |
+| decision | subject | {subject, choice, rationale, alternatives[]} |
+
+Protocol: read before work, append-only, dedup by type+key.
+</discovery_board>
+
+<error_codes>
+
+| Condition | Recovery |
+|-----------|----------|
+| No capabilities detected | Default to single `general` role in wave 1 |
+| All wave 1 tasks failed | Abort pipeline (downstream has no context) |
+| All tasks in wave N failed | Skip subsequent waves, proceed to aggregation |
+| Evaluation skipped all tasks in wave | Normal — skip wave, continue to next |
+| Task timeout | Mark failed, cascade skip dependents |
+| Session not found (--continue) | Error with available session list |
+| tasks.csv corrupted | Error, suggest manual recovery or new session |
+| Role count exceeds 5 | Auto-merge overlapping roles |
+</error_codes>
+
+<success_criteria>
+- [ ] Dynamic roles generated from task description keywords
+- [ ] tasks.csv created with role instructions in description column
+- [ ] Wave 1 executed with at least 1 task
+- [ ] Wave 2-4 evaluation gates applied (tasks included, skipped, or wave skipped)
+- [ ] prev_context built from upstream findings for each wave
+- [ ] Column separation rule maintained (no shared names between input and output)
+- [ ] wave-N.csv and wave-N-results.csv deleted after merge
+- [ ] discoveries.ndjson append-only throughout
+- [ ] results.csv and context.md generated in Phase 3
+- [ ] Session resumable via --continue
+</success_criteria>