claude-code-workflow 7.2.27 → 7.2.29

package/.claude/skills/team-motion-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: team-motion-design
+description: Unified team skill for motion design. Animation token systems, scroll choreography, GPU-accelerated transforms, reduced-motion fallback. Uses team-worker agent architecture. Triggers on "team motion design", "animation system".
+allowed-tools: Agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, TaskList, TaskGet, TaskUpdate, TaskCreate, TeamCreate, TeamDelete, SendMessage, mcp__ccw-tools__read_file, mcp__ccw-tools__write_file, mcp__ccw-tools__edit_file, mcp__ccw-tools__team_msg, mcp__chrome-devtools__performance_start_trace, mcp__chrome-devtools__performance_stop_trace, mcp__chrome-devtools__performance_analyze_insight, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__take_screenshot
+---
+
+# Team Motion Design
+
+Systematic motion design pipeline: research -> choreography -> animation -> performance testing. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
+
+## Architecture
+
+```
+Skill(skill="team-motion-design", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- analyze -> dispatch -> spawn workers -> STOP
+                                    |
+                    +-------+-------+-------+-------+
+                    v       v       v       v
+           [team-worker agents, each loads roles/<role>/role.md]
+      motion-researcher  choreographer  animator  motion-tester
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
+| motion-researcher | [roles/motion-researcher/role.md](roles/motion-researcher/role.md) | MRESEARCH-* | false |
+| choreographer | [roles/choreographer/role.md](roles/choreographer/role.md) | CHOREO-* | false |
+| animator | [roles/animator/role.md](roles/animator/role.md) | ANIM-* | true |
+| motion-tester | [roles/motion-tester/role.md](roles/motion-tester/role.md) | MTEST-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `MD`
+- **Session path**: `.workflow/.team/MD-<slug>-<date>/`
+- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+- **Max GC rounds**: 2
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "motion-design",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: motion-design
+requirement: <task-description>
+inner_loop: <true|false>
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
+- [specs/motion-tokens.md](specs/motion-tokens.md) -- Animation token schema
+- [specs/gpu-constraints.md](specs/gpu-constraints.md) -- Compositor-only animation rules
+- [specs/reduced-motion.md](specs/reduced-motion.md) -- Accessibility motion preferences
+
+## Session Directory
+
+```
+.workflow/.team/MD-<slug>-<date>/
++-- .msg/
+|   +-- messages.jsonl         # Team message bus
+|   +-- meta.json              # Pipeline config + GC state
++-- research/                  # Motion researcher output
+|   +-- perf-traces/           # Chrome DevTools performance traces
+|   +-- animation-inventory.json
+|   +-- performance-baseline.json
+|   +-- easing-catalog.json
++-- choreography/              # Choreographer output
+|   +-- motion-tokens.json
+|   +-- sequences/             # Scroll choreography sequences
++-- animations/                # Animator output
+|   +-- keyframes/             # CSS @keyframes files
+|   +-- orchestrators/         # JS animation orchestrators
++-- testing/                   # Motion tester output
+|   +-- traces/                # Performance trace data
+|   +-- reports/               # Performance reports
++-- wisdom/                    # Cross-task knowledge
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |

package/.claude/skills/team-motion-design/roles/animator/role.md

@@ -0,0 +1,194 @@
+---
+role: animator
+prefix: ANIM
+inner_loop: true
+message_types: [state_update]
+---
+
+# Animation Implementer
+
+Implement CSS animations/transitions and JS orchestration from choreography specs. Build @keyframes with motion tokens as custom properties, IntersectionObserver-based scroll triggers, requestAnimationFrame coordination, and prefers-reduced-motion overrides. GPU-accelerated, compositor-only animations.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Motion tokens | <session>/choreography/motion-tokens.json | Yes |
+| Choreography sequences | <session>/choreography/sequences/*.md | Yes (component/page) |
+| Research artifacts | <session>/research/*.json | Yes |
+| GPU constraints | specs/gpu-constraints.md | Yes |
+| Reduced motion spec | specs/reduced-motion.md | Yes |
+| Performance report | <session>/testing/reports/perf-report-*.md | Only for GC fix tasks |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Read motion tokens from choreography/motion-tokens.json
+3. Read choreography sequences (if applicable) from choreography/sequences/*.md
+4. Read research artifacts for existing animation context
+5. Read GPU constraints and reduced motion specs
+6. Detect task type from subject: "token" -> Token CSS, "section" -> Section animation, "fix" -> GC fix
+7. If GC fix task: read latest performance report from testing/reports/
+
+## Phase 3: Implementation Execution
+
+### Token CSS Implementation (ANIM-001 in tokens mode)
+
+Generate CSS custom properties and utility classes:
+
+**File: `<session>/animations/keyframes/motion-tokens.css`**:
+```css
+:root {
+  /* Easing functions */
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+  /* Duration scale */
+  --duration-fast: 0.15s;
+  --duration-base: 0.3s;
+  --duration-slow: 0.6s;
+  --duration-slower: 0.8s;
+  --duration-slowest: 1.2s;
+
+  /* Stagger */
+  --stagger-increment: 0.05s;
+}
+
+/* Reduced motion overrides */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+**File: `<session>/animations/keyframes/utility-animations.css`**:
+- `@keyframes fade-in` (opacity 0->1)
+- `@keyframes fade-up` (opacity 0->1, translateY 20px->0)
+- `@keyframes fade-down` (opacity 0->1, translateY -20px->0)
+- `@keyframes slide-in-left` (translateX -100%->0)
+- `@keyframes slide-in-right` (translateX 100%->0)
+- `@keyframes scale-in` (scale 0.95->1, opacity 0->1)
+- Utility classes: `.animate-fade-in`, `.animate-fade-up`, etc.
+- All animations consume motion token custom properties
+- All use compositor-only properties (transform, opacity)
+
+### Component/Section Animation (ANIM-001..N in component/page mode)
+
+For each section or component defined in choreography sequences:
+
+**CSS @keyframes** (`<session>/animations/keyframes/<name>.css`):
+- Define @keyframes consuming motion tokens via `var(--ease-out)`, `var(--duration-slow)`
+- Use `will-change: transform, opacity` on animated elements (remove after animation via JS)
+- Only animate compositor-safe properties: transform (translate, scale, rotate), opacity, filter
+- NEVER animate: width, height, top, left, margin, padding, border, color, background-color
+
+**JS Orchestrator** (`<session>/animations/orchestrators/<name>.js`):
+```javascript
+// IntersectionObserver-based scroll trigger
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.classList.add('is-visible');
+      observer.unobserve(entry.target); // one-shot
+    }
+  });
+}, { threshold: 0.2, rootMargin: '0px 0px -100px 0px' });
+
+// Staggered animation orchestrator
+function staggerReveal(container, itemSelector) {
+  const items = container.querySelectorAll(itemSelector);
+  const increment = parseFloat(getComputedStyle(document.documentElement)
+    .getPropertyValue('--stagger-increment')) || 0.05;
+
+  items.forEach((item, index) => {
+    item.style.transitionDelay = `${index * increment}s`;
+  });
+  // Trigger via IntersectionObserver on container
+  observer.observe(container);
+}
+
+// Reduced motion detection
+const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+if (prefersReducedMotion.matches) {
+  // Skip parallax, disable springs, use instant transitions
+}
+
+// requestAnimationFrame for scroll-linked effects (parallax)
+function parallaxScroll(element, rate) {
+  if (prefersReducedMotion.matches) return; // skip for reduced motion
+  let ticking = false;
+  window.addEventListener('scroll', () => {
+    if (!ticking) {
+      requestAnimationFrame(() => {
+        const scrolled = window.pageYOffset;
+        element.style.transform = `translateY(${scrolled * rate}px)`;
+        ticking = false;
+      });
+      ticking = true;
+    }
+  });
+}
+```
+
+### Height Animation Workaround
+Since `height` triggers layout (NEVER animate), use the grid trick:
+```css
+.expandable {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows var(--duration-normal) var(--ease-out-quart);
+}
+.expandable.open {
+  grid-template-rows: 1fr;
+}
+.expandable > .content {
+  overflow: hidden;
+}
+```
+This achieves smooth height animation using only grid layout changes (compositor-friendly).
+
+### Perceived Performance
+- **80ms threshold**: Any response under 80ms feels instant to the human brain
+- **Preemptive starts**: Begin animation on `pointerdown` not `click` (saves ~80-120ms perceived)
+- **Early completion**: Visual feedback can "finish" before actual operation completes (optimistic UI)
+- **Ease-in compresses perceived time**: Use ease-in for waiting states (progress bars) — makes them feel faster
+- **Ease-out satisfies entrances**: Use ease-out for content appearing — natural deceleration feels "settled"
+
+### GC Fix Mode (ANIM-fix-N)
+
+- Parse performance report for specific issues
+- Replace layout-triggering properties with compositor-only alternatives:
+  - `width/height` -> `transform: scale()`
+  - `top/left` -> `transform: translate()`
+  - `background-color` -> `opacity` on overlay
+- Reduce will-change elements to max 3-4 simultaneous
+- Add missing prefers-reduced-motion overrides
+- Signal `animation_revision` instead of `animation_ready`
+
+## Phase 4: Self-Validation & Output
+
+1. Animation integrity checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| no_layout_triggers | No width, height, top, left, margin, padding in @keyframes |
+| will_change_budget | Max 3-4 elements with will-change simultaneously |
+| reduced_motion | @media (prefers-reduced-motion: reduce) query present |
+| token_consumption | Animations use var(--token) references, no hardcoded values |
+| compositor_only | Only transform, opacity, filter in animation properties |
+
+2. JS orchestrator checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| intersection_observer | IntersectionObserver used for scroll triggers (not scroll events) |
+| raf_throttled | requestAnimationFrame used with ticking guard for scroll |
+| reduced_motion_js | `matchMedia('(prefers-reduced-motion: reduce)')` check present |
+| cleanup | will-change removed after animation completes (if applicable) |
+
+3. Update `<session>/wisdom/.msg/meta.json` under `animator` namespace:
+   - Read existing -> merge `{ "animator": { task_type, keyframe_count, orchestrator_count, uses_intersection_observer, has_parallax, has_stagger } }` -> write back

package/.claude/skills/team-motion-design/roles/choreographer/role.md

@@ -0,0 +1,164 @@
+---
+role: choreographer
+prefix: CHOREO
+inner_loop: false
+message_types: [state_update]
+---
+
+# Motion Choreographer
+
+Design animation token systems (easing functions, duration/delay scales), scroll-triggered reveal sequences, and transition state diagrams. Consume research findings from motion-researcher. Define the motion language that the animator implements.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Research artifacts | <session>/research/*.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Motion token spec | specs/motion-tokens.md | Yes |
+| GPU constraints | specs/gpu-constraints.md | Yes |
+| Reduced motion spec | specs/reduced-motion.md | Yes |
+
+1. Extract session path from task description
+2. Read research findings: animation-inventory.json, performance-baseline.json, easing-catalog.json
+3. Read motion token schema from specs/motion-tokens.md
+4. Read GPU constraints from specs/gpu-constraints.md for safe property list
+5. Read reduced motion guidelines from specs/reduced-motion.md
+
+## Phase 3: Design Execution
+
+### Motion Token System
+
+Define complete token system as CSS custom properties + JSON:
+
+**Easing Functions**:
+- `--ease-out`: `cubic-bezier(0.16, 1, 0.3, 1)` -- emphasis exit, deceleration
+- `--ease-in-out`: `cubic-bezier(0.65, 0, 0.35, 1)` -- smooth symmetrical
+- `--ease-spring`: `cubic-bezier(0.34, 1.56, 0.64, 1)` -- overshoot bounce
+- Integrate existing easing functions from research (avoid duplicates, reconcile naming)
+
+**Duration Scale**:
+- `--duration-fast`: `0.15s` -- micro-interactions (button press, toggle)
+- `--duration-base`: `0.3s` -- standard transitions (hover, focus)
+- `--duration-slow`: `0.6s` -- content reveals, panel slides
+- `--duration-slower`: `0.8s` -- page transitions, large moves
+- `--duration-slowest`: `1.2s` -- hero animations, splash
+
+**Delay Scale**:
+- `--stagger-base`: `0s` -- first item in stagger sequence
+- `--stagger-increment`: `0.05s` to `0.1s` -- per-item delay addition
+- Formula: `delay = base_delay + (index * stagger_increment)`
+- Max visible stagger: 8 items (avoid >0.8s total delay)
+
+**Reduced Motion Overrides**:
+- All durations -> `0.01ms`
+- All easings -> `linear` (instant)
+- No parallax, no bounce/spring
+- Opacity-only fades allowed (<0.15s)
+
+Output: `<session>/choreography/motion-tokens.json`
+```json
+{
+  "easing": {
+    "ease-out": { "value": "cubic-bezier(0.16, 1, 0.3, 1)", "use": "exit emphasis, deceleration" },
+    "ease-in-out": { "value": "cubic-bezier(0.65, 0, 0.35, 1)", "use": "smooth symmetrical" },
+    "ease-spring": { "value": "cubic-bezier(0.34, 1.56, 0.64, 1)", "use": "overshoot bounce" }
+  },
+  "duration": {
+    "fast": { "value": "0.15s", "use": "micro-interactions" },
+    "base": { "value": "0.3s", "use": "standard transitions" },
+    "slow": { "value": "0.6s", "use": "content reveals" },
+    "slower": { "value": "0.8s", "use": "page transitions" },
+    "slowest": { "value": "1.2s", "use": "hero animations" }
+  },
+  "stagger": {
+    "base_delay": "0s",
+    "increment": "0.05s",
+    "max_items": 8
+  },
+  "reduced_motion": {
+    "duration_override": "0.01ms",
+    "easing_override": "linear",
+    "allowed": ["opacity"],
+    "disallowed": ["parallax", "bounce", "spring", "infinite-loop"]
+  }
+}
+```
+
+### Scroll Choreography Sequences
+
+For component and page modes, define reveal sequences:
+
+- IntersectionObserver thresholds per section (typical: 0.1 to 0.3)
+- Entry direction: fade-up, fade-in, slide-left, slide-right
+- Stagger groups: which elements stagger together, with calculated delays
+- Parallax depths: foreground (1x), midground (0.5x), background (0.2x) scroll rates
+- Scroll-linked effects: progress-based opacity, transform interpolation
+
+Output per section: `<session>/choreography/sequences/<section-name>.md`
+```markdown
+# Section: <name>
+
+## Trigger
+- Observer threshold: 0.2
+- Root margin: "0px 0px -100px 0px"
+
+## Sequence
+1. Heading: fade-up, duration-slow, ease-out, delay 0s
+2. Subheading: fade-up, duration-slow, ease-out, delay 0.05s
+3. Cards[0..N]: fade-up, duration-slow, ease-out, stagger 0.08s each
+
+## Parallax (if applicable)
+- Background image: 0.2x scroll rate
+- Foreground elements: 1x (normal)
+
+## Reduced Motion Fallback
+- All elements: opacity fade only, duration-fast
+- No parallax, no directional movement
+```
+
+### Transition State Diagrams
+
+Define state transitions for interactive elements:
+
+| State Pair | Properties | Duration | Easing |
+|------------|-----------|----------|--------|
+| hidden -> visible (entry) | opacity: 0->1, transform: translateY(20px)->0 | duration-slow | ease-out |
+| visible -> hidden (exit) | opacity: 1->0, transform: 0->translateY(-10px) | duration-base | ease-in-out |
+| idle -> hover | opacity: 1->0.8, transform: scale(1)->scale(1.02) | duration-fast | ease-out |
+| idle -> focus | outline: none->2px solid, outline-offset: 0->2px | duration-fast | ease-out |
+| idle -> active (pressed) | transform: scale(1)->scale(0.98) | duration-fast | ease-out |
+| idle -> loading | opacity: 1->0.6, add pulse animation | duration-base | ease-in-out |
+
+All transitions use compositor-only properties (transform, opacity) per GPU constraints.
+
+## Phase 4: Self-Validation
+
+1. Token completeness checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| easing_complete | All 3 easing functions defined with valid cubic-bezier |
+| duration_complete | All 5 duration steps defined |
+| stagger_defined | Base delay, increment, and max items specified |
+| reduced_motion | Override values defined for all token categories |
+
+2. Sequence checks (if applicable):
+
+| Check | Pass Criteria |
+|-------|---------------|
+| threshold_valid | IntersectionObserver threshold between 0 and 1 |
+| safe_properties | Only compositor-safe properties in animations |
+| stagger_budget | No stagger sequence exceeds 0.8s total |
+| fallback_present | Reduced motion fallback defined for each sequence |
+
+3. State diagram checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| states_covered | entry, exit, hover, focus, active states defined |
+| compositor_only | All animated properties are transform or opacity |
+| durations_use_tokens | All durations reference token scale values |
+
+4. Update `<session>/wisdom/.msg/meta.json` under `choreographer` namespace:
+   - Read existing -> merge `{ "choreographer": { token_count, sequence_count, state_diagrams, has_parallax, has_stagger } }` -> write back

package/.claude/skills/team-motion-design/roles/coordinator/commands/analyze.md

@@ -0,0 +1,64 @@
+# Analyze Task
+
+Parse user task -> detect motion design scope -> build dependency graph -> determine pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Pipeline Hint |
+|----------|------------|---------------|
+| easing, cubic-bezier, duration, timing | token system | tokens |
+| scroll, parallax, reveal, stagger, intersection | scroll choreography | page |
+| transition, hover, focus, state change | component animation | component |
+| @keyframes, will-change, transform, opacity | animation implementation | component |
+| page transition, route animation, full page | page-level motion | page |
+| motion tokens, animation system, design system | token system | tokens |
+| spring, bounce, overshoot | easing design | tokens |
+| reduced-motion, prefers-reduced-motion, a11y | accessibility | component or tokens |
+
+## Scope Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Token/easing/duration system mentioned | tokens |
+| Animate specific component(s) | component |
+| Full page scroll choreography or page transitions | page |
+| Unclear | ask user |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single easing/token system | +1 |
+| Component animation | +2 |
+| Full page choreography | +3 |
+| Multiple scroll sections | +1 |
+| Parallax effects | +1 |
+| Reduced-motion required | +1 |
+| Performance constraints mentioned | +1 |
+
+Results: 1-2 Low (tokens), 3-4 Medium (component), 5+ High (page)
+
+## Framework Detection
+
+| Keywords | Framework |
+|----------|-----------|
+| react, jsx, tsx | React |
+| vue, v-bind | Vue |
+| svelte | Svelte |
+| vanilla, plain js | Vanilla JS |
+| css-only, pure css | CSS-only |
+| Default | CSS + Vanilla JS |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<tokens|component|page>",
+  "scope": "<description>",
+  "framework": "<detected-framework>",
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```