mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-06 16:31:12 +08:00
Refactor team collaboration skills and update documentation
- Renamed `team-lifecycle-v5` to `team-lifecycle` across various documentation files for consistency. - Updated references in code examples and usage sections to reflect the new skill name. - Added a new command file for the `monitor` functionality in the `team-iterdev` skill, detailing the coordinator's monitoring events and task management. - Introduced new components for dynamic pipeline visualization and session coordinates display in the frontend. - Implemented utility functions for pipeline stage detection and status derivation based on message history. - Enhanced the team role panel to map members to their respective pipeline roles with status indicators. - Updated Chinese documentation to reflect the changes in skill names and descriptions.
This commit is contained in:
catlog22
@@ -11,25 +11,34 @@ Unified team skill: design system analysis, token definition, component specific
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────┐
|
||||
│ Skill(skill="team-uidesign") │
|
||||
│ args="<task>" or args="--role=xxx" │
|
||||
└───────────────────┬───────────────────────────────┘
|
||||
│ Role Router
|
||||
┌──── --role present? ────┐
|
||||
│ NO │ YES
|
||||
↓ ↓
|
||||
Orchestration Mode Role Dispatch
|
||||
(auto → coordinator) (route to role.md)
|
||||
│
|
||||
┌────┴────┬───────────┬───────────┬───────────┐
|
||||
↓ ↓ ↓ ↓ ↓
|
||||
┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌───────────┐
|
||||
│coordinator││researcher││ designer ││ reviewer ││implementer│
|
||||
│ ││RESEARCH-*││ DESIGN-* ││ AUDIT-* ││ BUILD-* │
|
||||
└──────────┘└──────────┘└──────────┘└──────────┘└───────────┘
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-uidesign") |
|
||||
| args="<task-description>" |
|
||||
+-------------------+-------------------------------+
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
|
|
||||
Coordinator (inline)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v
|
||||
[tw] [tw] [tw] [tw]
|
||||
resear- design- review- imple-
|
||||
cher er er menter
|
||||
|
||||
(tw) = team-worker agent
|
||||
```
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
|
||||
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** -- complete the command workflow before proceeding
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
@@ -38,13 +47,13 @@ Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto r
|
||||
|
||||
### Role Registry
|
||||
|
||||
| Role | File | Task Prefix | Type | Compact |
|
||||
|------|------|-------------|------|---------|
|
||||
| coordinator | [roles/coordinator.md](roles/coordinator.md) | (none) | orchestrator | **⚠️ 压缩后必须重读** |
|
||||
| researcher | [roles/researcher.md](roles/researcher.md) | RESEARCH-* | pipeline | 压缩后必须重读 |
|
||||
| designer | [roles/designer.md](roles/designer.md) | DESIGN-* | pipeline | 压缩后必须重读 |
|
||||
| reviewer | [roles/reviewer.md](roles/reviewer.md) | AUDIT-* | pipeline | 压缩后必须重读 |
|
||||
| implementer | [roles/implementer.md](roles/implementer.md) | BUILD-* | pipeline | 压缩后必须重读 |
|
||||
| Role | Spec | Task Prefix | Inner Loop |
|
||||
|------|------|-------------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
|
||||
| researcher | [role-specs/researcher.md](role-specs/researcher.md) | RESEARCH-* | false |
|
||||
| designer | [role-specs/designer.md](role-specs/designer.md) | DESIGN-* | false |
|
||||
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | AUDIT-* | false |
|
||||
| implementer | [role-specs/implementer.md](role-specs/implementer.md) | BUILD-* | false |
|
||||
|
||||
> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。
|
||||
|
||||
@@ -338,39 +347,60 @@ Beat 1 2 3 4 5 6
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
When coordinator spawns workers, use background mode (Spawn-and-Stop):
|
||||
### v5 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker",
|
||||
team_name: "uidesign",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `You are team "uidesign" <ROLE>.
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-uidesign/role-specs/<role>.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: uidesign
|
||||
requirement: <task-description>
|
||||
inner_loop: false
|
||||
|
||||
## Primary Directive
|
||||
All your work must be executed through Skill to load role definition:
|
||||
Skill(skill="team-uidesign", args="--role=<role>")
|
||||
|
||||
Current task: <task-description>
|
||||
Session: <session-folder>
|
||||
|
||||
## Role Guidelines
|
||||
- Only process <PREFIX>-* tasks, do not execute other role work
|
||||
- All output prefixed with [<role>] identifier
|
||||
- Only communicate with coordinator
|
||||
- Do not use TaskCreate for other roles
|
||||
- Call mcp__ccw-tools__team_msg before every SendMessage
|
||||
|
||||
## Workflow
|
||||
1. Call Skill -> load role definition and execution logic
|
||||
2. Follow role.md 5-Phase flow
|
||||
3. team_msg + SendMessage results to coordinator
|
||||
4. TaskUpdate completed -> check next task`
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
**All roles** (researcher, designer, reviewer, implementer): Set `inner_loop: false`.
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
When the pipeline completes (all tasks done, coordinator Phase 5):
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "UI Design pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
|
||||
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
|
||||
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
| Choice | Action |
|
||||
|--------|--------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete(uidesign) -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-uidesign", args="resume")` |
|
||||
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
|
||||
|
||||
---
|
||||
|
||||
## Unified Session Directory
|
||||
|
||||
@@ -1,326 +0,0 @@
|
||||
# Coordinator Role
|
||||
|
||||
Orchestrate the UI Design workflow: team creation, task dispatching, progress monitoring, session state. Manages dual-track pipelines (design + implementation), sync points, and Generator-Critic loops between designer and reviewer.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Parse user requirements and clarify ambiguous inputs via AskUserQuestion
|
||||
- Create team and spawn worker subagents in background
|
||||
- Dispatch tasks with proper dependency chains (see SKILL.md Task Metadata Registry)
|
||||
- Monitor progress via worker callbacks and route messages
|
||||
- Maintain session state persistence
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute design/implementation work directly (delegate to workers)
|
||||
- Modify task outputs (workers own their deliverables)
|
||||
- Call implementation subagents directly
|
||||
- Skip dependency validation when creating task chains
|
||||
|
||||
> **Core principle**: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via TaskCreate.
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, first detect the invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains `[role-name]` tag from a known worker role | -> handleCallback: auto-advance pipeline |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck: output execution graph, no advancement |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume: check worker states, advance pipeline |
|
||||
| New session | None of the above | -> Phase 0 (Session Resume Check) |
|
||||
|
||||
For callback/check/resume: load coordination logic and execute the appropriate handler, then STOP.
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `task_unblocked` | coordinator -> any | Dependency resolved / sync point passed | Notify worker of available task |
|
||||
| `sync_checkpoint` | coordinator -> all | Audit passed at sync point | Design artifacts stable for consumption |
|
||||
| `fix_required` | coordinator -> designer | Audit found issues | Create DESIGN-fix task |
|
||||
| `error` | coordinator -> all | Critical system error | Escalation to user |
|
||||
| `shutdown` | coordinator -> all | Team being dissolved | Clean shutdown signal |
|
||||
|
||||
---
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
**Objective**: Detect and resume interrupted sessions before creating new ones.
|
||||
|
||||
**Workflow**:
|
||||
1. Scan session directory for sessions with status "active" or "paused"
|
||||
2. No sessions found -> proceed to Phase 1
|
||||
3. Single session found -> resume it (-> Session Reconciliation)
|
||||
4. Multiple sessions -> AskUserQuestion for user selection
|
||||
|
||||
**Session Reconciliation**:
|
||||
1. Audit TaskList -> get real status of all tasks
|
||||
2. Reconcile: session state <-> TaskList status (bidirectional sync)
|
||||
3. Reset any in_progress tasks -> pending (they were interrupted)
|
||||
4. Determine remaining pipeline from reconciled state
|
||||
5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
|
||||
6. Create missing tasks with correct blockedBy dependencies
|
||||
7. Verify dependency chain integrity
|
||||
8. Update session file with reconciled state
|
||||
9. Kick first executable task's worker -> Phase 4
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
**Objective**: Parse user input and gather execution parameters.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. **Parse arguments** for explicit settings: mode, scope, focus areas
|
||||
2. **Ask for missing parameters** via AskUserQuestion:
|
||||
|
||||
| Question | Header | Options |
|
||||
|----------|--------|---------|
|
||||
| UI design scope | Scope | Single component / Component system / Full design system |
|
||||
| Product type/industry | Industry | SaaS/Tech / E-commerce / Healthcare/Finance / Education/Content / Other |
|
||||
| Design constraints | Constraint | Existing design system / WCAG AA / Responsive / Dark mode |
|
||||
|
||||
3. **Map scope to pipeline**:
|
||||
|
||||
| Scope | Pipeline |
|
||||
|-------|----------|
|
||||
| Single component | `component` |
|
||||
| Component system | `system` |
|
||||
| Full design system | `full-system` |
|
||||
|
||||
4. **Industry config** affects audit strictness and design intelligence:
|
||||
|
||||
| Industry | Strictness | Must Have |
|
||||
|----------|------------|-----------|
|
||||
| SaaS/Tech | standard | Responsive, Dark mode |
|
||||
| E-commerce | standard | Responsive, Fast loading |
|
||||
| Healthcare/Finance | strict | WCAG AA, High contrast, Clear typography |
|
||||
| Education/Content | standard | Readability, Responsive |
|
||||
| Other | standard | (none) |
|
||||
|
||||
**Success**: All parameters captured, mode finalized.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
**Objective**: Initialize team, session file, and wisdom directory.
|
||||
|
||||
**Workflow**:
|
||||
1. Generate session ID: `UDS-<slug>-<date>`
|
||||
2. Create session folder: `.workflow/.team/UDS-<slug>-<date>/`
|
||||
3. Call TeamCreate with team name "uidesign"
|
||||
4. Create directory structure:
|
||||
|
||||
```
|
||||
UDS-<slug>-<date>/
|
||||
├── .msg/messages.jsonl
|
||||
├── .msg/meta.json
|
||||
├── wisdom/
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── research/
|
||||
├── design/
|
||||
│ ├── component-specs/
|
||||
│ └── layout-specs/
|
||||
├── audit/
|
||||
└── build/
|
||||
├── token-files/
|
||||
└── component-files/
|
||||
```
|
||||
|
||||
5. Initialize cross-role state via team_msg(type='state_update'):
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "coordinator",
|
||||
type: "state_update",
|
||||
data: {
|
||||
design_intelligence: {},
|
||||
design_token_registry: { colors: {}, typography: {}, spacing: {}, shadows: {}, borders: {} },
|
||||
style_decisions: [],
|
||||
component_inventory: [],
|
||||
accessibility_patterns: [],
|
||||
audit_history: [],
|
||||
industry_context: { industry: <industry>, config: <config> },
|
||||
_metadata: { created_at: <timestamp>, pipeline: <pipeline> }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
6. Write meta.json with:
|
||||
- session_id, team_name, topic, pipeline, status
|
||||
- current_phase, completed_tasks, sync_points
|
||||
- gc_state: { round, max_rounds: 2, converged }
|
||||
- user_preferences, industry_config, pipeline_progress
|
||||
|
||||
**Success**: Team created, session file written, wisdom initialized.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
**Objective**: Dispatch tasks based on mode with proper dependencies.
|
||||
|
||||
### Component Pipeline
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|--------------|-------------|
|
||||
| RESEARCH-001 | researcher | (none) | Design system analysis, component inventory, accessibility audit |
|
||||
| DESIGN-001 | designer | RESEARCH-001 | Component design and specification |
|
||||
| AUDIT-001 | reviewer | DESIGN-001 | Design review (GC loop entry) |
|
||||
| BUILD-001 | implementer | AUDIT-001 | Component code implementation |
|
||||
|
||||
### System Pipeline (Dual-Track)
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|--------------|-------------|
|
||||
| RESEARCH-001 | researcher | (none) | Design system analysis |
|
||||
| DESIGN-001 | designer | RESEARCH-001 | Design token system definition |
|
||||
| AUDIT-001 | reviewer | DESIGN-001 | Token audit [Sync Point 1] |
|
||||
| DESIGN-002 | designer | AUDIT-001 | Component specification design |
|
||||
| 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 |
|
||||
|
||||
### Full-System Pipeline
|
||||
|
||||
Same as System Pipeline, plus:
|
||||
- AUDIT-003: Final comprehensive audit (blockedBy BUILD-002)
|
||||
|
||||
**Task Creation**:
|
||||
- Include `Session: <session-folder>` in every task description
|
||||
- Set owner based on role mapping
|
||||
- Set blockedBy for dependency chains
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
**Objective**: Spawn first batch of ready workers in background, then STOP.
|
||||
|
||||
**Design**: Spawn-and-Stop + Callback pattern.
|
||||
- Spawn workers with `Task(run_in_background: true)` -> immediately return
|
||||
- Worker completes -> SendMessage callback -> auto-advance
|
||||
- User can use "check" / "resume" to manually advance
|
||||
- Coordinator does one operation per invocation, then STOPS
|
||||
|
||||
**Workflow**:
|
||||
1. Find tasks with: status=pending, blockedBy all resolved, owner assigned
|
||||
2. For each ready task -> spawn worker (see SKILL.md Coordinator Spawn Template)
|
||||
3. Output status summary
|
||||
4. STOP
|
||||
|
||||
**Pipeline advancement** driven by three wake sources:
|
||||
- Worker callback (automatic) -> Entry Router -> handleCallback
|
||||
- User "check" -> handleCheck (status only)
|
||||
- User "resume" -> handleResume (advance)
|
||||
|
||||
### Message Handling
|
||||
|
||||
| Received Message | Action |
|
||||
|-----------------|--------|
|
||||
| Researcher: research_ready | Read research output -> team_msg log -> TaskUpdate completed (auto-unblocks DESIGN) |
|
||||
| Designer: design_ready | Read design artifacts -> team_msg log -> TaskUpdate completed (auto-unblocks AUDIT) |
|
||||
| Designer: design_revision | GC loop: update round count, re-assign DESIGN-fix task |
|
||||
| Reviewer: audit_passed (score >= 8) | **Sync Point**: team_msg log(sync_checkpoint) -> TaskUpdate completed -> unblock parallel tasks |
|
||||
| Reviewer: audit_result (score 6-7) | GC round < max -> Create DESIGN-fix -> assign designer |
|
||||
| Reviewer: fix_required (score < 6) | GC round < max -> Create DESIGN-fix with severity CRITICAL -> assign designer |
|
||||
| Reviewer: audit_result + GC round >= max | Escalate to user: "Design review failed after {max} rounds" |
|
||||
| Implementer: build_complete | team_msg log -> TaskUpdate completed -> check if next AUDIT unblocked |
|
||||
| All tasks completed | -> Phase 5 |
|
||||
|
||||
### Generator-Critic Loop Control
|
||||
|
||||
| Condition | Score | Critical | Action |
|
||||
|-----------|-------|----------|--------|
|
||||
| Converged | >= 8 | 0 | Proceed (mark as sync_checkpoint) |
|
||||
| Not converged | 6-7 | 0 | GC round < max -> Create DESIGN-fix task |
|
||||
| Critical issues | < 6 | > 0 | GC round < max -> Create DESIGN-fix (CRITICAL) |
|
||||
| Exceeded max | any | any | Escalate to user |
|
||||
|
||||
**GC Escalation Options**:
|
||||
1. Accept current design - Skip remaining review, continue implementation
|
||||
2. Try one more round - Extra GC loop opportunity
|
||||
3. Terminate - Stop and handle manually
|
||||
|
||||
### Dual-Track Sync Point Management
|
||||
|
||||
**When AUDIT at sync point passes**:
|
||||
1. Record sync point in session.sync_points
|
||||
2. Unblock parallel tasks on both tracks
|
||||
3. team_msg log(sync_checkpoint)
|
||||
|
||||
**Dual-track failure fallback**:
|
||||
- Convert remaining parallel tasks to sequential
|
||||
- Remove parallel dependencies, add sequential blockedBy
|
||||
- team_msg log(error): "Dual-track sync failed, falling back to sequential"
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Report + Next Steps
|
||||
|
||||
**Objective**: Completion report and follow-up options.
|
||||
|
||||
**Workflow**:
|
||||
1. Load session state -> count completed tasks, duration
|
||||
2. List deliverables with output paths
|
||||
3. Update session status -> "completed"
|
||||
4. Offer next steps to user:
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| New component | Design new component (reuse team) |
|
||||
| Integration test | Verify component in actual page context |
|
||||
| Close team | Dismiss all teammates and cleanup |
|
||||
|
||||
**Report Structure**:
|
||||
- pipeline, tasks_completed, gc_rounds, sync_points_passed, final_audit_score
|
||||
- artifacts: { research, design, audit, build }
|
||||
|
||||
---
|
||||
|
||||
## Session State Tracking
|
||||
|
||||
**Update on task completion**:
|
||||
- completed_tasks: append task prefix
|
||||
- pipeline_progress.completed: increment
|
||||
|
||||
**Update on sync point passed**:
|
||||
- sync_points: append { audit, timestamp }
|
||||
|
||||
**Update on GC round**:
|
||||
- gc_state.round: increment
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Audit score < 6 after 2 GC rounds | Escalate to user for decision |
|
||||
| Dual-track sync failure | Fall back to single-track sequential execution |
|
||||
| BUILD cannot find design files | Wait for Sync Point or escalate |
|
||||
| Design token conflict | Reviewer arbitrates, coordinator intervenes |
|
||||
| Worker no response | Track messages, 2x no response -> respawn worker |
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Respawn worker, reassign task |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
@@ -1,249 +0,0 @@
|
||||
# Designer Role
|
||||
|
||||
Design token architect and component specification author. Defines visual language, component behavior, and responsive layouts. Acts as Generator in the designer<->reviewer Generator-Critic loop.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `designer` | **Tag**: `[designer]`
|
||||
- **Task Prefix**: `DESIGN-*`
|
||||
- **Responsibility**: Code generation (design artifacts)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `DESIGN-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[designer]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within design artifact generation responsibility scope
|
||||
- Consume design intelligence from ui-ux-pro-max when available
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify files outside design/ output directory
|
||||
- Omit `[designer]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| Read | Read | Read research findings, design intelligence |
|
||||
| Write | Write | Create design artifacts |
|
||||
| Edit | Write | Modify existing design files |
|
||||
| Glob | Search | Find existing design files |
|
||||
| Grep | Search | Search patterns in files |
|
||||
| Task | Delegate | Delegate to code-developer for complex generation |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `design_ready` | designer -> coordinator | Design artifact complete | Summary + file references |
|
||||
| `design_revision` | designer -> coordinator | GC fix iteration complete | What changed + audit feedback addressed |
|
||||
| `design_progress` | designer -> coordinator | Intermediate update | Current progress |
|
||||
| `error` | designer -> coordinator | Failure | Error details |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "designer",
|
||||
type: <message-type>,
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
> `to` and `summary` are auto-defaulted by the tool.
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from designer --type <message-type> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `DESIGN-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
**Task type detection**:
|
||||
|
||||
| Pattern | Task Type |
|
||||
|---------|-----------|
|
||||
| Subject contains "token" or "token" | Token design |
|
||||
| Subject contains "component" or "component" | Component spec |
|
||||
| Subject contains "fix" or "revision" | GC fix |
|
||||
|
||||
### Phase 2: Context Loading + Shared Memory Read
|
||||
|
||||
**Loading steps**:
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Read role states via team_msg(operation="get_state")
|
||||
3. Read research findings:
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| design-system-analysis.json | Existing tokens, styling approach |
|
||||
| component-inventory.json | Component list, patterns |
|
||||
| accessibility-audit.json | WCAG level, issues |
|
||||
|
||||
4. Read design intelligence:
|
||||
|
||||
| Field | Usage |
|
||||
|-------|-------|
|
||||
| design_system.colors | Recommended color values |
|
||||
| design_system.typography | Recommended font stacks |
|
||||
| recommendations.anti_patterns | Patterns to avoid |
|
||||
| ux_guidelines | Implementation hints |
|
||||
|
||||
5. If GC fix task: Read audit feedback from audit files
|
||||
|
||||
### Phase 3: Design Execution
|
||||
|
||||
#### Token System Design (DESIGN-001)
|
||||
|
||||
**Objective**: Define complete design token system following W3C Design Tokens Format.
|
||||
|
||||
**Token Categories**:
|
||||
|
||||
| Category | Tokens |
|
||||
|----------|--------|
|
||||
| Color | primary, secondary, background, surface, text (primary/secondary), semantic (success/warning/error/info) |
|
||||
| Typography | font-family (base/mono), font-size (xs-3xl), font-weight, line-height |
|
||||
| Spacing | xs(4px), sm(8px), md(16px), lg(24px), xl(32px), 2xl(48px) |
|
||||
| Shadow | sm, md, lg |
|
||||
| Border | radius (sm/md/lg/full), width |
|
||||
| Breakpoint | mobile(320px), tablet(768px), desktop(1024px), wide(1280px) |
|
||||
|
||||
**Design Intelligence Integration**:
|
||||
|
||||
| Source | Usage |
|
||||
|--------|-------|
|
||||
| recommended.colors.primary | -> color.primary.$value.light |
|
||||
| recommended.typography.heading | -> typography.font-family.base |
|
||||
| anti_patterns | -> Document in spec for implementer |
|
||||
|
||||
**Theme Support**:
|
||||
- All color tokens must have light/dark variants
|
||||
- Use `$value: { light: ..., dark: ... }` format
|
||||
|
||||
**Output**: `design/design-tokens.json`
|
||||
|
||||
#### Component Specification (DESIGN-002)
|
||||
|
||||
**Objective**: Define component specs consuming design tokens.
|
||||
|
||||
**Spec Structure**:
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| 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 | Variant descriptions and token overrides |
|
||||
| Anti-Patterns | From design intelligence |
|
||||
| Implementation Hints | From ux_guidelines |
|
||||
|
||||
**State Definition Requirements**:
|
||||
|
||||
| State | Required |
|
||||
|-------|----------|
|
||||
| default | Visual appearance |
|
||||
| hover | Background/opacity change |
|
||||
| focus | Outline specification (2px solid, offset 2px) |
|
||||
| active | Pressed state |
|
||||
| disabled | Opacity 0.5, cursor not-allowed |
|
||||
|
||||
**Output**: `design/component-specs/{component-name}.md`
|
||||
|
||||
#### GC Fix Mode (DESIGN-fix-N)
|
||||
|
||||
**Objective**: Address audit feedback and revise design.
|
||||
|
||||
**Workflow**:
|
||||
1. Parse audit feedback for specific issues
|
||||
2. Re-read affected design artifacts
|
||||
3. Apply fixes based on feedback:
|
||||
- Token value adjustments (contrast ratios, spacing)
|
||||
- Missing state definitions
|
||||
- Accessibility gaps
|
||||
- Naming convention fixes
|
||||
4. Re-write affected files with corrections
|
||||
5. Signal `design_revision` instead of `design_ready`
|
||||
|
||||
### Phase 4: Validation
|
||||
|
||||
**Self-check design artifacts**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| tokens_valid | Verify all $value fields non-empty | All values defined |
|
||||
| states_complete | Check all 5 states defined | default/hover/focus/active/disabled |
|
||||
| a11y_specified | Check accessibility section | Role, ARIA, keyboard defined |
|
||||
| responsive_defined | Check breakpoint specs | At least mobile/desktop |
|
||||
| token_refs_valid | Verify `{token.path}` references | All resolve to defined tokens |
|
||||
|
||||
**Token integrity check**:
|
||||
- Light/dark values exist for all color tokens
|
||||
- No empty $value fields
|
||||
- Valid CSS-parseable values
|
||||
|
||||
**Component spec check**:
|
||||
- All token references resolve
|
||||
- All states defined
|
||||
- A11y section complete
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[designer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Update shared memory**:
|
||||
|
||||
| Field | Update |
|
||||
|-------|--------|
|
||||
| design_token_registry | Token categories and keys |
|
||||
| style_decisions | Append design decision with timestamp |
|
||||
|
||||
**Message type selection**:
|
||||
|
||||
| Task Type | Message Type |
|
||||
|-----------|--------------|
|
||||
| GC fix task | `design_revision` |
|
||||
| Normal task | `design_ready` |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No DESIGN-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Research data missing | Use default tokens + mark for confirmation |
|
||||
| Token conflict | Document decision rationale, submit for review arbitration |
|
||||
| GC fix cannot satisfy all feedback | Document trade-offs, let coordinator decide |
|
||||
| Too many components | Prioritize MVP components, mark post-MVP |
|
||||
| Context/Plan file not found | Notify coordinator, request location |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
@@ -1,278 +0,0 @@
|
||||
# Implementer Role
|
||||
|
||||
Component code builder responsible for translating design specifications into production code. Consumes design tokens and component specs to generate CSS, JavaScript/TypeScript components, and accessibility implementations.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `implementer` | **Tag**: `[implementer]`
|
||||
- **Task Prefix**: `BUILD-*`
|
||||
- **Responsibility**: Code generation
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `BUILD-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[implementer]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within code implementation responsibility scope
|
||||
- Consume design tokens via CSS custom properties (no hardcoded values)
|
||||
- Follow design specifications exactly
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify design artifacts (only consume them)
|
||||
- Omit `[implementer]` identifier in any output
|
||||
- Use hardcoded colors/spacing (must use design tokens)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| Read | Read | Read design tokens, component specs, audit reports |
|
||||
| Write | Write | Create implementation files |
|
||||
| Edit | Write | Modify existing code files |
|
||||
| Glob | Search | Find files matching patterns |
|
||||
| Grep | Search | Search patterns in files |
|
||||
| Bash | Execute | Run build commands, tests |
|
||||
| Task | Delegate | Delegate to code-developer for implementation |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `build_complete` | implementer -> coordinator | Implementation finished | Changed files + summary |
|
||||
| `build_progress` | implementer -> coordinator | Intermediate update | Current progress |
|
||||
| `error` | implementer -> coordinator | Failure | Error details |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "implementer",
|
||||
type: <message-type>,
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
> `to` and `summary` are auto-defaulted by the tool.
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from implementer --type <message-type> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `BUILD-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
**Build type detection**:
|
||||
|
||||
| Pattern | Build Type |
|
||||
|---------|-----------|
|
||||
| Subject contains "token" or "token" | Token implementation |
|
||||
| Subject contains "component" or "component" | Component implementation |
|
||||
|
||||
### Phase 2: Context Loading + Shared Memory Read
|
||||
|
||||
**Loading steps**:
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Read role states via team_msg(operation="get_state"):
|
||||
|
||||
| Field | Usage |
|
||||
|-------|-------|
|
||||
| design_token_registry | Expected token categories |
|
||||
| style_decisions | Styling approach decisions |
|
||||
|
||||
3. Read design artifacts:
|
||||
|
||||
| Artifact | Build Type |
|
||||
|----------|-----------|
|
||||
| design-tokens.json | Token build |
|
||||
| component-specs/*.md | Component build |
|
||||
|
||||
4. Read latest audit report (for approved changes and feedback)
|
||||
|
||||
5. Read design intelligence:
|
||||
|
||||
| Field | Usage |
|
||||
|-------|-------|
|
||||
| stack_guidelines | Tech-specific implementation patterns |
|
||||
| recommendations.anti_patterns | Patterns to avoid |
|
||||
| ux_guidelines | Best practices |
|
||||
|
||||
6. Detect project tech stack from package.json
|
||||
|
||||
### Phase 3: Implementation Execution
|
||||
|
||||
#### Token Implementation (BUILD-001)
|
||||
|
||||
**Objective**: Convert design tokens to production code.
|
||||
|
||||
**Output files**:
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| tokens.css | CSS custom properties with :root and [data-theme="dark"] |
|
||||
| tokens.ts | TypeScript constants/types for programmatic access |
|
||||
| README.md | Token usage guide |
|
||||
|
||||
**CSS Output Structure**:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary: #1976d2;
|
||||
--color-text-primary: rgba(0,0,0,0.87);
|
||||
--spacing-md: 16px;
|
||||
/* ... */
|
||||
}
|
||||
|
||||
[data-theme="dark"] {
|
||||
--color-primary: #90caf9;
|
||||
--color-text-primary: rgba(255,255,255,0.87);
|
||||
/* ... */
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root:not([data-theme="light"]) {
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Requirements**:
|
||||
- Semantic token names matching design tokens
|
||||
- All color tokens have both light and dark values
|
||||
- CSS custom properties for runtime theming
|
||||
- TypeScript types enable autocomplete
|
||||
|
||||
**Execution**: Delegate to code-developer subagent.
|
||||
|
||||
#### Component Implementation (BUILD-002)
|
||||
|
||||
**Objective**: Implement component code from design specifications.
|
||||
|
||||
**Input**:
|
||||
- Component specification markdown
|
||||
- Design tokens (CSS file)
|
||||
- Audit feedback (if any)
|
||||
- Anti-patterns to avoid
|
||||
|
||||
**Output files** (per component):
|
||||
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| {ComponentName}.tsx | React/Vue/Svelte component |
|
||||
| {ComponentName}.css | Styles consuming tokens |
|
||||
| {ComponentName}.test.tsx | Basic render + state tests |
|
||||
| index.ts | Re-export |
|
||||
|
||||
**Implementation Requirements**:
|
||||
|
||||
| Requirement | Details |
|
||||
|-------------|---------|
|
||||
| Token consumption | Use var(--token-name), no hardcoded values |
|
||||
| States | Implement all 5: default, hover, focus, active, disabled |
|
||||
| ARIA | Add attributes as specified in design spec |
|
||||
| Responsive | Support breakpoints from spec |
|
||||
| Patterns | Follow project's existing component patterns |
|
||||
|
||||
**Accessibility Requirements**:
|
||||
|
||||
| Requirement | Criteria |
|
||||
|-------------|----------|
|
||||
| Keyboard navigation | Must work (Tab, Enter, Space, etc.) |
|
||||
| Screen reader | ARIA support |
|
||||
| Focus indicator | Visible using design token |
|
||||
| Color contrast | WCAG AA (4.5:1 text, 3:1 UI) |
|
||||
|
||||
**Anti-pattern Avoidance**:
|
||||
- Check against design intelligence anti_patterns
|
||||
- Verify no violation in implementation
|
||||
|
||||
**Execution**: Delegate to code-developer subagent per component.
|
||||
|
||||
### Phase 4: Validation
|
||||
|
||||
**Token build validation**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| File existence | Read tokens.css, tokens.ts | Files exist |
|
||||
| Token coverage | Parse CSS | All defined tokens present |
|
||||
| Theme support | Parse CSS | Light/dark variants exist |
|
||||
|
||||
**Component build validation**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| File existence | Glob component dir | At least 3 files (component, style, index) |
|
||||
| Token usage | Grep hardcoded values | No #xxx or rgb() in CSS (except in tokens.css) |
|
||||
| Focus styles | Grep :focus | :focus or :focus-visible defined |
|
||||
| Responsive | Grep @media | Media queries present |
|
||||
|
||||
**Hardcoded value detection**:
|
||||
|
||||
| Pattern | Severity |
|
||||
|---------|----------|
|
||||
| `#[0-9a-fA-F]{3,8}` in component CSS | Warning (should use token) |
|
||||
| `rgb(` or `rgba(` in component CSS | Warning (should use token) |
|
||||
| `cursor: pointer` missing on interactive | Info |
|
||||
| Missing :focus styles on interactive | Warning |
|
||||
|
||||
**Anti-pattern self-check**:
|
||||
- Verify implementation doesn't violate any anti_patterns from design intelligence
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[implementer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Update shared memory** (for component build):
|
||||
|
||||
| Field | Update |
|
||||
|-------|--------|
|
||||
| component_inventory | Add implementation_path, set implemented=true |
|
||||
|
||||
**Report content**:
|
||||
- Build type (token/component)
|
||||
- Output file count
|
||||
- Output directory path
|
||||
- List of created files
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No BUILD-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Design token file not found | Wait for sync point or report error |
|
||||
| Component spec incomplete | Use defaults + mark for confirmation |
|
||||
| Code generation fails | Retry once, still fails -> report error |
|
||||
| Hardcoded values detected | Auto-replace with token references |
|
||||
| Unknown tech stack | Default to React + CSS Modules |
|
||||
| Context/Plan file not found | Notify coordinator, request location |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
@@ -1,284 +0,0 @@
|
||||
# Researcher Role
|
||||
|
||||
Design system analyst responsible for current state assessment, component inventory, accessibility baseline, and competitive research. Provides foundation data for downstream designer and reviewer roles.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `researcher` | **Tag**: `[researcher]`
|
||||
- **Task Prefix**: `RESEARCH-*`
|
||||
- **Responsibility**: Read-only analysis
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `RESEARCH-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[researcher]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within read-only analysis responsibility scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify any files or resources (read-only analysis only)
|
||||
- Omit `[researcher]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| Read | Read | Read files and session data |
|
||||
| Glob | Search | Find files matching patterns |
|
||||
| Grep | Search | Search file contents |
|
||||
| Bash | Read | Execute read-only shell commands |
|
||||
| Task | Delegate | Delegate to cli-explore-agent, Explore agent |
|
||||
| Skill | Delegate | Call ui-ux-pro-max for design intelligence |
|
||||
| WebSearch | External | Search external documentation |
|
||||
| WebFetch | External | Fetch external resources |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `research_ready` | researcher -> coordinator | Research complete | Summary of findings + file references |
|
||||
| `research_progress` | researcher -> coordinator | Intermediate update | Current progress status |
|
||||
| `error` | researcher -> coordinator | Failure | Error details |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "researcher",
|
||||
type: <message-type>,
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
> `to` and `summary` are auto-defaulted by the tool.
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from researcher --type <message-type> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `RESEARCH-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: Context Loading + Shared Memory Read
|
||||
|
||||
**Loading steps**:
|
||||
|
||||
1. Extract session path from task description (pattern: `Session: <path>`)
|
||||
2. Read role states via team_msg(operation="get_state") from session
|
||||
3. Load existing component_inventory and accessibility_patterns if available
|
||||
|
||||
**Input Sources**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Task description | Yes |
|
||||
| Role state | team_msg(operation="get_state", session_id=<session-id>) | Yes |
|
||||
| Wisdom files | Session/wisdom/ | No |
|
||||
|
||||
### Phase 3: Research Execution
|
||||
|
||||
Research is divided into 4 analysis streams. Streams 1-3 analyze the codebase, Stream 4 retrieves design intelligence from ui-ux-pro-max.
|
||||
|
||||
#### Stream 1: Design System Analysis
|
||||
|
||||
**Objective**: Analyze existing design system and styling patterns.
|
||||
|
||||
**Tasks**:
|
||||
- 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, custom, etc.)
|
||||
|
||||
**Output**: `design-system-analysis.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"existing_tokens": { "colors": [], "typography": [], "spacing": [], "shadows": [] },
|
||||
"styling_approach": "css-modules | css-in-js | utility | scss | mixed",
|
||||
"component_library": { "name": "", "version": "", "usage_count": 0 },
|
||||
"custom_components": [],
|
||||
"inconsistencies": [],
|
||||
"_metadata": { "timestamp": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
**Execution**: Delegate to cli-explore-agent subagent.
|
||||
|
||||
#### Stream 2: Component Inventory
|
||||
|
||||
**Objective**: Discover all UI components in the codebase.
|
||||
|
||||
**Tasks**:
|
||||
- Find all component files
|
||||
- Identify props/API surface
|
||||
- Identify states supported (hover, focus, disabled, etc.)
|
||||
- Check accessibility attributes (ARIA labels, roles, etc.)
|
||||
- Map dependencies on other components
|
||||
|
||||
**Output**: `component-inventory.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"components": [{
|
||||
"name": "", "path": "", "type": "atom|molecule|organism|template",
|
||||
"props": [], "states": [], "aria_attributes": [],
|
||||
"dependencies": [], "usage_count": 0
|
||||
}],
|
||||
"patterns": {
|
||||
"naming_convention": "",
|
||||
"file_structure": "",
|
||||
"state_management": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Execution**: Delegate to Explore subagent.
|
||||
|
||||
#### Stream 3: Accessibility Baseline
|
||||
|
||||
**Objective**: Assess current accessibility state.
|
||||
|
||||
**Tasks**:
|
||||
- Check for ARIA attributes usage patterns
|
||||
- Identify keyboard navigation support
|
||||
- Check color contrast ratios (if design tokens found)
|
||||
- Find focus management patterns
|
||||
- Check semantic HTML usage
|
||||
|
||||
**Output**: `accessibility-audit.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"wcag_level": "none|partial-A|A|partial-AA|AA",
|
||||
"aria_coverage": { "labeled": 0, "total": 0, "percentage": 0 },
|
||||
"keyboard_nav": { "supported": [], "missing": [] },
|
||||
"contrast_issues": [],
|
||||
"focus_management": { "pattern": "", "coverage": "" },
|
||||
"semantic_html": { "score": 0, "issues": [] },
|
||||
"recommendations": []
|
||||
}
|
||||
```
|
||||
|
||||
**Execution**: Delegate to Explore subagent.
|
||||
|
||||
#### Stream 4: Design Intelligence (ui-ux-pro-max)
|
||||
|
||||
**Objective**: Retrieve industry-specific design intelligence.
|
||||
|
||||
**Detection**:
|
||||
- Industry from task description or session config
|
||||
- Tech stack from package.json
|
||||
|
||||
| Package | Detected Stack |
|
||||
|---------|---------------|
|
||||
| next | nextjs |
|
||||
| react | react |
|
||||
| vue | vue |
|
||||
| svelte | svelte |
|
||||
| @shadcn/ui | shadcn |
|
||||
| (default) | html-tailwind |
|
||||
|
||||
**Execution**: Call Skill(ui-ux-pro-max) with:
|
||||
1. `--design-system` for design system recommendations
|
||||
2. `--domain ux` for UX guidelines (accessibility, animation, responsive)
|
||||
3. `--stack <detected>` for stack-specific guidelines
|
||||
|
||||
**Output**: `design-intelligence.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"_source": "ui-ux-pro-max-skill | llm-general-knowledge",
|
||||
"_generated_at": "...",
|
||||
"industry": "...",
|
||||
"detected_stack": "...",
|
||||
"design_system": { "colors", "typography", "style" },
|
||||
"ux_guidelines": [],
|
||||
"stack_guidelines": {},
|
||||
"recommendations": { "anti_patterns": [], "must_have": [] }
|
||||
}
|
||||
```
|
||||
|
||||
**Degradation**: When ui-ux-pro-max unavailable, use LLM general knowledge, mark `_source` as `"llm-general-knowledge"`.
|
||||
|
||||
### Phase 4: Validation
|
||||
|
||||
**Verification checks**:
|
||||
|
||||
| File | Check |
|
||||
|------|-------|
|
||||
| design-system-analysis.json | Exists and valid JSON |
|
||||
| component-inventory.json | Exists and has components array |
|
||||
| accessibility-audit.json | Exists and has wcag_level |
|
||||
| design-intelligence.json | Exists and has required fields |
|
||||
|
||||
**If missing**: Re-run corresponding stream.
|
||||
|
||||
**Compile research summary**:
|
||||
|
||||
| Metric | Source |
|
||||
|--------|--------|
|
||||
| design_system_exists | designAnalysis.component_library?.name |
|
||||
| styling_approach | designAnalysis.styling_approach |
|
||||
| total_components | inventory.components?.length |
|
||||
| accessibility_level | a11yAudit.wcag_level |
|
||||
| design_intelligence_source | designIntelligence._source |
|
||||
| anti_patterns_count | designIntelligence.recommendations.anti_patterns?.length |
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[researcher]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Update shared memory**:
|
||||
- component_inventory: inventory.components
|
||||
- accessibility_patterns: a11yAudit.recommendations
|
||||
- design_intelligence: designIntelligence
|
||||
- industry_context: { industry, detected_stack }
|
||||
|
||||
**Report content**:
|
||||
- Total components discovered
|
||||
- Styling approach detected
|
||||
- Accessibility level assessed
|
||||
- Component library (if any)
|
||||
- Design intelligence source
|
||||
- Anti-patterns count
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No RESEARCH-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Cannot detect design system | Report as "greenfield", recommend building from scratch |
|
||||
| Component inventory timeout | Report partial findings + mark unscanned areas |
|
||||
| Accessibility tools unavailable | Manual spot-check + degraded report |
|
||||
| ui-ux-pro-max unavailable | Degrade to LLM general knowledge, mark `_source: "llm-general-knowledge"` |
|
||||
| Session/Plan file not found | Notify coordinator, request location |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
@@ -1,299 +0,0 @@
|
||||
# Reviewer Role
|
||||
|
||||
Design auditor responsible for consistency, accessibility compliance, and visual quality review. Acts as Critic in the designer<->reviewer Generator-Critic loop. Serves as sync point gatekeeper in dual-track pipelines.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `reviewer` | **Tag**: `[reviewer]`
|
||||
- **Task Prefix**: `AUDIT-*`
|
||||
- **Responsibility**: Read-only analysis (Validation)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `AUDIT-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[reviewer]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within validation responsibility scope
|
||||
- Apply industry-specific anti-patterns from design intelligence
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify any files or resources (read-only analysis only)
|
||||
- Omit `[reviewer]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| Read | Read | Read design artifacts, audit history |
|
||||
| Glob | Search | Find design and build files |
|
||||
| Grep | Search | Search patterns in files |
|
||||
| Bash | Read | Execute read-only shell commands |
|
||||
| Task | Delegate | Delegate to Explore agent for analysis |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `audit_passed` | reviewer -> coordinator | Score >= 8, no critical issues | Audit report + score, GC converged |
|
||||
| `audit_result` | reviewer -> coordinator | Score 6-7, non-critical issues | Feedback for GC revision |
|
||||
| `fix_required` | reviewer -> coordinator | Score < 6, critical issues found | Critical issues list |
|
||||
| `error` | reviewer -> coordinator | Failure | Error details |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "reviewer",
|
||||
type: <message-type>,
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
> `to` and `summary` are auto-defaulted by the tool.
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from reviewer --type <message-type> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Task Discovery
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery
|
||||
|
||||
Standard task discovery flow: TaskList -> filter by prefix `AUDIT-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
**Audit type detection**:
|
||||
|
||||
| Pattern | Audit Type |
|
||||
|---------|-----------|
|
||||
| Subject contains "token" or "token" | Token audit |
|
||||
| Subject contains "component" or "component" | Component audit |
|
||||
| Subject contains "final" or "final" | Final audit (cross-cutting) |
|
||||
| Subject contains "Sync Point" or "sync" | Sync point audit |
|
||||
|
||||
### Phase 2: Context Loading + Shared Memory Read
|
||||
|
||||
**Loading steps**:
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Read role states via team_msg(operation="get_state"):
|
||||
|
||||
| Field | Usage |
|
||||
|-------|-------|
|
||||
| audit_history | Previous audit scores for trend |
|
||||
| design_token_registry | Expected token categories |
|
||||
| industry_context | Strictness level, must-have features |
|
||||
|
||||
3. Read design intelligence for anti-patterns:
|
||||
|
||||
| Field | Usage |
|
||||
|-------|-------|
|
||||
| recommendations.anti_patterns | Industry-specific violations to check |
|
||||
| ux_guidelines | Best practices reference |
|
||||
|
||||
4. Read design artifacts:
|
||||
|
||||
| Artifact | When |
|
||||
|----------|------|
|
||||
| design-tokens.json | Token audit, component audit |
|
||||
| component-specs/*.md | Component audit, final audit |
|
||||
| build/**/* | Final audit only |
|
||||
|
||||
### Phase 3: Audit Execution
|
||||
|
||||
#### Audit Dimensions
|
||||
|
||||
5 dimensions scored on 1-10 scale:
|
||||
|
||||
| Dimension | Weight | Criteria |
|
||||
|-----------|--------|----------|
|
||||
| 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
|
||||
|
||||
**Consistency checks**:
|
||||
- Naming convention (kebab-case, semantic names)
|
||||
- Value patterns (consistent units: rem/px/%)
|
||||
- Theme completeness (light + dark for all colors)
|
||||
|
||||
**Accessibility checks**:
|
||||
- Color contrast ratios (text on background >= 4.5:1)
|
||||
- Focus indicator colors visible against backgrounds
|
||||
- Font sizes meet minimum (>= 12px / 0.75rem)
|
||||
|
||||
**Completeness checks**:
|
||||
- All token categories present (color, typography, spacing, shadow, border)
|
||||
- Breakpoints defined
|
||||
- Semantic color tokens (success, warning, error, info)
|
||||
|
||||
**Quality checks**:
|
||||
- $type metadata present (W3C format)
|
||||
- Values are valid (CSS-parseable)
|
||||
- No duplicate definitions
|
||||
|
||||
**Industry Compliance checks**:
|
||||
- Anti-patterns from ui-ux-pro-max not present in design
|
||||
- UX best practices followed
|
||||
- Design intelligence recommendations adhered to
|
||||
|
||||
#### Component Audit
|
||||
|
||||
**Consistency**:
|
||||
- Token references resolve
|
||||
- Naming matches convention
|
||||
|
||||
**Accessibility**:
|
||||
- ARIA roles defined
|
||||
- Keyboard behavior specified
|
||||
- Focus indicator defined
|
||||
|
||||
**Completeness**:
|
||||
- All 5 states (default/hover/focus/active/disabled)
|
||||
- Responsive breakpoints specified
|
||||
- Variants documented
|
||||
|
||||
**Quality**:
|
||||
- Clear descriptions
|
||||
- Variant system defined
|
||||
- Interaction specs clear
|
||||
|
||||
#### Final Audit (Cross-cutting)
|
||||
|
||||
**Token <-> Component consistency**:
|
||||
- All token references in components resolve to defined tokens
|
||||
- No hardcoded values in component specs
|
||||
|
||||
**Code <-> Design consistency** (if build artifacts exist):
|
||||
- CSS variables match design tokens
|
||||
- Component implementation matches spec states
|
||||
- ARIA attributes implemented as specified
|
||||
|
||||
**Cross-component consistency**:
|
||||
- Consistent spacing patterns
|
||||
- Consistent color usage for similar elements
|
||||
- Consistent interaction patterns
|
||||
|
||||
#### Score Calculation
|
||||
|
||||
```
|
||||
overallScore = round(
|
||||
consistency.score * 0.20 +
|
||||
accessibility.score * 0.25 +
|
||||
completeness.score * 0.20 +
|
||||
quality.score * 0.15 +
|
||||
industryCompliance.score * 0.20
|
||||
)
|
||||
```
|
||||
|
||||
**Issue Severity Classification**:
|
||||
|
||||
| Severity | Criteria | GC Impact |
|
||||
|----------|----------|-----------|
|
||||
| CRITICAL | Accessibility non-compliant (contrast < 3:1), missing critical states | Blocks GC convergence |
|
||||
| HIGH | Token reference inconsistent, missing ARIA, partial states | Counts toward GC score |
|
||||
| MEDIUM | Naming non-standard, incomplete docs, minor style issues | Recommended fix |
|
||||
| LOW | Code style, optional optimization | Informational |
|
||||
|
||||
**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) |
|
||||
|
||||
#### Audit Report Generation
|
||||
|
||||
**Output**: `audit/audit-{NNN}.md`
|
||||
|
||||
**Report Structure**:
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| Summary | Overall score, signal, critical/high/medium counts |
|
||||
| Sync Point Status | (If sync point) PASSED/BLOCKED |
|
||||
| Dimension Scores | Table with score/weight/weighted per dimension |
|
||||
| Critical Issues | Description, location, fix suggestion |
|
||||
| High Issues | Description, fix suggestion |
|
||||
| Medium Issues | Description |
|
||||
| Recommendations | Improvement suggestions |
|
||||
| GC Loop Status | Signal, action required |
|
||||
|
||||
### Phase 4: Validation
|
||||
|
||||
**Verification checks**:
|
||||
|
||||
| Check | Method |
|
||||
|-------|--------|
|
||||
| Audit report written | Read audit file exists |
|
||||
| Score valid | 1-10 range |
|
||||
| Signal valid | One of: audit_passed, audit_result, fix_required |
|
||||
|
||||
**Trend analysis** (if audit_history exists):
|
||||
|
||||
| Comparison | Trend |
|
||||
|------------|-------|
|
||||
| current > previous | improving |
|
||||
| current = previous | stable |
|
||||
| current < previous | declining |
|
||||
|
||||
Include trend in report.
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[reviewer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Update shared memory**:
|
||||
|
||||
| Field | Update |
|
||||
|-------|--------|
|
||||
| audit_history | Append { audit_id, score, critical_count, signal, is_sync_point, timestamp } |
|
||||
|
||||
**Message content**:
|
||||
- Audit number
|
||||
- Score
|
||||
- Signal
|
||||
- Critical/High issue counts
|
||||
- Sync point status (if applicable)
|
||||
- Issues requiring fix (if not passed)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No AUDIT-* tasks available | Idle, wait for coordinator assignment |
|
||||
| Design files not found | Report error, notify coordinator |
|
||||
| Token format unparseable | Degrade to text review |
|
||||
| Audit dimension cannot be assessed | Mark as N/A, exclude from score |
|
||||
| Anti-pattern check fails | Mark Industry Compliance as N/A |
|
||||
| Context/Plan file not found | Notify coordinator, request location |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
Reference in New Issue
Block a user