mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
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.
This commit is contained in:
catlog22
293
.claude/agents/team-supervisor.md
Normal file
293
.claude/agents/team-supervisor.md
Normal file
@@ -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=<session_id>) // all roles
|
||||
```
|
||||
- Record which roles have completed, their key_findings, decisions
|
||||
- Read `<session>/wisdom/*.md` — absorb accumulated team knowledge
|
||||
- Read `<session>/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 <session_id>. 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: "<task_id>", 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 `<session>/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 `<session>/artifacts/CHECKPOINT-NNN-report.md` (format defined in role_spec Phase 4).
|
||||
|
||||
### Step 6: Complete Task
|
||||
```javascript
|
||||
TaskUpdate({ taskId: "<task_id>", status: "completed" })
|
||||
```
|
||||
|
||||
### Step 7: Publish State
|
||||
```javascript
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session_id>",
|
||||
from: "supervisor",
|
||||
type: "state_update",
|
||||
data: {
|
||||
status: "task_complete",
|
||||
task_id: "<CHECKPOINT-NNN>",
|
||||
ref: "<session>/artifacts/CHECKPOINT-NNN-report.md",
|
||||
key_findings: ["..."],
|
||||
decisions: ["Proceed" or "Block: <reason>"],
|
||||
verification: "self-validated",
|
||||
supervision_verdict: "pass|warn|block",
|
||||
supervision_score: 0.85
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Step 8: Accumulate Context
|
||||
```
|
||||
context_accumulator.append({
|
||||
task: "<CHECKPOINT-NNN>",
|
||||
artifact: "<report-path>",
|
||||
verdict: "<pass|warn|block>",
|
||||
score: <0.0-1.0>,
|
||||
key_findings: [...],
|
||||
artifacts_read: [<list of artifact paths read this cycle>],
|
||||
quality_trend: "<stable|improving|degrading>"
|
||||
})
|
||||
```
|
||||
|
||||
### Step 9: Report to Coordinator
|
||||
```javascript
|
||||
SendMessage({
|
||||
type: "message",
|
||||
recipient: "coordinator",
|
||||
content: "[supervisor] CHECKPOINT-NNN complete.\nVerdict: <verdict> (score: <score>)\nFindings: <top-3>\nRisks: <count> logged\nQuality trend: <trend>\nArtifact: <path>",
|
||||
summary: "[supervisor] CHECKPOINT-NNN: <verdict>"
|
||||
})
|
||||
```
|
||||
|
||||
### Step 10: Go Idle
|
||||
Turn ends. Wait for next checkpoint request or shutdown.
|
||||
|
||||
---
|
||||
|
||||
## Crash Recovery
|
||||
|
||||
If spawned with `recovery: true` in prompt:
|
||||
|
||||
1. Scan `<session>/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: "<from message>",
|
||||
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: <session>/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.
|
||||
295
.claude/commands/ddd/doc-generate.md
Normal file
295
.claude/commands/ddd/doc-generate.md
Normal file
@@ -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/`
|
||||
218
.claude/commands/ddd/doc-refresh.md
Normal file
218
.claude/commands/ddd/doc-refresh.md
Normal file
@@ -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 <id1,id2,...>] [--features <id1,id2,...>] [--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 <ids>` | Comma-separated component IDs to refresh |
|
||||
| `--features <ids>` | 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`)
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
170
.claude/skills/team-frontend-debug/SKILL.md
Normal file
170
.claude/skills/team-frontend-debug/SKILL.md
Normal file
@@ -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 <name>
|
||||
| |
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/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 <name>` → Read `roles/<name>/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-<slug>-<date>/`
|
||||
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
|
||||
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<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 <role> worker",
|
||||
team_name: <team-name>,
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-frontend-debug/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: <team-name>
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
## User Commands
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View execution status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
| `revise <TASK-ID> [feedback]` | Revise specific task |
|
||||
| `feedback <text>` | Inject feedback for revision |
|
||||
| `retry <TASK-ID>` | 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-<slug>-<date>/
|
||||
├── 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 |
|
||||
207
.claude/skills/team-frontend-debug/roles/analyzer/role.md
Normal file
207
.claude/skills/team-frontend-debug/roles/analyzer/role.md
Normal file
@@ -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: "<project-root>",
|
||||
query: "<error message or function name from stack trace>"
|
||||
})
|
||||
```
|
||||
|
||||
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 `<session>/artifacts/ANALYZE-001-rca.md`:
|
||||
|
||||
```markdown
|
||||
# Root Cause Analysis Report
|
||||
|
||||
## Bug Summary
|
||||
- **Description**: <bug description>
|
||||
- **URL**: <target url>
|
||||
- **Reproduction**: <success/partial/failed>
|
||||
|
||||
## Root Cause
|
||||
- **Category**: <JS Error | Network | Rendering | Performance | State>
|
||||
- **Confidence**: <High | Medium | Low>
|
||||
- **Source File**: <file path>
|
||||
- **Source Line**: <line number>
|
||||
- **Root Cause**: <detailed explanation>
|
||||
|
||||
## Evidence Chain
|
||||
1. <evidence 1 -> finding>
|
||||
2. <evidence 2 -> finding>
|
||||
3. <correlation -> root cause>
|
||||
|
||||
## Fix Recommendation
|
||||
- **Approach**: <description of recommended fix>
|
||||
- **Files to modify**: <list>
|
||||
- **Risk level**: <Low | Medium | High>
|
||||
- **Estimated scope**: <lines of code / number of files>
|
||||
|
||||
## Additional Observations
|
||||
- <any related issues found>
|
||||
- <potential regression risks>
|
||||
```
|
||||
|
||||
Send state_update:
|
||||
```json
|
||||
{
|
||||
"status": "task_complete",
|
||||
"task_id": "ANALYZE-001",
|
||||
"ref": "<session>/artifacts/ANALYZE-001-rca.md",
|
||||
"key_findings": ["Root cause: <summary>", "Location: <file:line>"],
|
||||
"decisions": ["Recommended fix: <approach>"],
|
||||
"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: <what we know>"],
|
||||
"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 |
|
||||
@@ -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": "<url>",
|
||||
"features": [
|
||||
{ "id": "F-001", "name": "<name>", "url": "<path>", "description": "<desc>" }
|
||||
],
|
||||
"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": "<original>",
|
||||
"target_url": "<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" }
|
||||
}
|
||||
```
|
||||
@@ -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: <goal> | Success: <criteria>
|
||||
TASK:
|
||||
- <step 1>
|
||||
- <step 2>
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Base URL / Bug URL: <url>
|
||||
- Upstream artifacts: <list>
|
||||
EXPECTED: <artifact path> + <quality criteria>
|
||||
CONSTRAINTS: <scope limits>
|
||||
---
|
||||
InnerLoop: <true|false>
|
||||
RoleSpec: .claude/skills/team-frontend-debug/roles/<role>/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: <session-folder>
|
||||
- Base URL: <base-url>
|
||||
- Features: <feature-list-from-task-analysis>
|
||||
EXPECTED: <session>/artifacts/TEST-001-report.md + <session>/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: <session-folder>
|
||||
- Upstream: <session>/artifacts/TEST-001-issues.json
|
||||
- Test evidence: <session>/evidence/
|
||||
EXPECTED: <session>/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: <session-folder>
|
||||
- Upstream: <session>/artifacts/ANALYZE-001-rca.md
|
||||
EXPECTED: Modified source files + <session>/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: <session-folder>
|
||||
- Original test report: <session>/artifacts/TEST-001-report.md
|
||||
- Fix changes: <session>/artifacts/FIX-001-changes.md
|
||||
- Failed features: <from TEST-001-issues.json>
|
||||
EXPECTED: <session>/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: <session-folder>
|
||||
- Bug URL: <target-url>
|
||||
- Steps: <reproduction-steps>
|
||||
- Evidence plan: <from task-analysis.json>
|
||||
EXPECTED: <session>/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: <session-folder>
|
||||
- Upstream: <session>/evidence/
|
||||
- Bug description: <bug-description>
|
||||
EXPECTED: <session>/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: <session-folder>
|
||||
- Upstream: <session>/artifacts/ANALYZE-001-rca.md
|
||||
EXPECTED: Modified source files + <session>/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: <session-folder>
|
||||
- Original evidence: <session>/evidence/
|
||||
- Fix changes: <session>/artifacts/FIX-001-changes.md
|
||||
EXPECTED: <session>/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: <specific evidence requests from Analyzer>
|
||||
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
|
||||
@@ -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: <bug-description-summary>
|
||||
[coordinator] Progress: <done>/<total> (<pct>%)
|
||||
[coordinator] Active: <workers with elapsed time>
|
||||
[coordinator] Ready: <pending tasks with resolved deps>
|
||||
[coordinator] Evidence: <list of collected evidence types>
|
||||
[coordinator] Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
## handleResume
|
||||
|
||||
1. No active workers -> handleSpawnNext
|
||||
2. Has active -> check each status
|
||||
- completed -> mark done
|
||||
- in_progress -> still running
|
||||
3. Some completed -> handleSpawnNext
|
||||
4. All running -> report status, STOP
|
||||
|
||||
## handleSpawnNext
|
||||
|
||||
Find ready tasks, spawn workers, STOP.
|
||||
|
||||
1. Collect: completedSubjects, inProgressSubjects, readySubjects
|
||||
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
|
||||
128
.claude/skills/team-frontend-debug/roles/coordinator/role.md
Normal file
128
.claude/skills/team-frontend-debug/roles/coordinator/role.md
Normal file
@@ -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/<command>.md`
|
||||
2. Follow the workflow defined in the command
|
||||
3. Commands are inline execution guides, NOT separate agents
|
||||
4. Execute synchronously, complete before proceeding
|
||||
|
||||
## Entry Router
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains [role-name] | -> handleCallback (monitor.md) |
|
||||
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Iteration request | Message contains "need_more_evidence" | -> handleIteration (monitor.md) |
|
||||
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
|
||||
| Interrupted session | Active session in .workflow/.team/TFD-* | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
For callback/check/resume/iteration/complete: load commands/monitor.md, execute handler, STOP.
|
||||
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. Scan .workflow/.team/TFD-*/team-session.json for active/paused sessions
|
||||
2. No sessions -> Phase 1
|
||||
3. Single session -> reconcile:
|
||||
a. Audit 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-<slug>-<date>
|
||||
2. Create session folder structure:
|
||||
```
|
||||
.workflow/.team/TFD-<slug>-<date>/
|
||||
├── 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 |
|
||||
147
.claude/skills/team-frontend-debug/roles/fixer/role.md
Normal file
147
.claude/skills/team-frontend-debug/roles/fixer/role.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
role: fixer
|
||||
prefix: FIX
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: fix_complete
|
||||
progress: fix_progress
|
||||
error: error
|
||||
---
|
||||
|
||||
# Fixer
|
||||
|
||||
Code fix implementation based on root cause analysis.
|
||||
|
||||
## Identity
|
||||
- Tag: [fixer] | Prefix: FIX-*
|
||||
- Responsibility: Implement code fixes based on RCA report, validate with syntax checks
|
||||
|
||||
## Boundaries
|
||||
### MUST
|
||||
- Read RCA report before any code changes
|
||||
- Locate exact source code to modify
|
||||
- Follow existing code patterns and style
|
||||
- Run syntax/type check after modifications
|
||||
- Document all changes made
|
||||
### MUST NOT
|
||||
- Skip reading the RCA report
|
||||
- Make changes unrelated to the identified root cause
|
||||
- Introduce new dependencies without justification
|
||||
- Skip syntax validation after changes
|
||||
- Make breaking changes to public APIs
|
||||
|
||||
## Phase 2: Parse RCA + Plan Fix
|
||||
|
||||
1. Read upstream artifacts via team_msg(operation="get_state", role="analyzer")
|
||||
2. Extract RCA report path from analyzer's state_update ref
|
||||
3. Load RCA report: `<session>/artifacts/ANALYZE-001-rca.md`
|
||||
4. Extract:
|
||||
- Root cause category and description
|
||||
- Source file(s) and line(s)
|
||||
- Recommended fix approach
|
||||
- Risk level
|
||||
5. Read identified source files to understand context
|
||||
6. Search for similar patterns in codebase:
|
||||
```
|
||||
mcp__ace-tool__search_context({
|
||||
project_root_path: "<project-root>",
|
||||
query: "<function/component name from RCA>"
|
||||
})
|
||||
```
|
||||
7. Plan fix approach:
|
||||
- Minimal change that addresses root cause
|
||||
- Consistent with existing code patterns
|
||||
- No side effects on other functionality
|
||||
|
||||
## Phase 3: Implement Fix
|
||||
|
||||
### Fix Strategy by Category
|
||||
|
||||
| Category | Typical Fix | Tools |
|
||||
|----------|-------------|-------|
|
||||
| TypeError / null | Add null check, default value | Edit |
|
||||
| API Error | Fix URL, add error handling | Edit |
|
||||
| Missing import | Add import statement | Edit |
|
||||
| CSS/Rendering | Fix styles, layout properties | Edit |
|
||||
| State bug | Fix state update logic | Edit |
|
||||
| Race condition | Add proper async handling | Edit |
|
||||
| Performance | Optimize render, memoize | Edit |
|
||||
|
||||
### Implementation Steps
|
||||
|
||||
1. Read the target file(s)
|
||||
2. Apply minimal code changes using Edit tool
|
||||
3. If Edit fails, use mcp__ccw-tools__edit_file as fallback
|
||||
4. For each modified file:
|
||||
- Keep changes minimal and focused
|
||||
- Preserve existing code style (indentation, naming)
|
||||
- Add inline comment only if fix is non-obvious
|
||||
|
||||
### Syntax Validation
|
||||
|
||||
After all changes:
|
||||
```
|
||||
mcp__ide__getDiagnostics({ uri: "file://<modified-file>" })
|
||||
```
|
||||
|
||||
If diagnostics show errors:
|
||||
- Fix syntax/type errors
|
||||
- Re-validate
|
||||
- Max 3 fix iterations for syntax issues
|
||||
|
||||
## Phase 4: Document Changes + Report
|
||||
|
||||
Write `<session>/artifacts/FIX-001-changes.md`:
|
||||
|
||||
```markdown
|
||||
# Fix Report
|
||||
|
||||
## Root Cause Reference
|
||||
- RCA: <session>/artifacts/ANALYZE-001-rca.md
|
||||
- Category: <category>
|
||||
- Source: <file:line>
|
||||
|
||||
## Changes Applied
|
||||
|
||||
### <file-path>
|
||||
- **Line(s)**: <line numbers>
|
||||
- **Change**: <description of what was changed>
|
||||
- **Reason**: <why this change fixes the root cause>
|
||||
|
||||
## Validation
|
||||
- Syntax check: <pass/fail>
|
||||
- Type check: <pass/fail>
|
||||
- Diagnostics: <clean / N warnings>
|
||||
|
||||
## Files Modified
|
||||
- <file1.ts>
|
||||
- <file2.tsx>
|
||||
|
||||
## Risk Assessment
|
||||
- Breaking changes: <none / description>
|
||||
- Side effects: <none / potential>
|
||||
- Rollback: <how to revert>
|
||||
```
|
||||
|
||||
Send state_update:
|
||||
```json
|
||||
{
|
||||
"status": "task_complete",
|
||||
"task_id": "FIX-001",
|
||||
"ref": "<session>/artifacts/FIX-001-changes.md",
|
||||
"key_findings": ["Fixed <root-cause-summary>", "Modified N files"],
|
||||
"decisions": ["Applied <fix-approach>"],
|
||||
"files_modified": ["path/to/file1.ts", "path/to/file2.tsx"],
|
||||
"verification": "self-validated"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Source file not found | Search codebase, report if not found |
|
||||
| RCA location incorrect | Use ACE search to find correct location |
|
||||
| Syntax errors after fix | Iterate fix (max 3 attempts) |
|
||||
| Fix too complex | Report complexity, suggest manual intervention |
|
||||
| Multiple files need changes | Apply all changes, validate each |
|
||||
147
.claude/skills/team-frontend-debug/roles/reproducer/role.md
Normal file
147
.claude/skills/team-frontend-debug/roles/reproducer/role.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
role: reproducer
|
||||
prefix: REPRODUCE
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: evidence_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# Reproducer
|
||||
|
||||
Bug reproduction and evidence collection using Chrome DevTools MCP.
|
||||
|
||||
## Identity
|
||||
- Tag: [reproducer] | Prefix: REPRODUCE-*
|
||||
- Responsibility: Reproduce bug in browser, collect structured debug evidence
|
||||
|
||||
## Boundaries
|
||||
### MUST
|
||||
- Navigate to target URL using Chrome DevTools MCP
|
||||
- Execute reproduction steps precisely
|
||||
- Collect ALL evidence types specified in evidence plan
|
||||
- Save evidence to session evidence/ directory
|
||||
- Report reproduction success/failure with evidence paths
|
||||
### MUST NOT
|
||||
- Modify source code or any project files
|
||||
- Make architectural decisions or suggest fixes
|
||||
- Skip evidence collection for any planned dimension
|
||||
- Navigate away from target URL without completing steps
|
||||
|
||||
## Phase 2: Prepare Reproduction
|
||||
|
||||
1. Read upstream artifacts via team_msg(operation="get_state")
|
||||
2. Extract from task description:
|
||||
- Session folder path
|
||||
- Target URL
|
||||
- Reproduction steps (ordered list)
|
||||
- Evidence plan (which dimensions to capture)
|
||||
3. Verify browser is accessible:
|
||||
```
|
||||
mcp__chrome-devtools__list_pages()
|
||||
```
|
||||
4. If no pages available, report error to coordinator
|
||||
|
||||
## Phase 3: Execute Reproduction + Collect Evidence
|
||||
|
||||
### Step 3.1: Navigate to Target
|
||||
|
||||
```
|
||||
mcp__chrome-devtools__navigate_page({ type: "url", url: "<target-url>" })
|
||||
```
|
||||
|
||||
Wait for page load:
|
||||
```
|
||||
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
|
||||
```
|
||||
|
||||
### Step 3.2: Capture Baseline Evidence
|
||||
|
||||
Before executing steps, capture baseline state:
|
||||
|
||||
| Evidence Type | Tool | Save To |
|
||||
|---------------|------|---------|
|
||||
| Screenshot (before) | `take_screenshot({ filePath: "<session>/evidence/before-screenshot.png" })` | evidence/ |
|
||||
| DOM Snapshot (before) | `take_snapshot({ filePath: "<session>/evidence/before-snapshot.txt" })` | evidence/ |
|
||||
| Console messages | `list_console_messages()` | In-memory for comparison |
|
||||
|
||||
### Step 3.3: Execute Reproduction Steps
|
||||
|
||||
For each reproduction step:
|
||||
|
||||
1. Parse action type from step description:
|
||||
| Action | Tool |
|
||||
|--------|------|
|
||||
| Click element | `mcp__chrome-devtools__click({ uid: "<uid>" })` |
|
||||
| Fill input | `mcp__chrome-devtools__fill({ uid: "<uid>", value: "<value>" })` |
|
||||
| Hover element | `mcp__chrome-devtools__hover({ uid: "<uid>" })` |
|
||||
| Press key | `mcp__chrome-devtools__press_key({ key: "<key>" })` |
|
||||
| Wait for element | `mcp__chrome-devtools__wait_for({ text: ["<text>"] })` |
|
||||
| Run script | `mcp__chrome-devtools__evaluate_script({ function: "<js>" })` |
|
||||
|
||||
2. After each step, take snapshot to track DOM changes if needed
|
||||
|
||||
3. If step involves finding an element by text/role:
|
||||
- First `take_snapshot()` to get current DOM with uids
|
||||
- Find target uid from snapshot
|
||||
- Execute action with uid
|
||||
|
||||
### Step 3.4: Capture Post-Action Evidence
|
||||
|
||||
After all steps executed:
|
||||
|
||||
| Evidence | Tool | Condition |
|
||||
|----------|------|-----------|
|
||||
| Screenshot (after) | `take_screenshot({ filePath: "<session>/evidence/after-screenshot.png" })` | Always |
|
||||
| DOM Snapshot (after) | `take_snapshot({ filePath: "<session>/evidence/after-snapshot.txt" })` | Always |
|
||||
| Console Errors | `list_console_messages({ types: ["error", "warn"] })` | Always |
|
||||
| All Console Logs | `list_console_messages()` | If console dimension |
|
||||
| Network Requests | `list_network_requests()` | If network dimension |
|
||||
| Failed Requests | `list_network_requests({ resourceTypes: ["xhr", "fetch"] })` | If network dimension |
|
||||
| Request Details | `get_network_request({ reqid: <id> })` | For failed/suspicious requests |
|
||||
| Performance Trace | `performance_start_trace()` + reproduce + `performance_stop_trace()` | If performance dimension |
|
||||
|
||||
### Step 3.5: Save Evidence Summary
|
||||
|
||||
Write `<session>/evidence/evidence-summary.json`:
|
||||
```json
|
||||
{
|
||||
"reproduction_success": true,
|
||||
"target_url": "<url>",
|
||||
"steps_executed": ["step1", "step2"],
|
||||
"evidence_collected": {
|
||||
"screenshots": ["before-screenshot.png", "after-screenshot.png"],
|
||||
"snapshots": ["before-snapshot.txt", "after-snapshot.txt"],
|
||||
"console_errors": [{ "type": "error", "text": "..." }],
|
||||
"network_failures": [{ "url": "...", "status": 500, "method": "GET" }],
|
||||
"performance_trace": "trace.json"
|
||||
},
|
||||
"observations": ["Error X appeared after step 3", "Network request Y failed"]
|
||||
}
|
||||
```
|
||||
|
||||
## Phase 4: Report
|
||||
|
||||
1. Write evidence summary to session evidence/
|
||||
2. Send state_update:
|
||||
```json
|
||||
{
|
||||
"status": "task_complete",
|
||||
"task_id": "REPRODUCE-001",
|
||||
"ref": "<session>/evidence/evidence-summary.json",
|
||||
"key_findings": ["Bug reproduced successfully", "3 console errors captured", "1 failed API request"],
|
||||
"decisions": [],
|
||||
"verification": "self-validated"
|
||||
}
|
||||
```
|
||||
3. Report: reproduction result, evidence inventory, key observations
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Page fails to load | Retry once, then report navigation error |
|
||||
| Element not found | Take snapshot, search alternative selectors, report if still not found |
|
||||
| Bug not reproduced | Report with evidence of non-reproduction, suggest step refinement |
|
||||
| Browser disconnected | Report error to coordinator |
|
||||
| Timeout during wait | Capture current state, report partial reproduction |
|
||||
231
.claude/skills/team-frontend-debug/roles/tester/role.md
Normal file
231
.claude/skills/team-frontend-debug/roles/tester/role.md
Normal file
@@ -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: "<base-url><feature-url>" })
|
||||
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], 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: "<session>/evidence/F-<id>-<scenario>-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: "<session>/evidence/F-<id>-<scenario>-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 `<session>/artifacts/TEST-001-report.md`:
|
||||
|
||||
```markdown
|
||||
# Test Report
|
||||
|
||||
## Summary
|
||||
- **Features tested**: N
|
||||
- **Passed**: X
|
||||
- **Failed**: Y
|
||||
- **Warnings**: Z
|
||||
- **Test date**: <timestamp>
|
||||
- **Base URL**: <url>
|
||||
|
||||
## Results by Feature
|
||||
|
||||
### F-001: <feature-name> — PASS/FAIL/WARNING
|
||||
|
||||
**Scenarios:**
|
||||
| # | Scenario | Result | Issue |
|
||||
|---|----------|--------|-------|
|
||||
| 1 | <scenario-name> | PASS | — |
|
||||
| 2 | <scenario-name> | 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 `<session>/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": "<session>/artifacts/TEST-001-report.md",
|
||||
"key_findings": ["Tested N features", "Found X issues (Y high, Z medium)"],
|
||||
"decisions": [],
|
||||
"verification": "tested",
|
||||
"issues_ref": "<session>/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 |
|
||||
172
.claude/skills/team-frontend-debug/roles/verifier/role.md
Normal file
172
.claude/skills/team-frontend-debug/roles/verifier/role.md
Normal file
@@ -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: "<target-url>" })
|
||||
mcp__chrome-devtools__wait_for({ text: ["<expected-element>"], timeout: 10000 })
|
||||
```
|
||||
|
||||
### Step 3.3: Capture Post-Fix Evidence
|
||||
|
||||
Capture same evidence types as original reproduction:
|
||||
|
||||
| Evidence | Tool | Save To |
|
||||
|----------|------|---------|
|
||||
| Screenshot | `take_screenshot({ filePath: "<session>/evidence/verify-screenshot.png" })` | evidence/ |
|
||||
| DOM Snapshot | `take_snapshot({ filePath: "<session>/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 `<session>/artifacts/VERIFY-001-report.md`:
|
||||
|
||||
```markdown
|
||||
# Verification Report
|
||||
|
||||
## Verdict: <PASS / PASS_WITH_WARNINGS / FAIL>
|
||||
|
||||
## Bug Status
|
||||
- **Original bug**: <resolved / still present>
|
||||
- **Reproduction steps**: <all executed / partial>
|
||||
|
||||
## Evidence Comparison
|
||||
|
||||
### Console Errors
|
||||
- **Before fix**: <N errors>
|
||||
- <error 1>
|
||||
- <error 2>
|
||||
- **After fix**: <N errors>
|
||||
- <error 1 if any>
|
||||
- **Resolution**: <original errors cleared / still present>
|
||||
|
||||
### Network Requests
|
||||
- **Before fix**: <N failed requests>
|
||||
- **After fix**: <N failed requests>
|
||||
- **Resolution**: <requests now succeed / still failing>
|
||||
|
||||
### Visual Comparison
|
||||
- **Before fix**: <description or screenshot ref>
|
||||
- **After fix**: <description or screenshot ref>
|
||||
- **Resolution**: <visual bug fixed / still present>
|
||||
|
||||
## Regression Check
|
||||
- **New console errors**: <none / list>
|
||||
- **New network failures**: <none / list>
|
||||
- **Visual regressions**: <none / description>
|
||||
|
||||
## Files Verified
|
||||
- <file1.ts> — changes confirmed applied
|
||||
- <file2.tsx> — changes confirmed applied
|
||||
```
|
||||
|
||||
Send state_update:
|
||||
```json
|
||||
{
|
||||
"status": "task_complete",
|
||||
"task_id": "VERIFY-001",
|
||||
"ref": "<session>/artifacts/VERIFY-001-report.md",
|
||||
"key_findings": ["Verdict: <PASS/FAIL>", "Original bug: <resolved/present>"],
|
||||
"decisions": [],
|
||||
"verification": "tested",
|
||||
"verdict": "<pass|pass_with_warnings|fail>"
|
||||
}
|
||||
```
|
||||
|
||||
## 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 |
|
||||
215
.claude/skills/team-frontend-debug/specs/debug-tools.md
Normal file
215
.claude/skills/team-frontend-debug/specs/debug-tools.md
Normal file
@@ -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: "<uid-from-snapshot>" })
|
||||
```
|
||||
|
||||
### Fill Input
|
||||
```
|
||||
mcp__chrome-devtools__fill({ uid: "<uid>", value: "input text" })
|
||||
```
|
||||
|
||||
### Fill Multiple Fields
|
||||
```
|
||||
mcp__chrome-devtools__fill_form({
|
||||
elements: [
|
||||
{ uid: "<uid1>", value: "value1" },
|
||||
{ uid: "<uid2>", value: "value2" }
|
||||
]
|
||||
})
|
||||
```
|
||||
|
||||
### Hover Element
|
||||
```
|
||||
mcp__chrome-devtools__hover({ uid: "<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: "<session>/evidence/screenshot.png" })
|
||||
|
||||
// Full page
|
||||
mcp__chrome-devtools__take_screenshot({ filePath: "<path>", fullPage: true })
|
||||
|
||||
// Specific element
|
||||
mcp__chrome-devtools__take_screenshot({ uid: "<uid>", filePath: "<path>" })
|
||||
```
|
||||
|
||||
### 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: "<session>/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: "<path>" })
|
||||
```
|
||||
|
||||
### 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: "<session>/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: ["<uid>"]
|
||||
})
|
||||
|
||||
// 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: ["<uid>"]
|
||||
})
|
||||
```
|
||||
|
||||
## 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 |
|
||||
94
.claude/skills/team-frontend-debug/specs/pipelines.md
Normal file
94
.claude/skills/team-frontend-debug/specs/pipelines.md
Normal file
@@ -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 |
|
||||
@@ -22,11 +22,14 @@ Skill(skill="team-lifecycle-v4", args="task description")
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/role.md
|
||||
|
|
||||
+-- analyze → dispatch → spawn workers → STOP
|
||||
+-- analyze → dispatch → spawn → STOP
|
||||
|
|
||||
+-------+-------+-------+
|
||||
v v v v
|
||||
[team-worker agents, each loads roles/<role>/role.md]
|
||||
+--------+---+--------+
|
||||
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: <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-folder>
|
||||
session_id: <session-id>
|
||||
team_name: <team-name>
|
||||
requirement: <task-description>
|
||||
|
||||
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: <CHECKPOINT-NNN>
|
||||
scope: [<upstream-task-ids>]
|
||||
pipeline_progress: <done>/<total> tasks completed`,
|
||||
summary: "Checkpoint request: <CHECKPOINT-NNN>"
|
||||
})
|
||||
```
|
||||
|
||||
### 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 |
|
||||
|
||||
@@ -37,6 +37,16 @@ RoleSpec: .claude/skills/team-lifecycle-v4/roles/<role>/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)
|
||||
|
||||
@@ -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: <CHECKPOINT-NNN>\nscope: [<upstream-task-ids>]\npipeline_progress: <done>/<total> tasks completed",
|
||||
summary: "Checkpoint request: <CHECKPOINT-NNN>"
|
||||
})
|
||||
```
|
||||
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)
|
||||
|
||||
@@ -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 |
|
||||
|
||||
192
.claude/skills/team-lifecycle-v4/roles/supervisor/role.md
Normal file
192
.claude/skills/team-lifecycle-v4/roles/supervisor/role.md
Normal file
@@ -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 `<session>/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=<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 `<session>/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 `<session>/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": "<session>/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 |
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -82,3 +82,6 @@ codex-lens/.coverage
|
||||
codex-lens/*.db
|
||||
codex-lens/_*.txt
|
||||
codex-lens/.workflow/
|
||||
|
||||
# Claude skills (development only)
|
||||
.claude/skills/team-designer/
|
||||
|
||||
Reference in New Issue
Block a user