claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-frontend-debug/roles/coordinator/commands/monitor.md

@@ -0,0 +1,143 @@
+# 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
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [role-name] | handleCallback |
+| "need_more_evidence" | handleIteration |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed. Process and advance.
+
+1. Find matching worker by role in message
+2. Check if progress update (inner loop) or final completion
+3. Progress -> update session state, STOP
+4. Completion -> mark task done (read `<session>/tasks.json`, set status to "completed", write back), remove from active_workers
+5. Check for special conditions:
+   - **TEST-001 with 0 issues** -> skip ANALYZE/FIX/VERIFY (mark as completed in tasks.json), handleComplete
+   - **TEST-001 with only warnings** -> request_user_input: fix warnings or complete
+   - **TEST-001 with high/medium issues** -> proceed to ANALYZE-001
+   - ANALYZE-001 with `need_more_evidence: true` -> handleIteration
+   - VERIFY-001 with `verdict: fail` -> re-dispatch FIX (add FIX-002 entry to tasks.json blocked by VERIFY-001)
+   - VERIFY-001 with `verdict: pass` -> handleComplete
+6. -> handleSpawnNext
+
+## handleIteration
+
+Analyzer needs more evidence. Create supplemental reproduction task.
+
+1. Parse Analyzer's evidence request (dimensions, specific actions)
+2. Add REPRODUCE-002 entry to `<session>/tasks.json`:
+   - Set owner to "reproducer" (no blockedBy -- can start immediately)
+3. Add ANALYZE-002 entry to `<session>/tasks.json`:
+   - Set blockedBy: ["REPRODUCE-002"]
+   - Update FIX-001 entry to add ANALYZE-002 to its blockedBy
+4. Write updated tasks.json
+5. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+Output:
+```
+[coordinator] Debug Pipeline Status
+[coordinator] Bug: <bug-description-summary>
+[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] Active: <workers with elapsed time>
+[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator] Evidence: <list of collected evidence types>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+## handleResume
+
+1. No active workers -> handleSpawnNext
+2. Has active -> check each status
+   - completed -> mark done
+   - in_progress -> still running
+3. Some completed -> handleSpawnNext
+4. All running -> report status, STOP
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect: completedSubjects, inProgressSubjects, readySubjects (from tasks.json)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check if inner loop role with active worker -> skip (worker picks up)
+   b. Standard spawn:
+      - Update task status to "in_progress" in tasks.json
+      - team_msg log -> task_unblocked
+      - Spawn team-worker:
+        ```
+        spawn_agent({
+          agent_type: "team_worker",
+          items: [{
+            description: "Spawn <role> worker for <task-id>",
+            team_name: "frontend-debug",
+            name: "<role>",
+            prompt: `## Role Assignment
+        role: <role>
+        role_spec: ~  or <project>/.codex/skills/team-frontend-debug/roles/<role>/role.md
+        session: <session-folder>
+        session_id: <session-id>
+        team_name: frontend-debug
+        requirement: <task-description>
+        inner_loop: <true|false>
+
+        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.`
+          }]
+        })
+        ```
+      - Add to active_workers
+5. Update session, output summary, STOP
+6. Use `wait_agent({ ids: [<spawned-agent-ids>] })` to wait for callbacks. Workers use `report_agent_job_result()` to send results back.
+
+## handleComplete
+
+Pipeline done. Generate debug report and completion action.
+
+1. Generate debug summary:
+   - Bug description and reproduction results
+   - Root cause analysis (from ANALYZE artifacts)
+   - Code changes applied (from FIX artifacts)
+   - Verification verdict (from VERIFY artifacts)
+   - Evidence inventory (screenshots, logs, traces)
+2. Read session.completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, remove/archive session folder)
+   - auto_keep -> Keep Active (status=paused)
+
+## handleAdapt
+
+Not typically needed for debug pipeline. If Analyzer identifies a dimension not covered:
+
+1. Parse gap description
+2. Check if reproducer can cover it -> add to evidence plan
+3. Create supplemental REPRODUCE task entry in tasks.json
+
+## 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-frontend-debug/roles/coordinator/role.md

@@ -0,0 +1,131 @@
+# Coordinator Role
+
+Orchestrate team-frontend-debug: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze bug report -> Create team -> Dispatch debug tasks -> Monitor progress -> Report results
+
+## Boundaries
+
+### MUST
+- Parse bug report description (text-level only, no codebase reading)
+- Create team and spawn team-worker agents in background
+- Dispatch tasks with proper dependency chains
+- Monitor progress via callbacks and route messages
+- Maintain session state (team-session.json)
+- Handle iteration loops (analyzer requesting more evidence)
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Read source code or explore codebase (delegate to workers)
+- Execute debug/fix work directly
+- Modify task output artifacts
+- Spawn workers with general-purpose agent (MUST use team-worker)
+- Generate more than 5 worker roles
+
+## Command Execution Protocol
+When coordinator needs to execute a specific phase:
+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 [role-name] | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Iteration request | Message contains "need_more_evidence" | -> handleIteration (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active session in .workflow/.team/TFD-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/iteration/complete: load commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan .workflow/.team/TFD-*/team-session.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Audit tasks.json, reset in_progress->pending
+   b. Rebuild team workers
+   c. Kick first ready task
+4. Multiple -> request_user_input for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse user input — detect mode:
+   - Feature list / 功能清单 → **test-pipeline**
+   - Bug report / 错误描述 → **debug-pipeline**
+   - Ambiguous → request_user_input to clarify
+2. Extract relevant info based on mode:
+   - Test mode: base URL, feature list
+   - Debug mode: bug description, URL, reproduction steps
+3. Clarify if ambiguous (request_user_input)
+4. Delegate to @commands/analyze.md
+5. Output: task-analysis.json
+6. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## 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-frontend-debug`
+2. Generate session ID: TFD-<slug>-<date>
+3. Create session folder structure:
+   ```
+   .workflow/.team/TFD-<slug>-<date>/
+   ├── team-session.json
+   ├── evidence/
+   ├── artifacts/
+   ├── wisdom/
+   └── .msg/
+   ```
+3. Initialize session folder (replaces TeamCreate)
+4. Read specs/pipelines.md -> select pipeline (default: debug-pipeline)
+5. Register roles in team-session.json
+6. Initialize pipeline via team_msg state_update
+7. Write team-session.json
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph from task-analysis.json
+2. Read specs/pipelines.md for debug-pipeline task registry
+3. Topological sort tasks
+4. Build tasks array as JSON entries in `<session>/tasks.json`; set deps via `blockedBy` field in each entry
+5. Update team-session.json
+
+## 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. Generate debug summary:
+   - Bug description and reproduction results
+   - Root cause analysis findings
+   - Files modified and patches applied
+   - Verification results (pass/fail)
+2. Execute completion action per session.completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Bug report too vague | request_user_input for URL, steps, expected behavior |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending, respawn |
+| Dependency cycle | Detect in analysis, halt |
+| Browser unavailable | Report to user, suggest manual steps |

package/.codex/skills/team-frontend-debug/roles/fixer/role.md

@@ -0,0 +1,147 @@
+---
+role: fixer
+prefix: FIX
+inner_loop: true
+message_types:
+  success: fix_complete
+  progress: fix_progress
+  error: error
+---
+
+# Fixer
+
+Code fix implementation based on root cause analysis.
+
+## Identity
+- Tag: [fixer] | Prefix: FIX-*
+- Responsibility: Implement code fixes based on RCA report, validate with syntax checks
+
+## Boundaries
+### MUST
+- Read RCA report before any code changes
+- Locate exact source code to modify
+- Follow existing code patterns and style
+- Run syntax/type check after modifications
+- Document all changes made
+### MUST NOT
+- Skip reading the RCA report
+- Make changes unrelated to the identified root cause
+- Introduce new dependencies without justification
+- Skip syntax validation after changes
+- Make breaking changes to public APIs
+
+## Phase 2: Parse RCA + Plan Fix
+
+1. Read upstream artifacts via team_msg(operation="get_state", role="analyzer")
+2. Extract RCA report path from analyzer's state_update ref
+3. Load RCA report: `<session>/artifacts/ANALYZE-001-rca.md`
+4. Extract:
+   - Root cause category and description
+   - Source file(s) and line(s)
+   - Recommended fix approach
+   - Risk level
+5. Read identified source files to understand context
+6. Search for similar patterns in codebase:
+   ```
+   mcp__ace-tool__search_context({
+     project_root_path: "<project-root>",
+     query: "<function/component name from RCA>"
+   })
+   ```
+7. Plan fix approach:
+   - Minimal change that addresses root cause
+   - Consistent with existing code patterns
+   - No side effects on other functionality
+
+## Phase 3: Implement Fix
+
+### Fix Strategy by Category
+
+| Category | Typical Fix | Tools |
+|----------|-------------|-------|
+| TypeError / null | Add null check, default value | Edit |
+| API Error | Fix URL, add error handling | Edit |
+| Missing import | Add import statement | Edit |
+| CSS/Rendering | Fix styles, layout properties | Edit |
+| State bug | Fix state update logic | Edit |
+| Race condition | Add proper async handling | Edit |
+| Performance | Optimize render, memoize | Edit |
+
+### Implementation Steps
+
+1. Read the target file(s)
+2. Apply minimal code changes using Edit tool
+3. If Edit fails, use mcp__ccw-tools__edit_file as fallback
+4. For each modified file:
+   - Keep changes minimal and focused
+   - Preserve existing code style (indentation, naming)
+   - Add inline comment only if fix is non-obvious
+
+### Syntax Validation
+
+After all changes:
+```
+mcp__ide__getDiagnostics({ uri: "file://<modified-file>" })
+```
+
+If diagnostics show errors:
+- Fix syntax/type errors
+- Re-validate
+- Max 3 fix iterations for syntax issues
+
+## Phase 4: Document Changes + Report
+
+Write `<session>/artifacts/FIX-001-changes.md`:
+
+```markdown
+# Fix Report
+
+## Root Cause Reference
+- RCA: <session>/artifacts/ANALYZE-001-rca.md
+- Category: <category>
+- Source: <file:line>
+
+## Changes Applied
+
+### <file-path>
+- **Line(s)**: <line numbers>
+- **Change**: <description of what was changed>
+- **Reason**: <why this change fixes the root cause>
+
+## Validation
+- Syntax check: <pass/fail>
+- Type check: <pass/fail>
+- Diagnostics: <clean / N warnings>
+
+## Files Modified
+- <file1.ts>
+- <file2.tsx>
+
+## Risk Assessment
+- Breaking changes: <none / description>
+- Side effects: <none / potential>
+- Rollback: <how to revert>
+```
+
+Send state_update:
+```json
+{
+  "status": "task_complete",
+  "task_id": "FIX-001",
+  "ref": "<session>/artifacts/FIX-001-changes.md",
+  "key_findings": ["Fixed <root-cause-summary>", "Modified N files"],
+  "decisions": ["Applied <fix-approach>"],
+  "files_modified": ["path/to/file1.ts", "path/to/file2.tsx"],
+  "verification": "self-validated"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Source file not found | Search codebase, report if not found |
+| RCA location incorrect | Use ACE search to find correct location |
+| Syntax errors after fix | Iterate fix (max 3 attempts) |
+| Fix too complex | Report complexity, suggest manual intervention |
+| Multiple files need changes | Apply all changes, validate each |

package/.codex/skills/team-frontend-debug/roles/reproducer/role.md

@@ -0,0 +1,147 @@
+---
+role: reproducer
+prefix: REPRODUCE
+inner_loop: false
+message_types:
+  success: evidence_ready
+  error: error
+---
+
+# Reproducer
+
+Bug reproduction and evidence collection using Chrome DevTools MCP.
+
+## Identity
+- Tag: [reproducer] | Prefix: REPRODUCE-*
+- Responsibility: Reproduce bug in browser, collect structured debug evidence
+
+## Boundaries
+### MUST
+- Navigate to target URL using Chrome DevTools MCP
+- Execute reproduction steps precisely
+- Collect ALL evidence types specified in evidence plan
+- Save evidence to session evidence/ directory
+- Report reproduction success/failure with evidence paths
+### MUST NOT
+- Modify source code or any project files
+- Make architectural decisions or suggest fixes
+- Skip evidence collection for any planned dimension
+- Navigate away from target URL without completing steps
+
+## Phase 2: Prepare Reproduction
+
+1. Read upstream artifacts via team_msg(operation="get_state")
+2. Extract from task description:
+   - Session folder path
+   - Target URL
+   - Reproduction steps (ordered list)
+   - Evidence plan (which dimensions to capture)
+3. Verify browser is accessible:
+   ```
+   mcp__chrome-devtools__list_pages()
+   ```
+4. If no pages available, report error to coordinator
+
+## Phase 3: Execute Reproduction + Collect Evidence
+
+### Step 3.1: Navigate to Target
+
+```
+mcp__chrome-devtools__navigate_page({ type: "url", url: "<target-url>" })
+```
+
+Wait for page load:
+```
+mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
+```
+
+### Step 3.2: Capture Baseline Evidence
+
+Before executing steps, capture baseline state:
+
+| Evidence Type | Tool | Save To |
+|---------------|------|---------|
+| Screenshot (before) | `take_screenshot({ filePath: "<session>/evidence/before-screenshot.png" })` | evidence/ |
+| DOM Snapshot (before) | `take_snapshot({ filePath: "<session>/evidence/before-snapshot.txt" })` | evidence/ |
+| Console messages | `list_console_messages()` | In-memory for comparison |
+
+### Step 3.3: Execute Reproduction Steps
+
+For each reproduction step:
+
+1. Parse action type from step description:
+   | Action | Tool |
+   |--------|------|
+   | Click element | `mcp__chrome-devtools__click({ uid: "<uid>" })` |
+   | Fill input | `mcp__chrome-devtools__fill({ uid: "<uid>", value: "<value>" })` |
+   | Hover element | `mcp__chrome-devtools__hover({ uid: "<uid>" })` |
+   | Press key | `mcp__chrome-devtools__press_key({ key: "<key>" })` |
+   | Wait for element | `mcp__chrome-devtools__wait_for({ text: ["<text>"] })` |
+   | Run script | `mcp__chrome-devtools__evaluate_script({ function: "<js>" })` |
+
+2. After each step, take snapshot to track DOM changes if needed
+
+3. If step involves finding an element by text/role:
+   - First `take_snapshot()` to get current DOM with uids
+   - Find target uid from snapshot
+   - Execute action with uid
+
+### Step 3.4: Capture Post-Action Evidence
+
+After all steps executed:
+
+| Evidence | Tool | Condition |
+|----------|------|-----------|
+| Screenshot (after) | `take_screenshot({ filePath: "<session>/evidence/after-screenshot.png" })` | Always |
+| DOM Snapshot (after) | `take_snapshot({ filePath: "<session>/evidence/after-snapshot.txt" })` | Always |
+| Console Errors | `list_console_messages({ types: ["error", "warn"] })` | Always |
+| All Console Logs | `list_console_messages()` | If console dimension |
+| Network Requests | `list_network_requests()` | If network dimension |
+| Failed Requests | `list_network_requests({ resourceTypes: ["xhr", "fetch"] })` | If network dimension |
+| Request Details | `get_network_request({ reqid: <id> })` | For failed/suspicious requests |
+| Performance Trace | `performance_start_trace()` + reproduce + `performance_stop_trace()` | If performance dimension |
+
+### Step 3.5: Save Evidence Summary
+
+Write `<session>/evidence/evidence-summary.json`:
+```json
+{
+  "reproduction_success": true,
+  "target_url": "<url>",
+  "steps_executed": ["step1", "step2"],
+  "evidence_collected": {
+    "screenshots": ["before-screenshot.png", "after-screenshot.png"],
+    "snapshots": ["before-snapshot.txt", "after-snapshot.txt"],
+    "console_errors": [{ "type": "error", "text": "..." }],
+    "network_failures": [{ "url": "...", "status": 500, "method": "GET" }],
+    "performance_trace": "trace.json"
+  },
+  "observations": ["Error X appeared after step 3", "Network request Y failed"]
+}
+```
+
+## Phase 4: Report
+
+1. Write evidence summary to session evidence/
+2. Send state_update:
+   ```json
+   {
+     "status": "task_complete",
+     "task_id": "REPRODUCE-001",
+     "ref": "<session>/evidence/evidence-summary.json",
+     "key_findings": ["Bug reproduced successfully", "3 console errors captured", "1 failed API request"],
+     "decisions": [],
+     "verification": "self-validated"
+   }
+   ```
+3. Report: reproduction result, evidence inventory, key observations
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Page fails to load | Retry once, then report navigation error |
+| Element not found | Take snapshot, search alternative selectors, report if still not found |
+| Bug not reproduced | Report with evidence of non-reproduction, suggest step refinement |
+| Browser disconnected | Report error to coordinator |
+| Timeout during wait | Capture current state, report partial reproduction |