claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-ux-improve/roles/coordinator/commands/analyze.md

@@ -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" }
+}
+```

package/.codex/skills/team-ux-improve/roles/coordinator/commands/dispatch.md

@@ -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 |

package/.codex/skills/team-ux-improve/roles/coordinator/commands/monitor.md

@@ -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

package/.codex/skills/team-ux-improve/roles/coordinator/role.md

@@ -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 |