claude-code-workflow 7.2.27 → 7.2.29

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

@@ -0,0 +1,216 @@
+---
+role: builder
+prefix: BUILD
+inner_loop: true
+message_types: [state_update]
+---
+
+# Interactive Component Builder
+
+Implement vanilla JS + CSS interactive components from interaction blueprints. Zero dependencies, ES modules, progressive enhancement, GPU-only animations, touch-aware. Act as Generator in the builder<->a11y-tester Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Interaction blueprints | <session>/interaction/blueprints/*.md | Yes |
+| Research artifacts | <session>/research/*.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| A11y audit feedback | <session>/a11y/a11y-audit-*.md | Only for GC fix tasks |
+
+1. Extract session path from task description
+2. Read interaction blueprint for target component
+3. Read research artifacts: browser-api-audit.json (API availability), pattern-reference.json (reference patterns)
+4. Detect task type from subject: numbered -> New component, "fix" -> GC fix
+5. If GC fix task: read latest a11y audit feedback
+
+## Phase 3: Implementation Execution
+
+**Component Implementation (BUILD-001, BUILD-002, etc.)**:
+
+### JavaScript (ES Module)
+Implement component class in `<session>/build/components/{name}.js`:
+
+```javascript
+// Structure template (adapt to component type)
+export class ComponentName {
+  // --- Configuration ---
+  static defaults = { /* configurable params from blueprint */ };
+
+  // --- Lifecycle ---
+  constructor(element, options = {}) { /* merge options, query DOM, bind events */ }
+  init() { /* setup observers, initial state */ }
+  destroy() { /* cleanup: remove listeners, disconnect observers */ }
+
+  // --- State Machine ---
+  #state = 'idle';
+  #setState(next) { /* validate transition, update, trigger side effects */ }
+
+  // --- Event Handlers (from blueprint event flow map) ---
+  #onPointerDown(e) { /* setPointerCapture, transition state */ }
+  #onPointerMove(e) { /* lerp interpolation, update transform */ }
+  #onPointerUp(e) { /* releasePointerCapture, settle animation */ }
+  #onKeyDown(e) { /* keyboard mapping from blueprint */ }
+
+  // --- Animation ---
+  #lerp(current, target, speed) { return current + (target - current) * speed; }
+  #animate() { /* requestAnimationFrame loop, GPU-only transforms */ }
+
+  // --- Observers ---
+  #resizeObserver = null;  // responsive behavior
+  #intersectionObserver = null;  // scroll triggers
+
+  // --- Accessibility ---
+  #announceToScreenReader(message) { /* aria-live region update */ }
+}
+
+// Auto-init: progressive enhancement
+document.querySelectorAll('[data-component-name]').forEach(el => {
+  new ComponentName(el);
+});
+```
+
+Requirements:
+- Pure ES module with `export` (no CommonJS, no bundler)
+- Class-based with private fields (#)
+- Constructor accepts DOM element + options object
+- State machine from blueprint with validated transitions
+- Event handlers from blueprint event flow map
+- Lerp interpolation for smooth drag/follow (speed from blueprint)
+- requestAnimationFrame for frame-synced updates
+- setPointerCapture for reliable drag tracking
+- ResizeObserver for responsive layout adjustments
+- IntersectionObserver for scroll-triggered behavior (when applicable)
+- Proper cleanup in destroy() method
+- Auto-init via data attribute for progressive enhancement
+
+### CSS (Custom Properties)
+Implement styles in `<session>/build/components/{name}.css`:
+
+```css
+/* Structure template */
+/* --- Custom Properties (configurable) --- */
+.component-name {
+  --component-duration: 400ms;
+  --component-easing: cubic-bezier(0.16, 1, 0.3, 1);
+  --component-color-primary: #1a1a2e;
+  /* ... from blueprint animation choreography */
+}
+
+/* --- Base Layout (works without JS) --- */
+.component-name { /* progressive enhancement base */ }
+
+/* --- States (from blueprint state machine) --- */
+.component-name[data-state="idle"] { }
+.component-name[data-state="hover"] { }
+.component-name[data-state="active"] { }
+.component-name[data-state="dragging"] { }
+
+/* --- Animations (GPU-only: transform + opacity) --- */
+.component-name__element {
+  transform: translateX(0);
+  opacity: 1;
+  transition: transform var(--component-duration) var(--component-easing),
+              opacity var(--component-duration) var(--component-easing);
+  will-change: transform, opacity;
+}
+
+/* --- Focus Styles --- */
+.component-name:focus-visible {
+  outline: 2px solid var(--component-focus-color, #4a9eff);
+  outline-offset: 2px;
+}
+
+/* --- Reduced Motion --- */
+@media (prefers-reduced-motion: reduce) {
+  .component-name,
+  .component-name * {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+  }
+}
+
+/* --- Responsive --- */
+@media (max-width: 768px) { /* touch-optimized sizes */ }
+```
+
+Requirements:
+- CSS custom properties for all configurable values (no preprocessor)
+- Base layout works without JavaScript (progressive enhancement)
+- State-driven via data attributes (`data-state`, `data-active`)
+- GPU-only animations: transform + opacity ONLY (no width/height/top/left)
+- `will-change` on animated elements
+- `prefers-reduced-motion` media query with instant transitions
+- `focus-visible` for keyboard-only focus ring
+- Responsive breakpoints for touch targets (min 44x44px)
+- No inline styles from JS -- use CSS classes and custom properties
+
+### Native Platform APIs (prefer over custom implementations)
+
+**Dialog API** (`<dialog>`):
+- Use `<dialog>` for modals -- provides built-in focus trap and backdrop
+- `dialog.showModal()` for modal (with backdrop, escape-to-close, focus trap)
+- `dialog.show()` for non-modal
+- `dialog.close()` to dismiss
+- Style `::backdrop` pseudo-element for overlay
+- Returns focus to trigger element on close
+- Add `inert` attribute to siblings when modal is open (prevents background interaction)
+
+**Popover API** (native tooltips/dropdowns):
+- `<div popover>` for light-dismiss popovers (click-outside-to-close)
+- `<button popovertarget="id">` for trigger
+- Auto-stacking (no z-index management needed)
+- Built-in accessibility (focus management, escape-to-close)
+- Use for: tooltips, dropdown menus, date pickers, color pickers
+
+**CSS Anchor Positioning** (Chrome 125+, progressive enhancement):
+- `anchor-name: --trigger` on trigger element
+- `position-anchor: --trigger` on positioned element
+- `@position-try` for fallback positioning
+- Fallback: `position: fixed` with JS-calculated coordinates
+
+**GC Fix Mode (BUILD-fix-N)**:
+- Parse a11y audit feedback for specific issues
+- Re-read affected component files
+- Apply targeted fixes: missing ARIA attributes, keyboard handlers, focus management, contrast adjustments
+- Re-write affected files
+- Signal `build_revision` instead of `build_ready`
+
+## Phase 4: Self-Validation & Output
+
+1. Zero-dependency check:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| No imports from npm | No `import` from node_modules paths |
+| No require() | No CommonJS require statements |
+| ES module exports | Uses `export class` or `export function` |
+| No build tools needed | Runs directly in browser with `<script type="module">` |
+
+2. State machine completeness:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| All states from blueprint | Every blueprint state has corresponding code path |
+| All transitions | Every transition has handler code |
+| Error recovery | All states can reach idle via reset |
+
+3. Accessibility baseline:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| Keyboard handlers | onKeyDown handles Enter, Space, Escape, Arrows |
+| ARIA attributes | role, aria-label, aria-expanded (as needed) set |
+| Focus management | tabindex, focus-visible styles present |
+| Reduced motion | prefers-reduced-motion media query in CSS |
+
+4. Performance baseline:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| GPU-only transforms | No width/height/top/left in transitions |
+| No forced reflow | No offsetWidth/getBoundingClientRect in animation loop |
+| Cleanup | destroy() disconnects all observers and listeners |
+
+5. Update `<session>/wisdom/.msg/meta.json` under `builder` namespace:
+   - Read existing -> merge `{ "builder": { task_type, component_name, file_count, output_dir, states_implemented, events_bound } }` -> write back

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

@@ -0,0 +1,71 @@
+# Analyze Task
+
+Parse user task -> detect interactive component scope -> identify browser APIs -> determine pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Pipeline Hint |
+|----------|------------|---------------|
+| split, compare, before/after, slider, divider | split-compare | single |
+| gallery, carousel, scroll-snap, horizontal scroll | scroll-snap-gallery | gallery |
+| lightbox, modal, overlay, fullscreen view | lightbox | single |
+| scroll reveal, appear on scroll, fade in, stagger | scroll-reveal | single or gallery |
+| glass, terminal, frosted, blur, backdrop | glass-terminal | single |
+| lens, magnify, zoom, loupe | lens-effect | single |
+| drag, resize, pointer, touch | pointer-interaction | single |
+| page, landing, sections, multi-section | interactive-page | page |
+| multiple components, collection, set | multi-component | gallery or page |
+
+## Scope Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Single component mentioned | single |
+| Gallery or scroll-based multi-component | gallery |
+| Full interactive page or multi-section | page |
+| Unclear | ask user |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single component | +1 |
+| Gallery / scroll collection | +2 |
+| Full interactive page | +3 |
+| Pointer/drag interactions | +1 |
+| Scroll-based triggers (IntersectionObserver) | +1 |
+| Touch gestures (pinch, swipe) | +1 |
+| Overlay/modal with focus trap | +1 |
+| Animation choreography (stagger, sequence) | +1 |
+
+Results: 1-2 Low (single), 3-4 Medium (gallery), 5+ High (page)
+
+## Browser API Detection
+
+| Keywords | Browser API |
+|----------|-------------|
+| scroll, appear, visibility, threshold | IntersectionObserver |
+| resize, container, responsive, layout | ResizeObserver |
+| drag, pointer, mouse, click | Pointer Events |
+| touch, swipe, pinch, gesture | Touch Events |
+| scroll snap, snap point, mandatory | CSS scroll-snap |
+| clip, mask, reveal, wipe | CSS clip-path |
+| blur, frosted, glass | CSS backdrop-filter |
+| animate, transition, keyframe | Web Animations API |
+| focus, trap, tab, keyboard | Focus Management |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<single|gallery|page>",
+  "scope": "<description>",
+  "interaction_type": "<pointer|scroll|overlay|mixed>",
+  "components": ["<detected-component-types>"],
+  "browser_apis": ["<detected-apis>"],
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```

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