claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-uidesign/roles/implementer/role.md

@@ -0,0 +1,72 @@
+---
+role: implementer
+prefix: BUILD
+inner_loop: false
+message_types: [state_update]
+---
+
+# Component Code Builder
+
+Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Design tokens | <session>/design/design-tokens.json | Yes (token build) |
+| Component specs | <session>/design/component-specs/*.md | Yes (component build) |
+| Design intelligence | <session>/research/design-intelligence.json | Yes |
+| Latest audit report | <session>/audit/audit-*.md | No |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation
+3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build)
+4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines
+5. Read latest audit report for approved changes and feedback
+6. Detect project tech stack from package.json
+
+## Phase 3: Implementation Execution
+
+**Token Implementation (BUILD-001)**:
+- Convert design tokens to production code
+- Output files in `<session>/build/token-files/`:
+  - `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
+  - `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
+  - `README.md`: Token usage guide
+- All color tokens must have both light and dark values
+- Semantic token names must match design token definitions
+
+**Component Implementation (BUILD-002)**:
+- Implement component code from design specifications
+- Per-component output in `<session>/build/component-files/`:
+  - `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack)
+  - `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
+  - `{ComponentName}.test.tsx`: Basic render + state tests
+  - `index.ts`: Re-export
+- Requirements: no hardcoded colors/spacing (use design tokens), implement all 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
+- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
+- Check implementation against design intelligence anti_patterns
+
+## Phase 4: Validation & Output
+
+1. Token build validation:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| File existence | tokens.css and tokens.ts exist |
+| Token coverage | All defined tokens present in CSS |
+| Theme support | Light/dark variants exist |
+
+2. Component build validation:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| File existence | At least 3 files per component (component, style, index) |
+| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
+| Focus styles | `:focus` or `:focus-visible` defined |
+| Responsive | `@media` queries present |
+| Anti-pattern clean | No violations of design intelligence anti_patterns |
+
+3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
+   - Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back

package/.codex/skills/team-uidesign/roles/researcher/role.md

@@ -0,0 +1,82 @@
+---
+role: researcher
+prefix: RESEARCH
+inner_loop: false
+message_types: [state_update]
+---
+
+# Design System Researcher
+
+Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer 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 type and tech stack from package.json or equivalent:
+
+| Package | Detected Stack |
+|---------|---------------|
+| next | nextjs |
+| react | react |
+| vue | vue |
+| svelte | svelte |
+| @shadcn/ui | shadcn |
+| (default) | html-tailwind |
+
+3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns
+4. Read industry context from session config (industry, strictness, must-have features)
+
+## Phase 3: Research Execution
+
+Execute 4 analysis streams:
+
+**Stream 1 -- Design System Analysis**:
+- Search for existing design tokens (CSS variables, theme configs, token files)
+- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
+- Map color palette, typography scale, spacing system
+- Find component library usage (MUI, Ant Design, shadcn, custom)
+- Output: `<session>/research/design-system-analysis.json`
+
+**Stream 2 -- Component Inventory**:
+- Find all UI component files; identify props/API surface
+- Identify states supported (hover, focus, disabled, etc.)
+- Check accessibility attributes (ARIA labels, roles)
+- Map inter-component dependencies and usage counts
+- Output: `<session>/research/component-inventory.json`
+
+**Stream 3 -- Accessibility Baseline**:
+- Check ARIA attribute usage patterns, keyboard navigation support
+- Assess color contrast ratios (if design tokens found)
+- Find focus management and semantic HTML patterns
+- Output: `<session>/research/accessibility-audit.json`
+
+**Stream 4 -- Design Intelligence (ui-ux-pro-max)**:
+- Call `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` for design system recommendations
+- Call `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` for UX guidelines
+- Call `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` for stack guidelines
+- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
+- Output: `<session>/research/design-intelligence.json`
+
+Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.
+
+## Phase 4: Validation & Output
+
+1. Verify all 4 output files exist and contain valid JSON with required fields:
+
+| File | Required Fields |
+|------|----------------|
+| design-system-analysis.json | existing_tokens, styling_approach |
+| component-inventory.json | components array |
+| accessibility-audit.json | wcag_level |
+| design-intelligence.json | _source, design_system |
+
+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": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back

package/.codex/skills/team-uidesign/roles/reviewer/role.md

@@ -0,0 +1,67 @@
+---
+role: reviewer
+prefix: AUDIT
+inner_loop: false
+message_types: [state_update]
+---
+
+# Design Auditor
+
+Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes |
+| Design intelligence | <session>/research/design-intelligence.json | Yes |
+| Audit history | .msg/meta.json -> reviewer namespace | No |
+| Build artifacts | <session>/build/**/* | Only for final audit |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+
+1. Extract session path from task description
+2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit
+3. Read design intelligence for anti-patterns and ux_guidelines
+4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only)
+5. Load audit_history from meta.json for trend analysis
+
+## Phase 3: Audit Execution
+
+Score 5 dimensions on 1-10 scale:
+
+| Dimension | Weight | Focus |
+|-----------|--------|-------|
+| Consistency | 20% | Token usage, naming conventions, visual uniformity |
+| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast |
+| Completeness | 20% | All states defined, responsive specs, edge cases |
+| Quality | 15% | Token reference integrity, documentation clarity, maintainability |
+| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence |
+
+**Token Audit**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates.
+
+**Component Audit**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions.
+
+**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns).
+
+**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)`
+
+**Signal determination**:
+
+| Condition | Signal |
+|-----------|--------|
+| Score >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) |
+| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) |
+| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
+
+## Phase 4: Report & Output
+
+1. Write audit report to `<session>/audit/audit-{NNN}.md`:
+   - Summary: overall score, signal, critical/high/medium counts
+   - Sync Point Status (if applicable): PASSED/BLOCKED
+   - Dimension Scores table (score/weight/weighted per dimension)
+   - Critical/High/Medium issues with descriptions, locations, fix suggestions
+   - GC Loop Status: signal, action required
+   - Trend analysis (if audit_history exists): improving/stable/declining
+
+2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
+   - Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back

package/.codex/skills/team-uidesign/specs/pipelines.md

@@ -0,0 +1,76 @@
+# Pipeline Definitions
+
+UI design pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Count |
+|------|-------------|------------|
+| component | Single component: research -> design -> audit -> build | 4 tasks |
+| system | Design system: dual-track with 2 sync points | 7 tasks |
+| full-system | Full design system + final integrated audit | 8 tasks |
+
+## Component Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Design system analysis, component inventory, accessibility baseline |
+| DESIGN-001 | designer | [RESEARCH-001] | Design tokens + component spec with all 5 interactive states |
+| AUDIT-001 | reviewer | [DESIGN-001] | 5-dimension audit: consistency, accessibility, completeness, quality, compliance |
+| BUILD-001 | implementer | [AUDIT-001] | CSS custom properties + component code + ARIA + keyboard navigation |
+
+## System Pipeline Task Registry
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| RESEARCH-001 | researcher | [] | Design system analysis across all components |
+| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
+| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1: QUALITY-001] |
+| DESIGN-002 | designer | [AUDIT-001] | Component specification (parallel) |
+| BUILD-001 | implementer | [AUDIT-001] | Token code implementation (parallel) |
+| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
+| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
+
+## Full-System Pipeline Task Registry
+
+Same as System pipeline, plus:
+
+| Task ID | Role | blockedBy | Description |
+|---------|------|-----------|-------------|
+| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
+
+## Checkpoints / Sync Points
+
+| Checkpoint | Task | Condition | Action |
+|------------|------|-----------|--------|
+| QUALITY-001: Sync Point 1 | AUDIT-001 completes | Score >= 8, critical == 0 | Unblock DESIGN-002 + BUILD-001 (parallel) |
+| QUALITY-001: GC Loop | AUDIT-* completes | Score < 8 or critical > 0 | Create DESIGN-fix task, new AUDIT task (max 2 rounds) |
+
+## GC Loop Behavior
+
+| Signal | Condition | Action |
+|--------|-----------|--------|
+| audit_passed | Score >= 8, critical == 0 | GC converged -> record sync_point -> unblock downstream |
+| audit_result | Score 6-7, no critical | gc_rounds < max -> create DESIGN-fix task |
+| fix_required | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) |
+| Any | gc_rounds >= max | Escalate to user: accept / try one more / terminate |
+
+## Parallel Spawn Rules
+
+| Mode | After | Spawn Behavior |
+|------|-------|----------------|
+| component | Sequential | One task at a time |
+| system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
+| system | AUDIT-002 | Spawn BUILD-002 |
+| full-system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
+| full-system | BUILD-002 | Spawn AUDIT-003 |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| RESEARCH-001 | <session>/research/*.json |
+| DESIGN-001 | <session>/design/design-tokens.json + component-specs/*.md |
+| AUDIT-* | <session>/audit/audit-<NNN>.md |
+| BUILD-001 | <session>/build/token-files/* |
+| BUILD-002 | <session>/build/component-files/* |

package/.codex/skills/team-uidesign/specs/team-config.json

@@ -0,0 +1,107 @@
+{
+  "team_name": "uidesign",
+  "team_display_name": "UI Design",
+  "description": "UI design team with CP-9 Dual-Track for parallel design and implementation",
+  "version": "1.0.0",
+
+  "roles": {
+    "coordinator": {
+      "task_prefix": null,
+      "responsibility": "Scope assessment, dual-track orchestration, sync point management, GC loop control",
+      "message_types": ["task_unblocked", "sync_checkpoint", "fix_required", "error", "shutdown"]
+    },
+    "researcher": {
+      "task_prefix": "RESEARCH",
+      "responsibility": "Design system analysis, component inventory, accessibility baseline audit",
+      "message_types": ["research_ready", "research_progress", "error"]
+    },
+    "designer": {
+      "task_prefix": "DESIGN",
+      "responsibility": "Design token definition, component specifications, layout design",
+      "message_types": ["design_ready", "design_revision", "design_progress", "error"]
+    },
+    "reviewer": {
+      "task_prefix": "AUDIT",
+      "additional_prefixes": [],
+      "responsibility": "Design consistency audit, accessibility compliance, visual review",
+      "message_types": ["audit_result", "audit_passed", "fix_required", "error"]
+    },
+    "implementer": {
+      "task_prefix": "BUILD",
+      "responsibility": "Component code implementation, CSS generation, design token consumption",
+      "message_types": ["build_complete", "build_progress", "error"]
+    }
+  },
+
+  "pipelines": {
+    "component": {
+      "description": "Single component: research → design → audit → build",
+      "task_chain": ["RESEARCH-001", "DESIGN-001", "AUDIT-001", "BUILD-001"],
+      "complexity": "low"
+    },
+    "system": {
+      "description": "Design system with dual-track: design tokens → audit → parallel build+components → audit → build components",
+      "task_chain": [
+        "RESEARCH-001",
+        "DESIGN-001:tokens", "AUDIT-001",
+        "DESIGN-002:components || BUILD-001:tokens",
+        "AUDIT-002", "BUILD-002:components"
+      ],
+      "sync_points": ["AUDIT-001", "AUDIT-002"],
+      "complexity": "medium"
+    },
+    "full-system": {
+      "description": "Complete design system with 3 audit checkpoints",
+      "task_chain": [
+        "RESEARCH-001",
+        "DESIGN-001:tokens", "AUDIT-001",
+        "DESIGN-002:components || BUILD-001:tokens",
+        "AUDIT-002",
+        "BUILD-002:components", "AUDIT-003"
+      ],
+      "sync_points": ["AUDIT-001", "AUDIT-002", "AUDIT-003"],
+      "complexity": "high"
+    }
+  },
+
+  "innovation_patterns": {
+    "generator_critic": {
+      "generator": "designer",
+      "critic": "reviewer",
+      "max_rounds": 2,
+      "convergence": "audit.score >= 8 && audit.critical_count === 0",
+      "escalation": "Coordinator intervenes after max rounds"
+    },
+    "shared_memory": {
+      "file": "shared-memory.json",
+      "fields": {
+        "researcher": ["component_inventory", "accessibility_patterns"],
+        "designer": ["design_token_registry", "style_decisions"],
+        "reviewer": ["audit_history"],
+        "implementer": ["component_inventory"]
+      }
+    },
+    "dynamic_pipeline": {
+      "criteria": {
+        "component": "scope.component_count <= 1",
+        "system": "scope.component_count <= 5 && scope.has_token_system",
+        "full-system": "scope.component_count > 5 || scope.is_full_redesign"
+      }
+    },
+    "dual_track": {
+      "pattern": "CP-9",
+      "description": "Design and implementation proceed in parallel after sync checkpoints",
+      "sync_mechanism": "AUDIT tasks serve as sync points between tracks",
+      "fallback": "If dual-track fails, coordinator falls back to sequential execution"
+    }
+  },
+
+  "session_dirs": {
+    "base": ".workflow/.team/UDS-{slug}-{YYYY-MM-DD}/",
+    "research": "research/",
+    "design": "design/",
+    "audit": "audit/",
+    "build": "build/",
+    "messages": ".workflow/.team-msg/{team-name}/"
+  }
+}