feat: Implement UX improvement pipeline with role specifications and task management

- Added role specifications for explorer, implementer, scanner, tester, and diagnoser.
- Created dispatch and monitor commands for orchestrating task execution.
- Defined team configuration for the UX improvement pipeline, including roles and responsibilities.
- Established structured task descriptions for scanning, diagnosing, designing, implementing, and testing UI components.
- Introduced caching mechanisms for exploration results and context accumulation for implementer tasks.
- Enhanced error handling and validation processes across roles.
This commit is contained in:
catlog22
2026-03-05 16:42:56 +08:00
parent f6c7c14042
commit 3d92478772
18 changed files with 2039 additions and 122 deletions

View File

@@ -0,0 +1,212 @@
# 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:
```
TaskCreate({
subject: "<TASK-ID>",
owner: "<role>",
description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
TASK:
- <step 1: specific action>
- <step 2: specific action>
- <step 3: specific action>
CONTEXT:
- Session: <session-folder>
- 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>",
blockedBy: [<dependency-list>],
status: "pending"
})
```
### Standard Pipeline Tasks
**SCAN-001: UI Component Scanning**
```
TaskCreate({
subject: "SCAN-001",
owner: "scanner",
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",
blockedBy: [],
status: "pending"
})
```
**DIAG-001: Root Cause Diagnosis**
```
TaskCreate({
subject: "DIAG-001",
owner: "diagnoser",
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",
blockedBy: ["SCAN-001"],
status: "pending"
})
```
**DESIGN-001: Solution Design**
```
TaskCreate({
subject: "DESIGN-001",
owner: "designer",
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",
blockedBy: ["DIAG-001"],
status: "pending"
})
```
**IMPL-001: Code Implementation**
```
TaskCreate({
subject: "IMPL-001",
owner: "implementer",
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",
blockedBy: ["DESIGN-001"],
status: "pending"
})
```
**TEST-001: Test Validation**
```
TaskCreate({
subject: "TEST-001",
owner: "tester",
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",
blockedBy: ["IMPL-001"],
status: "pending"
})
```
---
## Phase 4: Validation
1. Verify all tasks created successfully
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 |

View File

@@ -0,0 +1,131 @@
# Monitor Command
## Purpose
Handle worker callbacks, status checks, pipeline advancement, and completion detection.
---
## Handlers
### handleCallback
**Trigger**: Worker SendMessage with `[scanner]`, `[diagnoser]`, `[designer]`, `[implementer]`, or `[tester]` tag.
1. Parse worker role from message tag
2. Mark corresponding task as completed: `TaskUpdate({ taskId: <task-id>, status: "completed" })`
3. Log completion to message bus:
```
team_msg(operation="log", session_id=<session-id>, from="coordinator",
type="task_complete", data={ role: <role>, task_id: <task-id> })
```
4. Check if all tasks completed -> handleComplete
5. Otherwise -> handleSpawnNext
### handleCheck
**Trigger**: User "check" or "status" command.
1. Load TaskList
2. Build status graph:
```
Pipeline Status:
✅ SCAN-001 (scanner) - completed
✅ DIAG-001 (diagnoser) - completed
🔄 DESIGN-001 (designer) - in_progress
⏳ IMPL-001 (implementer) - pending [blocked by DESIGN-001]
⏳ TEST-001 (tester) - pending [blocked by IMPL-001]
```
3. Output status graph, do NOT advance pipeline
4. STOP
### handleResume
**Trigger**: User "resume" or "continue" command.
1. Load TaskList
2. Check for fast-advance orphans:
- Tasks with status "in_progress" but no active worker
- Reset orphans to "pending"
3. -> handleSpawnNext
### handleSpawnNext
**Trigger**: After handleCallback or handleResume.
1. Load TaskList
2. Find ready tasks:
- status = "pending"
- All blockedBy tasks have status "completed"
3. For each ready task:
- Extract role from task owner
- Extract inner_loop from task description metadata
- Spawn team-worker agent:
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: "ux-improve",
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-ux-improve/role-specs/<role>.md
session: <session-folder>
session_id: <session-id>
team_name: ux-improve
requirement: <task-description>
inner_loop: <inner-loop-value>
Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
})
```
4. STOP (wait for next callback)
### handleConsensus
**Trigger**: consensus_blocked message from worker.
Route by severity:
| Severity | Action |
|----------|--------|
| HIGH | Pause pipeline, AskUserQuestion for resolution |
| MEDIUM | Log warning, continue pipeline |
| LOW | Log info, continue pipeline |
### handleComplete
**Trigger**: All tasks have status "completed".
1. Verify all tasks completed via TaskList
2. Generate pipeline summary:
- Total tasks: 5
- Duration: <calculated>
- Deliverables: list artifact paths
3. Execute completion action (see coordinator Phase 5)
---
## Fast-Advance Detection
When handleCallback detects a completed task:
| Condition | Action |
|-----------|--------|
| Exactly 1 ready successor, simple linear | Worker already fast-advanced, log sync |
| Multiple ready successors | Coordinator spawns all |
| No ready successors, all done | -> handleComplete |
| No ready successors, some pending | Wait (blocked tasks) |
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Worker callback with unknown role | Log warning, ignore |
| Task not found for callback | Log error, check TaskList |
| Spawn fails | Mark task as failed, log error, try next ready task |
| All tasks failed | Report failure, execute completion action |

View File

@@ -0,0 +1,220 @@
# Coordinator Role
## Identity
- **Name**: coordinator
- **Type**: Orchestration
- **Responsibility**: Orchestrate UX improvement pipeline, spawn workers, monitor progress, handle completion
## Boundaries
### MUST
- Parse user requirements (project path, framework)
- Create team and session structure
- Generate task chain via dispatch.md
- Spawn team-worker agents with correct role-spec paths
- Monitor worker callbacks and advance pipeline
- Execute completion action when pipeline finishes
- Handle user commands (check, resume)
### MUST NOT
- Execute worker domain logic directly
- Skip completion action
- Spawn workers as general-purpose agents (must use team-worker)
---
## Command Execution Protocol
When coordinator needs to execute a command (dispatch, monitor):
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
3. **Commands are inline execution guides** - NOT separate agents or subprocesses
4. **Execute synchronously** - complete the command workflow before proceeding
Example:
```
Phase 3 needs task dispatch
-> Read roles/coordinator/commands/dispatch.md
-> Execute Phase 2 (Context Loading)
-> Execute Phase 3 (Task Chain Creation)
-> Execute Phase 4 (Validation)
-> Continue to Phase 4
```
---
## Entry Router
When coordinator is invoked, detect invocation type:
| Detection | Condition | Handler |
|-----------|-----------|---------|
| Worker callback | Message contains `[scanner]`, `[diagnoser]`, etc. | -> handleCallback |
| Status check | Arguments contain "check" or "status" | -> handleCheck |
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
| Interrupted session | Active/paused session exists | -> Phase 0 (Resume Check) |
| New session | None of above | -> Phase 1 (Requirement Clarification) |
For callback/check/resume: load `commands/monitor.md` and execute handler, then STOP.
### Router Implementation
1. **Load session context** (if exists):
- Scan `.workflow/.team/ux-improve-*/.msg/meta.json` for active/paused sessions
- If found, extract known worker roles from meta.json or SKILL.md Role Registry
2. **Parse $ARGUMENTS** for detection keywords
3. **Route to handler**:
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
- For Phase 0: Execute Session Resume Check below
- For Phase 1: Execute Requirement Clarification below
---
## Phase 0: Session Resume Check
**Trigger**: Interrupted session detected (active/paused session exists)
1. Load session meta.json
2. Audit TaskList -> reconcile session state vs task status
3. Reset in_progress tasks -> pending (interrupted tasks)
4. Check for fast-advance orphans (tasks spawned but not in TaskList)
5. AskUserQuestion: "Resume session <session-id>? [Yes/No/New]"
- Yes -> Phase 4 (coordination loop)
- No -> Archive old session -> Phase 1
- New -> Keep old session paused -> Phase 1
---
## Phase 1: Requirement Clarification
1. Parse $ARGUMENTS for project path and framework flag
2. If project path missing -> AskUserQuestion for path
3. If framework not specified -> detect from package.json or ask user
4. Validate project path exists
5. Store: project_path, framework (react|vue)
---
## Phase 2: Team Creation
1. Generate session ID: `ux-improve-<timestamp>`
2. Create session directory structure:
```
.workflow/.team/<session-id>/
├── .msg/
├── artifacts/
├── explorations/
└── wisdom/
```
3. TeamCreate(team_name="ux-improve")
4. Initialize meta.json with pipeline config:
```
team_msg(operation="log", session_id=<session-id>, from="coordinator",
type="state_update",
data={
pipeline_mode: "standard",
pipeline_stages: ["scan", "diagnose", "design", "implement", "test"],
project_path: <path>,
framework: <framework>
})
```
---
## Phase 3: Task Chain Creation
Delegate to dispatch.md:
1. Read `roles/coordinator/commands/dispatch.md`
2. Execute Phase 2 (Context Loading)
3. Execute Phase 3 (Task Chain Creation)
4. Execute Phase 4 (Validation)
---
## Phase 4: Spawn-and-Stop Coordination
1. Find ready tasks (status=pending, no blockedBy or all blockedBy completed)
2. For each ready task:
- Extract role from task owner
- Spawn team-worker agent with role-spec path
- Use spawn template from SKILL.md
3. STOP (idle, wait for worker callbacks)
**Spawn template**:
```
Agent({
subagent_type: "team-worker",
description: "Spawn <role> worker",
team_name: "ux-improve",
name: "<role>",
run_in_background: true,
prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/team-ux-improve/role-specs/<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-spec Phase 2-4 -> built-in Phase 5 (report).`
})
```
**Inner loop roles**: implementer (inner_loop: true)
---
## Phase 5: Report + Completion Action
1. Load session state -> count completed tasks, duration
2. List deliverables with output paths:
- artifacts/scan-report.md
- artifacts/diagnosis.md
- artifacts/design-guide.md
- artifacts/fixes/
- artifacts/test-report.md
3. **Completion Action** (interactive mode):
```
AskUserQuestion({
questions: [{
question: "Team pipeline complete. What would you like to do?",
header: "Completion",
multiSelect: false,
options: [
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
]
}]
})
```
4. Handle user choice:
| Choice | Steps |
|--------|-------|
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete("ux-improve") -> output final summary with artifact paths |
| Keep Active | Update session status="paused" -> output: "Session paused. Resume with: Skill(skill='team-ux-improve', args='resume')" |
| Export Results | AskUserQuestion for target directory -> copy all artifacts -> Archive & Clean flow |
---
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Project path invalid | Re-prompt user for valid path |
| Framework detection fails | AskUserQuestion for framework selection |
| Worker spawn fails | Log error, mark task as failed, continue with other tasks |
| TeamCreate fails | Error: cannot proceed without team |
| Completion action timeout (5 min) | Default to Keep Active |