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,638 +1,142 @@
|
||||
---
|
||||
name: team-ux-improve
|
||||
description: Systematic UX improvement pipeline. Discovers and fixes UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems using scan->diagnose->design->implement->test workflow.
|
||||
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<project-path> [--framework react|vue]\""
|
||||
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 UX improvement. Systematically discovers and fixes UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team ux improve".
|
||||
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
|
||||
# Team UX Improve
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
|
||||
Systematic UX improvement pipeline: scan -> diagnose -> design -> implement -> test. 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`.
|
||||
|
||||
# UX Improvement Pipeline
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
$team-ux-improve "ccw/frontend --framework react"
|
||||
$team-ux-improve -c 4 "src/components"
|
||||
$team-ux-improve -y "app/ui --framework vue"
|
||||
$team-ux-improve --continue "ux-improve-1709856000"
|
||||
```
|
||||
|
||||
**Flags**:
|
||||
- `-y, --yes`: Skip all confirmations (auto mode)
|
||||
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4)
|
||||
- `--continue`: Resume existing session
|
||||
- `--framework react|vue`: Specify UI framework (auto-detected if omitted)
|
||||
|
||||
**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 UX improvement workflow that discovers UI/UX interaction issues (unresponsive buttons, missing feedback, state refresh problems) and fixes them methodically. The pipeline scans for issues, diagnoses root causes, designs solutions, implements fixes, and validates with tests.
|
||||
|
||||
**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary)
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ UX IMPROVEMENT PIPELINE WORKFLOW │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Phase 0: Framework Detection & Exploration (Interactive) │
|
||||
│ ├─ Detect UI framework (React/Vue/etc.) │
|
||||
│ ├─ Explore component patterns and conventions │
|
||||
│ ├─ Build component inventory │
|
||||
│ └─ Output: exploration cache for downstream tasks │
|
||||
│ │
|
||||
│ Phase 1: Requirement → CSV + Classification │
|
||||
│ ├─ Generate scan->diagnose->design->implement->test task chain │
|
||||
│ ├─ Classify tasks: csv-wave (scan/implement) | interactive (design) │
|
||||
│ ├─ Compute dependency waves (topological sort → depth grouping) │
|
||||
│ ├─ 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 (design) │
|
||||
│ │ ├─ 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 (testing) │
|
||||
│ │ ├─ Merge all results into master tasks.csv │
|
||||
│ │ └─ Check: any failed? → skip dependents │
|
||||
│ └─ discoveries.ndjson shared across all modes (append-only) │
|
||||
│ │
|
||||
│ Phase 3: Results Aggregation │
|
||||
│ ├─ Export final results.csv │
|
||||
│ ├─ Generate context.md with all findings │
|
||||
│ ├─ Display summary: issues found/fixed, test pass rate │
|
||||
│ └─ Offer: view results | retry failed | done │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
Skill(skill="team-ux-improve", args="<project-path> [--framework react|vue]")
|
||||
|
|
||||
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 v
|
||||
[team-worker agents, each loads roles/<role>/role.md]
|
||||
scanner diagnoser designer implementer tester
|
||||
```
|
||||
|
||||
---
|
||||
## Role Registry
|
||||
|
||||
## Task Classification Rules
|
||||
| Role | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| scanner | [roles/scanner/role.md](roles/scanner/role.md) | SCAN-* | false |
|
||||
| diagnoser | [roles/diagnoser/role.md](roles/diagnoser/role.md) | DIAG-* | false |
|
||||
| designer | [roles/designer/role.md](roles/designer/role.md) | DESIGN-* | false |
|
||||
| implementer | [roles/implementer/role.md](roles/implementer/role.md) | IMPL-* | true |
|
||||
| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | false |
|
||||
|
||||
Each task is classified by `exec_mode`:
|
||||
## Utility Member Registry
|
||||
|
||||
| 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, clarification, inline utility |
|
||||
**Coordinator-only**: Utility members can only be spawned by Coordinator. Workers CANNOT call spawn_agent() to spawn utility members.
|
||||
|
||||
**Classification Decision**:
|
||||
| Utility Member | Path | Callable By | Purpose |
|
||||
|----------------|------|-------------|---------|
|
||||
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | Coordinator only | Explore codebase for UI component patterns and framework-specific patterns |
|
||||
|
||||
| Task Property | Classification |
|
||||
|---------------|---------------|
|
||||
| Scanning tasks (pattern matching, issue detection) | `csv-wave` |
|
||||
| Diagnosis tasks (root cause analysis) | `csv-wave` |
|
||||
| Design tasks (solution design, user interaction) | `interactive` |
|
||||
| Implementation tasks (code fixes) | `csv-wave` |
|
||||
| Testing tasks (validation, iteration) | `interactive` |
|
||||
| Exploration tasks (framework patterns, component inventory) | `interactive` |
|
||||
## Role Router
|
||||
|
||||
---
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` → `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
## CSV Schema
|
||||
## Shared Constants
|
||||
|
||||
### tasks.csv (Master State)
|
||||
- **Session prefix**: `ux-improve`
|
||||
- **Session path**: `.workflow/.team/ux-improve-<timestamp>/`
|
||||
- **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 test iterations**: 5
|
||||
|
||||
```csv
|
||||
id,title,description,deps,context_from,exec_mode,role,component,wave,status,findings,issues_found,issues_fixed,error
|
||||
EXPLORE-001,Framework Exploration,Explore React component patterns and conventions,,,"interactive",explorer,,1,pending,"","","",""
|
||||
SCAN-001,Scan for UX issues,Scan components for unresponsive buttons and missing feedback,EXPLORE-001,EXPLORE-001,"csv-wave",scanner,Button,2,pending,"","","",""
|
||||
DIAG-001,Diagnose root causes,Analyze root causes of identified UX issues,SCAN-001,SCAN-001,"csv-wave",diagnoser,Button,3,pending,"","","",""
|
||||
DESIGN-001,Design solutions,Design fix approach for UX issues,DIAG-001,DIAG-001,"interactive",designer,Button,4,pending,"","","",""
|
||||
IMPL-001,Implement fixes,Apply fixes to Button component,DESIGN-001,DESIGN-001,"csv-wave",implementer,Button,5,pending,"","","",""
|
||||
TEST-001,Test fixes,Validate fixes and run tests,IMPL-001,IMPL-001,"interactive",tester,Button,6,pending,"","","",""
|
||||
```
|
||||
## Worker Spawn Template
|
||||
|
||||
**Columns**:
|
||||
|
||||
| Column | Phase | Description |
|
||||
|--------|-------|-------------|
|
||||
| `id` | Input | Unique task identifier (string) |
|
||||
| `title` | Input | Short task title |
|
||||
| `description` | Input | Detailed task description |
|
||||
| `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` |
|
||||
| `role` | Input | Role name: explorer, scanner, diagnoser, designer, implementer, tester |
|
||||
| `component` | Input | Component name being processed (empty for exploration) |
|
||||
| `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) |
|
||||
| `issues_found` | Output | Number of issues found (scanner/diagnoser only) |
|
||||
| `issues_fixed` | Output | Number of issues fixed (implementer only) |
|
||||
| `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 |
|
||||
|-------|-----------|---------|----------------|----------|
|
||||
| explorer | ~/.codex/agents/ux-explorer.md | 2.3 | Explore codebase for UI component patterns | pre-wave (Phase 0) |
|
||||
| designer | ~/.codex/agents/ux-designer.md | 2.4 | Design fix approach for UX issues | pre-wave (per component) |
|
||||
| tester | ~/.codex/agents/ux-tester.md | 2.4 | Validate fixes and run tests | post-wave (per component) |
|
||||
|
||||
> **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 3 |
|
||||
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
|
||||
| `context.md` | Human-readable execution report | Created in Phase 3 |
|
||||
| `interactive/{id}-result.json` | Results from interactive tasks | Created per interactive task |
|
||||
| `agents/registry.json` | Active interactive agent tracking | Updated on spawn/close |
|
||||
| `artifacts/scan-report.md` | Scanner findings | Created by scanner |
|
||||
| `artifacts/diagnosis.md` | Diagnoser analysis | Created by diagnoser |
|
||||
| `artifacts/design-guide.md` | Designer solutions | Created by designer |
|
||||
| `artifacts/fixes/` | Implementation files | Created by implementer |
|
||||
| `artifacts/test-report.md` | Tester validation | Created by tester |
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
├── wave-{N}.csv # Temporary per-wave input (csv-wave only)
|
||||
├── interactive/ # Interactive task artifacts
|
||||
│ ├── {id}-result.json # Per-task results
|
||||
│ └── cache-index.json # Shared exploration cache
|
||||
├── agents/
|
||||
│ └── registry.json # Active interactive agent tracking
|
||||
└── artifacts/ # Role deliverables
|
||||
├── scan-report.md
|
||||
├── diagnosis.md
|
||||
├── design-guide.md
|
||||
├── fixes/
|
||||
└── test-report.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: <true|false>
|
||||
|
||||
---
|
||||
Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },
|
||||
|
||||
## Implementation
|
||||
{ type: "text", text: `## Task Context
|
||||
task_id: <task-id>
|
||||
title: <task-title>
|
||||
description: <task-description>
|
||||
pipeline_phase: <pipeline-phase>` },
|
||||
|
||||
### Session Initialization
|
||||
|
||||
```javascript
|
||||
// Parse arguments
|
||||
const args = parseArguments($ARGUMENTS)
|
||||
const autoYes = args.yes || args.y
|
||||
const concurrency = args.concurrency || args.c || 4
|
||||
const continueMode = args.continue
|
||||
const projectPath = args._[0]
|
||||
const framework = args.framework
|
||||
|
||||
// Validate project path
|
||||
if (!projectPath) {
|
||||
throw new Error("Project path required")
|
||||
}
|
||||
|
||||
// Generate session ID
|
||||
const timestamp = Math.floor(Date.now() / 1000)
|
||||
const sessionId = `ux-improve-${timestamp}`
|
||||
const sessionDir = `.workflow/.csv-wave/${sessionId}`
|
||||
|
||||
// Create session structure
|
||||
Bash(`mkdir -p "${sessionDir}/interactive" "${sessionDir}/agents" "${sessionDir}/artifacts/fixes"`)
|
||||
|
||||
// Initialize registry
|
||||
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({
|
||||
active: [],
|
||||
closed: [],
|
||||
created_at: new Date().toISOString()
|
||||
}, null, 2))
|
||||
|
||||
// Initialize discoveries
|
||||
Write(`${sessionDir}/discoveries.ndjson`, '')
|
||||
|
||||
// Store session config
|
||||
Write(`${sessionDir}/config.json`, JSON.stringify({
|
||||
project_path: projectPath,
|
||||
framework: framework || "auto-detect",
|
||||
max_test_iterations: 5
|
||||
}, null, 2))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 0: Framework Detection & Exploration (Interactive)
|
||||
|
||||
**Objective**: Detect UI framework and explore component patterns.
|
||||
|
||||
```javascript
|
||||
// Spawn explorer
|
||||
const explorer = spawn_agent({
|
||||
message: `### MANDATORY FIRST STEPS
|
||||
1. Read: ~/.codex/agents/ux-explorer.md
|
||||
|
||||
---
|
||||
|
||||
## Task Assignment
|
||||
|
||||
**Goal**: Explore codebase for UI component patterns and framework conventions
|
||||
|
||||
**Project Path**: ${projectPath}
|
||||
|
||||
**Framework**: ${framework || "auto-detect"}
|
||||
|
||||
**Session Directory**: ${sessionDir}
|
||||
|
||||
**Deliverables**:
|
||||
- Framework detection (if auto-detect)
|
||||
- Component inventory with file paths
|
||||
- Pattern analysis (state management, event handling, styling)
|
||||
- Exploration cache for downstream tasks
|
||||
|
||||
**Instructions**:
|
||||
1. Detect framework if not specified (check package.json, file extensions)
|
||||
2. Scan for UI components (*.tsx, *.vue, etc.)
|
||||
3. Analyze component patterns and conventions
|
||||
4. Build component inventory
|
||||
5. Cache findings in explorations/cache-index.json
|
||||
6. Output result as JSON with framework and component list`
|
||||
{ type: "text", text: `## Upstream Context
|
||||
<prev_context>` }
|
||||
]
|
||||
})
|
||||
|
||||
// Wait for completion
|
||||
const result = wait({ ids: [explorer], timeout_ms: 600000 })
|
||||
|
||||
if (result.timed_out) {
|
||||
send_input({ id: explorer, message: "Please finalize exploration and output current findings." })
|
||||
const retry = wait({ ids: [explorer], timeout_ms: 120000 })
|
||||
}
|
||||
|
||||
// Store result
|
||||
const explorerOutput = JSON.parse(result.output)
|
||||
Write(`${sessionDir}/interactive/EXPLORE-001-result.json`, JSON.stringify({
|
||||
task_id: "EXPLORE-001",
|
||||
status: "completed",
|
||||
findings: explorerOutput.summary,
|
||||
framework: explorerOutput.framework,
|
||||
component_count: explorerOutput.components.length,
|
||||
timestamp: new Date().toISOString()
|
||||
}, null, 2))
|
||||
|
||||
close_agent({ id: explorer })
|
||||
|
||||
// Update config with detected framework
|
||||
const config = JSON.parse(Read(`${sessionDir}/config.json`))
|
||||
config.framework = explorerOutput.framework
|
||||
Write(`${sessionDir}/config.json`, JSON.stringify(config, null, 2))
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- Framework detected or confirmed
|
||||
- Component inventory created
|
||||
- Exploration cache available for downstream tasks
|
||||
After spawning, use `wait_agent({ ids: [...], timeout_ms: 900000 })` to collect results, then `close_agent({ id })` each worker.
|
||||
|
||||
---
|
||||
## User Commands
|
||||
|
||||
### Phase 1: Requirement → CSV + Classification
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View execution status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
|
||||
**Objective**: Generate task breakdown for UX improvement pipeline per component.
|
||||
## Specs Reference
|
||||
|
||||
```javascript
|
||||
// Load exploration results
|
||||
const explorationResult = JSON.parse(Read(`${sessionDir}/interactive/EXPLORE-001-result.json`))
|
||||
const components = explorationResult.components || []
|
||||
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
|
||||
|
||||
// Generate tasks for each component
|
||||
const allTasks = []
|
||||
let taskCounter = 1
|
||||
## Session Directory
|
||||
|
||||
// Add exploration task (already completed)
|
||||
allTasks.push({
|
||||
id: "EXPLORE-001",
|
||||
title: "Framework Exploration",
|
||||
description: "Explore component patterns and conventions",
|
||||
deps: "",
|
||||
context_from: "",
|
||||
exec_mode: "interactive",
|
||||
role: "explorer",
|
||||
component: "",
|
||||
wave: 1,
|
||||
status: "completed",
|
||||
findings: explorationResult.findings,
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
// For each component, create pipeline: scan -> diagnose -> design -> implement -> test
|
||||
for (const component of components) {
|
||||
const compName = component.name
|
||||
const compPath = component.path
|
||||
|
||||
// Scan task (csv-wave)
|
||||
const scanId = `SCAN-${String(taskCounter).padStart(3, '0')}`
|
||||
allTasks.push({
|
||||
id: scanId,
|
||||
title: `Scan ${compName}`,
|
||||
description: `Scan ${compName} component for UX issues: unresponsive buttons, missing feedback, state refresh problems\n\nFile: ${compPath}`,
|
||||
deps: "EXPLORE-001",
|
||||
context_from: "EXPLORE-001",
|
||||
exec_mode: "csv-wave",
|
||||
role: "scanner",
|
||||
component: compName,
|
||||
wave: 0, // Computed later
|
||||
status: "pending",
|
||||
findings: "",
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
// Diagnose task (csv-wave)
|
||||
const diagId = `DIAG-${String(taskCounter).padStart(3, '0')}`
|
||||
allTasks.push({
|
||||
id: diagId,
|
||||
title: `Diagnose ${compName}`,
|
||||
description: `Analyze root causes of UX issues in ${compName}\n\nFile: ${compPath}`,
|
||||
deps: scanId,
|
||||
context_from: scanId,
|
||||
exec_mode: "csv-wave",
|
||||
role: "diagnoser",
|
||||
component: compName,
|
||||
wave: 0,
|
||||
status: "pending",
|
||||
findings: "",
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
// Design task (interactive)
|
||||
const designId = `DESIGN-${String(taskCounter).padStart(3, '0')}`
|
||||
allTasks.push({
|
||||
id: designId,
|
||||
title: `Design fixes for ${compName}`,
|
||||
description: `Design fix approach for UX issues in ${compName}\n\nFile: ${compPath}`,
|
||||
deps: diagId,
|
||||
context_from: diagId,
|
||||
exec_mode: "interactive",
|
||||
role: "designer",
|
||||
component: compName,
|
||||
wave: 0,
|
||||
status: "pending",
|
||||
findings: "",
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
// Implement task (csv-wave)
|
||||
const implId = `IMPL-${String(taskCounter).padStart(3, '0')}`
|
||||
allTasks.push({
|
||||
id: implId,
|
||||
title: `Implement fixes for ${compName}`,
|
||||
description: `Apply fixes to ${compName} component\n\nFile: ${compPath}`,
|
||||
deps: designId,
|
||||
context_from: designId,
|
||||
exec_mode: "csv-wave",
|
||||
role: "implementer",
|
||||
component: compName,
|
||||
wave: 0,
|
||||
status: "pending",
|
||||
findings: "",
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
// Test task (interactive)
|
||||
const testId = `TEST-${String(taskCounter).padStart(3, '0')}`
|
||||
allTasks.push({
|
||||
id: testId,
|
||||
title: `Test fixes for ${compName}`,
|
||||
description: `Validate fixes and run tests for ${compName}\n\nFile: ${compPath}`,
|
||||
deps: implId,
|
||||
context_from: implId,
|
||||
exec_mode: "interactive",
|
||||
role: "tester",
|
||||
component: compName,
|
||||
wave: 0,
|
||||
status: "pending",
|
||||
findings: "",
|
||||
issues_found: "",
|
||||
issues_fixed: "",
|
||||
error: ""
|
||||
})
|
||||
|
||||
taskCounter++
|
||||
}
|
||||
|
||||
// Compute waves via topological sort
|
||||
const tasksWithWaves = computeWaves(allTasks)
|
||||
|
||||
// Write master CSV
|
||||
writeMasterCSV(`${sessionDir}/tasks.csv`, tasksWithWaves)
|
||||
|
||||
// User validation (skip if autoYes)
|
||||
if (!autoYes) {
|
||||
const approval = request_user_input({
|
||||
questions: [{
|
||||
id: "task_approval",
|
||||
question: `Generated ${tasksWithWaves.length} tasks for ${components.length} components. Proceed?`,
|
||||
header: "Validate",
|
||||
options: [
|
||||
{ label: "Proceed (Recommended)", description: "Start UX improvement pipeline" },
|
||||
{ label: "Cancel", description: "Abort workflow" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
if (approval.answers.task_approval.answers[0] !== "Proceed (Recommended)") {
|
||||
throw new Error("User cancelled workflow")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- tasks.csv created with valid schema, wave, and exec_mode assignments
|
||||
- No circular dependencies
|
||||
- User approved (or AUTO_YES)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Wave Execution Engine (Extended)
|
||||
|
||||
**Objective**: Execute tasks wave-by-wave with hybrid mechanism support.
|
||||
|
||||
(Implementation follows same pattern as team-roadmap-dev Phase 2, adapted for UX improvement roles)
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Results Aggregation
|
||||
|
||||
**Objective**: Generate final results and human-readable report.
|
||||
|
||||
```javascript
|
||||
// Load final master CSV
|
||||
const finalCSV = readMasterCSV(`${sessionDir}/tasks.csv`)
|
||||
|
||||
// Calculate metrics
|
||||
const completed = finalCSV.filter(t => t.status === 'completed').length
|
||||
const failed = finalCSV.filter(t => t.status === 'failed').length
|
||||
const skipped = finalCSV.filter(t => t.status === 'skipped').length
|
||||
const totalIssuesFound = finalCSV.reduce((sum, t) => sum + (parseInt(t.issues_found) || 0), 0)
|
||||
const totalIssuesFixed = finalCSV.reduce((sum, t) => sum + (parseInt(t.issues_fixed) || 0), 0)
|
||||
|
||||
// Export results.csv
|
||||
writeFinalResults(`${sessionDir}/results.csv`, finalCSV)
|
||||
|
||||
// Generate context.md
|
||||
const contextMd = generateUXContextReport(finalCSV, sessionDir, {
|
||||
totalIssuesFound,
|
||||
totalIssuesFixed
|
||||
})
|
||||
Write(`${sessionDir}/context.md`, contextMd)
|
||||
|
||||
// Cleanup active agents
|
||||
const registry = JSON.parse(Read(`${sessionDir}/agents/registry.json`))
|
||||
for (const agent of registry.active) {
|
||||
close_agent({ id: agent.id })
|
||||
}
|
||||
registry.active = []
|
||||
Write(`${sessionDir}/agents/registry.json`, JSON.stringify(registry, null, 2))
|
||||
|
||||
// Display summary
|
||||
console.log(`\n=== UX Improvement Pipeline Complete ===`)
|
||||
console.log(`Completed: ${completed}`)
|
||||
console.log(`Failed: ${failed}`)
|
||||
console.log(`Skipped: ${skipped}`)
|
||||
console.log(`Issues Found: ${totalIssuesFound}`)
|
||||
console.log(`Issues Fixed: ${totalIssuesFixed}`)
|
||||
console.log(`Fix Rate: ${totalIssuesFound > 0 ? Math.round(totalIssuesFixed / totalIssuesFound * 100) : 0}%`)
|
||||
console.log(`\nResults: ${sessionDir}/results.csv`)
|
||||
console.log(`Report: ${sessionDir}/context.md`)
|
||||
|
||||
// Offer next steps
|
||||
const nextStep = request_user_input({
|
||||
questions: [{
|
||||
id: "completion",
|
||||
question: "UX Improvement pipeline complete. What would you like to do?",
|
||||
header: "Done",
|
||||
options: [
|
||||
{ label: "Archive (Recommended)", description: "Archive session and clean up team resources" },
|
||||
{ label: "Keep Active", description: "Keep session for follow-up work" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
if (nextStep.answers.completion.answers[0] === "Archive (Recommended)") {
|
||||
Bash(`tar -czf "${sessionDir}.tar.gz" "${sessionDir}" && rm -rf "${sessionDir}"`)
|
||||
console.log(`Session archived to ${sessionDir}.tar.gz`)
|
||||
}
|
||||
.workflow/.team/ux-improve-<timestamp>/
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Team message bus
|
||||
│ └── meta.json # Pipeline config + role state snapshot
|
||||
├── artifacts/ # Role deliverables
|
||||
│ ├── scan-report.md # Scanner output
|
||||
│ ├── diagnosis.md # Diagnoser output
|
||||
│ ├── design-guide.md # Designer output
|
||||
│ ├── fixes/ # Implementer output
|
||||
│ └── test-report.md # Tester output
|
||||
├── explorations/ # Explorer cache
|
||||
│ └── cache-index.json
|
||||
└── wisdom/ # Session knowledge base
|
||||
├── contributions/ # Worker contributions (write-only for workers)
|
||||
├── principles/
|
||||
├── patterns/
|
||||
└── anti-patterns/
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- results.csv exported with UX metrics
|
||||
- context.md generated with issue summary
|
||||
- All interactive agents closed
|
||||
- Summary displayed to user
|
||||
|
||||
---
|
||||
|
||||
## Shared Discovery Board Protocol
|
||||
|
||||
All agents share `discoveries.ndjson` for UX findings.
|
||||
|
||||
**Discovery Types**:
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `ux_issue` | `component+type` | `{component, type, description, severity}` | UX issues discovered |
|
||||
| `pattern` | `pattern` | `{pattern, files[], description}` | UI patterns identified |
|
||||
| `fix_approach` | `component+issue` | `{component, issue, approach, rationale}` | Fix strategies |
|
||||
| `test_result` | `component+test` | `{component, test, status, details}` | Test outcomes |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Framework detection fails | request_user_input for framework selection |
|
||||
| No components found | Complete with empty report, note in findings |
|
||||
| Circular dependency | Detect in wave computation, abort with error |
|
||||
| CSV agent timeout | Mark as failed, continue with wave |
|
||||
| Interactive agent timeout | Urge convergence via send_input |
|
||||
| Test iterations exceeded (5) | Accept current state, continue |
|
||||
| All agents in wave failed | Log error, offer retry or abort |
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown command | Error with available command list |
|
||||
| Role not found | Error with role registry |
|
||||
| Project path invalid | Re-prompt user for valid path |
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is session initialization, then Phase 0
|
||||
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes
|
||||
3. **CSV is Source of Truth**: Master tasks.csv holds all state
|
||||
4. **CSV First**: Default to csv-wave; use interactive for design/testing
|
||||
5. **Context Propagation**: prev_context built from master CSV
|
||||
6. **Discovery Board is Append-Only**: Never clear discoveries.ndjson
|
||||
7. **Skip on Failure**: If dependency failed, skip dependent task
|
||||
8. **Lifecycle Balance**: Every spawn_agent has matching close_agent
|
||||
9. **Cleanup Temp Files**: Remove wave-{N}.csv after merge
|
||||
10. **DO NOT STOP**: Continuous execution until all waves complete
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
| Framework detection fails | request_user_input for framework selection |
|
||||
| Session corruption | Attempt recovery, fallback to manual |
|
||||
| Fast-advance conflict | Coordinator reconciles on next callback |
|
||||
| No UI issues found | Complete with empty fix list, generate clean bill report |
|
||||
| Test iterations exceeded | Accept current state, continue to completion |
|
||||
|
||||
@@ -1,136 +0,0 @@
|
||||
# UX Designer Agent
|
||||
|
||||
Interactive agent for designing fix approaches for identified UX issues. Proposes solutions and may interact with user for clarification.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/ux-designer.md`
|
||||
- **Responsibility**: Solution design for UX issues
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Design fix approaches for all identified issues
|
||||
- Consider framework patterns and conventions
|
||||
- Generate design guide for implementer
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Execute implementation directly
|
||||
- Skip issue analysis step
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Read` | File I/O | Load diagnosis, exploration cache |
|
||||
| `Write` | File I/O | Generate design guide |
|
||||
| `request_user_input` | Human interaction | Clarify design decisions if needed |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Issue Analysis
|
||||
|
||||
**Objective**: Analyze diagnosed issues and understand context.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read diagnosis findings from prev_context
|
||||
2. Load exploration cache for framework patterns
|
||||
3. Read discoveries.ndjson for related findings
|
||||
4. Categorize issues by type and severity
|
||||
|
||||
**Output**: Issue analysis summary
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Solution Design
|
||||
|
||||
**Objective**: Design fix approaches for each issue.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. For each issue:
|
||||
- Identify root cause from diagnosis
|
||||
- Propose fix approach following framework patterns
|
||||
- Consider side effects and edge cases
|
||||
- Define validation criteria
|
||||
2. Prioritize fixes by severity
|
||||
3. Document rationale for each approach
|
||||
|
||||
**Output**: Fix approaches per issue
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Design Guide Generation
|
||||
|
||||
**Objective**: Generate design guide for implementer.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Format design guide:
|
||||
```markdown
|
||||
# Design Guide: {Component}
|
||||
|
||||
## Issues to Fix
|
||||
|
||||
### Issue 1: {description}
|
||||
- **Severity**: {high/medium/low}
|
||||
- **Root Cause**: {cause}
|
||||
- **Fix Approach**: {approach}
|
||||
- **Rationale**: {why this approach}
|
||||
- **Validation**: {how to verify}
|
||||
|
||||
## Implementation Notes
|
||||
- Follow {framework} patterns
|
||||
- Test cases needed: {list}
|
||||
```
|
||||
2. Write design guide to artifacts/design-guide.md
|
||||
3. Share fix approaches via discoveries.ndjson
|
||||
|
||||
**Output**: Design guide file
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Designed fixes for {N} issues in {component}
|
||||
|
||||
## Findings
|
||||
- Issue 1: {description} → Fix: {approach}
|
||||
- Issue 2: {description} → Fix: {approach}
|
||||
|
||||
## Deliverables
|
||||
- File: artifacts/design-guide.md
|
||||
Content: Fix approaches with rationale and validation criteria
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"design_guide_path": "artifacts/design-guide.md",
|
||||
"issues_addressed": {N},
|
||||
"summary": "Designed fixes for {N} issues"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| No issues found | Generate empty design guide, note in findings |
|
||||
| Ambiguous fix approach | Ask user for guidance via request_user_input |
|
||||
| Conflicting patterns | Document trade-offs, recommend approach |
|
||||
@@ -1,158 +0,0 @@
|
||||
# UX Explorer Agent
|
||||
|
||||
Interactive agent for exploring codebase to identify UI component patterns and framework conventions.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/ux-explorer.md`
|
||||
- **Responsibility**: Framework detection and component inventory
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Detect UI framework (React/Vue/etc.)
|
||||
- Build component inventory with file paths
|
||||
- Cache findings for downstream tasks
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Execute implementation or fix tasks
|
||||
- Skip framework detection step
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Read` | File I/O | Load package.json, component files |
|
||||
| `Write` | File I/O | Generate exploration cache |
|
||||
| `Glob` | File search | Find component files |
|
||||
| `Bash` | CLI execution | Run framework detection commands |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Framework Detection
|
||||
|
||||
**Objective**: Detect UI framework if not specified.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. If framework specified in arguments, use it
|
||||
2. Otherwise, detect from package.json:
|
||||
- Check dependencies for react, vue, angular, svelte
|
||||
- Check file extensions (*.tsx → React, *.vue → Vue)
|
||||
3. Validate framework detection
|
||||
|
||||
**Output**: Framework name (react/vue/angular/svelte)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Component Inventory
|
||||
|
||||
**Objective**: Build inventory of UI components.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Search for component files based on framework:
|
||||
- React: `**/*.tsx`, `**/*.jsx`
|
||||
- Vue: `**/*.vue`
|
||||
- Angular: `**/*.component.ts`
|
||||
2. For each component:
|
||||
- Extract component name
|
||||
- Record file path
|
||||
- Identify component type (button, form, modal, etc.)
|
||||
3. Build component list
|
||||
|
||||
**Output**: Component inventory with paths
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Pattern Analysis
|
||||
|
||||
**Objective**: Analyze component patterns and conventions.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Sample components to identify patterns:
|
||||
- State management (useState, Vuex, etc.)
|
||||
- Event handling patterns
|
||||
- Styling approach (CSS modules, styled-components, etc.)
|
||||
2. Document conventions
|
||||
3. Identify common anti-patterns
|
||||
|
||||
**Output**: Pattern analysis summary
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Cache Generation
|
||||
|
||||
**Objective**: Generate exploration cache for downstream tasks.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Create cache structure:
|
||||
```json
|
||||
{
|
||||
"framework": "react",
|
||||
"components": [
|
||||
{"name": "Button", "path": "src/components/Button.tsx", "type": "button"},
|
||||
{"name": "Form", "path": "src/components/Form.tsx", "type": "form"}
|
||||
],
|
||||
"patterns": {
|
||||
"state_management": "React hooks",
|
||||
"event_handling": "inline handlers",
|
||||
"styling": "CSS modules"
|
||||
},
|
||||
"conventions": ["PascalCase component names", "Props interface per component"]
|
||||
}
|
||||
```
|
||||
2. Write cache to explorations/cache-index.json
|
||||
|
||||
**Output**: Exploration cache file
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Detected framework: {framework}
|
||||
- Found {N} components
|
||||
|
||||
## Findings
|
||||
- Component inventory: {N} components identified
|
||||
- Patterns: {state management}, {event handling}, {styling}
|
||||
- Conventions: {list}
|
||||
|
||||
## Deliverables
|
||||
- File: explorations/cache-index.json
|
||||
Content: Component inventory and pattern analysis
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"framework": "{framework}",
|
||||
"components": [{component list}],
|
||||
"component_count": {N},
|
||||
"summary": "Explored {N} components in {framework} project"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Framework detection fails | Ask user via request_user_input |
|
||||
| No components found | Return empty inventory, note in findings |
|
||||
| Invalid project path | Report error, request valid path |
|
||||
@@ -1,174 +0,0 @@
|
||||
# UX Tester Agent
|
||||
|
||||
Interactive agent for validating fixes and running tests. Iterates up to 5 times if tests fail.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Type**: `interactive`
|
||||
- **Role File**: `~/.codex/agents/ux-tester.md`
|
||||
- **Responsibility**: Fix validation and testing
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- Load role definition via MANDATORY FIRST STEPS pattern
|
||||
- Produce structured output following template
|
||||
- Run tests and validate fixes
|
||||
- Iterate up to 5 times on test failures
|
||||
- Generate test report
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Skip the MANDATORY FIRST STEPS role loading
|
||||
- Exceed 5 test iterations
|
||||
- Skip test execution step
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Type | Purpose |
|
||||
|------|------|---------|
|
||||
| `Bash` | CLI execution | Run tests, linters, build |
|
||||
| `Read` | File I/O | Load implementation findings, design guide |
|
||||
| `Write` | File I/O | Generate test report |
|
||||
|
||||
---
|
||||
|
||||
## Execution
|
||||
|
||||
### Phase 1: Test Preparation
|
||||
|
||||
**Objective**: Identify tests to run and prepare test environment.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Read implementation findings from prev_context
|
||||
2. Load design guide for validation criteria
|
||||
3. Identify test files related to component
|
||||
4. Check test framework (Jest, Vitest, etc.)
|
||||
|
||||
**Output**: Test plan
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Test Execution
|
||||
|
||||
**Objective**: Run tests and validate fixes (max 5 iterations).
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Run component tests:
|
||||
```bash
|
||||
npm test -- {component}.test
|
||||
```
|
||||
2. Run linter:
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
3. Check build:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
4. Collect results
|
||||
5. If tests fail and iteration < 5:
|
||||
- Analyze failures
|
||||
- Apply quick fixes if possible
|
||||
- Re-run tests
|
||||
6. If iteration >= 5:
|
||||
- Accept current state
|
||||
- Document remaining issues
|
||||
|
||||
**Output**: Test results with pass/fail status
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Validation
|
||||
|
||||
**Objective**: Validate fixes against design guide criteria.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. For each validation criterion in design guide:
|
||||
- Check if met by implementation
|
||||
- Check if validated by tests
|
||||
- Document status
|
||||
2. Calculate fix success rate
|
||||
3. Identify remaining issues
|
||||
|
||||
**Output**: Validation summary
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Test Report Generation
|
||||
|
||||
**Objective**: Generate test report with results.
|
||||
|
||||
**Steps**:
|
||||
|
||||
1. Format test report:
|
||||
```markdown
|
||||
# Test Report: {Component}
|
||||
|
||||
## Test Results
|
||||
- Tests passed: {X}/{Y}
|
||||
- Build status: {success/failed}
|
||||
- Linter warnings: {Z}
|
||||
|
||||
## Validation Status
|
||||
- Issue 1: {fixed/partial/unfixed}
|
||||
- Issue 2: {fixed/partial/unfixed}
|
||||
|
||||
## Remaining Issues
|
||||
- {list if any}
|
||||
|
||||
## Recommendation
|
||||
{approve/needs_work}
|
||||
```
|
||||
2. Write test report to artifacts/test-report.md
|
||||
3. Share test results via discoveries.ndjson
|
||||
|
||||
**Output**: Test report file
|
||||
|
||||
---
|
||||
|
||||
## Structured Output Template
|
||||
|
||||
```
|
||||
## Summary
|
||||
- Testing complete for {component}: {X}/{Y} tests passed
|
||||
|
||||
## Findings
|
||||
- Tests passed: {X}/{Y}
|
||||
- Build status: {success/failed}
|
||||
- Issues fixed: {N}
|
||||
- Remaining issues: {M}
|
||||
|
||||
## Deliverables
|
||||
- File: artifacts/test-report.md
|
||||
Content: Test results and validation status
|
||||
|
||||
## Output JSON
|
||||
{
|
||||
"test_report_path": "artifacts/test-report.md",
|
||||
"tests_passed": {X},
|
||||
"tests_total": {Y},
|
||||
"issues_fixed": {N},
|
||||
"recommendation": "approve" | "needs_work",
|
||||
"summary": "Testing complete: {X}/{Y} tests passed"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Tests fail to run | Document as issue, continue validation |
|
||||
| Build fails | Mark as critical issue, recommend fix |
|
||||
| Test iterations exceed 5 | Accept current state, document remaining issues |
|
||||
| No test files found | Note in findings, perform manual validation |
|
||||
@@ -1,55 +0,0 @@
|
||||
## TASK ASSIGNMENT
|
||||
|
||||
### MANDATORY FIRST STEPS
|
||||
1. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
|
||||
2. Read project context: .workflow/project-tech.json (if exists)
|
||||
3. Read exploration cache: {session_folder}/explorations/cache-index.json (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
**Task ID**: {id}
|
||||
**Title**: {title}
|
||||
**Description**: {description}
|
||||
**Role**: {role}
|
||||
**Component**: {component}
|
||||
|
||||
### Previous Tasks' Findings (Context)
|
||||
{prev_context}
|
||||
|
||||
---
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
1. **Read discoveries**: Load {session_folder}/discoveries.ndjson for shared UX findings
|
||||
2. **Use context**: Apply previous tasks' findings from prev_context above
|
||||
3. **Execute**: Perform role-specific task
|
||||
- **Scanner**: Scan component for UX issues (unresponsive buttons, missing feedback, state refresh)
|
||||
- **Diagnoser**: Analyze root causes of identified issues
|
||||
- **Implementer**: Apply fixes following design guide
|
||||
4. **Share discoveries**: Append findings to shared board:
|
||||
```bash
|
||||
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> {session_folder}/discoveries.ndjson
|
||||
```
|
||||
5. **Report result**: Return JSON via report_agent_job_result
|
||||
|
||||
### Discovery Types to Share
|
||||
- `ux_issue`: `{component, type, description, severity}` — UX issues discovered
|
||||
- `pattern`: `{pattern, files[], description}` — UI patterns identified
|
||||
- `fix_approach`: `{component, issue, approach, rationale}` — Fix strategies
|
||||
- `test_result`: `{component, test, status, details}` — Test outcomes
|
||||
|
||||
---
|
||||
|
||||
## Output (report_agent_job_result)
|
||||
|
||||
Return JSON:
|
||||
{
|
||||
"id": "{id}",
|
||||
"status": "completed" | "failed",
|
||||
"findings": "Key discoveries (max 500 chars)",
|
||||
"issues_found": "3",
|
||||
"issues_fixed": "3",
|
||||
"error": ""
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse user task -> detect UX improvement scope -> assess complexity -> determine pipeline configuration.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
| Keywords | Signal | Pipeline Hint |
|
||||
|----------|--------|---------------|
|
||||
| button, click, tap, unresponsive | interaction-issues | standard |
|
||||
| loading, spinner, feedback, progress | feedback-missing | standard |
|
||||
| state, refresh, update, stale | state-issues | standard |
|
||||
| form, input, validation, error | input-issues | standard |
|
||||
| accessibility, a11y, keyboard, screen reader | accessibility | standard |
|
||||
| performance, slow, lag, freeze | performance | standard |
|
||||
| all, full, complete, comprehensive | full-scope | standard |
|
||||
|
||||
## Framework Detection
|
||||
|
||||
| Keywords | Framework |
|
||||
|----------|-----------|
|
||||
| react, jsx, tsx, useState, useEffect | React |
|
||||
| vue, .vue, ref(), reactive(), v-model | Vue |
|
||||
| angular, ng-, @Component | Angular |
|
||||
| Default | auto-detect |
|
||||
|
||||
## Complexity Scoring
|
||||
|
||||
| Factor | Points |
|
||||
|--------|--------|
|
||||
| Single component scope | +1 |
|
||||
| Multiple components | +2 |
|
||||
| Full project scope | +3 |
|
||||
| Accessibility required | +1 |
|
||||
| Performance issues | +1 |
|
||||
| Complex state management | +1 |
|
||||
|
||||
Results: 1-2 Low (targeted fix), 3-4 Medium (standard pipeline), 5+ High (full pipeline)
|
||||
|
||||
## Scope Determination
|
||||
|
||||
| Signal | Pipeline Mode |
|
||||
|--------|---------------|
|
||||
| Specific component or file mentioned | targeted |
|
||||
| Multiple issues or general project | standard |
|
||||
| "Full audit" or "complete scan" | standard |
|
||||
| Unclear | ask user |
|
||||
|
||||
## Output
|
||||
|
||||
Write scope context to coordinator memory:
|
||||
```json
|
||||
{
|
||||
"pipeline_mode": "standard",
|
||||
"project_path": "<detected-or-provided-path>",
|
||||
"framework": "<react|vue|angular|auto>",
|
||||
"scope": "<detected-scope>",
|
||||
"issue_signals": ["interaction", "feedback", "state"],
|
||||
"complexity": { "score": 0, "level": "Low|Medium|High" }
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,233 @@
|
||||
# Dispatch Command
|
||||
|
||||
## Purpose
|
||||
|
||||
Create task chains based on execution mode. Generate structured task descriptions with PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS format.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session ID | coordinator Phase 2 | Yes |
|
||||
| Project path | coordinator Phase 1 | Yes |
|
||||
| Framework | coordinator Phase 1 | Yes |
|
||||
| Pipeline mode | meta.json | Yes |
|
||||
|
||||
1. Load session ID from coordinator context
|
||||
2. Load project path and framework from meta.json
|
||||
3. Determine pipeline mode (standard)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Task Chain Creation
|
||||
|
||||
### Task Description Template
|
||||
|
||||
Every task description uses structured format for clarity. Tasks are stored in `<session>/tasks.json`:
|
||||
|
||||
```
|
||||
// Read existing tasks.json (or initialize empty array)
|
||||
tasks = JSON.parse(Read("<session>/tasks.json")) || []
|
||||
|
||||
// Add new task entry:
|
||||
tasks.push({
|
||||
"id": "<TASK-ID>",
|
||||
"subject": "<TASK-ID>",
|
||||
"status": "pending",
|
||||
"owner": "<role>",
|
||||
"blockedBy": [<dependency-list>],
|
||||
"description": "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
|
||||
TASK:
|
||||
- <step 1: specific action>
|
||||
- <step 2: specific action>
|
||||
- <step 3: specific action>
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: <scope>
|
||||
- Upstream artifacts: <artifact-1.md>, <artifact-2.md>
|
||||
- Key files: <file1>, <file2> (if applicable)
|
||||
- State: via team_msg(operation=\"get_state\", role=<upstream-role>)
|
||||
EXPECTED: <deliverable path> + <quality criteria>
|
||||
CONSTRAINTS: <scope limits, focus areas>
|
||||
---
|
||||
InnerLoop: <true|false>
|
||||
<additional-metadata-fields>"
|
||||
})
|
||||
|
||||
// Write updated tasks.json
|
||||
Write("<session>/tasks.json", JSON.stringify(tasks, null, 2))
|
||||
```
|
||||
|
||||
### Standard Pipeline Tasks
|
||||
|
||||
**SCAN-001: UI Component Scanning**
|
||||
```
|
||||
// Add to tasks.json:
|
||||
{
|
||||
"id": "SCAN-001",
|
||||
"subject": "SCAN-001",
|
||||
"status": "pending",
|
||||
"owner": "scanner",
|
||||
"blockedBy": [],
|
||||
"description": "PURPOSE: Scan UI components to identify interaction issues (unresponsive buttons, missing feedback, state not refreshing) | Success: Complete issue report with file:line references and severity classification
|
||||
TASK:
|
||||
- Detect framework (React/Vue) from project structure
|
||||
- Scan UI components for interaction patterns using ACE search and file analysis
|
||||
- Identify missing feedback mechanisms (loading states, error handling, success confirmation)
|
||||
- Detect unresponsive actions (event binding issues, async handling problems)
|
||||
- Check state update patterns (mutation vs reactive updates)
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: Project path: <project-path>, Framework: <framework>
|
||||
- File patterns: **/*.tsx, **/*.vue, **/*.jsx
|
||||
- Focus: UI components with user interactions
|
||||
EXPECTED: artifacts/scan-report.md with structured issue list (severity: High/Medium/Low, file:line, description, category)
|
||||
CONSTRAINTS: Focus on interaction issues only, exclude styling/layout problems
|
||||
---
|
||||
InnerLoop: false"
|
||||
}
|
||||
```
|
||||
|
||||
**DIAG-001: Root Cause Diagnosis**
|
||||
```
|
||||
// Add to tasks.json:
|
||||
{
|
||||
"id": "DIAG-001",
|
||||
"subject": "DIAG-001",
|
||||
"status": "pending",
|
||||
"owner": "diagnoser",
|
||||
"blockedBy": ["SCAN-001"],
|
||||
"description": "PURPOSE: Diagnose root causes of identified UI issues | Success: Complete diagnosis report with fix recommendations for each issue
|
||||
TASK:
|
||||
- Load scan report from artifacts/scan-report.md
|
||||
- Analyze state management patterns (direct mutation vs reactive updates)
|
||||
- Trace event binding and propagation
|
||||
- Check async handling (promises, callbacks, error catching)
|
||||
- Identify framework-specific anti-patterns
|
||||
- Use CLI for complex multi-file analysis when needed
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: Issues from scan report
|
||||
- Upstream artifacts: artifacts/scan-report.md
|
||||
- State: via team_msg(operation=\"get_state\", role=\"scanner\")
|
||||
EXPECTED: artifacts/diagnosis.md with root cause analysis (issue ID, root cause, pattern type, fix recommendation)
|
||||
CONSTRAINTS: Focus on actionable root causes, provide specific fix strategies
|
||||
---
|
||||
InnerLoop: false"
|
||||
}
|
||||
```
|
||||
|
||||
**DESIGN-001: Solution Design**
|
||||
```
|
||||
// Add to tasks.json:
|
||||
{
|
||||
"id": "DESIGN-001",
|
||||
"subject": "DESIGN-001",
|
||||
"status": "pending",
|
||||
"owner": "designer",
|
||||
"blockedBy": ["DIAG-001"],
|
||||
"description": "PURPOSE: Design feedback mechanisms and state management solutions for identified issues | Success: Complete implementation guide with code patterns and examples
|
||||
TASK:
|
||||
- Load diagnosis report from artifacts/diagnosis.md
|
||||
- Design feedback mechanisms (loading/error/success states) for each issue
|
||||
- Design state management patterns (useState/ref, reactive updates)
|
||||
- Design input control improvements (file selectors, validation)
|
||||
- Generate framework-specific code patterns (React/Vue)
|
||||
- Use CLI for complex multi-component solutions when needed
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: Issues from diagnosis report
|
||||
- Upstream artifacts: artifacts/diagnosis.md
|
||||
- Framework: <framework>
|
||||
- State: via team_msg(operation=\"get_state\", role=\"diagnoser\")
|
||||
EXPECTED: artifacts/design-guide.md with implementation guide (issue ID, solution design, code patterns, state management examples, UI binding templates)
|
||||
CONSTRAINTS: Solutions must be framework-appropriate, provide complete working examples
|
||||
---
|
||||
InnerLoop: false"
|
||||
}
|
||||
```
|
||||
|
||||
**IMPL-001: Code Implementation**
|
||||
```
|
||||
// Add to tasks.json:
|
||||
{
|
||||
"id": "IMPL-001",
|
||||
"subject": "IMPL-001",
|
||||
"status": "pending",
|
||||
"owner": "implementer",
|
||||
"blockedBy": ["DESIGN-001"],
|
||||
"description": "PURPOSE: Generate fix code with proper state management, event handling, and UI feedback bindings | Success: All fixes implemented and validated
|
||||
TASK:
|
||||
- Load design guide from artifacts/design-guide.md
|
||||
- Extract implementation tasks from design guide
|
||||
- Generate fix code with proper state management (useState/ref)
|
||||
- Add event handlers with error catching
|
||||
- Implement UI feedback bindings (loading/error/success)
|
||||
- Use CLI for complex multi-file changes, direct Edit/Write for simple changes
|
||||
- Validate syntax and file existence after each fix
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: Fixes from design guide
|
||||
- Upstream artifacts: artifacts/design-guide.md
|
||||
- Framework: <framework>
|
||||
- State: via team_msg(operation=\"get_state\", role=\"designer\")
|
||||
- Context accumulator: Load from prior IMPL tasks (inner loop)
|
||||
EXPECTED: artifacts/fixes/ directory with all fix files, implementation summary in artifacts/fixes/README.md
|
||||
CONSTRAINTS: Maintain existing code style, ensure backward compatibility, validate all changes
|
||||
---
|
||||
InnerLoop: true"
|
||||
}
|
||||
```
|
||||
|
||||
**TEST-001: Test Validation**
|
||||
```
|
||||
// Add to tasks.json:
|
||||
{
|
||||
"id": "TEST-001",
|
||||
"subject": "TEST-001",
|
||||
"status": "pending",
|
||||
"owner": "tester",
|
||||
"blockedBy": ["IMPL-001"],
|
||||
"description": "PURPOSE: Generate and run tests to verify fixes (loading states, error handling, state updates) | Success: Pass rate >= 95%, all critical fixes validated
|
||||
TASK:
|
||||
- Detect test framework (Jest/Vitest) from project
|
||||
- Get changed files from implementer state
|
||||
- Load test strategy from design guide
|
||||
- Generate test cases for loading states, error handling, state updates
|
||||
- Run tests and parse results
|
||||
- If pass rate < 95%, use CLI to generate fixes (max 5 iterations)
|
||||
- Generate test report with pass/fail counts, coverage, fix iterations
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Scope: Fixes from implementer
|
||||
- Upstream artifacts: artifacts/fixes/, artifacts/design-guide.md
|
||||
- Framework: <framework>
|
||||
- State: via team_msg(operation=\"get_state\", role=\"implementer\")
|
||||
EXPECTED: artifacts/test-report.md with test results (pass/fail counts, coverage metrics, fix iterations, remaining issues)
|
||||
CONSTRAINTS: Pass rate threshold: 95%, max fix iterations: 5
|
||||
---
|
||||
InnerLoop: false"
|
||||
}
|
||||
|
||||
// Write all tasks to tasks.json
|
||||
Write("<session>/tasks.json", JSON.stringify(tasks, null, 2))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Validation
|
||||
|
||||
1. Verify all tasks created successfully in tasks.json
|
||||
2. Check task dependency chain is valid (no cycles)
|
||||
3. Verify all task owners match Role Registry
|
||||
4. Confirm task prefixes match role frontmatter
|
||||
5. Output task count and dependency graph
|
||||
|
||||
| Check | Pass Criteria |
|
||||
|-------|---------------|
|
||||
| Task count | 5 tasks created |
|
||||
| Dependencies | Linear chain: SCAN -> DIAG -> DESIGN -> IMPL -> TEST |
|
||||
| Owners | All owners in Role Registry |
|
||||
| Prefixes | Match role frontmatter |
|
||||
@@ -0,0 +1,160 @@
|
||||
# Monitor Pipeline
|
||||
|
||||
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
|
||||
|
||||
## Constants
|
||||
|
||||
- SPAWN_MODE: background
|
||||
- ONE_STEP_PER_INVOCATION: true
|
||||
- FAST_ADVANCE_AWARE: true
|
||||
- WORKER_AGENT: team_worker
|
||||
- MAX_TEST_ITERATIONS: 5
|
||||
|
||||
## Handler Router
|
||||
|
||||
| Source | Handler |
|
||||
|--------|---------|
|
||||
| Message contains [scanner], [diagnoser], [designer], [implementer], [tester] | handleCallback |
|
||||
| "capability_gap" | handleAdapt |
|
||||
| "check" or "status" | handleCheck |
|
||||
| "resume" or "continue" | handleResume |
|
||||
| All tasks completed | handleComplete |
|
||||
| Default | handleSpawnNext |
|
||||
|
||||
## handleCallback
|
||||
|
||||
Worker completed. Process and advance.
|
||||
|
||||
1. Parse message to identify role and task ID:
|
||||
|
||||
| Message Pattern | Role |
|
||||
|----------------|------|
|
||||
| `[scanner]` or `SCAN-*` | scanner |
|
||||
| `[diagnoser]` or `DIAG-*` | diagnoser |
|
||||
| `[designer]` or `DESIGN-*` | designer |
|
||||
| `[implementer]` or `IMPL-*` | implementer |
|
||||
| `[tester]` or `TEST-*` | tester |
|
||||
|
||||
2. Check if progress update (inner loop) or final completion
|
||||
3. Progress update -> update session state, STOP
|
||||
4. Completion -> mark task done:
|
||||
```
|
||||
// Read tasks.json, find task by id, update status
|
||||
tasks = JSON.parse(Read("<session>/tasks.json"))
|
||||
task = tasks.find(t => t.id === "<task-id>")
|
||||
task.status = "completed"
|
||||
Write("<session>/tasks.json", JSON.stringify(tasks, null, 2))
|
||||
```
|
||||
5. Remove from active_workers, record completion in session
|
||||
|
||||
6. Check for checkpoints:
|
||||
- **TEST-001 completes** -> Validation Gate:
|
||||
Read test results from `.msg/meta.json`
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| pass_rate >= 95% | -> handleSpawnNext (pipeline likely complete) |
|
||||
| pass_rate < 95% AND iterations < max | Log warning, still -> handleSpawnNext |
|
||||
| pass_rate < 95% AND iterations >= max | Accept current state -> handleComplete |
|
||||
|
||||
7. -> handleSpawnNext
|
||||
|
||||
## handleCheck
|
||||
|
||||
Read-only status report, then STOP.
|
||||
|
||||
```
|
||||
Pipeline Status (standard):
|
||||
[DONE] SCAN-001 (scanner) -> artifacts/scan-report.md
|
||||
[DONE] DIAG-001 (diagnoser) -> artifacts/diagnosis.md
|
||||
[RUN] DESIGN-001 (designer) -> designing solutions...
|
||||
[WAIT] IMPL-001 (implementer) -> blocked by DESIGN-001
|
||||
[WAIT] TEST-001 (tester) -> blocked by IMPL-001
|
||||
|
||||
Session: <session-id>
|
||||
Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
Output status -- do NOT advance pipeline.
|
||||
|
||||
## handleResume
|
||||
|
||||
1. Audit task list for inconsistencies:
|
||||
- Tasks stuck in "in_progress" -> reset to "pending"
|
||||
- Tasks with completed blockers but still "pending" -> include in spawn list
|
||||
2. -> handleSpawnNext
|
||||
|
||||
## handleSpawnNext
|
||||
|
||||
Find ready tasks, spawn workers, STOP.
|
||||
|
||||
1. Read tasks from `<session>/tasks.json`
|
||||
2. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed)
|
||||
3. No ready + work in progress -> report waiting, STOP
|
||||
4. No ready + nothing in progress -> handleComplete
|
||||
5. 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:
|
||||
|
||||
```
|
||||
spawn_agent({
|
||||
agent_type: "team_worker",
|
||||
items: [{
|
||||
description: "Spawn <role> worker for <task-id>",
|
||||
team_name: "ux-improve",
|
||||
name: "<role>",
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: ~ or <project>/.codex/skills/team-ux-improve/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: ux-improve
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
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).`
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
Stage-to-role mapping:
|
||||
| Task Prefix | Role |
|
||||
|-------------|------|
|
||||
| SCAN | scanner |
|
||||
| DIAG | diagnoser |
|
||||
| DESIGN | designer |
|
||||
| IMPL | implementer |
|
||||
| TEST | tester |
|
||||
|
||||
Inner loop roles: implementer (inner_loop: true)
|
||||
Single-task roles: scanner, diagnoser, designer, tester (inner_loop: false)
|
||||
|
||||
5. Add to active_workers, update session, output summary, STOP
|
||||
|
||||
## handleComplete
|
||||
|
||||
Pipeline done. Generate report and completion action.
|
||||
|
||||
1. Verify all tasks (including any fix-verify iterations) have status "completed"
|
||||
2. If any tasks not completed -> handleSpawnNext
|
||||
3. 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, spawn worker
|
||||
5. Role count >= 5 -> merge or pause
|
||||
|
||||
## Fast-Advance Reconciliation
|
||||
|
||||
On every coordinator wake:
|
||||
1. Read team_msg entries with type="fast_advance"
|
||||
2. Sync active_workers with spawned successors
|
||||
3. No duplicate spawns
|
||||
138
.codex/skills/team-ux-improve/roles/coordinator/role.md
Normal file
138
.codex/skills/team-ux-improve/roles/coordinator/role.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Coordinator Role
|
||||
|
||||
UX Improvement Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Systematically discovers and fixes UI/UX interaction issues.
|
||||
|
||||
## Identity
|
||||
- **Name**: coordinator | **Tag**: [coordinator]
|
||||
- **Responsibility**: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
- All output (report_agent_job_result, team_msg, logs) must carry `[coordinator]` identifier
|
||||
- Use `team_worker` agent type for all worker spawns
|
||||
- Parse project_path and framework from arguments
|
||||
- Dispatch tasks with proper dependency chains and blockedBy
|
||||
- Monitor worker progress via message bus and route messages
|
||||
- Handle wisdom initialization and consolidation
|
||||
- Maintain session state persistence
|
||||
|
||||
### MUST NOT
|
||||
- Execute worker domain logic directly (scanning, diagnosing, designing, implementing, testing)
|
||||
- Spawn workers without creating tasks first
|
||||
- Skip completion action
|
||||
- Modify source code directly -- delegate to implementer
|
||||
- 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 |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains [scanner], [diagnoser], [designer], [implementer], [tester] | -> handleCallback (monitor.md) |
|
||||
| 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/ux-improve-* | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
For callback/check/resume/adapt/complete: load `@commands/monitor.md`, execute matched handler, STOP.
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. Scan `.workflow/.team/ux-improve-*/.msg/meta.json` for active/paused sessions
|
||||
2. No sessions -> Phase 1
|
||||
3. Single session -> reconcile (audit tasks.json, reset in_progress->pending, rebuild team, kick first ready task)
|
||||
4. Multiple -> request_user_input for selection
|
||||
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
TEXT-LEVEL ONLY. No source code reading.
|
||||
|
||||
1. Parse `$ARGUMENTS` for project path and framework flag:
|
||||
- `<project-path>` (required)
|
||||
- `--framework react|vue` (optional, auto-detect if omitted)
|
||||
2. If project path missing -> request_user_input for path
|
||||
3. Delegate to `@commands/analyze.md` -> output scope context
|
||||
4. Store: project_path, framework, pipeline_mode, issue_signals
|
||||
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
1. Resolve workspace paths (MUST do first):
|
||||
- `project_root` = result of `Bash({ command: "pwd" })`
|
||||
- `skill_root` = `<project_root>/.claude/skills/team-ux-improve`
|
||||
2. Generate session ID: `ux-improve-<timestamp>`
|
||||
3. Create session folder structure:
|
||||
```
|
||||
.workflow/.team/ux-improve-<timestamp>/
|
||||
├── .msg/
|
||||
├── artifacts/
|
||||
├── explorations/
|
||||
└── wisdom/contributions/
|
||||
```
|
||||
4. **Wisdom Initialization**: Copy `<skill_root>/wisdom/` to `<session>/wisdom/`
|
||||
5. Initialize `.msg/meta.json` via team_msg state_update with pipeline metadata
|
||||
6. Create session folder: `.workflow/.team/ux-improve-<timestamp>/`
|
||||
7. Do NOT spawn workers yet - deferred to Phase 4
|
||||
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
Delegate to `@commands/dispatch.md`. Standard pipeline:
|
||||
|
||||
SCAN-001 -> DIAG-001 -> DESIGN-001 -> IMPL-001 -> TEST-001
|
||||
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
Delegate to `@commands/monitor.md#handleSpawnNext`:
|
||||
1. Find ready tasks (pending + blockedBy resolved)
|
||||
2. Spawn team-worker agents (see SKILL.md Spawn Template)
|
||||
3. Output status summary
|
||||
4. STOP
|
||||
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
1. Read session state -> collect all results
|
||||
2. List deliverables:
|
||||
|
||||
| Deliverable | Path |
|
||||
|-------------|------|
|
||||
| Scan Report | <session>/artifacts/scan-report.md |
|
||||
| Diagnosis | <session>/artifacts/diagnosis.md |
|
||||
| Design Guide | <session>/artifacts/design-guide.md |
|
||||
| Fix Files | <session>/artifacts/fixes/ |
|
||||
| Test Report | <session>/artifacts/test-report.md |
|
||||
|
||||
3. **Wisdom Consolidation**: Check `<session>/wisdom/contributions/` for worker contributions
|
||||
- If contributions exist -> request_user_input to merge to permanent wisdom
|
||||
- If approved -> copy to `<skill_root>/wisdom/`
|
||||
|
||||
4. Calculate: completed_tasks, total_issues_found, issues_fixed, test_pass_rate
|
||||
5. Output pipeline summary with [coordinator] prefix
|
||||
6. Execute completion action:
|
||||
```
|
||||
request_user_input({
|
||||
prompt: "Pipeline complete. What next?\n\nOptions:\n1. Archive & Clean - Archive session and clean up team resources\n2. Keep Active - Keep session for follow-up work\n3. Export Results - Export deliverables to specified location"
|
||||
})
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Project path invalid | Re-prompt user for valid path |
|
||||
| Framework detection fails | request_user_input for framework selection |
|
||||
| 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 |
|
||||
| Session corruption | Attempt recovery, fallback to manual reconciliation |
|
||||
| No UI issues found | Complete with empty fix list, generate clean bill report |
|
||||
| Test iterations exceeded | Accept current state, continue to completion |
|
||||
122
.codex/skills/team-ux-improve/roles/designer/role.md
Normal file
122
.codex/skills/team-ux-improve/roles/designer/role.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
role: designer
|
||||
prefix: DESIGN
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# UX Designer
|
||||
|
||||
Design feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates).
|
||||
|
||||
## Phase 2: Context & Pattern Loading
|
||||
|
||||
1. Load diagnosis report from `<session>/artifacts/diagnosis.md`
|
||||
2. Load diagnoser state via `team_msg(operation="get_state", session_id=<session-id>, role="diagnoser")`
|
||||
3. Detect framework from project structure
|
||||
4. Load framework-specific patterns:
|
||||
|
||||
| Framework | State Pattern | Event Pattern |
|
||||
|-----------|---------------|---------------|
|
||||
| React | useState, useRef | onClick, onChange |
|
||||
| Vue | ref, reactive | @click, @change |
|
||||
|
||||
### Wisdom Input
|
||||
|
||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` for established feedback design patterns
|
||||
2. Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
|
||||
3. Read `<session>/wisdom/principles/general-ux.md` for UX design principles
|
||||
4. Apply patterns when designing solutions for identified issues
|
||||
|
||||
### Complex Design (use CLI)
|
||||
|
||||
For complex multi-component solutions:
|
||||
|
||||
```
|
||||
Bash(`ccw cli -p "PURPOSE: Design comprehensive feedback mechanism for multi-step form
|
||||
CONTEXT: @<component-files>
|
||||
EXPECTED: Complete design with state flow diagram and code patterns
|
||||
CONSTRAINTS: Must support React hooks" --tool gemini --mode analysis`)
|
||||
```
|
||||
|
||||
## Phase 3: Solution Design
|
||||
|
||||
For each diagnosed issue, design solution:
|
||||
|
||||
### Feedback Mechanism Design
|
||||
|
||||
| Issue Type | Solution Design |
|
||||
|------------|-----------------|
|
||||
| Missing loading | Add loading state + UI indicator (spinner, disabled button) |
|
||||
| Missing error | Add error state + error message display |
|
||||
| Missing success | Add success state + confirmation toast/message |
|
||||
| No empty state | Add conditional rendering for empty data |
|
||||
|
||||
### State Management Design
|
||||
|
||||
**React Pattern**:
|
||||
```typescript
|
||||
const [isLoading, setIsLoading] = useState(false);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
const handleSubmit = async (event: React.FormEvent) => {
|
||||
event.preventDefault();
|
||||
setIsLoading(true);
|
||||
setError(null);
|
||||
try {
|
||||
const response = await fetch('/api/upload', { method: 'POST', body: formData });
|
||||
if (!response.ok) throw new Error('Upload failed');
|
||||
} catch (err: any) {
|
||||
setError(err.message || 'An error occurred');
|
||||
} finally {
|
||||
setIsLoading(false);
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Vue Pattern**:
|
||||
```typescript
|
||||
const isLoading = ref(false);
|
||||
const error = ref<string | null>(null);
|
||||
|
||||
const handleSubmit = async () => {
|
||||
isLoading.value = true;
|
||||
error.value = null;
|
||||
try {
|
||||
const response = await fetch('/api/upload', { method: 'POST', body: formData });
|
||||
if (!response.ok) throw new Error('Upload failed');
|
||||
} catch (err: any) {
|
||||
error.value = err.message || 'An error occurred';
|
||||
} finally {
|
||||
isLoading.value = false;
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Input Control Design
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Text input for file path | Add file picker: `<input type="file" />` |
|
||||
| Text input for folder path | Add directory picker: `<input type="file" webkitdirectory />` |
|
||||
| No validation | Add validation rules and error messages |
|
||||
|
||||
## Phase 4: Design Document Generation
|
||||
|
||||
1. Generate implementation guide for each issue and write to `<session>/artifacts/design-guide.md`
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If novel design patterns created:
|
||||
1. Write new patterns to `<session>/wisdom/contributions/designer-pattern-<timestamp>.md`
|
||||
2. Format: Problem context, solution design, implementation hints, trade-offs
|
||||
|
||||
3. Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="designer",
|
||||
type="state_update", data={
|
||||
designed_solutions: <count>,
|
||||
framework: <framework>,
|
||||
patterns_used: [<pattern-list>]
|
||||
})
|
||||
```
|
||||
93
.codex/skills/team-ux-improve/roles/diagnoser/role.md
Normal file
93
.codex/skills/team-ux-improve/roles/diagnoser/role.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
role: diagnoser
|
||||
prefix: DIAG
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# State Diagnoser
|
||||
|
||||
Diagnose root causes of UI issues: state management problems, event binding failures, async handling errors.
|
||||
|
||||
## Phase 2: Context & Complexity Assessment
|
||||
|
||||
1. Load scan report from `<session>/artifacts/scan-report.md`
|
||||
2. Load scanner state via `team_msg(operation="get_state", session_id=<session-id>, role="scanner")`
|
||||
|
||||
### Wisdom Input
|
||||
|
||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
|
||||
2. Use patterns to identify root causes of UI interaction issues
|
||||
3. Reference `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common causes
|
||||
|
||||
3. Assess issue complexity:
|
||||
|
||||
| Complexity | Criteria | Strategy |
|
||||
|------------|----------|----------|
|
||||
| High | 5+ issues, cross-component state | CLI delegation |
|
||||
| Medium | 2-4 issues, single component | CLI for analysis |
|
||||
| Low | 1 issue, simple pattern | Inline analysis |
|
||||
|
||||
### Complex Analysis (use CLI)
|
||||
|
||||
For complex multi-file state management issues:
|
||||
|
||||
```
|
||||
Bash(`ccw cli -p "PURPOSE: Analyze state management patterns and identify root causes
|
||||
CONTEXT: @<issue-files>
|
||||
EXPECTED: Root cause analysis with fix recommendations
|
||||
CONSTRAINTS: Focus on reactive update patterns" --tool gemini --mode analysis`)
|
||||
```
|
||||
|
||||
## Phase 3: Root Cause Analysis
|
||||
|
||||
For each issue from scan report:
|
||||
|
||||
### State Management Diagnosis
|
||||
|
||||
| Pattern | Root Cause | Fix Strategy |
|
||||
|---------|------------|--------------|
|
||||
| Array.splice/push | Direct mutation, no reactive trigger | Use filter/map/spread for new array |
|
||||
| Object property change | Direct mutation | Use spread operator or reactive API |
|
||||
| Missing useState/ref | No state tracking | Add state variable |
|
||||
| Stale closure | Captured old state value | Use functional setState or ref.current |
|
||||
|
||||
### Event Binding Diagnosis
|
||||
|
||||
| Pattern | Root Cause | Fix Strategy |
|
||||
|---------|------------|--------------|
|
||||
| onClick without handler | Missing event binding | Add event handler function |
|
||||
| Async without await | Unhandled promise | Add async/await or .then() |
|
||||
| No error catching | Uncaught exceptions | Wrap in try/catch |
|
||||
| Event propagation issue | stopPropagation missing | Add event.stopPropagation() |
|
||||
|
||||
### Async Handling Diagnosis
|
||||
|
||||
| Pattern | Root Cause | Fix Strategy |
|
||||
|---------|------------|--------------|
|
||||
| No loading state | Missing async state tracking | Add isLoading state |
|
||||
| No error handling | Missing catch block | Add try/catch with error state |
|
||||
| Race condition | Multiple concurrent requests | Add request cancellation or debounce |
|
||||
|
||||
## Phase 4: Diagnosis Report
|
||||
|
||||
1. Generate root cause analysis for each issue and write to `<session>/artifacts/diagnosis.md`
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If new root cause patterns discovered:
|
||||
1. Write diagnosis patterns to `<session>/wisdom/contributions/diagnoser-patterns-<timestamp>.md`
|
||||
2. Format: Symptom, root cause, detection method, fix approach
|
||||
|
||||
3. Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="diagnoser",
|
||||
type="state_update", data={
|
||||
diagnosed_issues: <count>,
|
||||
pattern_types: {
|
||||
state_management: <count>,
|
||||
event_binding: <count>,
|
||||
async_handling: <count>
|
||||
}
|
||||
})
|
||||
```
|
||||
77
.codex/skills/team-ux-improve/roles/explorer/role.md
Normal file
77
.codex/skills/team-ux-improve/roles/explorer/role.md
Normal file
@@ -0,0 +1,77 @@
|
||||
---
|
||||
role: explorer
|
||||
prefix: EXPLORE
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Codebase Explorer
|
||||
|
||||
Explore codebase for UI component patterns, state management conventions, and framework-specific patterns. Callable by coordinator only.
|
||||
|
||||
## Phase 2: Exploration Scope
|
||||
|
||||
1. Parse exploration request from task description
|
||||
2. Determine file patterns based on framework:
|
||||
|
||||
### Wisdom Input
|
||||
|
||||
1. Read `<session>/wisdom/patterns/ui-feedback.md` and `<session>/wisdom/patterns/state-management.md` if available
|
||||
2. Use known patterns as reference when exploring codebase for component structures
|
||||
3. Check `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` to identify problematic patterns during exploration
|
||||
|
||||
| Framework | Patterns |
|
||||
|-----------|----------|
|
||||
| React | `**/*.tsx`, `**/*.jsx`, `**/use*.ts`, `**/store*.ts` |
|
||||
| Vue | `**/*.vue`, `**/composables/*.ts`, `**/stores/*.ts` |
|
||||
|
||||
3. Check exploration cache: `<session>/explorations/cache-index.json`
|
||||
- If cache hit and fresh -> return cached results
|
||||
- If cache miss or stale -> proceed to Phase 3
|
||||
|
||||
## Phase 3: Codebase Exploration
|
||||
|
||||
Use ACE search for semantic queries:
|
||||
|
||||
```
|
||||
mcp__ace-tool__search_context(
|
||||
project_root_path="<project-path>",
|
||||
query="<exploration-query>"
|
||||
)
|
||||
```
|
||||
|
||||
Exploration dimensions:
|
||||
|
||||
| Dimension | Query | Purpose |
|
||||
|-----------|-------|---------|
|
||||
| Component patterns | "UI components with user interactions" | Find interactive components |
|
||||
| State management | "State management patterns useState ref reactive" | Identify state conventions |
|
||||
| Event handling | "Event handlers onClick onChange onSubmit" | Map event patterns |
|
||||
| Error handling | "Error handling try catch error state" | Find error patterns |
|
||||
| Feedback mechanisms | "Loading state spinner progress indicator" | Find existing feedback |
|
||||
|
||||
For each dimension, collect:
|
||||
- File paths
|
||||
- Pattern examples
|
||||
- Convention notes
|
||||
|
||||
## Phase 4: Exploration Summary
|
||||
|
||||
1. Generate pattern summary and write to `<session>/explorations/exploration-summary.md`
|
||||
2. Cache results to `<session>/explorations/cache-index.json`
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If new component patterns or framework conventions discovered:
|
||||
1. Write pattern summaries to `<session>/wisdom/contributions/explorer-patterns-<timestamp>.md`
|
||||
2. Format: Pattern Name, Framework, Use Case, Code Example, Adoption
|
||||
|
||||
4. Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="explorer",
|
||||
type="state_update", data={
|
||||
framework: <framework>,
|
||||
components_found: <count>,
|
||||
patterns_identified: [<pattern-list>]
|
||||
})
|
||||
```
|
||||
102
.codex/skills/team-ux-improve/roles/implementer/role.md
Normal file
102
.codex/skills/team-ux-improve/roles/implementer/role.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
role: implementer
|
||||
prefix: IMPL
|
||||
inner_loop: true
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Code Implementer
|
||||
|
||||
Generate executable fix code with proper state management, event handling, and UI feedback bindings.
|
||||
|
||||
## Phase 2: Task & Design Loading
|
||||
|
||||
1. Extract session path from task description
|
||||
2. Read design guide: `<session>/artifacts/design-guide.md`
|
||||
3. Extract implementation tasks from design guide
|
||||
4. **Wisdom Input**:
|
||||
- Read `<session>/wisdom/patterns/state-management.md` for state handling patterns
|
||||
- Read `<session>/wisdom/patterns/ui-feedback.md` for UI feedback implementation patterns
|
||||
- Read `<session>/wisdom/principles/general-ux.md` for implementation principles
|
||||
- Load framework-specific conventions if available
|
||||
- Apply these patterns and principles when generating code to ensure consistency and quality
|
||||
5. **For inner loop**: Load context_accumulator from prior IMPL tasks
|
||||
|
||||
### Context Accumulator (Inner Loop)
|
||||
|
||||
```
|
||||
context_accumulator = {
|
||||
completed_fixes: [<fix-1>, <fix-2>],
|
||||
modified_files: [<file-1>, <file-2>],
|
||||
patterns_applied: [<pattern-1>]
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 3: Code Implementation
|
||||
|
||||
Implementation backend selection:
|
||||
|
||||
| Backend | Condition | Method |
|
||||
|---------|-----------|--------|
|
||||
| CLI | Complex multi-file changes | `ccw cli --tool gemini --mode write` |
|
||||
| Direct | Simple single-file changes | Inline Edit/Write |
|
||||
|
||||
### CLI Implementation (Complex)
|
||||
|
||||
```
|
||||
Bash(`ccw cli -p "PURPOSE: Implement loading state and error handling for upload form
|
||||
TASK:
|
||||
- Add useState for isLoading and error
|
||||
- Wrap async call in try/catch/finally
|
||||
- Update UI bindings for button and error display
|
||||
CONTEXT: @src/components/Upload.tsx
|
||||
EXPECTED: Modified Upload.tsx with complete implementation
|
||||
CONSTRAINTS: Maintain existing code style" --tool gemini --mode write`)
|
||||
```
|
||||
|
||||
### Direct Implementation (Simple)
|
||||
|
||||
For simple state variable additions or UI binding changes use Edit/Write tools directly.
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
For each fix in design guide:
|
||||
1. Read target file
|
||||
2. Determine complexity (simple vs complex)
|
||||
3. Apply fix using appropriate backend
|
||||
4. Verify syntax (no compilation errors)
|
||||
5. Append to context_accumulator
|
||||
|
||||
## Phase 4: Self-Validation
|
||||
|
||||
| Check | Method | Pass Criteria |
|
||||
|-------|--------|---------------|
|
||||
| Syntax | IDE diagnostics or tsc --noEmit | No errors |
|
||||
| File existence | Verify planned files exist | All present |
|
||||
| Acceptance criteria | Match against design guide | All met |
|
||||
|
||||
Validation steps:
|
||||
1. Run syntax check on modified files
|
||||
2. Verify all files from design guide exist
|
||||
3. Check acceptance criteria from design guide
|
||||
4. If validation fails -> attempt auto-fix (max 2 attempts)
|
||||
|
||||
### Context Accumulator Update
|
||||
|
||||
Append to context_accumulator and write summary to `<session>/artifacts/fixes/README.md`.
|
||||
|
||||
Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="implementer",
|
||||
type="state_update", data={
|
||||
completed_fixes: <count>,
|
||||
modified_files: [<file-list>],
|
||||
validation_passed: true
|
||||
})
|
||||
```
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If reusable code patterns or snippets created:
|
||||
1. Write code snippets to `<session>/wisdom/contributions/implementer-snippets-<timestamp>.md`
|
||||
2. Format: Use case, code snippet with comments, framework compatibility notes
|
||||
93
.codex/skills/team-ux-improve/roles/scanner/role.md
Normal file
93
.codex/skills/team-ux-improve/roles/scanner/role.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
role: scanner
|
||||
prefix: SCAN
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# UI Scanner
|
||||
|
||||
Scan UI components to identify interaction issues: unresponsive buttons, missing feedback mechanisms, state not refreshing.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Project path | Task description CONTEXT | Yes |
|
||||
| Framework | Task description CONTEXT | Yes |
|
||||
| Scan scope | Task description CONSTRAINTS | Yes |
|
||||
|
||||
1. Extract session path and project path from task description
|
||||
2. Detect framework from project structure:
|
||||
|
||||
| Signal | Framework |
|
||||
|--------|-----------|
|
||||
| package.json has "react" | React |
|
||||
| package.json has "vue" | Vue |
|
||||
| *.tsx files present | React |
|
||||
| *.vue files present | Vue |
|
||||
|
||||
3. Build file pattern list for scanning:
|
||||
- React: `**/*.tsx`, `**/*.jsx`, `**/use*.ts`
|
||||
- Vue: `**/*.vue`, `**/composables/*.ts`
|
||||
|
||||
### Wisdom Input
|
||||
|
||||
1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` if available
|
||||
2. Use anti-patterns to identify known UX issues during scanning
|
||||
3. Check `<session>/wisdom/patterns/ui-feedback.md` for expected feedback patterns
|
||||
|
||||
### Complex Analysis (use CLI)
|
||||
|
||||
For large projects with many components:
|
||||
|
||||
```
|
||||
Bash(`ccw cli -p "PURPOSE: Discover all UI components with user interactions
|
||||
CONTEXT: @<project-path>/**/*.tsx @<project-path>/**/*.vue
|
||||
EXPECTED: Component list with interaction types (click, submit, input, select)
|
||||
CONSTRAINTS: Focus on interactive components only" --tool gemini --mode analysis`)
|
||||
```
|
||||
|
||||
## Phase 3: Component Scanning
|
||||
|
||||
Scan strategy:
|
||||
|
||||
| Category | Detection Pattern | Severity |
|
||||
|----------|-------------------|----------|
|
||||
| Unresponsive actions | onClick/\@click without async handling or error catching | High |
|
||||
| Missing loading state | Form submit without isLoading/loading ref | High |
|
||||
| State not refreshing | Array.splice/push without reactive reassignment | High |
|
||||
| Missing error feedback | try/catch without error state or user notification | Medium |
|
||||
| Missing success feedback | API call without success confirmation | Medium |
|
||||
| No empty state | Data list without empty state placeholder | Low |
|
||||
| Input without validation | Form input without validation rules | Low |
|
||||
| Missing file selector | Text input for file/folder path without picker | Medium |
|
||||
|
||||
For each component file:
|
||||
1. Read file content
|
||||
2. Scan for interaction patterns using Grep
|
||||
3. Check for feedback mechanisms (loading, error, success states)
|
||||
4. Check state update patterns (mutation vs reactive)
|
||||
5. Record issues with file:line references
|
||||
|
||||
## Phase 4: Issue Report Generation
|
||||
|
||||
1. Classify issues by severity (High/Medium/Low)
|
||||
2. Group by category (unresponsive, missing feedback, state issues, input UX)
|
||||
3. Generate structured report and write to `<session>/artifacts/scan-report.md`
|
||||
4. Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="scanner",
|
||||
type="state_update", data={
|
||||
total_issues: <count>,
|
||||
high: <count>, medium: <count>, low: <count>,
|
||||
categories: [<category-list>],
|
||||
scanned_files: <count>
|
||||
})
|
||||
```
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If novel UX issues discovered that aren't in anti-patterns:
|
||||
1. Write findings to `<session>/wisdom/contributions/scanner-issues-<timestamp>.md`
|
||||
2. Format: Issue description, detection criteria, affected components
|
||||
84
.codex/skills/team-ux-improve/roles/tester/role.md
Normal file
84
.codex/skills/team-ux-improve/roles/tester/role.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
role: tester
|
||||
prefix: TEST
|
||||
inner_loop: false
|
||||
message_types: [state_update]
|
||||
---
|
||||
|
||||
# Test Engineer
|
||||
|
||||
Generate and run tests to verify fixes (loading states, error handling, state updates).
|
||||
|
||||
## Phase 2: Environment Detection
|
||||
|
||||
1. Detect test framework from project files:
|
||||
|
||||
| Signal | Framework |
|
||||
|--------|-----------|
|
||||
| package.json has "jest" | Jest |
|
||||
| package.json has "vitest" | Vitest |
|
||||
| package.json has "@testing-library/react" | React Testing Library |
|
||||
| package.json has "@vue/test-utils" | Vue Test Utils |
|
||||
|
||||
2. Get changed files from implementer state:
|
||||
```
|
||||
team_msg(operation="get_state", session_id=<session-id>, role="implementer")
|
||||
```
|
||||
|
||||
3. Load test strategy from design guide
|
||||
|
||||
### Wisdom Input
|
||||
|
||||
1. Read `<session>/wisdom/anti-patterns/common-ux-pitfalls.md` for common issues to test
|
||||
2. Read `<session>/wisdom/patterns/ui-feedback.md` for expected feedback behaviors to verify
|
||||
3. Use wisdom to design comprehensive test cases covering known edge cases
|
||||
|
||||
## Phase 3: Test Generation & Execution
|
||||
|
||||
### Test Generation
|
||||
|
||||
For each modified file, generate test cases covering loading states, error handling, state updates, and accessibility.
|
||||
|
||||
### Test Execution
|
||||
|
||||
Iterative test-fix cycle (max 5 iterations):
|
||||
|
||||
1. Run tests: `npm test` or `npm run test:unit`
|
||||
2. Parse results -> calculate pass rate
|
||||
3. If pass rate >= 95% -> exit (success)
|
||||
4. If pass rate < 95% and iterations < 5:
|
||||
- Analyze failures
|
||||
- Use CLI to generate fixes:
|
||||
```
|
||||
Bash(`ccw cli -p "PURPOSE: Fix test failures
|
||||
CONTEXT: @<test-file> @<source-file>
|
||||
EXPECTED: Fixed code that passes tests
|
||||
CONSTRAINTS: Maintain existing functionality" --tool gemini --mode write`)
|
||||
```
|
||||
- Increment iteration counter
|
||||
- Loop to step 1
|
||||
5. If iterations >= 5 -> send fix_required message
|
||||
|
||||
## Phase 4: Test Report
|
||||
|
||||
### Wisdom Contribution
|
||||
|
||||
If new edge cases or test patterns discovered:
|
||||
1. Write test findings to `<session>/wisdom/contributions/tester-edge-cases-<timestamp>.md`
|
||||
2. Format: Edge case description, test scenario, expected behavior, actual behavior
|
||||
|
||||
Write report to `<session>/artifacts/test-report.md`.
|
||||
|
||||
Share state via team_msg:
|
||||
```
|
||||
team_msg(operation="log", session_id=<session-id>, from="tester",
|
||||
type="state_update", data={
|
||||
total_tests: <count>,
|
||||
passed: <count>,
|
||||
failed: <count>,
|
||||
pass_rate: <percentage>,
|
||||
fix_iterations: <count>
|
||||
})
|
||||
```
|
||||
|
||||
If pass rate < 95%, send fix_required message to coordinator.
|
||||
@@ -1,87 +0,0 @@
|
||||
# UX Improvement — CSV Schema
|
||||
|
||||
## Master CSV: tasks.csv
|
||||
|
||||
### Column Definitions
|
||||
|
||||
#### Input Columns (Set by Decomposer)
|
||||
|
||||
| Column | Type | Required | Description | Example |
|
||||
|--------|------|----------|-------------|---------|
|
||||
| `id` | string | Yes | Unique task identifier | `"SCAN-001"` |
|
||||
| `title` | string | Yes | Short task title | `"Scan Button component"` |
|
||||
| `description` | string | Yes | Detailed task description (self-contained) | `"Scan Button component for UX issues..."` |
|
||||
| `deps` | string | No | Semicolon-separated dependency task IDs | `"EXPLORE-001"` |
|
||||
| `context_from` | string | No | Semicolon-separated task IDs for context | `"EXPLORE-001"` |
|
||||
| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` |
|
||||
| `role` | enum | Yes | Role name: `explorer`, `scanner`, `diagnoser`, `designer`, `implementer`, `tester` | `"scanner"` |
|
||||
| `component` | string | No | Component name being processed | `"Button"` |
|
||||
|
||||
#### 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) | `"[EXPLORE-001] Found 15 components..."` |
|
||||
|
||||
#### Output Columns (Set by Agent)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `status` | enum | `pending` → `completed` / `failed` / `skipped` | `"completed"` |
|
||||
| `findings` | string | Key discoveries (max 500 chars) | `"Found 3 UX issues: unresponsive onClick..."` |
|
||||
| `issues_found` | string | Number of issues found (scanner/diagnoser) | `"3"` |
|
||||
| `issues_fixed` | string | Number of issues fixed (implementer) | `"3"` |
|
||||
| `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 |
|
||||
|
||||
---
|
||||
|
||||
### Example Data
|
||||
|
||||
```csv
|
||||
id,title,description,deps,context_from,exec_mode,role,component,wave,status,findings,issues_found,issues_fixed,error
|
||||
EXPLORE-001,Framework Exploration,Explore React component patterns,,,"interactive",explorer,,1,completed,"Found 15 components using React hooks","","",""
|
||||
SCAN-001,Scan Button,Scan Button for UX issues,EXPLORE-001,EXPLORE-001,"csv-wave",scanner,Button,2,pending,"","","",""
|
||||
DIAG-001,Diagnose Button,Analyze root causes in Button,SCAN-001,SCAN-001,"csv-wave",diagnoser,Button,3,pending,"","","",""
|
||||
DESIGN-001,Design Button fixes,Design fix approach for Button,DIAG-001,DIAG-001,"interactive",designer,Button,4,pending,"","","",""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Discovery Types
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `ux_issue` | `component+type` | `{component, type, description, severity}` | UX issues discovered |
|
||||
| `pattern` | `pattern` | `{pattern, files[], description}` | UI patterns identified |
|
||||
| `fix_approach` | `component+issue` | `{component, issue, approach, rationale}` | Fix strategies |
|
||||
| `test_result` | `component+test` | `{component, test, status, details}` | Test outcomes |
|
||||
|
||||
### Discovery NDJSON Format
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-03-08T14:30:22Z","worker":"SCAN-001","type":"ux_issue","data":{"component":"Button","type":"unresponsive_click","description":"onClick handler not firing","severity":"high"}}
|
||||
{"ts":"2026-03-08T14:35:10Z","worker":"DIAG-001","type":"pattern","data":{"pattern":"event delegation","files":["Button.tsx"],"description":"Using event delegation pattern"}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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" |
|
||||
| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" |
|
||||
| Role valid | role ∈ {explorer, scanner, diagnoser, designer, implementer, tester} | "Invalid role: {role}" |
|
||||
54
.codex/skills/team-ux-improve/specs/pipelines.md
Normal file
54
.codex/skills/team-ux-improve/specs/pipelines.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Pipeline Definitions
|
||||
|
||||
UX improvement pipeline modes and task registry.
|
||||
|
||||
## Pipeline Modes
|
||||
|
||||
| Mode | Description | Task Chain |
|
||||
|------|-------------|------------|
|
||||
| standard | Full UX improvement pipeline | SCAN-001 -> DIAG-001 -> DESIGN-001 -> IMPL-001 -> TEST-001 |
|
||||
|
||||
## Standard Pipeline Task Registry
|
||||
|
||||
| Task ID | Role | blockedBy | Inner Loop | Description |
|
||||
|---------|------|-----------|------------|-------------|
|
||||
| SCAN-001 | scanner | [] | false | Scan UI components for interaction issues (unresponsive buttons, missing feedback, state problems) |
|
||||
| DIAG-001 | diagnoser | [SCAN-001] | false | Root cause diagnosis with fix recommendations |
|
||||
| DESIGN-001 | designer | [DIAG-001] | false | Feedback mechanism and state management solution design |
|
||||
| IMPL-001 | implementer | [DESIGN-001] | true | Code implementation with proper state handling |
|
||||
| TEST-001 | tester | [IMPL-001] | false | Test generation and validation (pass rate >= 95%, max 5 iterations) |
|
||||
|
||||
## Checkpoints
|
||||
|
||||
| Checkpoint | Trigger | Condition | Action |
|
||||
|------------|---------|-----------|--------|
|
||||
| Pipeline complete | TEST-001 completes | All tasks done | Coordinator Phase 5: wisdom consolidation + completion action |
|
||||
|
||||
## Test Iteration Behavior
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| pass_rate >= 95% | Pipeline complete |
|
||||
| pass_rate < 95% AND iterations < 5 | Tester generates fixes, re-runs (inner loop within TEST-001) |
|
||||
| pass_rate < 95% AND iterations >= 5 | Accept current state, report to coordinator |
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Task | Output Path |
|
||||
|------|-------------|
|
||||
| SCAN-001 | <session>/artifacts/scan-report.md |
|
||||
| DIAG-001 | <session>/artifacts/diagnosis.md |
|
||||
| DESIGN-001 | <session>/artifacts/design-guide.md |
|
||||
| IMPL-001 | <session>/artifacts/fixes/ |
|
||||
| TEST-001 | <session>/artifacts/test-report.md |
|
||||
|
||||
## Wisdom System
|
||||
|
||||
Workers contribute learnings to `<session>/wisdom/contributions/`. On pipeline completion, coordinator asks user to merge approved contributions to permanent wisdom at `~ or <project>/.claude/skills/team-ux-improve/wisdom/`.
|
||||
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| wisdom/principles/ | Core UX principles |
|
||||
| wisdom/patterns/ | Solution patterns (ui-feedback, state-management) |
|
||||
| wisdom/anti-patterns/ | Issues to avoid (common-ux-pitfalls) |
|
||||
| wisdom/contributions/ | Session worker contributions (pending review) |
|
||||
181
.codex/skills/team-ux-improve/specs/team-config.json
Normal file
181
.codex/skills/team-ux-improve/specs/team-config.json
Normal file
@@ -0,0 +1,181 @@
|
||||
{
|
||||
"version": "5.0.0",
|
||||
"team_name": "ux-improve",
|
||||
"team_display_name": "UX Improve",
|
||||
"team_purpose": "Systematically discover and fix UI/UX interaction issues including unresponsive buttons, missing feedback, and state refresh problems",
|
||||
"skill_name": "team-ux-improve",
|
||||
"skill_path": "~ or <project>/.claude/skills/team-ux-improve/",
|
||||
"worker_agent": "team-worker",
|
||||
"pipeline_type": "Standard",
|
||||
"completion_action": "interactive",
|
||||
"has_inline_discuss": false,
|
||||
"has_shared_explore": true,
|
||||
"roles": [
|
||||
{
|
||||
"name": "coordinator",
|
||||
"display_name": "Coordinator",
|
||||
"type": "orchestrator",
|
||||
"responsibility_type": "orchestration",
|
||||
"role_spec": "roles/coordinator/role.md",
|
||||
"task_prefix": null,
|
||||
"inner_loop": false,
|
||||
"allowed_tools": ["Agent", "AskUserQuestion", "Read", "Write", "Bash", "Glob", "Grep", "TaskList", "TaskGet", "TaskUpdate", "TaskCreate", "TeamCreate", "TeamDelete", "SendMessage", "mcp__ccw-tools__team_msg"],
|
||||
"description": "Orchestrates the UX improvement pipeline, spawns workers, monitors progress"
|
||||
},
|
||||
{
|
||||
"name": "scanner",
|
||||
"display_name": "UI Scanner",
|
||||
"type": "worker",
|
||||
"responsibility_type": "read_only_analysis",
|
||||
"role_spec": "roles/scanner/role.md",
|
||||
"task_prefix": "SCAN",
|
||||
"inner_loop": false,
|
||||
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||
"description": "Scans UI components to identify interaction issues (unresponsive buttons, missing feedback, state not refreshing)",
|
||||
"frontmatter": {
|
||||
"prefix": "SCAN",
|
||||
"inner_loop": false,
|
||||
"message_types": {
|
||||
"success": "scan_complete",
|
||||
"error": "error"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "diagnoser",
|
||||
"display_name": "State Diagnoser",
|
||||
"type": "worker",
|
||||
"responsibility_type": "orchestration",
|
||||
"role_spec": "roles/diagnoser/role.md",
|
||||
"task_prefix": "DIAG",
|
||||
"inner_loop": false,
|
||||
"allowed_tools": ["Read", "Grep", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||
"description": "Diagnoses root causes of UI issues: state management problems, event binding failures, async handling errors",
|
||||
"frontmatter": {
|
||||
"prefix": "DIAG",
|
||||
"inner_loop": false,
|
||||
"message_types": {
|
||||
"success": "diag_complete",
|
||||
"error": "error"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "designer",
|
||||
"display_name": "UX Designer",
|
||||
"type": "worker",
|
||||
"responsibility_type": "orchestration",
|
||||
"role_spec": "roles/designer/role.md",
|
||||
"task_prefix": "DESIGN",
|
||||
"inner_loop": false,
|
||||
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||
"description": "Designs feedback mechanisms (loading/error/success states) and state management patterns (React/Vue reactive updates)",
|
||||
"frontmatter": {
|
||||
"prefix": "DESIGN",
|
||||
"inner_loop": false,
|
||||
"message_types": {
|
||||
"success": "design_complete",
|
||||
"error": "error"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "implementer",
|
||||
"display_name": "Code Implementer",
|
||||
"type": "worker",
|
||||
"responsibility_type": "code_generation",
|
||||
"role_spec": "roles/implementer/role.md",
|
||||
"task_prefix": "IMPL",
|
||||
"inner_loop": true,
|
||||
"allowed_tools": ["Read", "Write", "Edit", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__edit_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||
"description": "Generates executable fix code with proper state management, event handling, and UI feedback bindings",
|
||||
"frontmatter": {
|
||||
"prefix": "IMPL",
|
||||
"inner_loop": true,
|
||||
"message_types": {
|
||||
"success": "impl_complete",
|
||||
"error": "error"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "tester",
|
||||
"display_name": "Test Engineer",
|
||||
"type": "worker",
|
||||
"responsibility_type": "validation",
|
||||
"role_spec": "roles/tester/role.md",
|
||||
"task_prefix": "TEST",
|
||||
"inner_loop": false,
|
||||
"allowed_tools": ["Read", "Write", "Bash", "mcp__ccw-tools__read_file", "mcp__ccw-tools__write_file", "mcp__ccw-tools__team_msg", "TaskList", "TaskGet", "TaskUpdate", "SendMessage"],
|
||||
"description": "Generates test cases to verify fixes (loading states, error handling, state updates)",
|
||||
"frontmatter": {
|
||||
"prefix": "TEST",
|
||||
"inner_loop": false,
|
||||
"message_types": {
|
||||
"success": "test_complete",
|
||||
"error": "error",
|
||||
"fix": "fix_required"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"utility_members": [
|
||||
{
|
||||
"name": "explorer",
|
||||
"display_name": "Codebase Explorer",
|
||||
"role_spec": "roles/explorer/role.md",
|
||||
"callable_by": "coordinator",
|
||||
"purpose": "Explore codebase for UI component patterns, state management conventions, and framework-specific patterns",
|
||||
"allowed_tools": ["Read", "Grep", "Glob", "Bash", "mcp__ace-tool__search_context", "mcp__ccw-tools__read_file", "mcp__ccw-tools__team_msg"],
|
||||
"frontmatter": {
|
||||
"prefix": "EXPLORE",
|
||||
"inner_loop": false,
|
||||
"message_types": {
|
||||
"success": "explore_complete",
|
||||
"error": "error"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"pipeline": {
|
||||
"stages": [
|
||||
{
|
||||
"stage_id": 1,
|
||||
"stage_name": "UI Scanning",
|
||||
"roles": ["scanner"],
|
||||
"dependencies": [],
|
||||
"description": "Scan UI components for interaction issues"
|
||||
},
|
||||
{
|
||||
"stage_id": 2,
|
||||
"stage_name": "Root Cause Diagnosis",
|
||||
"roles": ["diagnoser"],
|
||||
"dependencies": ["scanner"],
|
||||
"description": "Diagnose root causes of identified issues"
|
||||
},
|
||||
{
|
||||
"stage_id": 3,
|
||||
"stage_name": "Solution Design",
|
||||
"roles": ["designer"],
|
||||
"dependencies": ["diagnoser"],
|
||||
"description": "Design feedback mechanisms and state management solutions"
|
||||
},
|
||||
{
|
||||
"stage_id": 4,
|
||||
"stage_name": "Code Implementation",
|
||||
"roles": ["implementer"],
|
||||
"dependencies": ["designer"],
|
||||
"description": "Generate fix code with proper state handling"
|
||||
},
|
||||
{
|
||||
"stage_id": 5,
|
||||
"stage_name": "Test Validation",
|
||||
"roles": ["tester"],
|
||||
"dependencies": ["implementer"],
|
||||
"description": "Generate and run tests to verify fixes"
|
||||
}
|
||||
],
|
||||
"diagram": "scanner (SCAN) → diagnoser (DIAG) → designer (DESIGN) → implementer (IMPL) → tester (TEST)",
|
||||
"fast_advance_eligible": ["scanner→diagnoser", "diagnoser→designer", "designer→implementer"]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
# Common UX Pitfalls
|
||||
|
||||
## Interaction Issues
|
||||
- Buttons without loading states during async operations
|
||||
- Missing error handling with user feedback
|
||||
- State changes without visual updates
|
||||
- Double-click vulnerabilities
|
||||
|
||||
## State Issues
|
||||
- Stale data after mutations
|
||||
- Race conditions in async operations
|
||||
- Missing rollback for failed optimistic updates
|
||||
|
||||
## Feedback Issues
|
||||
- Silent failures without user notification
|
||||
- Generic error messages without actionable guidance
|
||||
- Missing confirmation for destructive actions
|
||||
@@ -0,0 +1,14 @@
|
||||
# State Management Patterns
|
||||
|
||||
## Local Component State
|
||||
- Use for UI-only state (open/closed, hover, focus)
|
||||
- Keep close to where it's used
|
||||
|
||||
## Shared State
|
||||
- Lift state to lowest common ancestor
|
||||
- Use context or state management library for deep trees
|
||||
|
||||
## Async State
|
||||
- Track loading, error, and success states
|
||||
- Handle race conditions with request cancellation
|
||||
- Implement retry logic with exponential backoff
|
||||
16
.codex/skills/team-ux-improve/wisdom/patterns/ui-feedback.md
Normal file
16
.codex/skills/team-ux-improve/wisdom/patterns/ui-feedback.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# UI Feedback Patterns
|
||||
|
||||
## Loading States
|
||||
- Use skeleton loaders for content areas
|
||||
- Disable buttons during async operations
|
||||
- Show progress indicators for long operations
|
||||
|
||||
## Error Handling
|
||||
- Display errors inline when possible
|
||||
- Provide actionable error messages
|
||||
- Allow retry for transient failures
|
||||
|
||||
## Success Feedback
|
||||
- Toast notifications for non-critical successes
|
||||
- Inline confirmation for critical actions
|
||||
- Auto-dismiss non-critical notifications
|
||||
@@ -0,0 +1,16 @@
|
||||
# General UX Principles
|
||||
|
||||
## Feedback & Responsiveness
|
||||
- Every user action should have immediate visual feedback
|
||||
- Loading states must be shown for operations >200ms
|
||||
- Success/error states should be clearly communicated
|
||||
|
||||
## State Management
|
||||
- UI state should reflect the underlying data state
|
||||
- Optimistic updates should have rollback mechanisms
|
||||
- State changes should be atomic and predictable
|
||||
|
||||
## Accessibility
|
||||
- Interactive elements must be keyboard accessible
|
||||
- Color should not be the only indicator of state
|
||||
- Focus states must be visible
|
||||
Reference in New Issue
Block a user