claude-code-workflow 7.2.27 → 7.2.29

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 |

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

@@ -0,0 +1,144 @@
+---
+role: interaction-designer
+prefix: INTERACT
+inner_loop: false
+message_types: [state_update]
+---
+
+# Interaction Blueprint Designer
+
+Design complete interaction blueprints: state machines, event flows, gesture specifications, animation choreography, and input mapping tables. Consume research artifacts to produce blueprints for the builder role.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Research artifacts | <session>/research/*.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Existing blueprints | <session>/interaction/blueprints/*.md | Only for INTERACT-002+ |
+
+1. Extract session path from task description
+2. Read research findings: interaction-inventory.json, browser-api-audit.json, pattern-reference.json
+3. Detect task type from subject: "001" -> Primary blueprint, "002" -> Secondary/gallery blueprint
+4. If INTERACT-002+: read existing blueprints for consistency with base component
+
+## Phase 3: Design Execution
+
+**Primary Blueprint (INTERACT-001)**:
+
+For each target component, produce a blueprint document containing:
+
+### State Machine
+Define complete state diagram:
+```
+[idle] --(pointerenter)--> [hover]
+[hover] --(pointerdown)--> [active]
+[hover] --(pointerleave)--> [idle]
+[active] --(pointermove)--> [dragging/animating]
+[active] --(pointerup)--> [hover]
+[dragging] --(pointerup)--> [settling]
+[settling] --(transitionend)--> [idle]
+[any] --(focus)--> [focused]
+[focused] --(blur)--> [previous-state]
+[any] --(keydown:Escape)--> [idle]
+```
+- All states must be reachable
+- All states must have exit transitions
+- Error/reset transitions from every state back to idle
+
+### Event Flow Map
+Map events to handlers to state transitions:
+
+| Event | Source | Handler | State Transition | Side Effect |
+|-------|--------|---------|-----------------|-------------|
+| pointerdown | element | onPointerDown | idle->active | setPointerCapture, preventDefault |
+| pointermove | document | onPointerMove | active->dragging | update position via lerp |
+| pointerup | document | onPointerUp | dragging->settling | releasePointerCapture |
+| keydown:ArrowLeft | element | onKeyDown | - | decrement value |
+| keydown:ArrowRight | element | onKeyDown | - | increment value |
+| keydown:Escape | element | onKeyDown | any->idle | reset to default |
+| keydown:Enter/Space | element | onKeyDown | idle->active | toggle/activate |
+
+### Gesture Specification
+For pointer/touch interactions:
+
+| Gesture | Detection | Parameters |
+|---------|-----------|------------|
+| Drag | pointerdown + pointermove > 3px | lerp speed: 0.15, axis: x/y/both |
+| Swipe | pointerup with velocity > 0.5px/ms | direction: left/right/up/down |
+| Pinch | 2+ touch points, distance change | scale factor, min/max zoom |
+| Scroll snap | CSS scroll-snap-type: x mandatory | align: start/center, behavior: smooth |
+
+- Lerp interpolation: `current += (target - current) * speed`
+- Dead zone: ignore movements < 3px from start
+- Velocity tracking: store last 3-5 pointer positions with timestamps
+
+### Animation Choreography
+Define animation sequences:
+
+| Animation | Trigger | Properties | Duration | Easing | GPU |
+|-----------|---------|------------|----------|--------|-----|
+| Entry | mount/reveal | opacity 0->1, translateY 20px->0 | 400ms | cubic-bezier(0.16,1,0.3,1) | Yes |
+| Exit | unmount/hide | opacity 1->0, translateY 0->-10px | 200ms | ease-in | Yes |
+| Drag follow | pointermove | translateX via lerp | per-frame | linear (lerp) | Yes |
+| Settle | pointerup | translateX to snap point | 300ms | cubic-bezier(0.16,1,0.3,1) | Yes |
+| Hover | pointerenter | scale 1->1.02 | 200ms | ease-out | Yes |
+| Focus ring | focus-visible | outline-offset 0->2px | 150ms | ease-out | No (outline) |
+| Stagger | intersection | delay: index * 80ms | 400ms+delay | cubic-bezier(0.16,1,0.3,1) | Yes |
+
+- ALL animations must use transform + opacity only (GPU-composited)
+- Exception: outline for focus indicators
+- Reduced motion: replace all motion with opacity-only crossfade (200ms)
+
+### Input Mapping Table
+Unified mapping across input methods:
+
+| Action | Mouse | Touch | Keyboard | Screen Reader |
+|--------|-------|-------|----------|--------------|
+| Activate | click | tap | Enter/Space | Enter/Space |
+| Navigate prev | - | swipe-right | ArrowLeft | ArrowLeft |
+| Navigate next | - | swipe-left | ArrowRight | ArrowRight |
+| Drag/adjust | pointerdown+move | pointerdown+move | Arrow keys (step) | Arrow keys (step) |
+| Dismiss | click outside | tap outside | Escape | Escape |
+| Focus | pointermove (hover) | - | Tab | Tab |
+
+### Platform API Preference
+
+When designing interaction blueprints, prefer native APIs over custom implementations:
+
+| Need | Native API | Custom Fallback |
+|------|-----------|-----------------|
+| Modal dialog | `<dialog>` + `showModal()` | Custom with focus trap + inert |
+| Tooltip/popover | Popover API (`popover` attribute) | Custom with click-outside listener |
+| Dropdown positioning | CSS Anchor Positioning | `position: fixed` + JS coords |
+| Focus trap | `<dialog>` built-in or `inert` attribute | Manual focus cycling with tabindex |
+| Escape-to-close | Built into `<dialog>` and Popover | Manual keydown listener |
+
+Document in blueprint: which native API to use, what the fallback is for unsupported browsers, and how to feature-detect.
+
+**Gallery/Secondary Blueprint (INTERACT-002)**:
+- Design scroll-snap container interaction
+- Navigation controls (prev/next arrows, dots/indicators)
+- Active item detection via IntersectionObserver
+- Keyboard navigation within gallery (ArrowLeft/ArrowRight between items)
+- Touch momentum and snap behavior
+- Reference base component blueprint for consistency
+
+Output: `<session>/interaction/blueprints/{component-name}.md`
+
+## Phase 4: Self-Validation
+
+| Check | Pass Criteria |
+|-------|---------------|
+| State machine complete | All states reachable, all states have exit |
+| Event coverage | All events mapped to handlers |
+| Keyboard complete | All interactive actions have keyboard equivalent |
+| Touch parity | All mouse actions have touch equivalent |
+| GPU-only animations | No width/height/top/left animations |
+| Reduced motion | prefers-reduced-motion fallback defined |
+| Screen reader path | All actions accessible via screen reader |
+
+If any check fails, revise the blueprint before output.
+
+Update `<session>/wisdom/.msg/meta.json` under `interaction-designer` namespace:
+- Read existing -> merge `{ "interaction-designer": { task_type, components_designed, states_count, events_count, gestures } }` -> write back

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

@@ -0,0 +1,131 @@
+---
+role: researcher
+prefix: RESEARCH
+inner_loop: false
+message_types: [state_update]
+---
+
+# Interaction Pattern Researcher
+
+Analyze existing interactive components, audit browser API usage, and collect reference patterns for target component types. Produce foundation data for downstream interaction-designer, builder, and a11y-tester roles.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Detect project structure and existing interactive patterns:
+
+| File Pattern | Detected Pattern |
+|--------------|-----------------|
+| *.js with addEventListener | Event-driven components |
+| IntersectionObserver usage | Scroll-triggered animations |
+| ResizeObserver usage | Responsive layout components |
+| pointer/mouse/touch events | Interactive drag/gesture components |
+| scroll-snap in CSS | Scroll-snap gallery |
+| backdrop-filter in CSS | Glass/frosted effects |
+| clip-path in CSS | Reveal/mask animations |
+
+3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep) to scan for existing interactive components, animation patterns, event handling approaches
+4. Read interaction type context from session config
+
+## Phase 3: Research Execution
+
+Execute 3 analysis streams:
+
+**Stream 1 -- Interaction Inventory**:
+- Search for existing interactive components (event listeners, observers, animation code)
+- Identify interaction patterns in use (drag, scroll, overlay, reveal)
+- Map component lifecycle (init, mount, resize, destroy)
+- Find dependency patterns (any external libs vs vanilla)
+- Catalog gesture handling approaches (pointer vs mouse+touch)
+- Output: `<session>/research/interaction-inventory.json`
+- Schema:
+  ```json
+  {
+    "existing_components": [
+      { "name": "", "type": "", "events": [], "observers": [], "file": "" }
+    ],
+    "patterns": {
+      "event_handling": "",
+      "animation_approach": "",
+      "lifecycle": "",
+      "dependency_model": ""
+    },
+    "summary": { "total_interactive": 0, "vanilla_count": 0, "lib_count": 0 }
+  }
+  ```
+
+**Stream 2 -- Browser API Audit**:
+- Check availability and usage of target browser APIs:
+  - IntersectionObserver (scroll triggers, lazy loading, visibility detection)
+  - ResizeObserver (responsive layout, container queries)
+  - Pointer Events (unified mouse/touch/pen input)
+  - Touch Events (gesture recognition, multi-touch)
+  - CSS scroll-snap (snap points, scroll behavior)
+  - CSS clip-path (shape masking, reveal animations)
+  - CSS backdrop-filter (blur, brightness, glass effects)
+  - Web Animations API (programmatic animation control)
+  - requestAnimationFrame (frame-synced updates)
+- Identify polyfill needs for target browser support
+- Output: `<session>/research/browser-api-audit.json`
+- Schema:
+  ```json
+  {
+    "apis": {
+      "<api-name>": {
+        "available": true,
+        "in_use": false,
+        "support": "baseline|modern|polyfill-needed",
+        "usage_count": 0,
+        "notes": ""
+      }
+    },
+    "polyfill_needs": [],
+    "min_browser_target": ""
+  }
+  ```
+
+**Stream 3 -- Pattern Reference**:
+- Collect reference patterns for each target component type
+- For each component, document: state machine pattern, event flow, animation approach, touch handling, accessibility pattern
+- Reference well-known implementations (e.g., scroll-snap gallery, split-view compare, lightbox overlay)
+- Note performance considerations and gotchas per pattern
+- Output: `<session>/research/pattern-reference.json`
+- Schema:
+  ```json
+  {
+    "patterns": [
+      {
+        "component_type": "",
+        "state_machine": { "states": [], "transitions": [] },
+        "events": { "primary": [], "fallback": [] },
+        "animation": { "approach": "", "gpu_only": true, "easing": "" },
+        "touch": { "gestures": [], "threshold_px": 0 },
+        "a11y": { "role": "", "aria_states": [], "keyboard": [] },
+        "performance": { "budget_ms": 0, "gotchas": [] }
+      }
+    ]
+  }
+  ```
+
+Compile research summary metrics: existing_interactive_count, vanilla_ratio, apis_available, polyfill_count, patterns_collected.
+
+## Phase 4: Validation & Output
+
+1. Verify all 3 output files exist and contain valid JSON with required fields:
+
+| File | Required Fields |
+|------|----------------|
+| interaction-inventory.json | existing_components array, patterns object |
+| browser-api-audit.json | apis object |
+| pattern-reference.json | patterns array |
+
+2. If any file missing or invalid, re-run corresponding stream
+
+3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace:
+   - Read existing -> merge `{ "researcher": { interactive_count, vanilla_ratio, apis_available, polyfill_needs, scope } }` -> write back