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 |
|
||||
|
||||
Reference in New Issue
Block a user