claude-code-workflow 7.2.27 → 7.2.28

package/.codex/skills/team-interactive-craft/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,162 @@
+# Command: Dispatch
+
+Create the interactive craft task chain with correct dependencies and structured task descriptions. Supports single, gallery, and page pipeline modes.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| User requirement | From coordinator Phase 1 | Yes |
+| Session folder | From coordinator Phase 2 | Yes |
+| Pipeline mode | From tasks.json `pipeline_mode` | Yes |
+| Interaction type | From tasks.json `interaction_type` | Yes |
+
+1. Load user requirement and scope from tasks.json
+2. Load pipeline stage definitions from specs/pipelines.md
+3. Read `pipeline_mode` and `interaction_type` from tasks.json
+
+## Phase 3: Task Chain Creation (Mode-Branched)
+
+### Task Entry Template
+
+Each task in tasks.json `tasks` object:
+```json
+{
+  "<TASK-ID>": {
+    "title": "<concise title>",
+    "description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n  - <step 1: specific action>\n  - <step 2: specific action>\n  - <step 3: specific action>\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <interaction-scope>\n  - Components: <component-list>\n  - Upstream artifacts: <artifact-1>, <artifact-2>\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>",
+    "role": "<role-name>",
+    "prefix": "<PREFIX>",
+    "deps": ["<dependency-list>"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+### Mode Router
+
+| Mode | Action |
+|------|--------|
+| `single` | Create 4 tasks: RESEARCH -> INTERACT -> BUILD -> A11Y |
+| `gallery` | Create 6 tasks: RESEARCH -> INTERACT-001 -> BUILD-001 -> INTERACT-002 -> BUILD-002 -> A11Y |
+| `page` | Create 4+ tasks: RESEARCH -> INTERACT -> [BUILD-001..N parallel] -> A11Y |
+
+---
+
+### Single Pipeline Task Chain
+
+**RESEARCH-001** (researcher):
+```json
+{
+  "RESEARCH-001": {
+    "title": "Interaction pattern analysis and browser API audit",
+    "description": "PURPOSE: Analyze interaction patterns, browser API availability, and reference implementations | Success: 3 research artifacts with valid data\nTASK:\n  - Catalog existing interactive components in project\n  - Audit browser API usage (IntersectionObserver, ResizeObserver, Pointer Events, Touch Events)\n  - Collect reference patterns for target component type\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <interaction-scope>\n  - Components: <component-list>\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/research/*.json | All 3 research files with valid JSON\nCONSTRAINTS: Read-only analysis | Focus on <interaction-scope>",
+    "role": "researcher",
+    "prefix": "RESEARCH",
+    "deps": [],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**INTERACT-001** (interaction-designer):
+```json
+{
+  "INTERACT-001": {
+    "title": "Interaction blueprint with state machine and event flows",
+    "description": "PURPOSE: Design complete interaction blueprint with state machine and event flows | Success: Blueprint with all states, events, and keyboard mappings defined\nTASK:\n  - Define state machine (idle -> hover -> active -> animating -> complete)\n  - Map event flows (pointer/touch/keyboard -> handlers -> state transitions)\n  - Specify gesture parameters (lerp speed, thresholds, easing)\n  - Design animation choreography (entry/exit/idle transitions)\n  - Create touch/keyboard/mouse mapping table\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <interaction-scope>\n  - Upstream artifacts: research/*.json\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/interaction/blueprints/<component-name>.md | Complete state machine + event map + keyboard coverage\nCONSTRAINTS: Vanilla JS only | GPU-only animations | Progressive enhancement",
+    "role": "interaction-designer",
+    "prefix": "INTERACT",
+    "deps": ["RESEARCH-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**BUILD-001** (builder):
+```json
+{
+  "BUILD-001": {
+    "title": "Vanilla JS + CSS interactive component implementation",
+    "description": "PURPOSE: Implement interactive component as vanilla JS + CSS | Success: Working ES module + CSS with all states, touch-aware, keyboard accessible\nTASK:\n  - Implement ES module component class from interaction blueprint\n  - Write CSS with custom properties (no preprocessor)\n  - Add progressive enhancement (content works without JS)\n  - Use GPU-only animations (transform + opacity)\n  - Implement pointer events with touch fallback\n  - Add ResizeObserver for responsive behavior\n  - Add IntersectionObserver for scroll triggers (if applicable)\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <interaction-scope>\n  - Upstream artifacts: interaction/blueprints/*.md, research/*.json\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/build/components/<name>.js + <name>.css | Zero dependencies, all states implemented\nCONSTRAINTS: No npm packages | ES modules only | No inline styles | < 5ms per frame",
+    "role": "builder",
+    "prefix": "BUILD",
+    "deps": ["INTERACT-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**A11Y-001** (a11y-tester):
+```json
+{
+  "A11Y-001": {
+    "title": "Accessibility audit of built component",
+    "description": "PURPOSE: Audit accessibility of built component | Success: Audit report with pass/fail per check, 0 critical issues\nTASK:\n  - Test keyboard navigation (tab order, arrow keys, escape, enter/space)\n  - Check screen reader compatibility (ARIA roles, states, live regions)\n  - Verify reduced motion fallback (prefers-reduced-motion)\n  - Test focus management (visible indicator, focus trap for overlays)\n  - Check color contrast (foreground/background ratio)\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <interaction-scope>\n  - Upstream artifacts: build/components/*.js, build/components/*.css, interaction/blueprints/*.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/a11y/a11y-audit-001.md | Per-check pass/fail with remediation suggestions\nCONSTRAINTS: Read-only analysis | GC convergence: 0 critical issues",
+    "role": "a11y-tester",
+    "prefix": "A11Y",
+    "deps": ["BUILD-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+---
+
+### Gallery Pipeline Task Chain
+
+Create tasks in dependency order:
+
+| Task | Role | deps | Description |
+|------|------|------|-------------|
+| RESEARCH-001 | researcher | [] | Interaction patterns + browser API audit |
+| INTERACT-001 | interaction-designer | [RESEARCH-001] | Base component interaction blueprint |
+| BUILD-001 | builder | [INTERACT-001] | Base component implementation |
+| INTERACT-002 | interaction-designer | [BUILD-001] | Gallery/scroll-snap interaction blueprint |
+| BUILD-002 | builder | [INTERACT-002] | Gallery container + navigation implementation |
+| A11Y-001 | a11y-tester | [BUILD-002] | Full gallery accessibility audit |
+
+Task descriptions follow same template as single pipeline, with subject-specific content:
+- INTERACT-002 focuses on scroll-snap container, navigation dots, active item detection
+- BUILD-002 focuses on gallery container with CSS scroll-snap, IntersectionObserver for active item, navigation controls
+
+---
+
+### Page Pipeline Task Chain
+
+| Task | Role | deps | Description |
+|------|------|------|-------------|
+| RESEARCH-001 | researcher | [] | Interaction patterns for all page sections |
+| INTERACT-001 | interaction-designer | [RESEARCH-001] | Blueprints for all interactive sections |
+| BUILD-001..N | builder | [INTERACT-001] | One task per section (parallel fan-out) |
+| A11Y-001 | a11y-tester | [BUILD-001..N] | Full page accessibility audit |
+
+**Parallel fan-out**: Create one BUILD task per distinct interactive section detected in the interaction blueprint. Each BUILD task deps only on INTERACT-001. A11Y-001 deps on ALL BUILD tasks.
+
+Task descriptions for each BUILD-00N specify which section to implement, referencing the corresponding section in the interaction blueprint.
+
+---
+
+## Phase 4: Validation
+
+Verify task chain integrity:
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | tasks.json count | single: 4, gallery: 6, page: 3+N |
+| Dependencies correct | Trace dependency graph | Acyclic, correct deps |
+| No circular dependencies | Trace dependency graph | Acyclic |
+| Task IDs use correct prefixes | Pattern check | RESEARCH/INTERACT/BUILD/A11Y |
+| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
+
+If validation fails, fix the specific task and re-validate.

package/.codex/skills/team-interactive-craft/roles/coordinator/commands/monitor.md

@@ -0,0 +1,233 @@
+# Monitor Pipeline
+
+Synchronous pipeline coordination using spawn_agent + wait_agent.
+
+## Constants
+
+- WORKER_AGENT: team_worker
+- MAX_GC_ROUNDS: 2
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed (wait_agent returns). Process and advance.
+
+1. Determine role from completed task prefix:
+
+| Task Prefix | Role |
+|-------------|------|
+| `RESEARCH-*` | researcher |
+| `INTERACT-*` | interaction-designer |
+| `BUILD-*` | builder |
+| `A11Y-*` | a11y-tester |
+
+2. Mark task completed in tasks.json: `state.tasks[taskId].status = 'completed'`
+3. Record completion in session state
+
+4. Check checkpoint for completed task:
+
+| Completed Task | Checkpoint | Action |
+|---------------|------------|--------|
+| RESEARCH-001 | - | Notify user: research complete |
+| INTERACT-001 | - | Proceed to BUILD-001 (single/gallery) or BUILD-001..N (page parallel) |
+| INTERACT-002 | - | Proceed to BUILD-002 (gallery) |
+| BUILD-001 | - | Check mode: single -> A11Y-001; gallery -> INTERACT-002; page -> check if all BUILD done |
+| BUILD-001..N | - | Page mode: check if all BUILD tasks done -> A11Y-001 |
+| BUILD-002 | - | Gallery: proceed to A11Y-001 |
+| A11Y-001 | QUALITY: A11y Gate | Check a11y signal -> GC loop or complete |
+
+5. **A11y Gate handling** (A11Y task completed):
+   Read a11y signal from result: `a11y_passed`, `a11y_result`, or `fix_required`
+
+   | Signal | Condition | Action |
+   |--------|-----------|--------|
+   | `a11y_passed` | 0 critical issues | GC converged -> record gate -> handleComplete |
+   | `a11y_result` | Minor issues only | gc_rounds < max -> create BUILD-fix task in tasks.json |
+   | `fix_required` | Critical issues found | gc_rounds < max -> create BUILD-fix task (CRITICAL) in tasks.json |
+   | Any | gc_rounds >= max | Escalate to user |
+
+   **GC Fix Task Creation** (add to tasks.json):
+   ```json
+   {
+     "BUILD-fix-<round>": {
+       "title": "Address a11y audit feedback",
+       "description": "PURPOSE: Address a11y audit feedback | Success: All critical/high issues resolved\nTASK:\n  - Parse a11y audit feedback for specific issues\n  - Apply targeted fixes to component JS/CSS\nCONTEXT:\n  - Session: <session-folder>\n  - Upstream artifacts: a11y/a11y-audit-<NNN>.md",
+       "role": "builder",
+       "prefix": "BUILD",
+       "deps": [],
+       "status": "pending",
+       "findings": "",
+       "error": ""
+     }
+   }
+   ```
+   Then create new A11Y task in tasks.json with deps on fix. Increment gc_state.round.
+
+   **GC Escalation Options** (when max rounds exceeded):
+   1. Accept current implementation - skip remaining a11y fixes
+   2. Try one more round
+   3. Terminate
+
+6. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report from tasks.json, then STOP.
+
+```
+Pipeline Status (<pipeline-mode>):
+  [DONE]  RESEARCH-001      (researcher)            -> research/*.json
+  [DONE]  INTERACT-001      (interaction-designer)  -> blueprints/*.md
+  [RUN]   BUILD-001         (builder)               -> building component...
+  [WAIT]  A11Y-001          (a11y-tester)            -> blocked by BUILD-001
+
+GC Rounds: 0/2
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+**Agent Health Check** (v4):
+```
+// 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
+```
+
+1. Audit tasks.json for inconsistencies:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed deps but still "pending" -> include in spawn list
+2. -> handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, wait for results.
+
+1. Read tasks.json: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. Update task status to in_progress in tasks.json
+   c. team_msg log -> task_unblocked
+   d. Spawn team_worker:
+
+```javascript
+// 1) Update status in tasks.json
+state.tasks[taskId].status = 'in_progress'
+
+// 2) Spawn worker
+const agentId = spawn_agent({
+  agent_type: "team_worker",
+  task_name: taskId,  // e.g., "BUILD-001" -- enables named targeting
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${role}
+role_spec: ${skillRoot}/roles/${role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${taskDescription}
+inner_loop: ${innerLoop}` },
+
+    { type: "text", text: `Read role_spec file to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }
+  ]
+})
+
+// 3) Track agent
+state.active_agents[taskId] = { agentId, role, started_at: now }
+
+// 4) Wait for completion -- use task_name for stable targeting (v4)
+const waitResult = wait_agent({ targets: [taskId], timeout_ms: 900000 })
+if (waitResult.timed_out) {
+  state.tasks[taskId].status = 'timed_out'
+  close_agent({ target: taskId })
+  delete state.active_agents[taskId]
+} else {
+  // 5) Collect results and update tasks.json
+  state.tasks[taskId].status = 'completed'
+  close_agent({ target: taskId })  // Use task_name, not agentId
+  delete state.active_agents[taskId]
+}
+```
+
+**Parallel spawn rules by mode**:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| single | Sequential | One task at a time |
+| gallery | Sequential | One task at a time |
+| page | After INTERACT-001 | Spawn BUILD-001..N in parallel, wait_agent for all |
+| page | After all BUILD done | Spawn A11Y-001 |
+
+**Cross-Agent Supplementary Context** (v4):
+
+When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+
+```
+// Example: Send research results to running interaction-designer
+send_message({
+  target: "<running-agent-task-name>",
+  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+})
+// Note: send_message queues info without interrupting the agent's current work
+```
+
+Use `send_message` (not `assign_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+
+5. Update tasks.json, output summary, 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
+```
+
+Pipeline done. Generate report and completion action.
+
+**Completion check by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| single | All 4 tasks (+ fix tasks) completed |
+| gallery | All 6 tasks (+ fix tasks) completed |
+| page | All 3+N tasks (+ fix tasks) completed |
+
+1. If any tasks not completed -> handleSpawnNext
+2. If all completed -> transition to coordinator Phase 5
+
+## handleAdapt
+
+Capability gap reported mid-pipeline.
+
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role spec
+4. Create new task in tasks.json, spawn worker
+5. Role count >= 5 -> merge or pause
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read tasks.json for completed tasks
+2. Sync active_agents with actual state
+3. No duplicate spawns

package/.codex/skills/team-interactive-craft/roles/coordinator/role.md

@@ -0,0 +1,209 @@
+# Coordinator Role
+
+Interactive Craft Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages task chains for interactive component creation, GC loops between builder and a11y-tester, parallel fan-out for page mode.
+
+## Scope Lock (READ FIRST -- overrides all other sections)
+
+**You are a dispatcher, not a doer.** Your ONLY outputs are:
+- Session state files (`.workflow/.team/` directory)
+- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `assign_task` calls
+- Status reports to the user / `request_user_input` prompts
+
+**FORBIDDEN** (even if the task seems trivial):
+```
+WRONG: Read/Grep/Glob on project source code        -- worker work
+WRONG: Bash("ccw cli ...")                           -- worker work
+WRONG: Edit/Write on project source files            -- worker work
+```
+
+**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work -> STOP -> spawn worker."
+
+---
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (team_msg, logs) must carry `[coordinator]` identifier
+- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
+- Dispatch tasks with proper dependency chains and deps in tasks.json
+- Monitor worker progress via wait_agent and process results
+- Handle Generator-Critic loops with max 2 iterations
+- Maintain session state persistence (tasks.json)
+- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
+- Use `send_message` for supplementary context (non-interrupting) and `assign_task` for triggering new work
+- Use `list_agents` for session resume health checks and cleanup verification
+
+### MUST NOT
+- Implement domain logic (researching, designing, building, testing) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip sync points when configured
+- Force-advance pipeline past failed a11y audit
+- Modify source code or component artifacts directly -- delegate to workers
+- Omit `[coordinator]` identifier in any output
+- Call CLI tools (ccw cli) -- only workers use CLI
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (analyze, dispatch, monitor):
+
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/IC-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/IC-*/tasks.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (read tasks.json, reset in_progress->pending, kick first ready task)
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse task description from arguments
+2. Detect interactive scope:
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Single component (split compare, lightbox, lens, scroll reveal, glass terminal) | single |
+| Gallery, carousel, scroll-snap collection, multi-component scroll | gallery |
+| Full interactive page, landing page, multi-section interactive | page |
+| Unclear | ask user |
+
+3. Ask for missing parameters if scope unclear:
+   ```
+   request_user_input({
+     questions: [
+       { question: "Interactive component scope?", header: "Scope", options: [
+         { label: "Single component", description: "One interactive element (split compare, lightbox, etc.)" },
+         { label: "Gallery / Scroll collection", description: "Scroll-snap gallery or multi-component scroll" },
+         { label: "Full interactive page", description: "Complete page with multiple interactive sections" }
+       ]},
+       { question: "Primary interaction type?", header: "Interaction", options: [
+         { label: "Pointer/drag", description: "Drag, resize, slider interactions" },
+         { label: "Scroll-based", description: "Scroll snap, scroll reveal, parallax" },
+         { label: "Overlay/modal", description: "Lightbox, lens, tooltip overlays" },
+         { label: "Mixed" }
+       ]}
+     ]
+   })
+   ```
+4. Delegate to `@commands/analyze.md` -> output scope context
+5. Record: pipeline_mode, interaction_type, complexity
+
+## Phase 2: Create Session + Initialize
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.codex/skills/team-interactive-craft`
+2. Generate session ID: `IC-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+   ```
+   .workflow/.team/IC-<slug>-<date>/research/
+   .workflow/.team/IC-<slug>-<date>/interaction/blueprints/
+   .workflow/.team/IC-<slug>-<date>/build/components/
+   .workflow/.team/IC-<slug>-<date>/a11y/
+   .workflow/.team/IC-<slug>-<date>/wisdom/
+   .workflow/.team/IC-<slug>-<date>/.msg/
+   ```
+4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
+5. Write initial tasks.json:
+   ```json
+   {
+     "session_id": "<id>",
+     "pipeline_mode": "<single|gallery|page>",
+     "interaction_type": "<pointer|scroll|overlay|mixed>",
+     "created_at": "<ISO timestamp>",
+     "gc_rounds": 0,
+     "max_gc_rounds": 2,
+     "active_agents": {},
+     "tasks": {}
+   }
+   ```
+6. Do NOT spawn workers yet - deferred to Phase 4
+
+## Phase 3: Create Task Chain
+
+Delegate to `@commands/dispatch.md`. Task chains by mode:
+
+| Mode | Task Chain |
+|------|------------|
+| single | RESEARCH-001 -> INTERACT-001 -> BUILD-001 -> A11Y-001 |
+| gallery | RESEARCH-001 -> INTERACT-001 -> BUILD-001 -> INTERACT-002 -> BUILD-002 -> A11Y-001 |
+| page | RESEARCH-001 -> INTERACT-001 -> [BUILD-001..N parallel] -> A11Y-001 |
+
+## Phase 4: Spawn-and-Wait
+
+Delegate to `@commands/monitor.md#handleSpawnNext`:
+1. Find ready tasks (pending + deps resolved)
+2. Spawn team_worker agents via spawn_agent, wait_agent for results
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Completion Action
+
+1. Read session state -> collect all results
+2. List deliverables:
+
+| Deliverable | Path |
+|-------------|------|
+| Interaction Inventory | <session>/research/interaction-inventory.json |
+| Browser API Audit | <session>/research/browser-api-audit.json |
+| Pattern Reference | <session>/research/pattern-reference.json |
+| Interaction Blueprints | <session>/interaction/blueprints/*.md |
+| Component JS Files | <session>/build/components/*.js |
+| Component CSS Files | <session>/build/components/*.css |
+| A11y Audit Reports | <session>/a11y/a11y-audit-*.md |
+
+3. Calculate: completed_tasks, gc_rounds, a11y_score, components_built
+4. Output pipeline summary with [coordinator] prefix
+5. Execute completion action:
+   ```
+   request_user_input({
+     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
+       { label: "Archive & Clean", description: "Archive session and clean up resources" },
+       { label: "Keep Active", description: "Keep session for follow-up work" },
+       { label: "Export Results", description: "Export deliverables to specified location" }
+     ]}]
+   })
+   ```
+
+## v4 Coordination Patterns
+
+### Message Semantics
+- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### Agent Lifecycle Management
+- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
+- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, assign_task, and close_agent calls.
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Reset task to pending, respawn worker |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid scope | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |
+| GC loop stuck > 2 rounds | Escalate to user: accept / try one more / terminate |