mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-06 16:31:12 +08:00
feat: Add coordinator commands and role specifications for UI design team
- Implemented the 'monitor' command for coordinator role to handle monitoring events, task completion, and pipeline management. - Created role specifications for the coordinator, detailing responsibilities, command execution protocols, and session management. - Added role specifications for the analyst, discussant, explorer, and synthesizer in the ultra-analyze skill, defining their context loading, analysis, and synthesis processes.
This commit is contained in:
catlog22
@@ -1,97 +1,74 @@
|
||||
---
|
||||
name: team-frontend
|
||||
description: Unified team skill for frontend development team. All roles invoke this skill with --role arg. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), WebFetch(*), WebSearch(*)
|
||||
description: Unified team skill for frontend development. Uses team-worker agent architecture with role-spec files for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Built-in ui-ux-pro-max design intelligence. Triggers on "team frontend".
|
||||
allowed-tools: Task, TaskCreate, TaskList, TaskGet, TaskUpdate, TeamCreate, TeamDelete, SendMessage, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, mcp__ace-tool__search_context
|
||||
---
|
||||
|
||||
# Team Frontend Development
|
||||
|
||||
Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. All team members invoke with `--role=xxx` to route to role-specific execution.
|
||||
Unified team skill: frontend development with built-in ui-ux-pro-max design intelligence. Covers requirement analysis, design system generation, frontend implementation, and quality assurance. Built on **team-worker agent architecture** -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ Skill(skill="team-frontend") │
|
||||
│ args="<task-description>" or args="--role=xxx" │
|
||||
└──────────────────────────┬───────────────────────────┘
|
||||
│ Role Router
|
||||
┌──── --role present? ────┐
|
||||
│ NO │ YES
|
||||
↓ ↓
|
||||
Orchestration Mode Role Dispatch
|
||||
(auto -> coordinator) (route to role.md)
|
||||
│
|
||||
┌────┴────┬───────────┬───────────┬───────────┐
|
||||
↓ ↓ ↓ ↓ ↓
|
||||
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
|
||||
│ coord │ │analyst │ │architect│ │developer│ │ qa │
|
||||
│ │ │ANALYZE-*│ │ARCH-* │ │DEV-* │ │QA-* │
|
||||
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘
|
||||
```
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-frontend") |
|
||||
| args="<task-description>" |
|
||||
+-------------------+-------------------------------+
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
|
|
||||
Coordinator (inline)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v
|
||||
[tw] [tw] [tw] [tw]
|
||||
analyst archi- devel- qa
|
||||
tect oper
|
||||
|
||||
## Command Architecture
|
||||
|
||||
Each role is organized as a folder with a `role.md` orchestrator and optional `commands/` for delegation:
|
||||
|
||||
```
|
||||
roles/
|
||||
├── coordinator/
|
||||
│ ├── role.md
|
||||
│ └── commands/
|
||||
├── analyst/
|
||||
│ ├── role.md
|
||||
│ └── commands/
|
||||
│ └── design-intelligence.md
|
||||
├── architect/
|
||||
│ ├── role.md
|
||||
│ └── commands/
|
||||
├── developer/
|
||||
│ ├── role.md
|
||||
│ └── commands/
|
||||
└── qa/
|
||||
├── role.md
|
||||
└── commands/
|
||||
└── pre-delivery-checklist.md
|
||||
(tw) = team-worker agent
|
||||
```
|
||||
|
||||
## Role Router
|
||||
|
||||
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
|
||||
|
||||
### Input Parsing
|
||||
|
||||
Parse `$ARGUMENTS` to extract `--role`. If absent -> Orchestration Mode (auto route to coordinator).
|
||||
Parse `$ARGUMENTS`. No `--role` needed -- always routes to coordinator.
|
||||
|
||||
### Role Registry
|
||||
|
||||
| Role | File | Task Prefix | Type | Compact |
|
||||
|------|------|-------------|------|---------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | **compressed -> must re-read** |
|
||||
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | pipeline | compressed -> must re-read |
|
||||
| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | pipeline | compressed -> must re-read |
|
||||
| developer | [roles/developer/role.md](roles/developer/role.md) | DEV-* | pipeline | compressed -> must re-read |
|
||||
| qa | [roles/qa/role.md](roles/qa/role.md) | QA-* | pipeline | compressed -> must re-read |
|
||||
|
||||
> **COMPACT PROTECTION**: Role files are execution documents, not reference material. When context compression occurs and role instructions are reduced to summaries, **you MUST immediately `Read` the corresponding role.md to reload before continuing execution**. Do not execute any Phase based on summaries.
|
||||
| Role | Spec | Task Prefix | Type | Inner Loop |
|
||||
|------|------|-------------|------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | - |
|
||||
| analyst | [role-specs/analyst.md](role-specs/analyst.md) | ANALYZE-* | read_only_analysis | false |
|
||||
| architect | [role-specs/architect.md](role-specs/architect.md) | ARCH-* | code_generation | false |
|
||||
| developer | [role-specs/developer.md](role-specs/developer.md) | DEV-* | code_generation | true |
|
||||
| qa | [role-specs/qa.md](role-specs/qa.md) | QA-* | read_only_analysis | false |
|
||||
|
||||
### Dispatch
|
||||
|
||||
1. Extract `--role` from arguments
|
||||
2. If no `--role` -> route to coordinator (Orchestration Mode)
|
||||
3. Look up role in registry -> Read the role file -> Execute its phases
|
||||
Always route to coordinator. Coordinator reads `roles/coordinator/role.md` and executes its phases.
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
When invoked without `--role`, coordinator auto-starts. User just provides task description.
|
||||
User just provides task description.
|
||||
|
||||
**Invocation**: `Skill(skill="team-frontend", args="<task-description>")`
|
||||
**Invocation**:
|
||||
```bash
|
||||
Skill(skill="team-frontend", args="<task-description>")
|
||||
```
|
||||
|
||||
**Lifecycle**:
|
||||
```
|
||||
User provides task description
|
||||
-> coordinator Phase 1-3: Requirement clarification + industry identification -> TeamCreate -> Create task chain
|
||||
-> coordinator Phase 1-3: Parse requirements -> TeamCreate -> Create task chain
|
||||
-> coordinator Phase 4: spawn first batch workers (background) -> STOP
|
||||
-> Worker executes -> SendMessage callback -> coordinator advances next step
|
||||
-> Loop until pipeline complete -> Phase 5 report
|
||||
-> Worker (team-worker agent) executes -> SendMessage callback -> coordinator advances
|
||||
-> GC loop (developer <-> qa) if fix_required (max 2 rounds)
|
||||
-> All tasks complete -> Phase 5 report + completion action
|
||||
```
|
||||
|
||||
**User Commands** (wake paused coordinator):
|
||||
@@ -103,272 +80,120 @@ User provides task description
|
||||
|
||||
---
|
||||
|
||||
## Shared Infrastructure
|
||||
## Command Execution Protocol
|
||||
|
||||
The following templates apply to all worker roles. Each role.md only needs to write **Phase 2-4** role-specific logic.
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
### Worker Phase 1: Task Discovery (shared by all workers)
|
||||
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
|
||||
|
||||
Every worker executes the same task discovery flow on startup:
|
||||
|
||||
1. Call `TaskList()` to get all tasks
|
||||
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
|
||||
3. No tasks -> idle wait
|
||||
4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
|
||||
|
||||
**Resume Artifact Check** (prevent duplicate output after resume):
|
||||
- Check whether this task's output artifact already exists
|
||||
- Artifact complete -> skip to Phase 5 report completion
|
||||
- Artifact incomplete or missing -> normal Phase 2-4 execution
|
||||
|
||||
### Worker Phase 5: Report (shared by all workers)
|
||||
|
||||
Standard reporting flow after task completion:
|
||||
|
||||
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
|
||||
- Parameters: operation="log", team=**<session-id>**, from=<role>, to="coordinator", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
|
||||
- **CLI fallback**: When MCP unavailable -> `ccw team log --team <session-id> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json`
|
||||
- **Note**: `team` must be session ID (e.g., `FES-xxx-date`), NOT team name. Extract from `Session:` field in task description.
|
||||
2. **SendMessage**: Send result to coordinator (content and summary both prefixed with `[<role>]`)
|
||||
3. **TaskUpdate**: Mark task completed
|
||||
4. **Loop**: Return to Phase 1 to check next task
|
||||
|
||||
### Wisdom Accumulation (all roles)
|
||||
|
||||
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session initialization.
|
||||
|
||||
**Directory**:
|
||||
Example:
|
||||
```
|
||||
<session-folder>/wisdom/
|
||||
├── learnings.md # Patterns and insights
|
||||
├── decisions.md # Architecture and design decisions
|
||||
├── conventions.md # Codebase conventions
|
||||
└── issues.md # Known risks and issues
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
**Worker Load** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
|
||||
**Worker Contribute** (Phase 4/5): Write this task's discoveries to corresponding wisdom files.
|
||||
|
||||
### Role Isolation Rules
|
||||
|
||||
#### Output Tagging
|
||||
|
||||
All outputs must carry `[role_name]` prefix.
|
||||
|
||||
#### Coordinator Isolation
|
||||
|
||||
| Allowed | Forbidden |
|
||||
|---------|-----------|
|
||||
| Requirement clarification (AskUserQuestion) | Direct code writing/modification |
|
||||
| Create task chain (TaskCreate) | Calling implementation subagents |
|
||||
| Dispatch tasks to workers | Direct analysis/testing/review |
|
||||
| Monitor progress (message bus) | Bypassing workers |
|
||||
| Report results to user | Modifying source code |
|
||||
|
||||
#### Worker Isolation
|
||||
|
||||
| Allowed | Forbidden |
|
||||
|---------|-----------|
|
||||
| Process tasks with own prefix | Process tasks with other role prefixes |
|
||||
| SendMessage to coordinator | Communicate directly with other workers |
|
||||
| Use tools declared in Toolbox | Create tasks for other roles (TaskCreate) |
|
||||
| Delegate to commands/ files | Modify resources outside own responsibility |
|
||||
|
||||
### Message Bus (All Roles)
|
||||
|
||||
Every SendMessage **before**, must call `mcp__ccw-tools__team_msg` to log.
|
||||
|
||||
**Message types by role**:
|
||||
|
||||
| Role | Types |
|
||||
|------|-------|
|
||||
| coordinator | `task_unblocked`, `sync_checkpoint`, `fix_required`, `error`, `shutdown` |
|
||||
| analyst | `analyze_ready`, `analyze_progress`, `error` |
|
||||
| architect | `arch_ready`, `arch_revision`, `arch_progress`, `error` |
|
||||
| developer | `dev_complete`, `dev_progress`, `error` |
|
||||
| qa | `qa_passed`, `qa_result`, `fix_required`, `error` |
|
||||
|
||||
### Shared Memory
|
||||
|
||||
Cross-role accumulated knowledge stored in `shared-memory.json`:
|
||||
|
||||
| Field | Owner | Content |
|
||||
|-------|-------|---------|
|
||||
| `design_intelligence` | analyst | ui-ux-pro-max output |
|
||||
| `design_token_registry` | architect | colors, typography, spacing, shadows |
|
||||
| `component_inventory` | architect | Component specs |
|
||||
| `style_decisions` | architect | Design system decisions |
|
||||
| `qa_history` | qa | QA audit results |
|
||||
| `industry_context` | analyst | Industry-specific rules |
|
||||
|
||||
Each role reads in Phase 2, writes own fields in Phase 5.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Architecture
|
||||
|
||||
### Three Pipeline Modes
|
||||
|
||||
```
|
||||
page (single page - linear):
|
||||
ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001
|
||||
|
||||
feature (multi-component feature - with architecture review):
|
||||
ANALYZE-001 -> ARCH-001(tokens+structure) -> QA-001(architecture-review)
|
||||
-> DEV-001(components) -> QA-002(code-review)
|
||||
|
||||
system (full frontend system - dual-track parallel):
|
||||
ANALYZE-001 -> ARCH-001(tokens) -> QA-001(token-review)
|
||||
-> [ARCH-002(components) || DEV-001(tokens)](parallel, blockedBy QA-001)
|
||||
-> QA-002(component-review) -> DEV-002(components) -> QA-003(final)
|
||||
```
|
||||
|
||||
### Generator-Critic Loop (developer <-> qa)
|
||||
|
||||
Developer and qa iterate to ensure code quality and design compliance:
|
||||
|
||||
```
|
||||
┌──────────┐ DEV artifact ┌──────────┐
|
||||
│ developer│ ─────────────────────> │ qa │
|
||||
│(Generator)│ │ (Critic) │
|
||||
│ │ <───────────────────── │ │
|
||||
└──────────┘ QA feedback └──────────┘
|
||||
(max 2 rounds)
|
||||
|
||||
Convergence: qa.score >= 8 && qa.critical_count === 0
|
||||
```
|
||||
|
||||
### Consulting Pattern (developer -> analyst)
|
||||
|
||||
Developer can request design decision consultation via coordinator:
|
||||
|
||||
```
|
||||
developer -> coordinator: "Need design decision consultation"
|
||||
coordinator -> analyst: Create ANALYZE-consult task
|
||||
analyst -> coordinator: Design recommendation
|
||||
coordinator -> developer: Forward recommendation
|
||||
```
|
||||
|
||||
### Cadence Control
|
||||
|
||||
**Beat model**: Event-driven, each beat = coordinator wake -> process -> spawn -> STOP.
|
||||
|
||||
```
|
||||
Beat Cycle (single beat)
|
||||
═══════════════════════════════════════════════════════════
|
||||
Event Coordinator Workers
|
||||
───────────────────────────────────────────────────────────
|
||||
callback/resume ──> ┌─ handleCallback ─┐
|
||||
│ mark completed │
|
||||
│ check pipeline │
|
||||
├─ handleSpawnNext ─┤
|
||||
│ find ready tasks │
|
||||
│ spawn workers ───┼──> [Worker A] Phase 1-5
|
||||
│ (parallel OK) ──┼──> [Worker B] Phase 1-5
|
||||
└─ STOP (idle) ─────┘ │
|
||||
│
|
||||
callback <─────────────────────────────────────────┘
|
||||
(next beat) SendMessage + TaskUpdate(completed)
|
||||
═══════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
**Pipeline beat view**:
|
||||
|
||||
```
|
||||
Page mode (4 beats, strictly serial)
|
||||
──────────────────────────────────────────────────────────
|
||||
Beat 1 2 3 4
|
||||
│ │ │ │
|
||||
ANALYZE -> ARCH -> DEV -> QA
|
||||
▲ ▲
|
||||
pipeline pipeline
|
||||
start done
|
||||
|
||||
A=ANALYZE ARCH=architect D=DEV Q=QA
|
||||
|
||||
Feature mode (5 beats, with architecture review gate)
|
||||
──────────────────────────────────────────────────────────
|
||||
Beat 1 2 3 4 5
|
||||
│ │ │ │ │
|
||||
ANALYZE -> ARCH -> QA-1 -> DEV -> QA-2
|
||||
▲ ▲
|
||||
arch review code review
|
||||
|
||||
System mode (7 beats, dual-track parallel)
|
||||
──────────────────────────────────────────────────────────
|
||||
Beat 1 2 3 4 5 6 7
|
||||
│ │ │ ┌────┴────┐ │ │ │
|
||||
ANALYZE -> ARCH-1 -> QA-1 -> ARCH-2 || DEV-1 -> QA-2 -> DEV-2 -> QA-3
|
||||
▲ ▲
|
||||
parallel window final check
|
||||
```
|
||||
|
||||
**Checkpoints**:
|
||||
|
||||
| Trigger | Location | Behavior |
|
||||
|---------|----------|----------|
|
||||
| Architecture review gate | QA-001 (arch review) complete | Pause if critical issues, wait for architect revision |
|
||||
| GC loop limit | developer <-> qa max 2 rounds | Exceed rounds -> stop iteration, report current state |
|
||||
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
|
||||
|
||||
**Stall Detection** (coordinator `handleCheck` executes):
|
||||
|
||||
| Check | Condition | Resolution |
|
||||
|-------|-----------|------------|
|
||||
| Worker no response | in_progress task no callback | Report waiting task list, suggest user `resume` |
|
||||
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy dependency chain, report blocking point |
|
||||
| GC loop exceeded | DEV/QA iteration > max_rounds | Terminate loop, output latest QA report |
|
||||
|
||||
### Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Phase | Dependencies | Description |
|
||||
|---------|------|-------|-------------|-------------|
|
||||
| ANALYZE-001 | analyst | analysis | (none) | Requirement analysis + design intelligence via ui-ux-pro-max |
|
||||
| ARCH-001 | architect | design | ANALYZE-001 | Design token system + component architecture |
|
||||
| ARCH-002 | architect | design | QA-001 (system mode) | Component specs refinement |
|
||||
| DEV-001 | developer | impl | ARCH-001 or QA-001 | Frontend component/page implementation |
|
||||
| DEV-002 | developer | impl | QA-002 (system mode) | Component implementation from refined specs |
|
||||
| QA-001 | qa | review | ARCH-001 or DEV-001 | Architecture review or code review |
|
||||
| QA-002 | qa | review | DEV-001 | Code review (feature/system mode) |
|
||||
| QA-003 | qa | review | DEV-002 (system mode) | Final quality check |
|
||||
|
||||
---
|
||||
|
||||
## 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: <team-name>,
|
||||
team_name: "frontend",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `You are team "<team-name>" <ROLE>.
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-frontend/role-specs/<role>.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: frontend
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
## Primary Directive
|
||||
All your work must be executed through Skill to load role definition:
|
||||
Skill(skill="team-frontend", args="--role=<role>")
|
||||
|
||||
Current requirement: <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).`
|
||||
})
|
||||
```
|
||||
|
||||
**Inner Loop roles** (developer): Set `inner_loop: true`. The team-worker agent handles the loop internally.
|
||||
|
||||
**Single-task roles** (analyst, architect, qa): Set `inner_loop: false`.
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Definitions
|
||||
|
||||
### Pipeline Diagrams
|
||||
|
||||
**Page Mode** (4 beats, linear):
|
||||
```
|
||||
Pipeline: Page (Linear)
|
||||
=====================================================
|
||||
Stage 1 Stage 2 Stage 3 Stage 4
|
||||
ANALYZE-001 --> ARCH-001 --> DEV-001 --> QA-001
|
||||
[analyst] [architect] [developer] [qa]
|
||||
```
|
||||
|
||||
**Feature Mode** (5 beats, with architecture review gate):
|
||||
```
|
||||
Pipeline: Feature (Architecture Review Gate)
|
||||
=====================================================
|
||||
Stage 1 Stage 2 Stage 3 Stage 4 Stage 5
|
||||
ANALYZE-001 --> ARCH-001 --> QA-001 --> DEV-001 --> QA-002
|
||||
[analyst] [architect] [qa:arch-rev] [developer] [qa:code-rev]
|
||||
```
|
||||
|
||||
**System Mode** (7 beats, dual-track parallel):
|
||||
```
|
||||
Pipeline: System (Dual-Track Parallel)
|
||||
=====================================================
|
||||
Stage 1 Stage 2 Stage 3 Stage 4 (parallel) Stage 5 Stage 6 Stage 7
|
||||
ANALYZE-001 --> ARCH-001 --> QA-001 --> ARCH-002 ─┐ --> QA-002 --> DEV-002 --> QA-003
|
||||
[analyst] [architect] [qa:arch-rev] [architect] | [qa] [developer] [qa:final]
|
||||
DEV-001 ──┘
|
||||
[developer:tokens]
|
||||
```
|
||||
|
||||
### Generator-Critic Loop (developer <-> qa)
|
||||
|
||||
```
|
||||
developer (Generator) -> QA artifact -> qa (Critic)
|
||||
<- QA feedback <-
|
||||
(max 2 rounds)
|
||||
|
||||
Convergence: qa.score >= 8 && qa.critical_count === 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Stage | Dependencies | Description |
|
||||
|---------|------|-------|-------------|-------------|
|
||||
| ANALYZE-001 | analyst | analysis | (none) | Requirement analysis + design intelligence |
|
||||
| ARCH-001 | architect | design | ANALYZE-001 | Design token system + component architecture |
|
||||
| ARCH-002 | architect | design | QA-001 (system) | Component specs refinement |
|
||||
| DEV-001 | developer | impl | ARCH-001 or QA-001 | Frontend implementation |
|
||||
| DEV-002 | developer | impl | QA-002 (system) | Component implementation |
|
||||
| QA-001 | qa | review | ARCH-001 or DEV-001 | Architecture or code review |
|
||||
| QA-002 | qa | review | DEV-001 | Code review |
|
||||
| QA-003 | qa | review | DEV-002 (system) | Final quality check |
|
||||
|
||||
---
|
||||
|
||||
## ui-ux-pro-max Integration
|
||||
|
||||
### Design Intelligence Engine
|
||||
@@ -377,50 +202,100 @@ Analyst role invokes ui-ux-pro-max via Skill to obtain industry design intellige
|
||||
|
||||
| Action | Invocation |
|
||||
|--------|------------|
|
||||
| Full design system recommendation | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
|
||||
| Domain search (UX, typography, color) | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
|
||||
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
|
||||
| Domain search | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
|
||||
| Tech stack guidance | `Skill(skill="ui-ux-pro-max", args="<query> --stack <stack>")` |
|
||||
| Persist design system (cross-session) | `Skill(skill="ui-ux-pro-max", args="<query> --design-system --persist -p <projectName>")` |
|
||||
|
||||
**Supported Domains**: product, style, typography, color, landing, chart, ux, web
|
||||
**Supported Stacks**: html-tailwind, react, nextjs, vue, svelte, shadcn, swiftui, react-native, flutter
|
||||
|
||||
**Fallback**: If ui-ux-pro-max skill not installed, degrade to LLM general design knowledge. Suggest installation: `/plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
|
||||
|
||||
---
|
||||
|
||||
## Completion Action
|
||||
|
||||
At Phase 5, coordinator offers interactive completion:
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Team pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)" },
|
||||
{ label: "Keep Active" },
|
||||
{ label: "Export Results" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
| Choice | Steps |
|
||||
|--------|-------|
|
||||
| Archive & Clean | Verify completed -> update status -> TeamDelete("frontend") -> final summary |
|
||||
| Keep Active | Status="paused" -> "Resume with: Skill(skill='team-frontend', args='resume')" |
|
||||
| Export Results | Ask target dir -> copy artifacts -> Archive flow |
|
||||
|
||||
---
|
||||
|
||||
## Message Bus
|
||||
|
||||
Every SendMessage must be preceded by `mcp__ccw-tools__team_msg` log:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: <role>,
|
||||
type: <message-type>,
|
||||
data: {ref: <artifact-path>}
|
||||
})
|
||||
```
|
||||
|
||||
`to` and `summary` auto-defaulted -- do NOT specify explicitly.
|
||||
|
||||
**CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
|
||||
|
||||
**Message types by role**:
|
||||
|
||||
| Role | Types |
|
||||
|------|-------|
|
||||
| coordinator | `task_unblocked`, `sync_checkpoint`, `fix_required`, `error`, `shutdown` |
|
||||
| analyst | `analyze_ready`, `error` |
|
||||
| architect | `arch_ready`, `arch_revision`, `error` |
|
||||
| developer | `dev_complete`, `dev_progress`, `error` |
|
||||
| qa | `qa_passed`, `qa_result`, `fix_required`, `error` |
|
||||
|
||||
---
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/FE-<slug>-<YYYY-MM-DD>/
|
||||
├── team-session.json # Session state
|
||||
├── shared-memory.json # Cross-role accumulated knowledge
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Message bus log
|
||||
│ └── meta.json # Session state + cross-role state
|
||||
├── wisdom/ # Cross-task knowledge
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── analysis/ # Analyst output
|
||||
│ ├── design-intelligence.json
|
||||
│ └── requirements.md
|
||||
├── architecture/ # Architect output
|
||||
│ ├── design-tokens.json
|
||||
│ ├── component-specs/
|
||||
│ │ └── <component-name>.md
|
||||
│ └── project-structure.md
|
||||
├── qa/ # QA output
|
||||
│ └── audit-<NNN>.md
|
||||
└── build/ # Developer output
|
||||
├── token-files/
|
||||
└── component-files/
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown --role value | Error with available role list |
|
||||
| Missing --role arg | Orchestration Mode -> auto route to coordinator |
|
||||
| Role file not found | Error with expected path (roles/<name>/role.md) |
|
||||
| QA score < 6 over 2 GC rounds | Coordinator reports to user |
|
||||
| Dual-track sync failure | Fallback to single-track sequential execution |
|
||||
| ui-ux-pro-max skill not installed | Degrade to LLM general design knowledge, show install command |
|
||||
| DEV cannot find design files | Wait for sync point or escalate to coordinator |
|
||||
| Unknown command | Error with available command list |
|
||||
| QA score < 6 over 2 GC rounds | Escalate to user |
|
||||
| Dual-track sync failure (system mode) | Fallback to single-track sequential |
|
||||
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |
|
||||
| Worker no response | Report waiting task, suggest user `resume` |
|
||||
| Pipeline deadlock | Check blockedBy chain, report blocking point |
|
||||
|
||||
92
.claude/skills/team-frontend/role-specs/analyst.md
Normal file
92
.claude/skills/team-frontend/role-specs/analyst.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
prefix: ANALYZE
|
||||
inner_loop: false
|
||||
subagents: []
|
||||
message_types:
|
||||
success: analyze_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# Requirements Analyst
|
||||
|
||||
Analyze frontend requirements and retrieve industry design intelligence via ui-ux-pro-max skill. Produce design-intelligence.json and requirements.md for downstream consumption by architect and developer roles.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Industry context | Extracted from task description | Yes |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path, industry type, and tech stack from task description
|
||||
2. Detect existing design system:
|
||||
|
||||
| Signal | Detection Method |
|
||||
|--------|-----------------|
|
||||
| Token files | Glob `**/*token*.*` |
|
||||
| CSS files | Glob `**/*.css` |
|
||||
| Package.json | Read for framework dependencies |
|
||||
|
||||
3. Detect tech stack from package.json:
|
||||
|
||||
| Dependency | Stack |
|
||||
|------------|-------|
|
||||
| `next` | nextjs |
|
||||
| `react` | react |
|
||||
| `vue` | vue |
|
||||
| `svelte` | svelte |
|
||||
| `@shadcn/ui` | shadcn |
|
||||
| (none) | html-tailwind |
|
||||
|
||||
4. Load .msg/meta.json for shared state
|
||||
|
||||
## Phase 3: Design Intelligence Retrieval
|
||||
|
||||
Retrieve design intelligence via ui-ux-pro-max skill integration.
|
||||
|
||||
**Step 1: Invoke ui-ux-pro-max** (primary path):
|
||||
|
||||
| Action | Invocation |
|
||||
|--------|------------|
|
||||
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
|
||||
| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
|
||||
| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
|
||||
|
||||
**Step 2: Fallback** (if skill unavailable):
|
||||
- Generate design recommendations from LLM general knowledge
|
||||
- Log warning: `ui-ux-pro-max not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
|
||||
|
||||
**Step 3: Analyze existing codebase** (if token/CSS files found):
|
||||
- Explore existing design patterns (color palette, typography scale, spacing, component patterns)
|
||||
|
||||
**Step 4: Competitive reference** (optional, if industry is not "Other"):
|
||||
- `WebSearch({ query: "<industry> web design trends best practices" })`
|
||||
|
||||
**Step 5: Compile design-intelligence.json**:
|
||||
|
||||
| Field | Source |
|
||||
|-------|--------|
|
||||
| `_source` | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
|
||||
| `industry` | Task description |
|
||||
| `detected_stack` | Phase 2 detection |
|
||||
| `design_system` | Skill output (colors, typography, effects) |
|
||||
| `ux_guidelines` | Skill UX domain output |
|
||||
| `stack_guidelines` | Skill stack output |
|
||||
| `recommendations` | Synthesized: style, anti-patterns, must-have |
|
||||
|
||||
**Output files**:
|
||||
- `<session>/analysis/design-intelligence.json`
|
||||
- `<session>/analysis/requirements.md`
|
||||
|
||||
## Phase 4: Self-Review
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| JSON validity | Parse design-intelligence.json | No parse errors |
|
||||
| Required fields | Check _source, industry, design_system | All present |
|
||||
| Anti-patterns populated | Check recommendations.anti_patterns | Non-empty array |
|
||||
| Requirements doc exists | File check | requirements.md written |
|
||||
|
||||
Update .msg/meta.json: merge `design_intelligence` and `industry_context` keys.
|
||||
86
.claude/skills/team-frontend/role-specs/architect.md
Normal file
86
.claude/skills/team-frontend/role-specs/architect.md
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
prefix: ARCH
|
||||
inner_loop: false
|
||||
subagents: []
|
||||
message_types:
|
||||
success: arch_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# Frontend Architect
|
||||
|
||||
Consume design-intelligence.json to define design token system, component architecture, and project structure. Token values prioritize ui-ux-pro-max recommendations. Produce architecture artifacts for developer consumption.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
|
||||
| Design intelligence | <session>/analysis/design-intelligence.json | Yes |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path and scope from task description
|
||||
2. Load design intelligence from analyst output
|
||||
3. Load .msg/meta.json for shared state (industry_context, design_intelligence)
|
||||
4. Detect existing project structure via Glob `src/**/*`
|
||||
|
||||
**Fail-safe**: If design-intelligence.json not found, use default token values and log warning.
|
||||
|
||||
## Phase 3: Architecture Design
|
||||
|
||||
**Scope selection**:
|
||||
|
||||
| Scope | Output |
|
||||
|-------|--------|
|
||||
| `tokens` | Design token system only |
|
||||
| `components` | Component specs only |
|
||||
| `full` | Both tokens and components + project structure |
|
||||
|
||||
**Step 1: Design Token System** (scope: tokens or full):
|
||||
|
||||
Generate `<session>/architecture/design-tokens.json` with categories:
|
||||
|
||||
| Category | Content | Source |
|
||||
|----------|---------|--------|
|
||||
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max |
|
||||
| `typography` | Font families, font sizes (scale) | ui-ux-pro-max |
|
||||
| `spacing` | xs through 2xl | Standard scale |
|
||||
| `border-radius` | sm, md, lg, full | Standard scale |
|
||||
| `shadow` | sm, md, lg | Standard elevation |
|
||||
| `transition` | fast, normal, slow | Standard durations |
|
||||
|
||||
Use `$type` + `$value` format (Design Tokens Community Group). Support light/dark mode via nested values.
|
||||
|
||||
**Step 2: Component Architecture** (scope: components or full):
|
||||
|
||||
Generate component specs in `<session>/architecture/component-specs/`:
|
||||
- Design reference (style, stack)
|
||||
- Props table (name, type, default, description)
|
||||
- Variants table
|
||||
- Accessibility requirements (role, keyboard, ARIA, contrast)
|
||||
- Anti-patterns to avoid (from design intelligence)
|
||||
|
||||
**Step 3: Project Structure** (scope: full):
|
||||
|
||||
Generate `<session>/architecture/project-structure.md` with stack-specific layout:
|
||||
|
||||
| Stack | Key Directories |
|
||||
|-------|----------------|
|
||||
| react | src/components/, src/pages/, src/hooks/, src/styles/ |
|
||||
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/ |
|
||||
| vue | src/components/, src/views/, src/composables/, src/styles/ |
|
||||
| html-tailwind | src/components/, src/pages/, src/styles/ |
|
||||
|
||||
## Phase 4: Self-Review
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| JSON validity | Parse design-tokens.json | No errors |
|
||||
| Required categories | Check color, typography, spacing | All present |
|
||||
| Anti-pattern compliance | Token values vs anti-patterns | No violations |
|
||||
| Component specs complete | Each has props + accessibility | All complete |
|
||||
| File existence | Verify all planned files | All present |
|
||||
|
||||
Update .msg/meta.json: merge `design_token_registry` and `component_inventory` keys.
|
||||
93
.claude/skills/team-frontend/role-specs/developer.md
Normal file
93
.claude/skills/team-frontend/role-specs/developer.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
prefix: DEV
|
||||
inner_loop: true
|
||||
subagents: []
|
||||
message_types:
|
||||
success: dev_complete
|
||||
error: error
|
||||
---
|
||||
|
||||
# Frontend Developer
|
||||
|
||||
Consume architecture artifacts (design tokens, component specs, project structure) to implement frontend code. Reference design-intelligence.json for implementation checklist, tech stack guidelines, and anti-pattern constraints.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Scope | Extracted from task description (tokens/components/full) | No (default: full) |
|
||||
| Design intelligence | <session>/analysis/design-intelligence.json | No |
|
||||
| Design tokens | <session>/architecture/design-tokens.json | Yes |
|
||||
| Component specs | <session>/architecture/component-specs/*.md | No |
|
||||
| Project structure | <session>/architecture/project-structure.md | No |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path and scope from task description
|
||||
2. Load design tokens (required -- if missing, report to coordinator)
|
||||
3. Load design intelligence for anti-patterns and guidelines
|
||||
4. Load component specs and project structure
|
||||
5. Detect tech stack from design intelligence `detected_stack`
|
||||
6. Load .msg/meta.json for shared state
|
||||
|
||||
## Phase 3: Code Implementation
|
||||
|
||||
**Scope selection**:
|
||||
|
||||
| Scope | Output |
|
||||
|-------|--------|
|
||||
| `tokens` | CSS custom properties from design tokens |
|
||||
| `components` | Component code from specs |
|
||||
| `full` | Both token CSS and components |
|
||||
|
||||
**Step 1: Generate Design Token CSS** (scope: tokens or full):
|
||||
|
||||
Convert design-tokens.json to `src/styles/tokens.css`:
|
||||
|
||||
| JSON Category | CSS Variable Prefix |
|
||||
|---------------|---------------------|
|
||||
| color | `--color-` |
|
||||
| typography.font-family | `--font-` |
|
||||
| typography.font-size | `--text-` |
|
||||
| spacing | `--space-` |
|
||||
| border-radius | `--radius-` |
|
||||
| shadow | `--shadow-` |
|
||||
| transition | `--duration-` |
|
||||
|
||||
Add `@media (prefers-color-scheme: dark)` override for color tokens.
|
||||
|
||||
**Step 2: Implement Components** (scope: components or full):
|
||||
|
||||
Implementation strategy by complexity:
|
||||
|
||||
| Condition | Strategy |
|
||||
|-----------|----------|
|
||||
| <= 2 components | Direct inline Edit/Write |
|
||||
| 3-5 components | Single batch implementation |
|
||||
| > 5 components | Group by module, implement per batch |
|
||||
|
||||
**Coding standards** (mandatory):
|
||||
- Use design token CSS variables -- never hardcode colors/spacing
|
||||
- All interactive elements: `cursor: pointer`
|
||||
- Transitions: 150-300ms via `var(--duration-normal)`
|
||||
- Text contrast: minimum 4.5:1 ratio
|
||||
- Include `focus-visible` styles for keyboard navigation
|
||||
- Support `prefers-reduced-motion`
|
||||
- Responsive: mobile-first with md/lg breakpoints
|
||||
- No emoji as functional icons
|
||||
|
||||
## Phase 4: Self-Review
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Hardcoded colors | Scan for hex codes outside tokens.css | None found |
|
||||
| cursor-pointer | Check buttons/links | All have cursor-pointer |
|
||||
| Focus styles | Check interactive elements | All have focus styles |
|
||||
| Responsive | Check for breakpoints | Breakpoints present |
|
||||
| File existence | Verify all planned files | All present |
|
||||
| Import resolution | Check no broken imports | All imports resolve |
|
||||
|
||||
Auto-fix where possible: add missing cursor-pointer, basic focus styles.
|
||||
|
||||
Update .msg/meta.json: merge `component_inventory` key with implemented file list.
|
||||
79
.claude/skills/team-frontend/role-specs/qa.md
Normal file
79
.claude/skills/team-frontend/role-specs/qa.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
prefix: QA
|
||||
inner_loop: false
|
||||
subagents: []
|
||||
message_types:
|
||||
success: qa_passed
|
||||
error: error
|
||||
---
|
||||
|
||||
# QA Engineer
|
||||
|
||||
Execute 5-dimension quality audit integrating ux-guidelines Do/Don't rules, pre-delivery checklist, and industry anti-pattern library. Perform CSS-level precise review on architecture artifacts and implementation code.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Review type | Extracted from task description | No (default: code-review) |
|
||||
| Design intelligence | <session>/analysis/design-intelligence.json | No |
|
||||
| Design tokens | <session>/architecture/design-tokens.json | No |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path and review type from task description
|
||||
2. Load design intelligence (for anti-patterns, must-have rules)
|
||||
3. Load design tokens (for compliance checks)
|
||||
4. Load .msg/meta.json (for industry context, strictness level)
|
||||
5. Collect files to review based on review type:
|
||||
|
||||
| Type | Files to Review |
|
||||
|------|-----------------|
|
||||
| architecture-review | `<session>/architecture/**/*` |
|
||||
| token-review | `<session>/architecture/**/*` |
|
||||
| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
||||
| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
||||
|
||||
## Phase 3: 5-Dimension Audit
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Code Quality | 0.20 | Structure, naming, maintainability |
|
||||
| Accessibility | 0.25 | WCAG compliance, keyboard nav, screen reader |
|
||||
| Design Compliance | 0.20 | Anti-pattern check, design token usage |
|
||||
| UX Best Practices | 0.20 | Interaction patterns, responsive, animations |
|
||||
| Pre-Delivery | 0.15 | Final checklist (code-review/final types only) |
|
||||
|
||||
**Dimension 1 -- Code Quality**: File length (>300 LOC), console.log, empty catch, unused imports.
|
||||
|
||||
**Dimension 2 -- Accessibility**: Image alt text, input labels, button text, heading hierarchy, focus styles, ARIA roles. Strict mode (medical/financial): prefers-reduced-motion required.
|
||||
|
||||
**Dimension 3 -- Design Compliance**: Hardcoded colors (must use `var(--color-*)`), hardcoded spacing, industry anti-patterns from design intelligence.
|
||||
|
||||
**Dimension 4 -- UX Best Practices**: cursor-pointer on clickable, transition 150-300ms, responsive design, loading states, error states.
|
||||
|
||||
**Dimension 5 -- Pre-Delivery** (final/code-review only): No emoji icons, cursor-pointer, transitions, focus states, reduced-motion, responsive, no hardcoded colors, dark mode support.
|
||||
|
||||
**Score calculation**: `score = sum(dimension_score * weight)`
|
||||
|
||||
**Verdict**:
|
||||
|
||||
| Condition | Verdict | Message Type |
|
||||
|-----------|---------|-------------|
|
||||
| score >= 8 AND critical == 0 | PASSED | `qa_passed` |
|
||||
| score >= 6 AND critical == 0 | PASSED_WITH_WARNINGS | `qa_result` |
|
||||
| score < 6 OR critical > 0 | FIX_REQUIRED | `fix_required` |
|
||||
|
||||
## Phase 4: Self-Review
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| All dimensions scored | Check 5 dimension scores | All present |
|
||||
| Audit report written | File check | audit-NNN.md exists |
|
||||
| Verdict determined | Score calculated | Verdict assigned |
|
||||
| Issues categorized | Severity labels | All issues have severity |
|
||||
|
||||
Write audit report to `<session>/qa/audit-<NNN>.md` with: summary, dimension scores, issues by severity, passed dimensions.
|
||||
|
||||
Update .msg/meta.json: append to `qa_history` array.
|
||||
@@ -1,150 +0,0 @@
|
||||
# Command: design-intelligence
|
||||
|
||||
> 通过 Skill 调用 ui-ux-pro-max 获取行业设计智能，生成 design-intelligence.json。
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of analyst role: Core design intelligence retrieval
|
||||
- ui-ux-pro-max skill 已安装
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Skill invocation
|
||||
**Skill**: `ui-ux-pro-max`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1: 调用 ui-ux-pro-max 生成设计系统
|
||||
|
||||
analyst 在 subagent 中通过 Skill 调用 ui-ux-pro-max，获取完整设计系统推荐：
|
||||
|
||||
```javascript
|
||||
// 核心调用：生成完整设计系统
|
||||
// ui-ux-pro-max 的 Step 2 会自动执行 search.py --design-system
|
||||
Task({
|
||||
subagent_type: "general-purpose",
|
||||
run_in_background: false,
|
||||
description: "Retrieve design intelligence via ui-ux-pro-max skill",
|
||||
prompt: `调用 ui-ux-pro-max skill 获取设计系统推荐。
|
||||
|
||||
## 需求
|
||||
- 产品类型/行业: ${industry}
|
||||
- 关键词: ${keywords}
|
||||
- 技术栈: ${detectedStack}
|
||||
|
||||
## 执行步骤
|
||||
|
||||
### 1. 生成设计系统（必须）
|
||||
Skill(skill="ui-ux-pro-max", args="${industry} ${keywords} --design-system")
|
||||
|
||||
### 2. 补充 UX 指南
|
||||
Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")
|
||||
|
||||
### 3. 获取技术栈指南
|
||||
Skill(skill="ui-ux-pro-max", args="${keywords} --stack ${detectedStack}")
|
||||
|
||||
## 输出
|
||||
将所有结果整合写入: ${sessionFolder}/analysis/design-intelligence-raw.md
|
||||
|
||||
包含:
|
||||
- 设计系统推荐（pattern, style, colors, typography, effects, anti-patterns）
|
||||
- UX 最佳实践
|
||||
- 技术栈指南
|
||||
- 行业反模式列表
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
### Step 2: 解析 Skill 输出
|
||||
|
||||
```javascript
|
||||
// 读取 ui-ux-pro-max 的原始输出
|
||||
let rawOutput = ''
|
||||
try {
|
||||
rawOutput = Read(`${sessionFolder}/analysis/design-intelligence-raw.md`)
|
||||
} catch {}
|
||||
|
||||
// 解析为结构化 design-intelligence.json
|
||||
const designIntelligence = {
|
||||
_source: "ui-ux-pro-max-skill",
|
||||
_generated_at: new Date().toISOString(),
|
||||
industry: industry,
|
||||
detected_stack: detectedStack,
|
||||
design_system: parseDesignSystem(rawOutput),
|
||||
ux_guidelines: parseUxGuidelines(rawOutput),
|
||||
stack_guidelines: parseStackGuidelines(rawOutput),
|
||||
recommendations: {
|
||||
style: null,
|
||||
color_palette: null,
|
||||
typography: null,
|
||||
anti_patterns: parseAntiPatterns(rawOutput),
|
||||
must_have: industryConfig?.mustHave || []
|
||||
}
|
||||
}
|
||||
|
||||
Write(`${sessionFolder}/analysis/design-intelligence.json`, JSON.stringify(designIntelligence, null, 2))
|
||||
```
|
||||
|
||||
### Step 3: Fallback
|
||||
|
||||
```javascript
|
||||
// 若 ui-ux-pro-max skill 不可用（未安装），降级为 LLM 通用设计知识
|
||||
// analyst 在 Phase 3 中直接基于 LLM 知识生成设计推荐
|
||||
if (!skillAvailable) {
|
||||
return {
|
||||
_source: "llm-general-knowledge",
|
||||
_fallback: true,
|
||||
note: "ui-ux-pro-max skill not installed. Install via: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Skill 调用参考
|
||||
|
||||
ui-ux-pro-max 支持的调用方式：
|
||||
|
||||
| 用途 | 调用 |
|
||||
|------|------|
|
||||
| 完整设计系统 | `Skill(skill="ui-ux-pro-max", args="<query> --design-system")` |
|
||||
| 持久化设计系统 | `Skill(skill="ui-ux-pro-max", args="<query> --design-system --persist -p <name>")` |
|
||||
| 领域搜索 | `Skill(skill="ui-ux-pro-max", args="<query> --domain <domain>")` |
|
||||
| 技术栈指南 | `Skill(skill="ui-ux-pro-max", args="<query> --stack <stack>")` |
|
||||
|
||||
可用领域: product, style, typography, color, landing, chart, ux, web
|
||||
可用技术栈: html-tailwind, react, nextjs, vue, svelte, shadcn, swiftui, react-native, flutter
|
||||
|
||||
## Output Format
|
||||
|
||||
```json
|
||||
{
|
||||
"_source": "ui-ux-pro-max-skill",
|
||||
"design_system": {
|
||||
"pattern": "...",
|
||||
"style": "...",
|
||||
"colors": { "primary": "...", "secondary": "...", "cta": "..." },
|
||||
"typography": { "heading": "...", "body": "..." },
|
||||
"effects": "...",
|
||||
"anti_patterns": []
|
||||
},
|
||||
"ux_guidelines": [],
|
||||
"stack_guidelines": {},
|
||||
"recommendations": {
|
||||
"style": null,
|
||||
"color_palette": null,
|
||||
"typography": null,
|
||||
"anti_patterns": [],
|
||||
"must_have": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| ui-ux-pro-max skill not installed | Fallback to LLM general knowledge, suggest install command |
|
||||
| Skill execution error | Retry once, then fallback |
|
||||
| Partial output | Use available data, fill gaps with defaults |
|
||||
| Timeout | Use partial results, log warning |
|
||||
@@ -1,225 +0,0 @@
|
||||
# Analyst Role
|
||||
|
||||
Requirements analyst. Invokes ui-ux-pro-max search engine to retrieve industry design intelligence, analyzes requirements, matches industry inference rules, generates design-intelligence.json for downstream consumption.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `analyst` | **Tag**: `[analyst]`
|
||||
- **Task Prefix**: `ANALYZE-*`
|
||||
- **Responsibility**: Read-only analysis + design intelligence retrieval
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `ANALYZE-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[analyst]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within requirement analysis and design intelligence scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope (architecture, implementation, QA)
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify source code files
|
||||
- Omit `[analyst]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
| `design-intelligence` | [commands/design-intelligence.md](commands/design-intelligence.md) | Phase 3 | ui-ux-pro-max integration for design system retrieval |
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `Read` | builtin | Phase 2 | Load session files, shared memory |
|
||||
| `Glob` | builtin | Phase 2 | Detect existing token files, CSS files |
|
||||
| `Grep` | builtin | Phase 2 | Search codebase patterns |
|
||||
| `Bash` | builtin | Phase 3 | Call ui-ux-pro-max search.py |
|
||||
| `WebSearch` | builtin | Phase 3 | Competitive reference, design trends |
|
||||
| `Task(cli-explore-agent)` | subagent | Phase 3 | Deep codebase exploration |
|
||||
| `Skill(ui-ux-pro-max)` | skill | Phase 3 | Design intelligence retrieval |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `analyze_ready` | analyst → coordinator | Analysis complete | Design intelligence ready for downstream consumption |
|
||||
| `analyze_progress` | analyst → coordinator | Partial progress | Analysis progress update |
|
||||
| `error` | analyst → coordinator | Analysis failure | Analysis failed or tool unavailable |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: **<session-id>**, // MUST be session ID (e.g., FES-xxx-date), NOT team name. Extract from Session: field.
|
||||
from: "analyst",
|
||||
to: "coordinator",
|
||||
type: <message-type>,
|
||||
summary: "[analyst] ANALYZE complete: <task-subject>",
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <session-id> --from analyst --to coordinator --type <message-type> --summary \"[analyst] ...\" --ref <artifact-path> --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 `ANALYZE-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
**Input Sources**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Extract from task description `Session: <path>` | Yes |
|
||||
| Industry context | Extract from task description `Industry: <type>` | Yes |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
| Session info | `<session-folder>/team-session.json` | No |
|
||||
| Existing tokens | Glob `**/*token*.*` | No |
|
||||
| Existing CSS | Glob `**/*.css` | No |
|
||||
| Package.json | For tech stack detection | No |
|
||||
|
||||
**Loading Steps**:
|
||||
|
||||
1. Extract session folder from task description
|
||||
2. Extract industry context from task description
|
||||
3. Load shared memory and session info
|
||||
4. Detect existing design system in project
|
||||
5. Detect tech stack from package.json
|
||||
|
||||
**Tech Stack Detection**:
|
||||
|
||||
| Detection | Stack |
|
||||
|-----------|-------|
|
||||
| `next` in dependencies | nextjs |
|
||||
| `react` in dependencies | react |
|
||||
| `vue` in dependencies | vue |
|
||||
| `svelte` in dependencies | svelte |
|
||||
| `@shadcn/ui` in dependencies | shadcn |
|
||||
| No package.json | html-tailwind |
|
||||
|
||||
### Phase 3: Core Analysis - Design Intelligence Retrieval
|
||||
|
||||
Key integration point with ui-ux-pro-max. Retrieve design intelligence via Skill.
|
||||
|
||||
**Execution Strategy**:
|
||||
|
||||
| Condition | Strategy |
|
||||
|-----------|----------|
|
||||
| ui-ux-pro-max skill available | Full design system retrieval via Skill |
|
||||
| ui-ux-pro-max not installed | Fallback to LLM general knowledge |
|
||||
|
||||
**Step 1: Invoke ui-ux-pro-max via Skill**
|
||||
|
||||
Delegate to `commands/design-intelligence.md` for detailed execution.
|
||||
|
||||
**Skill Invocations**:
|
||||
|
||||
| Action | Invocation |
|
||||
|--------|------------|
|
||||
| Full design system | `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` |
|
||||
| UX guidelines | `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` |
|
||||
| Tech stack guide | `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` |
|
||||
|
||||
**Step 2: Fallback - LLM General Knowledge**
|
||||
|
||||
If ui-ux-pro-max skill not available (not installed or execution failed):
|
||||
- Generate design recommendations from LLM general knowledge
|
||||
- Quality is lower than data-driven recommendations from ui-ux-pro-max
|
||||
- Suggest installation: `/plugin install ui-ux-pro-max@ui-ux-pro-max-skill`
|
||||
|
||||
**Step 3: Analyze Existing Codebase**
|
||||
|
||||
If existing token files or CSS files found:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: "Explore existing design system",
|
||||
prompt: "Analyze existing design system: <token-files>, <css-files>. Find: color palette, typography scale, spacing system, component patterns. Output as JSON."
|
||||
})
|
||||
```
|
||||
|
||||
**Step 4: Competitive Reference** (optional)
|
||||
|
||||
If industry is not "Other":
|
||||
- Quick web search for design inspiration
|
||||
- `WebSearch({ query: "<industry> web design trends 2025 best practices" })`
|
||||
|
||||
### Phase 4: Synthesis and Output
|
||||
|
||||
**Compile Design Intelligence**:
|
||||
|
||||
Generate `design-intelligence.json` with:
|
||||
|
||||
| Field | Source | Description |
|
||||
|-------|--------|-------------|
|
||||
| `_source` | Execution | "ui-ux-pro-max-skill" or "llm-general-knowledge" |
|
||||
| `industry` | Task | Industry context |
|
||||
| `detected_stack` | Phase 2 | Tech stack detection result |
|
||||
| `design_system` | Skill/fallback | Colors, typography, style |
|
||||
| `ux_guidelines` | Skill | UX best practices |
|
||||
| `stack_guidelines` | Skill | Tech-specific guidance |
|
||||
| `existing_patterns` | Phase 3 | Codebase analysis results |
|
||||
| `recommendations` | Synthesis | Style, colors, anti-patterns, must-have |
|
||||
|
||||
**Output Files**:
|
||||
|
||||
1. **design-intelligence.json**: Structured data for downstream consumption
|
||||
2. **requirements.md**: Human-readable requirements summary
|
||||
|
||||
**Update Shared Memory**:
|
||||
- Write `design_intelligence` field
|
||||
- Write `industry_context` field
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[analyst]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Report Content**:
|
||||
- Task subject and status
|
||||
- Design intelligence source (ui-ux-pro-max or LLM fallback)
|
||||
- Industry and detected stack
|
||||
- Anti-patterns count
|
||||
- Output file paths
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No ANALYZE-* tasks available | Idle, wait for coordinator assignment |
|
||||
| ui-ux-pro-max not found | Fallback to LLM general knowledge, log warning |
|
||||
| search.py execution error | Retry once, then fallback |
|
||||
| Python not available | Fallback to LLM general knowledge |
|
||||
| Session folder not found | Notify coordinator, request location |
|
||||
| Web search fails | Skip competitive reference, continue |
|
||||
| Critical issue beyond scope | SendMessage fix_required to coordinator |
|
||||
@@ -1,219 +0,0 @@
|
||||
# Architect Role
|
||||
|
||||
Frontend architect. Consumes design-intelligence.json, defines design token system, component architecture, project structure, and technology selection. Design token values should prioritize ui-ux-pro-max recommendations.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `architect` | **Tag**: `[architect]`
|
||||
- **Task Prefix**: `ARCH-*`
|
||||
- **Responsibility**: Code generation (architecture artifacts)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `ARCH-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[architect]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within architecture design and token definition scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope (analysis, implementation, QA)
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Implement concrete component code (only define specifications)
|
||||
- Omit `[architect]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
> No command files -- all phases execute inline.
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `Read` | builtin | Phase 2-3 | Load design intelligence, shared memory |
|
||||
| `Write` | builtin | Phase 3-4 | Write architecture artifacts |
|
||||
| `Edit` | builtin | Phase 3-4 | Modify architecture files |
|
||||
| `Glob` | builtin | Phase 2 | Detect project structure |
|
||||
| `Grep` | builtin | Phase 2 | Search patterns |
|
||||
| `Task(code-developer)` | subagent | Phase 3 | Complex architecture file generation |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `arch_ready` | architect → coordinator | Architecture complete | Architecture artifacts ready for downstream |
|
||||
| `arch_revision` | architect → coordinator | Revision after QA feedback | Architecture revision complete |
|
||||
| `arch_progress` | architect → coordinator | Partial progress | Architecture progress update |
|
||||
| `error` | architect → coordinator | Architecture failure | Architecture design failed |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: **<session-id>**, // MUST be session ID (e.g., FES-xxx-date), NOT team name. Extract from Session: field.
|
||||
from: "architect",
|
||||
to: "coordinator",
|
||||
type: <message-type>,
|
||||
summary: "[architect] ARCH complete: <task-subject>",
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <session-id> --from architect --to coordinator --type <message-type> --summary \"[architect] ...\" --ref <artifact-path> --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 `ARCH-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
**Input Sources**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Extract from task description `Session: <path>` | Yes |
|
||||
| Scope | Extract from task description `Scope: <tokens|components|full>` | No (default: full) |
|
||||
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
| Project files | Glob `src/**/*` | No |
|
||||
|
||||
**Loading Steps**:
|
||||
|
||||
1. Extract session folder from task description
|
||||
2. Extract scope (tokens / components / full)
|
||||
3. Load design intelligence from analyst output
|
||||
4. Load shared memory
|
||||
5. Load existing project structure via Glob
|
||||
|
||||
**Fail-safe**: If design-intelligence.json not found -> SendMessage to coordinator requesting location.
|
||||
|
||||
### Phase 3: Architecture Design
|
||||
|
||||
**Scope Selection**:
|
||||
|
||||
| Scope | Output |
|
||||
|-------|--------|
|
||||
| `tokens` | Design token system only |
|
||||
| `components` | Component architecture only |
|
||||
| `full` | Both tokens and components |
|
||||
|
||||
#### Step 1: Design Token System (scope: tokens or full)
|
||||
|
||||
Generate `design-tokens.json` with categories:
|
||||
|
||||
| Category | Content | Source |
|
||||
|----------|---------|--------|
|
||||
| `color` | Primary, secondary, background, surface, text, CTA | ui-ux-pro-max recommendations |
|
||||
| `typography` | Font families, font sizes | ui-ux-pro-max recommendations |
|
||||
| `spacing` | Scale from xs to 2xl | Standard scale |
|
||||
| `border-radius` | sm, md, lg, full | Standard scale |
|
||||
| `shadow` | sm, md, lg | Standard elevation |
|
||||
| `transition` | fast, normal, slow | Standard durations |
|
||||
|
||||
**Token Structure**:
|
||||
- Use `$type` and `$value` format (Design Tokens Community Group)
|
||||
- Support light/dark mode via nested values
|
||||
- Fallback to defaults if design intelligence unavailable
|
||||
|
||||
#### Step 2: Component Architecture (scope: components or full)
|
||||
|
||||
Generate component specifications in `architecture/component-specs/`:
|
||||
|
||||
**Component Spec Template**:
|
||||
1. Design Reference (style, stack)
|
||||
2. Props table (name, type, default, description)
|
||||
3. Variants table (name, description)
|
||||
4. Accessibility requirements (role, keyboard, ARIA, contrast)
|
||||
5. Implementation hints (CSS keywords)
|
||||
6. Anti-patterns to avoid (from design intelligence)
|
||||
|
||||
**Component List**: Derived from task description analysis.
|
||||
|
||||
#### Step 3: Project Structure (scope: full or no existing project)
|
||||
|
||||
Generate `project-structure.md`:
|
||||
|
||||
**Stack-specific Structure**:
|
||||
|
||||
| Stack | Directory Layout |
|
||||
|-------|-----------------|
|
||||
| react | src/components/, src/pages/, src/hooks/, src/styles/, src/utils/, src/types/ |
|
||||
| nextjs | app/(routes)/, app/components/, app/lib/, app/styles/, app/types/ |
|
||||
| vue | src/components/, src/views/, src/composables/, src/styles/, src/types/ |
|
||||
| html-tailwind | src/components/, src/pages/, src/styles/, src/assets/ |
|
||||
|
||||
**Conventions**:
|
||||
- Naming: kebab-case for files, PascalCase for components
|
||||
- Imports: absolute imports via @/ alias
|
||||
- Styling: CSS Modules + design tokens (or Tailwind for html-tailwind)
|
||||
- Testing: co-located test files (*.test.tsx)
|
||||
|
||||
### Phase 4: Self-Validation
|
||||
|
||||
**Validation Checks**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| JSON validity | Parse design-tokens.json | No errors |
|
||||
| Required categories | Check for color, typography, spacing | All present |
|
||||
| Anti-pattern compliance | Check token values against anti-patterns | No violations |
|
||||
| File existence | Verify all planned files exist | All files present |
|
||||
|
||||
**Validation Result**:
|
||||
|
||||
| Status | Condition |
|
||||
|--------|-----------|
|
||||
| complete | No issues found |
|
||||
| complete_with_warnings | Non-critical issues found |
|
||||
|
||||
**Update Shared Memory**:
|
||||
- Write `design_token_registry` field with generated tokens
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[architect]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Report Content**:
|
||||
- Task subject and status
|
||||
- Scope completed
|
||||
- Token counts (colors, typography, spacing)
|
||||
- Design intelligence source
|
||||
- Output file paths
|
||||
- Validation warnings (if any)
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No ARCH-* tasks available | Idle, wait for coordinator assignment |
|
||||
| design-intelligence.json not found | Use default token values, log warning |
|
||||
| Session folder not found | Notify coordinator, request location |
|
||||
| Token validation fails | Report issues, continue with warnings |
|
||||
| Sub-agent failure | Retry once, fallback to direct execution |
|
||||
| Critical issue beyond scope | SendMessage error to coordinator |
|
||||
@@ -0,0 +1,202 @@
|
||||
# Command: Dispatch
|
||||
|
||||
Create the frontend development task chain with correct dependencies and structured task descriptions. Supports page, feature, and 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 session.json `pipeline_mode` | Yes |
|
||||
| Industry | From session.json `industry` | Yes |
|
||||
| Constraints | From session.json `constraints` | No |
|
||||
|
||||
1. Load user requirement and scope from session.json
|
||||
2. Load pipeline mode (page / feature / system) from session.json
|
||||
3. Load industry and constraints for task descriptions
|
||||
|
||||
## Phase 3: Task Chain Creation
|
||||
|
||||
### Task Description Template
|
||||
|
||||
Every task description uses structured format:
|
||||
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "<TASK-ID>",
|
||||
owner: "<role>",
|
||||
description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
|
||||
TASK:
|
||||
- <step 1: specific action>
|
||||
- <step 2: specific action>
|
||||
- <step 3: specific action>
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Industry: <industry>
|
||||
- Scope: <scope>
|
||||
- Upstream artifacts: <artifact-1>, <artifact-2>
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: <deliverable path> + <quality criteria>
|
||||
CONSTRAINTS: <scope limits, focus areas>",
|
||||
blockedBy: [<dependency-list>],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
### Mode Router
|
||||
|
||||
| Mode | Task Chain |
|
||||
|------|------------|
|
||||
| `page` | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 |
|
||||
| `feature` | ANALYZE-001 -> ARCH-001 -> QA-001 -> DEV-001 -> QA-002 |
|
||||
| `system` | ANALYZE-001 -> ARCH-001 -> QA-001 -> [ARCH-002 || DEV-001] -> QA-002 -> DEV-002 -> QA-003 |
|
||||
|
||||
---
|
||||
|
||||
### Page Mode Task Chain (4 tasks)
|
||||
|
||||
**ANALYZE-001** (analyst):
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "ANALYZE-001",
|
||||
description: "PURPOSE: Analyze frontend requirements and retrieve design intelligence | Success: design-intelligence.json produced with industry-specific recommendations
|
||||
TASK:
|
||||
- Detect tech stack and existing design system
|
||||
- Retrieve design intelligence via ui-ux-pro-max (or LLM fallback)
|
||||
- Analyze existing codebase patterns
|
||||
- Compile design-intelligence.json and requirements.md
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Industry: <industry>
|
||||
- Scope: <scope>
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: <session>/analysis/design-intelligence.json + requirements.md | Structured design data
|
||||
CONSTRAINTS: Read-only analysis | No code modifications",
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
**ARCH-001** (architect):
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "ARCH-001",
|
||||
description: "PURPOSE: Define design token system and component architecture | Success: design-tokens.json + component specs produced
|
||||
TASK:
|
||||
- Load design intelligence from analyst output
|
||||
- Generate design token system (colors, typography, spacing, shadows)
|
||||
- Define component architecture and specs
|
||||
- Generate project structure
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Industry: <industry>
|
||||
- Scope: full
|
||||
- Upstream artifacts: design-intelligence.json, requirements.md
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: <session>/architecture/design-tokens.json + component-specs/ + project-structure.md
|
||||
CONSTRAINTS: Use ui-ux-pro-max recommendations for token values | Support light/dark mode",
|
||||
blockedBy: ["ANALYZE-001"],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
**DEV-001** (developer):
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "DEV-001",
|
||||
description: "PURPOSE: Implement frontend page/components from architecture artifacts | Success: All planned files implemented with design token usage
|
||||
TASK:
|
||||
- Load design tokens, component specs, project structure
|
||||
- Generate CSS custom properties from design tokens
|
||||
- Implement components following specs and coding standards
|
||||
- Self-validate: no hardcoded colors, cursor-pointer, focus styles, responsive
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Industry: <industry>
|
||||
- Scope: full
|
||||
- Upstream artifacts: design-tokens.json, component-specs/, project-structure.md
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: src/styles/tokens.css + component files | Design-token compliant code
|
||||
CONSTRAINTS: Use CSS variables from tokens | Mobile-first responsive | WCAG AA",
|
||||
blockedBy: ["ARCH-001"],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
**QA-001** (qa):
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "QA-001",
|
||||
description: "PURPOSE: Execute 5-dimension quality audit on implementation | Success: Score >= 8 with 0 critical issues
|
||||
TASK:
|
||||
- Load design intelligence and tokens for compliance checks
|
||||
- Execute 5-dimension audit (code quality, accessibility, design compliance, UX, pre-delivery)
|
||||
- Calculate weighted score and determine verdict
|
||||
- Write audit report
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Industry: <industry>
|
||||
- Review type: code-review
|
||||
- Upstream artifacts: design-intelligence.json, design-tokens.json, src/**
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: <session>/qa/audit-001.md | Weighted score + verdict + categorized issues
|
||||
CONSTRAINTS: Read-only review | No code modifications",
|
||||
blockedBy: ["DEV-001"],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Feature Mode Task Chain (5 tasks)
|
||||
|
||||
Create ANALYZE-001 and ARCH-001 as page mode above, then:
|
||||
|
||||
**QA-001** (qa, architecture review):
|
||||
- blockedBy: ["ARCH-001"]
|
||||
- Review type: architecture-review
|
||||
- Reviews architecture artifacts before developer starts
|
||||
|
||||
**DEV-001** (developer):
|
||||
- blockedBy: ["QA-001"] (waits for arch review to pass)
|
||||
|
||||
**QA-002** (qa, code review):
|
||||
- blockedBy: ["DEV-001"]
|
||||
- Review type: code-review
|
||||
|
||||
---
|
||||
|
||||
### System Mode Task Chain (7 tasks)
|
||||
|
||||
Create ANALYZE-001, ARCH-001, QA-001 as feature mode above, then:
|
||||
|
||||
**ARCH-002** (architect, parallel with DEV-001):
|
||||
- blockedBy: ["QA-001"]
|
||||
- Scope: components (refined specs after QA feedback)
|
||||
|
||||
**DEV-001** (developer, parallel with ARCH-002):
|
||||
- blockedBy: ["QA-001"]
|
||||
- Scope: tokens (CSS generation)
|
||||
|
||||
**QA-002** (qa):
|
||||
- blockedBy: ["ARCH-002"]
|
||||
- Review type: component-review
|
||||
|
||||
**DEV-002** (developer):
|
||||
- blockedBy: ["QA-002"]
|
||||
- Scope: components
|
||||
|
||||
**QA-003** (qa, final review):
|
||||
- blockedBy: ["DEV-002"]
|
||||
- Review type: final
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
| Check | Method | Expected |
|
||||
|-------|--------|----------|
|
||||
| Task count correct | TaskList count | page: 4, feature: 5, system: 7 |
|
||||
| Dependencies correct | Trace dependency graph | Acyclic, correct blockedBy |
|
||||
| Structured descriptions | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
|
||||
| Owner assignments correct | Role matches task prefix | ANALYZE->analyst, ARCH->architect, DEV->developer, QA->qa |
|
||||
|
||||
If validation fails, fix the specific task and re-validate.
|
||||
@@ -0,0 +1,185 @@
|
||||
# Command: Monitor
|
||||
|
||||
Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, GC loops, and completion.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session state | <session>/session.json | Yes |
|
||||
| Task list | TaskList() | Yes |
|
||||
| Trigger event | From Entry Router detection | Yes |
|
||||
| Pipeline definition | From SKILL.md | Yes |
|
||||
|
||||
1. Load session.json for current state, `pipeline_mode`, `gc_rounds`
|
||||
2. Run TaskList() to get current task statuses
|
||||
3. Identify trigger event type from Entry Router
|
||||
|
||||
## Phase 3: Event Handlers
|
||||
|
||||
### handleCallback
|
||||
|
||||
Triggered when a worker sends completion message.
|
||||
|
||||
1. Parse message to identify role and task ID:
|
||||
|
||||
| Message Pattern | Role Detection |
|
||||
|----------------|---------------|
|
||||
| `[analyst]` or task ID `ANALYZE-*` | analyst |
|
||||
| `[architect]` or task ID `ARCH-*` | architect |
|
||||
| `[developer]` or task ID `DEV-*` | developer |
|
||||
| `[qa]` or task ID `QA-*` | qa |
|
||||
|
||||
2. Mark task as completed:
|
||||
|
||||
```
|
||||
TaskUpdate({ taskId: "<task-id>", status: "completed" })
|
||||
```
|
||||
|
||||
3. Record completion in session state
|
||||
|
||||
4. Check if checkpoint applies:
|
||||
|
||||
| Completed Task | Pipeline Mode | Checkpoint Action |
|
||||
|---------------|---------------|-------------------|
|
||||
| ANALYZE-001 | all | Log: analysis ready |
|
||||
| ARCH-001 | feature/system | Log: architecture ready for review |
|
||||
| QA-001 (arch review) | feature/system | Gate: pause if critical issues, wait for architect revision |
|
||||
| QA-* (code review) | all | Check verdict for GC loop (see below) |
|
||||
|
||||
5. **GC Loop Check** (when QA completes with fix_required):
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| QA verdict = PASSED or PASSED_WITH_WARNINGS | Proceed to handleSpawnNext |
|
||||
| QA verdict = FIX_REQUIRED AND gc_round < 2 | Create DEV-fix + QA-recheck tasks, increment gc_round |
|
||||
| QA verdict = FIX_REQUIRED AND gc_round >= 2 | Escalate to user: accept current state or manual intervention |
|
||||
|
||||
**GC Fix Task Creation**:
|
||||
```
|
||||
TaskCreate({
|
||||
subject: "DEV-fix-<round>",
|
||||
description: "PURPOSE: Fix issues identified in QA audit | Success: All critical/high issues resolved
|
||||
TASK:
|
||||
- Load QA audit report with findings
|
||||
- Address critical and high severity issues
|
||||
- Re-validate fixes against coding standards
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Upstream artifacts: <session>/qa/audit-<NNN>.md
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: Fixed source files | QA issues resolved
|
||||
CONSTRAINTS: Targeted fixes only | Do not introduce regressions",
|
||||
blockedBy: [],
|
||||
status: "pending"
|
||||
})
|
||||
|
||||
TaskCreate({
|
||||
subject: "QA-recheck-<round>",
|
||||
description: "PURPOSE: Re-audit after developer fixes | Success: Score >= 8, critical == 0
|
||||
TASK:
|
||||
- Execute 5-dimension audit on fixed code
|
||||
- Focus on previously flagged issues
|
||||
- Calculate new score
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Review type: code-review
|
||||
- Shared memory: <session>/.msg/meta.json
|
||||
EXPECTED: <session>/qa/audit-<NNN>.md | Improved score
|
||||
CONSTRAINTS: Read-only review",
|
||||
blockedBy: ["DEV-fix-<round>"],
|
||||
status: "pending"
|
||||
})
|
||||
```
|
||||
|
||||
6. Proceed to handleSpawnNext
|
||||
|
||||
### handleSpawnNext
|
||||
|
||||
Find and spawn the next ready tasks.
|
||||
|
||||
1. Scan task list for tasks where:
|
||||
- Status is "pending"
|
||||
- All blockedBy tasks have status "completed"
|
||||
|
||||
2. For each ready task, spawn team-worker:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker for <task-id>",
|
||||
team_name: "frontend",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-frontend/role-specs/<role>.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: frontend
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
|
||||
})
|
||||
```
|
||||
|
||||
3. **Parallel spawn rules**:
|
||||
|
||||
| Mode | Scenario | Spawn Behavior |
|
||||
|------|----------|---------------|
|
||||
| page | Each stage sequential | One worker at a time |
|
||||
| feature | After QA-001 arch review | Spawn DEV-001 |
|
||||
| system | After QA-001 arch review | Spawn ARCH-002 + DEV-001 in parallel |
|
||||
|
||||
4. STOP after spawning -- wait for next callback
|
||||
|
||||
### handleCheck
|
||||
|
||||
Output current pipeline status.
|
||||
|
||||
```
|
||||
Pipeline Status (<mode> mode):
|
||||
[DONE] ANALYZE-001 (analyst) -> design-intelligence.json
|
||||
[DONE] ARCH-001 (architect) -> design-tokens.json
|
||||
[RUN] DEV-001 (developer) -> implementing...
|
||||
[WAIT] QA-001 (qa) -> blocked by DEV-001
|
||||
|
||||
GC Rounds: 0/2
|
||||
Session: <session-id>
|
||||
```
|
||||
|
||||
Output status -- do NOT advance pipeline.
|
||||
|
||||
### handleResume
|
||||
|
||||
Resume pipeline after user pause or interruption.
|
||||
|
||||
1. Audit task list for inconsistencies:
|
||||
- Tasks stuck in "in_progress" -> reset to "pending"
|
||||
- Tasks with completed blockers but still "pending" -> include in spawn list
|
||||
2. Proceed to handleSpawnNext
|
||||
|
||||
### handleComplete
|
||||
|
||||
Triggered when all pipeline tasks are completed.
|
||||
|
||||
**Completion check**:
|
||||
|
||||
| Mode | Completion Condition |
|
||||
|------|---------------------|
|
||||
| page | All 4 tasks (+ any GC fix/recheck tasks) completed |
|
||||
| feature | All 5 tasks (+ any GC fix/recheck tasks) completed |
|
||||
| system | All 7 tasks (+ any GC fix/recheck tasks) completed |
|
||||
|
||||
1. If any tasks not completed, return to handleSpawnNext
|
||||
2. If all completed, transition to coordinator Phase 5
|
||||
|
||||
## Phase 4: State Persistence
|
||||
|
||||
After every handler execution:
|
||||
|
||||
1. Update session.json with current state (active tasks, gc_rounds, last event)
|
||||
2. Verify task list consistency
|
||||
3. STOP and wait for next event
|
||||
@@ -1,257 +1,266 @@
|
||||
# Coordinator Role
|
||||
# Coordinator - Frontend Development Team
|
||||
|
||||
Frontend team coordinator. Orchestrates pipeline: requirement clarification → industry identification → team creation → task chain → dispatch → monitoring → reporting. Manages Generator-Critic loops between developer and qa, consulting pattern between developer and analyst.
|
||||
**Role**: coordinator
|
||||
**Type**: Orchestrator
|
||||
**Team**: frontend
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Responsibility**: Parse requirements → Create team → Dispatch tasks → Monitor progress → Report results
|
||||
Orchestrates the frontend development pipeline: manages task chains, spawns team-worker agents, handles Generator-Critic loops (developer <-> qa), consulting pattern (developer -> analyst), and drives the pipeline to completion.
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- All output (SendMessage, team_msg, logs) must carry `[coordinator]` identifier
|
||||
- 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
|
||||
- Use `team-worker` agent type for all worker spawns (NOT `general-purpose`)
|
||||
- Follow Command Execution Protocol for dispatch and monitor commands
|
||||
- Respect pipeline stage dependencies (blockedBy)
|
||||
- Stop after spawning workers -- wait for callbacks
|
||||
- Handle GC loops (developer <-> qa) with max 2 iterations
|
||||
- Execute completion action in Phase 5
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute frontend development work directly (delegate to workers)
|
||||
- Modify task outputs (workers own their deliverables)
|
||||
- Call implementation subagents directly
|
||||
- Skip dependency validation when creating task chains
|
||||
- Omit `[coordinator]` identifier in any output
|
||||
- Implement domain logic (analyzing, designing, coding, reviewing) -- workers handle this
|
||||
- Spawn workers without creating tasks first
|
||||
- Skip architecture review gate when configured (feature/system modes)
|
||||
- Force-advance pipeline past failed QA review
|
||||
- Modify source code directly -- delegate to developer worker
|
||||
|
||||
> **Core principle**: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via TaskCreate.
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
|
||||
When coordinator is invoked, first detect the invocation type:
|
||||
When coordinator is invoked, detect 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) |
|
||||
| Worker callback | Message contains role tag [analyst], [architect], [developer], [qa] | -> handleCallback |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
|
||||
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
|
||||
| New session | None of above | -> Phase 1 (Requirement Clarification) |
|
||||
|
||||
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
|
||||
|
||||
### Router Implementation
|
||||
|
||||
1. **Load session context** (if exists):
|
||||
- Scan `.workflow/.team/FE-*/.msg/meta.json` for active/paused sessions
|
||||
- If found, extract session folder path, status, and pipeline mode
|
||||
|
||||
2. **Parse $ARGUMENTS** for detection keywords:
|
||||
- Check for role name tags in message content
|
||||
- Check for "check", "status", "resume", "continue" keywords
|
||||
|
||||
3. **Route to handler**:
|
||||
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
|
||||
- For Phase 0: Execute Session Resume Check below
|
||||
- For Phase 1: Execute Requirement Clarification below
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `task_unblocked` | coordinator → any | Dependency resolved | Notify worker of available task |
|
||||
| `sync_checkpoint` | coordinator → all | QA passed at sync point | Design artifacts stable for consumption |
|
||||
| `fix_required` | coordinator → developer | QA found issues | Create DEV-fix task |
|
||||
| `error` | coordinator → all | Critical system error | Escalation to user |
|
||||
| `shutdown` | coordinator → all | Team being dissolved | Clean shutdown signal |
|
||||
Triggered when an active/paused session is detected on coordinator entry.
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
1. Load session.json from detected session folder
|
||||
2. Audit task list:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: **<session-id>**, // MUST be session ID (e.g., FES-xxx-date), NOT team name. Extract from Session: field.
|
||||
from: "coordinator",
|
||||
to: <recipient>,
|
||||
type: <message-type>,
|
||||
summary: "[coordinator] <summary>",
|
||||
ref: <artifact-path>
|
||||
TaskList()
|
||||
```
|
||||
|
||||
3. Reconcile session state vs task status:
|
||||
|
||||
| Task Status | Session Expects | Action |
|
||||
|-------------|----------------|--------|
|
||||
| in_progress | Should be running | Reset to pending (worker was interrupted) |
|
||||
| completed | Already tracked | Skip |
|
||||
| pending + unblocked | Ready to run | Include in spawn list |
|
||||
|
||||
4. Rebuild team if not active:
|
||||
|
||||
```
|
||||
TeamCreate({ team_name: "frontend" })
|
||||
```
|
||||
|
||||
5. Spawn workers for ready tasks -> Phase 4 coordination loop
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
1. Parse user task description from $ARGUMENTS
|
||||
|
||||
2. Ask for missing parameters via AskUserQuestion:
|
||||
|
||||
**Scope Selection**:
|
||||
|
||||
| Option | Pipeline |
|
||||
|--------|----------|
|
||||
| Single page | page (4-beat linear) |
|
||||
| Multi-component feature | feature (5-beat with arch review) |
|
||||
| Full frontend system | system (7-beat dual-track) |
|
||||
|
||||
**Industry Selection**:
|
||||
|
||||
| Option | Strictness |
|
||||
|--------|------------|
|
||||
| SaaS/Tech | standard |
|
||||
| E-commerce/Retail | standard |
|
||||
| Healthcare/Finance | strict |
|
||||
| Other | standard |
|
||||
|
||||
**Design Constraints** (multi-select): Existing design system, WCAG AA, Responsive, Dark mode
|
||||
|
||||
3. Record requirements: mode, scope, industry, constraints
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Session & Team Setup
|
||||
|
||||
1. Create session directory:
|
||||
|
||||
```
|
||||
Bash("mkdir -p .workflow/.team/FE-<slug>-<YYYY-MM-DD>/{.msg,wisdom,analysis,architecture,qa,build}")
|
||||
```
|
||||
|
||||
2. Write session.json:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "active",
|
||||
"team_name": "frontend",
|
||||
"requirement": "<requirement>",
|
||||
"timestamp": "<ISO-8601>",
|
||||
"pipeline_mode": "<page|feature|system>",
|
||||
"industry": "<industry>",
|
||||
"constraints": [],
|
||||
"gc_rounds": {}
|
||||
}
|
||||
```
|
||||
|
||||
3. Initialize .msg/meta.json:
|
||||
|
||||
```
|
||||
Write("<session>/.msg/meta.json", { "session_id": "<session-id>", "requirement": "<requirement>", "pipeline_mode": "<mode>" })
|
||||
```
|
||||
|
||||
4. Create team:
|
||||
|
||||
```
|
||||
TeamCreate({ team_name: "frontend" })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Task Chain Creation
|
||||
|
||||
Execute `commands/dispatch.md` inline (Command Execution Protocol):
|
||||
|
||||
1. Read `roles/coordinator/commands/dispatch.md`
|
||||
2. Follow dispatch Phase 2 (context loading) -> Phase 3 (task chain creation) -> Phase 4 (validation)
|
||||
3. Result: all pipeline tasks created with correct blockedBy dependencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Spawn & Coordination Loop
|
||||
|
||||
### Initial Spawn
|
||||
|
||||
Find first unblocked task and spawn its worker:
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn analyst worker",
|
||||
team_name: "frontend",
|
||||
name: "analyst",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: analyst
|
||||
role_spec: .claude/skills/team-frontend/role-specs/analyst.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: frontend
|
||||
requirement: <requirement>
|
||||
inner_loop: false
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
**STOP** after spawning. Wait for worker callback.
|
||||
|
||||
### Coordination (via monitor.md handlers)
|
||||
|
||||
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks:
|
||||
|
||||
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
|
||||
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
|
||||
- handleComplete -> all done -> Phase 5
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
1. Load session state -> count completed tasks, calculate duration
|
||||
2. List deliverables:
|
||||
|
||||
| Deliverable | Path |
|
||||
|-------------|------|
|
||||
| Design Intelligence | <session>/analysis/design-intelligence.json |
|
||||
| Requirements | <session>/analysis/requirements.md |
|
||||
| Design Tokens | <session>/architecture/design-tokens.json |
|
||||
| Component Specs | <session>/architecture/component-specs/ |
|
||||
| Project Structure | <session>/architecture/project-structure.md |
|
||||
| QA Audits | <session>/qa/audit-*.md |
|
||||
|
||||
3. Output pipeline summary: task count, duration, QA scores
|
||||
|
||||
4. **Completion Action** (interactive):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <session-id> --from coordinator --to <recipient> --type <message-type> --summary \"[coordinator] ...\" --ref <artifact-path> --json")
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Team 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" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
5. Handle user choice:
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### 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:
|
||||
|
||||
**Scope Selection**:
|
||||
| Option | Description | Pipeline |
|
||||
|--------|-------------|----------|
|
||||
| Single page | Design and implement a standalone page/component | page |
|
||||
| Multi-component feature | Multiple components + design tokens + interaction logic | feature |
|
||||
| Full frontend system | Build complete frontend from scratch (tokens + component library + pages) | system |
|
||||
|
||||
**Industry Selection**:
|
||||
| Option | Description | Strictness |
|
||||
|--------|-------------|------------|
|
||||
| SaaS/Tech | SaaS, dev tools, AI products | standard |
|
||||
| E-commerce/Retail | E-commerce, luxury, marketplace | standard |
|
||||
| Healthcare/Finance | Healthcare, banking, insurance (high compliance) | strict |
|
||||
| Other | Manual keyword input | standard |
|
||||
|
||||
**Design Constraints** (multi-select):
|
||||
- Existing design system (must be compatible with existing tokens/components)
|
||||
- WCAG AA (must meet WCAG 2.1 AA accessibility standards)
|
||||
- Responsive (must support mobile/tablet/desktop)
|
||||
- Dark mode (must support light/dark theme switching)
|
||||
|
||||
3. **Store requirements**: mode, scope, focus, constraints
|
||||
|
||||
**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: `FE-<slug>-<YYYY-MM-DD>`
|
||||
2. Create session folder structure
|
||||
3. Call TeamCreate with team name
|
||||
4. Initialize wisdom directory (learnings.md, decisions.md, conventions.md, issues.md)
|
||||
5. Write session file with: session_id, mode, scope, status="active"
|
||||
6. Initialize shared-memory.json with empty structures
|
||||
7. Do NOT pre-spawn workers (spawned per-stage in Phase 4)
|
||||
|
||||
**Session Directory Structure**:
|
||||
```
|
||||
.workflow/.team/FE-<slug>-<date>/
|
||||
├── team-session.json
|
||||
├── shared-memory.json
|
||||
├── wisdom/
|
||||
├── analysis/
|
||||
├── architecture/
|
||||
├── qa/
|
||||
└── build/
|
||||
```
|
||||
|
||||
**Success**: Team created, session file written, wisdom initialized.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Create Task Chain
|
||||
|
||||
**Objective**: Dispatch tasks based on mode with proper dependencies.
|
||||
|
||||
**Pipeline Definitions**:
|
||||
|
||||
| Mode | Task Chain | Description |
|
||||
|------|------------|-------------|
|
||||
| page | ANALYZE-001 -> ARCH-001 -> DEV-001 -> QA-001 | Linear 4-beat |
|
||||
| feature | ANALYZE-001 -> ARCH-001 -> QA-001 -> DEV-001 -> QA-002 | 5-beat with architecture review |
|
||||
| system | ANALYZE-001 -> ARCH-001 -> QA-001 -> [ARCH-002 || DEV-001] -> QA-002 -> DEV-002 -> QA-003 | 7-beat dual-track |
|
||||
|
||||
**Task Creation** (for each task):
|
||||
- Include `Session: <session-folder>` in description
|
||||
- Set owner based on role mapping
|
||||
- Set blockedBy dependencies based on pipeline
|
||||
|
||||
**Success**: All tasks created with correct dependencies.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Coordination Loop
|
||||
|
||||
**Objective**: Spawn first batch of ready workers, 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
|
||||
|
||||
**Pipeline advancement** driven by three wake sources:
|
||||
- Worker callback (automatic) -> Entry Router -> handleCallback
|
||||
- User "check" -> handleCheck (status only)
|
||||
- User "resume" -> handleResume (advance)
|
||||
|
||||
**Message Routing**:
|
||||
|
||||
| Received Message | Action |
|
||||
|-----------------|--------|
|
||||
| analyst: `analyze_ready` | team_msg log -> TaskUpdate ANALYZE completed -> unblock ARCH |
|
||||
| architect: `arch_ready` | team_msg log -> TaskUpdate ARCH completed -> unblock QA/DEV |
|
||||
| developer: `dev_complete` | team_msg log -> TaskUpdate DEV completed -> unblock QA |
|
||||
| qa: `qa_passed` | team_msg log -> TaskUpdate QA completed -> unblock next stage |
|
||||
| qa: `fix_required` | Create DEV-fix task -> notify developer (GC loop) |
|
||||
| developer: consult request | Create ANALYZE-consult task -> notify analyst |
|
||||
| Worker: `error` | Assess severity -> retry or escalate to user |
|
||||
| All tasks completed | -> Phase 5 |
|
||||
|
||||
**GC Loop Control** (Generator-Critic: developer <-> qa):
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| QA sends fix_required && gcRound < MAX_GC_ROUNDS (2) | Create DEV-fix task + QA-recheck task, increment gcRound |
|
||||
| QA sends fix_required && gcRound >= MAX_GC_ROUNDS | Escalate to user: accept current state or manual intervention |
|
||||
|
||||
---
|
||||
|
||||
### 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 via AskUserQuestion:
|
||||
- New requirement -> back to Phase 1
|
||||
- Close team -> shutdown -> TeamDelete
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Respawn worker, reassign task |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
| Invalid mode | Reject with error, ask to clarify |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
| Teammate unresponsive | Send follow-up, 2x -> respawn |
|
||||
| QA rejected 3+ times | Escalate to user |
|
||||
| Dual-track sync failure | Fallback to single-track sequential |
|
||||
| ui-ux-pro-max unavailable | Continue with LLM general knowledge |
|
||||
| DEV can't find design files | Wait for sync point or escalate |
|
||||
| Choice | Steps |
|
||||
|--------|-------|
|
||||
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete("frontend") -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-frontend', args='resume')" |
|
||||
| Export Results | AskUserQuestion for target directory -> copy artifacts -> Archive & Clean flow |
|
||||
|
||||
@@ -1,238 +0,0 @@
|
||||
# Developer Role
|
||||
|
||||
Frontend developer. Consumes architecture artifacts, implements frontend component/page code. References design-intelligence.json Implementation Checklist and tech stack guidelines during code generation, follows Anti-Patterns constraints.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `developer` | **Tag**: `[developer]`
|
||||
- **Task Prefix**: `DEV-*`
|
||||
- **Responsibility**: Code generation
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `DEV-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[developer]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within frontend code implementation scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope (analysis, architecture, QA)
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Modify design token definitions (only consume them)
|
||||
- Omit `[developer]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
> No command files -- all phases execute inline.
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `Read` | builtin | Phase 2 | Load architecture artifacts |
|
||||
| `Write` | builtin | Phase 3 | Write source code files |
|
||||
| `Edit` | builtin | Phase 3 | Modify source code |
|
||||
| `Bash` | builtin | Phase 3-4 | Run build commands, install deps, format |
|
||||
| `Glob` | builtin | Phase 2-4 | Search project files |
|
||||
| `Grep` | builtin | Phase 2-4 | Search code patterns |
|
||||
| `Task(code-developer)` | subagent | Phase 3 | Complex component implementation |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `dev_complete` | developer → coordinator | Implementation complete | Code implementation finished |
|
||||
| `dev_progress` | developer → coordinator | Partial progress | Implementation progress update |
|
||||
| `error` | developer → coordinator | Implementation failure | Implementation failed |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: **<session-id>**, // MUST be session ID (e.g., FES-xxx-date), NOT team name. Extract from Session: field.
|
||||
from: "developer",
|
||||
to: "coordinator",
|
||||
type: <message-type>,
|
||||
summary: "[developer] DEV complete: <task-subject>",
|
||||
ref: <artifact-path>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <session-id> --from developer --to coordinator --type <message-type> --summary \"[developer] ...\" --ref <artifact-path> --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 `DEV-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
**Input Sources**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Extract from task description `Session: <path>` | Yes |
|
||||
| Scope | Extract from task description `Scope: <tokens|components|full>` | No (default: full) |
|
||||
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
|
||||
| Design tokens | `<session-folder>/architecture/design-tokens.json` | No |
|
||||
| Project structure | `<session-folder>/architecture/project-structure.md` | No |
|
||||
| Component specs | `<session-folder>/architecture/component-specs/*.md` | No |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
|
||||
**Loading Steps**:
|
||||
|
||||
1. Extract session folder and scope from task description
|
||||
2. Load design intelligence
|
||||
3. Load design tokens
|
||||
4. Load project structure
|
||||
5. Load component specs (if available)
|
||||
6. Load shared memory
|
||||
7. Detect tech stack from design intelligence
|
||||
|
||||
**Fail-safe**: If design-tokens.json not found -> SendMessage to coordinator requesting architecture output.
|
||||
|
||||
### Phase 3: Code Implementation
|
||||
|
||||
**Scope Selection**:
|
||||
|
||||
| Scope | Output |
|
||||
|-------|--------|
|
||||
| `tokens` | Generate CSS custom properties from design tokens |
|
||||
| `components` | Implement components from specs |
|
||||
| `full` | Both tokens and components |
|
||||
|
||||
#### Step 1: Generate Design Token CSS (scope: tokens or full)
|
||||
|
||||
Convert `design-tokens.json` to CSS custom properties:
|
||||
|
||||
**Token Category Mapping**:
|
||||
|
||||
| JSON Category | CSS Variable Prefix | Example |
|
||||
|---------------|---------------------|---------|
|
||||
| color | `--color-` | `--color-primary` |
|
||||
| typography.font-family | `--font-` | `--font-heading` |
|
||||
| typography.font-size | `--text-` | `--text-lg` |
|
||||
| spacing | `--space-` | `--space-md` |
|
||||
| border-radius | `--radius-` | `--radius-lg` |
|
||||
| shadow | `--shadow-` | `--shadow-md` |
|
||||
| transition | `--duration-` | `--duration-normal` |
|
||||
|
||||
**Output**: `src/styles/tokens.css`
|
||||
|
||||
**Dark Mode Support**: Add `@media (prefers-color-scheme: dark)` override for colors.
|
||||
|
||||
#### Step 2: Implement Components (scope: components or full)
|
||||
|
||||
**Implementation Strategy**:
|
||||
|
||||
| Condition | Strategy |
|
||||
|-----------|----------|
|
||||
| <= 2 tasks, low complexity | Direct: inline Edit/Write |
|
||||
| 3-5 tasks, medium complexity | Single agent: one code-developer for all |
|
||||
| > 5 tasks, high complexity | Batch agent: group by module, one agent per batch |
|
||||
|
||||
**Subagent Delegation** (for complex implementation):
|
||||
|
||||
```
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: "Implement frontend components: <task-description>",
|
||||
prompt: "..."
|
||||
})
|
||||
```
|
||||
|
||||
**Prompt Content for Subagent**:
|
||||
- Goal: task description
|
||||
- Tech stack: detected stack
|
||||
- Design tokens: import path, CSS variable usage
|
||||
- Component specs: from component-specs/*.md
|
||||
- Stack-specific guidelines: from design intelligence
|
||||
- Implementation checklist: from design intelligence
|
||||
- Anti-patterns to avoid: from design intelligence
|
||||
- Coding standards: design token usage, cursor styles, transitions, contrast, focus styles, reduced motion, responsive
|
||||
|
||||
**Coding Standards**:
|
||||
- Use design token CSS variables, never hardcode colors/spacing
|
||||
- All interactive elements must have `cursor: pointer`
|
||||
- Transitions: 150-300ms (use `var(--duration-normal)`)
|
||||
- Text contrast: minimum 4.5:1 ratio
|
||||
- Include `focus-visible` styles for keyboard navigation
|
||||
- Support `prefers-reduced-motion`
|
||||
- Responsive: mobile-first with md/lg breakpoints
|
||||
- No emoji as functional icons
|
||||
|
||||
### Phase 4: Self-Validation
|
||||
|
||||
**Pre-delivery Self-checks**:
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Hardcoded colors | Scan for hex codes outside tokens.css | None found |
|
||||
| cursor-pointer | Check buttons/links for cursor style | All have cursor-pointer |
|
||||
| Focus styles | Check interactive elements | All have focus styles |
|
||||
| Responsive | Check for breakpoints | Breakpoints present |
|
||||
| File existence | Verify all planned files exist | All files present |
|
||||
| Import resolution | Check no broken imports | All imports resolve |
|
||||
|
||||
**Auto-fix** (if possible):
|
||||
- Add missing cursor-pointer to buttons/links
|
||||
- Add basic focus styles
|
||||
|
||||
**Update Shared Memory**:
|
||||
- Write `component_inventory` field with implemented files
|
||||
|
||||
**Validation Result**:
|
||||
|
||||
| Status | Condition |
|
||||
|--------|-----------|
|
||||
| complete | No issues found |
|
||||
| complete_with_warnings | Non-critical issues found |
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[developer]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Report Content**:
|
||||
- Task subject and status
|
||||
- Scope completed
|
||||
- File count implemented
|
||||
- Self-check results
|
||||
- Output file paths
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No DEV-* tasks available | Idle, wait for coordinator assignment |
|
||||
| design-tokens.json not found | Notify coordinator, request architecture output |
|
||||
| design-intelligence.json not found | Use default implementation guidelines |
|
||||
| Sub-agent failure | Retry once, fallback to direct implementation |
|
||||
| Build/compile errors | Attempt auto-fix, report remaining issues |
|
||||
| Critical issue beyond scope | SendMessage error to coordinator |
|
||||
@@ -1,116 +0,0 @@
|
||||
# Command: pre-delivery-checklist
|
||||
|
||||
> 最终交付前的 CSS 级别精准检查清单，融合 ui-ux-pro-max Pre-Delivery Checklist 和 ux-guidelines.csv 规则。
|
||||
|
||||
## When to Use
|
||||
|
||||
- Phase 3 of qa role, Dimension 5: Pre-Delivery
|
||||
- Final review type (`reviewType === 'final'` or `reviewType === 'code-review'`)
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Direct (inline pattern matching)
|
||||
|
||||
## Checklist Items
|
||||
|
||||
### Accessibility
|
||||
|
||||
| # | Check | Pattern | Severity | Do | Don't |
|
||||
|---|-------|---------|----------|-----|-------|
|
||||
| 1 | Images have alt text | `<img` without `alt=` | CRITICAL | Always provide descriptive alt text | Leave alt empty without role="presentation" |
|
||||
| 2 | Form inputs have labels | `<input` without `<label`/`aria-label` | HIGH | Associate every input with a label | Use placeholder as sole label |
|
||||
| 3 | Focus states visible | Interactive elements without `focus` styles | HIGH | Add focus-visible outline | Remove default focus ring without replacement |
|
||||
| 4 | Color contrast 4.5:1 | Light text on light background | HIGH | Ensure 4.5:1 minimum ratio | Use low-contrast decorative text for content |
|
||||
| 5 | prefers-reduced-motion | Animations without media query | MEDIUM | Wrap in @media (prefers-reduced-motion: no-preference) | Force animations on all users |
|
||||
| 6 | Heading hierarchy | Skipped heading levels (h1→h3) | MEDIUM | Use sequential heading levels | Skip levels for visual sizing |
|
||||
|
||||
### Interaction
|
||||
|
||||
| # | Check | Pattern | Severity | Do | Don't |
|
||||
|---|-------|---------|----------|-----|-------|
|
||||
| 7 | cursor-pointer on clickable | Buttons/links without cursor-pointer | MEDIUM | Add cursor: pointer to all clickable elements | Leave default cursor |
|
||||
| 8 | Transitions 150-300ms | Duration outside range | LOW | Use 150-300ms for micro-interactions | Use >500ms or <100ms transitions |
|
||||
| 9 | Loading states | Async ops without loading indicator | MEDIUM | Show skeleton/spinner during fetch | Leave blank screen while loading |
|
||||
| 10 | Error states | Async ops without error handling | HIGH | Show user-friendly error message | Silently fail or show raw error |
|
||||
|
||||
### Design Compliance
|
||||
|
||||
| # | Check | Pattern | Severity | Do | Don't |
|
||||
|---|-------|---------|----------|-----|-------|
|
||||
| 11 | No hardcoded colors | Hex values outside tokens.css | HIGH | Use var(--color-*) tokens | Hardcode #hex values |
|
||||
| 12 | No hardcoded spacing | px values for margin/padding | MEDIUM | Use var(--space-*) tokens | Hardcode pixel values |
|
||||
| 13 | No emoji as icons | Unicode emoji in UI | HIGH | Use proper SVG/icon library | Use emoji for functional icons |
|
||||
| 14 | Dark mode support | No prefers-color-scheme | MEDIUM | Support light/dark themes | Design for light mode only |
|
||||
|
||||
### Layout
|
||||
|
||||
| # | Check | Pattern | Severity | Do | Don't |
|
||||
|---|-------|---------|----------|-----|-------|
|
||||
| 15 | Responsive breakpoints | No md:/lg:/@media | MEDIUM | Mobile-first responsive design | Desktop-only layout |
|
||||
| 16 | No horizontal scroll | Fixed widths > viewport | HIGH | Use relative/fluid widths | Set fixed pixel widths on containers |
|
||||
|
||||
## Execution
|
||||
|
||||
```javascript
|
||||
function runPreDeliveryChecklist(fileContents) {
|
||||
const results = { passed: 0, failed: 0, items: [] }
|
||||
|
||||
const checks = [
|
||||
{ id: 1, check: "Images have alt text", test: (c) => /<img\s/.test(c) && !/<img\s[^>]*alt=/.test(c), severity: 'CRITICAL' },
|
||||
{ id: 7, check: "cursor-pointer on clickable", test: (c) => /button|onClick/.test(c) && !/cursor-pointer/.test(c), severity: 'MEDIUM' },
|
||||
{ id: 11, check: "No hardcoded colors", test: (c, f) => f !== 'src/styles/tokens.css' && /#[0-9a-fA-F]{6}/.test(c), severity: 'HIGH' },
|
||||
{ id: 13, check: "No emoji as icons", test: (c) => /[\u{1F300}-\u{1F9FF}]/u.test(c), severity: 'HIGH' },
|
||||
{ id: 14, check: "Dark mode support", test: (c) => !/prefers-color-scheme|dark:|\.dark/.test(c), severity: 'MEDIUM', global: true },
|
||||
{ id: 15, check: "Responsive breakpoints", test: (c) => !/md:|lg:|@media.*min-width/.test(c), severity: 'MEDIUM', global: true }
|
||||
]
|
||||
|
||||
// Per-file checks
|
||||
for (const [file, content] of Object.entries(fileContents)) {
|
||||
for (const check of checks.filter(c => !c.global)) {
|
||||
if (check.test(content, file)) {
|
||||
results.failed++
|
||||
results.items.push({ ...check, file, status: 'FAIL' })
|
||||
} else {
|
||||
results.passed++
|
||||
results.items.push({ ...check, file, status: 'PASS' })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Global checks (across all content)
|
||||
const allContent = Object.values(fileContents).join('\n')
|
||||
for (const check of checks.filter(c => c.global)) {
|
||||
if (check.test(allContent)) {
|
||||
results.failed++
|
||||
results.items.push({ ...check, file: 'global', status: 'FAIL' })
|
||||
} else {
|
||||
results.passed++
|
||||
results.items.push({ ...check, file: 'global', status: 'PASS' })
|
||||
}
|
||||
}
|
||||
|
||||
return results
|
||||
}
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Pre-Delivery Checklist Results
|
||||
- Passed: X / Y
|
||||
- Failed: Z
|
||||
|
||||
### Failed Items
|
||||
- [CRITICAL] #1 Images have alt text — src/components/Hero.tsx
|
||||
- [HIGH] #11 No hardcoded colors — src/styles/custom.css
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No files to check | Report empty checklist, score 10/10 |
|
||||
| File read error | Skip file, note in report |
|
||||
| Regex error | Skip check, note in report |
|
||||
@@ -1,257 +0,0 @@
|
||||
# QA Role
|
||||
|
||||
Quality assurance engineer. Integrates ux-guidelines.csv Do/Don't rules, Pre-Delivery Checklist, and industry anti-pattern library to execute 5-dimension code review. Upgrades from conceptual review to CSS-level precise review.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `qa` | **Tag**: `[qa]`
|
||||
- **Task Prefix**: `QA-*`
|
||||
- **Responsibility**: Read-only analysis (code review + quality audit)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Only process `QA-*` prefixed tasks
|
||||
- All output (SendMessage, team_msg, logs) must carry `[qa]` identifier
|
||||
- Only communicate with coordinator via SendMessage
|
||||
- Work strictly within quality review scope
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Execute work outside this role's responsibility scope (analysis, architecture, implementation)
|
||||
- Communicate directly with other worker roles (must go through coordinator)
|
||||
- Create tasks for other roles (TaskCreate is coordinator-exclusive)
|
||||
- Directly modify source code (only report issues)
|
||||
- Omit `[qa]` identifier in any output
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
| `pre-delivery-checklist` | [commands/pre-delivery-checklist.md](commands/pre-delivery-checklist.md) | Phase 3 | Final delivery checklist execution |
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `Read` | builtin | Phase 2-3 | Load artifacts, read code files |
|
||||
| `Glob` | builtin | Phase 2 | Collect files to review |
|
||||
| `Grep` | builtin | Phase 3 | Search code patterns |
|
||||
| `Bash` | builtin | Phase 3 | Run read-only checks (lint, type-check) |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `qa_passed` | qa → coordinator | All checks passed | Review passed, proceed to next stage |
|
||||
| `qa_result` | qa → coordinator | Review complete with findings | Review complete, has findings to address |
|
||||
| `fix_required` | qa → coordinator | Critical issues found | Critical issues found, needs fix (triggers GC loop) |
|
||||
| `error` | qa → coordinator | Review failure | Review process failed |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
team: **<session-id>**, // MUST be session ID (e.g., FES-xxx-date), NOT team name. Extract from Session: field.
|
||||
from: "qa",
|
||||
to: "coordinator",
|
||||
type: <message-type>,
|
||||
summary: "[qa] QA <verdict>: <task-subject> (<score>/10)",
|
||||
ref: <audit-file>
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --team <session-id> --from qa --to coordinator --type <message-type> --summary \"[qa] ...\" --ref <audit-file> --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5-Dimension Audit Framework
|
||||
|
||||
| Dimension | Weight | Source | Focus |
|
||||
|-----------|--------|--------|-------|
|
||||
| Code Quality | 0.20 | Standard code review | Code structure, naming, maintainability |
|
||||
| Accessibility | 0.25 | ux-guidelines.csv accessibility rules | WCAG compliance, keyboard nav, screen reader |
|
||||
| Design Compliance | 0.20 | design-intelligence.json anti-patterns | Industry anti-pattern check, design token usage |
|
||||
| UX Best Practices | 0.20 | ux-guidelines.csv Do/Don't rules | Interaction patterns, responsive, animations |
|
||||
| Pre-Delivery | 0.15 | ui-ux-pro-max Pre-Delivery Checklist | Final delivery checklist |
|
||||
|
||||
---
|
||||
|
||||
## 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 `QA-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.
|
||||
|
||||
### Phase 2: Context Loading
|
||||
|
||||
**Input Sources**:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session folder | Extract from task description `Session: <path>` | Yes |
|
||||
| Review type | Extract from task description `Type: <type>` | No (default: code-review) |
|
||||
| Design intelligence | `<session-folder>/analysis/design-intelligence.json` | No |
|
||||
| Design tokens | `<session-folder>/architecture/design-tokens.json` | No |
|
||||
| Shared memory | `<session-folder>/shared-memory.json` | No |
|
||||
|
||||
**Review Types**:
|
||||
|
||||
| Type | Files to Review |
|
||||
|------|-----------------|
|
||||
| architecture-review | `<session-folder>/architecture/**/*` |
|
||||
| token-review | `<session-folder>/architecture/**/*` |
|
||||
| component-review | `<session-folder>/architecture/component-specs/**/*` |
|
||||
| code-review | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
||||
| final | `src/**/*.{tsx,jsx,vue,svelte,html,css}` |
|
||||
|
||||
**Loading Steps**:
|
||||
|
||||
1. Extract session folder and review type
|
||||
2. Load design intelligence (for anti-patterns, must-have)
|
||||
3. Load design tokens (for compliance checks)
|
||||
4. Load shared memory (for industry context, strictness)
|
||||
5. Collect files to review based on review type
|
||||
|
||||
### Phase 3: 5-Dimension Audit
|
||||
|
||||
#### Dimension 1: Code Quality (weight: 0.20)
|
||||
|
||||
| Check | Severity | Description |
|
||||
|-------|----------|-------------|
|
||||
| File length | MEDIUM | File exceeds 300 lines, consider splitting |
|
||||
| console.log | LOW | console.log found in production code |
|
||||
| Empty catch | HIGH | Empty catch block found |
|
||||
| Unused imports | LOW | Unused imports detected |
|
||||
|
||||
#### Dimension 2: Accessibility (weight: 0.25)
|
||||
|
||||
| Check | Severity | Do | Don't |
|
||||
|-------|----------|----|----|
|
||||
| Image alt | CRITICAL | Always provide alt text | Leave alt empty without role="presentation" |
|
||||
| Input labels | HIGH | Use <label> or aria-label | Rely on placeholder as label |
|
||||
| Button text | HIGH | Add aria-label for icon-only buttons | Use title as sole accessible name |
|
||||
| Heading hierarchy | MEDIUM | Maintain sequential heading levels | Skip heading levels |
|
||||
| Focus styles | HIGH | Add focus-visible outline | Remove default outline without replacement |
|
||||
| ARIA roles | MEDIUM | Include tabindex for non-native elements | Use role without keyboard support |
|
||||
|
||||
**Strict Mode** (medical/financial):
|
||||
|
||||
| Check | Severity | Do | Don't |
|
||||
|-------|----------|----|----|
|
||||
| Reduced motion | HIGH | Wrap animations in @media (prefers-reduced-motion) | Force animations on all users |
|
||||
|
||||
#### Dimension 3: Design Compliance (weight: 0.20)
|
||||
|
||||
| Check | Severity | Do | Don't |
|
||||
|-------|----------|----|----|
|
||||
| Hardcoded colors | HIGH | Use var(--color-primary) | Hardcode #1976d2 |
|
||||
| Hardcoded spacing | MEDIUM | Use var(--space-md) | Hardcode 16px |
|
||||
| Industry anti-patterns | CRITICAL/HIGH | Follow industry-specific guidelines | Violate anti-patterns (gradients, emojis as icons, etc.) |
|
||||
|
||||
#### Dimension 4: UX Best Practices (weight: 0.20)
|
||||
|
||||
| Check | Severity | Do | Don't |
|
||||
|-------|----------|----|----|
|
||||
| Cursor pointer | MEDIUM | Add cursor: pointer to all clickable elements | Leave default cursor on buttons/links |
|
||||
| Transition duration | LOW | Use 150-300ms | Use durations outside 100-500ms |
|
||||
| Responsive | MEDIUM | Use mobile-first responsive design | Design for desktop only |
|
||||
| Loading states | MEDIUM | Show loading indicator during data fetching | Leave blank screen while loading |
|
||||
| Error states | HIGH | Show user-friendly error message | Silently fail or show raw error |
|
||||
|
||||
#### Dimension 5: Pre-Delivery (weight: 0.15)
|
||||
|
||||
Only run on `final` or `code-review` types.
|
||||
|
||||
| Check | Severity |
|
||||
|-------|----------|
|
||||
| No emojis as functional icons | HIGH |
|
||||
| cursor-pointer on all clickable | MEDIUM |
|
||||
| Transitions in valid range (150-300ms) | LOW |
|
||||
| Focus states visible | HIGH |
|
||||
| prefers-reduced-motion support | MEDIUM |
|
||||
| Responsive breakpoints | MEDIUM |
|
||||
| No hardcoded colors | HIGH |
|
||||
| Dark mode support | MEDIUM |
|
||||
|
||||
### Phase 4: Score Calculation and Report
|
||||
|
||||
**Calculate Weighted Score**:
|
||||
|
||||
```
|
||||
score = sum(dimension_score * dimension_weight) for all dimensions
|
||||
```
|
||||
|
||||
**Collect Issues**:
|
||||
|
||||
- Aggregate all issues from all dimensions
|
||||
- Count critical issues
|
||||
|
||||
**Determine Verdict**:
|
||||
|
||||
| Condition | Verdict |
|
||||
|-----------|---------|
|
||||
| score >= 8 AND critical_count === 0 | PASSED |
|
||||
| score >= 6 AND critical_count === 0 | PASSED_WITH_WARNINGS |
|
||||
| score < 6 OR critical_count > 0 | FIX_REQUIRED |
|
||||
|
||||
**Write Audit Report** to `<session-folder>/qa/audit-<NNN>.md`:
|
||||
|
||||
Report structure:
|
||||
1. Summary (verdict, score, critical count, total issues)
|
||||
2. Dimension scores table
|
||||
3. Issues (by severity, with Do/Don't guidance)
|
||||
4. Passed dimensions
|
||||
|
||||
**Update Shared Memory**:
|
||||
- Append to `qa_history` array
|
||||
|
||||
### Phase 5: Report to Coordinator
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report
|
||||
|
||||
Standard report flow: team_msg log -> SendMessage with `[qa]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.
|
||||
|
||||
**Message Type Selection**:
|
||||
|
||||
| Verdict | Message Type |
|
||||
|---------|-------------|
|
||||
| PASSED | `qa_passed` |
|
||||
| PASSED_WITH_WARNINGS | `qa_result` |
|
||||
| FIX_REQUIRED | `fix_required` |
|
||||
|
||||
**Report Content**:
|
||||
- Task subject
|
||||
- Verdict and score
|
||||
- Dimension summary
|
||||
- Critical issues (if any)
|
||||
- High priority issues (if any)
|
||||
- Audit report path
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No QA-* tasks available | Idle, wait for coordinator assignment |
|
||||
| design-intelligence.json not found | Skip design compliance dimension, adjust weights |
|
||||
| No files to review | Report empty review, notify coordinator |
|
||||
| Session folder not found | Notify coordinator, request location |
|
||||
| Critical issue beyond scope | SendMessage error to coordinator |
|
||||
Reference in New Issue
Block a user