maestro-flow 0.3.14 → 0.3.16

package/.codex/skills/team-lifecycle-v4/SKILL.md

@@ -87,134 +87,39 @@ Before calling ANY tool, apply this check:
 
 ### Worker Spawn Template
 
-Coordinator spawns workers using this template:
-
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  message: `## Role Assignment
-role: <role>
-role_spec: <skill_root>/roles/<role>/role.md
-session: <session-folder>
-session_id: <session-id>
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).
-
-## Task Context
-task_id: <task-id>
-title: <task-title>
-description: <task-description>
-pipeline_phase: <pipeline-phase>
-
-## Upstream Context
-<prev_context>`
-})
-```
+Spawn via `team-worker` agent. Message includes: role, role_spec path (`<skill_root>/roles/<role>/role.md`), session folder/id, requirement, inner_loop flag, task context (id, title, description, pipeline_phase), upstream context. Worker executes: Phase 1 (discovery) -> role Phase 2-4 -> Phase 5 (report).
 
 ### Supervisor Spawn Template
 
-Supervisor is a **resident agent** (independent from team_worker). Spawned once during session init, woken via followup_task for each CHECKPOINT task.
-
-#### Spawn (Phase 2 -- once per session)
-
-```
-supervisorId = spawn_agent({
-  agent_type: "team_supervisor",
-  task_name: "supervisor",
-  fork_turns: "none",
-  message: `## Role Assignment
-role: supervisor
-role_spec: <skill_root>/roles/supervisor/role.md
-session: <session-folder>
-session_id: <session-id>
-requirement: <task-description>
-
-Read role_spec file (<skill_root>/roles/supervisor/role.md) to load checkpoint definitions.
-Init: load baseline context, report ready, go idle.
-Wake cycle: orchestrator sends checkpoint requests via followup_task.`
-})
-```
+Supervisor is a **resident agent** (`team_supervisor`), independent from team_worker.
 
-#### Wake (per CHECKPOINT task)
-
-```
-followup_task({
-  target: "supervisor",
-  message: `## Checkpoint Request
-task_id: <CHECKPOINT-NNN>
-scope: [<upstream-task-ids>]
-pipeline_progress: <done>/<total> tasks completed`
-})
-wait_agent({ timeout_ms: 1800000 })  // 30 min
-```
-
-#### Shutdown (pipeline complete)
-
-```
-close_agent({ target: "supervisor" })
-```
+- **Spawn** (Phase 2, once): Load role-spec from `roles/supervisor/role.md`, init baseline context, go idle
+- **Wake** (per CHECKPOINT): `followup_task` with checkpoint task_id, upstream scope, progress. `wait_agent` (30 min)
+- **Shutdown**: `close_agent({ target: "supervisor" })` at pipeline end
 
 ### Model Selection Guide
 
-| Role | model | reasoning_effort | Rationale |
-|------|-------|-------------------|-----------|
-| Analyst (RESEARCH-*) | (default) | medium | Read-heavy exploration, less reasoning needed |
-| Writer (DRAFT-*) | (default) | high | Spec writing requires precision and completeness |
-| Planner (PLAN-*) | (default) | high | Architecture decisions need full reasoning |
-| Executor (IMPL-*) | (default) | high | Code generation needs precision |
-| Tester (TEST-*) | (default) | high | Test generation requires deep code understanding |
-| Reviewer (REVIEW-*, QUALITY-*, IMPROVE-*) | (default) | high | Deep analysis for quality assessment |
-| Supervisor (CHECKPOINT-*) | (default) | medium | Gate checking, report aggregation |
-
-Override model/reasoning_effort in spawn_agent when cost optimization is needed:
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  model: "<model-override>",
-  reasoning_effort: "<effort-level>",
-  message: "..."
-})
-```
-
-### v4 Agent Coordination
-
-#### Message Semantics
-
-| Intent | API | Example |
-|--------|-----|---------|
-| Queue supplementary info (don't interrupt) | `send_message` | Send planning results to running implementers |
-| Wake resident supervisor for checkpoint | `followup_task` | Trigger CHECKPOINT-* evaluation on supervisor |
-| Supervisor reports back to coordinator | `send_message` | Supervisor sends checkpoint verdict as supplementary info |
-| Check running agents | `list_agents` | Verify agent + supervisor health during resume |
+| Role | reasoning_effort |
+|------|-------------------|
+| Analyst (RESEARCH-*) | medium |
+| Writer (DRAFT-*) | high |
+| Planner (PLAN-*) | high |
+| Executor (IMPL-*) | high |
+| Tester (TEST-*) | high |
+| Reviewer (REVIEW-*, QUALITY-*, IMPROVE-*) | high |
+| Supervisor (CHECKPOINT-*) | medium |
 
-**CRITICAL**: The supervisor is a **resident agent** woken via `followup_task`, NOT `send_message`. Regular workers complete and are closed; the supervisor persists across checkpoints. See "Supervisor Spawn Template" above.
+Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
 
-#### Agent Health Check
+### v4 Agent Coordination
 
-Use `list_agents({})` in handleResume and handleComplete:
+**Message Semantics**: `send_message` for supplementary info to workers. `followup_task` to wake supervisor for checkpoints. `list_agents` for health checks.
 
-```
-// Reconcile session state with actual running agents
-const running = list_agents({})
-// Compare with tasks.json active_agents
-// Reset orphaned tasks (in_progress but agent gone) to pending
-// ALSO check supervisor: if supervisor missing but CHECKPOINT tasks pending -> respawn
-```
+**CRITICAL**: Supervisor is a **resident agent** woken via `followup_task`, NOT `send_message`. Regular workers are one-shot; supervisor persists across checkpoints.
 
-#### Named Agent Targeting
+**Agent Health Check**: Reconcile `tasks.json.active_agents` with `list_agents({})`. Reset orphaned tasks to pending. If supervisor missing but CHECKPOINT tasks pending, respawn.
 
-Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "IMPL-001", message: "..." })` -- queue planning context to running implementer
-- `followup_task({ target: "supervisor", message: "..." })` -- wake supervisor for checkpoint
-- `close_agent({ target: "IMPL-001" })` -- cleanup regular worker by name
-- `close_agent({ target: "supervisor" })` -- shutdown supervisor at pipeline end
+**Named Targeting**: `send_message({ target: "IMPL-001" })`, `followup_task({ target: "supervisor" })`, `close_agent({ target: ... })`.
 
 ### User Commands
 
@@ -229,22 +134,7 @@ Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
 
 ### Completion Action
 
-When pipeline completes, coordinator presents:
-
-```
-request_user_input({
-  questions: [{
-    question: "Pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up resources" },
-      { label: "Keep Active", description: "Keep session for follow-up work" },
-      { label: "Export Results", description: "Export deliverables to target directory" }
-    ]
-  }]
-})
-```
+Present choice via `request_user_input`: **Archive & Clean** (recommended), **Keep Active**, **Export Results**.
 
 ### Specs Reference
 
@@ -271,18 +161,7 @@ request_user_input({
 
 ### Wave Execution Engine
 
-For each wave in the pipeline:
-
-1. **Load state** -- Read `<session>/tasks.json`, filter tasks for current wave
-2. **Skip failed deps** -- Mark tasks whose dependencies failed/skipped as `skipped`
-3. **Build upstream context** -- For each task, gather findings from `context_from` tasks via tasks.json and `discoveries/{id}.json`
-4. **Separate task types** -- Split into regular tasks and CHECKPOINT tasks
-5. **Spawn regular tasks** -- For each regular task, call `spawn_agent({ agent_type: "team_worker", message: "..." })`, collect agent IDs
-6. **Wait** -- `wait_agent({ timeout_ms: 1800000 })` (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents.
-7. **Collect results** -- Read `discoveries/{task_id}.json` for each agent, update tasks.json status/findings/error, then `close_agent({ target })` each worker
-8. **Execute checkpoints** -- For each CHECKPOINT task, `followup_task` to supervisor, `wait_agent`, read checkpoint report from `artifacts/`, parse verdict
-9. **Handle block** -- If verdict is `block`, prompt user via `request_user_input` with options: Override / Revise upstream / Abort
-10. **Persist** -- Write updated state to `<session>/tasks.json`
+Per wave: load state from `tasks.json` -> skip tasks with failed deps -> build upstream context from `discoveries/{id}.json` -> separate regular vs CHECKPOINT tasks -> spawn regular workers (`wait_agent` 30 min, timeout: STATUS_CHECK 3 min -> FINALIZE 3 min -> close) -> collect results to `discoveries/`, update `tasks.json` -> execute checkpoints via `followup_task` to supervisor -> handle `block` verdict (prompt: Override/Revise/Abort) -> persist state.
 </execution>
 
 <error_codes>

package/.codex/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md

@@ -21,75 +21,30 @@ Synchronous pipeline coordination using spawn_agent + wait_agent.
 
 Read-only status report from tasks.json + team_msg progress, then STOP.
 
-1. Read tasks.json
-2. Count tasks by status (pending, in_progress, completed, failed, skipped)
-3. Read worker progress from message bus:
-   ```javascript
-   const progressMsgs = mcp__maestro-tools__team_msg({
-     operation: "list",
-     session_id: sessionId,
-     type: "progress",
-     last: 50
-   })
-   const blockerMsgs = mcp__maestro-tools__team_msg({
-     operation: "list",
-     session_id: sessionId,
-     type: "blocker",
-     last: 10
-   })
-   // Aggregate latest milestone per task
-   const taskProgress = {}
-   for (const msg of progressMsgs.result.messages) {
-     const tid = msg.data?.task_id
-     if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
-       taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts, summary: msg.summary }
-     }
-   }
-   ```
-
-4. Output enhanced status:
+Read tasks.json + team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Aggregate latest milestone per task.
 
+**Output format**:
 ```
-[coordinator] Pipeline Status
-[coordinator] Progress: <done>/<total> (<pct>%)
-[coordinator]
-[coordinator] Active Workers:
-[coordinator]   <task_id>  <role>  <milestone_phase>  <pct>%  "<summary>"  <time_ago>
-[coordinator]   ...
-[coordinator]
-[coordinator] Blockers: <count> (or "none")
-[coordinator]   <task_id>: <blocker_detail>    ← only if blockers exist
-[coordinator]
+[coordinator] Pipeline Status — Progress: <done>/<total> (<pct>%)
+[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
+[coordinator] Blockers: <count or "none"> (detail per blocker if any)
 [coordinator] Completed: <list>
 [coordinator] Ready: <pending with resolved deps>
 [coordinator] Commands: 'resume' to advance | 'check' to refresh
 ```
 
-**CLI equivalent for human monitoring** (no coordinator needed):
-```bash
-maestro agent-msg list -s "<session_id>" --type progress --last 10
-maestro agent-msg list -s "<session_id>" --type blocker
-```
+**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
 
 ## handleResume
 
-**Agent Health Check** (v4):
+**Agent Health Check** (v4): Cross-check `list_agents()` against `active_agents`. Missing agents -> reset task to pending. Crashed supervisor (resident + no CHECKPOINT in_progress + pending CHECKPOINT exists) -> respawn with recovery: true.
+
 ```
-// Verify actual running agents match session state
-const runningAgents = list_agents({})
-// For each active_agent in tasks.json:
-//   - If agent NOT in runningAgents -> agent crashed
-//   - Reset that task to pending, remove from active_agents
-// This prevents stale agent references from blocking the pipeline
+Load active_agents -> route:
+  none -> handleSpawnNext
+  has agents -> health check, process completions -> handleSpawnNext
 ```
 
-1. Read tasks.json, check active_agents
-2. No active agents -> handleSpawnNext
-3. Has active agents -> check each:
-   - If supervisor with `resident: true` + no CHECKPOINT in_progress + pending CHECKPOINT exists
-     -> supervisor may have crashed. Respawn via spawn_agent({ agent_type: "team_supervisor" }) with recovery: true
-4. Proceed to handleSpawnNext
-
 ## handleSpawnNext
 
 Find ready tasks, spawn workers, wait for completion, process results.
@@ -104,195 +59,48 @@ Find ready tasks, spawn workers, wait for completion, process results.
 
 For each ready non-CHECKPOINT task:
 
-```javascript
-// 1) Update status in tasks.json
-state.tasks[task.id].status = 'in_progress'
-
-// 2) Spawn worker
-const agentId = spawn_agent({
-  agent_type: "team_worker",
-  task_name: task.id,  // e.g., "PLAN-001" — enables named targeting
-  message: `## Role Assignment
-role: ${task.role}
-role_spec: ${skillRoot}/roles/${task.role}/role.md
-session: ${sessionFolder}
-session_id: ${sessionId}
-requirement: ${requirement}
-inner_loop: ${hasInnerLoop(task.role)}
-
-Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
-Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).
-
+**Spawn worker message template**:
+```
+## Role Assignment
+role: <role> | role_spec: <skillRoot>/roles/<role>/role.md
+session: <session-folder> | session_id: <session-id>
+requirement: <requirement> | inner_loop: <true|false>
+Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
 ## Task Context
-task_id: ${task.id}
-title: ${task.title}
-description: ${task.description}
-pipeline_phase: ${task.pipeline_phase}
-
+task_id: <id> | title: <title> | description: <description> | pipeline_phase: <phase>
 ## Upstream Context
-${prevContext}
-
+<prevContext>
 ## Progress Milestones
-session_id: ${sessionId}
-Report progress via team_msg at natural phase boundaries (context loaded → core work done → verification).
-Report blockers immediately via team_msg type="blocker".
-Report completion via team_msg type="task_complete" after report_agent_job_result.
-See agent-instruction.md "Progress Milestone Protocol" for format.`
-})
-
-// 3) Track agent
-state.active_agents[task.id] = { agentId, role: task.role, started_at: now }
+Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
 ```
 
-After spawning all ready regular tasks:
-
-```javascript
-// 4) Batch wait — use task_name for stable targeting (v4)
-const taskNames = Object.entries(state.active_agents)
-  .filter(([_, a]) => !a.resident)
-  .map(([taskId]) => taskId)
-const waitResult = wait_agent({ timeout_ms: 1800000 })  // 30 min
-// 4a) Drain progress from message bus (before collecting discoveries)
-const progressMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "progress", last: 100
-})
-const blockerMsgs = mcp__maestro-tools__team_msg({
-  operation: "list", session_id: sessionId, type: "blocker", last: 20
-})
-// Log execution trace
-for (const msg of (progressMsgs.result?.messages || [])) {
-  console.log(`[coordinator] trace: ${msg.summary}`)
-}
-if (blockerMsgs.result?.messages?.length > 0) {
-  console.log(`[coordinator] WARNING: ${blockerMsgs.result.messages.length} blocker(s) reported during execution`)
-  for (const b of blockerMsgs.result.messages) {
-    console.log(`[coordinator]   ${b.data?.task_id}: ${b.data?.blocker_detail}`)
-  }
-}
-
-if (waitResult.timed_out) {
-  // Use progress trace to understand where workers got stuck
-  for (const taskId of taskNames) {
-    // Status probe before closing
-    followup_task({ target: taskId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
-    const status = wait_agent({ timeout_ms: 180000 })  // 3 min
-    if (status.timed_out) {
-      followup_task({ target: taskId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
-      const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
-      if (forced.timed_out) {
-        const lastProgress = (progressMsgs.result?.messages || [])
-          .filter(m => m.data?.task_id === taskId)
-          .pop()
-        state.tasks[taskId].status = 'timed_out'
-        state.tasks[taskId].error = lastProgress
-          ? `Timed out at ${lastProgress.data.phase} (${lastProgress.data.progress_pct}%)`
-          : 'Timed out with no progress reported'
-        close_agent({ target: taskId })
-        delete state.active_agents[taskId]
-      }
-      // else: forced output received, process result
-    }
-    // else: status received, continue processing
-  }
-} else {
-  // 5) Collect results from discoveries/{task_id}.json
-  for (const [taskId, agent] of Object.entries(state.active_agents)) {
-    if (agent.resident) continue
-    try {
-      const disc = JSON.parse(Read(`${sessionFolder}/discoveries/${taskId}.json`))
-      state.tasks[taskId].status = disc.status || 'completed'
-      state.tasks[taskId].findings = disc.findings || ''
-      state.tasks[taskId].quality_score = disc.quality_score || null
-      state.tasks[taskId].error = disc.error || null
-    } catch {
-      state.tasks[taskId].status = 'failed'
-      state.tasks[taskId].error = 'No discovery file produced'
-    }
-    close_agent({ target: taskId })  // Use task_name, not agentId
-    delete state.active_agents[taskId]
-  }
-}
-```
-
-**Cross-Agent Supplementary Context** (v4):
+**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress + blockers from team_msg, log execution trace.
 
-When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent. Normal completion -> read `discoveries/{task_id}.json` for status/findings/quality_score/error. Missing file -> status="failed". Close each agent (use task_name, not agentId).
 
-```
-// Example: Send planning results to running implementers
-send_message({
-  target: "<running-agent-task-name>",
-  message: `## Supplementary Context\n${upstreamFindings}`
-})
-// Note: send_message queues info without interrupting the agent's current work
-```
-
-Use `send_message` (not `followup_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
 
 ### Handle CHECKPOINT Tasks
 
 For each ready CHECKPOINT task:
 
-1. Verify supervisor is in active_agents with `resident: true`
-   - Not found -> spawn supervisor via SKILL.md Supervisor Spawn Template, record supervisorId
-2. Determine scope: list task IDs that this checkpoint depends on (its deps)
-3. Wake supervisor:
-   ```javascript
-   followup_task({
-     target: supervisorId,
-     message: `## Checkpoint Request
-   task_id: ${task.id}
-   scope: [${task.deps.join(', ')}]
-   pipeline_progress: ${completedCount}/${totalCount} tasks completed`
-   })
-   const cpResult = wait_agent({ timeout_ms: 1800000 })  // 30 min
-   if (cpResult.timed_out) {
-     followup_task({ target: supervisorId, message: "STATUS_CHECK: Report current progress, findings so far, and estimated remaining work." })
-     const status = wait_agent({ timeout_ms: 180000 })  // 3 min
-     if (status.timed_out) {
-       followup_task({ target: supervisorId, message: "FINALIZE: Output all current findings immediately. Time limit reached.", interrupt: true })
-       const forced = wait_agent({ timeout_ms: 180000 })  // 3 min
-       if (forced.timed_out) { /* mark checkpoint timed_out, close supervisor, STOP */ }
-     }
-   }
-   ```
-4. Read checkpoint report from artifacts/${task.id}-report.md
-5. Parse verdict (pass / warn / block):
+1. Ensure supervisor in active_agents (resident: true). Not found -> spawn via SKILL.md Supervisor Spawn Template.
+2. Wake supervisor via `followup_task` with checkpoint scope (dep task IDs) + pipeline progress.
+3. `wait_agent` (30 min) with standard timeout escalation (STATUS_CHECK -> FINALIZE -> timed_out).
+4. Read `artifacts/${task.id}-report.md`, parse verdict:
    - **pass** -> mark completed, proceed
    - **warn** -> log risks to wisdom, mark completed, proceed
    - **block** -> request_user_input: Override / Revise upstream / Abort
 
 ### Persist and Loop
 
-After processing all results:
-1. Write updated tasks.json
-2. Check if more tasks are now ready (deps newly resolved)
-3. If yes -> loop back to step 1 of handleSpawnNext
-4. If no more ready and all done -> handleComplete
-5. If no more ready but some still blocked -> report status, STOP
+Write tasks.json -> more tasks ready? -> loop handleSpawnNext. All done -> handleComplete. Blocked -> report, STOP.
 
 ## handleComplete
 
-**Cleanup Verification** (v4):
-```
-// Verify all agents are properly closed
-const remaining = list_agents({})
-// If any team agents still running -> close_agent each
-// Ensures clean session shutdown
-```
+**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents (including resident supervisor).
 
-Pipeline done. Generate report and completion action.
-
-1. Shutdown resident supervisor (if active):
-   ```javascript
-   close_agent({ target: supervisorId })
-   ```
-   Remove from active_agents in tasks.json
-2. Generate summary (deliverables, stats, discussions)
-3. Read tasks.json completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean (rm -rf session folder)
-   - auto_keep -> Keep Active (update status to "paused")
+Pipeline done. Generate summary (deliverables, stats, discussions). Route by completion_action: interactive (Archive/Keep/Export) | auto_archive | auto_keep.
 
 ## handleAdapt
 

package/.codex/skills/team-quality-assurance/SKILL.md

@@ -79,57 +79,19 @@ Before calling ANY tool, apply this check:
 
 ### Worker Spawn Template
 
-Coordinator spawns workers using this template:
-
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  message: `## Role Assignment
-role: <role>
-role_spec: <skill_root>/roles/<role>/role.md
-session: <session-folder>
-session_id: <session-id>
-requirement: <task-description>
-inner_loop: <true|false>
-
-Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
-
-## Task Context
-task_id: <task-id>
-title: <task-title>
-description: <task-description>
-pipeline_phase: <pipeline-phase>
-
-## Upstream Context
-<prev_context>`
-})
-```
-
-After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target })` each worker.
+Spawn via `team-worker` agent. Message includes: role, role_spec path, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> close.
 
 ### Model Selection Guide
 
-| Role | model | reasoning_effort | Rationale |
-|------|-------|-------------------|-----------|
-| Scout (SCOUT-*) | (default) | medium | Issue discovery scanning, less reasoning needed |
-| Strategist (QASTRAT-*) | (default) | high | Test strategy design requires deep analysis |
-| Generator (QAGEN-*) | (default) | high | Test code generation needs precision |
-| Executor (QARUN-*) | (default) | medium | Running tests and collecting results |
-| Analyst (QAANA-*) | (default) | high | Quality analysis and coverage assessment |
+| Role | reasoning_effort |
+|------|-------------------|
+| Scout (SCOUT-*) | medium |
+| Strategist (QASTRAT-*) | high |
+| Generator (QAGEN-*) | high |
+| Executor (QARUN-*) | medium |
+| Analyst (QAANA-*) | high |
 
-Override model/reasoning_effort in spawn_agent when cost optimization is needed:
-```
-spawn_agent({
-  agent_type: "team_worker",
-  task_name: "<task-id>",
-  fork_turns: "none",
-  model: "<model-override>",
-  reasoning_effort: "<effort-level>",
-  message: "..."
-})
-```
+Override via `model`/`reasoning_effort` params in spawn_agent for cost optimization.
 
 ### User Commands
 
@@ -143,53 +105,17 @@ spawn_agent({
 
 ### v4 Agent Coordination
 
-#### Message Semantics
-
-| Intent | API | Example |
-|--------|-----|---------|
-| Send scout findings to running strategist | `send_message` | Queue issue scan results to QASTRAT-* |
-| Not used in this skill | `followup_task` | No resident agents -- all workers are one-shot |
-| Check running agents | `list_agents` | Verify agent health during resume |
-
-#### Pipeline Pattern
+**Message Semantics**: `send_message` to queue scout findings to strategist. `list_agents` for health checks. `followup_task` not used (all one-shot workers).
 
-Sequential pipeline with GC loops: scout -> strategist -> generator -> executor -> analyst. The executor/generator may loop via GC fix tasks when coverage is below target (max 3 rounds).
+**Pipeline Pattern**: Sequential with GC loops: scout -> strategist -> generator -> executor -> analyst. Generator/executor may loop (max 3 rounds) when coverage below target.
 
-#### Agent Health Check
+**Agent Health Check**: Reconcile `tasks.json` with `list_agents({})`. Reset orphaned tasks to pending.
 
-Use `list_agents({})` in handleResume and handleComplete:
-
-```
-// Reconcile session state with actual running agents
-const running = list_agents({})
-// Compare with tasks.json active_agents
-// Reset orphaned tasks (in_progress but agent gone) to pending
-```
-
-#### Named Agent Targeting
-
-Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
-- `send_message({ target: "QASTRAT-001", message: "..." })` -- queue scout findings to running strategist
-- `close_agent({ target: "SCOUT-001" })` -- cleanup by name after completion
+**Named Targeting**: `send_message({ target: "QASTRAT-001" })`, `close_agent({ target: "SCOUT-001" })`.
 
 ### Completion Action
 
-When pipeline completes, coordinator presents:
-
-```
-request_user_input({
-  questions: [{
-    question: "Quality Assurance pipeline complete. What would you like to do?",
-    header: "Completion",
-    multiSelect: false,
-    options: [
-      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up" },
-      { label: "Keep Active", description: "Keep session for follow-up work" },
-      { label: "Export Results", description: "Export deliverables to target directory" }
-    ]
-  }]
-})
-```
+Present choice: **Archive & Clean** (recommended), **Keep Active**, **Export Results**.
 
 ### Session Directory