claude-code-workflow 7.2.15 → 7.2.16

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

@@ -0,0 +1,59 @@
+# Analyze Task
+
+Parse user task -> detect UI design scope -> build dependency graph -> design pipeline mode.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Capability | Pipeline Hint |
+|----------|------------|---------------|
+| component, button, card, input, modal | component | component |
+| design system, token, theme | system | system |
+| complete, full, all components, redesign | full | full-system |
+| accessibility, a11y, wcag | accessibility | component or system |
+| implement, build, code | implementation | component |
+
+## Scope Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Single component mentioned | component |
+| Multiple components or "design system" | system |
+| "Full design system" or "complete redesign" | full-system |
+| Unclear | ask user |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single component | +1 |
+| Component system | +2 |
+| Full design system | +3 |
+| Accessibility required | +1 |
+| Multiple industries/constraints | +1 |
+
+Results: 1-2 Low (component), 3-4 Medium (system), 5+ High (full-system)
+
+## Industry Detection
+
+| Keywords | Industry |
+|----------|----------|
+| saas, dashboard, analytics | SaaS/Tech |
+| shop, cart, checkout, e-commerce | E-commerce |
+| medical, patient, healthcare | Healthcare |
+| bank, finance, payment | Finance |
+| edu, course, learning | Education/Content |
+| Default | SaaS/Tech |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<component|system|full-system>",
+  "scope": "<description>",
+  "industry": "<detected-industry>",
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```

package/.codex/skills/team-uidesign/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,156 @@
+# Command: Dispatch
+
+Create the UI design task chain with correct dependencies and structured task descriptions. Supports component, system, and full-system 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 |
+| Industry config | From tasks.json `industry` | Yes |
+
+1. Load user requirement and design scope from tasks.json
+2. Load pipeline stage definitions from specs/pipelines.md
+3. Read `pipeline_mode` and `industry` 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: <design-scope>\n  - Industry: <industry>\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 |
+|------|--------|
+| `component` | Create 4 tasks: RESEARCH -> DESIGN -> AUDIT -> BUILD |
+| `system` | Create 7 tasks: dual-track with 2 sync points |
+| `full-system` | Create 8 tasks: dual-track with 3 sync points (final audit) |
+
+---
+
+### Component Pipeline Task Chain
+
+**RESEARCH-001** (researcher):
+```json
+{
+  "RESEARCH-001": {
+    "title": "Design system analysis and component inventory",
+    "description": "PURPOSE: Analyze existing design system, build component inventory, assess accessibility baseline | Success: 4 research artifacts produced with valid data\nTASK:\n  - Analyze existing design tokens and styling patterns\n  - Build component inventory with props and states\n  - Assess accessibility baseline (WCAG level, ARIA coverage)\n  - Retrieve design intelligence via ui-ux-pro-max\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <design-scope>\n  - Industry: <industry>\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/research/*.json | All 4 research files with valid JSON\nCONSTRAINTS: Read-only analysis | Focus on <design-scope>",
+    "role": "researcher",
+    "prefix": "RESEARCH",
+    "deps": [],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**DESIGN-001** (designer):
+```json
+{
+  "DESIGN-001": {
+    "title": "Define component design with tokens and specifications",
+    "description": "PURPOSE: Define component design with tokens and specifications | Success: Design tokens + component spec with all states defined\nTASK:\n  - Define design tokens consuming research findings\n  - Create component specification with all 5 interactive states\n  - Ensure accessibility spec (role, ARIA, keyboard, focus)\n  - Reference design intelligence recommendations\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <design-scope>\n  - Industry: <industry>\n  - Upstream artifacts: research/*.json\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/design/design-tokens.json + component-specs/*.md | Complete token system + spec\nCONSTRAINTS: Follow W3C Design Tokens Format | All color tokens need light/dark",
+    "role": "designer",
+    "prefix": "DESIGN",
+    "deps": ["RESEARCH-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**AUDIT-001** (reviewer):
+```json
+{
+  "AUDIT-001": {
+    "title": "Audit design for consistency, accessibility, and quality",
+    "description": "PURPOSE: Audit design for consistency, accessibility, and quality | Success: Audit score >= 8 with 0 critical issues\nTASK:\n  - Score 5 dimensions: consistency, accessibility, completeness, quality, industry compliance\n  - Check token naming, theme completeness, contrast ratios\n  - Verify component states and ARIA spec\n  - Check against design intelligence anti-patterns\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <design-scope>\n  - Industry: <industry>\n  - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/audit/audit-001.md | 5-dimension scored report\nCONSTRAINTS: Read-only analysis | GC convergence: score >= 8 and 0 critical",
+    "role": "reviewer",
+    "prefix": "AUDIT",
+    "deps": ["DESIGN-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+**BUILD-001** (implementer):
+```json
+{
+  "BUILD-001": {
+    "title": "Implement component code from design specs",
+    "description": "PURPOSE: Implement component code from design specs | Success: Production code with token consumption and accessibility\nTASK:\n  - Generate CSS custom properties from design tokens\n  - Implement component with all 5 states\n  - Add ARIA attributes and keyboard navigation\n  - Validate no hardcoded values\nCONTEXT:\n  - Session: <session-folder>\n  - Scope: <design-scope>\n  - Industry: <industry>\n  - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md, audit/audit-001.md\n  - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/build/**/* | Component + tokens CSS/TS + tests\nCONSTRAINTS: Use var(--token-name) only | Follow project patterns",
+    "role": "implementer",
+    "prefix": "BUILD",
+    "deps": ["AUDIT-001"],
+    "status": "pending",
+    "findings": "",
+    "error": ""
+  }
+}
+```
+
+---
+
+### System Pipeline Task Chain (Dual-Track)
+
+Create tasks in dependency order:
+
+| Task | Role | deps | Description |
+|------|------|------|-------------|
+| RESEARCH-001 | researcher | [] | Design system analysis |
+| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
+| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1] |
+| DESIGN-002 | designer | [AUDIT-001] | Component specification |
+| BUILD-001 | implementer | [AUDIT-001] | Token code implementation |
+| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
+| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
+
+Task descriptions follow same template as component pipeline, with subject-specific content for tokens vs components and appropriate upstream artifacts.
+
+---
+
+### Full-System Pipeline Task Chain
+
+Same as System Pipeline, plus:
+
+| Task | Role | deps | Description |
+|------|------|------|-------------|
+| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
+
+---
+
+## Phase 4: Validation
+
+Verify task chain integrity:
+
+| Check | Method | Expected |
+|-------|--------|----------|
+| Task count correct | tasks.json count | component: 4, system: 7, full-system: 8 |
+| Dependencies correct | Trace dependency graph | Acyclic, correct deps |
+| No circular dependencies | Trace dependency graph | Acyclic |
+| Task IDs use correct prefixes | Pattern check | RESEARCH/DESIGN/AUDIT/BUILD |
+| 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-uidesign/roles/coordinator/commands/monitor.md

@@ -0,0 +1,194 @@
+# 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 |
+| `DESIGN-*` | designer |
+| `AUDIT-*` | reviewer |
+| `BUILD-*` | implementer |
+
+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 |
+| DESIGN-001 (tokens) | - | Proceed to AUDIT-001 |
+| AUDIT-* | QUALITY-001: Sync Point | Check audit signal -> GC loop or unblock parallel |
+| BUILD-001 (tokens) | - | Check if BUILD-002 ready |
+| BUILD-002 (components) | - | Check if AUDIT-003 exists (full-system) or handleComplete |
+
+5. **Sync Point handling** (AUDIT task completed):
+   Read audit signal from result: `audit_passed`, `audit_result`, or `fix_required`
+
+   | 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 in tasks.json |
+   | `fix_required` | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) in tasks.json |
+   | Any | gc_rounds >= max | Escalate to user |
+
+   **GC Fix Task Creation** (add to tasks.json):
+   ```json
+   {
+     "DESIGN-fix-<round>": {
+       "title": "Address audit feedback",
+       "description": "PURPOSE: Address audit feedback | Success: All critical/high issues resolved\nTASK:\n  - Parse audit feedback for specific issues\n  - Apply targeted fixes\nCONTEXT:\n  - Session: <session-folder>\n  - Upstream artifacts: audit/audit-<NNN>.md",
+       "role": "designer",
+       "prefix": "DESIGN",
+       "deps": [],
+       "status": "pending",
+       "findings": "",
+       "error": ""
+     }
+   }
+   ```
+   Then create new AUDIT task in tasks.json with deps on fix. Increment gc_state.round.
+
+   **GC Escalation Options** (when max rounds exceeded):
+   1. Accept current design - skip review, continue implementation
+   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]  DESIGN-001   (designer)    -> design-tokens.json
+  [RUN]   AUDIT-001    (reviewer)    -> auditing tokens...
+  [WAIT]  BUILD-001    (implementer) -> blocked by AUDIT-001
+  [WAIT]  DESIGN-002   (designer)    -> blocked by AUDIT-001
+
+GC Rounds: 0/2
+Sync Points: 0/<expected>
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+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",
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${role}
+role_spec: ${skillRoot}/roles/${role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+requirement: ${taskDescription}
+inner_loop: false` },
+
+    { 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
+wait_agent({ ids: [agentId] })
+
+// 5) Collect results and update tasks.json
+state.tasks[taskId].status = 'completed'
+delete state.active_agents[taskId]
+```
+
+**Parallel spawn rules by mode**:
+
+| Mode | Scenario | Spawn Behavior |
+|------|----------|---------------|
+| component | Sequential | One task at a time |
+| system | After Sync Point 1 | Spawn DESIGN-002 + BUILD-001 in parallel, wait_agent for both |
+| system | After Sync Point 2 | Spawn BUILD-002 |
+| full-system | After Sync Point 1 | Spawn DESIGN-002 + BUILD-001 in parallel, wait_agent for both |
+| full-system | After BUILD-002 | Spawn AUDIT-003 |
+
+5. Update tasks.json, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate report and completion action.
+
+**Completion check by mode**:
+
+| Mode | Completion Condition |
+|------|---------------------|
+| component | All 4 tasks (+ fix tasks) completed |
+| system | All 7 tasks (+ fix tasks) completed |
+| full-system | All 8 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

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

@@ -0,0 +1,179 @@
+# Coordinator Role
+
+UI Design Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages dual-track task chains (design + implementation), GC loops, sync points.
+
+## 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)
+
+### MUST NOT
+- Implement domain logic (researching, designing, auditing, building) -- workers handle this
+- Spawn workers without creating tasks first
+- Skip sync points when configured
+- Force-advance pipeline past failed audit
+- Modify source code or design 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 |
+|-----------|-----------|---------|
+| 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/UDS-* | -> 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/UDS-*/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 design scope:
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| Single component mentioned | component |
+| Multiple components or "design system" | system |
+| "Full design system" or "complete redesign" | full-system |
+| Unclear | ask user |
+
+3. Ask for missing parameters if scope unclear:
+   ```
+   request_user_input({
+     questions: [
+       { question: "UI design scope?", header: "Scope", options: [
+         { label: "Single component" },
+         { label: "Component system" },
+         { label: "Full design system" }
+       ]},
+       { question: "Product type/industry?", header: "Industry", options: [
+         { label: "SaaS/Tech" }, { label: "E-commerce" },
+         { label: "Healthcare/Finance" }, { label: "Education/Content" }, { label: "Other" }
+       ]}
+     ]
+   })
+   ```
+4. Delegate to `@commands/analyze.md` -> output scope context
+5. Record: pipeline_mode, industry, 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-uidesign`
+2. Generate session ID: `UDS-<slug>-<YYYY-MM-DD>`
+3. Create session folder structure:
+   ```
+   .workflow/.team/UDS-<slug>-<date>/research/
+   .workflow/.team/UDS-<slug>-<date>/design/component-specs/
+   .workflow/.team/UDS-<slug>-<date>/design/layout-specs/
+   .workflow/.team/UDS-<slug>-<date>/audit/
+   .workflow/.team/UDS-<slug>-<date>/build/token-files/
+   .workflow/.team/UDS-<slug>-<date>/build/component-files/
+   .workflow/.team/UDS-<slug>-<date>/wisdom/
+   .workflow/.team/UDS-<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": "<component|system|full-system>",
+     "industry": "<industry>",
+     "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 |
+|------|------------|
+| component | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> BUILD-001 |
+| system | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> [DESIGN-002 + BUILD-001] -> AUDIT-002 -> BUILD-002 |
+| full-system | system chain + AUDIT-003 after BUILD-002 |
+
+## 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 |
+|-------------|------|
+| Design System Analysis | <session>/research/design-system-analysis.json |
+| Component Inventory | <session>/research/component-inventory.json |
+| Accessibility Audit | <session>/research/accessibility-audit.json |
+| Design Intelligence | <session>/research/design-intelligence.json |
+| Design Tokens | <session>/design/design-tokens.json |
+| Component Specs | <session>/design/component-specs/*.md |
+| Audit Reports | <session>/audit/audit-*.md |
+| Token Files | <session>/build/token-files/* |
+| Component Files | <session>/build/component-files/* |
+
+3. Calculate: completed_tasks, gc_rounds, sync_points_passed, final_audit_score
+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" }
+     ]}]
+   })
+   ```
+
+## 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-uidesign/roles/designer/role.md

@@ -0,0 +1,69 @@
+---
+role: designer
+prefix: DESIGN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Design Token & Component Spec Author
+
+Define visual language through design tokens (W3C Design Tokens Format) and component specifications. Consume design intelligence from researcher. Act as Generator in the designer<->reviewer Generator-Critic loop.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Research artifacts | <session>/research/*.json | Yes |
+| Design intelligence | <session>/research/design-intelligence.json | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Audit feedback | <session>/audit/audit-*.md | Only for GC fix tasks |
+
+1. Extract session path from task description
+2. Read research findings: design-system-analysis.json, component-inventory.json, accessibility-audit.json
+3. Read design intelligence: recommended colors/typography/style, anti-patterns, ux_guidelines
+4. Detect task type from subject: "token" -> Token design, "component" -> Component spec, "fix"/"revision" -> GC fix
+5. If GC fix task: read latest audit feedback from audit files
+
+## Phase 3: Design Execution
+
+**Token System Design (DESIGN-001)**:
+- Define complete token system following W3C Design Tokens Format
+- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide)
+- All color tokens must have light/dark variants using `$value: { light: ..., dark: ... }`
+- Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks
+- Document anti-patterns from design intelligence for implementer reference
+- Output: `<session>/design/design-tokens.json`
+
+**Component Specification (DESIGN-002)**:
+- Define component specs consuming design tokens
+- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (default/hover/focus/active/disabled), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints
+- All interactive states required: default, hover (background/opacity change), focus (outline 2px solid, offset 2px), active (pressed), disabled (opacity 0.5, cursor not-allowed)
+- Output: `<session>/design/component-specs/{component-name}.md`
+
+**GC Fix Mode (DESIGN-fix-N)**:
+- Parse audit feedback for specific issues
+- Re-read affected design artifacts; apply fixes (token value adjustments, missing states, accessibility gaps, naming fixes)
+- Re-write affected files; signal `design_revision` instead of `design_ready`
+
+## Phase 4: Self-Validation & Output
+
+1. Token integrity checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| tokens_valid | All $value fields non-empty |
+| theme_complete | Light/dark values for all color tokens |
+| values_parseable | Valid CSS-parseable values |
+| no_duplicates | No duplicate token definitions |
+
+2. Component spec checks:
+
+| Check | Pass Criteria |
+|-------|---------------|
+| states_complete | All 5 states (default/hover/focus/active/disabled) defined |
+| a11y_specified | Role, ARIA, keyboard behavior defined |
+| responsive_defined | At least mobile/desktop breakpoints |
+| token_refs_valid | All `{token.path}` references resolve to defined tokens |
+
+3. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
+   - Read existing -> merge `{ "designer": { task_type, token_categories, component_count, style_decisions } }` -> write back