mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
62d8aa3623
- Implement tests for AssociationHighlight, DashboardToolbar, QueuePanel, SessionGroupTree, and TerminalDashboardPage to ensure proper functionality and state management. - Create tests for cliSessionStore, issueQueueIntegrationStore, queueExecutionStore, queueSchedulerStore, sessionManagerStore, and terminalGridStore to validate state resets and workspace scoping. - Mock necessary dependencies and state management hooks to isolate tests and ensure accurate behavior.
496 lines
20 KiB
Markdown
496 lines
20 KiB
Markdown
---
|
|
name: team-review
|
|
description: Multi-agent code review pipeline with scanner, reviewer, and fixer roles. Executes toolchain + LLM scan, deep analysis with root cause enrichment, and automated fixes with rollback-on-failure.
|
|
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--full|--fix|-q] [--dimensions=sec,cor,prf,mnt] \"target path or pattern\""
|
|
allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
|
---
|
|
|
|
## Auto Mode
|
|
|
|
When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults.
|
|
|
|
# Team Review
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
$team-review "src/auth/**/*.ts"
|
|
$team-review -c 2 --full "src/components"
|
|
$team-review -y --dimensions=sec,cor "src/api"
|
|
$team-review --continue "RV-auth-review-2026-03-08"
|
|
$team-review -q "src/utils"
|
|
$team-review --fix "src/auth/login.ts"
|
|
```
|
|
|
|
**Flags**:
|
|
- `-y, --yes`: Skip all confirmations (auto mode)
|
|
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
|
|
- `--continue`: Resume existing session
|
|
- `--full`: Enable scan + review + fix pipeline
|
|
- `--fix`: Fix-only mode (skip scan/review)
|
|
- `-q, --quick`: Quick scan only
|
|
- `--dimensions=sec,cor,prf,mnt`: Custom dimensions (security, correctness, performance, maintainability)
|
|
|
|
**Output Directory**: `.workflow/.csv-wave/{session-id}/`
|
|
**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Orchestrate multi-agent code review with three specialized roles: scanner (toolchain + LLM semantic scan), reviewer (deep analysis with root cause enrichment), and fixer (automated fixes with rollback-on-failure). Supports 4-dimension analysis: security (SEC), correctness (COR), performance (PRF), maintainability (MNT).
|
|
|
|
**Execution Model**: Hybrid — CSV wave pipeline (primary) + individual agent spawn (secondary)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ Team Review WORKFLOW │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Phase 0: Pre-Wave Interactive │
|
|
│ ├─ Parse arguments and detect pipeline mode │
|
|
│ ├─ Validate target path and resolve file patterns │
|
|
│ └─ Output: refined requirements for decomposition │
|
|
│ │
|
|
│ Phase 1: Requirement → CSV + Classification │
|
|
│ ├─ Generate task breakdown based on pipeline mode │
|
|
│ ├─ Create scan/review/fix tasks with dependencies │
|
|
│ ├─ Classify tasks: csv-wave (scanner, reviewer) | interactive (fixer)│
|
|
│ ├─ Compute dependency waves (topological sort → depth grouping) │
|
|
│ ├─ Generate tasks.csv with wave + exec_mode columns │
|
|
│ └─ User validates task breakdown (skip if -y) │
|
|
│ │
|
|
│ Phase 2: Wave Execution Engine (Extended) │
|
|
│ ├─ For each wave (1..N): │
|
|
│ │ ├─ Execute pre-wave interactive tasks (if any) │
|
|
│ │ ├─ Build wave CSV (filter csv-wave tasks for this wave) │
|
|
│ │ ├─ Inject previous findings into prev_context column │
|
|
│ │ ├─ spawn_agents_on_csv(wave CSV) │
|
|
│ │ ├─ Execute post-wave interactive tasks (if any) │
|
|
│ │ ├─ Merge all results into master tasks.csv │
|
|
│ │ └─ Check: any failed? → skip dependents │
|
|
│ └─ discoveries.ndjson shared across all modes (append-only) │
|
|
│ │
|
|
│ Phase 3: Post-Wave Interactive │
|
|
│ ├─ Generate final review report and fix summary │
|
|
│ └─ Final aggregation / report │
|
|
│ │
|
|
│ Phase 4: Results Aggregation │
|
|
│ ├─ Export final results.csv │
|
|
│ ├─ Generate context.md with all findings │
|
|
│ ├─ Display summary: completed/failed/skipped per wave │
|
|
│ └─ Offer: view results | retry failed | done │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Task Classification Rules
|
|
|
|
Each task is classified by `exec_mode`:
|
|
|
|
| exec_mode | Mechanism | Criteria |
|
|
|-----------|-----------|----------|
|
|
| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction |
|
|
| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, clarification, inline utility |
|
|
|
|
**Classification Decision**:
|
|
|
|
| Task Property | Classification |
|
|
|---------------|---------------|
|
|
| Scanner task (toolchain + LLM scan) | `csv-wave` |
|
|
| Reviewer task (deep analysis) | `csv-wave` |
|
|
| Fixer task (code modification with rollback) | `interactive` |
|
|
|
|
---
|
|
|
|
## CSV Schema
|
|
|
|
### tasks.csv (Master State)
|
|
|
|
```csv
|
|
id,title,description,deps,context_from,exec_mode,dimension,target,wave,status,findings,error
|
|
1,Scan codebase,Run toolchain + LLM scan on target files,,,"csv-wave","sec,cor,prf,mnt","src/**/*.ts",1,pending,"",""
|
|
2,Review findings,Deep analysis with root cause enrichment,1,1,"csv-wave","sec,cor,prf,mnt","scan-results.json",2,pending,"",""
|
|
3,Fix issues,Apply fixes with rollback-on-failure,2,2,"interactive","","review-report.json",3,pending,"",""
|
|
```
|
|
|
|
**Columns**:
|
|
|
|
| Column | Phase | Description |
|
|
|--------|-------|-------------|
|
|
| `id` | Input | Unique task identifier (string) |
|
|
| `title` | Input | Short task title |
|
|
| `description` | Input | Detailed task description |
|
|
| `deps` | Input | Semicolon-separated dependency task IDs |
|
|
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
|
|
| `exec_mode` | Input | `csv-wave` or `interactive` |
|
|
| `dimension` | Input | Review dimensions (sec,cor,prf,mnt) |
|
|
| `target` | Input | Target path or pattern |
|
|
| `wave` | Computed | Wave number (computed by topological sort, 1-based) |
|
|
| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
|
|
| `findings` | Output | Key discoveries or implementation notes (max 500 chars) |
|
|
| `error` | Output | Error message if failed (empty if success) |
|
|
|
|
### Per-Wave CSV (Temporary)
|
|
|
|
Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only).
|
|
|
|
---
|
|
|
|
## Agent Registry (Interactive Agents)
|
|
|
|
| Agent | Role File | Pattern | Responsibility | Position |
|
|
|-------|-----------|---------|----------------|----------|
|
|
| fixer | agents/fixer.md | 2.3 | Apply fixes with rollback-on-failure | post-wave |
|
|
|
|
> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload.
|
|
|
|
---
|
|
|
|
## Output Artifacts
|
|
|
|
| File | Purpose | Lifecycle |
|
|
|------|---------|-----------|
|
|
| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
|
|
| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after |
|
|
| `results.csv` | Final export of all task results | Created in Phase 4 |
|
|
| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves |
|
|
| `context.md` | Human-readable execution report | Created in Phase 4 |
|
|
| `interactive/fixer-result.json` | Results from fixer task | Created per interactive task |
|
|
| `agents/registry.json` | Active interactive agent tracking | Updated on spawn/close |
|
|
|
|
---
|
|
|
|
## Session Structure
|
|
|
|
```
|
|
.workflow/.csv-wave/{session-id}/
|
|
├── tasks.csv # Master state (all tasks, both modes)
|
|
├── results.csv # Final results export
|
|
├── discoveries.ndjson # Shared discovery board (all agents)
|
|
├── context.md # Human-readable report
|
|
├── wave-{N}.csv # Temporary per-wave input (csv-wave only)
|
|
├── interactive/ # Interactive task artifacts
|
|
│ ├── fixer-result.json # Per-task results
|
|
│ └── cache-index.json # Shared exploration cache
|
|
└── agents/
|
|
└── registry.json # Active interactive agent tracking
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation
|
|
|
|
### Session Initialization
|
|
|
|
```javascript
|
|
// Parse arguments
|
|
const args = parseArguments($ARGUMENTS)
|
|
const AUTO_YES = args.yes || args.y || false
|
|
const CONCURRENCY = args.concurrency || args.c || 3
|
|
const CONTINUE_SESSION = args.continue || null
|
|
const MODE = args.full ? 'full' : args.fix ? 'fix-only' : args.quick || args.q ? 'quick' : 'default'
|
|
const DIMENSIONS = args.dimensions || 'sec,cor,prf,mnt'
|
|
const TARGET = args._[0] || null
|
|
|
|
// Generate session ID
|
|
const sessionId = `RV-${slugify(TARGET || 'review')}-${formatDate(new Date(), 'yyyy-MM-dd')}`
|
|
const sessionDir = `.workflow/.csv-wave/${sessionId}`
|
|
|
|
// Create session structure
|
|
Bash({ command: `mkdir -p "${sessionDir}/interactive" "${sessionDir}/agents"` })
|
|
Write(`${sessionDir}/discoveries.ndjson`, '')
|
|
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({ active: [], closed: [] }))
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 0: Pre-Wave Interactive
|
|
|
|
**Objective**: Parse arguments, validate target, detect pipeline mode
|
|
|
|
**Execution**:
|
|
|
|
1. Parse command-line arguments for mode flags (--full, --fix, -q)
|
|
2. Extract target path/pattern from arguments
|
|
3. Validate target exists and resolve to file list
|
|
4. Detect pipeline mode based on flags
|
|
5. Store configuration in session metadata
|
|
|
|
**Success Criteria**:
|
|
- Refined requirements available for Phase 1 decomposition
|
|
- Interactive agents closed, results stored
|
|
|
|
---
|
|
|
|
### Phase 1: Requirement → CSV + Classification
|
|
|
|
**Objective**: Generate task breakdown based on pipeline mode and create master CSV
|
|
|
|
**Decomposition Rules**:
|
|
|
|
| Mode | Tasks Generated |
|
|
|------|----------------|
|
|
| quick | SCAN-001 (quick scan only) |
|
|
| default | SCAN-001 → REV-001 |
|
|
| full | SCAN-001 → REV-001 → FIX-001 |
|
|
| fix-only | FIX-001 (requires existing review report) |
|
|
|
|
**Classification Rules**:
|
|
|
|
- Scanner tasks: `exec_mode=csv-wave` (one-shot toolchain + LLM scan)
|
|
- Reviewer tasks: `exec_mode=csv-wave` (one-shot deep analysis)
|
|
- Fixer tasks: `exec_mode=interactive` (multi-round with rollback)
|
|
|
|
**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only).
|
|
|
|
**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES).
|
|
|
|
**Success Criteria**:
|
|
- tasks.csv created with valid schema, wave, and exec_mode assignments
|
|
- No circular dependencies
|
|
- User approved (or AUTO_YES)
|
|
|
|
---
|
|
|
|
### Phase 2: Wave Execution Engine (Extended)
|
|
|
|
**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation.
|
|
|
|
```javascript
|
|
// Load master CSV
|
|
const masterCSV = readCSV(`${sessionDir}/tasks.csv`)
|
|
const maxWave = Math.max(...masterCSV.map(t => t.wave))
|
|
|
|
for (let wave = 1; wave <= maxWave; wave++) {
|
|
// Execute pre-wave interactive tasks
|
|
const preWaveTasks = masterCSV.filter(t =>
|
|
t.wave === wave && t.exec_mode === 'interactive' && t.position === 'pre-wave'
|
|
)
|
|
for (const task of preWaveTasks) {
|
|
const agent = spawn_agent({
|
|
message: buildInteractivePrompt(task, sessionDir)
|
|
})
|
|
const result = wait({ ids: [agent], timeout_ms: 600000 })
|
|
close_agent({ id: agent })
|
|
updateTaskStatus(task.id, result)
|
|
}
|
|
|
|
// Build wave CSV (csv-wave tasks only)
|
|
const waveTasks = masterCSV.filter(t => t.wave === wave && t.exec_mode === 'csv-wave')
|
|
if (waveTasks.length > 0) {
|
|
// Inject prev_context from context_from tasks
|
|
for (const task of waveTasks) {
|
|
if (task.context_from) {
|
|
const contextIds = task.context_from.split(';')
|
|
const contextFindings = masterCSV
|
|
.filter(t => contextIds.includes(t.id))
|
|
.map(t => `[Task ${t.id}] ${t.findings}`)
|
|
.join('\n\n')
|
|
task.prev_context = contextFindings
|
|
}
|
|
}
|
|
|
|
// Write wave CSV
|
|
writeCSV(`${sessionDir}/wave-${wave}.csv`, waveTasks)
|
|
|
|
// Execute wave
|
|
spawn_agents_on_csv({
|
|
csv_path: `${sessionDir}/wave-${wave}.csv`,
|
|
instruction_path: `${sessionDir}/instructions/agent-instruction.md`,
|
|
concurrency: CONCURRENCY
|
|
})
|
|
|
|
// Merge results back to master
|
|
const waveResults = readCSV(`${sessionDir}/wave-${wave}.csv`)
|
|
for (const result of waveResults) {
|
|
const masterTask = masterCSV.find(t => t.id === result.id)
|
|
Object.assign(masterTask, result)
|
|
}
|
|
writeCSV(`${sessionDir}/tasks.csv`, masterCSV)
|
|
|
|
// Cleanup wave CSV
|
|
Bash({ command: `rm "${sessionDir}/wave-${wave}.csv"` })
|
|
}
|
|
|
|
// Execute post-wave interactive tasks
|
|
const postWaveTasks = masterCSV.filter(t =>
|
|
t.wave === wave && t.exec_mode === 'interactive' && t.position === 'post-wave'
|
|
)
|
|
for (const task of postWaveTasks) {
|
|
const agent = spawn_agent({
|
|
message: buildInteractivePrompt(task, sessionDir)
|
|
})
|
|
const result = wait({ ids: [agent], timeout_ms: 600000 })
|
|
close_agent({ id: agent })
|
|
updateTaskStatus(task.id, result)
|
|
}
|
|
|
|
// Check for failures and skip dependents
|
|
const failedTasks = masterCSV.filter(t => t.wave === wave && t.status === 'failed')
|
|
if (failedTasks.length > 0) {
|
|
skipDependents(masterCSV, failedTasks)
|
|
}
|
|
}
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- All waves executed in order
|
|
- Both csv-wave and interactive tasks handled per wave
|
|
- Each wave's results merged into master CSV before next wave starts
|
|
- Dependent tasks skipped when predecessor failed
|
|
- discoveries.ndjson accumulated across all waves and mechanisms
|
|
- Interactive agent lifecycle tracked in registry.json
|
|
|
|
---
|
|
|
|
### Phase 3: Post-Wave Interactive
|
|
|
|
**Objective**: Generate final review report and fix summary
|
|
|
|
**Execution**:
|
|
|
|
1. Aggregate all findings from scan and review tasks
|
|
2. Generate comprehensive review report with metrics
|
|
3. If fixer ran, generate fix summary with success/failure rates
|
|
4. Write final reports to session directory
|
|
|
|
**Success Criteria**:
|
|
- Post-wave interactive processing complete
|
|
- Interactive agents closed, results stored
|
|
|
|
---
|
|
|
|
### Phase 4: Results Aggregation
|
|
|
|
**Objective**: Generate final results and human-readable report.
|
|
|
|
```javascript
|
|
// Export results.csv
|
|
const masterCSV = readCSV(`${sessionDir}/tasks.csv`)
|
|
writeCSV(`${sessionDir}/results.csv`, masterCSV)
|
|
|
|
// Generate context.md
|
|
const contextMd = generateContextReport(masterCSV, sessionDir)
|
|
Write(`${sessionDir}/context.md`, contextMd)
|
|
|
|
// Cleanup interactive agents
|
|
const registry = JSON.parse(Read(`${sessionDir}/agents/registry.json`))
|
|
for (const agent of registry.active) {
|
|
close_agent({ id: agent.id })
|
|
}
|
|
Write(`${sessionDir}/agents/registry.json`, JSON.stringify({ active: [], closed: registry.closed }))
|
|
|
|
// Display summary
|
|
const summary = {
|
|
total: masterCSV.length,
|
|
completed: masterCSV.filter(t => t.status === 'completed').length,
|
|
failed: masterCSV.filter(t => t.status === 'failed').length,
|
|
skipped: masterCSV.filter(t => t.status === 'skipped').length
|
|
}
|
|
console.log(`Pipeline complete: ${summary.completed}/${summary.total} tasks completed`)
|
|
```
|
|
|
|
**Success Criteria**:
|
|
- results.csv exported (all tasks, both modes)
|
|
- context.md generated
|
|
- All interactive agents closed (registry.json cleanup)
|
|
- Summary displayed to user
|
|
|
|
---
|
|
|
|
## Shared Discovery Board Protocol
|
|
|
|
**Discovery Types**:
|
|
|
|
| Type | Dedup Key | Data Schema | Description |
|
|
|------|-----------|-------------|-------------|
|
|
| `finding` | `file+line+dimension` | `{dimension, file, line, severity, title}` | Code issue discovered by scanner |
|
|
| `root_cause` | `finding_id` | `{finding_id, description, related_findings[]}` | Root cause analysis from reviewer |
|
|
| `fix_applied` | `file+line` | `{file, line, fix_strategy, status}` | Fix application result from fixer |
|
|
| `pattern` | `pattern_name` | `{pattern, files[], occurrences}` | Code pattern identified across files |
|
|
|
|
**Discovery NDJSON Format**:
|
|
|
|
```jsonl
|
|
{"ts":"2026-03-08T14:30:22Z","worker":"1","type":"finding","data":{"dimension":"sec","file":"src/auth.ts","line":42,"severity":"high","title":"SQL injection vulnerability"}}
|
|
{"ts":"2026-03-08T14:35:10Z","worker":"2","type":"root_cause","data":{"finding_id":"SEC-001","description":"Unsanitized user input in query","related_findings":["SEC-002"]}}
|
|
{"ts":"2026-03-08T14:40:05Z","worker":"3","type":"fix_applied","data":{"file":"src/auth.ts","line":42,"fix_strategy":"minimal","status":"fixed"}}
|
|
```
|
|
|
|
> Both csv-wave and interactive agents read/write the same discoveries.ndjson file.
|
|
|
|
---
|
|
|
|
## Cross-Mechanism Context Bridging
|
|
|
|
### Interactive Result → CSV Task
|
|
|
|
When a pre-wave interactive task produces results needed by csv-wave tasks:
|
|
|
|
```javascript
|
|
// 1. Interactive result stored in file
|
|
const resultFile = `${sessionDir}/interactive/${taskId}-result.json`
|
|
|
|
// 2. Wave engine reads when building prev_context for csv-wave tasks
|
|
// If a csv-wave task has context_from referencing an interactive task:
|
|
// Read the interactive result file and include in prev_context
|
|
```
|
|
|
|
### CSV Result → Interactive Task
|
|
|
|
When a post-wave interactive task needs CSV wave results:
|
|
|
|
```javascript
|
|
// Option A: Include in spawn message
|
|
const csvFindings = readMasterCSV().filter(t => t.wave === currentWave && t.exec_mode === 'csv-wave')
|
|
const context = csvFindings.map(t => `## Task ${t.id}: ${t.title}\n${t.findings}`).join('\n\n')
|
|
|
|
spawn_agent({
|
|
message: `...\n### Wave ${currentWave} Results\n${context}\n...`
|
|
})
|
|
|
|
// Option B: Inject via send_input (if agent already running)
|
|
send_input({
|
|
id: activeAgent,
|
|
message: `## Wave ${currentWave} Results\n${context}\n\nProceed with analysis.`
|
|
})
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling
|
|
|
|
| Error | Resolution |
|
|
|-------|------------|
|
|
| Circular dependency | Detect in wave computation, abort with error message |
|
|
| CSV agent timeout | Mark as failed in results, continue with wave |
|
|
| CSV agent failed | Mark as failed, skip dependent tasks in later waves |
|
|
| Interactive agent timeout | Urge convergence via send_input, then close if still timed out |
|
|
| Interactive agent failed | Mark as failed, skip dependents |
|
|
| Pre-wave interactive failed | Skip dependent csv-wave tasks in same wave |
|
|
| All agents in wave failed | Log error, offer retry or abort |
|
|
| CSV parse error | Validate CSV format before execution, show line number |
|
|
| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
|
|
| Lifecycle leak | Cleanup all active agents via registry.json at end |
|
|
| Continue mode: no session found | List available sessions, prompt user to select |
|
|
| Target path invalid | AskUserQuestion for corrected path |
|
|
| Scanner finds 0 findings | Report clean, skip review + fix stages |
|
|
|
|
---
|
|
|
|
## Core Rules
|
|
|
|
1. **Start Immediately**: First action is session initialization, then Phase 0/1
|
|
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
|
|
3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive)
|
|
4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it
|
|
5. **Context Propagation**: prev_context built from master CSV, not from memory
|
|
6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson — both mechanisms share it
|
|
7. **Skip on Failure**: If a dependency failed, skip the dependent task (regardless of mechanism)
|
|
8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent (tracked in registry.json)
|
|
9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
|
|
10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
|