maestro-flow 0.5.31 → 0.5.33

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

@@ -0,0 +1,166 @@
+# 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.
+
+## Identity
+- **Name**: coordinator | **Tag**: [coordinator]
+- **Responsibility**: Analyze task -> Create team -> Dispatch tasks -> monitor_process progress -> Report results
+
+## Boundaries
+
+### MUST
+- All output (send_message, 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 blockedBy
+- monitor_process worker progress via message bus and route messages
+- Handle Generator-Critic loops with max 2 iterations
+- Maintain session state persistence
+
+### 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
+
+## 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 |
+|-----------|-----------|---------|
+| Worker callback | Message contains [researcher], [interaction-designer], [builder], [a11y-tester] | -> handleCallback (monitor.md) |
+| 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 callback/check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan `.workflow/.team/IC-*/.msg/meta.json` for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile (audit list_tasks, reset in_progress->pending, rebuild team, kick first ready task)
+4. Multiple -> ask_user 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:
+   ```
+   ask_user({
+     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 Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/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. create_team(team_name="interactive-craft")
+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-Stop
+
+Delegate to `@commands/monitor.md#handleSpawnNext`:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+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:
+   ```
+   ask_user({
+     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
+       { label: "Archive & Clean", description: "Archive session and clean up team resources" },
+       { label: "Keep Active", description: "Keep session for follow-up work" },
+       { label: "Export Results", description: "Export deliverables to specified location" }
+     ]}]
+   })
+   ```
+
+## 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/.agents/skills/team-interactive-craft/roles/interaction-designer/role.md

@@ -0,0 +1,146 @@
+---
+role: interaction-designer
+prefix: INTERACT
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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/.agents/skills/team-interactive-craft/roles/researcher/role.md

@@ -0,0 +1,133 @@
+---
+role: researcher
+prefix: RESEARCH
+inner_loop: false
+message_types: [state_update]
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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., `maestro delegate "..." --to 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