From 80d8954b7a3ab2cf28d7f8d2160cd82e20b2ac6b Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 7 Mar 2026 22:52:40 +0800 Subject: [PATCH] Add roles for fixer, reproducer, tester, verifier, and supervisor with detailed workflows - Introduced `fixer` role for implementing code fixes based on RCA reports, including phases for parsing RCA, planning fixes, implementing changes, and documenting results. - Added `reproducer` role for bug reproduction and evidence collection using Chrome DevTools, detailing steps for navigating to target URLs, executing reproduction steps, and capturing evidence. - Created `tester` role for feature-driven testing, outlining processes for parsing feature lists, executing test scenarios, and reporting discovered issues. - Established `verifier` role for fix verification, focusing on re-executing reproduction steps and comparing evidence before and after fixes. - Implemented `supervisor` role for overseeing pipeline phase transitions, ensuring consistency across artifacts and compliance with processes. - Added specifications for debug tools and pipeline definitions to standardize usage patterns and task management across roles. --- .claude/agents/team-supervisor.md | 293 +++++++++++++++++ .claude/commands/ddd/doc-generate.md | 295 ++++++++++++++++++ .claude/commands/ddd/doc-refresh.md | 218 +++++++++++++ .claude/commands/ddd/index-build.md | 90 ++---- .claude/commands/ddd/scan.md | 258 +-------------- .claude/commands/ddd/sync.md | 108 +------ .claude/commands/ddd/update.md | 18 +- .claude/skills/team-frontend-debug/SKILL.md | 170 ++++++++++ .../roles/analyzer/role.md | 207 ++++++++++++ .../roles/coordinator/commands/analyze.md | 174 +++++++++++ .../roles/coordinator/commands/dispatch.md | 256 +++++++++++++++ .../roles/coordinator/commands/monitor.md | 122 ++++++++ .../roles/coordinator/role.md | 128 ++++++++ .../team-frontend-debug/roles/fixer/role.md | 147 +++++++++ .../roles/reproducer/role.md | 147 +++++++++ .../team-frontend-debug/roles/tester/role.md | 231 ++++++++++++++ .../roles/verifier/role.md | 172 ++++++++++ .../team-frontend-debug/specs/debug-tools.md | 215 +++++++++++++ .../team-frontend-debug/specs/pipelines.md | 94 ++++++ .claude/skills/team-lifecycle-v4/SKILL.md | 67 +++- .../roles/coordinator/commands/dispatch.md | 10 + .../roles/coordinator/commands/monitor.md | 47 ++- .../roles/coordinator/role.md | 13 +- .../roles/supervisor/role.md | 192 ++++++++++++ .../specs/knowledge-transfer.md | 16 + .../team-lifecycle-v4/specs/pipelines.md | 26 +- .npmignore | 3 + 27 files changed, 3274 insertions(+), 443 deletions(-) create mode 100644 .claude/agents/team-supervisor.md create mode 100644 .claude/commands/ddd/doc-generate.md create mode 100644 .claude/commands/ddd/doc-refresh.md create mode 100644 .claude/skills/team-frontend-debug/SKILL.md create mode 100644 .claude/skills/team-frontend-debug/roles/analyzer/role.md create mode 100644 .claude/skills/team-frontend-debug/roles/coordinator/commands/analyze.md create mode 100644 .claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md create mode 100644 .claude/skills/team-frontend-debug/roles/coordinator/commands/monitor.md create mode 100644 .claude/skills/team-frontend-debug/roles/coordinator/role.md create mode 100644 .claude/skills/team-frontend-debug/roles/fixer/role.md create mode 100644 .claude/skills/team-frontend-debug/roles/reproducer/role.md create mode 100644 .claude/skills/team-frontend-debug/roles/tester/role.md create mode 100644 .claude/skills/team-frontend-debug/roles/verifier/role.md create mode 100644 .claude/skills/team-frontend-debug/specs/debug-tools.md create mode 100644 .claude/skills/team-frontend-debug/specs/pipelines.md create mode 100644 .claude/skills/team-lifecycle-v4/roles/supervisor/role.md diff --git a/.claude/agents/team-supervisor.md b/.claude/agents/team-supervisor.md new file mode 100644 index 00000000..aeec1fbc --- /dev/null +++ b/.claude/agents/team-supervisor.md @@ -0,0 +1,293 @@ +--- +name: team-supervisor +description: | + Message-driven resident agent for pipeline supervision. Spawned once per session, + stays alive across checkpoint tasks, woken by coordinator via SendMessage. + + Unlike team-worker (task-discovery lifecycle), team-supervisor uses a message-driven + lifecycle: Init → idle → wake → execute → idle → ... → shutdown. + + Reads message bus + artifacts (read-only), produces supervision reports. + + Examples: + - Context: Coordinator spawns supervisor at session start + user: "role: supervisor\nrole_spec: .../supervisor/role.md\nsession: .workflow/.team/TLV4-xxx" + assistant: "Loading role spec, initializing baseline context, reporting ready, going idle" + commentary: Agent initializes once, then waits for checkpoint assignments via SendMessage + + - Context: Coordinator wakes supervisor for checkpoint + user: (SendMessage) "## Checkpoint Request\ntask_id: CHECKPOINT-001\nscope: [DRAFT-001, DRAFT-002]" + assistant: "Claiming task, loading incremental context, executing checks, reporting verdict" + commentary: Agent wakes, executes one checkpoint, reports, goes idle again +color: cyan +--- + +You are a **resident pipeline supervisor**. You observe the pipeline's health across checkpoint boundaries, maintaining context continuity in-memory. + +**You are NOT a team-worker.** Your lifecycle is fundamentally different: +- team-worker: discover task → execute → report → STOP +- team-supervisor: init → idle → [wake → execute → idle]* → shutdown + +--- + +## Prompt Input Parsing + +Parse the following fields from your prompt: + +| Field | Required | Description | +|-------|----------|-------------| +| `role` | Yes | Always `supervisor` | +| `role_spec` | Yes | Path to supervisor role.md | +| `session` | Yes | Session folder path | +| `session_id` | Yes | Session ID for message bus operations | +| `team_name` | Yes | Team name for SendMessage | +| `requirement` | Yes | Original task/requirement description | +| `recovery` | No | `true` if respawned after crash — triggers recovery protocol | + +--- + +## Lifecycle + +``` +Entry: + Parse prompt → extract fields + Read role_spec → load checkpoint definitions (Phase 2-4 instructions) + + Init Phase: + Load baseline context (all role states, wisdom, session state) + context_accumulator = [] + SendMessage(coordinator, "ready") + → idle + + Wake Cycle (coordinator sends checkpoint request): + Parse message → task_id, scope + TaskUpdate(task_id, in_progress) + Incremental context load (only new data since last wake) + Execute checkpoint checks (from role_spec) + Write report artifact + TaskUpdate(task_id, completed) + team_msg state_update + Accumulate to context_accumulator + SendMessage(coordinator, checkpoint report) + → idle + + Shutdown (coordinator sends shutdown_request): + shutdown_response(approve: true) + → die +``` + +--- + +## Init Phase + +Run once at spawn. Build baseline understanding of the pipeline. + +### Step 1: Load Role Spec +``` +Read role_spec path → parse frontmatter + body +``` +Body contains checkpoint-specific check definitions (CHECKPOINT-001, 002, 003). + +### Step 2: Load Baseline Context +``` +team_msg(operation="get_state", session_id=) // all roles +``` +- Record which roles have completed, their key_findings, decisions +- Read `/wisdom/*.md` — absorb accumulated team knowledge +- Read `/team-session.json` — understand pipeline mode, stages + +### Step 3: Report Ready +```javascript +SendMessage({ + type: "message", + recipient: "coordinator", + content: "[supervisor] Resident supervisor ready. Baseline loaded for session . Awaiting checkpoint assignments.", + summary: "[supervisor] Ready, awaiting checkpoints" +}) +``` + +### Step 4: Go Idle +Turn ends. Agent sleeps until coordinator sends a message. + +--- + +## Wake Cycle + +Triggered when coordinator sends a message. Parse and execute. + +### Step 1: Parse Checkpoint Request + +Coordinator message format: +```markdown +## Checkpoint Request +task_id: CHECKPOINT-NNN +scope: [TASK-A, TASK-B, ...] +pipeline_progress: M/N tasks completed +``` + +Extract `task_id` and `scope` from the message content. + +### Step 2: Claim Task +```javascript +TaskUpdate({ taskId: "", status: "in_progress" }) +``` + +### Step 3: Incremental Context Load + +Only load data that's NEW since last wake (or since init if first wake): + +| Source | Method | What's New | +|--------|--------|------------| +| Role states | `team_msg(operation="get_state")` | Roles completed since last wake | +| Message bus | `team_msg(operation="list", session_id, last=30)` | Recent messages (errors, progress) | +| Artifacts | Read files in scope that aren't in context_accumulator yet | New upstream deliverables | +| Wisdom | Read `/wisdom/*.md` | New entries appended since last wake | + +**Efficiency rule**: Skip re-reading artifacts already in context_accumulator. Only read artifacts for tasks listed in `scope` that haven't been processed before. + +### Step 4: Execute Checks + +Follow the checkpoint-specific instructions in role_spec body (Phase 3 section). Each checkpoint type defines its own check matrix. + +### Step 5: Write Report + +Write to `/artifacts/CHECKPOINT-NNN-report.md` (format defined in role_spec Phase 4). + +### Step 6: Complete Task +```javascript +TaskUpdate({ taskId: "", status: "completed" }) +``` + +### Step 7: Publish State +```javascript +mcp__ccw-tools__team_msg({ + operation: "log", + session_id: "", + from: "supervisor", + type: "state_update", + data: { + status: "task_complete", + task_id: "", + ref: "/artifacts/CHECKPOINT-NNN-report.md", + key_findings: ["..."], + decisions: ["Proceed" or "Block: "], + verification: "self-validated", + supervision_verdict: "pass|warn|block", + supervision_score: 0.85 + } +}) +``` + +### Step 8: Accumulate Context +``` +context_accumulator.append({ + task: "", + artifact: "", + verdict: "", + score: <0.0-1.0>, + key_findings: [...], + artifacts_read: [], + quality_trend: "" +}) +``` + +### Step 9: Report to Coordinator +```javascript +SendMessage({ + type: "message", + recipient: "coordinator", + content: "[supervisor] CHECKPOINT-NNN complete.\nVerdict: (score: )\nFindings: \nRisks: logged\nQuality trend: \nArtifact: ", + summary: "[supervisor] CHECKPOINT-NNN: " +}) +``` + +### Step 10: Go Idle +Turn ends. Wait for next checkpoint request or shutdown. + +--- + +## Crash Recovery + +If spawned with `recovery: true` in prompt: + +1. Scan `/artifacts/CHECKPOINT-*-report.md` for existing reports +2. Read each report → rebuild context_accumulator entries +3. Check TaskList for any in_progress CHECKPOINT task (coordinator resets it to pending before respawn) +4. SendMessage to coordinator: "[supervisor] Recovered. Rebuilt context from N previous checkpoint reports." +5. Go idle — resume normal wake cycle + +--- + +## Shutdown Protocol + +When receiving a `shutdown_request` message: + +```javascript +SendMessage({ + type: "shutdown_response", + request_id: "", + approve: true +}) +``` + +Agent terminates. + +--- + +## Message Protocol Reference + +### Coordinator → Supervisor (wake) + +```markdown +## Checkpoint Request +task_id: CHECKPOINT-001 +scope: [DRAFT-001, DRAFT-002] +pipeline_progress: 3/10 tasks completed +``` + +### Supervisor → Coordinator (report) + +``` +[supervisor] CHECKPOINT-001 complete. +Verdict: pass (score: 0.90) +Findings: Terminology aligned, decision chain consistent, all artifacts present +Risks: 0 logged +Quality trend: stable +Artifact: /artifacts/CHECKPOINT-001-report.md +``` + +### Coordinator → Supervisor (shutdown) + +Standard `shutdown_request` via SendMessage tool. + +--- + +## Role Isolation Rules + +| Allowed | Prohibited | +|---------|-----------| +| Read ALL role states (cross-role visibility) | Modify any upstream artifacts | +| Read ALL message bus entries | Create or reassign tasks | +| Read ALL artifacts in session | SendMessage to other workers directly | +| Write CHECKPOINT report artifacts | Spawn agents | +| Append to wisdom files | Process non-CHECKPOINT work | +| SendMessage to coordinator only | Make implementation decisions | + +--- + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Artifact file not found | Score check as warn (not fail), log missing path | +| Message bus empty/unavailable | Score as warn, note "no messages to analyze" | +| Role state missing for upstream | Fall back to reading artifact files directly | +| Coordinator message unparseable | SendMessage error to coordinator, stay idle | +| Cumulative errors >= 3 across wakes | SendMessage alert to coordinator, stay idle (don't die) | +| No checkpoint request for extended time | Stay idle — resident agents don't self-terminate | + +--- + +## Output Tag + +All output lines must be prefixed with `[supervisor]` tag. diff --git a/.claude/commands/ddd/doc-generate.md b/.claude/commands/ddd/doc-generate.md new file mode 100644 index 00000000..01af3fd0 --- /dev/null +++ b/.claude/commands/ddd/doc-generate.md @@ -0,0 +1,295 @@ +--- +name: doc-generate +description: Generate full document tree from doc-index.json. Layer 3 (components) → Layer 2 (features) → Layer 1 (indexes/overview). Standalone or called by scan/index-build. +argument-hint: "[-y|--yes] [--layer <3|2|1|all>] [--force] [--skip-overview] [--skip-schema]" +allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*) +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-generate all layers without confirmation prompts. + +# DDD Doc Generate Command (/ddd:doc-generate) + +## Purpose + +Generate the complete document tree from `doc-index.json`. **Single source of truth** for all document generation logic, following bottom-up Layer 3 → 2 → 1 strategy. + +``` +doc-index.json → tech-registry/*.md (L3) → feature-maps/*.md (L2) → _index.md + README + ARCHITECTURE (L1) +``` + +## When to Use + +| Scenario | Use | +|----------|-----| +| After `/ddd:scan` builds doc-index.json | **doc-generate** (auto-called by scan) | +| After `/ddd:index-build` builds doc-index.json | **doc-generate** (auto-called by index-build) | +| Rebuild all docs from existing index | **doc-generate --force** | +| Regenerate only component docs | **doc-generate --layer 3** | +| Regenerate only overview/index docs | **doc-generate --layer 1** | + +## Prerequisite + +- `doc-index.json` must exist at `.workflow/.doc-index/doc-index.json` +- If not found → error: "No doc-index.json found. Run /ddd:scan or /ddd:index-build first." + +## Storage Output + +``` +.workflow/.doc-index/ +├── doc-index.json ← Input (read-only, not modified) +├── SCHEMA.md ← Schema documentation +├── README.md ← Project overview (Layer 1) +├── ARCHITECTURE.md ← Architecture overview (Layer 1) +├── feature-maps/ ← Feature documentation (Layer 2) +│ ├── _index.md +│ └── {feature-slug}.md +├── tech-registry/ ← Component documentation (Layer 3) +│ ├── _index.md +│ └── {component-slug}.md +└── sessions/ + └── _index.md ← Planning sessions index (Layer 1) +``` + +## Phase 1: Load & Validate + +### 1.1 Load doc-index.json + +``` +Read .workflow/.doc-index/doc-index.json +Validate: features[], technicalComponents[] are non-empty arrays +``` + +### 1.2 Schema Version Check + +```javascript +const schemaVersion = docIndex.schema_version || '0.0'; +if (schemaVersion !== '1.0') { + warn(`Schema version mismatch: found ${schemaVersion}, expected 1.0`); +} +``` + +### 1.3 Determine Generation Scope + +``` +IF --layer 3: generate Layer 3 only +IF --layer 2: generate Layer 2 only (requires Layer 3 exists) +IF --layer 1: generate Layer 1 only (requires Layer 2 exists) +IF --layer all (default): generate Layer 3 → 2 → 1 +``` + +### 1.4 Check Existing Docs + +``` +IF docs already exist AND NOT --force: + Warn: "Documents already exist. Use --force to overwrite." + Ask user (unless -y → overwrite) +``` + +## Phase 2: Layer 3 — Component Documentation + +For each component in `technicalComponents[]`: + +```bash +ccw cli -p "PURPOSE: Generate component documentation for {component.name} +TASK: +• Document component purpose and responsibility +• List exported symbols (classes, functions, types) +• Document dependencies (internal and external) +• Include code examples for key APIs +• Document integration points with other components +MODE: write +CONTEXT: @{component.codeLocations[].path} +EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples +CONSTRAINTS: Focus on public API | Include type signatures +" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/ +``` + +Output: `.workflow/.doc-index/tech-registry/{component-slug}.md` + +Frontmatter: +```markdown +--- +layer: 3 +component_id: tech-{slug} +name: ComponentName +type: service|controller|model|... +features: [feat-auth] +code_locations: + - path: src/services/auth.ts + symbols: [AuthService, AuthService.login] +generated_at: ISO8601 +--- +``` + +Sections: Responsibility, Code Locations, Related Requirements, Architecture Decisions, Dependencies (in/out) + +## Phase 3: Layer 2 — Feature Documentation + +For each feature in `features[]`: + +```bash +ccw cli -p "PURPOSE: Generate feature documentation for {feature.name} +TASK: +• Describe feature purpose and business value +• List requirements (from requirementIds) +• Document components involved (from techComponentIds) +• Include architecture decisions (from adrIds) +• Provide integration guide +MODE: write +CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md +EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration +CONSTRAINTS: Reference Layer 3 component docs | Business-focused language +" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/ +``` + +Output: `.workflow/.doc-index/feature-maps/{feature-slug}.md` + +Frontmatter: +```markdown +--- +layer: 2 +feature_id: feat-{slug} +name: Feature Name +epic_id: EPIC-NNN|null +status: implemented|in-progress|planned|partial +requirements: [REQ-001, REQ-002] +components: [tech-auth-service, tech-user-model] +depends_on_layer3: [tech-auth-service, tech-user-model] +tags: [auth, security] +generated_at: ISO8601 +--- +``` + +Sections: Overview, Requirements (with mapping status), Technical Components, Architecture Decisions, Change History + +## Phase 4: Layer 1 — Index & Overview Documentation + +### 4.1 Index Documents + +Generate catalog files: + +- **feature-maps/_index.md** — Feature overview table with status +- **tech-registry/_index.md** — Component registry table with types +- **action-logs/_index.md** — Action history table (empty initially for new projects) + +### 4.2 README.md (unless --skip-overview) + +```bash +ccw cli -p "PURPOSE: Generate project README with overview and navigation +TASK: +• Project summary and purpose +• Quick start guide +• Navigation to features, components, and architecture +• Link to doc-index.json +MODE: write +CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md +EXPECTED: README.md with: Overview, Quick Start, Navigation, Links +CONSTRAINTS: High-level only | Entry point for new developers +" --tool gemini --mode write --cd .workflow/.doc-index/ +``` + +### 4.3 ARCHITECTURE.md (unless --skip-overview) + +```bash +ccw cli -p "PURPOSE: Generate architecture overview document +TASK: +• System design overview +• Component relationships and dependencies +• Key architecture decisions (from ADRs) +• Technology stack +MODE: write +CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md +EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack +CONSTRAINTS: Architecture-focused | Reference component docs for details +" --tool gemini --mode write --cd .workflow/.doc-index/ +``` + +### 4.4 sessions/_index.md (unless --skip-overview) + +```bash +ccw cli -p "PURPOSE: Generate planning sessions index +TASK: +• List all planning session folders chronologically +• Link to each session's plan.json +• Show session status and task count +MODE: write +CONTEXT: @.workflow/.doc-index/planning/*/plan.json +EXPECTED: sessions/_index.md with: Session List, Links, Status +CONSTRAINTS: Chronological order | Link to session folders +" --tool gemini --mode write --cd .workflow/.doc-index/sessions/ +``` + +Layer 1 frontmatter: +```markdown +--- +layer: 1 +depends_on_layer2: [feat-auth, feat-orders] +generated_at: ISO8601 +--- +``` + +## Phase 5: SCHEMA.md (unless --skip-schema) + +### 5.1 Generate Schema Documentation + +```bash +ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning +TASK: +• Document current schema structure (all fields) +• Define versioning policy (semver: major.minor) +• Document migration protocol for version upgrades +• Provide examples for each schema section +MODE: write +CONTEXT: @.workflow/.doc-index/doc-index.json +EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples +CONSTRAINTS: Complete field documentation | Clear migration steps +" --tool gemini --mode write --cd .workflow/.doc-index/ +``` + +### 5.2 Versioning Policy + +**Semantic Versioning**: +- **Major** (X.0): Breaking changes (field removal, type changes, incompatible structure) +- **Minor** (X.Y): Non-breaking additions (new optional fields, new sections) + +**Migration Protocol**: +1. Detect version mismatch in ddd:plan/ddd:sync +2. Log warning with migration instructions +3. Provide migration script or regeneration option +4. Update schema_version after successful migration + +## Phase 6: Generation Report + +``` +Document Generation Report + +Project: {name} +Source: doc-index.json (build_path: {spec-first|code-first}) + +Generated: + Layer 3 (Components): {N} documents in tech-registry/ + Layer 2 (Features): {N} documents in feature-maps/ + Layer 1 (Indexes): {N} documents (_index.md, README, ARCHITECTURE) + Schema: SCHEMA.md + +Total: {N} documents generated +``` + +## Flags + +| Flag | Effect | +|------|--------| +| `-y, --yes` | Auto-confirm all decisions | +| `--layer <3\|2\|1\|all>` | Generate specific layer only (default: all) | +| `--force` | Overwrite existing documents | +| `--skip-overview` | Skip README.md, ARCHITECTURE.md, sessions/_index.md | +| `--skip-schema` | Skip SCHEMA.md generation | + +## Integration Points + +- **Input from**: `doc-index.json` (from `/ddd:scan` or `/ddd:index-build`) +- **Called by**: `/ddd:scan` (after index assembly), `/ddd:index-build` (after index assembly) +- **Standalone**: Can be run independently on any project with existing doc-index.json +- **Output**: Complete document tree in `.workflow/.doc-index/` diff --git a/.claude/commands/ddd/doc-refresh.md b/.claude/commands/ddd/doc-refresh.md new file mode 100644 index 00000000..b4e4ad8c --- /dev/null +++ b/.claude/commands/ddd/doc-refresh.md @@ -0,0 +1,218 @@ +--- +name: doc-refresh +description: Incrementally update affected documents based on changed components/features. Layer 3 → 2 → 1 selective refresh. Called by sync/update or used standalone. +argument-hint: "[-y|--yes] [--components ] [--features ] [--minimal] [--dry-run]" +allowed-tools: TodoWrite(*), Agent(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*) +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-update affected documents without confirmation prompts. + +# DDD Doc Refresh Command (/ddd:doc-refresh) + +## Purpose + +Incrementally update **only the affected documents** after code changes. Unlike `/ddd:doc-generate` (full generation), this command selectively refreshes documents for specific components and features. + +``` +affected component/feature IDs → update tech-registry (L3) → update feature-maps (L2) → update indexes (L1) +``` + +## When to Use + +| Scenario | Use | +|----------|-----| +| After `/ddd:sync` detects code changes | **doc-refresh** (auto-called by sync) | +| After `/ddd:update` traces impact | **doc-refresh** (auto-called by update) | +| Manual refresh of specific component docs | **doc-refresh --components tech-auth-service** | +| Quick metadata-only update | **doc-refresh --minimal --components tech-auth-service** | +| Preview what would change | **doc-refresh --dry-run --components tech-auth-service** | + +## Prerequisite + +- `doc-index.json` must exist at `.workflow/.doc-index/doc-index.json` +- At least one of `--components` or `--features` must be provided (or received from caller) +- Corresponding documents must already exist (generated by `/ddd:doc-generate`) +- If documents missing → error: "Documents not found. Run /ddd:doc-generate first." + +## Phase 1: Determine Refresh Scope + +### 1.1 Resolve Affected Entities + +``` +IF --components provided: + affected_components = parse comma-separated IDs + affected_features = lookup featureIds for each component in doc-index.json + +IF --features provided: + affected_features = parse comma-separated IDs + affected_components = union of all component IDs linked to features + +Merge both sets if both flags provided. +``` + +### 1.2 Validate Entities Exist + +For each ID, verify it exists in doc-index.json. Warn and skip missing IDs. + +### 1.3 Check Document Existence + +For each affected entity, check if corresponding .md file exists: +- Missing Layer 3 doc → warn: "Component doc not found. Run /ddd:doc-generate first." +- Missing Layer 2 doc → warn: "Feature doc not found. Run /ddd:doc-generate first." + +## Phase 2: Layer 3 — Update Component Docs + +For each affected component's `tech-registry/{slug}.md`: + +```bash +ccw cli -p "PURPOSE: Update component documentation for {component.name} after code changes +TASK: +• Update code locations and line ranges +• Update symbol list (add new exports, remove deleted) +• Add change entry to history table +• Refresh usage examples if API changed +MODE: write +CONTEXT: @{component.codeLocations[].path} +EXPECTED: Updated markdown with current API state +CONSTRAINTS: Preserve existing structure | Only update changed sections +" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/ +``` + +Update frontmatter: +```markdown +--- +layer: 3 +component_id: tech-auth-service +generated_at: {original} +last_updated: ISO8601 +--- +``` + +### 2.1 Minimal Mode (--minimal) + +With `--minimal`, only update: +- `codeLocations` in frontmatter +- `last_updated` timestamp +- Skip CLI call for content regeneration + +## Phase 3: Layer 2 — Update Feature Docs + +For each affected feature's `feature-maps/{slug}.md`: + +```bash +ccw cli -p "PURPOSE: Update feature documentation for {feature.name} after component changes +TASK: +• Update component list if new components added +• Update status if requirements now fully implemented +• Add change entry to history table +• Refresh integration guide if component APIs changed +MODE: write +CONTEXT: @.workflow/.doc-index/tech-registry/{affected-components}.md +EXPECTED: Updated markdown reflecting current feature state +CONSTRAINTS: Reference updated Layer 3 docs | Preserve business language +" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/ +``` + +Update frontmatter: +```markdown +--- +layer: 2 +feature_id: feat-auth +depends_on_layer3: [tech-auth-service, tech-user-model] +generated_at: {original} +last_updated: ISO8601 +--- +``` + +### 3.1 Minimal Mode (--minimal) + +With `--minimal`, only update: +- Component list in frontmatter +- Feature status (if requirements mapping changed) +- `last_updated` timestamp +- Skip CLI call for content regeneration + +## Phase 4: Layer 1 — Update Index Docs (conditional) + +### 4.1 Trigger Conditions + +| Condition | Action | +|-----------|--------| +| New component registered | Update `tech-registry/_index.md` | +| Component removed | Update `tech-registry/_index.md` | +| Feature status changed | Update `feature-maps/_index.md` | +| New feature added | Update `feature-maps/_index.md` + README.md | +| Major architecture change | Update ARCHITECTURE.md | +| New action-log entry | Update `action-logs/_index.md` | + +### 4.2 Update _index.md Files + +Refresh table entries for affected features/components: +- `feature-maps/_index.md` +- `tech-registry/_index.md` +- `action-logs/_index.md` (if new action entry) + +### 4.3 Update Overview Docs (only if significant) + +If new features added or major status changes: + +```bash +ccw cli -p "PURPOSE: Update project overview docs after feature changes +TASK: +• Update README.md feature list +• Update ARCHITECTURE.md if new components added +• Update sessions/_index.md with new planning sessions +MODE: write +CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json +EXPECTED: Updated overview docs with current project state +CONSTRAINTS: High-level only | Link to Layer 2 for details +" --tool gemini --mode write --cd .workflow/.doc-index/ +``` + +### 4.4 Skip Layer 1 + +With `--minimal` or when changes are minor (only code location updates): skip Layer 1 entirely. + +## Phase 5: Refresh Report + +``` +Document Refresh Report + +Affected Scope: + Components: {N} ({component IDs}) + Features: {N} ({feature IDs}) + +Updated: + Layer 3 (Components): {N} documents refreshed + Layer 2 (Features): {N} documents refreshed + Layer 1 (Indexes): {N} documents refreshed (or "skipped") + +Mode: {full|minimal} +``` + +## Dry-Run Mode + +With `--dry-run`: +- Execute Phase 1 (scope determination) +- Display what would be updated (affected files list) +- Skip all file writes (Phase 2-4) +- Output: "Dry-run complete. {N} documents would be refreshed." + +## Flags + +| Flag | Effect | +|------|--------| +| `-y, --yes` | Auto-confirm all updates | +| `--components ` | Comma-separated component IDs to refresh | +| `--features ` | Comma-separated feature IDs to refresh | +| `--minimal` | Only update metadata/frontmatter, skip content regeneration | +| `--dry-run` | Preview what would change without modifying files | + +## Integration Points + +- **Input from**: `doc-index.json`, affected entity IDs (from `/ddd:sync` or `/ddd:update`) +- **Called by**: `/ddd:sync` (after change detection + index update), `/ddd:update` (after impact tracing + index update) +- **Standalone**: Can be run independently to refresh specific component/feature docs +- **Prerequisite**: Documents must exist (generated by `/ddd:doc-generate`) diff --git a/.claude/commands/ddd/index-build.md b/.claude/commands/ddd/index-build.md index ad6aac5e..09d1cb38 100644 --- a/.claude/commands/ddd/index-build.md +++ b/.claude/commands/ddd/index-build.md @@ -118,73 +118,10 @@ Each EPIC-NNN → one feat-{slug} - tags: from domain keywords ``` -### 3.2 Generate Feature Map Documents +### 3.2 Document Generation (delegated) -For each feature → `feature-maps/{slug}.md`: - -```markdown ---- -id: feat-{slug} -name: Feature Name -epic_id: EPIC-NNN -status: implemented -requirements: [REQ-001, REQ-002] -components: [tech-auth-service, tech-user-model] -tags: [auth, security] -last_updated: ISO8601 ---- - -# Feature Name - -## Overview -{Description from epic} - -## Requirements -- **REQ-001**: {title} (Must) — {component mapping status} -- **REQ-002**: {title} (Should) — {component mapping status} - -## Technical Components -- **AuthService** (`src/services/auth.ts`): {role} - -## Architecture Decisions -- **ADR-001**: {title} - -## Change History -| Date | Task | Description | -|------|------|-------------| -| {date} | Initial | Indexed from spec SPEC-{session} | -``` - -### 3.3 Generate Tech Registry Documents - -For each component → `tech-registry/{slug}.md`: - -```markdown ---- -id: tech-{slug} -name: ComponentName -type: service -features: [feat-auth] -code_locations: - - path: src/services/auth.ts - symbols: [AuthService, AuthService.login] -last_updated: ISO8601 ---- - -# ComponentName - -## Responsibility -{From Gemini analysis} - -## Code Locations -- `src/services/auth.ts`: Main implementation - -## Related Requirements -- **REQ-001**: {title} - -## Architecture Decisions -- **ADR-001**: {title} -``` +Feature-map and tech-registry document generation is handled by `/ddd:doc-generate` in Phase 5. +Phase 3 only builds the data structures (feature → requirement → component mappings) that doc-generate consumes. ## Phase 4: Assemble doc-index.json @@ -223,14 +160,22 @@ If a code-first index exists (from prior `/ddd:scan`): - Update `build_path` to `"spec-first"` - Preserve existing `tech-*` components (update links only) -## Phase 5: Generate Index Documents & Validation +## Phase 5: Generate Documents -### 5.1 Index Documents -- `feature-maps/_index.md` — feature overview table -- `tech-registry/_index.md` — component registry table -- `action-logs/_index.md` — empty, populated by `/ddd:sync` +Delegate all document generation to `/ddd:doc-generate`: -### 5.2 Coverage Report +``` +Invoke /ddd:doc-generate [-y] +``` + +This generates the complete document tree (Layer 3 → 2 → 1): +- `tech-registry/{slug}.md` — component docs from Phase 2 mapping (Layer 3) +- `feature-maps/{slug}.md` — feature docs from Phase 3 mapping (Layer 2) +- `_index.md`, `README.md`, `ARCHITECTURE.md`, `SCHEMA.md` — index/overview docs (Layer 1) + +See `/ddd:doc-generate` for full details on generation strategy and flags. + +## Phase 6: Coverage Report ``` Index Build Report (spec-first) @@ -262,5 +207,6 @@ Gaps: ## Integration Points - **Input from**: `spec-generator` outputs, codebase, existing `/ddd:scan` index +- **Delegates to**: `/ddd:doc-generate` (Phase 5, full document generation) - **Output to**: `ddd:plan`, `ddd:sync`, `ddd:update` - **Upgrades**: Can merge with prior code-first (`/ddd:scan`) index diff --git a/.claude/commands/ddd/scan.md b/.claude/commands/ddd/scan.md index 69e5ae19..ac253b93 100644 --- a/.claude/commands/ddd/scan.md +++ b/.claude/commands/ddd/scan.md @@ -277,235 +277,8 @@ Write the index with code-first markers: } ``` -## Phase 7: Layer-Based Document Generation (TASK-004) -**Generation Strategy**: Layer 3 → Layer 2 → Layer 1 (bottom-up, following memory-manage pattern) - -### 7.1 Layer Definition - -| Layer | Content | Generation Order | Dependencies | -|-------|---------|------------------|--------------| -| **Layer 3** | Component docs (`tech-registry/{slug}.md`) | First | Source code only | -| **Layer 2** | Feature docs (`feature-maps/{slug}.md`) | Second | Layer 3 component docs | -| **Layer 1** | Index docs (`README.md`, `ARCHITECTURE.md`, `_index.md`) | Third | Layer 2 feature docs | - -### 7.2 Layer 3: Component Documentation - -For each component in `technicalComponents[]`: - -```bash -ccw cli -p "PURPOSE: Generate component documentation for {component.name} -TASK: -• Document component purpose and responsibility -• List exported symbols (classes, functions, types) -• Document dependencies (internal and external) -• Include code examples for key APIs -• Document integration points with other components -MODE: write -CONTEXT: @{component.codeLocations[].path} -EXPECTED: Markdown file with: Overview, API Reference, Dependencies, Usage Examples -CONSTRAINTS: Focus on public API | Include type signatures -" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/ -``` - -Output: `.workflow/.doc-index/tech-registry/{component-slug}.md` - -Add layer metadata to generated doc: -```markdown ---- -layer: 3 -component_id: tech-auth-service -generated_at: ISO8601 ---- -``` - -### 7.3 Layer 2: Feature Documentation - -For each feature in `features[]`: - -```bash -ccw cli -p "PURPOSE: Generate feature documentation for {feature.name} -TASK: -• Describe feature purpose and business value -• List requirements (from requirementIds) -• Document components involved (from techComponentIds) -• Include architecture decisions (from adrIds) -• Provide integration guide -MODE: write -CONTEXT: @.workflow/.doc-index/tech-registry/{related-components}.md -EXPECTED: Markdown file with: Overview, Requirements, Components, Architecture, Integration -CONSTRAINTS: Reference Layer 3 component docs | Business-focused language -" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/ -``` - -Output: `.workflow/.doc-index/feature-maps/{feature-slug}.md` - -Add layer metadata: -```markdown ---- -layer: 2 -feature_id: feat-auth -depends_on_layer3: [tech-auth-service, tech-user-model] -generated_at: ISO8601 ---- -``` - -### 7.4 Layer 1: Index Documentation - -Generate top-level overview documents: - -1. **README.md** - Project overview with navigation -2. **ARCHITECTURE.md** - System architecture overview -3. **feature-maps/_index.md** - Feature catalog -4. **tech-registry/_index.md** - Component catalog -5. **sessions/_index.md** - Planning sessions index - -```bash -ccw cli -p "PURPOSE: Generate project overview documentation -TASK: -• Create README.md with project summary and navigation -• Create ARCHITECTURE.md with system design overview -• Create _index.md files for feature-maps and tech-registry -• Include links to all Layer 2 feature docs -MODE: write -CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/tech-registry/*.md @.workflow/.doc-index/doc-index.json -EXPECTED: Overview documents with navigation links -CONSTRAINTS: High-level only | Link to Layer 2 docs for details -" --tool gemini --mode write --cd .workflow/.doc-index/ -``` - -Add layer metadata: -```markdown ---- -layer: 1 -depends_on_layer2: [feat-auth, feat-orders] -generated_at: ISO8601 ---- -``` - -## Phase 8: Project Overview Documentation (TASK-005) - -Generate standard overview documents as entry points for navigation. - -### 8.1 README.md Template - -```bash -ccw cli -p "PURPOSE: Generate project README with overview and navigation -TASK: -• Project summary and purpose -• Quick start guide -• Navigation to features, components, and architecture -• Link to doc-index.json -MODE: write -CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/feature-maps/_index.md -EXPECTED: README.md with: Overview, Quick Start, Navigation, Links -CONSTRAINTS: High-level only | Entry point for new developers -" --tool gemini --mode write --cd .workflow/.doc-index/ -``` - -Output: `.workflow/.doc-index/README.md` - -### 8.2 ARCHITECTURE.md Template - -```bash -ccw cli -p "PURPOSE: Generate architecture overview document -TASK: -• System design overview -• Component relationships and dependencies -• Key architecture decisions (from ADRs) -• Technology stack -MODE: write -CONTEXT: @.workflow/.doc-index/doc-index.json @.workflow/.doc-index/tech-registry/*.md -EXPECTED: ARCHITECTURE.md with: System Design, Component Diagram, ADRs, Tech Stack -CONSTRAINTS: Architecture-focused | Reference component docs for details -" --tool gemini --mode write --cd .workflow/.doc-index/ -``` - -Output: `.workflow/.doc-index/ARCHITECTURE.md` - -### 8.3 sessions/_index.md Template - -```bash -ccw cli -p "PURPOSE: Generate planning sessions index -TASK: -• List all planning session folders chronologically -• Link to each session's plan.json -• Show session status and task count -MODE: write -CONTEXT: @.workflow/.doc-index/planning/*/plan.json -EXPECTED: sessions/_index.md with: Session List, Links, Status -CONSTRAINTS: Chronological order | Link to session folders -" --tool gemini --mode write --cd .workflow/.doc-index/sessions/ -``` - -Output: `.workflow/.doc-index/sessions/_index.md` - -### 8.4 Update ddd:sync for Overview Docs - -Add to Phase 4 (Refresh Documents): -- If Layer 2 changed significantly → regenerate README.md and ARCHITECTURE.md -- If new planning session created → update sessions/_index.md - -## Phase 9: Schema Versioning (TASK-006) - -### 9.1 Add schema_version to doc-index.json - -Update Phase 6 doc-index.json generation to include: - -```json -{ - "schema_version": "1.0", - "version": "1.0", - "project": "{project-name}", - ... -} -``` - -### 9.2 Create SCHEMA.md - -```bash -ccw cli -p "PURPOSE: Document doc-index.json schema structure and versioning -TASK: -• Document current schema structure (all fields) -• Define versioning policy (semver: major.minor) -• Document migration protocol for version upgrades -• Provide examples for each schema section -MODE: write -CONTEXT: @.workflow/.doc-index/doc-index.json -EXPECTED: SCHEMA.md with: Schema Structure, Versioning Policy, Migration Protocol, Examples -CONSTRAINTS: Complete field documentation | Clear migration steps -" --tool gemini --mode write --cd .workflow/.doc-index/ -``` - -Output: `.workflow/.doc-index/SCHEMA.md` - -### 9.3 Version Check Logic - -Add to ddd:plan and ddd:sync Phase 1: - -```javascript -const docIndex = JSON.parse(Read('.workflow/.doc-index/doc-index.json')); -const schemaVersion = docIndex.schema_version || '0.0'; // Default for legacy - -if (schemaVersion !== '1.0') { - console.warn(`Schema version mismatch: found ${schemaVersion}, expected 1.0`); - console.warn('Consider running schema migration or regenerating doc-index'); -} -``` - -### 9.4 Versioning Policy - -**Semantic Versioning**: -- **Major** (X.0): Breaking changes (field removal, type changes, incompatible structure) -- **Minor** (X.Y): Non-breaking additions (new optional fields, new sections) - -**Migration Protocol**: -1. Detect version mismatch in ddd:plan/ddd:sync -2. Log warning with migration instructions -3. Provide migration script or regeneration option -4. Update schema_version after successful migration - -## Phase 6.5: Build DeepWiki Feature-to-Symbol Index +## Phase 7: Build DeepWiki Feature-to-Symbol Index If DeepWiki is available (`.codexlens/deepwiki_index.db` exists): @@ -527,28 +300,22 @@ If DeepWiki is available (`.codexlens/deepwiki_index.db` exists): **Graceful degradation**: If DeepWiki is unavailable, set `deepwiki_feature_to_symbol_index: {}` and log warning. -## Phase 7: Generate Documents +## Phase 8: Generate Documents -### 7.1 Feature Maps +Delegate all document generation to `/ddd:doc-generate`: -For each feature → `feature-maps/{slug}.md`: -- Frontmatter with id, name, status, inferred requirements, components, tags -- Sections: Overview, Inferred Requirements, Technical Components, Dependencies, Change History -- Mark inferred content: `> Inferred from code analysis` +``` +Invoke /ddd:doc-generate [-y] +``` -### 7.2 Tech Registry +This generates the complete document tree (Layer 3 → 2 → 1): +- `tech-registry/{slug}.md` — component docs (Layer 3) +- `feature-maps/{slug}.md` — feature docs (Layer 2) +- `_index.md`, `README.md`, `ARCHITECTURE.md`, `SCHEMA.md` — index/overview docs (Layer 1) -For each component → `tech-registry/{slug}.md`: -- Frontmatter with id, name, type, code_locations, depends_on -- Sections: Responsibility, Code Locations, Related Features, Dependencies (in/out) +See `/ddd:doc-generate` for full details on generation strategy and flags. -### 7.3 Index Documents - -- `feature-maps/_index.md` — feature table -- `tech-registry/_index.md` — component table -- `action-logs/_index.md` — recent git history table - -## Phase 8: Validation & Report +## Phase 9: Validation & Report ``` Scan Report @@ -593,5 +360,6 @@ When a scanned project later runs `spec-generator` + `/ddd:index-build`: ## Integration Points - **Input from**: Codebase, git history, `project-tech.json` +- **Delegates to**: `/ddd:doc-generate` (Phase 8, full document generation) - **Output to**: `ddd:plan`, `ddd:sync`, `ddd:update`, `ddd:index-build` (upgrade) - **Standalone**: Can be used independently on any project diff --git a/.claude/commands/ddd/sync.md b/.claude/commands/ddd/sync.md index 2d748fa2..9b49b28a 100644 --- a/.claude/commands/ddd/sync.md +++ b/.claude/commands/ddd/sync.md @@ -247,103 +247,19 @@ For each affected feature: Set `doc-index.json.last_updated` to current time. -## Phase 4: Refresh Documents (Layer-Based Regeneration, TASK-004) +## Phase 4: Refresh Documents & Action Log -**Strategy**: Regenerate affected documents following Layer 3 → Layer 2 → Layer 1 order. +### 4.1 Delegate Document Refresh to /ddd:doc-refresh -### 4.1 Identify Affected Layers +From Phase 2 impact tracing, collect affected component and feature IDs, then delegate: -From Phase 2 impact tracing: -- **Layer 3 affected**: Components with modified codeLocations -- **Layer 2 affected**: Features linked to affected components -- **Layer 1 affected**: Index docs if Layer 2 changed - -### 4.2 Layer 3: Update Component Docs - -For each affected component's `tech-registry/{slug}.md`: - -```bash -ccw cli -p "PURPOSE: Update component documentation for {component.name} after code changes -TASK: -• Update code locations and line ranges -• Update symbol list (add new exports, remove deleted) -• Add change entry to history table -• Refresh usage examples if API changed -MODE: write -CONTEXT: @{component.codeLocations[].path} -EXPECTED: Updated markdown with current API state -CONSTRAINTS: Preserve existing structure | Only update changed sections -" --tool gemini --mode write --cd .workflow/.doc-index/tech-registry/ +``` +Invoke /ddd:doc-refresh [-y] --components {affected_component_ids} --features {affected_feature_ids} ``` -Update layer metadata: -```markdown ---- -layer: 3 -component_id: tech-auth-service -generated_at: ISO8601 -last_updated: ISO8601 ---- -``` +This handles Layer 3 → 2 → 1 selective document refresh. See `/ddd:doc-refresh` for full details. -### 4.3 Layer 2: Update Feature Docs - -For each affected feature's `feature-maps/{slug}.md`: - -```bash -ccw cli -p "PURPOSE: Update feature documentation for {feature.name} after component changes -TASK: -• Update component list if new components added -• Update status if requirements now fully implemented -• Add change entry to history table -• Refresh integration guide if component APIs changed -MODE: write -CONTEXT: @.workflow/.doc-index/tech-registry/{affected-components}.md -EXPECTED: Updated markdown reflecting current feature state -CONSTRAINTS: Reference updated Layer 3 docs | Preserve business language -" --tool gemini --mode write --cd .workflow/.doc-index/feature-maps/ -``` - -Update layer metadata: -```markdown ---- -layer: 2 -feature_id: feat-auth -depends_on_layer3: [tech-auth-service, tech-user-model] -generated_at: ISO8601 -last_updated: ISO8601 ---- -``` - -### 4.4 Layer 1: Update Index Docs (if needed) - -If Layer 2 changed significantly (new features, status changes): - -```bash -ccw cli -p "PURPOSE: Update project overview docs after feature changes -TASK: -• Update README.md feature list -• Update ARCHITECTURE.md if new components added -• Update sessions/_index.md with new planning sessions -• Update other _index.md files with new entries -MODE: write -CONTEXT: @.workflow/.doc-index/feature-maps/*.md @.workflow/.doc-index/doc-index.json -EXPECTED: Updated overview docs with current project state -CONSTRAINTS: High-level only | Link to Layer 2 for details -" --tool gemini --mode write --cd .workflow/.doc-index/ -``` - -Update layer metadata: -```markdown ---- -layer: 1 -depends_on_layer2: [feat-auth, feat-orders] -generated_at: ISO8601 -last_updated: ISO8601 ---- -``` - -### 4.5 Update Action Log +### 4.2 Generate Action Log Entry Create `.workflow/.doc-index/action-logs/{task-id}.md`: @@ -374,19 +290,10 @@ timestamp: ISO8601 |------|------|-------|--------| | {symbol/file/component} | {type} | {score} | {fresh/warning/stale} | -- Stale counts: {N} symbols, {N} files, {N} components -- Auto-regeneration candidates: {list of items with auto_regenerate and score >= stale} - ## Notes {any user-provided notes} ``` -### 4.4 Update Index Documents - -- Refresh `feature-maps/_index.md` table -- Refresh `tech-registry/_index.md` table -- Append to `action-logs/_index.md` table - ## Phase 5: Confirmation (unless -y) Present update summary to user: @@ -408,6 +315,7 @@ Present update summary to user: ## Integration Points - **Input from**: `execution-manifest.json` (preferred, from ddd:execute) OR Git history (fallback), `doc-index.json`, `/ddd:plan` output +- **Delegates to**: `/ddd:doc-refresh` (Phase 4.1, selective document refresh) - **Output to**: Updated `doc-index.json`, feature-maps/, tech-registry/, action-logs/ - **Triggers**: After completing any development task - **Data source priority**: `--from-manifest` > `--commit` > `--task-id` > git diff HEAD~1 diff --git a/.claude/commands/ddd/update.md b/.claude/commands/ddd/update.md index 40d6de7f..05caa18e 100644 --- a/.claude/commands/ddd/update.md +++ b/.claude/commands/ddd/update.md @@ -120,16 +120,21 @@ For orphan files in src/: ## Phase 4: Refresh Documents (if updates were made) -### 4.1 Minimal Doc Updates +### 4.1 Delegate to /ddd:doc-refresh -Only update documents that need changes: -- `tech-registry/{slug}.md` — if code locations changed -- `feature-maps/{slug}.md` — only if component list changed -- `_index.md` files — only if entries were added/removed +From Phase 2 impact tracing, collect affected component and feature IDs, then delegate: + +``` +Invoke /ddd:doc-refresh [-y] --minimal --components {affected_component_ids} --features {affected_feature_ids} +``` + +The `--minimal` flag ensures only metadata/frontmatter is updated (code locations, timestamps), skipping full content regeneration. This keeps the update lightweight. + +See `/ddd:doc-refresh` for full details. ### 4.2 Skip If --check-only -With `--check-only`, only output the impact report without modifying any files. +With `--check-only`, skip Phase 3 and Phase 4 entirely — only output the impact report. ## Flags @@ -149,6 +154,7 @@ With `--check-only`, only output the impact report without modifying any files. ## Integration Points - **Input from**: Git working tree, `doc-index.json` +- **Delegates to**: `/ddd:doc-refresh` (Phase 4.1, incremental document refresh with --minimal) - **Output to**: Updated `doc-index.json`, impact report - **Triggers**: During development, pre-commit, or periodic refresh - **Can chain to**: `/ddd:sync` for full post-task synchronization diff --git a/.claude/skills/team-frontend-debug/SKILL.md b/.claude/skills/team-frontend-debug/SKILL.md new file mode 100644 index 00000000..c8d977cc --- /dev/null +++ b/.claude/skills/team-frontend-debug/SKILL.md @@ -0,0 +1,170 @@ +--- +name: team-frontend-debug +description: Frontend debugging team using Chrome DevTools MCP. Dual-mode — feature-list testing or bug-report debugging. Triggers on "team-frontend-debug", "frontend debug". +allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__chrome-devtools__*(*) +--- + +# Frontend Debug Team + +Dual-mode frontend debugging: feature-list testing or bug-report debugging, powered by Chrome DevTools MCP. + +## Architecture + +``` +Skill(skill="team-frontend-debug", args="feature list or bug description") + | + SKILL.md (this file) = Router + | + +--------------+--------------+ + | | + no --role flag --role + | | + Coordinator Worker + roles/coordinator/role.md roles//role.md + | + +-- analyze input → select pipeline → dispatch → spawn → STOP + | + ┌──────────────────────────┼──────────────────────┐ + v v v + [test-pipeline] [debug-pipeline] [shared] + tester(DevTools) reproducer(DevTools) analyzer + fixer + verifier +``` + +## Pipeline Modes + +| Input | Pipeline | Flow | +|-------|----------|------| +| Feature list / 功能清单 | `test-pipeline` | TEST → ANALYZE → FIX → VERIFY | +| Bug report / 错误描述 | `debug-pipeline` | REPRODUCE → ANALYZE → FIX → VERIFY | + +## Role Registry + +| Role | Path | Prefix | Inner Loop | +|------|------|--------|------------| +| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — | +| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | true | +| reproducer | [roles/reproducer/role.md](roles/reproducer/role.md) | REPRODUCE-* | false | +| analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false | +| fixer | [roles/fixer/role.md](roles/fixer/role.md) | FIX-* | true | +| verifier | [roles/verifier/role.md](roles/verifier/role.md) | VERIFY-* | false | + +## Role Router + +Parse `$ARGUMENTS`: +- Has `--role ` → Read `roles//role.md`, execute Phase 2-4 +- No `--role` → Read `roles/coordinator/role.md`, execute entry router + +## Shared Constants + +- **Session prefix**: `TFD` +- **Session path**: `.workflow/.team/TFD--/` +- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications) +- **Message bus**: `mcp__ccw-tools__team_msg(session_id=, ...)` + +## Chrome DevTools MCP Tools + +All browser inspection operations use Chrome DevTools MCP. Reproducer and Verifier are primary consumers. + +| Tool | Purpose | +|------|---------| +| `mcp__chrome-devtools__navigate_page` | Navigate to target URL | +| `mcp__chrome-devtools__take_screenshot` | Capture visual state | +| `mcp__chrome-devtools__take_snapshot` | Capture DOM/a11y tree | +| `mcp__chrome-devtools__list_console_messages` | Read console logs | +| `mcp__chrome-devtools__get_console_message` | Get specific console message | +| `mcp__chrome-devtools__list_network_requests` | Monitor network activity | +| `mcp__chrome-devtools__get_network_request` | Inspect request/response detail | +| `mcp__chrome-devtools__performance_start_trace` | Start performance recording | +| `mcp__chrome-devtools__performance_stop_trace` | Stop and analyze trace | +| `mcp__chrome-devtools__click` | Simulate user click | +| `mcp__chrome-devtools__fill` | Fill form inputs | +| `mcp__chrome-devtools__hover` | Hover over elements | +| `mcp__chrome-devtools__evaluate_script` | Execute JavaScript in page | +| `mcp__chrome-devtools__wait_for` | Wait for element/text | +| `mcp__chrome-devtools__list_pages` | List open browser tabs | +| `mcp__chrome-devtools__select_page` | Switch active tab | + +## Worker Spawn Template + +Coordinator spawns workers using this template: + +``` +Agent({ + subagent_type: "team-worker", + description: "Spawn worker", + team_name: , + name: "", + run_in_background: true, + prompt: `## Role Assignment +role: +role_spec: .claude/skills/team-frontend-debug/roles//role.md +session: +session_id: +team_name: +requirement: +inner_loop: + +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).` +}) +``` + +## User Commands + +| Command | Action | +|---------|--------| +| `check` / `status` | View execution status graph | +| `resume` / `continue` | Advance to next step | +| `revise [feedback]` | Revise specific task | +| `feedback ` | Inject feedback for revision | +| `retry ` | Re-run a failed task | + +## Completion Action + +When pipeline completes, coordinator presents: + +``` +AskUserQuestion({ + questions: [{ + question: "Pipeline complete. What would you like to do?", + header: "Completion", + multiSelect: false, + options: [ + { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" }, + { label: "Keep Active", description: "Keep session for follow-up debugging" }, + { label: "Export Results", description: "Export debug report and patches" } + ] + }] +}) +``` + +## Specs Reference + +- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry +- [specs/debug-tools.md](specs/debug-tools.md) — Chrome DevTools MCP usage patterns and evidence collection + +## Session Directory + +``` +.workflow/.team/TFD--/ +├── team-session.json # Session state + role registry +├── evidence/ # Screenshots, snapshots, network logs +├── artifacts/ # Test reports, RCA reports, patches, verification reports +├── wisdom/ # Cross-task debug knowledge +└── .msg/ # Team message bus +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| All features pass test | Report success, pipeline completes without ANALYZE/FIX/VERIFY | +| Bug not reproducible | Reproducer reports failure, coordinator asks user for more details | +| Browser not available | Report error, suggest manual reproduction steps | +| Analysis inconclusive | Analyzer requests more evidence via iteration loop | +| Fix introduces regression | Verifier reports fail, coordinator dispatches re-fix | +| No issues found in test | Skip downstream tasks, report all-pass | +| Unknown command | Error with available command list | +| Role not found | Error with role registry | diff --git a/.claude/skills/team-frontend-debug/roles/analyzer/role.md b/.claude/skills/team-frontend-debug/roles/analyzer/role.md new file mode 100644 index 00000000..b8eeaf12 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/analyzer/role.md @@ -0,0 +1,207 @@ +--- +role: analyzer +prefix: ANALYZE +inner_loop: false +message_types: + success: rca_ready + iteration: need_more_evidence + error: error +--- + +# Analyzer + +Root cause analysis from debug evidence. + +## Identity +- Tag: [analyzer] | Prefix: ANALYZE-* +- Responsibility: Analyze evidence artifacts, identify root cause, produce RCA report + +## Boundaries +### MUST +- Load ALL evidence from reproducer before analysis +- Correlate findings across multiple evidence types +- Identify specific file:line location when possible +- Request supplemental evidence if analysis is inconclusive +- Produce structured RCA report +### MUST NOT +- Modify source code or project files +- Skip loading upstream evidence +- Guess root cause without evidence support +- Proceed with low-confidence RCA (request more evidence instead) + +## Phase 2: Load Evidence + +1. Read upstream artifacts via team_msg(operation="get_state", role="reproducer") +2. Extract evidence paths from reproducer's state_update ref +3. Load evidence-summary.json from session evidence/ +4. Load all evidence files: + - Read screenshot files (visual inspection) + - Read DOM snapshots (structural analysis) + - Parse console error messages + - Parse network request logs + - Read performance trace if available +5. Load wisdom/ for any prior debug knowledge + +## Phase 3: Root Cause Analysis + +### Step 3.1: Console Error Analysis + +Priority analysis — most bugs have console evidence: + +1. Filter console messages by type: error > warn > log +2. For each error: + - Extract error message and stack trace + - Identify source file and line number from stack + - Classify: TypeError, ReferenceError, SyntaxError, NetworkError, CustomError +3. Map errors to reproduction steps (correlation by timing) + +### Step 3.2: Network Analysis + +If network evidence collected: + +1. Identify failed requests (4xx, 5xx, timeout, CORS) +2. For each failed request: + - Request URL, method, headers + - Response status, body (if captured) + - Timing information +3. Check for: + - Missing authentication tokens + - Incorrect API endpoints + - CORS policy violations + - Request/response payload issues + +### Step 3.3: DOM Structure Analysis + +If snapshots collected: + +1. Compare before/after snapshots +2. Identify: + - Missing or extra elements + - Incorrect attributes or content + - Accessibility tree anomalies + - State-dependent rendering issues + +### Step 3.4: Performance Analysis + +If performance trace collected: + +1. Identify long tasks (>50ms) +2. Check for: + - JavaScript execution bottlenecks + - Layout thrashing + - Excessive re-renders + - Memory leaks (growing heap) + - Large resource loads + +### Step 3.5: Cross-Correlation + +Combine findings from all dimensions: + +1. Build timeline of events leading to bug +2. Identify the earliest trigger point +3. Trace from trigger to visible symptom +4. Determine if issue is: + - Frontend code bug (logic error, missing null check, etc.) + - Backend/API issue (wrong data, missing endpoint) + - Configuration issue (env vars, build config) + - Race condition / timing issue + +### Step 3.6: Source Code Mapping + +Use codebase search to locate root cause: + +``` +mcp__ace-tool__search_context({ + project_root_path: "", + query: "" +}) +``` + +Read identified source files to confirm root cause location. + +### Step 3.7: Confidence Assessment + +| Confidence | Criteria | Action | +|------------|----------|--------| +| High (>80%) | Stack trace points to specific line + error is clear | Proceed with RCA | +| Medium (50-80%) | Likely cause identified but needs confirmation | Proceed with caveats | +| Low (<50%) | Multiple possible causes, insufficient evidence | Request more evidence | + +If Low confidence: send `need_more_evidence` message with specific requests. + +## Phase 4: RCA Report + +Write `/artifacts/ANALYZE-001-rca.md`: + +```markdown +# Root Cause Analysis Report + +## Bug Summary +- **Description**: +- **URL**: +- **Reproduction**: + +## Root Cause +- **Category**: +- **Confidence**: +- **Source File**: +- **Source Line**: +- **Root Cause**: + +## Evidence Chain +1. finding> +2. finding> +3. root cause> + +## Fix Recommendation +- **Approach**: +- **Files to modify**: +- **Risk level**: +- **Estimated scope**: + +## Additional Observations +- +- +``` + +Send state_update: +```json +{ + "status": "task_complete", + "task_id": "ANALYZE-001", + "ref": "/artifacts/ANALYZE-001-rca.md", + "key_findings": ["Root cause: ", "Location: "], + "decisions": ["Recommended fix: "], + "verification": "self-validated" +} +``` + +## Iteration Protocol + +When evidence is insufficient (confidence < 50%): + +1. Send state_update with `need_more_evidence: true`: + ```json + { + "status": "need_more_evidence", + "task_id": "ANALYZE-001", + "ref": null, + "key_findings": ["Partial analysis: "], + "decisions": [], + "evidence_request": { + "dimensions": ["network_detail", "state_inspection"], + "specific_actions": ["Capture request body for /api/users", "Evaluate React state after click"] + } + } + ``` +2. Coordinator creates REPRODUCE-002 + ANALYZE-002 +3. ANALYZE-002 loads both original and supplemental evidence + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Evidence files missing | Report with available data, note gaps | +| No clear root cause | Request supplemental evidence via iteration | +| Multiple possible causes | Rank by likelihood, report top 3 | +| Source code not found | Report with best available location info | diff --git a/.claude/skills/team-frontend-debug/roles/coordinator/commands/analyze.md b/.claude/skills/team-frontend-debug/roles/coordinator/commands/analyze.md new file mode 100644 index 00000000..2cd98c63 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/coordinator/commands/analyze.md @@ -0,0 +1,174 @@ +# Analyze Input + +Parse user input -> detect mode (feature-test vs bug-report) -> build dependency graph -> assign roles. + +**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration. + +## Step 1: Detect Input Mode + +``` +if input contains: 功能, feature, 清单, list, 测试, test, 完成, done, 验收 + → mode = "test-pipeline" +elif input contains: bug, 错误, 报错, crash, 问题, 不工作, 白屏, 异常 + → mode = "debug-pipeline" +else + → AskUserQuestion to clarify +``` + +``` +AskUserQuestion({ + questions: [{ + question: "请确认调试模式", + header: "Mode", + multiSelect: false, + options: [ + { label: "功能测试", description: "根据功能清单逐项测试，发现并修复问题" }, + { label: "Bug修复", description: "针对已知Bug进行复现、分析和修复" } + ] + }] +}) +``` + +--- + +## Mode A: Feature Test (test-pipeline) + +### Parse Feature List + +Extract from user input: + +| Field | Source | Required | +|-------|--------|----------| +| base_url | URL in text or AskUserQuestion | Yes | +| features | Feature list (bullet points, numbered list, or free text) | Yes | +| test_depth | User preference or default "standard" | Auto | + +Parse features into structured format: +```json +[ + { "id": "F-001", "name": "用户登录", "url": "/login", "description": "..." }, + { "id": "F-002", "name": "数据列表", "url": "/dashboard", "description": "..." } +] +``` + +If base_url missing: +``` +AskUserQuestion({ + questions: [{ + question: "请提供应用的访问地址", + header: "Base URL", + multiSelect: false, + options: [ + { label: "localhost:3000", description: "本地开发服务器" }, + { label: "localhost:5173", description: "Vite默认端口" }, + { label: "Custom", description: "自定义URL" } + ] + }] +}) +``` + +### Complexity Scoring (Test Mode) + +| Factor | Points | +|--------|--------| +| Per feature | +1 | +| Features > 5 | +2 | +| Features > 10 | +3 | +| Cross-page workflows | +1 | + +Results: 1-3 Low, 4-6 Medium, 7+ High + +### Output (Test Mode) + +```json +{ + "mode": "test-pipeline", + "base_url": "", + "features": [ + { "id": "F-001", "name": "", "url": "", "description": "" } + ], + "pipeline_type": "test-pipeline", + "dependency_graph": { + "TEST-001": { "role": "tester", "blockedBy": [], "priority": "P0" }, + "ANALYZE-001": { "role": "analyzer", "blockedBy": ["TEST-001"], "priority": "P0", "conditional": true }, + "FIX-001": { "role": "fixer", "blockedBy": ["ANALYZE-001"], "priority": "P0", "conditional": true }, + "VERIFY-001": { "role": "verifier", "blockedBy": ["FIX-001"], "priority": "P0", "conditional": true } + }, + "roles": [ + { "name": "tester", "prefix": "TEST", "inner_loop": true }, + { "name": "analyzer", "prefix": "ANALYZE", "inner_loop": false }, + { "name": "fixer", "prefix": "FIX", "inner_loop": true }, + { "name": "verifier", "prefix": "VERIFY", "inner_loop": false } + ], + "complexity": { "score": 0, "level": "Low|Medium|High" } +} +``` + +--- + +## Mode B: Bug Report (debug-pipeline) + +### Parse Bug Report + +Extract from user input: + +| Field | Source | Required | +|-------|--------|----------| +| bug_description | User text | Yes | +| target_url | URL in text or AskUserQuestion | Yes | +| reproduction_steps | Steps in text or AskUserQuestion | Yes | +| expected_behavior | User description | Recommended | +| actual_behavior | User description | Recommended | +| severity | User indication or auto-assess | Auto | + +### Debug Dimension Detection + +| Keywords | Dimension | Evidence Needed | +|----------|-----------|-----------------| +| 渲染, 样式, 显示, 布局, CSS | UI/Rendering | screenshot, snapshot | +| 请求, API, 接口, 网络, 超时 | Network | network_requests | +| 错误, 报错, 异常, crash | JavaScript Error | console_messages | +| 慢, 卡顿, 性能, 加载 | Performance | performance_trace | +| 状态, 数据, 更新, 不同步 | State Management | console + snapshot | +| 交互, 点击, 输入, 表单 | User Interaction | click/fill + screenshot | + +### Complexity Scoring (Debug Mode) + +| Factor | Points | +|--------|--------| +| Single dimension (e.g., JS error only) | 1 | +| Multi-dimension (UI + Network) | +1 per extra | +| Intermittent / hard to reproduce | +2 | +| Performance profiling needed | +1 | + +Results: 1-2 Low, 3-4 Medium, 5+ High + +### Output (Debug Mode) + +```json +{ + "mode": "debug-pipeline", + "bug_description": "", + "target_url": "", + "reproduction_steps": ["step 1", "step 2"], + "dimensions": ["ui_rendering", "javascript_error"], + "evidence_plan": { + "screenshot": true, "snapshot": true, + "console": true, "network": true, "performance": false + }, + "pipeline_type": "debug-pipeline", + "dependency_graph": { + "REPRODUCE-001": { "role": "reproducer", "blockedBy": [], "priority": "P0" }, + "ANALYZE-001": { "role": "analyzer", "blockedBy": ["REPRODUCE-001"], "priority": "P0" }, + "FIX-001": { "role": "fixer", "blockedBy": ["ANALYZE-001"], "priority": "P0" }, + "VERIFY-001": { "role": "verifier", "blockedBy": ["FIX-001"], "priority": "P0" } + }, + "roles": [ + { "name": "reproducer", "prefix": "REPRODUCE", "inner_loop": false }, + { "name": "analyzer", "prefix": "ANALYZE", "inner_loop": false }, + { "name": "fixer", "prefix": "FIX", "inner_loop": true }, + { "name": "verifier", "prefix": "VERIFY", "inner_loop": false } + ], + "complexity": { "score": 0, "level": "Low|Medium|High" } +} +``` diff --git a/.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md b/.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md new file mode 100644 index 00000000..55b6f2d5 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md @@ -0,0 +1,256 @@ +# Dispatch Debug Tasks + +Create task chains from dependency graph with proper blockedBy relationships. + +## Workflow + +1. Read task-analysis.json -> extract pipeline_type and dependency_graph +2. Read specs/pipelines.md -> get task registry for selected pipeline +3. Topological sort tasks (respect blockedBy) +4. Validate all owners exist in role registry (SKILL.md) +5. For each task (in order): + - TaskCreate with structured description (see template below) + - TaskUpdate with blockedBy + owner assignment +6. Update team-session.json with pipeline.tasks_total +7. Validate chain (no orphans, no cycles, all refs valid) + +## Task Description Template + +``` +PURPOSE: | Success: +TASK: + - + - +CONTEXT: + - Session: + - Base URL / Bug URL: + - Upstream artifacts: +EXPECTED: + +CONSTRAINTS: +--- +InnerLoop: +RoleSpec: .claude/skills/team-frontend-debug/roles//role.md +``` + +--- + +## Test Pipeline Tasks (mode: test-pipeline) + +### TEST-001: Feature Testing + +``` +PURPOSE: Test all features from feature list and discover issues | Success: All features tested with pass/fail results +TASK: + - Parse feature list from task description + - For each feature: navigate to URL, explore page, generate test scenarios + - Execute test scenarios using Chrome DevTools MCP (click, fill, hover, etc.) + - Capture evidence: screenshots, console logs, network requests + - Classify results: pass / fail / warning + - Compile test report with discovered issues +CONTEXT: + - Session: + - Base URL: + - Features: +EXPECTED: /artifacts/TEST-001-report.md + /artifacts/TEST-001-issues.json +CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code | Test all listed features +--- +InnerLoop: true +RoleSpec: .claude/skills/team-frontend-debug/roles/tester/role.md +``` + +### ANALYZE-001 (Test Mode): Analyze Discovered Issues + +``` +PURPOSE: Analyze issues discovered by tester to identify root causes | Success: RCA for each discovered issue +TASK: + - Load test report and issues list from TEST-001 + - For each high/medium severity issue: analyze evidence, identify root cause + - Correlate console errors, network failures, DOM anomalies to source code + - Produce consolidated RCA report covering all issues +CONTEXT: + - Session: + - Upstream: /artifacts/TEST-001-issues.json + - Test evidence: /evidence/ +EXPECTED: /artifacts/ANALYZE-001-rca.md with root causes for all issues +CONSTRAINTS: Read-only analysis | Skip low-severity warnings unless user requests +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md +``` + +**Conditional**: If TEST-001 reports zero issues → skip ANALYZE-001, FIX-001, VERIFY-001. Pipeline completes. + +### FIX-001 (Test Mode): Fix All Issues + +``` +PURPOSE: Fix all identified issues from RCA | Success: All high/medium issues resolved +TASK: + - Load consolidated RCA report from ANALYZE-001 + - For each root cause: locate code, implement fix + - Run syntax/type check after all modifications + - Document all changes +CONTEXT: + - Session: + - Upstream: /artifacts/ANALYZE-001-rca.md +EXPECTED: Modified source files + /artifacts/FIX-001-changes.md +CONSTRAINTS: Minimal changes per issue | Follow existing code style +--- +InnerLoop: true +RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md +``` + +### VERIFY-001 (Test Mode): Re-Test After Fix + +``` +PURPOSE: Re-run failed test scenarios to verify fixes | Success: Previously failed scenarios now pass +TASK: + - Load original test report (failed scenarios only) + - Re-execute failed scenarios using Chrome DevTools MCP + - Capture evidence and compare with original + - Report pass/fail per scenario +CONTEXT: + - Session: + - Original test report: /artifacts/TEST-001-report.md + - Fix changes: /artifacts/FIX-001-changes.md + - Failed features: +EXPECTED: /artifacts/VERIFY-001-report.md with pass/fail per previously-failed scenario +CONSTRAINTS: Only re-test failed scenarios | Use Chrome DevTools MCP only +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md +``` + +--- + +## Debug Pipeline Tasks (mode: debug-pipeline) + +### REPRODUCE-001: Evidence Collection + +``` +PURPOSE: Reproduce reported bug and collect debug evidence | Success: Bug reproduced with evidence artifacts +TASK: + - Navigate to target URL + - Execute reproduction steps using Chrome DevTools MCP + - Capture evidence: screenshots, DOM snapshots, console logs, network requests + - If performance dimension: run performance trace + - Package all evidence into session evidence/ directory +CONTEXT: + - Session: + - Bug URL: + - Steps: + - Evidence plan: +EXPECTED: /evidence/ directory with all captures + reproduction report +CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md +``` + +### ANALYZE-001 (Debug Mode): Root Cause Analysis + +``` +PURPOSE: Analyze evidence to identify root cause | Success: RCA report with specific file:line location +TASK: + - Load evidence from REPRODUCE-001 + - Analyze console errors and stack traces + - Analyze failed/abnormal network requests + - Compare DOM snapshot against expected structure + - Correlate findings to source code location +CONTEXT: + - Session: + - Upstream: /evidence/ + - Bug description: +EXPECTED: /artifacts/ANALYZE-001-rca.md with root cause, file:line, fix recommendation +CONSTRAINTS: Read-only analysis | Request more evidence if inconclusive +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/analyzer/role.md +``` + +### FIX-001 (Debug Mode): Code Fix + +``` +PURPOSE: Fix the identified bug | Success: Code changes that resolve the root cause +TASK: + - Load RCA report from ANALYZE-001 + - Locate the problematic code + - Implement fix following existing code patterns + - Run syntax/type check on modified files +CONTEXT: + - Session: + - Upstream: /artifacts/ANALYZE-001-rca.md +EXPECTED: Modified source files + /artifacts/FIX-001-changes.md +CONSTRAINTS: Minimal changes | Follow existing code style | No breaking changes +--- +InnerLoop: true +RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md +``` + +### VERIFY-001 (Debug Mode): Fix Verification + +``` +PURPOSE: Verify bug is fixed | Success: Original bug no longer reproduces +TASK: + - Navigate to same URL as REPRODUCE-001 + - Execute same reproduction steps + - Capture evidence and compare with original + - Confirm bug is resolved and no regressions +CONTEXT: + - Session: + - Original evidence: /evidence/ + - Fix changes: /artifacts/FIX-001-changes.md +EXPECTED: /artifacts/VERIFY-001-report.md with pass/fail verdict +CONSTRAINTS: Use Chrome DevTools MCP only | Same steps as reproduction +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/verifier/role.md +``` + +--- + +## Dynamic Iteration Tasks + +### REPRODUCE-002 (Debug Mode): Supplemental Evidence + +Created when Analyzer requests more evidence: +``` +PURPOSE: Collect additional evidence per Analyzer request | Success: Targeted evidence collected +TASK: +CONTEXT: Session + Analyzer request +--- +InnerLoop: false +RoleSpec: .claude/skills/team-frontend-debug/roles/reproducer/role.md +``` + +### FIX-002 (Either Mode): Re-Fix After Failed Verification + +Created when Verifier reports fail: +``` +PURPOSE: Re-fix based on verification failure feedback | Success: Issue resolved +TASK: Review VERIFY-001 failure details, apply corrective fix +CONTEXT: Session + VERIFY-001-report.md +--- +InnerLoop: true +RoleSpec: .claude/skills/team-frontend-debug/roles/fixer/role.md +``` + +## Conditional Skip Rules + +| Condition | Action | +|-----------|--------| +| test-pipeline + TEST-001 finds 0 issues | Skip ANALYZE/FIX/VERIFY → pipeline complete | +| test-pipeline + TEST-001 finds only warnings | AskUserQuestion: fix warnings or complete | +| debug-pipeline + REPRODUCE-001 cannot reproduce | AskUserQuestion: retry with more info or abort | + +## InnerLoop Flag Rules + +- true: tester (iterates over features), fixer (may need multiple fix passes) +- false: reproducer, analyzer, verifier (single-pass tasks) + +## Dependency Validation + +- No orphan tasks (all tasks have valid owner) +- No circular dependencies +- All blockedBy references exist +- Session reference in every task description +- RoleSpec reference in every task description diff --git a/.claude/skills/team-frontend-debug/roles/coordinator/commands/monitor.md b/.claude/skills/team-frontend-debug/roles/coordinator/commands/monitor.md new file mode 100644 index 00000000..7ee95961 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/coordinator/commands/monitor.md @@ -0,0 +1,122 @@ +# 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, remove from active_workers +5. Check for special conditions: + - **TEST-001 with 0 issues** -> skip ANALYZE/FIX/VERIFY (mark as completed), handleComplete + - **TEST-001 with only warnings** -> AskUserQuestion: 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 (create FIX-002 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. Create REPRODUCE-002 task: + - TaskCreate with description from Analyzer's request + - blockedBy: [] (can start immediately) +3. Create ANALYZE-002 task: + - blockedBy: [REPRODUCE-002] + - Update FIX-001 blockedBy to include ANALYZE-002 +4. Update team-session.json with new tasks +5. -> handleSpawnNext + +## handleCheck + +Read-only status report, then STOP. + +Output: +``` +[coordinator] Debug Pipeline Status +[coordinator] Bug: +[coordinator] Progress: / (%) +[coordinator] Active: +[coordinator] Ready: +[coordinator] Evidence: +[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 +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: + - TaskUpdate -> in_progress + - team_msg log -> task_unblocked + - Spawn team-worker (see SKILL.md Worker Spawn Template) + - Add to active_workers +5. Update session, output summary, STOP + +## 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 -> AskUserQuestion (Archive/Keep/Export) + - auto_archive -> Archive & Clean (status=completed, TeamDelete) + - 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 + +## 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 diff --git a/.claude/skills/team-frontend-debug/roles/coordinator/role.md b/.claude/skills/team-frontend-debug/roles/coordinator/role.md new file mode 100644 index 00000000..1bfbc811 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/coordinator/role.md @@ -0,0 +1,128 @@ +# 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/.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 TaskList, reset in_progress->pending + b. Rebuild team workers + c. Kick first ready task +4. Multiple -> AskUserQuestion 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 → AskUserQuestion 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 (AskUserQuestion) +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. Generate session ID: TFD-- +2. Create session folder structure: + ``` + .workflow/.team/TFD--/ + ├── team-session.json + ├── evidence/ + ├── artifacts/ + ├── wisdom/ + └── .msg/ + ``` +3. TeamCreate with team name +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. Create tasks via TaskCreate with blockedBy +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 -> AskUserQuestion (Archive/Keep/Export) + - auto_archive -> Archive & Clean + +## Error Handling + +| Error | Resolution | +|-------|------------| +| Bug report too vague | AskUserQuestion 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 | diff --git a/.claude/skills/team-frontend-debug/roles/fixer/role.md b/.claude/skills/team-frontend-debug/roles/fixer/role.md new file mode 100644 index 00000000..f1218bd2 --- /dev/null +++ b/.claude/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: `/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: "", + query: "" + }) + ``` +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://" }) +``` + +If diagnostics show errors: +- Fix syntax/type errors +- Re-validate +- Max 3 fix iterations for syntax issues + +## Phase 4: Document Changes + Report + +Write `/artifacts/FIX-001-changes.md`: + +```markdown +# Fix Report + +## Root Cause Reference +- RCA: /artifacts/ANALYZE-001-rca.md +- Category: +- Source: + +## Changes Applied + +### +- **Line(s)**: +- **Change**: +- **Reason**: + +## Validation +- Syntax check: +- Type check: +- Diagnostics: + +## Files Modified +- +- + +## Risk Assessment +- Breaking changes: +- Side effects: +- Rollback: +``` + +Send state_update: +```json +{ + "status": "task_complete", + "task_id": "FIX-001", + "ref": "/artifacts/FIX-001-changes.md", + "key_findings": ["Fixed ", "Modified N files"], + "decisions": ["Applied "], + "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 | diff --git a/.claude/skills/team-frontend-debug/roles/reproducer/role.md b/.claude/skills/team-frontend-debug/roles/reproducer/role.md new file mode 100644 index 00000000..9fcdc873 --- /dev/null +++ b/.claude/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: "" }) +``` + +Wait for page load: +``` +mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 }) +``` + +### Step 3.2: Capture Baseline Evidence + +Before executing steps, capture baseline state: + +| Evidence Type | Tool | Save To | +|---------------|------|---------| +| Screenshot (before) | `take_screenshot({ filePath: "/evidence/before-screenshot.png" })` | evidence/ | +| DOM Snapshot (before) | `take_snapshot({ filePath: "/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: "" })` | + | Fill input | `mcp__chrome-devtools__fill({ uid: "", value: "" })` | + | Hover element | `mcp__chrome-devtools__hover({ uid: "" })` | + | Press key | `mcp__chrome-devtools__press_key({ key: "" })` | + | Wait for element | `mcp__chrome-devtools__wait_for({ text: [""] })` | + | Run script | `mcp__chrome-devtools__evaluate_script({ function: "" })` | + +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: "/evidence/after-screenshot.png" })` | Always | +| DOM Snapshot (after) | `take_snapshot({ filePath: "/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: })` | For failed/suspicious requests | +| Performance Trace | `performance_start_trace()` + reproduce + `performance_stop_trace()` | If performance dimension | + +### Step 3.5: Save Evidence Summary + +Write `/evidence/evidence-summary.json`: +```json +{ + "reproduction_success": true, + "target_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": "/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 | diff --git a/.claude/skills/team-frontend-debug/roles/tester/role.md b/.claude/skills/team-frontend-debug/roles/tester/role.md new file mode 100644 index 00000000..cced8c26 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/tester/role.md @@ -0,0 +1,231 @@ +--- +role: tester +prefix: TEST +inner_loop: true +message_types: + success: test_complete + progress: test_progress + error: error +--- + +# Tester + +Feature-driven testing using Chrome DevTools MCP. Proactively discover bugs from feature list. + +## Identity +- Tag: [tester] | Prefix: TEST-* +- Responsibility: Parse feature list → generate test scenarios → execute in browser → report discovered issues + +## Boundaries +### MUST +- Parse feature list into testable scenarios +- Navigate to each feature's page using Chrome DevTools MCP +- Execute test scenarios with user interaction simulation +- Capture evidence for each test (screenshot, console, network) +- Classify results: pass / fail / warning +- Report all discovered issues with evidence +### MUST NOT +- Modify source code or project files +- Skip features in the list +- Report pass without actually testing +- Make assumptions about expected behavior without evidence + +## Phase 2: Parse Feature List + Plan Tests + +1. Read upstream artifacts via team_msg(operation="get_state") +2. Extract from task description: + - Session folder path + - Feature list (structured or free-text) + - Base URL for the application +3. Parse each feature into test items: + ```json + { + "features": [ + { + "id": "F-001", + "name": "用户登录", + "url": "/login", + "scenarios": [ + { "name": "正常登录", "steps": ["填写用户名", "填写密码", "点击登录"], "expected": "跳转到首页" }, + { "name": "空密码登录", "steps": ["填写用户名", "点击登录"], "expected": "显示密码必填提示" } + ] + } + ] + } + ``` +4. If feature descriptions lack detail, use page exploration to generate scenarios: + - Navigate to feature URL + - Take snapshot to discover interactive elements + - Generate scenarios from available UI elements (forms, buttons, links) + +## Phase 3: Execute Tests + +### Inner Loop: Process One Feature at a Time + +For each feature in the list: + +#### Step 3.1: Navigate to Feature Page + +``` +mcp__chrome-devtools__navigate_page({ type: "url", url: "" }) +mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 }) +``` + +#### Step 3.2: Explore Page Structure + +``` +mcp__chrome-devtools__take_snapshot() +``` + +Parse snapshot to identify: +- Interactive elements (buttons, inputs, links, selects) +- Form fields and their labels +- Navigation elements +- Dynamic content areas + +If no predefined scenarios, generate test scenarios from discovered elements. + +#### Step 3.3: Execute Each Scenario + +For each scenario: + +1. **Capture baseline**: + ``` + mcp__chrome-devtools__take_screenshot({ filePath: "/evidence/F---before.png" }) + mcp__chrome-devtools__list_console_messages() // baseline errors + ``` + +2. **Execute steps**: + - Map step descriptions to MCP actions: + | Step Pattern | MCP Action | + |-------------|------------| + | 点击/click XX | `take_snapshot` → find uid → `click({ uid })` | + | 填写/输入/fill XX with YY | `take_snapshot` → find uid → `fill({ uid, value })` | + | 悬停/hover XX | `take_snapshot` → find uid → `hover({ uid })` | + | 等待/wait XX | `wait_for({ text: ["XX"] })` | + | 导航/navigate to XX | `navigate_page({ type: "url", url: "XX" })` | + | 按键/press XX | `press_key({ key: "XX" })` | + | 滚动/scroll | `evaluate_script({ function: "() => window.scrollBy(0, 500)" })` | + +3. **Capture result**: + ``` + mcp__chrome-devtools__take_screenshot({ filePath: "/evidence/F---after.png" }) + mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] }) + mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] }) + ``` + +#### Step 3.4: Evaluate Scenario Result + +| Check | Pass Condition | Fail Condition | +|-------|---------------|----------------| +| Console errors | No new errors after action | New Error/TypeError/ReferenceError | +| Network requests | All 2xx responses | Any 4xx/5xx response | +| Expected text | Expected text appears on page | Expected text not found | +| Visual state | Page renders without broken layout | Blank area, overflow, missing elements | +| Page responsive | Actions complete within timeout | Timeout or page freeze | + +Classify result: +``` +pass: All checks pass +fail: Console error OR network failure OR expected behavior not met +warning: Deprecation warnings OR slow response (>3s) OR minor visual issue +``` + +#### Step 3.5: Report Progress (Inner Loop) + +After each feature, send progress via state_update: +```json +{ + "status": "in_progress", + "task_id": "TEST-001", + "progress": "3/5 features tested", + "issues_found": 2 +} +``` + +## Phase 4: Test Report + +Write `/artifacts/TEST-001-report.md`: + +```markdown +# Test Report + +## Summary +- **Features tested**: N +- **Passed**: X +- **Failed**: Y +- **Warnings**: Z +- **Test date**: +- **Base URL**: + +## Results by Feature + +### F-001: — PASS/FAIL/WARNING + +**Scenarios:** +| # | Scenario | Result | Issue | +|---|----------|--------|-------| +| 1 | | PASS | — | +| 2 | | FAIL | Console TypeError at step 3 | + +**Evidence:** +- Screenshot (before): evidence/F-001-scenario1-before.png +- Screenshot (after): evidence/F-001-scenario1-after.png +- Console errors: [list] +- Network failures: [list] + +### F-002: ... + +## Discovered Issues + +| ID | Feature | Severity | Description | Evidence | +|----|---------|----------|-------------|----------| +| BUG-001 | F-001 | High | TypeError on login submit | Console error + screenshot | +| BUG-002 | F-003 | Medium | API returns 500 on save | Network log | +| BUG-003 | F-005 | Low | Deprecation warning in console | Console warning | +``` + +Write `/artifacts/TEST-001-issues.json`: +```json +{ + "issues": [ + { + "id": "BUG-001", + "feature": "F-001", + "feature_name": "用户登录", + "severity": "high", + "description": "点击登录按钮后控制台报TypeError", + "category": "javascript_error", + "evidence": { + "console_errors": ["TypeError: Cannot read property 'token' of undefined"], + "screenshot": "evidence/F-001-login-after.png", + "network_failures": [] + }, + "reproduction_steps": ["导航到/login", "填写用户名admin", "填写密码test", "点击登录按钮"] + } + ] +} +``` + +Send state_update: +```json +{ + "status": "task_complete", + "task_id": "TEST-001", + "ref": "/artifacts/TEST-001-report.md", + "key_findings": ["Tested N features", "Found X issues (Y high, Z medium)"], + "decisions": [], + "verification": "tested", + "issues_ref": "/artifacts/TEST-001-issues.json" +} +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Feature URL not accessible | Log as failed, continue to next feature | +| Element not found for action | Take snapshot, search alternatives, skip scenario if not found | +| Page crash during test | Capture console, reload, continue next scenario | +| All features pass | Report success, no downstream ANALYZE needed | +| Timeout during interaction | Capture current state, mark as warning, continue | diff --git a/.claude/skills/team-frontend-debug/roles/verifier/role.md b/.claude/skills/team-frontend-debug/roles/verifier/role.md new file mode 100644 index 00000000..8db38444 --- /dev/null +++ b/.claude/skills/team-frontend-debug/roles/verifier/role.md @@ -0,0 +1,172 @@ +--- +role: verifier +prefix: VERIFY +inner_loop: false +message_types: + success: verification_result + error: error +--- + +# Verifier + +Fix verification using Chrome DevTools MCP to confirm bug resolution. + +## Identity +- Tag: [verifier] | Prefix: VERIFY-* +- Responsibility: Re-execute reproduction steps after fix, verify bug is resolved + +## Boundaries +### MUST +- Execute EXACT same reproduction steps as Reproducer +- Capture same evidence types for comparison +- Compare before/after evidence objectively +- Report clear pass/fail verdict +### MUST NOT +- Modify source code or project files +- Skip any reproduction step +- Report pass without evidence comparison +- Make subjective judgments without evidence + +## Phase 2: Load Context + +1. Read upstream artifacts via team_msg(operation="get_state") +2. Load from multiple upstream roles: + - Reproducer: evidence-summary.json (original evidence + steps) + - Fixer: FIX-001-changes.md (what was changed) +3. Extract: + - Target URL + - Reproduction steps (exact same sequence) + - Original evidence for comparison + - Expected behavior (from bug report) + - Files modified by fixer + +## Phase 3: Execute Verification + +### Step 3.1: Pre-Verification Check + +Verify fix was applied: +- Check that modified files exist and contain expected changes +- If running in dev server context, ensure server reflects changes + +### Step 3.2: Navigate and Reproduce + +Execute SAME steps as Reproducer: + +``` +mcp__chrome-devtools__navigate_page({ type: "url", url: "" }) +mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 }) +``` + +### Step 3.3: Capture Post-Fix Evidence + +Capture same evidence types as original reproduction: + +| Evidence | Tool | Save To | +|----------|------|---------| +| Screenshot | `take_screenshot({ filePath: "/evidence/verify-screenshot.png" })` | evidence/ | +| DOM Snapshot | `take_snapshot({ filePath: "/evidence/verify-snapshot.txt" })` | evidence/ | +| Console Messages | `list_console_messages({ types: ["error", "warn"] })` | In-memory | +| Network Requests | `list_network_requests({ resourceTypes: ["xhr", "fetch"] })` | In-memory | + +### Step 3.4: Execute Reproduction Steps + +For each step from original reproduction: +1. Execute same action (click, fill, hover, etc.) +2. Observe result +3. Note any differences from original reproduction + +### Step 3.5: Capture Final State + +After all steps: +- Screenshot of final state +- Console messages (check for new errors) +- Network requests (check for new failures) + +## Phase 4: Compare and Report + +### Comparison Criteria + +| Dimension | Pass | Fail | +|-----------|------|------| +| Console Errors | Original error no longer appears | Original error still present | +| Network | Failed request now succeeds | Request still fails | +| Visual | Expected rendering achieved | Bug still visible | +| DOM | Expected structure present | Structure still wrong | +| New Errors | No new errors introduced | New errors detected | + +### Verdict Logic + +``` +if original_error_resolved AND no_new_errors: + verdict = "pass" +elif original_error_resolved AND has_new_errors: + verdict = "pass_with_warnings" # bug fixed but new issues +else: + verdict = "fail" +``` + +### Write Verification Report + +Write `/artifacts/VERIFY-001-report.md`: + +```markdown +# Verification Report + +## Verdict: + +## Bug Status +- **Original bug**: +- **Reproduction steps**: + +## Evidence Comparison + +### Console Errors +- **Before fix**: + - + - +- **After fix**: + - +- **Resolution**: + +### Network Requests +- **Before fix**: +- **After fix**: +- **Resolution**: + +### Visual Comparison +- **Before fix**: +- **After fix**: +- **Resolution**: + +## Regression Check +- **New console errors**: +- **New network failures**: +- **Visual regressions**: + +## Files Verified +- — changes confirmed applied +- — changes confirmed applied +``` + +Send state_update: +```json +{ + "status": "task_complete", + "task_id": "VERIFY-001", + "ref": "/artifacts/VERIFY-001-report.md", + "key_findings": ["Verdict: ", "Original bug: "], + "decisions": [], + "verification": "tested", + "verdict": "" +} +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Page fails to load | Retry once, report if still fails | +| Fix not applied | Report to coordinator, suggest re-fix | +| New errors detected | Report pass_with_warnings with details | +| Bug still present | Report fail with evidence comparison | +| Partial reproduction | Report with completed steps, note gaps | diff --git a/.claude/skills/team-frontend-debug/specs/debug-tools.md b/.claude/skills/team-frontend-debug/specs/debug-tools.md new file mode 100644 index 00000000..6e872113 --- /dev/null +++ b/.claude/skills/team-frontend-debug/specs/debug-tools.md @@ -0,0 +1,215 @@ +# Chrome DevTools MCP Usage Patterns + +Reference for debug tool usage across all roles. Reproducer and Verifier are primary consumers. + +## 1. Navigation & Page Control + +### Navigate to URL +``` +mcp__chrome-devtools__navigate_page({ type: "url", url: "http://localhost:3000/page" }) +``` + +### Wait for Page Load +``` +mcp__chrome-devtools__wait_for({ text: ["Expected Text"], timeout: 10000 }) +``` + +### Reload Page +``` +mcp__chrome-devtools__navigate_page({ type: "reload" }) +``` + +### List Open Pages +``` +mcp__chrome-devtools__list_pages() +``` + +### Select Page +``` +mcp__chrome-devtools__select_page({ pageId: 0 }) +``` + +## 2. User Interaction Simulation + +### Click Element +``` +// First take snapshot to find uid +mcp__chrome-devtools__take_snapshot() +// Then click by uid +mcp__chrome-devtools__click({ uid: "" }) +``` + +### Fill Input +``` +mcp__chrome-devtools__fill({ uid: "", value: "input text" }) +``` + +### Fill Multiple Fields +``` +mcp__chrome-devtools__fill_form({ + elements: [ + { uid: "", value: "value1" }, + { uid: "", value: "value2" } + ] +}) +``` + +### Hover Element +``` +mcp__chrome-devtools__hover({ uid: "" }) +``` + +### Press Key +``` +mcp__chrome-devtools__press_key({ key: "Enter" }) +mcp__chrome-devtools__press_key({ key: "Control+A" }) +``` + +### Type Text +``` +mcp__chrome-devtools__type_text({ text: "typed content", submitKey: "Enter" }) +``` + +## 3. Evidence Collection + +### Screenshot +``` +// Full viewport +mcp__chrome-devtools__take_screenshot({ filePath: "/evidence/screenshot.png" }) + +// Full page +mcp__chrome-devtools__take_screenshot({ filePath: "", fullPage: true }) + +// Specific element +mcp__chrome-devtools__take_screenshot({ uid: "", filePath: "" }) +``` + +### DOM/A11y Snapshot +``` +// Standard snapshot +mcp__chrome-devtools__take_snapshot() + +// Verbose (all a11y info) +mcp__chrome-devtools__take_snapshot({ verbose: true }) + +// Save to file +mcp__chrome-devtools__take_snapshot({ filePath: "/evidence/snapshot.txt" }) +``` + +### Console Messages +``` +// All messages +mcp__chrome-devtools__list_console_messages() + +// Errors and warnings only +mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] }) + +// Get specific message detail +mcp__chrome-devtools__get_console_message({ msgid: 5 }) +``` + +### Network Requests +``` +// All requests +mcp__chrome-devtools__list_network_requests() + +// XHR/Fetch only (API calls) +mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] }) + +// Get request detail (headers, body, response) +mcp__chrome-devtools__get_network_request({ reqid: 3 }) + +// Save response to file +mcp__chrome-devtools__get_network_request({ reqid: 3, responseFilePath: "" }) +``` + +### Performance Trace +``` +// Start trace (auto-reload and auto-stop) +mcp__chrome-devtools__performance_start_trace({ reload: true, autoStop: true }) + +// Start manual trace +mcp__chrome-devtools__performance_start_trace({ reload: false, autoStop: false }) + +// Stop and save +mcp__chrome-devtools__performance_stop_trace({ filePath: "/evidence/trace.json" }) +``` + +## 4. Script Execution + +### Evaluate JavaScript +``` +// Get page title +mcp__chrome-devtools__evaluate_script({ function: "() => document.title" }) + +// Get element state +mcp__chrome-devtools__evaluate_script({ + function: "(el) => ({ text: el.innerText, classes: el.className })", + args: [""] +}) + +// Check React state (if applicable) +mcp__chrome-devtools__evaluate_script({ + function: "() => { const fiber = document.querySelector('#root')._reactRootContainer; return fiber ? 'React detected' : 'No React'; }" +}) + +// Get computed styles +mcp__chrome-devtools__evaluate_script({ + function: "(el) => JSON.stringify(window.getComputedStyle(el))", + args: [""] +}) +``` + +## 5. Common Debug Patterns + +### Pattern: Reproduce Click Bug +``` +1. navigate_page → target URL +2. wait_for → page loaded +3. take_snapshot → find target element uid +4. take_screenshot → before state +5. list_console_messages → baseline errors +6. click → target element +7. wait_for → expected result (or timeout) +8. take_screenshot → after state +9. list_console_messages → new errors +10. list_network_requests → triggered requests +``` + +### Pattern: Debug API Error +``` +1. navigate_page → target URL +2. wait_for → page loaded +3. take_snapshot → find trigger element +4. click/fill → trigger API call +5. list_network_requests → find the API request +6. get_network_request → inspect headers, body, response +7. list_console_messages → check for error handling +``` + +### Pattern: Debug Performance Issue +``` +1. navigate_page → target URL (set URL first) +2. performance_start_trace → start recording with reload +3. (auto-stop after page loads) +4. Read trace results → identify long tasks, bottlenecks +``` + +### Pattern: Debug Visual/CSS Issue +``` +1. navigate_page → target URL +2. take_screenshot → capture current visual state +3. take_snapshot({ verbose: true }) → full a11y tree with styles +4. evaluate_script → get computed styles of problematic element +5. Compare expected vs actual styles +``` + +## 6. Error Handling + +| Error | Meaning | Resolution | +|-------|---------|------------| +| "No page selected" | No browser tab active | list_pages → select_page | +| "Element not found" | uid is stale | take_snapshot → get new uid | +| "Navigation timeout" | Page didn't load | Check URL, retry with longer timeout | +| "Evaluation failed" | JS error in script | Check script syntax, page context | +| "No trace recording" | stop_trace without start | Ensure start_trace was called first | diff --git a/.claude/skills/team-frontend-debug/specs/pipelines.md b/.claude/skills/team-frontend-debug/specs/pipelines.md new file mode 100644 index 00000000..66f84ef1 --- /dev/null +++ b/.claude/skills/team-frontend-debug/specs/pipelines.md @@ -0,0 +1,94 @@ +# Pipeline Definitions + +## 1. Pipeline Selection Criteria + +| Keywords | Pipeline | +|----------|----------| +| 功能, feature, 清单, list, 测试, test, 完成, done, 验收 | `test-pipeline` | +| bug, 错误, 报错, crash, 问题, 不工作, 白屏, 异常 | `debug-pipeline` | +| performance, 性能, slow, 慢, latency, memory | `debug-pipeline` (perf dimension) | +| Ambiguous / unclear | AskUserQuestion | + +## 2. Test Pipeline (Feature-List Driven) + +**4 tasks, linear with conditional skip** + +``` +TEST-001 → [issues found?] → ANALYZE-001 → FIX-001 → VERIFY-001 + | + └─ no issues → Pipeline Complete (skip ANALYZE/FIX/VERIFY) +``` + +| Task | Role | Description | Conditional | +|------|------|-------------|-------------| +| TEST-001 | tester | Test all features, discover issues | Always | +| ANALYZE-001 | analyzer | Analyze discovered issues, produce RCA | Skip if 0 issues | +| FIX-001 | fixer | Fix all identified root causes | Skip if 0 issues | +| VERIFY-001 | verifier | Re-test failed scenarios to verify fixes | Skip if 0 issues | + +### Conditional Skip Logic + +After TEST-001 completes, coordinator reads `TEST-001-issues.json`: +- `issues.length === 0` → All pass. Skip downstream tasks, report success. +- `issues.filter(i => i.severity !== "low").length === 0` → Only warnings. AskUserQuestion: fix or complete. +- `issues.filter(i => i.severity === "high" || i.severity === "medium").length > 0` → Proceed with ANALYZE → FIX → VERIFY. + +### Re-Fix Iteration + +If VERIFY-001 reports failures: +- Create FIX-002 (blockedBy: VERIFY-001) → VERIFY-002 (blockedBy: FIX-002) +- Max 3 fix iterations + +## 3. Debug Pipeline (Bug-Report Driven) + +**4 tasks, linear with iteration support** + +``` +REPRODUCE-001 → ANALYZE-001 → FIX-001 → VERIFY-001 + ↑ | + | (if fail) | + +--- REPRODUCE-002 ←----+ +``` + +| Task | Role | Description | +|------|------|-------------| +| REPRODUCE-001 | reproducer | Reproduce bug, collect evidence | +| ANALYZE-001 | analyzer | Analyze evidence, produce RCA report | +| FIX-001 | fixer | Implement code fix based on RCA | +| VERIFY-001 | verifier | Verify fix with same reproduction steps | + +### Iteration Rules + +- **Analyzer → Reproducer**: If Analyzer confidence < 50%, creates REPRODUCE-002 → ANALYZE-002 +- **Verifier → Fixer**: If Verifier verdict = fail, creates FIX-002 → VERIFY-002 + +### Maximum Iterations + +- Max reproduction iterations: 2 +- Max fix iterations: 3 +- After max iterations: report to user for manual intervention + +## 4. Task Metadata Registry + +| Task ID | Role | Pipeline | Depends On | Priority | +|---------|------|----------|------------|----------| +| TEST-001 | tester | test | - | P0 | +| REPRODUCE-001 | reproducer | debug | - | P0 | +| ANALYZE-001 | analyzer | both | TEST-001 or REPRODUCE-001 | P0 | +| FIX-001 | fixer | both | ANALYZE-001 | P0 | +| VERIFY-001 | verifier | both | FIX-001 | P0 | +| REPRODUCE-002 | reproducer | debug | (dynamic) | P0 | +| ANALYZE-002 | analyzer | debug | REPRODUCE-002 | P0 | +| FIX-002 | fixer | both | VERIFY-001 | P0 | +| VERIFY-002 | verifier | both | FIX-002 | P0 | + +## 5. Evidence Types Registry + +| Dimension | Evidence | MCP Tool | Collector Roles | +|-----------|----------|----------|----------------| +| Visual | Screenshots | take_screenshot | tester, reproducer, verifier | +| DOM | A11y snapshots | take_snapshot | tester, reproducer, verifier | +| Console | Error/warn messages | list_console_messages | tester, reproducer, verifier | +| Network | API requests/responses | list/get_network_request | tester, reproducer, verifier | +| Performance | Trace recording | performance_start/stop_trace | reproducer, verifier | +| Interaction | User actions | click/fill/hover | tester, reproducer, verifier | diff --git a/.claude/skills/team-lifecycle-v4/SKILL.md b/.claude/skills/team-lifecycle-v4/SKILL.md index 4a1a550e..ed3c2c2a 100644 --- a/.claude/skills/team-lifecycle-v4/SKILL.md +++ b/.claude/skills/team-lifecycle-v4/SKILL.md @@ -22,11 +22,14 @@ Skill(skill="team-lifecycle-v4", args="task description") Coordinator Worker roles/coordinator/role.md roles//role.md | - +-- analyze → dispatch → spawn workers → STOP - | - +-------+-------+-------+ - v v v v - [team-worker agents, each loads roles//role.md] + +-- analyze → dispatch → spawn → STOP + | + +--------+---+--------+ + v v v + [team-worker] ... [team-supervisor] + per-task resident agent + lifecycle message-driven + (woken via SendMessage) ``` ## Role Registry @@ -40,6 +43,7 @@ Skill(skill="team-lifecycle-v4", args="task description") | executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | true | | tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | false | | reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-*, QUALITY-*, IMPROVE-* | false | +| supervisor | [roles/supervisor/role.md](roles/supervisor/role.md) | CHECKPOINT-* | false | ## Role Router @@ -79,6 +83,57 @@ Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 }) ``` +## Supervisor Spawn Template + +Supervisor is a **resident agent** (independent from team-worker). Spawned once during session init, woken via SendMessage for each CHECKPOINT task. + +### Spawn (Phase 2 — once per session) + +``` +Agent({ + subagent_type: "team-supervisor", + description: "Spawn resident supervisor", + team_name: , + name: "supervisor", + run_in_background: true, + prompt: `## Role Assignment +role: supervisor +role_spec: .claude/skills/team-lifecycle-v4/roles/supervisor/role.md +session: +session_id: +team_name: +requirement: + +Read role_spec file to load checkpoint definitions. +Init: load baseline context, report ready, go idle. +Wake cycle: coordinator sends checkpoint requests via SendMessage.` +}) +``` + +### Wake (handleSpawnNext — per CHECKPOINT task) + +``` +SendMessage({ + type: "message", + recipient: "supervisor", + content: `## Checkpoint Request +task_id: +scope: [] +pipeline_progress: / tasks completed`, + summary: "Checkpoint request: " +}) +``` + +### Shutdown (handleComplete) + +``` +SendMessage({ + type: "shutdown_request", + recipient: "supervisor", + content: "Pipeline complete, shutting down supervisor" +}) +``` + ## User Commands | Command | Action | @@ -137,4 +192,6 @@ AskUserQuestion({ | Role not found | Error with role registry | | CLI tool fails | Worker fallback to direct implementation | | Fast-advance conflict | Coordinator reconciles on next callback | +| Supervisor crash | Respawn with `recovery: true`, auto-rebuilds from existing reports | +| Supervisor not ready for CHECKPOINT | Spawn/respawn supervisor, wait for ready, then wake | | Completion action fails | Default to Keep Active | diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md index 19a02fec..f32856a1 100644 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/dispatch.md @@ -37,6 +37,16 @@ RoleSpec: .claude/skills/team-lifecycle-v4/roles//role.md - true: Role has 2+ serial same-prefix tasks (writer: DRAFT-001->004) - false: Role has 1 task, or tasks are parallel +## CHECKPOINT Task Rules + +CHECKPOINT tasks are dispatched like regular tasks but handled differently at spawn time: + +- Created via TaskCreate with proper blockedBy (upstream tasks that must complete first) +- Owner: supervisor +- **NOT spawned as team-worker** — coordinator wakes the resident supervisor via SendMessage +- If `supervision: false` in team-session.json, skip creating CHECKPOINT tasks entirely +- RoleSpec in description: `.claude/skills/team-lifecycle-v4/roles/supervisor/role.md` + ## Dependency Validation - No orphan tasks (all tasks have valid owner) diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md index d3868a54..9d01293c 100644 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/commands/monitor.md @@ -8,6 +8,7 @@ Event-driven pipeline coordination. Beat model: coordinator wake -> process -> s - ONE_STEP_PER_INVOCATION: true - FAST_ADVANCE_AWARE: true - WORKER_AGENT: team-worker +- SUPERVISOR_AGENT: team-supervisor (resident, woken via SendMessage) ## Handler Router @@ -27,8 +28,13 @@ 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, remove from active_workers +4. Completion -> mark task done + - Resident agent (supervisor) -> keep in active_workers (stays alive for future checkpoints) + - Standard worker -> remove from active_workers 5. Check for checkpoints: + - CHECKPOINT-* with verdict "block" -> AskUserQuestion: Override / Revise upstream / Abort + - CHECKPOINT-* with verdict "warn" -> log risks to wisdom, proceed normally + - CHECKPOINT-* with verdict "pass" -> proceed normally - QUALITY-001 -> display quality gate, pause for user commands - PLAN-001 -> read plan.json complexity, create dynamic IMPL tasks per specs/pipelines.md routing 6. -> handleSpawnNext @@ -52,6 +58,8 @@ Output: 2. Has active -> check each status - completed -> mark done - in_progress -> still running + - Resident agent (supervisor) with `resident: true` + no CHECKPOINT in_progress + pending CHECKPOINT exists + -> supervisor may have crashed. Respawn with `recovery: true` 3. Some completed -> handleSpawnNext 4. All running -> report status, STOP @@ -64,18 +72,43 @@ Find ready tasks, spawn workers, 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. TaskUpdate -> in_progress - c. team_msg log -> task_unblocked - d. Spawn team-worker (see SKILL.md Spawn Template) - e. Add to active_workers + b. **CHECKPOINT-* task** -> wake resident supervisor (see below) + c. Other tasks -> standard spawn: + - TaskUpdate -> in_progress + - team_msg log -> task_unblocked + - Spawn team-worker (see SKILL.md Worker Spawn Template) + - Add to active_workers 5. Update session, output summary, STOP +### Wake Supervisor for CHECKPOINT + +When a ready task has prefix `CHECKPOINT-*`: + +1. Verify supervisor is in active_workers with `resident: true` + - Not found -> spawn supervisor using SKILL.md Supervisor Spawn Template, wait for ready callback, then wake +2. Determine scope: list task IDs that this checkpoint depends on (its blockedBy tasks) +3. SendMessage to supervisor (see SKILL.md Supervisor Wake Template): + ``` + SendMessage({ + type: "message", + recipient: "supervisor", + content: "## Checkpoint Request\ntask_id: \nscope: []\npipeline_progress: / tasks completed", + summary: "Checkpoint request: " + }) + ``` +4. Do NOT TaskUpdate in_progress — supervisor claims the task itself +5. Do NOT add duplicate entry to active_workers (supervisor already tracked) + ## handleComplete Pipeline done. Generate report and completion action. -1. Generate summary (deliverables, stats, discussions) -2. Read session.completion_action: +1. Shutdown resident supervisor (if active): + ``` + SendMessage({ type: "shutdown_request", recipient: "supervisor", content: "Pipeline complete" }) + ``` +2. Generate summary (deliverables, stats, discussions) +3. Read session.completion_action: - interactive -> AskUserQuestion (Archive/Keep/Export) - auto_archive -> Archive & Clean (status=completed, TeamDelete) - auto_keep -> Keep Active (status=paused) diff --git a/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md b/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md index fd7fcdf5..03c94208 100644 --- a/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md +++ b/.claude/skills/team-lifecycle-v4/roles/coordinator/role.md @@ -49,7 +49,13 @@ For callback/check/resume/adapt/complete: load commands/monitor.md, execute hand 1. Scan .workflow/.team/TLV4-*/team-session.json for active/paused sessions 2. No sessions -> Phase 1 -3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task) +3. Single session -> reconcile: + a. Audit TaskList, reset in_progress->pending + b. Rebuild team workers + c. If pipeline has CHECKPOINT tasks AND `supervision !== false`: + - Respawn supervisor with `recovery: true` (see SKILL.md Supervisor Spawn Template) + - Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files + d. Kick first ready task 4. Multiple -> AskUserQuestion for selection ## Phase 1: Requirement Clarification @@ -79,6 +85,10 @@ TEXT-LEVEL ONLY. No source code reading. }) ``` 8. Write team-session.json +9. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND `supervision !== false`): + - Use SKILL.md Supervisor Spawn Template (subagent_type: "team-supervisor") + - Wait for "[supervisor] Ready" callback before proceeding to Phase 3 + - Record supervisor in active_workers with `resident: true` flag ## Phase 3: Create Task Chain @@ -112,5 +122,6 @@ Delegate to commands/monitor.md#handleSpawnNext: | Task too vague | AskUserQuestion for clarification | | Session corruption | Attempt recovery, fallback to manual | | Worker crash | Reset task to pending, respawn | +| Supervisor crash | Respawn with `recovery: true` in prompt, supervisor rebuilds context from existing reports | | Dependency cycle | Detect in analysis, halt | | Role limit exceeded | Merge overlapping roles | diff --git a/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md b/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md new file mode 100644 index 00000000..81657954 --- /dev/null +++ b/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md @@ -0,0 +1,192 @@ +--- +role: supervisor +prefix: CHECKPOINT +inner_loop: false +discuss_rounds: [] +message_types: + success: supervision_report + alert: consistency_alert + warning: pattern_warning + error: error +--- + +# Supervisor + +Process and execution supervision at pipeline phase transition points. + +## Identity +- Tag: [supervisor] | Prefix: CHECKPOINT-* +- Responsibility: Verify cross-artifact consistency, process compliance, and execution health between pipeline phases + +## Boundaries + +### MUST +- Read all upstream state_update messages from message bus +- Read upstream artifacts referenced in state data +- Check terminology consistency across produced documents +- Verify process compliance (upstream consumed, artifacts exist, wisdom contributed) +- Analyze error/retry patterns in message bus +- Output supervision_report with clear verdict (pass/warn/block) +- Write checkpoint report to `/artifacts/CHECKPOINT-NNN-report.md` + +### MUST NOT +- Perform deep quality scoring (reviewer's job — 4 dimensions × 25% weight) +- Evaluate AC testability or ADR justification (reviewer's job) +- Modify any artifacts (read-only observer) +- Skip reading message bus history (essential for pattern detection) +- Block pipeline without justification (every block needs specific evidence) +- Run discussion rounds (no consensus needed for checkpoints) + +## Phase 2: Context Gathering + +Load ALL available context for comprehensive supervision: + +### Step 1: Message Bus Analysis +``` +team_msg(operation="list", session_id=) +``` +- Collect all messages since session start +- Group by: type, from, error count +- Build timeline of task completions and their quality_self_scores + +### Step 2: Upstream State Loading +``` +team_msg(operation="get_state") // all roles +``` +- Load state for every completed upstream role +- Extract: key_findings, decisions, terminology_keys, open_questions +- Note: upstream_refs_consumed for reference chain verification + +### Step 3: Artifact Reading +- Read each artifact referenced in upstream states' `ref` paths +- Extract document structure, key terms, design decisions +- DO NOT deep-read entire documents — scan headings + key sections only + +### Step 4: Wisdom Loading +- Read `/wisdom/*.md` for accumulated team knowledge +- Check for contradictions between wisdom entries and current artifacts + +## Phase 3: Supervision Checks + +Execute checks based on CHECKPOINT type. Each checkpoint has a predefined scope. + +### CHECKPOINT-001: Brief ↔ PRD Consistency (after DRAFT-002) + +| Check | Method | Pass Criteria | +|-------|--------|---------------| +| Vision→Requirements trace | Compare brief goals with PRD FR-NNN IDs | Every vision goal maps to ≥1 requirement | +| Terminology alignment | Extract key terms from both docs | Same concept uses same term (no "user" vs "customer" drift) | +| Scope consistency | Compare brief scope with PRD scope | No requirements outside brief scope | +| Decision continuity | Compare decisions in analyst state vs writer state | No contradictions | +| Artifact existence | Check file paths | product-brief.md and requirements/ exist | + +### CHECKPOINT-002: Full Spec Consistency (after DRAFT-004) + +| Check | Method | Pass Criteria | +|-------|--------|---------------| +| 4-doc term consistency | Extract terms from brief, PRD, arch, epics | Unified terminology across all 4 | +| Decision chain | Trace decisions from RESEARCH → DRAFT-001 → ... → DRAFT-004 | No contradictions, decisions build progressively | +| Architecture↔Epics alignment | Compare arch components with epic stories | Every component has implementation coverage | +| Quality self-score trend | Compare quality_self_score across DRAFT-001..004 states | Not degrading (score[N] >= score[N-1] - 10) | +| Open questions resolved | Check open_questions across all states | No critical open questions remaining | +| Wisdom consistency | Cross-check wisdom entries against artifacts | No contradictory entries | + +### CHECKPOINT-003: Plan ↔ Input Alignment (after PLAN-001) + +| Check | Method | Pass Criteria | +|-------|--------|---------------| +| Plan covers requirements | Compare plan.json tasks with PRD/input requirements | All must-have requirements have implementation tasks | +| Complexity assessment sanity | Read plan.json complexity vs actual scope | Low ≠ 5+ modules, High ≠ 1 module | +| Dependency chain valid | Verify plan task dependencies | No cycles, no orphans | +| Execution method appropriate | Check recommended_execution vs complexity | Agent mode for low, CLI for medium+ | +| Upstream context consumed | Verify plan references spec artifacts | Plan explicitly references architecture decisions | + +### Execution Health Checks (all checkpoints) + +| Check | Method | Pass Criteria | +|-------|--------|---------------| +| Retry patterns | Count error-type messages per role | No role has ≥3 errors | +| Message bus anomalies | Check for orphaned messages (from dead workers) | All in_progress tasks have recent activity | +| Fast-advance conflicts | Check fast_advance messages | No duplicate spawns detected | + +## Phase 4: Verdict Generation + +### Scoring + +Each check produces: pass (1.0) | warn (0.5) | fail (0.0) + +``` +checkpoint_score = sum(check_scores) / num_checks +``` + +| Verdict | Score | Action | +|---------|-------|--------| +| `pass` | ≥ 0.8 | Auto-proceed, log report | +| `warn` | 0.5-0.79 | Proceed with recorded risks in wisdom | +| `block` | < 0.5 | Halt pipeline, report to coordinator | + +### Report Generation + +Write to `/artifacts/CHECKPOINT-NNN-report.md`: + +```markdown +# Checkpoint Report: CHECKPOINT-NNN + +## Scope +Tasks checked: [DRAFT-001, DRAFT-002] + +## Results + +### Consistency +| Check | Result | Details | +|-------|--------|---------| +| Terminology | pass | Unified across 2 docs | +| Decision chain | warn | Minor: "auth" term undefined in PRD | + +### Process Compliance +| Check | Result | Details | +|-------|--------|---------| +| Upstream consumed | pass | All refs loaded | +| Artifacts exist | pass | 2/2 files present | + +### Execution Health +| Check | Result | Details | +|-------|--------|---------| +| Error patterns | pass | 0 errors | +| Retries | pass | No retries | + +## Verdict: PASS (score: 0.90) + +## Recommendations +- Define "auth" explicitly in PRD glossary section + +## Risks Logged +- None +``` + +### State Update + +```json +{ + "status": "task_complete", + "task_id": "CHECKPOINT-001", + "ref": "/artifacts/CHECKPOINT-001-report.md", + "key_findings": ["Terminology aligned", "Decision chain consistent"], + "decisions": ["Proceed to architecture phase"], + "verification": "self-validated", + "supervision_verdict": "pass", + "supervision_score": 0.90, + "risks_logged": 0, + "blocks_detected": 0 +} +``` + +## Error Handling + +| Scenario | Resolution | +|----------|------------| +| Artifact file not found | Score as warn (not fail), log missing path | +| Message bus empty | Score as warn, note "no messages to analyze" | +| State missing for upstream role | Use artifact reading as fallback | +| All checks pass trivially | Still generate report for audit trail | +| Checkpoint blocked but user overrides | Log override in wisdom, proceed | diff --git a/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md b/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md index 3d67348b..0a20bda4 100644 --- a/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md +++ b/.claude/skills/team-lifecycle-v4/specs/knowledge-transfer.md @@ -64,6 +64,22 @@ Sent via `team_msg(type="state_update")` on task completion. - `files_modified`: Only for implementation tasks - `verification`: One of `self-validated`, `peer-reviewed`, `tested` +**Supervisor-specific extensions** (CHECKPOINT tasks only): + +```json +{ + "supervision_verdict": "pass | warn | block", + "supervision_score": 0.85, + "risks_logged": 0, + "blocks_detected": 0 +} +``` + +- `supervision_verdict`: Required for CHECKPOINT tasks. Determines pipeline progression. +- `supervision_score`: Float 0.0-1.0. Aggregate of individual check scores. +- `risks_logged`: Count of risks written to wisdom/issues.md. +- `blocks_detected`: Count of blocking issues found. >0 implies verdict=block. + ## 5. Exploration Cache Protocol Prevents redundant research across tasks and discussion rounds. diff --git a/.claude/skills/team-lifecycle-v4/specs/pipelines.md b/.claude/skills/team-lifecycle-v4/specs/pipelines.md index d991c73d..21358856 100644 --- a/.claude/skills/team-lifecycle-v4/specs/pipelines.md +++ b/.claude/skills/team-lifecycle-v4/specs/pipelines.md @@ -12,10 +12,10 @@ ## 2. Spec-Only Pipeline -**6 tasks, 3 discussion rounds** +**6 tasks + 2 optional checkpoints, 3 discussion rounds** ``` -RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QUALITY-001(+D3) +RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> [CHECKPOINT-001] -> DRAFT-003 -> DRAFT-004 -> [CHECKPOINT-002] -> QUALITY-001(+D3) ``` | Task | Role | Description | Discuss | @@ -23,39 +23,48 @@ RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> DRAFT-003 -> DRAFT-004 -> QU | RESEARCH-001 | analyst | Research domain, competitors, constraints | D1: scope alignment | | DRAFT-001 | writer | Product brief, self-validate | - | | DRAFT-002 | writer | Requirements PRD | D2: requirements review | +| CHECKPOINT-001 | supervisor | Brief↔PRD consistency, terminology alignment | - | | DRAFT-003 | writer | Architecture design, self-validate | - | | DRAFT-004 | writer | Epics & stories, self-validate | - | +| CHECKPOINT-002 | supervisor | Full spec consistency (4 docs), quality trend | - | | QUALITY-001 | reviewer | Quality gate scoring | D3: readiness decision | **Checkpoint**: After QUALITY-001 -- pause for user approval before any implementation. +**Supervision opt-out**: Set `supervision: false` in team-session.json to skip CHECKPOINT tasks. + ## 3. Impl-Only Pipeline -**4 tasks, 0 discussion rounds** +**4 tasks + 1 optional checkpoint, 0 discussion rounds** ``` -PLAN-001 -> IMPL-001 -> TEST-001 + REVIEW-001 +PLAN-001 -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001 ``` | Task | Role | Description | |------|------|-------------| | PLAN-001 | planner | Break down into implementation steps, assess complexity | +| CHECKPOINT-003 | supervisor | Plan↔input alignment, complexity sanity check | | IMPL-001 | implementer | Execute implementation plan | | TEST-001 | tester | Validate against acceptance criteria | | REVIEW-001 | reviewer | Code review | TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes. +**Supervision opt-out**: Set `supervision: false` in team-session.json to skip CHECKPOINT tasks. + ## 4. Full-Lifecycle Pipeline -**10 tasks = spec-only (6) + impl (4)** +**10 tasks + 3 optional checkpoints = spec-only (6+2) + impl (4+1)** ``` -[Spec pipeline] -> PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 + REVIEW-001 +[Spec pipeline with CHECKPOINT-001/002] -> PLAN-001(blockedBy: QUALITY-001) -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001 ``` PLAN-001 is blocked until QUALITY-001 passes and user approves the checkpoint. +**Supervision opt-out**: Set `supervision: false` in team-session.json to skip all CHECKPOINT tasks. + ## 5. Frontend Pipelines | Pipeline | Description | @@ -86,7 +95,10 @@ PLAN-001 outputs a complexity assessment that determines the impl topology. | DRAFT-002 | writer | requirements | DRAFT-001 | D2 | P0 | | DRAFT-003 | writer | architecture | DRAFT-002 | - | P0 | | DRAFT-004 | writer | epics | DRAFT-003 | - | P0 | -| QUALITY-001 | reviewer | readiness | DRAFT-004 | D3 | P0 | +| QUALITY-001 | reviewer | readiness | CHECKPOINT-002 (or DRAFT-004) | D3 | P0 | +| CHECKPOINT-001 | supervisor | checkpoint | DRAFT-002 | - | P1 | +| CHECKPOINT-002 | supervisor | checkpoint | DRAFT-004 | - | P1 | +| CHECKPOINT-003 | supervisor | checkpoint | PLAN-001 | - | P1 | | PLAN-001 | planner | planning | QUALITY-001 (or user input) | - | P0 | | ARCH-001 | architect | arch-detail | PLAN-001 | - | P1 | | ORCH-001 | orchestrator | orchestration | PLAN-001 or ARCH-001 | - | P1 | diff --git a/.npmignore b/.npmignore index e54135b2..33941df4 100644 --- a/.npmignore +++ b/.npmignore @@ -82,3 +82,6 @@ codex-lens/.coverage codex-lens/*.db codex-lens/_*.txt codex-lens/.workflow/ + +# Claude skills (development only) +.claude/skills/team-designer/