mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-28 20:01:17 +08:00
feat: migrate all codex team skills from spawn_agents_on_csv to spawn_agent + wait_agent architecture
- Delete 21 old team skill directories using CSV-wave pipeline pattern (~100+ files) - Delete old team-lifecycle (v3) and team-planex-v2 - Create generic team-worker.toml and team-supervisor.toml (replacing tlv4-specific TOMLs) - Convert 19 team skills from Claude Code format (Agent/SendMessage/TaskCreate) to Codex format (spawn_agent/wait_agent/tasks.json/request_user_input) - Update team-lifecycle-v4 to use generic agent types (team_worker/team_supervisor) - Convert all coordinator role files: dispatch.md, monitor.md, role.md - Convert all worker role files: remove run_in_background, fix Bash syntax - Convert all specs/pipelines.md references - Final state: 20 team skills, 217 .md files, zero Claude Code API residuals Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -1,767 +1,133 @@
|
||||
---
|
||||
name: team-uidesign
|
||||
description: UI design team pipeline. Research existing design system, generate design tokens (W3C format), audit quality, and implement code. CSV wave pipeline with GC loop (designer <-> reviewer) and dual-track parallel support.
|
||||
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"UI design task description\""
|
||||
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, request_user_input
|
||||
description: Unified team skill for UI design team. Research -> design tokens -> audit -> implementation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates dual-track pipeline with GC loops and sync points. Triggers on "team ui design", "ui design team".
|
||||
allowed-tools: spawn_agent(*), wait_agent(*), send_input(*), close_agent(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__read_file(*), mcp__ccw-tools__write_file(*), mcp__ccw-tools__edit_file(*), mcp__ccw-tools__team_msg(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults for scope/industry/constraints.
|
||||
|
||||
# Team UI Design
|
||||
|
||||
## Usage
|
||||
Systematic UI design pipeline: research -> design tokens -> review -> implementation. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
|
||||
|
||||
```bash
|
||||
$team-uidesign "Design a button component with tokens and accessibility"
|
||||
$team-uidesign -c 3 "Create a complete design system for our SaaS dashboard"
|
||||
$team-uidesign -y "Full design system redesign for healthcare portal"
|
||||
$team-uidesign --continue "uds-saas-dashboard-20260308"
|
||||
```
|
||||
|
||||
**Flags**:
|
||||
- `-y, --yes`: Skip all confirmations (auto mode)
|
||||
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
|
||||
- `--continue`: Resume existing session
|
||||
|
||||
**Output Directory**: `.workflow/.csv-wave/{session-id}/`
|
||||
**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Systematic UI design pipeline: research existing design system, generate design tokens (W3C Design Tokens Format), audit for quality/accessibility, and implement production code. Roles: researcher, designer, reviewer, implementer -- dynamically assigned as CSV wave tasks with dependency ordering. Supports component (4-task), system (7-task), and full-system (8-task) pipeline modes. Designer <-> Reviewer Generator-Critic loop with max 2 rounds.
|
||||
|
||||
**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary)
|
||||
## Architecture
|
||||
|
||||
```
|
||||
+-------------------------------------------------------------------+
|
||||
| TEAM UI DESIGN WORKFLOW |
|
||||
+-------------------------------------------------------------------+
|
||||
| |
|
||||
| Phase 0: Pre-Wave Interactive (Requirement Clarification) |
|
||||
| +- Parse UI design task description |
|
||||
| +- Select scope (component/system/full-system), industry |
|
||||
| +- Output: refined requirements for decomposition |
|
||||
| |
|
||||
| Phase 1: Requirement -> CSV + Classification |
|
||||
| +- Signal detection: keyword scan -> pipeline inference |
|
||||
| +- Pipeline selection (component/system/full-system) |
|
||||
| +- Dependency graph from pipeline definition |
|
||||
| +- Classify tasks: csv-wave | interactive (exec_mode) |
|
||||
| +- Compute dependency waves (topological sort) |
|
||||
| +- Generate tasks.csv with wave + exec_mode columns |
|
||||
| +- User validates task breakdown (skip if -y) |
|
||||
| |
|
||||
| Phase 2: Wave Execution Engine (Extended) |
|
||||
| +- For each wave (1..N): |
|
||||
| | +- Execute pre-wave interactive tasks (if any) |
|
||||
| | +- Build wave CSV (filter csv-wave tasks for this wave) |
|
||||
| | +- Inject previous findings into prev_context column |
|
||||
| | +- spawn_agents_on_csv(wave CSV) |
|
||||
| | +- Execute post-wave interactive tasks (if any) |
|
||||
| | +- Merge all results into master tasks.csv |
|
||||
| | +- Check: any failed? -> skip dependents |
|
||||
| | +- GC Loop: if audit fails, create DESIGN-fix + AUDIT-re |
|
||||
| +- discoveries.ndjson shared across all modes (append-only) |
|
||||
| |
|
||||
| Phase 3: Post-Wave Interactive (Completion Action) |
|
||||
| +- Pipeline completion report with deliverables listing |
|
||||
| +- Interactive completion choice (Archive/Keep/Export) |
|
||||
| +- Final aggregation / report |
|
||||
| |
|
||||
| Phase 4: Results Aggregation |
|
||||
| +- Export final results.csv |
|
||||
| +- Generate context.md with all findings |
|
||||
| +- Display summary: completed/failed/skipped per wave |
|
||||
| +- Offer: view results | retry failed | done |
|
||||
| |
|
||||
+-------------------------------------------------------------------+
|
||||
Skill(skill="team-uidesign", args="task description")
|
||||
|
|
||||
SKILL.md (this file) = Router
|
||||
|
|
||||
+--------------+--------------+
|
||||
| |
|
||||
no --role flag --role <name>
|
||||
| |
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/role.md
|
||||
|
|
||||
+-- analyze → dispatch → spawn workers → STOP
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v
|
||||
[team-worker agents, each loads roles/<role>/role.md]
|
||||
researcher designer reviewer implementer
|
||||
```
|
||||
|
||||
---
|
||||
## Role Registry
|
||||
|
||||
## Task Classification Rules
|
||||
| Role | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| researcher | [roles/researcher/role.md](roles/researcher/role.md) | RESEARCH-* | false |
|
||||
| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
|
||||
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | AUDIT-* | false |
|
||||
| implementer | [roles/implementer/role.md](roles/implementer/role.md) | BUILD-* | false |
|
||||
|
||||
Each task is classified by `exec_mode`:
|
||||
## Role Router
|
||||
|
||||
| exec_mode | Mechanism | Criteria |
|
||||
|-----------|-----------|----------|
|
||||
| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
|
||||
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, revision cycles, user approval |
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` → `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
**Classification Decision**:
|
||||
## Shared Constants
|
||||
|
||||
| Task Property | Classification |
|
||||
|---------------|---------------|
|
||||
| Design system research (researcher) | `csv-wave` |
|
||||
| Token system design (designer) | `csv-wave` |
|
||||
| Component specification (designer) | `csv-wave` |
|
||||
| 5-dimension audit (reviewer) | `csv-wave` |
|
||||
| Token/component implementation (implementer) | `csv-wave` |
|
||||
| GC loop fix revision (designer) | `csv-wave` |
|
||||
| GC loop escalation (user decision on audit failure) | `interactive` |
|
||||
| Pipeline completion action | `interactive` |
|
||||
- **Session prefix**: `UDS`
|
||||
- **Session path**: `.workflow/.team/UDS-<slug>-<date>/`
|
||||
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
|
||||
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
|
||||
- **Max GC rounds**: 2
|
||||
|
||||
---
|
||||
## Worker Spawn Template
|
||||
|
||||
## CSV Schema
|
||||
|
||||
### tasks.csv (Master State)
|
||||
|
||||
```csv
|
||||
id,title,description,role,pipeline_mode,scope,audit_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,audit_score,audit_signal,error
|
||||
"RESEARCH-001","Design system analysis","PURPOSE: Analyze existing design system...","researcher","component","full","","","","csv-wave","1","pending","","","","",""
|
||||
"DESIGN-001","Design tokens + component spec","PURPOSE: Define design tokens...","designer","component","tokens","","RESEARCH-001","RESEARCH-001","csv-wave","2","pending","","","","",""
|
||||
"AUDIT-001","Design audit","PURPOSE: 5-dimension quality audit...","reviewer","component","full","token-audit","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","","",""
|
||||
```
|
||||
|
||||
**Columns**:
|
||||
|
||||
| Column | Phase | Description |
|
||||
|--------|-------|-------------|
|
||||
| `id` | Input | Unique task identifier (PREFIX-NNN: RESEARCH, DESIGN, AUDIT, BUILD) |
|
||||
| `title` | Input | Short task title |
|
||||
| `description` | Input | Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS |
|
||||
| `role` | Input | Role name: `researcher`, `designer`, `reviewer`, `implementer` |
|
||||
| `pipeline_mode` | Input | Pipeline: `component`, `system`, `full-system` |
|
||||
| `scope` | Input | Task scope: `full`, `tokens`, `components` |
|
||||
| `audit_type` | Input | Audit type: `token-audit`, `component-audit`, `final-audit` (empty for non-reviewer) |
|
||||
| `deps` | Input | Semicolon-separated dependency task IDs |
|
||||
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
|
||||
| `exec_mode` | Input | `csv-wave` or `interactive` |
|
||||
| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
|
||||
| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
|
||||
| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
|
||||
| `artifacts_produced` | Output | Semicolon-separated paths of produced artifacts |
|
||||
| `audit_score` | Output | Audit weighted score (0-10, empty for non-reviewer tasks) |
|
||||
| `audit_signal` | Output | Audit signal: `audit_passed`, `audit_result`, `fix_required` (empty for non-reviewer) |
|
||||
| `error` | Output | Error message if failed (empty if success) |
|
||||
|
||||
### Per-Wave CSV (Temporary)
|
||||
|
||||
Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
|
||||
|
||||
---
|
||||
|
||||
## Agent Registry (Interactive Agents)
|
||||
|
||||
| Agent | Role File | Pattern | Responsibility | Position |
|
||||
|-------|-----------|---------|----------------|----------|
|
||||
| GC Loop Handler | agents/gc-loop-handler.md | 2.3 (send_input cycle) | Handle audit GC loop escalation decisions | post-wave |
|
||||
| Completion Handler | agents/completion-handler.md | 2.3 (send_input cycle) | Handle pipeline completion action (Archive/Keep/Export) | standalone |
|
||||
|
||||
> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| File | Purpose | Lifecycle |
|
||||
|------|---------|-----------|
|
||||
| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
|
||||
| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
|
||||
| `results.csv` | Final export of all task results | Created in Phase 4 |
|
||||
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
|
||||
| `context.md` | Human-readable execution report | Created in Phase 4 |
|
||||
| `task-analysis.json` | Phase 0/1 output: scope, pipeline, industry | Created in Phase 1 |
|
||||
| `role-instructions/` | Per-role instruction templates for CSV agents | Created in Phase 1 |
|
||||
| `artifacts/` | All deliverables: research, design, audit, build artifacts | Created by agents |
|
||||
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
|
||||
|
||||
---
|
||||
|
||||
## Session Structure
|
||||
Coordinator spawns workers using this template:
|
||||
|
||||
```
|
||||
.workflow/.csv-wave/{session-id}/
|
||||
+-- tasks.csv # Master state (all tasks, both modes)
|
||||
+-- results.csv # Final results export
|
||||
+-- discoveries.ndjson # Shared discovery board (all agents)
|
||||
+-- context.md # Human-readable report
|
||||
+-- task-analysis.json # Phase 1 analysis output
|
||||
+-- wave-{N}.csv # Temporary per-wave input (csv-wave only)
|
||||
+-- role-instructions/ # Per-role instruction templates
|
||||
| +-- researcher.md
|
||||
| +-- designer.md
|
||||
| +-- reviewer.md
|
||||
| +-- implementer.md
|
||||
+-- artifacts/ # All deliverables
|
||||
| +-- research/
|
||||
| | +-- design-system-analysis.json
|
||||
| | +-- component-inventory.json
|
||||
| | +-- accessibility-audit.json
|
||||
| | +-- design-intelligence.json
|
||||
| +-- design/
|
||||
| | +-- design-tokens.json
|
||||
| | +-- component-specs/
|
||||
| | +-- layout-specs/
|
||||
| +-- audit/
|
||||
| | +-- audit-001.md
|
||||
| +-- build/
|
||||
| +-- token-files/
|
||||
| +-- component-files/
|
||||
+-- interactive/ # Interactive task artifacts
|
||||
| +-- {id}-result.json
|
||||
+-- wisdom/ # Cross-task knowledge
|
||||
+-- learnings.md
|
||||
+-- decisions.md
|
||||
spawn_agent({
|
||||
agent_type: "team_worker",
|
||||
items: [
|
||||
{ type: "text", text: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: <skill_root>/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
requirement: <task-description>
|
||||
inner_loop: false
|
||||
|
||||
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
|
||||
|
||||
{ type: "text", text: `## Task Context
|
||||
task_id: <task-id>
|
||||
title: <task-title>
|
||||
description: <task-description>
|
||||
pipeline_phase: <pipeline-phase>` },
|
||||
|
||||
{ type: "text", text: `## Upstream Context
|
||||
<prev_context>` }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
|
||||
|
||||
## Implementation
|
||||
## User Commands
|
||||
|
||||
### Session Initialization
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View execution status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
## Specs Reference
|
||||
|
||||
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const continueMode = $ARGUMENTS.includes('--continue')
|
||||
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
|
||||
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
|
||||
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
|
||||
|
||||
const requirement = $ARGUMENTS
|
||||
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
|
||||
.trim()
|
||||
|
||||
const slug = requirement.toLowerCase()
|
||||
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
|
||||
.substring(0, 40)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
|
||||
const sessionId = `uds-${slug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
|
||||
|
||||
Bash(`mkdir -p ${sessionFolder}/artifacts/research ${sessionFolder}/artifacts/design/component-specs ${sessionFolder}/artifacts/design/layout-specs ${sessionFolder}/artifacts/audit ${sessionFolder}/artifacts/build/token-files ${sessionFolder}/artifacts/build/component-files ${sessionFolder}/role-instructions ${sessionFolder}/interactive ${sessionFolder}/wisdom`)
|
||||
|
||||
Write(`${sessionFolder}/discoveries.ndjson`, '')
|
||||
Write(`${sessionFolder}/wisdom/learnings.md`, '# Learnings\n')
|
||||
Write(`${sessionFolder}/wisdom/decisions.md`, '# Decisions\n')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 0: Pre-Wave Interactive (Requirement Clarification)
|
||||
|
||||
**Objective**: Parse UI design task, clarify scope/industry/constraints, prepare for decomposition.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. **Parse user task description** from $ARGUMENTS
|
||||
|
||||
2. **Check for existing sessions** (continue mode):
|
||||
- Scan `.workflow/.csv-wave/uds-*/tasks.csv` for sessions with pending tasks
|
||||
- If `--continue`: resume the specified or most recent session, skip to Phase 2
|
||||
- If active session found: ask user whether to resume or start new
|
||||
|
||||
3. **Clarify scope and industry** (skip if AUTO_YES):
|
||||
|
||||
**Scope Selection**:
|
||||
|
||||
| Option | Pipeline | Task Count |
|
||||
|--------|----------|------------|
|
||||
| Single component | component | 4 tasks (linear) |
|
||||
| Component system | system | 7 tasks (dual-track parallel) |
|
||||
| Full design system | full-system | 8 tasks (dual-track + final audit) |
|
||||
|
||||
**Industry Selection**:
|
||||
|
||||
| Option | Strictness |
|
||||
|--------|------------|
|
||||
| SaaS/Tech | standard |
|
||||
| E-commerce/Retail | standard |
|
||||
| Healthcare/Finance | strict (extra accessibility) |
|
||||
| Education/Content | standard |
|
||||
| Other | standard |
|
||||
|
||||
4. **Signal Detection** for pipeline selection:
|
||||
|
||||
| Signal | Keywords | Pipeline Hint |
|
||||
|--------|----------|---------------|
|
||||
| Component | component, button, card, input, modal | component |
|
||||
| System | design system, token, theme, multiple components | system |
|
||||
| Full | complete, full, all components, redesign | full-system |
|
||||
| Accessibility | accessibility, a11y, wcag | component or system |
|
||||
|
||||
5. **Complexity Scoring**:
|
||||
|
||||
| Factor | Points |
|
||||
|--------|--------|
|
||||
| Single component | +1 |
|
||||
| Component system | +2 |
|
||||
| Full design system | +3 |
|
||||
| Accessibility required | +1 |
|
||||
| Multiple industries/constraints | +1 |
|
||||
|
||||
Results: 1-2 component, 3-4 system, 5+ full-system.
|
||||
|
||||
6. **Industry Detection**:
|
||||
|
||||
| Keywords | Industry |
|
||||
|----------|----------|
|
||||
| saas, dashboard, analytics | SaaS/Tech |
|
||||
| shop, cart, checkout | E-commerce |
|
||||
| medical, patient, healthcare | Healthcare |
|
||||
| bank, finance, payment | Finance |
|
||||
| edu, course, learning | Education/Content |
|
||||
| Default | SaaS/Tech |
|
||||
|
||||
7. Record: pipeline_mode, industry, complexity
|
||||
|
||||
**Success Criteria**:
|
||||
- Scope, industry, constraints determined
|
||||
- Pipeline mode selected (component/system/full-system)
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Requirement -> CSV + Classification
|
||||
|
||||
**Objective**: Build task dependency graph, generate tasks.csv and per-role instruction templates.
|
||||
|
||||
**Decomposition Rules**:
|
||||
|
||||
1. **Pipeline Selection** based on scope:
|
||||
|
||||
| Scope | Pipeline | Tasks |
|
||||
|-------|----------|-------|
|
||||
| component | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> BUILD-001 | 4 |
|
||||
| system | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> [DESIGN-002 + BUILD-001] -> AUDIT-002 -> BUILD-002 | 7 |
|
||||
| full-system | system chain + AUDIT-003 after BUILD-002 | 8 |
|
||||
|
||||
2. **Task Description Template**: Every task description uses PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS format
|
||||
|
||||
3. **Role Instruction Generation**: Write per-role instruction templates to `role-instructions/{role}.md` using the base instruction template customized for each role (researcher, designer, reviewer, implementer)
|
||||
|
||||
**Classification Rules**:
|
||||
|
||||
| Task Property | exec_mode |
|
||||
|---------------|-----------|
|
||||
| Research analysis pass (researcher) | `csv-wave` |
|
||||
| Token design pass (designer) | `csv-wave` |
|
||||
| Component spec pass (designer) | `csv-wave` |
|
||||
| Audit pass (reviewer) | `csv-wave` |
|
||||
| Implementation pass (implementer) | `csv-wave` |
|
||||
| GC fix revision (designer) | `csv-wave` |
|
||||
| All standard pipeline tasks | `csv-wave` |
|
||||
|
||||
**Wave Computation**: Kahn's BFS topological sort with depth tracking.
|
||||
|
||||
```javascript
|
||||
// Generate per-role instruction templates
|
||||
for (const role of ['researcher', 'designer', 'reviewer', 'implementer']) {
|
||||
const instruction = generateRoleInstruction(role, sessionFolder)
|
||||
Write(`${sessionFolder}/role-instructions/${role}.md`, instruction)
|
||||
}
|
||||
|
||||
// Generate tasks.csv from pipeline definition
|
||||
const tasks = buildTasksCsv(pipelineMode, requirement, sessionFolder, industry, constraints)
|
||||
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
|
||||
Write(`${sessionFolder}/task-analysis.json`, JSON.stringify(analysisResult, null, 2))
|
||||
```
|
||||
|
||||
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
|
||||
|
||||
**Success Criteria**:
|
||||
- tasks.csv created with valid schema, wave, and exec_mode assignments
|
||||
- Role instruction templates generated in role-instructions/
|
||||
- task-analysis.json written
|
||||
- No circular dependencies
|
||||
- User approved (or AUTO_YES)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Wave Execution Engine (Extended)
|
||||
|
||||
**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation.
|
||||
|
||||
```javascript
|
||||
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
|
||||
let tasks = parseCsv(masterCsv)
|
||||
const maxWave = Math.max(...tasks.map(t => t.wave))
|
||||
let gcRound = 0
|
||||
const MAX_GC_ROUNDS = 2
|
||||
|
||||
for (let wave = 1; wave <= maxWave; wave++) {
|
||||
console.log(`\nWave ${wave}/${maxWave}`)
|
||||
|
||||
// 1. Separate tasks by exec_mode
|
||||
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
|
||||
const csvTasks = waveTasks.filter(t => t.exec_mode === 'csv-wave')
|
||||
const interactiveTasks = waveTasks.filter(t => t.exec_mode === 'interactive')
|
||||
|
||||
// 2. Check dependencies -- skip tasks whose deps failed
|
||||
for (const task of waveTasks) {
|
||||
const depIds = (task.deps || '').split(';').filter(Boolean)
|
||||
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
|
||||
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
|
||||
task.status = 'skipped'
|
||||
task.error = `Dependency failed: ${depIds.filter((id, i) =>
|
||||
['failed','skipped'].includes(depStatuses[i])).join(', ')}`
|
||||
}
|
||||
}
|
||||
|
||||
// 3. Execute pre-wave interactive tasks (if any)
|
||||
const preWaveInteractive = interactiveTasks.filter(t => t.status === 'pending')
|
||||
for (const task of preWaveInteractive) {
|
||||
Read(`agents/gc-loop-handler.md`)
|
||||
const agent = spawn_agent({
|
||||
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: agents/gc-loop-handler.md\n2. Read: ${sessionFolder}/discoveries.ndjson\n\nGoal: ${task.description}\nScope: ${task.title}\nSession: ${sessionFolder}\n\n### Previous Context\n${buildPrevContext(task, tasks)}`
|
||||
})
|
||||
const result = wait({ ids: [agent], timeout_ms: 600000 })
|
||||
if (result.timed_out) {
|
||||
send_input({ id: agent, message: "Please finalize and output current findings." })
|
||||
wait({ ids: [agent], timeout_ms: 120000 })
|
||||
}
|
||||
Write(`${sessionFolder}/interactive/${task.id}-result.json`, JSON.stringify({
|
||||
task_id: task.id, status: "completed", findings: parseFindings(result),
|
||||
timestamp: getUtc8ISOString()
|
||||
}))
|
||||
close_agent({ id: agent })
|
||||
task.status = 'completed'
|
||||
task.findings = parseFindings(result)
|
||||
}
|
||||
|
||||
// 4. Build prev_context for csv-wave tasks
|
||||
const pendingCsvTasks = csvTasks.filter(t => t.status === 'pending')
|
||||
for (const task of pendingCsvTasks) {
|
||||
task.prev_context = buildPrevContext(task, tasks)
|
||||
}
|
||||
|
||||
if (pendingCsvTasks.length > 0) {
|
||||
// 5. Write wave CSV
|
||||
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingCsvTasks))
|
||||
|
||||
// 6. Build instruction per role group
|
||||
const waveInstruction = buildWaveInstruction(pendingCsvTasks, sessionFolder, wave)
|
||||
|
||||
// 7. Execute wave via spawn_agents_on_csv
|
||||
spawn_agents_on_csv({
|
||||
csv_path: `${sessionFolder}/wave-${wave}.csv`,
|
||||
id_column: "id",
|
||||
instruction: waveInstruction,
|
||||
max_concurrency: maxConcurrency,
|
||||
max_runtime_seconds: 900,
|
||||
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
|
||||
output_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
id: { type: "string" },
|
||||
status: { type: "string", enum: ["completed", "failed"] },
|
||||
findings: { type: "string" },
|
||||
artifacts_produced: { type: "string" },
|
||||
audit_score: { type: "string" },
|
||||
audit_signal: { type: "string" },
|
||||
error: { type: "string" }
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
// 8. Merge results into master CSV
|
||||
const results = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
|
||||
for (const r of results) {
|
||||
const t = tasks.find(t => t.id === r.id)
|
||||
if (t) Object.assign(t, r)
|
||||
}
|
||||
|
||||
// 9. GC Loop Check: if a reviewer task returned fix_required
|
||||
const auditResults = results.filter(r => r.id.startsWith('AUDIT') && r.audit_signal === 'fix_required')
|
||||
for (const ar of auditResults) {
|
||||
if (gcRound < MAX_GC_ROUNDS) {
|
||||
gcRound++
|
||||
const fixId = `DESIGN-fix-${gcRound}`
|
||||
const recheckId = `AUDIT-recheck-${gcRound}`
|
||||
tasks.push({
|
||||
id: fixId, title: `Fix audit issues (round ${gcRound})`,
|
||||
description: `PURPOSE: Address audit feedback from ${ar.id} | Success: All critical/high issues resolved\nTASK:\n- Parse audit feedback for specific issues\n- Apply targeted fixes to design tokens/specs\n- Re-validate affected artifacts\nCONTEXT:\n- Session: ${sessionFolder}\n- Upstream: artifacts/audit/\nEXPECTED: Fixed design artifacts\nCONSTRAINTS: Targeted fixes only`,
|
||||
role: 'designer', pipeline_mode: tasks[0].pipeline_mode, scope: 'full',
|
||||
audit_type: '', deps: ar.id, context_from: ar.id,
|
||||
exec_mode: 'csv-wave', wave: wave + 1, status: 'pending',
|
||||
findings: '', artifacts_produced: '', audit_score: '', audit_signal: '', error: ''
|
||||
})
|
||||
tasks.push({
|
||||
id: recheckId, title: `Audit recheck (round ${gcRound})`,
|
||||
description: `PURPOSE: Re-audit after fixes | Success: Score >= 8, critical == 0\nTASK:\n- Execute 5-dimension audit on fixed artifacts\n- Focus on previously flagged issues\nCONTEXT:\n- Session: ${sessionFolder}\n- Audit type: token-audit\nEXPECTED: artifacts/audit/audit-recheck-${gcRound}.md`,
|
||||
role: 'reviewer', pipeline_mode: tasks[0].pipeline_mode, scope: 'full',
|
||||
audit_type: 'token-audit', deps: fixId, context_from: fixId,
|
||||
exec_mode: 'csv-wave', wave: wave + 2, status: 'pending',
|
||||
findings: '', artifacts_produced: '', audit_score: '', audit_signal: '', error: ''
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 10. Update master CSV
|
||||
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
|
||||
|
||||
// 11. Cleanup temp files
|
||||
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
|
||||
|
||||
// 12. Display wave summary
|
||||
const completed = waveTasks.filter(t => t.status === 'completed').length
|
||||
const failed = waveTasks.filter(t => t.status === 'failed').length
|
||||
const skipped = waveTasks.filter(t => t.status === 'skipped').length
|
||||
console.log(`Wave ${wave} Complete: ${completed} completed, ${failed} failed, ${skipped} skipped`)
|
||||
}
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- All waves executed in order
|
||||
- Both csv-wave and interactive tasks handled per wave
|
||||
- Each wave's results merged into master CSV before next wave starts
|
||||
- Dependent tasks skipped when predecessor failed
|
||||
- GC loop (designer <-> reviewer) handled with max 2 rounds
|
||||
- discoveries.ndjson accumulated across all waves and mechanisms
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Post-Wave Interactive (Completion Action)
|
||||
|
||||
**Objective**: Pipeline completion report with deliverables listing and interactive completion choice.
|
||||
|
||||
```javascript
|
||||
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
|
||||
const completed = tasks.filter(t => t.status === 'completed')
|
||||
const failed = tasks.filter(t => t.status === 'failed')
|
||||
|
||||
const deliverables = [
|
||||
{ name: "Design System Analysis", path: `${sessionFolder}/artifacts/research/design-system-analysis.json` },
|
||||
{ name: "Component Inventory", path: `${sessionFolder}/artifacts/research/component-inventory.json` },
|
||||
{ name: "Accessibility Audit", path: `${sessionFolder}/artifacts/research/accessibility-audit.json` },
|
||||
{ name: "Design Intelligence", path: `${sessionFolder}/artifacts/research/design-intelligence.json` },
|
||||
{ name: "Design Tokens", path: `${sessionFolder}/artifacts/design/design-tokens.json` },
|
||||
{ name: "Component Specs", path: `${sessionFolder}/artifacts/design/component-specs/` },
|
||||
{ name: "Audit Reports", path: `${sessionFolder}/artifacts/audit/` },
|
||||
{ name: "Token Files", path: `${sessionFolder}/artifacts/build/token-files/` },
|
||||
{ name: "Component Files", path: `${sessionFolder}/artifacts/build/component-files/` }
|
||||
]
|
||||
|
||||
console.log(`
|
||||
============================================
|
||||
UI DESIGN TEAM COMPLETE
|
||||
|
||||
Pipeline: ${completed.length}/${tasks.length} tasks (${tasks[0]?.pipeline_mode} mode)
|
||||
GC Rounds: ${gcRound}/${MAX_GC_ROUNDS}
|
||||
Session: ${sessionFolder}
|
||||
|
||||
Deliverables:
|
||||
${deliverables.map(d => ` - ${d.name}: ${d.path}`).join('\n')}
|
||||
============================================
|
||||
`)
|
||||
|
||||
if (!AUTO_YES) {
|
||||
// Spawn completion handler interactive agent
|
||||
Read(`agents/completion-handler.md`)
|
||||
const agent = spawn_agent({
|
||||
message: `## TASK ASSIGNMENT\n\n### MANDATORY FIRST STEPS\n1. Read: agents/completion-handler.md\n2. Read: ${sessionFolder}/tasks.csv\n\nGoal: Handle pipeline completion action\nSession: ${sessionFolder}\nDeliverables: ${JSON.stringify(deliverables)}`
|
||||
})
|
||||
const result = wait({ ids: [agent], timeout_ms: 300000 })
|
||||
close_agent({ id: agent })
|
||||
}
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Post-wave interactive processing complete
|
||||
- User informed of deliverables and pipeline status
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Results Aggregation
|
||||
|
||||
**Objective**: Generate final results and human-readable report.
|
||||
|
||||
```javascript
|
||||
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
|
||||
|
||||
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
|
||||
let contextMd = `# UI Design Report\n\n`
|
||||
contextMd += `**Session**: ${sessionId}\n`
|
||||
contextMd += `**Pipeline**: ${tasks[0]?.pipeline_mode} mode\n`
|
||||
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n\n`
|
||||
|
||||
contextMd += `## Summary\n`
|
||||
contextMd += `| Status | Count |\n|--------|-------|\n`
|
||||
contextMd += `| Completed | ${tasks.filter(t => t.status === 'completed').length} |\n`
|
||||
contextMd += `| Failed | ${tasks.filter(t => t.status === 'failed').length} |\n`
|
||||
contextMd += `| Skipped | ${tasks.filter(t => t.status === 'skipped').length} |\n\n`
|
||||
|
||||
const maxWave = Math.max(...tasks.map(t => t.wave))
|
||||
contextMd += `## Wave Execution\n\n`
|
||||
for (let w = 1; w <= maxWave; w++) {
|
||||
const waveTasks = tasks.filter(t => t.wave === w)
|
||||
contextMd += `### Wave ${w}\n\n`
|
||||
for (const t of waveTasks) {
|
||||
const icon = t.status === 'completed' ? '[DONE]' : t.status === 'failed' ? '[FAIL]' : '[SKIP]'
|
||||
contextMd += `${icon} **${t.title}** [${t.role}]`
|
||||
if (t.audit_score) contextMd += ` Score: ${t.audit_score}/10 (${t.audit_signal})`
|
||||
contextMd += ` ${t.findings || ''}\n\n`
|
||||
}
|
||||
}
|
||||
|
||||
contextMd += `## Audit Summary\n\n`
|
||||
const auditResults = tasks.filter(t => t.role === 'reviewer' && t.audit_score)
|
||||
for (const a of auditResults) {
|
||||
contextMd += `- **${a.id}**: Score ${a.audit_score}/10 - ${a.audit_signal}\n`
|
||||
}
|
||||
|
||||
contextMd += `\n## GC Loop Summary\n`
|
||||
contextMd += `- Rounds used: ${gcRound}/${MAX_GC_ROUNDS}\n`
|
||||
|
||||
Write(`${sessionFolder}/context.md`, contextMd)
|
||||
console.log(`Results exported to: ${sessionFolder}/results.csv`)
|
||||
console.log(`Report generated at: ${sessionFolder}/context.md`)
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- results.csv exported (all tasks, both modes)
|
||||
- context.md generated with audit summary
|
||||
- Summary displayed to user
|
||||
|
||||
---
|
||||
|
||||
## Shared Discovery Board Protocol
|
||||
|
||||
All agents (csv-wave and interactive) share a single `discoveries.ndjson` file for cross-task knowledge exchange.
|
||||
|
||||
**Format**: One JSON object per line (NDJSON):
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-03-08T10:00:00Z","worker":"RESEARCH-001","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}
|
||||
{"ts":"2026-03-08T10:05:00Z","worker":"DESIGN-001","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}
|
||||
{"ts":"2026-03-08T10:10:00Z","worker":"BUILD-001","type":"file_modified","data":{"file":"tokens.css","change":"Generated CSS custom properties","lines_added":85}}
|
||||
{"ts":"2026-03-08T10:15:00Z","worker":"AUDIT-001","type":"issue_found","data":{"file":"design-tokens.json","line":0,"severity":"high","description":"Missing dark mode variant for semantic color tokens"}}
|
||||
```
|
||||
|
||||
**Discovery Types**:
|
||||
|
||||
| Type | Data Schema | Description |
|
||||
|------|-------------|-------------|
|
||||
| `tech_stack_detected` | `{stack, framework, ui_lib}` | Tech stack identified by researcher |
|
||||
| `design_pattern_found` | `{pattern_name, location, description}` | Existing design pattern in codebase |
|
||||
| `token_generated` | `{category, count, supports_dark_mode}` | Design token category created |
|
||||
| `file_modified` | `{file, change, lines_added}` | File change recorded |
|
||||
| `issue_found` | `{file, line, severity, description}` | Audit issue discovered |
|
||||
| `anti_pattern_violation` | `{pattern, file, line, description}` | Design anti-pattern detected |
|
||||
| `artifact_produced` | `{name, path, producer, type}` | Deliverable created |
|
||||
|
||||
**Protocol**:
|
||||
1. Agents MUST read discoveries.ndjson at start of execution
|
||||
2. Agents MUST append relevant discoveries during execution
|
||||
3. Agents MUST NOT modify or delete existing entries
|
||||
4. Deduplication by `{type, data.file}` key
|
||||
|
||||
---
|
||||
|
||||
## Pipeline Definitions
|
||||
|
||||
### Component Mode (4 tasks, linear)
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
RESEARCH-001 --> DESIGN-001 --> AUDIT-001 --> BUILD-001
|
||||
[researcher] [designer] [reviewer] [implementer]
|
||||
wave 1 wave 2 wave 3 wave 4
|
||||
.workflow/.team/UDS-<slug>-<date>/
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Team message bus
|
||||
│ └── meta.json # Pipeline config + GC state
|
||||
├── research/ # Researcher output
|
||||
│ ├── design-system-analysis.json
|
||||
│ ├── component-inventory.json
|
||||
│ ├── accessibility-audit.json
|
||||
│ └── design-intelligence.json
|
||||
├── design/ # Designer output
|
||||
│ ├── design-tokens.json
|
||||
│ ├── component-specs/
|
||||
│ └── layout-specs/
|
||||
├── audit/ # Reviewer output
|
||||
│ └── audit-*.md
|
||||
├── build/ # Implementer output
|
||||
│ ├── token-files/
|
||||
│ └── component-files/
|
||||
└── wisdom/ # Cross-task knowledge
|
||||
```
|
||||
|
||||
### System Mode (7 tasks, dual-track parallel)
|
||||
|
||||
```
|
||||
RESEARCH-001 --> DESIGN-001 --> AUDIT-001 --> DESIGN-002 --+
|
||||
[researcher] [designer] [reviewer] [designer] |
|
||||
BUILD-001 --+--> AUDIT-002 --> BUILD-002
|
||||
[implementer] [reviewer] [implementer]
|
||||
wave 1 wave 2 wave 3 wave 4 wave 5 wave 6
|
||||
```
|
||||
|
||||
### Full-System Mode (8 tasks, dual-track + final audit)
|
||||
|
||||
```
|
||||
Same as System + AUDIT-003 after BUILD-002
|
||||
|
||||
BUILD-002 --> AUDIT-003
|
||||
[reviewer: final-audit]
|
||||
wave 6 wave 7
|
||||
```
|
||||
|
||||
### Generator-Critic Loop (designer <-> reviewer)
|
||||
|
||||
```
|
||||
designer (Generator) -> design artifacts -> reviewer (Critic)
|
||||
<- audit feedback <-
|
||||
(max 2 rounds)
|
||||
|
||||
Convergence: audit.score >= 8 AND audit.critical_count === 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Circular dependency | Detect in wave computation, abort with error message |
|
||||
| CSV agent timeout | Mark as failed in results, continue with wave |
|
||||
| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
|
||||
| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
|
||||
| Interactive agent failed | Mark as failed, skip dependents |
|
||||
| All agents in wave failed | Log error, offer retry or abort |
|
||||
| CSV parse error | Validate CSV format before execution, show line number |
|
||||
| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
|
||||
| Audit score < 6 over 2 GC rounds | Escalate to user for manual intervention |
|
||||
| ui-ux-pro-max unavailable | Degrade to LLM general design knowledge |
|
||||
| Task description too vague | request_user_input for clarification in Phase 0 |
|
||||
| Continue mode: no session found | List available sessions, prompt user to select |
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is session initialization, then Phase 0/1
|
||||
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
|
||||
3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
|
||||
4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it
|
||||
5. **Context Propagation**: prev_context built from master CSV, not from memory
|
||||
6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
|
||||
7. **Skip on Failure**: If a dependency failed, skip the dependent task
|
||||
8. **GC Loop Cap**: Max 2 generator-critic rounds between designer and reviewer
|
||||
9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
|
||||
10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Role Constraints (Main Agent)
|
||||
|
||||
**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation.
|
||||
|
||||
15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:
|
||||
- Spawns agents with task assignments
|
||||
- Waits for agent callbacks
|
||||
- Merges results and coordinates workflow
|
||||
- Manages workflow transitions between phases
|
||||
|
||||
16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:
|
||||
- Wait patiently for `wait()` calls to complete
|
||||
- NOT skip workflow steps due to perceived delays
|
||||
- NOT assume agents have failed just because they're taking time
|
||||
- Trust the timeout mechanisms defined in the skill
|
||||
|
||||
17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST:
|
||||
- Use `send_input()` to ask questions or provide clarification
|
||||
- NOT skip the agent or move to next phase prematurely
|
||||
- Give agents opportunity to respond before escalating
|
||||
- Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })`
|
||||
|
||||
18. **No Workflow Shortcuts**: The coordinator MUST NOT:
|
||||
- Skip phases or stages defined in the workflow
|
||||
- Bypass required approval or review steps
|
||||
- Execute dependent tasks before prerequisites complete
|
||||
- Assume task completion without explicit agent callback
|
||||
- Make up or fabricate agent results
|
||||
|
||||
19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience:
|
||||
- Total execution time may range from 30-90 minutes or longer
|
||||
- Each phase may take 10-30 minutes depending on complexity
|
||||
- The coordinator must remain active and attentive throughout the entire process
|
||||
- Do not terminate or skip steps due to time concerns
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown command | Error with available command list |
|
||||
| Role not found | Error with role registry |
|
||||
| Session corruption | Attempt recovery, fallback to manual |
|
||||
| Fast-advance conflict | Coordinator reconciles on next callback |
|
||||
| Completion action fails | Default to Keep Active |
|
||||
| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |
|
||||
|
||||
@@ -1,177 +0,0 @@
|
||||
# Completion Handler Agent
|
||||
|
||||
Handle pipeline completion action for the UI design workflow. Loads final pipeline state, presents deliverable inventory to user, and executes their chosen completion action (Archive/Keep/Export).
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Responsibility**: Pipeline completion action handling (Archive/Keep/Export)
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Read tasks.csv to determine final pipeline state (completed/failed/skipped counts)
|
||||
- Inventory all deliverable artifacts across categories
|
||||
- Present completion summary with deliverable listing to user
|
||||
- Execute user's chosen completion action faithfully
|
||||
- Produce structured output with completion report
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip deliverable inventory before presenting options
|
||||
- Auto-select completion action without user input
|
||||
- Delete or modify design artifacts during completion
|
||||
- Proceed if tasks.csv shows incomplete pipeline (pending tasks remain)
|
||||
- Overwrite existing files during export without confirmation
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Read` | builtin | Load tasks.csv, results, and artifact contents |
|
||||
| `Write` | builtin | Write completion reports and session markers |
|
||||
| `Bash` | builtin | File operations for archive/export |
|
||||
| `Glob` | builtin | Discover deliverable artifacts across directories |
|
||||
| `request_user_input` | builtin | Present completion options and get user choice |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Pipeline State Loading
|
||||
|
||||
**Objective**: Load final pipeline state and inventory all deliverables.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| tasks.csv | Yes | Master state with all task statuses |
|
||||
| Session directory | Yes | `.workflow/.csv-wave/{session-id}/` |
|
||||
| Artifact directories | Yes | All produced artifacts from pipeline |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read tasks.csv -- count tasks by status (completed, failed, skipped, pending)
|
||||
2. Verify no pending tasks remain (warn if pipeline is incomplete)
|
||||
3. Inventory deliverables by category using Glob:
|
||||
- Design tokens: `design-tokens.json`, `design-tokens/*.json`
|
||||
- Component specs: `component-specs/*.md`, `component-specs/*.json`
|
||||
- Layout specs: `layout-specs/*.md`, `layout-specs/*.json`
|
||||
- Audit reports: `audit/*.md`, `audit/*.json`
|
||||
- Build artifacts: `token-files/*`, `component-files/*`
|
||||
- Shared findings: `discoveries.ndjson`
|
||||
- Context report: `context.md`
|
||||
4. For each deliverable, note file size and last modified timestamp
|
||||
|
||||
**Output**: Complete pipeline state with deliverable inventory
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Completion Summary Presentation
|
||||
|
||||
**Objective**: Present pipeline results and deliverable inventory to user.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Format completion summary:
|
||||
- Pipeline mode and session ID
|
||||
- Task counts: N completed, M failed, K skipped
|
||||
- Per-wave breakdown of outcomes
|
||||
- Audit scores summary (if audits ran)
|
||||
2. Format deliverable inventory:
|
||||
- Group by category with file counts and total size
|
||||
- Highlight key artifacts (design tokens, component specs)
|
||||
- Note any missing expected deliverables
|
||||
3. Present three completion options to user via request_user_input:
|
||||
- **Archive & Clean**: Summarize results, mark session complete, clean temp files
|
||||
- **Keep Active**: Keep session directory for follow-up iterations
|
||||
- **Export Results**: Copy deliverables to a user-specified location
|
||||
|
||||
**Output**: User's chosen completion action
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Action Execution
|
||||
|
||||
**Objective**: Execute the user's chosen completion action.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Archive & Clean**:
|
||||
- Generate final results.csv from tasks.csv
|
||||
- Write completion summary to context.md
|
||||
- Mark session as complete (write `.session-complete` marker)
|
||||
- Remove temporary wave CSV files (wave-*.csv)
|
||||
- Preserve all deliverable artifacts and reports
|
||||
|
||||
2. **Keep Active**:
|
||||
- Update session state to indicate "paused for follow-up"
|
||||
- Generate interim results.csv snapshot
|
||||
- Log continuation point in discoveries.ndjson
|
||||
- Report session ID for `--continue` flag usage
|
||||
|
||||
3. **Export Results**:
|
||||
- Ask user for target export directory via request_user_input
|
||||
- Create export directory structure mirroring deliverable categories
|
||||
- Copy all deliverables to target location
|
||||
- Generate export manifest listing all copied files
|
||||
- Optionally archive session after export (ask user)
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Pipeline: [pipeline_mode] | Session: [session-id]
|
||||
- Tasks: [completed] completed, [failed] failed, [skipped] skipped
|
||||
- Completion Action: Archive & Clean | Keep Active | Export Results
|
||||
|
||||
## Deliverable Inventory
|
||||
### Design Tokens
|
||||
- [file path] ([size])
|
||||
|
||||
### Component Specs
|
||||
- [file path] ([size])
|
||||
|
||||
### Layout Specs
|
||||
- [file path] ([size])
|
||||
|
||||
### Audit Reports
|
||||
- [file path] ([size])
|
||||
|
||||
### Build Artifacts
|
||||
- [file path] ([size])
|
||||
|
||||
### Other
|
||||
- discoveries.ndjson ([entries] entries)
|
||||
- context.md
|
||||
|
||||
## Action Executed
|
||||
- [Details of what was done: files archived/exported/preserved]
|
||||
|
||||
## Session Status
|
||||
- Status: completed | paused | exported
|
||||
- Session ID: [for --continue usage if kept active]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| tasks.csv missing or corrupt | Report error, attempt recovery from wave CSVs |
|
||||
| Pending tasks still exist | Warn user, allow completion with advisory |
|
||||
| Deliverable directory empty | Note missing artifacts in summary, proceed |
|
||||
| Export target directory not writable | Report permission error, ask for alternative path |
|
||||
| Export file conflict (existing files) | Ask user: overwrite, skip, or rename |
|
||||
| Session marker already exists | Warn duplicate completion, allow re-export |
|
||||
| Timeout approaching | Output partial inventory with current state |
|
||||
@@ -1,162 +0,0 @@
|
||||
# GC Loop Handler Agent
|
||||
|
||||
Handle audit GC loop escalation decisions for UI design review cycles. Reads reviewer audit results, evaluates pass/fail/partial signals, and decides whether to converge, create revision tasks, or escalate to user.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Responsibility**: Audit GC loop escalation decisions for design review cycles
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Read audit results including audit_signal, audit_score, and audit findings
|
||||
- Evaluate audit outcome against convergence criteria
|
||||
- Track iteration count (max 3 before escalation)
|
||||
- Reference specific audit findings in all decisions
|
||||
- Produce structured output with GC decision and rationale
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip reading audit results before making decisions
|
||||
- Allow more than 3 fix iterations without escalating
|
||||
- Approve designs that received fix_required signal without revision
|
||||
- Create revision tasks unrelated to audit findings
|
||||
- Modify design artifacts directly (designer role handles revisions)
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Read` | builtin | Load audit results, tasks.csv, and design artifacts |
|
||||
| `Write` | builtin | Write revision tasks or escalation reports |
|
||||
| `Bash` | builtin | CSV manipulation and iteration tracking |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Audit Results Loading
|
||||
|
||||
**Objective**: Load and parse reviewer audit output.
|
||||
|
||||
**Input**:
|
||||
|
||||
| Source | Required | Description |
|
||||
|--------|----------|-------------|
|
||||
| Audit task row | Yes | From tasks.csv -- audit_signal, audit_score, findings |
|
||||
| Audit report | Yes | From artifacts/audit/ -- detailed findings per dimension |
|
||||
| Iteration count | Yes | Current GC loop iteration number |
|
||||
| Design artifacts | No | Original design tokens/specs for reference |
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read tasks.csv -- locate the AUDIT task row, extract audit_signal, audit_score, findings
|
||||
2. Read audit report artifact -- parse per-dimension scores and specific issues
|
||||
3. Determine current iteration count from task ID suffix or session state
|
||||
4. Categorize findings by severity:
|
||||
- Critical (blocks approval): accessibility failures, token format violations
|
||||
- High (requires fix): consistency issues, missing states
|
||||
- Medium (recommended): naming improvements, documentation gaps
|
||||
- Low (optional): style preferences, minor suggestions
|
||||
|
||||
**Output**: Parsed audit results with categorized findings
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: GC Decision Evaluation
|
||||
|
||||
**Objective**: Determine loop action based on audit signal and iteration count.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. **Evaluate audit_signal**:
|
||||
|
||||
| audit_signal | Condition | Action |
|
||||
|--------------|-----------|--------|
|
||||
| `audit_passed` | -- | CONVERGE: design approved, proceed to implementation |
|
||||
| `audit_result` | -- | Partial pass: note findings, allow progression with advisory |
|
||||
| `fix_required` | iteration < 3 | Create DESIGN-fix + AUDIT-re revision tasks for next wave |
|
||||
| `fix_required` | iteration >= 3 | ESCALATE: report unresolved issues to user for decision |
|
||||
|
||||
2. **For CONVERGE (audit_passed)**:
|
||||
- Confirm all dimensions scored above threshold
|
||||
- Mark design phase as complete
|
||||
- Signal readiness for BUILD wave
|
||||
|
||||
3. **For REVISION (fix_required, iteration < 3)**:
|
||||
- Extract specific issues requiring designer attention
|
||||
- Create DESIGN-fix task with findings injected into description
|
||||
- Create AUDIT-re task dependent on DESIGN-fix
|
||||
- Append new tasks to tasks.csv with incremented wave number
|
||||
|
||||
4. **For ESCALATE (fix_required, iteration >= 3)**:
|
||||
- Summarize all iterations: what was fixed, what remains
|
||||
- List unresolved Critical/High findings with file references
|
||||
- Present options to user: force-approve, manual fix, abort pipeline
|
||||
|
||||
**Output**: GC decision with supporting rationale
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Decision Reporting
|
||||
|
||||
**Objective**: Produce final GC loop decision report.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Record decision in discoveries.ndjson with iteration context
|
||||
2. Update tasks.csv status for audit task if needed
|
||||
3. Report final decision with specific audit findings referenced
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- GC Decision: CONVERGE | REVISION | ESCALATE
|
||||
- Audit Signal: [audit_passed | audit_result | fix_required]
|
||||
- Audit Score: [N/10]
|
||||
- Iteration: [current] / 3
|
||||
|
||||
## Audit Findings
|
||||
### Critical
|
||||
- [finding with artifact:line reference]
|
||||
|
||||
### High
|
||||
- [finding with artifact:line reference]
|
||||
|
||||
### Medium/Low
|
||||
- [finding summary]
|
||||
|
||||
## Decision Rationale
|
||||
- [Why this decision was made, referencing specific findings]
|
||||
|
||||
## Actions Taken
|
||||
- [Tasks created / status updates / escalation details]
|
||||
|
||||
## Next Step
|
||||
- CONVERGE: Proceed to BUILD wave
|
||||
- REVISION: Execute DESIGN-fix-NNN + AUDIT-re-NNN in next wave
|
||||
- ESCALATE: Awaiting user decision on unresolved findings
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Audit results missing or unreadable | Report missing data, request audit re-run |
|
||||
| audit_signal column empty | Treat as fix_required, log anomaly |
|
||||
| Iteration count unclear | Parse from task ID pattern, default to iteration 1 |
|
||||
| Revision task creation fails | Log error, escalate to user immediately |
|
||||
| Contradictory audit signals (passed but critical findings) | Treat as fix_required, log inconsistency |
|
||||
| Timeout approaching | Output partial decision with current iteration state |
|
||||
@@ -1,509 +0,0 @@
|
||||
# Team UI Design — Agent Instruction
|
||||
|
||||
This instruction is loaded by team-worker agents when spawned with roles: `researcher`, `designer`, `reviewer`, `implementer`.
|
||||
|
||||
---
|
||||
|
||||
## Role-Based Execution
|
||||
|
||||
### Researcher Role
|
||||
|
||||
**Responsibility**: Analyze existing design system, build component inventory, assess accessibility baseline, retrieve design intelligence.
|
||||
|
||||
**Input**:
|
||||
- `id`: Task ID (e.g., `RESEARCH-001`)
|
||||
- `title`: Task title
|
||||
- `description`: Detailed task description with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS
|
||||
- `role`: `researcher`
|
||||
- `pipeline_mode`: `component`, `system`, or `full-system`
|
||||
- `scope`: `full`
|
||||
- `prev_context`: Previous tasks' findings (empty for wave 1)
|
||||
|
||||
**Execution Protocol**:
|
||||
|
||||
1. **Read shared discoveries**:
|
||||
```javascript
|
||||
const discoveries = Read(`{session}/discoveries.ndjson`)
|
||||
```
|
||||
|
||||
2. **Analyze existing design system**:
|
||||
- Scan codebase for design tokens (CSS variables, theme files, config)
|
||||
- Identify styling patterns (CSS-in-JS, Tailwind, styled-components)
|
||||
- Extract color palette, typography scale, spacing system
|
||||
|
||||
3. **Build component inventory**:
|
||||
- List all UI components with props and states
|
||||
- Document component hierarchy and composition patterns
|
||||
- Note accessibility features (ARIA, keyboard nav)
|
||||
|
||||
4. **Assess accessibility baseline**:
|
||||
- Check contrast ratios (WCAG AA/AAA)
|
||||
- Verify semantic HTML usage
|
||||
- Document keyboard navigation support
|
||||
- Note screen reader compatibility
|
||||
|
||||
5. **Retrieve design intelligence** (if ui-ux-pro-max available):
|
||||
- Query for industry best practices
|
||||
- Get component design patterns
|
||||
- Retrieve accessibility guidelines
|
||||
|
||||
6. **Write research artifacts**:
|
||||
```javascript
|
||||
Write(`{session}/artifacts/research/design-system-analysis.json`, JSON.stringify({
|
||||
tech_stack: { framework: "React", ui_lib: "shadcn", styling: "Tailwind" },
|
||||
existing_tokens: { colors: 24, typography: 7, spacing: 6 },
|
||||
patterns: ["Compound components", "Render props"],
|
||||
gaps: ["Missing dark mode", "Inconsistent spacing"]
|
||||
}, null, 2))
|
||||
|
||||
Write(`{session}/artifacts/research/component-inventory.json`, JSON.stringify({
|
||||
components: [
|
||||
{ name: "Button", props: ["variant", "size"], states: ["default", "hover", "active", "disabled"] }
|
||||
]
|
||||
}, null, 2))
|
||||
|
||||
Write(`{session}/artifacts/research/accessibility-audit.json`, JSON.stringify({
|
||||
wcag_level: "AA",
|
||||
contrast_issues: 3,
|
||||
keyboard_nav: "partial",
|
||||
screen_reader: "good"
|
||||
}, null, 2))
|
||||
|
||||
Write(`{session}/artifacts/research/design-intelligence.json`, JSON.stringify({
|
||||
industry: "SaaS/Tech",
|
||||
best_practices: ["8px grid", "4-5 color shades", "Semantic naming"],
|
||||
patterns: ["Button variants", "Form validation states"]
|
||||
}, null, 2))
|
||||
```
|
||||
|
||||
7. **Share discoveries**:
|
||||
```bash
|
||||
echo '{"ts":"2026-03-08T10:00:00Z","worker":"{id}","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}' >> {session}/discoveries.ndjson
|
||||
```
|
||||
|
||||
8. **Report result**:
|
||||
```javascript
|
||||
report_agent_job_result({
|
||||
id: "{id}",
|
||||
status: "completed",
|
||||
findings: "Detected React + shadcn stack. 24 color tokens, 7 typography scales. Missing dark mode variants. WCAG AA baseline with 3 contrast issues.",
|
||||
artifacts_produced: "artifacts/research/design-system-analysis.json;artifacts/research/component-inventory.json;artifacts/research/accessibility-audit.json;artifacts/research/design-intelligence.json",
|
||||
audit_score: "",
|
||||
audit_signal: "",
|
||||
error: ""
|
||||
})
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- All 4 research artifacts produced with valid JSON
|
||||
- Tech stack identified
|
||||
- Component inventory complete
|
||||
- Accessibility baseline documented
|
||||
|
||||
---
|
||||
|
||||
### Designer Role
|
||||
|
||||
**Responsibility**: Generate design tokens (W3C Design Tokens Format) and component specifications.
|
||||
|
||||
**Input**:
|
||||
- `id`: Task ID (e.g., `DESIGN-001`)
|
||||
- `title`: Task title
|
||||
- `description`: Detailed task description
|
||||
- `role`: `designer`
|
||||
- `pipeline_mode`: `component`, `system`, or `full-system`
|
||||
- `scope`: `tokens`, `components`, or `full`
|
||||
- `context_from`: Upstream task IDs (e.g., `RESEARCH-001`)
|
||||
- `prev_context`: Previous tasks' findings
|
||||
|
||||
**Execution Protocol**:
|
||||
|
||||
1. **Read shared discoveries and upstream artifacts**:
|
||||
```javascript
|
||||
const discoveries = Read(`{session}/discoveries.ndjson`)
|
||||
const research = JSON.parse(Read(`{session}/artifacts/research/design-system-analysis.json`))
|
||||
```
|
||||
|
||||
2. **Generate design tokens** (W3C Design Tokens Format):
|
||||
```javascript
|
||||
const tokens = {
|
||||
"color": {
|
||||
"primary": {
|
||||
"$type": "color",
|
||||
"$value": "#3B82F6",
|
||||
"$description": "Primary brand color"
|
||||
},
|
||||
"primary-dark": {
|
||||
"$type": "color",
|
||||
"$value": "#1E40AF",
|
||||
"$description": "Primary color for dark mode"
|
||||
}
|
||||
},
|
||||
"typography": {
|
||||
"font-size-base": {
|
||||
"$type": "dimension",
|
||||
"$value": "16px"
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"space-1": {
|
||||
"$type": "dimension",
|
||||
"$value": "4px"
|
||||
}
|
||||
}
|
||||
}
|
||||
Write(`{session}/artifacts/design/design-tokens.json`, JSON.stringify(tokens, null, 2))
|
||||
```
|
||||
|
||||
3. **Create component specifications**:
|
||||
```markdown
|
||||
# Button Component Specification
|
||||
|
||||
## Overview
|
||||
Primary interactive element for user actions.
|
||||
|
||||
## States
|
||||
1. Default: Base appearance
|
||||
2. Hover: Elevated, color shift
|
||||
3. Active: Pressed state
|
||||
4. Disabled: Reduced opacity, no interaction
|
||||
5. Focus: Keyboard focus ring
|
||||
|
||||
## Variants
|
||||
- Primary: Filled background
|
||||
- Secondary: Outlined
|
||||
- Ghost: Text only
|
||||
|
||||
## Accessibility
|
||||
- ARIA role: button
|
||||
- Keyboard: Enter/Space to activate
|
||||
- Focus visible: 2px outline
|
||||
- Contrast: WCAG AA minimum
|
||||
|
||||
## Token Usage
|
||||
- Background: color.primary
|
||||
- Text: color.on-primary
|
||||
- Padding: spacing.space-3 spacing.space-4
|
||||
- Border radius: border.radius-md
|
||||
```
|
||||
|
||||
4. **Ensure light/dark mode support**:
|
||||
- All color tokens have light and dark variants
|
||||
- Semantic tokens reference base tokens
|
||||
- Theme switching mechanism defined
|
||||
|
||||
5. **Share discoveries**:
|
||||
```bash
|
||||
echo '{"ts":"2026-03-08T10:05:00Z","worker":"{id}","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}' >> {session}/discoveries.ndjson
|
||||
```
|
||||
|
||||
6. **Report result**:
|
||||
```javascript
|
||||
report_agent_job_result({
|
||||
id: "{id}",
|
||||
status: "completed",
|
||||
findings: "Generated design token system with 24 color tokens (light+dark), 7 typography scales, 6 spacing values. Created component spec for Button with all 5 states, ARIA roles, and responsive breakpoints.",
|
||||
artifacts_produced: "artifacts/design/design-tokens.json;artifacts/design/component-specs/button.md",
|
||||
audit_score: "",
|
||||
audit_signal: "",
|
||||
error: ""
|
||||
})
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Design tokens in W3C format
|
||||
- All color tokens have light/dark variants
|
||||
- Component specs include all 5 states
|
||||
- Accessibility requirements documented
|
||||
|
||||
---
|
||||
|
||||
### Reviewer Role
|
||||
|
||||
**Responsibility**: 5-dimension quality audit for design artifacts.
|
||||
|
||||
**Input**:
|
||||
- `id`: Task ID (e.g., `AUDIT-001`)
|
||||
- `title`: Task title
|
||||
- `description`: Detailed task description
|
||||
- `role`: `reviewer`
|
||||
- `pipeline_mode`: `component`, `system`, or `full-system`
|
||||
- `scope`: `full`
|
||||
- `audit_type`: `token-audit`, `component-audit`, or `final-audit`
|
||||
- `context_from`: Upstream task IDs (e.g., `DESIGN-001`)
|
||||
- `prev_context`: Previous tasks' findings
|
||||
|
||||
**Execution Protocol**:
|
||||
|
||||
1. **Read design artifacts**:
|
||||
```javascript
|
||||
const tokens = JSON.parse(Read(`{session}/artifacts/design/design-tokens.json`))
|
||||
const componentSpecs = Glob(`{session}/artifacts/design/component-specs/*.md`)
|
||||
```
|
||||
|
||||
2. **5-Dimension Audit**:
|
||||
|
||||
**Consistency (20%)**:
|
||||
- Token naming follows convention
|
||||
- Semantic tokens reference base tokens correctly
|
||||
- Component specs use consistent terminology
|
||||
|
||||
**Accessibility (25%)**:
|
||||
- Contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI)
|
||||
- All interactive states have focus indicators
|
||||
- ARIA roles and labels defined
|
||||
- Keyboard navigation specified
|
||||
|
||||
**Completeness (20%)**:
|
||||
- All 5 interactive states defined
|
||||
- Light and dark mode for all color tokens
|
||||
- Responsive breakpoints specified
|
||||
- Edge cases documented
|
||||
|
||||
**Quality (15%)**:
|
||||
- Token values follow design principles (8px grid, etc.)
|
||||
- Component specs are clear and actionable
|
||||
- No hardcoded values in specs
|
||||
|
||||
**Industry Compliance (20%)**:
|
||||
- Follows industry best practices (from research)
|
||||
- Meets domain-specific requirements (healthcare: stricter accessibility)
|
||||
- Aligns with design system standards
|
||||
|
||||
3. **Calculate weighted score**:
|
||||
```javascript
|
||||
const score = (consistency * 0.20) + (accessibility * 0.25) + (completeness * 0.20) + (quality * 0.15) + (industry * 0.20)
|
||||
```
|
||||
|
||||
4. **Determine audit signal**:
|
||||
- `audit_passed`: score >= 8.0 AND critical_count === 0
|
||||
- `audit_result`: score >= 6.0 AND critical_count === 0
|
||||
- `fix_required`: score < 6.0 OR critical_count > 0
|
||||
|
||||
5. **Write audit report**:
|
||||
```markdown
|
||||
# Design Audit Report: {id}
|
||||
|
||||
## Overall Score: {score}/10
|
||||
|
||||
## Dimension Scores
|
||||
- Consistency: {consistency}/10 (20%)
|
||||
- Accessibility: {accessibility}/10 (25%)
|
||||
- Completeness: {completeness}/10 (20%)
|
||||
- Quality: {quality}/10 (15%)
|
||||
- Industry: {industry}/10 (20%)
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical (0)
|
||||
(none)
|
||||
|
||||
### High (1)
|
||||
- Missing dark mode variant for semantic color tokens
|
||||
|
||||
### Medium (2)
|
||||
- Border radius not defined for pill variant
|
||||
- Focus ring color not specified
|
||||
|
||||
### Low (3)
|
||||
- Token naming could be more semantic
|
||||
- Component spec missing edge case documentation
|
||||
- Responsive breakpoint values not aligned with 8px grid
|
||||
|
||||
## Recommendations
|
||||
1. Add dark mode variants for all semantic tokens
|
||||
2. Define border-radius-pill token
|
||||
3. Specify focus ring color (accessibility.focus-ring)
|
||||
|
||||
## Verdict: {audit_signal}
|
||||
```
|
||||
|
||||
6. **Share discoveries**:
|
||||
```bash
|
||||
echo '{"ts":"2026-03-08T10:15:00Z","worker":"{id}","type":"issue_found","data":{"file":"design-tokens.json","line":0,"severity":"high","description":"Missing dark mode variant for semantic color tokens"}}' >> {session}/discoveries.ndjson
|
||||
```
|
||||
|
||||
7. **Report result**:
|
||||
```javascript
|
||||
report_agent_job_result({
|
||||
id: "{id}",
|
||||
status: "completed",
|
||||
findings: "Design audit: 8.4/10. Token naming consistent, all color tokens have light/dark variants, contrast ratios meet WCAG AA. Minor: missing border-radius for pill variant.",
|
||||
artifacts_produced: "artifacts/audit/audit-001.md",
|
||||
audit_score: "8.4",
|
||||
audit_signal: "audit_passed",
|
||||
error: ""
|
||||
})
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- All 5 dimensions scored
|
||||
- Audit report written with issue breakdown
|
||||
- Audit signal determined (pass/result/fix_required)
|
||||
- Score >= 8.0 with 0 critical issues for GC convergence
|
||||
|
||||
---
|
||||
|
||||
### Implementer Role
|
||||
|
||||
**Responsibility**: Implement component code from design specs with token consumption and accessibility.
|
||||
|
||||
**Input**:
|
||||
- `id`: Task ID (e.g., `BUILD-001`)
|
||||
- `title`: Task title
|
||||
- `description`: Detailed task description
|
||||
- `role`: `implementer`
|
||||
- `pipeline_mode`: `component`, `system`, or `full-system`
|
||||
- `scope`: `full`
|
||||
- `context_from`: Upstream task IDs (e.g., `AUDIT-001`)
|
||||
- `prev_context`: Previous tasks' findings
|
||||
|
||||
**Execution Protocol**:
|
||||
|
||||
1. **Read design artifacts and audit feedback**:
|
||||
```javascript
|
||||
const tokens = JSON.parse(Read(`{session}/artifacts/design/design-tokens.json`))
|
||||
const componentSpec = Read(`{session}/artifacts/design/component-specs/button.md`)
|
||||
const auditReport = Read(`{session}/artifacts/audit/audit-001.md`)
|
||||
```
|
||||
|
||||
2. **Generate CSS custom properties from tokens**:
|
||||
```css
|
||||
:root {
|
||||
--color-primary: #3B82F6;
|
||||
--color-primary-dark: #1E40AF;
|
||||
--font-size-base: 16px;
|
||||
--space-1: 4px;
|
||||
}
|
||||
|
||||
[data-theme="dark"] {
|
||||
--color-primary: var(--color-primary-dark);
|
||||
}
|
||||
```
|
||||
|
||||
3. **Implement component with all 5 states**:
|
||||
```tsx
|
||||
import React from 'react'
|
||||
|
||||
interface ButtonProps {
|
||||
variant?: 'primary' | 'secondary' | 'ghost'
|
||||
disabled?: boolean
|
||||
children: React.ReactNode
|
||||
}
|
||||
|
||||
export const Button: React.FC<ButtonProps> = ({ variant = 'primary', disabled, children }) => {
|
||||
return (
|
||||
<button
|
||||
className={`btn btn-${variant}`}
|
||||
disabled={disabled}
|
||||
aria-disabled={disabled}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
4. **Add ARIA attributes and keyboard navigation**:
|
||||
- `role="button"` (if not native button)
|
||||
- `aria-disabled` for disabled state
|
||||
- `aria-pressed` for toggle buttons
|
||||
- Focus management with `:focus-visible`
|
||||
|
||||
5. **Validate no hardcoded values**:
|
||||
- All colors use `var(--token-name)`
|
||||
- All spacing uses token variables
|
||||
- All typography uses token variables
|
||||
|
||||
6. **Follow project patterns**:
|
||||
- Match existing component structure
|
||||
- Use same import patterns
|
||||
- Follow naming conventions from research
|
||||
|
||||
7. **Share discoveries**:
|
||||
```bash
|
||||
echo '{"ts":"2026-03-08T10:10:00Z","worker":"{id}","type":"file_modified","data":{"file":"tokens.css","change":"Generated CSS custom properties from design tokens","lines_added":85}}' >> {session}/discoveries.ndjson
|
||||
```
|
||||
|
||||
8. **Report result**:
|
||||
```javascript
|
||||
report_agent_job_result({
|
||||
id: "{id}",
|
||||
status: "completed",
|
||||
findings: "Implemented Button component with all 5 states, ARIA attributes, keyboard navigation. Generated CSS custom properties from design tokens. No hardcoded values.",
|
||||
artifacts_produced: "artifacts/build/token-files/tokens.css;artifacts/build/component-files/Button.tsx",
|
||||
audit_score: "",
|
||||
audit_signal: "",
|
||||
error: ""
|
||||
})
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Component code implements all 5 states
|
||||
- All values use token variables (no hardcoded)
|
||||
- ARIA attributes present
|
||||
- Keyboard navigation functional
|
||||
- Follows project patterns
|
||||
|
||||
---
|
||||
|
||||
## Generator-Critic Loop (Designer <-> Reviewer)
|
||||
|
||||
When reviewer returns `audit_signal: "fix_required"`:
|
||||
|
||||
1. Coordinator creates `DESIGN-fix-{round}` task (max 2 rounds)
|
||||
2. Designer reads audit feedback, applies targeted fixes
|
||||
3. Coordinator creates `AUDIT-recheck-{round}` task
|
||||
4. Reviewer re-audits fixed artifacts
|
||||
5. Convergence: score >= 8.0 AND critical_count === 0
|
||||
|
||||
---
|
||||
|
||||
## Shared Discovery Board
|
||||
|
||||
All roles read/write `{session}/discoveries.ndjson`:
|
||||
|
||||
**Discovery Types**:
|
||||
- `tech_stack_detected`: Tech stack identified
|
||||
- `design_pattern_found`: Existing design pattern
|
||||
- `token_generated`: Design token category created
|
||||
- `file_modified`: File change recorded
|
||||
- `issue_found`: Audit issue discovered
|
||||
- `anti_pattern_violation`: Design anti-pattern detected
|
||||
- `artifact_produced`: Deliverable created
|
||||
|
||||
**Protocol**:
|
||||
1. Read discoveries at start
|
||||
2. Append discoveries during execution (never modify existing)
|
||||
3. Deduplicate by type + data key
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Upstream artifact not found | Report error, mark failed |
|
||||
| Design tokens invalid JSON | Report error, mark failed |
|
||||
| Component spec missing required sections | Report error, mark failed |
|
||||
| Audit score calculation error | Default to 0, report error |
|
||||
| Implementation build fails | Report error, mark failed |
|
||||
| CLI tool timeout | Fallback to direct implementation |
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
All roles use `report_agent_job_result` with this schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "{id}",
|
||||
"status": "completed" | "failed",
|
||||
"findings": "Key discoveries (max 500 chars)",
|
||||
"artifacts_produced": "semicolon-separated paths",
|
||||
"audit_score": "0-10 (reviewer only)",
|
||||
"audit_signal": "audit_passed|audit_result|fix_required (reviewer only)",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,59 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse user task -> detect UI design scope -> build dependency graph -> design pipeline mode.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
| Keywords | Capability | Pipeline Hint |
|
||||
|----------|------------|---------------|
|
||||
| component, button, card, input, modal | component | component |
|
||||
| design system, token, theme | system | system |
|
||||
| complete, full, all components, redesign | full | full-system |
|
||||
| accessibility, a11y, wcag | accessibility | component or system |
|
||||
| implement, build, code | implementation | component |
|
||||
|
||||
## Scope Determination
|
||||
|
||||
| Signal | Pipeline Mode |
|
||||
|--------|---------------|
|
||||
| Single component mentioned | component |
|
||||
| Multiple components or "design system" | system |
|
||||
| "Full design system" or "complete redesign" | full-system |
|
||||
| Unclear | ask user |
|
||||
|
||||
## Complexity Scoring
|
||||
|
||||
| Factor | Points |
|
||||
|--------|--------|
|
||||
| Single component | +1 |
|
||||
| Component system | +2 |
|
||||
| Full design system | +3 |
|
||||
| Accessibility required | +1 |
|
||||
| Multiple industries/constraints | +1 |
|
||||
|
||||
Results: 1-2 Low (component), 3-4 Medium (system), 5+ High (full-system)
|
||||
|
||||
## Industry Detection
|
||||
|
||||
| Keywords | Industry |
|
||||
|----------|----------|
|
||||
| saas, dashboard, analytics | SaaS/Tech |
|
||||
| shop, cart, checkout, e-commerce | E-commerce |
|
||||
| medical, patient, healthcare | Healthcare |
|
||||
| bank, finance, payment | Finance |
|
||||
| edu, course, learning | Education/Content |
|
||||
| Default | SaaS/Tech |
|
||||
|
||||
## Output
|
||||
|
||||
Write scope context to coordinator memory:
|
||||
```json
|
||||
{
|
||||
"pipeline_mode": "<component|system|full-system>",
|
||||
"scope": "<description>",
|
||||
"industry": "<detected-industry>",
|
||||
"complexity": { "score": 0, "level": "Low|Medium|High" }
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,156 @@
|
||||
# Command: Dispatch
|
||||
|
||||
Create the UI design task chain with correct dependencies and structured task descriptions. Supports component, system, and full-system pipeline modes.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| User requirement | From coordinator Phase 1 | Yes |
|
||||
| Session folder | From coordinator Phase 2 | Yes |
|
||||
| Pipeline mode | From tasks.json `pipeline_mode` | Yes |
|
||||
| Industry config | From tasks.json `industry` | Yes |
|
||||
|
||||
1. Load user requirement and design scope from tasks.json
|
||||
2. Load pipeline stage definitions from specs/pipelines.md
|
||||
3. Read `pipeline_mode` and `industry` from tasks.json
|
||||
|
||||
## Phase 3: Task Chain Creation (Mode-Branched)
|
||||
|
||||
### Task Entry Template
|
||||
|
||||
Each task in tasks.json `tasks` object:
|
||||
```json
|
||||
{
|
||||
"<TASK-ID>": {
|
||||
"title": "<concise title>",
|
||||
"description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>\nTASK:\n - <step 1: specific action>\n - <step 2: specific action>\n - <step 3: specific action>\nCONTEXT:\n - Session: <session-folder>\n - Scope: <design-scope>\n - Industry: <industry>\n - Upstream artifacts: <artifact-1>, <artifact-2>\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <deliverable path> + <quality criteria>\nCONSTRAINTS: <scope limits, focus areas>",
|
||||
"role": "<role-name>",
|
||||
"prefix": "<PREFIX>",
|
||||
"deps": ["<dependency-list>"],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Mode Router
|
||||
|
||||
| Mode | Action |
|
||||
|------|--------|
|
||||
| `component` | Create 4 tasks: RESEARCH -> DESIGN -> AUDIT -> BUILD |
|
||||
| `system` | Create 7 tasks: dual-track with 2 sync points |
|
||||
| `full-system` | Create 8 tasks: dual-track with 3 sync points (final audit) |
|
||||
|
||||
---
|
||||
|
||||
### Component Pipeline Task Chain
|
||||
|
||||
**RESEARCH-001** (researcher):
|
||||
```json
|
||||
{
|
||||
"RESEARCH-001": {
|
||||
"title": "Design system analysis and component inventory",
|
||||
"description": "PURPOSE: Analyze existing design system, build component inventory, assess accessibility baseline | Success: 4 research artifacts produced with valid data\nTASK:\n - Analyze existing design tokens and styling patterns\n - Build component inventory with props and states\n - Assess accessibility baseline (WCAG level, ARIA coverage)\n - Retrieve design intelligence via ui-ux-pro-max\nCONTEXT:\n - Session: <session-folder>\n - Scope: <design-scope>\n - Industry: <industry>\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/research/*.json | All 4 research files with valid JSON\nCONSTRAINTS: Read-only analysis | Focus on <design-scope>",
|
||||
"role": "researcher",
|
||||
"prefix": "RESEARCH",
|
||||
"deps": [],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**DESIGN-001** (designer):
|
||||
```json
|
||||
{
|
||||
"DESIGN-001": {
|
||||
"title": "Define component design with tokens and specifications",
|
||||
"description": "PURPOSE: Define component design with tokens and specifications | Success: Design tokens + component spec with all states defined\nTASK:\n - Define design tokens consuming research findings\n - Create component specification with all 5 interactive states\n - Ensure accessibility spec (role, ARIA, keyboard, focus)\n - Reference design intelligence recommendations\nCONTEXT:\n - Session: <session-folder>\n - Scope: <design-scope>\n - Industry: <industry>\n - Upstream artifacts: research/*.json\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/design/design-tokens.json + component-specs/*.md | Complete token system + spec\nCONSTRAINTS: Follow W3C Design Tokens Format | All color tokens need light/dark",
|
||||
"role": "designer",
|
||||
"prefix": "DESIGN",
|
||||
"deps": ["RESEARCH-001"],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**AUDIT-001** (reviewer):
|
||||
```json
|
||||
{
|
||||
"AUDIT-001": {
|
||||
"title": "Audit design for consistency, accessibility, and quality",
|
||||
"description": "PURPOSE: Audit design for consistency, accessibility, and quality | Success: Audit score >= 8 with 0 critical issues\nTASK:\n - Score 5 dimensions: consistency, accessibility, completeness, quality, industry compliance\n - Check token naming, theme completeness, contrast ratios\n - Verify component states and ARIA spec\n - Check against design intelligence anti-patterns\nCONTEXT:\n - Session: <session-folder>\n - Scope: <design-scope>\n - Industry: <industry>\n - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/audit/audit-001.md | 5-dimension scored report\nCONSTRAINTS: Read-only analysis | GC convergence: score >= 8 and 0 critical",
|
||||
"role": "reviewer",
|
||||
"prefix": "AUDIT",
|
||||
"deps": ["DESIGN-001"],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**BUILD-001** (implementer):
|
||||
```json
|
||||
{
|
||||
"BUILD-001": {
|
||||
"title": "Implement component code from design specs",
|
||||
"description": "PURPOSE: Implement component code from design specs | Success: Production code with token consumption and accessibility\nTASK:\n - Generate CSS custom properties from design tokens\n - Implement component with all 5 states\n - Add ARIA attributes and keyboard navigation\n - Validate no hardcoded values\nCONTEXT:\n - Session: <session-folder>\n - Scope: <design-scope>\n - Industry: <industry>\n - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md, audit/audit-001.md\n - Shared memory: <session>/wisdom/.msg/meta.json\nEXPECTED: <session>/build/**/* | Component + tokens CSS/TS + tests\nCONSTRAINTS: Use var(--token-name) only | Follow project patterns",
|
||||
"role": "implementer",
|
||||
"prefix": "BUILD",
|
||||
"deps": ["AUDIT-001"],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### System Pipeline Task Chain (Dual-Track)
|
||||
|
||||
Create tasks in dependency order:
|
||||
|
||||
| Task | Role | deps | Description |
|
||||
|------|------|------|-------------|
|
||||
| RESEARCH-001 | researcher | [] | Design system analysis |
|
||||
| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
|
||||
| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1] |
|
||||
| DESIGN-002 | designer | [AUDIT-001] | Component specification |
|
||||
| BUILD-001 | implementer | [AUDIT-001] | Token code implementation |
|
||||
| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
|
||||
| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
|
||||
|
||||
Task descriptions follow same template as component pipeline, with subject-specific content for tokens vs components and appropriate upstream artifacts.
|
||||
|
||||
---
|
||||
|
||||
### Full-System Pipeline Task Chain
|
||||
|
||||
Same as System Pipeline, plus:
|
||||
|
||||
| Task | Role | deps | Description |
|
||||
|------|------|------|-------------|
|
||||
| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
Verify task chain integrity:
|
||||
|
||||
| Check | Method | Expected |
|
||||
|-------|--------|----------|
|
||||
| Task count correct | tasks.json count | component: 4, system: 7, full-system: 8 |
|
||||
| Dependencies correct | Trace dependency graph | Acyclic, correct deps |
|
||||
| No circular dependencies | Trace dependency graph | Acyclic |
|
||||
| Task IDs use correct prefixes | Pattern check | RESEARCH/DESIGN/AUDIT/BUILD |
|
||||
| Structured descriptions complete | Each has PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | All present |
|
||||
|
||||
If validation fails, fix the specific task and re-validate.
|
||||
@@ -0,0 +1,194 @@
|
||||
# Monitor Pipeline
|
||||
|
||||
Synchronous pipeline coordination using spawn_agent + wait_agent.
|
||||
|
||||
## Constants
|
||||
|
||||
- WORKER_AGENT: team_worker
|
||||
- MAX_GC_ROUNDS: 2
|
||||
|
||||
## Handler Router
|
||||
|
||||
| Source | Handler |
|
||||
|--------|---------|
|
||||
| "capability_gap" | handleAdapt |
|
||||
| "check" or "status" | handleCheck |
|
||||
| "resume" or "continue" | handleResume |
|
||||
| All tasks completed | handleComplete |
|
||||
| Default | handleSpawnNext |
|
||||
|
||||
## handleCallback
|
||||
|
||||
Worker completed (wait_agent returns). Process and advance.
|
||||
|
||||
1. Determine role from completed task prefix:
|
||||
|
||||
| Task Prefix | Role |
|
||||
|-------------|------|
|
||||
| `RESEARCH-*` | researcher |
|
||||
| `DESIGN-*` | designer |
|
||||
| `AUDIT-*` | reviewer |
|
||||
| `BUILD-*` | implementer |
|
||||
|
||||
2. Mark task completed in tasks.json: `state.tasks[taskId].status = 'completed'`
|
||||
3. Record completion in session state
|
||||
|
||||
4. Check checkpoint for completed task:
|
||||
|
||||
| Completed Task | Checkpoint | Action |
|
||||
|---------------|------------|--------|
|
||||
| RESEARCH-001 | - | Notify user: research complete |
|
||||
| DESIGN-001 (tokens) | - | Proceed to AUDIT-001 |
|
||||
| AUDIT-* | QUALITY-001: Sync Point | Check audit signal -> GC loop or unblock parallel |
|
||||
| BUILD-001 (tokens) | - | Check if BUILD-002 ready |
|
||||
| BUILD-002 (components) | - | Check if AUDIT-003 exists (full-system) or handleComplete |
|
||||
|
||||
5. **Sync Point handling** (AUDIT task completed):
|
||||
Read audit signal from result: `audit_passed`, `audit_result`, or `fix_required`
|
||||
|
||||
| Signal | Condition | Action |
|
||||
|--------|-----------|--------|
|
||||
| `audit_passed` | Score >= 8, critical === 0 | GC converged -> record sync_point -> unblock downstream |
|
||||
| `audit_result` | Score 6-7, no critical | gc_rounds < max -> create DESIGN-fix task in tasks.json |
|
||||
| `fix_required` | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) in tasks.json |
|
||||
| Any | gc_rounds >= max | Escalate to user |
|
||||
|
||||
**GC Fix Task Creation** (add to tasks.json):
|
||||
```json
|
||||
{
|
||||
"DESIGN-fix-<round>": {
|
||||
"title": "Address audit feedback",
|
||||
"description": "PURPOSE: Address audit feedback | Success: All critical/high issues resolved\nTASK:\n - Parse audit feedback for specific issues\n - Apply targeted fixes\nCONTEXT:\n - Session: <session-folder>\n - Upstream artifacts: audit/audit-<NNN>.md",
|
||||
"role": "designer",
|
||||
"prefix": "DESIGN",
|
||||
"deps": [],
|
||||
"status": "pending",
|
||||
"findings": "",
|
||||
"error": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
Then create new AUDIT task in tasks.json with deps on fix. Increment gc_state.round.
|
||||
|
||||
**GC Escalation Options** (when max rounds exceeded):
|
||||
1. Accept current design - skip review, continue implementation
|
||||
2. Try one more round
|
||||
3. Terminate
|
||||
|
||||
6. -> handleSpawnNext
|
||||
|
||||
## handleCheck
|
||||
|
||||
Read-only status report from tasks.json, then STOP.
|
||||
|
||||
```
|
||||
Pipeline Status (<pipeline-mode>):
|
||||
[DONE] RESEARCH-001 (researcher) -> research/*.json
|
||||
[DONE] DESIGN-001 (designer) -> design-tokens.json
|
||||
[RUN] AUDIT-001 (reviewer) -> auditing tokens...
|
||||
[WAIT] BUILD-001 (implementer) -> blocked by AUDIT-001
|
||||
[WAIT] DESIGN-002 (designer) -> blocked by AUDIT-001
|
||||
|
||||
GC Rounds: 0/2
|
||||
Sync Points: 0/<expected>
|
||||
Session: <session-id>
|
||||
Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
Output status -- do NOT advance pipeline.
|
||||
|
||||
## handleResume
|
||||
|
||||
1. Audit tasks.json for inconsistencies:
|
||||
- Tasks stuck in "in_progress" -> reset to "pending"
|
||||
- Tasks with completed deps but still "pending" -> include in spawn list
|
||||
2. -> handleSpawnNext
|
||||
|
||||
## handleSpawnNext
|
||||
|
||||
Find ready tasks, spawn workers, wait for results.
|
||||
|
||||
1. Read tasks.json: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
|
||||
2. No ready + work in progress -> report waiting, STOP
|
||||
3. No ready + nothing in progress -> handleComplete
|
||||
4. Has ready -> for each:
|
||||
a. Check inner loop role with active worker -> skip (worker picks up)
|
||||
b. Update task status to in_progress in tasks.json
|
||||
c. team_msg log -> task_unblocked
|
||||
d. Spawn team_worker:
|
||||
|
||||
```javascript
|
||||
// 1) Update status in tasks.json
|
||||
state.tasks[taskId].status = 'in_progress'
|
||||
|
||||
// 2) Spawn worker
|
||||
const agentId = spawn_agent({
|
||||
agent_type: "team_worker",
|
||||
items: [
|
||||
{ type: "text", text: `## Role Assignment
|
||||
role: ${role}
|
||||
role_spec: ${skillRoot}/roles/${role}/role.md
|
||||
session: ${sessionFolder}
|
||||
session_id: ${sessionId}
|
||||
requirement: ${taskDescription}
|
||||
inner_loop: false` },
|
||||
|
||||
{ type: "text", text: `Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` }
|
||||
]
|
||||
})
|
||||
|
||||
// 3) Track agent
|
||||
state.active_agents[taskId] = { agentId, role, started_at: now }
|
||||
|
||||
// 4) Wait for completion
|
||||
wait_agent({ ids: [agentId] })
|
||||
|
||||
// 5) Collect results and update tasks.json
|
||||
state.tasks[taskId].status = 'completed'
|
||||
delete state.active_agents[taskId]
|
||||
```
|
||||
|
||||
**Parallel spawn rules by mode**:
|
||||
|
||||
| Mode | Scenario | Spawn Behavior |
|
||||
|------|----------|---------------|
|
||||
| component | Sequential | One task at a time |
|
||||
| system | After Sync Point 1 | Spawn DESIGN-002 + BUILD-001 in parallel, wait_agent for both |
|
||||
| system | After Sync Point 2 | Spawn BUILD-002 |
|
||||
| full-system | After Sync Point 1 | Spawn DESIGN-002 + BUILD-001 in parallel, wait_agent for both |
|
||||
| full-system | After BUILD-002 | Spawn AUDIT-003 |
|
||||
|
||||
5. Update tasks.json, output summary, STOP
|
||||
|
||||
## handleComplete
|
||||
|
||||
Pipeline done. Generate report and completion action.
|
||||
|
||||
**Completion check by mode**:
|
||||
|
||||
| Mode | Completion Condition |
|
||||
|------|---------------------|
|
||||
| component | All 4 tasks (+ fix tasks) completed |
|
||||
| system | All 7 tasks (+ fix tasks) completed |
|
||||
| full-system | All 8 tasks (+ fix tasks) completed |
|
||||
|
||||
1. If any tasks not completed -> handleSpawnNext
|
||||
2. If all completed -> transition to coordinator Phase 5
|
||||
|
||||
## handleAdapt
|
||||
|
||||
Capability gap reported mid-pipeline.
|
||||
|
||||
1. Parse gap description
|
||||
2. Check if existing role covers it -> redirect
|
||||
3. Role count < 5 -> generate dynamic role spec
|
||||
4. Create new task in tasks.json, spawn worker
|
||||
5. Role count >= 5 -> merge or pause
|
||||
|
||||
## Fast-Advance Reconciliation
|
||||
|
||||
On every coordinator wake:
|
||||
1. Read tasks.json for completed tasks
|
||||
2. Sync active_agents with actual state
|
||||
3. No duplicate spawns
|
||||
179
.codex/skills/team-uidesign/roles/coordinator/role.md
Normal file
179
.codex/skills/team-uidesign/roles/coordinator/role.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# Coordinator Role
|
||||
|
||||
UI Design Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages dual-track task chains (design + implementation), GC loops, sync points.
|
||||
|
||||
## Identity
|
||||
- **Name**: coordinator | **Tag**: [coordinator]
|
||||
- **Responsibility**: Analyze task -> Create session -> Dispatch tasks -> Monitor progress -> Report results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- All output (team_msg, logs) must carry `[coordinator]` identifier
|
||||
- Use `team_worker` agent type for all worker spawns (NOT `general-purpose`)
|
||||
- Dispatch tasks with proper dependency chains and deps in tasks.json
|
||||
- Monitor worker progress via wait_agent and process results
|
||||
- Handle Generator-Critic loops with max 2 iterations
|
||||
- Maintain session state persistence (tasks.json)
|
||||
|
||||
### MUST NOT
|
||||
- Implement domain logic (researching, designing, auditing, building) -- workers handle this
|
||||
- Spawn workers without creating tasks first
|
||||
- Skip sync points when configured
|
||||
- Force-advance pipeline past failed audit
|
||||
- Modify source code or design artifacts directly -- delegate to workers
|
||||
- Omit `[coordinator]` identifier in any output
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (analyze, dispatch, monitor):
|
||||
|
||||
1. Read `commands/<command>.md`
|
||||
2. Follow the workflow defined in the command
|
||||
3. Commands are inline execution guides, NOT separate agents
|
||||
4. Execute synchronously, complete before proceeding
|
||||
|
||||
## Entry Router
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
|
||||
| Interrupted session | Active/paused session exists in .workflow/.team/UDS-* | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
For check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. Scan `.workflow/.team/UDS-*/tasks.json` for active/paused sessions
|
||||
2. No sessions -> Phase 1
|
||||
3. Single session -> reconcile (read tasks.json, reset in_progress->pending, kick first ready task)
|
||||
4. Multiple -> request_user_input for selection
|
||||
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
TEXT-LEVEL ONLY. No source code reading.
|
||||
|
||||
1. Parse task description from arguments
|
||||
2. Detect design scope:
|
||||
|
||||
| Signal | Pipeline Mode |
|
||||
|--------|---------------|
|
||||
| Single component mentioned | component |
|
||||
| Multiple components or "design system" | system |
|
||||
| "Full design system" or "complete redesign" | full-system |
|
||||
| Unclear | ask user |
|
||||
|
||||
3. Ask for missing parameters if scope unclear:
|
||||
```
|
||||
request_user_input({
|
||||
questions: [
|
||||
{ question: "UI design scope?", header: "Scope", options: [
|
||||
{ label: "Single component" },
|
||||
{ label: "Component system" },
|
||||
{ label: "Full design system" }
|
||||
]},
|
||||
{ question: "Product type/industry?", header: "Industry", options: [
|
||||
{ label: "SaaS/Tech" }, { label: "E-commerce" },
|
||||
{ label: "Healthcare/Finance" }, { label: "Education/Content" }, { label: "Other" }
|
||||
]}
|
||||
]
|
||||
})
|
||||
```
|
||||
4. Delegate to `@commands/analyze.md` -> output scope context
|
||||
5. Record: pipeline_mode, industry, complexity
|
||||
|
||||
## Phase 2: Create Session + Initialize
|
||||
|
||||
1. Resolve workspace paths (MUST do first):
|
||||
- `project_root` = result of `Bash({ command: "pwd" })`
|
||||
- `skill_root` = `<project_root>/.codex/skills/team-uidesign`
|
||||
2. Generate session ID: `UDS-<slug>-<YYYY-MM-DD>`
|
||||
3. Create session folder structure:
|
||||
```
|
||||
.workflow/.team/UDS-<slug>-<date>/research/
|
||||
.workflow/.team/UDS-<slug>-<date>/design/component-specs/
|
||||
.workflow/.team/UDS-<slug>-<date>/design/layout-specs/
|
||||
.workflow/.team/UDS-<slug>-<date>/audit/
|
||||
.workflow/.team/UDS-<slug>-<date>/build/token-files/
|
||||
.workflow/.team/UDS-<slug>-<date>/build/component-files/
|
||||
.workflow/.team/UDS-<slug>-<date>/wisdom/
|
||||
.workflow/.team/UDS-<slug>-<date>/.msg/
|
||||
```
|
||||
4. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
|
||||
5. Write initial tasks.json:
|
||||
```json
|
||||
{
|
||||
"session_id": "<id>",
|
||||
"pipeline_mode": "<component|system|full-system>",
|
||||
"industry": "<industry>",
|
||||
"created_at": "<ISO timestamp>",
|
||||
"gc_rounds": 0,
|
||||
"max_gc_rounds": 2,
|
||||
"active_agents": {},
|
||||
"tasks": {}
|
||||
}
|
||||
```
|
||||
6. Do NOT spawn workers yet - deferred to Phase 4
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
Delegate to `@commands/dispatch.md`. Task chains by mode:
|
||||
|
||||
| Mode | Task Chain |
|
||||
|------|------------|
|
||||
| component | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> BUILD-001 |
|
||||
| system | RESEARCH-001 -> DESIGN-001 -> AUDIT-001 -> [DESIGN-002 + BUILD-001] -> AUDIT-002 -> BUILD-002 |
|
||||
| full-system | system chain + AUDIT-003 after BUILD-002 |
|
||||
|
||||
## Phase 4: Spawn-and-Wait
|
||||
|
||||
Delegate to `@commands/monitor.md#handleSpawnNext`:
|
||||
1. Find ready tasks (pending + deps resolved)
|
||||
2. Spawn team_worker agents via spawn_agent, wait_agent for results
|
||||
3. Output status summary
|
||||
4. STOP
|
||||
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
1. Read session state -> collect all results
|
||||
2. List deliverables:
|
||||
|
||||
| Deliverable | Path |
|
||||
|-------------|------|
|
||||
| Design System Analysis | <session>/research/design-system-analysis.json |
|
||||
| Component Inventory | <session>/research/component-inventory.json |
|
||||
| Accessibility Audit | <session>/research/accessibility-audit.json |
|
||||
| Design Intelligence | <session>/research/design-intelligence.json |
|
||||
| Design Tokens | <session>/design/design-tokens.json |
|
||||
| Component Specs | <session>/design/component-specs/*.md |
|
||||
| Audit Reports | <session>/audit/audit-*.md |
|
||||
| Token Files | <session>/build/token-files/* |
|
||||
| Component Files | <session>/build/component-files/* |
|
||||
|
||||
3. Calculate: completed_tasks, gc_rounds, sync_points_passed, final_audit_score
|
||||
4. Output pipeline summary with [coordinator] prefix
|
||||
5. Execute completion action:
|
||||
```
|
||||
request_user_input({
|
||||
questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
|
||||
{ label: "Archive & Clean", description: "Archive session and clean up resources" },
|
||||
{ label: "Keep Active", description: "Keep session for follow-up work" },
|
||||
{ label: "Export Results", description: "Export deliverables to specified location" }
|
||||
]}]
|
||||
})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Reset task to pending, respawn worker |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
| Invalid scope | Reject with error, ask to clarify |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
| GC loop stuck > 2 rounds | Escalate to user: accept / try one more / terminate |
|
||||
69
.codex/skills/team-uidesign/roles/designer/role.md
Normal file
69
.codex/skills/team-uidesign/roles/designer/role.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
role: designer
|
||||
prefix: DESIGN
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Design Token & Component Spec Author
|
||||
|
||||
Define visual language through design tokens (W3C Design Tokens Format) and component specifications. Consume design intelligence from researcher. Act as Generator in the designer<->reviewer Generator-Critic loop.
|
||||
|
||||
## Phase 2: Context & Artifact Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Research artifacts | <session>/research/*.json | Yes |
|
||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
||||
| Audit feedback | <session>/audit/audit-*.md | Only for GC fix tasks |
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Read research findings: design-system-analysis.json, component-inventory.json, accessibility-audit.json
|
||||
3. Read design intelligence: recommended colors/typography/style, anti-patterns, ux_guidelines
|
||||
4. Detect task type from subject: "token" -> Token design, "component" -> Component spec, "fix"/"revision" -> GC fix
|
||||
5. If GC fix task: read latest audit feedback from audit files
|
||||
|
||||
## Phase 3: Design Execution
|
||||
|
||||
**Token System Design (DESIGN-001)**:
|
||||
- Define complete token system following W3C Design Tokens Format
|
||||
- Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide)
|
||||
- All color tokens must have light/dark variants using `$value: { light: ..., dark: ... }`
|
||||
- Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks
|
||||
- Document anti-patterns from design intelligence for implementer reference
|
||||
- Output: `<session>/design/design-tokens.json`
|
||||
|
||||
**Component Specification (DESIGN-002)**:
|
||||
- Define component specs consuming design tokens
|
||||
- Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (default/hover/focus/active/disabled), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints
|
||||
- All interactive states required: default, hover (background/opacity change), focus (outline 2px solid, offset 2px), active (pressed), disabled (opacity 0.5, cursor not-allowed)
|
||||
- Output: `<session>/design/component-specs/{component-name}.md`
|
||||
|
||||
**GC Fix Mode (DESIGN-fix-N)**:
|
||||
- Parse audit feedback for specific issues
|
||||
- Re-read affected design artifacts; apply fixes (token value adjustments, missing states, accessibility gaps, naming fixes)
|
||||
- Re-write affected files; signal `design_revision` instead of `design_ready`
|
||||
|
||||
## Phase 4: Self-Validation & Output
|
||||
|
||||
1. Token integrity checks:
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| tokens_valid | All $value fields non-empty |
|
||||
| theme_complete | Light/dark values for all color tokens |
|
||||
| values_parseable | Valid CSS-parseable values |
|
||||
| no_duplicates | No duplicate token definitions |
|
||||
|
||||
2. Component spec checks:
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| states_complete | All 5 states (default/hover/focus/active/disabled) defined |
|
||||
| a11y_specified | Role, ARIA, keyboard behavior defined |
|
||||
| responsive_defined | At least mobile/desktop breakpoints |
|
||||
| token_refs_valid | All `{token.path}` references resolve to defined tokens |
|
||||
|
||||
3. Update `<session>/wisdom/.msg/meta.json` under `designer` namespace:
|
||||
- Read existing -> merge `{ "designer": { task_type, token_categories, component_count, style_decisions } }` -> write back
|
||||
72
.codex/skills/team-uidesign/roles/implementer/role.md
Normal file
72
.codex/skills/team-uidesign/roles/implementer/role.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
role: implementer
|
||||
prefix: BUILD
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Component Code Builder
|
||||
|
||||
Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.
|
||||
|
||||
## Phase 2: Context & Artifact Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Design tokens | <session>/design/design-tokens.json | Yes (token build) |
|
||||
| Component specs | <session>/design/component-specs/*.md | Yes (component build) |
|
||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
||||
| Latest audit report | <session>/audit/audit-*.md | No |
|
||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation
|
||||
3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build)
|
||||
4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines
|
||||
5. Read latest audit report for approved changes and feedback
|
||||
6. Detect project tech stack from package.json
|
||||
|
||||
## Phase 3: Implementation Execution
|
||||
|
||||
**Token Implementation (BUILD-001)**:
|
||||
- Convert design tokens to production code
|
||||
- Output files in `<session>/build/token-files/`:
|
||||
- `tokens.css`: CSS custom properties with `:root` (light) and `[data-theme="dark"]` selectors, plus `@media (prefers-color-scheme: dark)` fallback
|
||||
- `tokens.ts`: TypeScript constants and types for programmatic access with autocomplete support
|
||||
- `README.md`: Token usage guide
|
||||
- All color tokens must have both light and dark values
|
||||
- Semantic token names must match design token definitions
|
||||
|
||||
**Component Implementation (BUILD-002)**:
|
||||
- Implement component code from design specifications
|
||||
- Per-component output in `<session>/build/component-files/`:
|
||||
- `{ComponentName}.tsx`: React/Vue/Svelte component (match detected stack)
|
||||
- `{ComponentName}.css`: Styles consuming tokens via `var(--token-name)` only
|
||||
- `{ComponentName}.test.tsx`: Basic render + state tests
|
||||
- `index.ts`: Re-export
|
||||
- Requirements: no hardcoded colors/spacing (use design tokens), implement all 5 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
|
||||
- Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
|
||||
- Check implementation against design intelligence anti_patterns
|
||||
|
||||
## Phase 4: Validation & Output
|
||||
|
||||
1. Token build validation:
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| File existence | tokens.css and tokens.ts exist |
|
||||
| Token coverage | All defined tokens present in CSS |
|
||||
| Theme support | Light/dark variants exist |
|
||||
|
||||
2. Component build validation:
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| File existence | At least 3 files per component (component, style, index) |
|
||||
| No hardcoded values | No `#xxx` or `rgb()` in component CSS (only in tokens.css) |
|
||||
| Focus styles | `:focus` or `:focus-visible` defined |
|
||||
| Responsive | `@media` queries present |
|
||||
| Anti-pattern clean | No violations of design intelligence anti_patterns |
|
||||
|
||||
3. Update `<session>/wisdom/.msg/meta.json` under `implementer` namespace:
|
||||
- Read existing -> merge `{ "implementer": { build_type, file_count, output_dir, components_built } }` -> write back
|
||||
82
.codex/skills/team-uidesign/roles/researcher/role.md
Normal file
82
.codex/skills/team-uidesign/roles/researcher/role.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
role: researcher
|
||||
prefix: RESEARCH
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Design System Researcher
|
||||
|
||||
Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.
|
||||
|
||||
## Phase 2: Context & Environment Detection
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path and target scope from task description
|
||||
2. Detect project type and tech stack from package.json or equivalent:
|
||||
|
||||
| Package | Detected Stack |
|
||||
|---------|---------------|
|
||||
| next | nextjs |
|
||||
| react | react |
|
||||
| vue | vue |
|
||||
| svelte | svelte |
|
||||
| @shadcn/ui | shadcn |
|
||||
| (default) | html-tailwind |
|
||||
|
||||
3. Use CLI tools (e.g., `ccw cli -p "..." --tool gemini --mode analysis`) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns
|
||||
4. Read industry context from session config (industry, strictness, must-have features)
|
||||
|
||||
## Phase 3: Research Execution
|
||||
|
||||
Execute 4 analysis streams:
|
||||
|
||||
**Stream 1 -- Design System Analysis**:
|
||||
- Search for existing design tokens (CSS variables, theme configs, token files)
|
||||
- Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
|
||||
- Map color palette, typography scale, spacing system
|
||||
- Find component library usage (MUI, Ant Design, shadcn, custom)
|
||||
- Output: `<session>/research/design-system-analysis.json`
|
||||
|
||||
**Stream 2 -- Component Inventory**:
|
||||
- Find all UI component files; identify props/API surface
|
||||
- Identify states supported (hover, focus, disabled, etc.)
|
||||
- Check accessibility attributes (ARIA labels, roles)
|
||||
- Map inter-component dependencies and usage counts
|
||||
- Output: `<session>/research/component-inventory.json`
|
||||
|
||||
**Stream 3 -- Accessibility Baseline**:
|
||||
- Check ARIA attribute usage patterns, keyboard navigation support
|
||||
- Assess color contrast ratios (if design tokens found)
|
||||
- Find focus management and semantic HTML patterns
|
||||
- Output: `<session>/research/accessibility-audit.json`
|
||||
|
||||
**Stream 4 -- Design Intelligence (ui-ux-pro-max)**:
|
||||
- Call `Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system")` for design system recommendations
|
||||
- Call `Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")` for UX guidelines
|
||||
- Call `Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>")` for stack guidelines
|
||||
- Degradation: when unavailable, use LLM general knowledge, mark `_source: "llm-general-knowledge"`
|
||||
- Output: `<session>/research/design-intelligence.json`
|
||||
|
||||
Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count.
|
||||
|
||||
## Phase 4: Validation & Output
|
||||
|
||||
1. Verify all 4 output files exist and contain valid JSON with required fields:
|
||||
|
||||
| File | Required Fields |
|
||||
|------|----------------|
|
||||
| design-system-analysis.json | existing_tokens, styling_approach |
|
||||
| component-inventory.json | components array |
|
||||
| accessibility-audit.json | wcag_level |
|
||||
| design-intelligence.json | _source, design_system |
|
||||
|
||||
2. If any file missing or invalid, re-run corresponding stream
|
||||
|
||||
3. Update `<session>/wisdom/.msg/meta.json` under `researcher` namespace:
|
||||
- Read existing -> merge `{ "researcher": { detected_stack, component_count, wcag_level, di_source, scope } }` -> write back
|
||||
67
.codex/skills/team-uidesign/roles/reviewer/role.md
Normal file
67
.codex/skills/team-uidesign/roles/reviewer/role.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
role: reviewer
|
||||
prefix: AUDIT
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Design Auditor
|
||||
|
||||
Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.
|
||||
|
||||
## Phase 2: Context & Artifact Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Design artifacts | <session>/design/*.json, <session>/design/component-specs/*.md | Yes |
|
||||
| Design intelligence | <session>/research/design-intelligence.json | Yes |
|
||||
| Audit history | .msg/meta.json -> reviewer namespace | No |
|
||||
| Build artifacts | <session>/build/**/* | Only for final audit |
|
||||
| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit
|
||||
3. Read design intelligence for anti-patterns and ux_guidelines
|
||||
4. Read design artifacts: design-tokens.json (token/component audit), component-specs/*.md (component/final audit), build/**/* (final audit only)
|
||||
5. Load audit_history from meta.json for trend analysis
|
||||
|
||||
## Phase 3: Audit Execution
|
||||
|
||||
Score 5 dimensions on 1-10 scale:
|
||||
|
||||
| Dimension | Weight | Focus |
|
||||
|-----------|--------|-------|
|
||||
| Consistency | 20% | Token usage, naming conventions, visual uniformity |
|
||||
| Accessibility | 25% | WCAG AA compliance, ARIA attributes, keyboard nav, contrast |
|
||||
| Completeness | 20% | All states defined, responsive specs, edge cases |
|
||||
| Quality | 15% | Token reference integrity, documentation clarity, maintainability |
|
||||
| Industry Compliance | 20% | Anti-pattern avoidance, UX best practices, design intelligence adherence |
|
||||
|
||||
**Token Audit**: Naming convention (kebab-case, semantic names), value patterns (consistent units), theme completeness (light+dark for all colors), contrast ratios (text on background >= 4.5:1), minimum font sizes (>= 12px), all categories present, W3C $type metadata, no duplicates.
|
||||
|
||||
**Component Audit**: Token references resolve, naming matches convention, ARIA roles defined, keyboard behavior specified, focus indicator defined, all 5 states present, responsive breakpoints specified, variants documented, clear descriptions.
|
||||
|
||||
**Final Audit (cross-cutting)**: Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns).
|
||||
|
||||
**Score calculation**: `overallScore = round(consistency*0.20 + accessibility*0.25 + completeness*0.20 + quality*0.15 + industryCompliance*0.20)`
|
||||
|
||||
**Signal determination**:
|
||||
|
||||
| Condition | Signal |
|
||||
|-----------|--------|
|
||||
| Score >= 8 AND critical_count === 0 | `audit_passed` (GC CONVERGED) |
|
||||
| Score >= 6 AND critical_count === 0 | `audit_result` (GC REVISION NEEDED) |
|
||||
| Score < 6 OR critical_count > 0 | `fix_required` (CRITICAL FIX NEEDED) |
|
||||
|
||||
## Phase 4: Report & Output
|
||||
|
||||
1. Write audit report to `<session>/audit/audit-{NNN}.md`:
|
||||
- Summary: overall score, signal, critical/high/medium counts
|
||||
- Sync Point Status (if applicable): PASSED/BLOCKED
|
||||
- Dimension Scores table (score/weight/weighted per dimension)
|
||||
- Critical/High/Medium issues with descriptions, locations, fix suggestions
|
||||
- GC Loop Status: signal, action required
|
||||
- Trend analysis (if audit_history exists): improving/stable/declining
|
||||
|
||||
2. Update `<session>/wisdom/.msg/meta.json` under `reviewer` namespace:
|
||||
- Read existing -> merge `{ "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } }` -> write back
|
||||
@@ -1,187 +0,0 @@
|
||||
# Team UI Design -- CSV Schema
|
||||
|
||||
## Master CSV: tasks.csv
|
||||
|
||||
### Column Definitions
|
||||
|
||||
#### Input Columns (Set by Decomposer)
|
||||
|
||||
| Column | Type | Required | Description | Example |
|
||||
|--------|------|----------|-------------|---------|
|
||||
| `id` | string | Yes | Unique task identifier (PREFIX-NNN) | `"RESEARCH-001"` |
|
||||
| `title` | string | Yes | Short task title | `"Design system analysis"` |
|
||||
| `description` | string | Yes | Detailed task description (self-contained) with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS | `"PURPOSE: Analyze existing design system..."` |
|
||||
| `role` | enum | Yes | Worker role: `researcher`, `designer`, `reviewer`, `implementer` | `"researcher"` |
|
||||
| `pipeline_mode` | enum | Yes | Pipeline mode: `component`, `system`, `full-system` | `"component"` |
|
||||
| `scope` | enum | Yes | Task scope: `full`, `tokens`, `components` | `"full"` |
|
||||
| `audit_type` | string | No | Audit type: `token-audit`, `component-audit`, `final-audit` (empty for non-reviewer) | `"token-audit"` |
|
||||
| `deps` | string | No | Semicolon-separated dependency task IDs | `"RESEARCH-001"` |
|
||||
| `context_from` | string | No | Semicolon-separated task IDs for context | `"RESEARCH-001"` |
|
||||
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
|
||||
|
||||
#### Computed Columns (Set by Wave Engine)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `wave` | integer | Wave number (1-based, from topological sort) | `2` |
|
||||
| `prev_context` | string | Aggregated findings from context_from tasks (per-wave CSV only) | `"[RESEARCH-001] Detected React + shadcn stack..."` |
|
||||
|
||||
#### Output Columns (Set by Agent)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` |
|
||||
| `findings` | string | Key discoveries (max 500 chars) | `"Generated 24 color tokens with dark mode..."` |
|
||||
| `artifacts_produced` | string | Semicolon-separated paths of produced artifacts | `"artifacts/research/design-system-analysis.json;artifacts/research/component-inventory.json"` |
|
||||
| `audit_score` | string | Audit weighted score 0-10 (empty for non-reviewer tasks) | `"8.5"` |
|
||||
| `audit_signal` | enum | `audit_passed`, `audit_result`, `fix_required` (empty for non-reviewer) | `"audit_passed"` |
|
||||
| `error` | string | Error message if failed | `""` |
|
||||
|
||||
---
|
||||
|
||||
### exec_mode Values
|
||||
|
||||
| Value | Mechanism | Description |
|
||||
|-------|-----------|-------------|
|
||||
| `csv-wave` | `spawn_agents_on_csv` | One-shot batch execution within wave |
|
||||
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round individual execution |
|
||||
|
||||
Interactive tasks appear in master CSV for dependency tracking but are NOT included in wave-{N}.csv files.
|
||||
|
||||
---
|
||||
|
||||
### Role Prefixes
|
||||
|
||||
| Role | Prefix | Responsibility Type |
|
||||
|------|--------|---------------------|
|
||||
| researcher | RESEARCH | read-only (design system analysis + intelligence retrieval) |
|
||||
| designer | DESIGN | generation (design tokens + component specs, W3C format) |
|
||||
| reviewer | AUDIT | validation (5-dimension quality audit, GC critic) |
|
||||
| implementer | BUILD | code-gen (CSS custom properties + components + accessibility) |
|
||||
|
||||
---
|
||||
|
||||
### Example Data
|
||||
|
||||
```csv
|
||||
id,title,description,role,pipeline_mode,scope,audit_type,deps,context_from,exec_mode,wave,status,findings,artifacts_produced,audit_score,audit_signal,error
|
||||
"RESEARCH-001","Design system analysis","PURPOSE: Analyze existing design system, build component inventory, assess accessibility baseline | Success: 4 research artifacts produced with valid data\nTASK:\n- Analyze existing design tokens and styling patterns\n- Build component inventory with props and states\n- Assess accessibility baseline\n- Retrieve design intelligence via ui-ux-pro-max\nCONTEXT:\n- Session: .workflow/.csv-wave/uds-saas-dashboard-20260308\n- Industry: SaaS/Tech\nEXPECTED: artifacts/research/*.json | All 4 research files with valid JSON\nCONSTRAINTS: Read-only analysis","researcher","component","full","","","","csv-wave","1","pending","","","","",""
|
||||
"DESIGN-001","Design tokens + component spec","PURPOSE: Define design tokens (W3C format) and component specification | Success: Design tokens + component spec with all states defined\nTASK:\n- Define complete token system (color, typography, spacing, shadow, border, breakpoint)\n- Create component specification with all 5 interactive states\n- Ensure accessibility spec\nCONTEXT:\n- Session: .workflow/.csv-wave/uds-saas-dashboard-20260308\n- Upstream: research/*.json\nEXPECTED: artifacts/design/design-tokens.json + component-specs/*.md\nCONSTRAINTS: Follow W3C Design Tokens Format | Light/dark for all color tokens","designer","component","tokens","","RESEARCH-001","RESEARCH-001","csv-wave","2","pending","","","","",""
|
||||
"AUDIT-001","Design audit","PURPOSE: 5-dimension quality audit for consistency, accessibility, completeness, quality, industry compliance | Success: Audit score >= 8 with 0 critical issues\nTASK:\n- Score 5 dimensions (consistency 20%, accessibility 25%, completeness 20%, quality 15%, industry 20%)\n- Check token naming, theme completeness, contrast ratios\n- Verify component states and ARIA spec\nCONTEXT:\n- Session: .workflow/.csv-wave/uds-saas-dashboard-20260308\n- Upstream: design/design-tokens.json, design/component-specs/*.md\nEXPECTED: artifacts/audit/audit-001.md\nCONSTRAINTS: Read-only analysis | GC convergence: score >= 8 and 0 critical","reviewer","component","full","token-audit","DESIGN-001","DESIGN-001","csv-wave","3","pending","","","","",""
|
||||
"BUILD-001","Component implementation","PURPOSE: Implement component code from design specs | Success: Production code with token consumption and accessibility\nTASK:\n- Generate CSS custom properties from design tokens\n- Implement component with all 5 states\n- Add ARIA attributes and keyboard navigation\n- Validate no hardcoded values\nCONTEXT:\n- Session: .workflow/.csv-wave/uds-saas-dashboard-20260308\n- Upstream: design/design-tokens.json, design/component-specs/*.md, audit/audit-001.md\nEXPECTED: artifacts/build/**/*\nCONSTRAINTS: Use var(--token-name) only | Follow project patterns","implementer","component","full","","AUDIT-001","AUDIT-001","csv-wave","4","pending","","","","",""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Column Lifecycle
|
||||
|
||||
```
|
||||
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
|
||||
--------------------- -------------------- -----------------
|
||||
id ----------> id ----------> id
|
||||
title ----------> title ----------> (reads)
|
||||
description ----------> description ----------> (reads)
|
||||
role ----------> role ----------> (reads)
|
||||
pipeline_mode ---------> pipeline_mode ---------> (reads)
|
||||
scope ----------> scope ----------> (reads)
|
||||
audit_type ----------> audit_type ----------> (reads)
|
||||
deps ----------> deps ----------> (reads)
|
||||
context_from----------> context_from----------> (reads)
|
||||
exec_mode ----------> exec_mode ----------> (reads)
|
||||
wave ----------> (reads)
|
||||
prev_context ----------> (reads)
|
||||
status
|
||||
findings
|
||||
artifacts_produced
|
||||
audit_score
|
||||
audit_signal
|
||||
error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Schema (JSON)
|
||||
|
||||
Agent output via `report_agent_job_result` (csv-wave tasks):
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "DESIGN-001",
|
||||
"status": "completed",
|
||||
"findings": "Generated design token system with 24 color tokens (light+dark), 7 typography scales, 6 spacing values. Created component spec for Button with all 5 states, ARIA roles, and responsive breakpoints.",
|
||||
"artifacts_produced": "artifacts/design/design-tokens.json;artifacts/design/component-specs/button.md",
|
||||
"audit_score": "",
|
||||
"audit_signal": "",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
Reviewer agent output example:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "AUDIT-001",
|
||||
"status": "completed",
|
||||
"findings": "Design audit: 8.4/10. Token naming consistent, all color tokens have light/dark variants, contrast ratios meet WCAG AA. Minor: missing border-radius for pill variant.",
|
||||
"artifacts_produced": "artifacts/audit/audit-001.md",
|
||||
"audit_score": "8.4",
|
||||
"audit_signal": "audit_passed",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`.
|
||||
|
||||
---
|
||||
|
||||
## Discovery Types
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `tech_stack_detected` | `data.stack` | `{stack, framework, ui_lib}` | Tech stack identified |
|
||||
| `design_pattern_found` | `data.pattern_name+data.location` | `{pattern_name, location, description}` | Existing design pattern |
|
||||
| `token_generated` | `data.category` | `{category, count, supports_dark_mode}` | Design token category created |
|
||||
| `file_modified` | `data.file` | `{file, change, lines_added}` | File change recorded |
|
||||
| `issue_found` | `data.file+data.line` | `{file, line, severity, description}` | Audit issue discovered |
|
||||
| `anti_pattern_violation` | `data.pattern+data.file` | `{pattern, file, line, description}` | Design anti-pattern detected |
|
||||
| `artifact_produced` | `data.path` | `{name, path, producer, type}` | Deliverable created |
|
||||
|
||||
### Discovery NDJSON Format
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-03-08T10:00:00Z","worker":"RESEARCH-001","type":"tech_stack_detected","data":{"stack":"react","framework":"nextjs","ui_lib":"shadcn"}}
|
||||
{"ts":"2026-03-08T10:05:00Z","worker":"DESIGN-001","type":"token_generated","data":{"category":"color","count":24,"supports_dark_mode":true}}
|
||||
{"ts":"2026-03-08T10:10:00Z","worker":"BUILD-001","type":"file_modified","data":{"file":"tokens.css","change":"Generated CSS custom properties from design tokens","lines_added":85}}
|
||||
{"ts":"2026-03-08T10:15:00Z","worker":"AUDIT-001","type":"issue_found","data":{"file":"design-tokens.json","line":0,"severity":"high","description":"Missing dark mode variant for semantic color tokens"}}
|
||||
```
|
||||
|
||||
> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Mechanism Context Flow
|
||||
|
||||
| Source | Target | Mechanism |
|
||||
|--------|--------|-----------|
|
||||
| CSV task findings | Interactive task | Injected via spawn message or send_input |
|
||||
| Interactive task result | CSV task prev_context | Read from interactive/{id}-result.json |
|
||||
| Any agent discovery | Any agent | Shared via discoveries.ndjson |
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Rule | Check | Error |
|
||||
|------|-------|-------|
|
||||
| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" |
|
||||
| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" |
|
||||
| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" |
|
||||
| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" |
|
||||
| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" |
|
||||
| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" |
|
||||
| Description non-empty | Every task has description | "Empty description for task: {id}" |
|
||||
| Status enum | status in {pending, completed, failed, skipped} | "Invalid status: {status}" |
|
||||
| Role valid | role in {researcher, designer, reviewer, implementer} | "Invalid role: {role}" |
|
||||
| Pipeline mode valid | pipeline_mode in {component, system, full-system} | "Invalid pipeline_mode: {mode}" |
|
||||
| Audit signal valid | audit_signal in {audit_passed, audit_result, fix_required, ""} | "Invalid audit_signal: {signal}" |
|
||||
| Cross-mechanism deps | Interactive to CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" |
|
||||
76
.codex/skills/team-uidesign/specs/pipelines.md
Normal file
76
.codex/skills/team-uidesign/specs/pipelines.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# Pipeline Definitions
|
||||
|
||||
UI design pipeline modes and task registry.
|
||||
|
||||
## Pipeline Modes
|
||||
|
||||
| Mode | Description | Task Count |
|
||||
|------|-------------|------------|
|
||||
| component | Single component: research -> design -> audit -> build | 4 tasks |
|
||||
| system | Design system: dual-track with 2 sync points | 7 tasks |
|
||||
| full-system | Full design system + final integrated audit | 8 tasks |
|
||||
|
||||
## Component Pipeline Task Registry
|
||||
|
||||
| Task ID | Role | blockedBy | Description |
|
||||
|---------|------|-----------|-------------|
|
||||
| RESEARCH-001 | researcher | [] | Design system analysis, component inventory, accessibility baseline |
|
||||
| DESIGN-001 | designer | [RESEARCH-001] | Design tokens + component spec with all 5 interactive states |
|
||||
| AUDIT-001 | reviewer | [DESIGN-001] | 5-dimension audit: consistency, accessibility, completeness, quality, compliance |
|
||||
| BUILD-001 | implementer | [AUDIT-001] | CSS custom properties + component code + ARIA + keyboard navigation |
|
||||
|
||||
## System Pipeline Task Registry
|
||||
|
||||
| Task ID | Role | blockedBy | Description |
|
||||
|---------|------|-----------|-------------|
|
||||
| RESEARCH-001 | researcher | [] | Design system analysis across all components |
|
||||
| DESIGN-001 | designer | [RESEARCH-001] | Token system design |
|
||||
| AUDIT-001 | reviewer | [DESIGN-001] | Token audit [Sync Point 1: QUALITY-001] |
|
||||
| DESIGN-002 | designer | [AUDIT-001] | Component specification (parallel) |
|
||||
| BUILD-001 | implementer | [AUDIT-001] | Token code implementation (parallel) |
|
||||
| AUDIT-002 | reviewer | [DESIGN-002] | Component audit [Sync Point 2] |
|
||||
| BUILD-002 | implementer | [AUDIT-002, BUILD-001] | Component code implementation |
|
||||
|
||||
## Full-System Pipeline Task Registry
|
||||
|
||||
Same as System pipeline, plus:
|
||||
|
||||
| Task ID | Role | blockedBy | Description |
|
||||
|---------|------|-----------|-------------|
|
||||
| AUDIT-003 | reviewer | [BUILD-002] | Final integrated audit (cross-cutting) |
|
||||
|
||||
## Checkpoints / Sync Points
|
||||
|
||||
| Checkpoint | Task | Condition | Action |
|
||||
|------------|------|-----------|--------|
|
||||
| QUALITY-001: Sync Point 1 | AUDIT-001 completes | Score >= 8, critical == 0 | Unblock DESIGN-002 + BUILD-001 (parallel) |
|
||||
| QUALITY-001: GC Loop | AUDIT-* completes | Score < 8 or critical > 0 | Create DESIGN-fix task, new AUDIT task (max 2 rounds) |
|
||||
|
||||
## GC Loop Behavior
|
||||
|
||||
| Signal | Condition | Action |
|
||||
|--------|-----------|--------|
|
||||
| audit_passed | Score >= 8, critical == 0 | GC converged -> record sync_point -> unblock downstream |
|
||||
| audit_result | Score 6-7, no critical | gc_rounds < max -> create DESIGN-fix task |
|
||||
| fix_required | Score < 6 or critical > 0 | gc_rounds < max -> create DESIGN-fix task (CRITICAL) |
|
||||
| Any | gc_rounds >= max | Escalate to user: accept / try one more / terminate |
|
||||
|
||||
## Parallel Spawn Rules
|
||||
|
||||
| Mode | After | Spawn Behavior |
|
||||
|------|-------|----------------|
|
||||
| component | Sequential | One task at a time |
|
||||
| system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
|
||||
| system | AUDIT-002 | Spawn BUILD-002 |
|
||||
| full-system | Sync Point 1 (AUDIT-001) | Spawn DESIGN-002 + BUILD-001 in parallel |
|
||||
| full-system | BUILD-002 | Spawn AUDIT-003 |
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Task | Output Path |
|
||||
|------|-------------|
|
||||
| RESEARCH-001 | <session>/research/*.json |
|
||||
| DESIGN-001 | <session>/design/design-tokens.json + component-specs/*.md |
|
||||
| AUDIT-* | <session>/audit/audit-<NNN>.md |
|
||||
| BUILD-001 | <session>/build/token-files/* |
|
||||
| BUILD-002 | <session>/build/component-files/* |
|
||||
107
.codex/skills/team-uidesign/specs/team-config.json
Normal file
107
.codex/skills/team-uidesign/specs/team-config.json
Normal file
@@ -0,0 +1,107 @@
|
||||
{
|
||||
"team_name": "uidesign",
|
||||
"team_display_name": "UI Design",
|
||||
"description": "UI design team with CP-9 Dual-Track for parallel design and implementation",
|
||||
"version": "1.0.0",
|
||||
|
||||
"roles": {
|
||||
"coordinator": {
|
||||
"task_prefix": null,
|
||||
"responsibility": "Scope assessment, dual-track orchestration, sync point management, GC loop control",
|
||||
"message_types": ["task_unblocked", "sync_checkpoint", "fix_required", "error", "shutdown"]
|
||||
},
|
||||
"researcher": {
|
||||
"task_prefix": "RESEARCH",
|
||||
"responsibility": "Design system analysis, component inventory, accessibility baseline audit",
|
||||
"message_types": ["research_ready", "research_progress", "error"]
|
||||
},
|
||||
"designer": {
|
||||
"task_prefix": "DESIGN",
|
||||
"responsibility": "Design token definition, component specifications, layout design",
|
||||
"message_types": ["design_ready", "design_revision", "design_progress", "error"]
|
||||
},
|
||||
"reviewer": {
|
||||
"task_prefix": "AUDIT",
|
||||
"additional_prefixes": [],
|
||||
"responsibility": "Design consistency audit, accessibility compliance, visual review",
|
||||
"message_types": ["audit_result", "audit_passed", "fix_required", "error"]
|
||||
},
|
||||
"implementer": {
|
||||
"task_prefix": "BUILD",
|
||||
"responsibility": "Component code implementation, CSS generation, design token consumption",
|
||||
"message_types": ["build_complete", "build_progress", "error"]
|
||||
}
|
||||
},
|
||||
|
||||
"pipelines": {
|
||||
"component": {
|
||||
"description": "Single component: research → design → audit → build",
|
||||
"task_chain": ["RESEARCH-001", "DESIGN-001", "AUDIT-001", "BUILD-001"],
|
||||
"complexity": "low"
|
||||
},
|
||||
"system": {
|
||||
"description": "Design system with dual-track: design tokens → audit → parallel build+components → audit → build components",
|
||||
"task_chain": [
|
||||
"RESEARCH-001",
|
||||
"DESIGN-001:tokens", "AUDIT-001",
|
||||
"DESIGN-002:components || BUILD-001:tokens",
|
||||
"AUDIT-002", "BUILD-002:components"
|
||||
],
|
||||
"sync_points": ["AUDIT-001", "AUDIT-002"],
|
||||
"complexity": "medium"
|
||||
},
|
||||
"full-system": {
|
||||
"description": "Complete design system with 3 audit checkpoints",
|
||||
"task_chain": [
|
||||
"RESEARCH-001",
|
||||
"DESIGN-001:tokens", "AUDIT-001",
|
||||
"DESIGN-002:components || BUILD-001:tokens",
|
||||
"AUDIT-002",
|
||||
"BUILD-002:components", "AUDIT-003"
|
||||
],
|
||||
"sync_points": ["AUDIT-001", "AUDIT-002", "AUDIT-003"],
|
||||
"complexity": "high"
|
||||
}
|
||||
},
|
||||
|
||||
"innovation_patterns": {
|
||||
"generator_critic": {
|
||||
"generator": "designer",
|
||||
"critic": "reviewer",
|
||||
"max_rounds": 2,
|
||||
"convergence": "audit.score >= 8 && audit.critical_count === 0",
|
||||
"escalation": "Coordinator intervenes after max rounds"
|
||||
},
|
||||
"shared_memory": {
|
||||
"file": "shared-memory.json",
|
||||
"fields": {
|
||||
"researcher": ["component_inventory", "accessibility_patterns"],
|
||||
"designer": ["design_token_registry", "style_decisions"],
|
||||
"reviewer": ["audit_history"],
|
||||
"implementer": ["component_inventory"]
|
||||
}
|
||||
},
|
||||
"dynamic_pipeline": {
|
||||
"criteria": {
|
||||
"component": "scope.component_count <= 1",
|
||||
"system": "scope.component_count <= 5 && scope.has_token_system",
|
||||
"full-system": "scope.component_count > 5 || scope.is_full_redesign"
|
||||
}
|
||||
},
|
||||
"dual_track": {
|
||||
"pattern": "CP-9",
|
||||
"description": "Design and implementation proceed in parallel after sync checkpoints",
|
||||
"sync_mechanism": "AUDIT tasks serve as sync points between tracks",
|
||||
"fallback": "If dual-track fails, coordinator falls back to sequential execution"
|
||||
}
|
||||
},
|
||||
|
||||
"session_dirs": {
|
||||
"base": ".workflow/.team/UDS-{slug}-{YYYY-MM-DD}/",
|
||||
"research": "research/",
|
||||
"design": "design/",
|
||||
"audit": "audit/",
|
||||
"build": "build/",
|
||||
"messages": ".workflow/.team-msg/{team-name}/"
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user