mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
@@ -1,238 +1,72 @@
|
||||
---
|
||||
name: team-review
|
||||
description: "Unified team skill for code review. Uses team-worker agent architecture with role-spec files. 3-role pipeline: scanner, reviewer, fixer. Triggers on team-review."
|
||||
description: Unified team skill for code review. 3-role pipeline: scanner, reviewer, fixer. Triggers on "team-review".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*)
|
||||
---
|
||||
|
||||
# Team Review
|
||||
|
||||
Unified team skill: code scanning, vulnerability review, optimization suggestions, and automated fix. All team members invoke with `--role=xxx` to route to role-specific execution.
|
||||
Orchestrate multi-agent code review: scanner -> reviewer -> fixer. Toolchain + LLM scan, deep analysis with root cause enrichment, and automated fix with rollback-on-failure.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
+---------------------------------------------------+
|
||||
| Skill(skill="team-review") |
|
||||
| args="<task-description>" |
|
||||
+-------------------+-------------------------------+
|
||||
Skill(skill="team-review", args="task description")
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
SKILL.md (this file) = Router
|
||||
|
|
||||
Coordinator (inline)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+
|
||||
v v v
|
||||
[tw] [tw] [tw]
|
||||
scann- review- fixer
|
||||
er er
|
||||
|
||||
(tw) = team-worker agent
|
||||
+--------------+--------------+
|
||||
| |
|
||||
no --role flag --role <name>
|
||||
| |
|
||||
Coordinator Worker
|
||||
roles/coordinator/role.md roles/<name>/role.md
|
||||
|
|
||||
+-- analyze -> dispatch -> spawn workers -> STOP
|
||||
|
|
||||
+-------+-------+-------+
|
||||
v v v
|
||||
[scan] [review] [fix]
|
||||
team-worker agents, each loads roles/<role>/role.md
|
||||
```
|
||||
|
||||
## Role Registry
|
||||
|
||||
| Role | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| scanner | [roles/scanner/role.md](roles/scanner/role.md) | SCAN-* | false |
|
||||
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REV-* | false |
|
||||
| fixer | [roles/fixer/role.md](roles/fixer/role.md) | FIX-* | true |
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` -> Read `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator).
|
||||
## Shared Constants
|
||||
|
||||
### Role Registry
|
||||
- **Session prefix**: `RV`
|
||||
- **Session path**: `.workflow/.team/RV-<slug>-<date>/`
|
||||
- **Team name**: `review`
|
||||
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
|
||||
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
|
||||
|
||||
| Role | Spec | Task Prefix | Inner Loop |
|
||||
|------|------|-------------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
|
||||
| scanner | [role-specs/scanner.md](role-specs/scanner.md) | SCAN-* | false |
|
||||
| reviewer | [role-specs/reviewer.md](role-specs/reviewer.md) | REV-* | false |
|
||||
| fixer | [role-specs/fixer.md](role-specs/fixer.md) | FIX-* | true |
|
||||
## Worker Spawn Template
|
||||
|
||||
> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。
|
||||
|
||||
### Dispatch
|
||||
|
||||
1. Extract `--role` from arguments
|
||||
2. If no `--role` → route to coordinator (Orchestration Mode)
|
||||
3. Look up role in registry → Read the role file → Execute its phases
|
||||
|
||||
### Orchestration Mode
|
||||
|
||||
When invoked without `--role`, coordinator auto-starts. User just provides target description.
|
||||
|
||||
**Invocation**: `Skill(skill="team-review", args="<target-path>")`
|
||||
|
||||
**Lifecycle**:
|
||||
```
|
||||
User provides scan target
|
||||
→ coordinator Phase 1-3: Parse flags → TeamCreate → Create task chain
|
||||
→ coordinator Phase 4: spawn first batch workers (background) → STOP
|
||||
→ Worker executes → SendMessage callback → coordinator advances next step
|
||||
→ Loop until pipeline complete → Phase 5 report
|
||||
```
|
||||
|
||||
**User Commands** (wake paused coordinator):
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status graph, no advancement |
|
||||
| `resume` / `continue` | Check worker states, advance next step |
|
||||
|
||||
---
|
||||
|
||||
## Pipeline (CP-1 Linear)
|
||||
|
||||
```
|
||||
coordinator dispatch
|
||||
→ SCAN-* (scanner: toolchain + LLM scan)
|
||||
→ REV-* (reviewer: deep analysis + report)
|
||||
→ [user confirm]
|
||||
→ FIX-* (fixer: plan + execute + verify)
|
||||
```
|
||||
|
||||
### Cadence Control
|
||||
|
||||
**Beat model**: Event-driven, each beat = coordinator wake → process → spawn → STOP.
|
||||
|
||||
```
|
||||
Beat Cycle (single beat)
|
||||
═══════════════════════════════════════════════════════════
|
||||
Event Coordinator Workers
|
||||
───────────────────────────────────────────────────────────
|
||||
callback/resume ──→ ┌─ handleCallback ─┐
|
||||
│ mark completed │
|
||||
│ check pipeline │
|
||||
├─ handleSpawnNext ─┤
|
||||
│ find ready tasks │
|
||||
│ spawn workers ───┼──→ [Worker A] Phase 1-5
|
||||
└─ STOP (idle) ─────┘ │
|
||||
│
|
||||
callback ←─────────────────────────────────────────┘
|
||||
(next beat) SendMessage + TaskUpdate(completed)
|
||||
═══════════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
**Pipeline beat view**:
|
||||
|
||||
```
|
||||
Review Pipeline (3 beats, linear with user checkpoint)
|
||||
──────────────────────────────────────────────────────────
|
||||
Beat 1 2 ⏸ 3
|
||||
│ │ │ │
|
||||
SCAN → REV ──→ [confirm] → FIX
|
||||
▲ ▲
|
||||
pipeline pipeline
|
||||
start done
|
||||
|
||||
SCAN=scanner REV=reviewer FIX=fixer
|
||||
```
|
||||
|
||||
**Checkpoints**:
|
||||
|
||||
| Trigger | Location | Behavior |
|
||||
|---------|----------|----------|
|
||||
| Review→Fix transition | REV-* complete | Pause, present review report, wait for user `resume` to confirm fix |
|
||||
| Quick mode (`-q`) | After SCAN-* | Pipeline ends after scan, no review/fix |
|
||||
| Fix-only mode (`--fix`) | Entry | Skip scan/review, go directly to fixer |
|
||||
|
||||
**Stall Detection** (coordinator `handleCheck` executes):
|
||||
|
||||
| Check | Condition | Resolution |
|
||||
|-------|-----------|------------|
|
||||
| Worker no response | in_progress task no callback | Report waiting task list, suggest user `resume` |
|
||||
| Pipeline deadlock | no ready + no running + has pending | Check blockedBy dependency chain, report blocking point |
|
||||
|
||||
### Task Metadata Registry
|
||||
|
||||
| Task ID | Role | Phase | Dependencies | Description |
|
||||
|---------|------|-------|-------------|-------------|
|
||||
| SCAN-001 | scanner | scan | (none) | Toolchain + LLM code scanning |
|
||||
| REV-001 | reviewer | review | SCAN-001 | Deep analysis and review report |
|
||||
| FIX-001 | fixer | fix | REV-001 + user confirm | Plan + execute + verify fixes |
|
||||
|
||||
---
|
||||
|
||||
## Shared Infrastructure
|
||||
|
||||
### Worker Phase 1: Task Discovery (shared by all workers)
|
||||
|
||||
Every worker executes the same task discovery flow on startup:
|
||||
|
||||
1. Call `TaskList()` to get all tasks
|
||||
2. Filter: subject matches this role's prefix + owner is this role + status is pending + blockedBy is empty
|
||||
3. No tasks → idle wait
|
||||
4. Has tasks → `TaskGet` for details → `TaskUpdate` mark in_progress
|
||||
|
||||
**Resume Artifact Check** (prevent duplicate output after resume):
|
||||
- Check whether this task's output artifact already exists
|
||||
- Artifact complete → skip to Phase 5 report completion
|
||||
- Artifact incomplete or missing → normal Phase 2-4 execution
|
||||
|
||||
### Worker Phase 5: Report (shared by all workers)
|
||||
|
||||
Standard reporting flow after task completion:
|
||||
|
||||
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
|
||||
- Parameters: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
|
||||
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
|
||||
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
|
||||
2. **SendMessage**: Send result to coordinator
|
||||
3. **TaskUpdate**: Mark task completed
|
||||
4. **Loop**: Return to Phase 1 to check next task
|
||||
|
||||
### Wisdom Accumulation (all roles)
|
||||
|
||||
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory at session initialization.
|
||||
|
||||
**Directory**:
|
||||
```
|
||||
<session-folder>/wisdom/
|
||||
├── learnings.md # Patterns and insights
|
||||
├── decisions.md # Architecture and design decisions
|
||||
├── conventions.md # Codebase conventions
|
||||
└── issues.md # Known risks and issues
|
||||
```
|
||||
|
||||
**Worker Load** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
|
||||
**Worker Contribute** (Phase 4/5): Write this task's discoveries to corresponding wisdom files.
|
||||
|
||||
### Role Isolation Rules
|
||||
|
||||
| Allowed | Forbidden |
|
||||
|---------|-----------|
|
||||
| Process tasks with own prefix | Process tasks with other role prefixes |
|
||||
| SendMessage to coordinator | Communicate directly with other workers |
|
||||
| Use tools declared in Toolbox | Create tasks for other roles |
|
||||
| Delegate to commands/ files | Modify resources outside own responsibility |
|
||||
|
||||
Coordinator additional restrictions: Do not write/modify code directly, do not call implementation CLI tools, do not execute analysis/test/review directly.
|
||||
|
||||
### Team Configuration
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Team name | review |
|
||||
| Session directory | `.workflow/.team/RV-<slug>-<date>/` |
|
||||
| Shared memory | `.msg/meta.json` in session dir |
|
||||
| Team config | `specs/team-config.json` |
|
||||
| Finding schema | `specs/finding-schema.json` |
|
||||
| Dimensions | `specs/dimensions.md` |
|
||||
|
||||
---
|
||||
|
||||
## Coordinator Spawn Template
|
||||
|
||||
### v5 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path:
|
||||
Coordinator spawns workers using this template:
|
||||
|
||||
```
|
||||
Agent({
|
||||
agent_type: "team-worker",
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker",
|
||||
team_name: "review",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-review/role-specs/<role>.md
|
||||
role_spec: .claude/skills/team-review/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: review
|
||||
@@ -240,41 +74,25 @@ 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-spec Phase 2-4 -> built-in Phase 5 (report).`
|
||||
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
**Inner Loop roles** (fixer): Set `inner_loop: true`.
|
||||
## User Commands
|
||||
|
||||
**Single-task roles** (scanner, reviewer): Set `inner_loop: false`.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Via coordinator (auto pipeline)
|
||||
Skill(skill="team-review", args="src/auth/**") # scan + review
|
||||
Skill(skill="team-review", args="--full src/auth/**") # scan + review + fix
|
||||
Skill(skill="team-review", args="--fix .review/review-*.json") # fix only
|
||||
Skill(skill="team-review", args="-q src/auth/**") # quick scan only
|
||||
|
||||
# Direct role invocation
|
||||
Skill(skill="team-review", args="--role=scanner src/auth/**")
|
||||
Skill(skill="team-review", args="--role=reviewer --input scan-result.json")
|
||||
Skill(skill="team-review", args="--role=fixer --input fix-manifest.json")
|
||||
|
||||
# Flags (all modes)
|
||||
--dimensions=sec,cor,perf,maint # custom dimensions (default: all 4)
|
||||
-y / --yes # skip confirmations
|
||||
-q / --quick # quick scan mode
|
||||
--full # full pipeline (scan → review → fix)
|
||||
--fix # fix mode only
|
||||
```
|
||||
|
||||
---
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | View pipeline status graph |
|
||||
| `resume` / `continue` | Advance to next step |
|
||||
| `--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 |
|
||||
| `-y` / `--yes` | Skip confirmations |
|
||||
|
||||
## Completion Action
|
||||
|
||||
When the pipeline completes (all tasks done, coordinator Phase 5):
|
||||
When pipeline completes, coordinator presents:
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
@@ -283,56 +101,41 @@ AskUserQuestion({
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
|
||||
{ label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
|
||||
{ label: "Export Results", description: "Export deliverables to a specified location, then clean" }
|
||||
{ label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
|
||||
{ label: "Keep Active", description: "Keep session for follow-up work" },
|
||||
{ label: "Export Results", description: "Export deliverables to target directory" }
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
| Choice | Action |
|
||||
|--------|--------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-review", args="resume")` |
|
||||
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
|
||||
|
||||
---
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/RV-<slug>-<YYYY-MM-DD>/
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl # Message bus log
|
||||
│ └── meta.json # Session state + cross-role state
|
||||
├── wisdom/ # Cross-task knowledge
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── scan/ # Scanner output
|
||||
│ └── scan-results.json
|
||||
├── review/ # Reviewer output
|
||||
│ └── review-report.json
|
||||
└── fix/ # Fixer output
|
||||
└── fix-manifest.json
|
||||
.workflow/.team/RV-<slug>-<date>/
|
||||
├── .msg/messages.jsonl # Team message bus
|
||||
├── .msg/meta.json # Session state + cross-role state
|
||||
├── wisdom/ # Cross-task knowledge
|
||||
├── scan/ # Scanner output
|
||||
├── review/ # Reviewer output
|
||||
└── fix/ # Fixer output
|
||||
```
|
||||
|
||||
## Specs Reference
|
||||
|
||||
- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
|
||||
- [specs/dimensions.md](specs/dimensions.md) — Review dimension definitions (SEC/COR/PRF/MNT)
|
||||
- [specs/finding-schema.json](specs/finding-schema.json) — Finding data schema
|
||||
- [specs/team-config.json](specs/team-config.json) — Team configuration
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown --role value | Error with available role list |
|
||||
| Missing --role arg | Orchestration Mode → auto route to coordinator |
|
||||
| Role file not found | Error with expected file path (roles/<name>/role.md) |
|
||||
| Invalid flags | Warn and continue with defaults |
|
||||
| No target specified (no --role) | AskUserQuestion to clarify |
|
||||
|
||||
## Execution Rules
|
||||
|
||||
1. **Parse first**: Extract --role and flags from $ARGUMENTS before anything else
|
||||
2. **Progressive loading**: Read ONLY the matched role.md, not all four
|
||||
3. **Full delegation**: Role.md owns entire execution -- do not add logic here
|
||||
4. **Self-contained**: Each role.md includes its own message bus, task lifecycle, toolbox
|
||||
5. **DO NOT STOP**: Continuous execution until role completes all 5 phases
|
||||
| Role not found | Error with expected path (roles/<name>/role.md) |
|
||||
| CLI tool fails | Worker fallback to direct implementation |
|
||||
| Scanner finds 0 findings | Report clean, skip review + fix |
|
||||
| User declines fix | Delete FIX tasks, complete with review-only results |
|
||||
| Fast-advance conflict | Coordinator reconciles on next callback |
|
||||
| Completion action fails | Default to Keep Active |
|
||||
|
||||
@@ -0,0 +1,71 @@
|
||||
# Analyze Task
|
||||
|
||||
Parse user task -> detect review capabilities -> build dependency graph -> design pipeline.
|
||||
|
||||
**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
|
||||
|
||||
## Signal Detection
|
||||
|
||||
| Keywords | Capability | Prefix |
|
||||
|----------|------------|--------|
|
||||
| scan, lint, static analysis, toolchain | scanner | SCAN |
|
||||
| review, analyze, audit, findings | reviewer | REV |
|
||||
| fix, repair, remediate, patch | fixer | FIX |
|
||||
|
||||
## Pipeline Mode Detection
|
||||
|
||||
| Condition | Mode |
|
||||
|-----------|------|
|
||||
| Flag `--fix` | fix-only |
|
||||
| Flag `--full` | full |
|
||||
| Flag `-q` or `--quick` | quick |
|
||||
| (none) | default |
|
||||
|
||||
## Dependency Graph
|
||||
|
||||
Natural ordering for review pipeline:
|
||||
- Tier 0: scanner (toolchain + semantic scan, no upstream dependency)
|
||||
- Tier 1: reviewer (deep analysis, requires scan findings)
|
||||
- Tier 2: fixer (apply fixes, requires reviewed findings + user confirm)
|
||||
|
||||
## Pipeline Definitions
|
||||
|
||||
```
|
||||
quick: SCAN(quick=true)
|
||||
default: SCAN -> REV
|
||||
full: SCAN -> REV -> [user confirm] -> FIX
|
||||
fix-only: FIX
|
||||
```
|
||||
|
||||
## Complexity Scoring
|
||||
|
||||
| Factor | Points |
|
||||
|--------|--------|
|
||||
| Per capability | +1 |
|
||||
| Large target scope (>20 files) | +2 |
|
||||
| Multiple dimensions | +1 |
|
||||
| Fix phase included | +1 |
|
||||
|
||||
Results: 1-2 Low, 3-4 Medium, 5+ High
|
||||
|
||||
## Role Minimization
|
||||
|
||||
- Cap at 4 roles (coordinator + 3 workers)
|
||||
- Sequential pipeline: scanner -> reviewer -> fixer
|
||||
|
||||
## Output
|
||||
|
||||
Write <session>/task-analysis.json:
|
||||
```json
|
||||
{
|
||||
"task_description": "<original>",
|
||||
"pipeline_mode": "<quick|default|full|fix-only>",
|
||||
"target": "<path>",
|
||||
"dimensions": ["sec", "cor", "prf", "mnt"],
|
||||
"auto_confirm": false,
|
||||
"capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>" }],
|
||||
"dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."] } },
|
||||
"roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
|
||||
"complexity": { "score": 0, "level": "Low|Medium|High" }
|
||||
}
|
||||
```
|
||||
@@ -1,143 +1,91 @@
|
||||
# Command: dispatch
|
||||
# Dispatch Tasks
|
||||
|
||||
> Task chain creation based on pipeline mode. Creates SCAN/REV/FIX tasks with dependencies.
|
||||
Create task chains from pipeline mode with proper blockedBy relationships.
|
||||
|
||||
## When to Use
|
||||
## Workflow
|
||||
|
||||
- Phase 3 of Coordinator
|
||||
- Pipeline mode detected, need to create task chain
|
||||
- Session initialized
|
||||
1. Read task-analysis.json -> extract pipeline_mode and parameters
|
||||
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 session meta.json with pipeline.tasks_total
|
||||
7. Validate chain (no orphans, no cycles, all refs valid)
|
||||
|
||||
**Trigger conditions**:
|
||||
- Coordinator Phase 2 complete
|
||||
- Mode switch requires chain rebuild
|
||||
## Task Description Template
|
||||
|
||||
## Strategy
|
||||
|
||||
### Delegation Mode
|
||||
|
||||
**Mode**: Direct (coordinator operates TaskCreate/TaskUpdate directly)
|
||||
|
||||
### Decision Logic
|
||||
|
||||
```javascript
|
||||
// Build pipeline based on mode
|
||||
function buildPipeline(pipelineMode) {
|
||||
const pipelines = {
|
||||
'default': [
|
||||
{ prefix: 'SCAN', suffix: '001', owner: 'scanner', desc: 'Multi-dimension code scan', blockedBy: [], meta: {} },
|
||||
{ prefix: 'REV', suffix: '001', owner: 'reviewer', desc: 'Deep finding analysis and review', blockedBy: ['SCAN-001'], meta: {} }
|
||||
],
|
||||
'full': [
|
||||
{ prefix: 'SCAN', suffix: '001', owner: 'scanner', desc: 'Multi-dimension code scan', blockedBy: [], meta: {} },
|
||||
{ prefix: 'REV', suffix: '001', owner: 'reviewer', desc: 'Deep finding analysis and review', blockedBy: ['SCAN-001'], meta: {} },
|
||||
{ prefix: 'FIX', suffix: '001', owner: 'fixer', desc: 'Plan and execute fixes', blockedBy: ['REV-001'], meta: {} }
|
||||
],
|
||||
'fix-only': [
|
||||
{ prefix: 'FIX', suffix: '001', owner: 'fixer', desc: 'Execute fixes from manifest', blockedBy: [], meta: {} }
|
||||
],
|
||||
'quick': [
|
||||
{ prefix: 'SCAN', suffix: '001', owner: 'scanner', desc: 'Quick scan (fast mode)', blockedBy: [], meta: { quick: true } }
|
||||
]
|
||||
}
|
||||
return pipelines[pipelineMode] || pipelines['default']
|
||||
}
|
||||
```
|
||||
PURPOSE: <goal> | Success: <criteria>
|
||||
TASK:
|
||||
- <step 1>
|
||||
- <step 2>
|
||||
CONTEXT:
|
||||
- Session: <session-folder>
|
||||
- Target: <target>
|
||||
- Dimensions: <dimensions>
|
||||
- Upstream artifacts: <list>
|
||||
EXPECTED: <artifact path> + <quality criteria>
|
||||
CONSTRAINTS: <scope limits>
|
||||
---
|
||||
InnerLoop: <true|false>
|
||||
RoleSpec: .claude/skills/team-review/roles/<role>/role.md
|
||||
```
|
||||
|
||||
## Execution Steps
|
||||
## Pipeline Task Registry
|
||||
|
||||
### Step 1: Session Initialization
|
||||
|
||||
```javascript
|
||||
// Session directory already created in Phase 2
|
||||
// Write pipeline config to shared memory
|
||||
const sharedMemory = JSON.parse(Read(`${sessionFolder}/.msg/meta.json`))
|
||||
sharedMemory.pipeline_mode = pipelineMode
|
||||
sharedMemory.pipeline_stages = buildPipeline(pipelineMode).map(s => `${s.prefix}-${s.suffix}`)
|
||||
Write(`${sessionFolder}/.msg/meta.json`, JSON.stringify(sharedMemory, null, 2))
|
||||
### default Mode
|
||||
```
|
||||
SCAN-001 (scanner): Multi-dimension code scan
|
||||
blockedBy: [], meta: target=<target>, dimensions=<dims>
|
||||
REV-001 (reviewer): Deep finding analysis and review
|
||||
blockedBy: [SCAN-001]
|
||||
```
|
||||
|
||||
### Step 2: Create Task Chain
|
||||
|
||||
```javascript
|
||||
const pipeline = buildPipeline(pipelineMode)
|
||||
const taskIds = {}
|
||||
|
||||
for (const stage of pipeline) {
|
||||
const taskSubject = `${stage.prefix}-${stage.suffix}: ${stage.desc}`
|
||||
|
||||
// Build task description with session context
|
||||
const fullDesc = [
|
||||
stage.desc,
|
||||
`\nsession: ${sessionFolder}`,
|
||||
`\ntarget: ${target}`,
|
||||
`\ndimensions: ${dimensions.join(',')}`,
|
||||
stage.meta?.quick ? `\nquick: true` : '',
|
||||
`\n\nGoal: ${taskDescription || target}`
|
||||
].join('')
|
||||
|
||||
// Create task
|
||||
TaskCreate({
|
||||
subject: taskSubject,
|
||||
description: fullDesc,
|
||||
activeForm: `${stage.desc} in progress`
|
||||
})
|
||||
|
||||
// Record task ID
|
||||
const allTasks = TaskList()
|
||||
const newTask = allTasks.find(t => t.subject.startsWith(`${stage.prefix}-${stage.suffix}`))
|
||||
taskIds[`${stage.prefix}-${stage.suffix}`] = newTask.id
|
||||
|
||||
// Set owner and dependencies
|
||||
const blockedByIds = stage.blockedBy
|
||||
.map(dep => taskIds[dep])
|
||||
.filter(Boolean)
|
||||
|
||||
TaskUpdate({
|
||||
taskId: newTask.id,
|
||||
owner: stage.owner,
|
||||
addBlockedBy: blockedByIds
|
||||
})
|
||||
}
|
||||
### full Mode
|
||||
```
|
||||
SCAN-001 (scanner): Multi-dimension code scan
|
||||
blockedBy: [], meta: target=<target>, dimensions=<dims>
|
||||
REV-001 (reviewer): Deep finding analysis and review
|
||||
blockedBy: [SCAN-001]
|
||||
FIX-001 (fixer): Plan and execute fixes
|
||||
blockedBy: [REV-001]
|
||||
```
|
||||
|
||||
### Step 3: Verify Chain
|
||||
### fix-only Mode
|
||||
```
|
||||
FIX-001 (fixer): Execute fixes from manifest
|
||||
blockedBy: [], meta: input=<fix-manifest>
|
||||
```
|
||||
|
||||
```javascript
|
||||
const allTasks = TaskList()
|
||||
const chainTasks = pipeline.map(s => taskIds[`${s.prefix}-${s.suffix}`]).filter(Boolean)
|
||||
const chainValid = chainTasks.length === pipeline.length
|
||||
### quick Mode
|
||||
```
|
||||
SCAN-001 (scanner): Quick scan (fast mode)
|
||||
blockedBy: [], meta: target=<target>, quick=true
|
||||
```
|
||||
|
||||
if (!chainValid) {
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId, from: "coordinator",
|
||||
type: "error",
|
||||
})
|
||||
}
|
||||
## InnerLoop Flag Rules
|
||||
|
||||
- true: fixer role (iterative fix cycles)
|
||||
- false: scanner, reviewer roles
|
||||
|
||||
## 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
|
||||
|
||||
## Log After Creation
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: sessionId, from: "coordinator",
|
||||
to: "all", type: "dispatch_ready",
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "coordinator",
|
||||
type: "dispatch_ready",
|
||||
data: { pipeline: "<mode>", task_count: <N>, target: "<target>" }
|
||||
})
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Task Chain Created
|
||||
|
||||
### Mode: [default|full|fix-only|quick]
|
||||
### Pipeline Stages: [count]
|
||||
- [prefix]-[suffix]: [description] (owner: [role], blocked by: [deps])
|
||||
|
||||
### Verification: PASS/FAIL
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Task creation fails | Retry once, then report to user |
|
||||
| Dependency cycle | Flatten dependencies, warn coordinator |
|
||||
| Invalid pipelineMode | Default to 'default' mode |
|
||||
| Missing session folder | Re-create, log warning |
|
||||
|
||||
@@ -1,276 +1,184 @@
|
||||
# Command: Monitor
|
||||
# Monitor Pipeline
|
||||
|
||||
Handle all coordinator monitoring events for the review pipeline using the async Spawn-and-Stop pattern. One operation per invocation, then STOP and wait for the next callback.
|
||||
Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
|
||||
|
||||
## Constants
|
||||
|
||||
| Key | Value | Description |
|
||||
|-----|-------|-------------|
|
||||
| SPAWN_MODE | background | All workers spawned via `Task(run_in_background: true)` |
|
||||
| ONE_STEP_PER_INVOCATION | true | Coordinator does one operation then STOPS |
|
||||
| WORKER_AGENT | team-worker | All workers spawned as team-worker agents |
|
||||
- SPAWN_MODE: background
|
||||
- ONE_STEP_PER_INVOCATION: true
|
||||
- FAST_ADVANCE_AWARE: true
|
||||
- WORKER_AGENT: team-worker
|
||||
|
||||
### Role-Worker Map
|
||||
## Handler Router
|
||||
|
||||
| Source | Handler |
|
||||
|--------|---------|
|
||||
| Message contains [scanner], [reviewer], [fixer] | handleCallback |
|
||||
| "capability_gap" | handleAdapt |
|
||||
| "check" or "status" | handleCheck |
|
||||
| "resume" or "continue" | handleResume |
|
||||
| All tasks completed | handleComplete |
|
||||
| Default | handleSpawnNext |
|
||||
|
||||
## Role-Worker Map
|
||||
|
||||
| Prefix | Role | Role Spec | inner_loop |
|
||||
|--------|------|-----------|------------|
|
||||
| SCAN | scanner | `.claude/skills/team-review/role-specs/scanner.md` | false |
|
||||
| REV | reviewer | `.claude/skills/team-review/role-specs/reviewer.md` | false |
|
||||
| FIX | fixer | `.claude/skills/team-review/role-specs/fixer.md` | false |
|
||||
| SCAN-* | scanner | `.claude/skills/team-review/roles/scanner/role.md` | false |
|
||||
| REV-* | reviewer | `.claude/skills/team-review/roles/reviewer/role.md` | false |
|
||||
| FIX-* | fixer | `.claude/skills/team-review/roles/fixer/role.md` | true |
|
||||
|
||||
### Pipeline Modes
|
||||
## handleCallback
|
||||
|
||||
| Mode | Stages |
|
||||
|------|--------|
|
||||
| scan-only | SCAN-001 |
|
||||
| default | SCAN-001 -> REV-001 |
|
||||
| full | SCAN-001 -> REV-001 -> FIX-001 |
|
||||
| fix-only | FIX-001 |
|
||||
Worker completed. Verify completion, check pipeline conditions, advance.
|
||||
|
||||
## Phase 2: Context Loading
|
||||
1. Parse message to identify role and task ID:
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Session file | `<session-folder>/.msg/meta.json` | Yes |
|
||||
| Task list | `TaskList()` | Yes |
|
||||
| Active workers | session.active_workers[] | Yes |
|
||||
| Pipeline mode | session.pipeline_mode | Yes |
|
||||
| Message Pattern | Role Detection |
|
||||
|----------------|---------------|
|
||||
| `[scanner]` or task ID `SCAN-*` | scanner |
|
||||
| `[reviewer]` or task ID `REV-*` | reviewer |
|
||||
| `[fixer]` or task ID `FIX-*` | fixer |
|
||||
|
||||
```
|
||||
Load session state:
|
||||
1. Read <session-folder>/.msg/meta.json -> session
|
||||
2. TaskList() -> allTasks
|
||||
3. Extract pipeline_mode from session
|
||||
4. Extract active_workers[] from session (default: [])
|
||||
5. Parse $ARGUMENTS to determine trigger event
|
||||
6. autoYes = /\b(-y|--yes)\b/.test(args)
|
||||
```
|
||||
2. Check if progress update (inner loop) or final completion
|
||||
3. Progress -> update session state, STOP
|
||||
4. Completion -> mark task done via TaskUpdate(status="completed"), remove from active_workers
|
||||
5. Check for checkpoints:
|
||||
- scanner completes -> read meta.json for findings_count:
|
||||
- findings_count === 0 -> delete remaining REV-*/FIX-* tasks -> handleComplete
|
||||
- findings_count > 0 -> proceed to handleSpawnNext
|
||||
- reviewer completes AND pipeline_mode === 'full':
|
||||
- autoYes flag set -> write fix-manifest.json, set fix_scope='all' -> handleSpawnNext
|
||||
- NO autoYes -> AskUserQuestion:
|
||||
```
|
||||
question: "<N> findings reviewed. Proceed with fix?"
|
||||
options:
|
||||
- "Fix all": set fix_scope='all'
|
||||
- "Fix critical/high only": set fix_scope='critical,high'
|
||||
- "Skip fix": delete FIX-* tasks -> handleComplete
|
||||
```
|
||||
Write fix_scope to meta.json, write fix-manifest.json, -> handleSpawnNext
|
||||
- fixer completes -> handleSpawnNext (checks for completion naturally)
|
||||
|
||||
## Phase 3: Event Handlers
|
||||
6. -> handleSpawnNext
|
||||
|
||||
### Wake-up Source Detection
|
||||
## handleCheck
|
||||
|
||||
Parse `$ARGUMENTS` to determine handler:
|
||||
|
||||
| Priority | Condition | Handler |
|
||||
|----------|-----------|---------|
|
||||
| 1 | Message contains `[scanner]`, `[reviewer]`, or `[fixer]` | handleCallback |
|
||||
| 2 | Contains "check" or "status" | handleCheck |
|
||||
| 3 | Contains "resume", "continue", or "next" | handleResume |
|
||||
| 4 | Pipeline detected as complete (no pending, no in_progress) | handleComplete |
|
||||
| 5 | None of the above (initial spawn after dispatch) | handleSpawnNext |
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCallback
|
||||
|
||||
Worker completed a task. Verify completion, check pipeline conditions, advance.
|
||||
|
||||
```
|
||||
Receive callback from [<role>]
|
||||
+- Find matching active worker by role tag
|
||||
+- Task status = completed?
|
||||
| +- YES -> remove from active_workers -> update session
|
||||
| | +- role = scanner?
|
||||
| | | +- Read session.findings_count from meta.json
|
||||
| | | +- findings_count === 0?
|
||||
| | | | +- YES -> Skip remaining stages:
|
||||
| | | | | Delete all REV-* and FIX-* tasks (TaskUpdate status='deleted')
|
||||
| | | | | Log: "0 findings, skipping review/fix stages"
|
||||
| | | | | -> handleComplete
|
||||
| | | | +- NO -> normal advance
|
||||
| | | +- -> handleSpawnNext
|
||||
| | +- role = reviewer?
|
||||
| | | +- pipeline_mode === 'full'?
|
||||
| | | | +- YES -> Need fix confirmation gate
|
||||
| | | | | +- autoYes?
|
||||
| | | | | | +- YES -> Set fix_scope='all' in meta.json
|
||||
| | | | | | +- Write fix-manifest.json
|
||||
| | | | | | +- -> handleSpawnNext
|
||||
| | | | | +- NO -> AskUserQuestion:
|
||||
| | | | | question: "<N> findings reviewed. Proceed with fix?"
|
||||
| | | | | header: "Fix Confirmation"
|
||||
| | | | | options:
|
||||
| | | | | - "Fix all": Set fix_scope='all'
|
||||
| | | | | - "Fix critical/high only": Set fix_scope='critical,high'
|
||||
| | | | | - "Skip fix": Delete FIX-* tasks -> handleComplete
|
||||
| | | | | +- Write fix_scope to meta.json
|
||||
| | | | | +- Write fix-manifest.json:
|
||||
| | | | | { source: "<session>/review/review-report.json",
|
||||
| | | | | scope: fix_scope, session: sessionFolder }
|
||||
| | | | | +- -> handleSpawnNext
|
||||
| | | | +- NO -> normal advance -> handleSpawnNext
|
||||
| | +- role = fixer?
|
||||
| | +- -> handleSpawnNext (checks for completion naturally)
|
||||
| +- NO -> progress message, do not advance -> STOP
|
||||
+- No matching worker found
|
||||
+- Scan all active workers for completed tasks
|
||||
+- Found completed -> process each -> handleSpawnNext
|
||||
+- None completed -> STOP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleSpawnNext
|
||||
|
||||
Find all ready tasks, spawn one team-worker agent in background, update session, STOP.
|
||||
|
||||
```
|
||||
Collect task states from TaskList()
|
||||
+- completedSubjects: status = completed
|
||||
+- inProgressSubjects: status = in_progress
|
||||
+- deletedSubjects: status = deleted
|
||||
+- readySubjects: status = pending
|
||||
AND (no blockedBy OR all blockedBy in completedSubjects)
|
||||
|
||||
Ready tasks found?
|
||||
+- NONE + work in progress -> report waiting -> STOP
|
||||
+- NONE + nothing in progress -> PIPELINE_COMPLETE -> handleComplete
|
||||
+- HAS ready tasks -> take first ready task:
|
||||
+- Determine role from prefix:
|
||||
| SCAN-* -> scanner
|
||||
| REV-* -> reviewer
|
||||
| FIX-* -> fixer
|
||||
+- TaskUpdate -> in_progress
|
||||
+- team_msg log -> task_unblocked (team_session_id=<session-id>)
|
||||
+- Spawn team-worker (see spawn call below)
|
||||
+- Add to session.active_workers
|
||||
+- Update session file
|
||||
+- Output: "[coordinator] Spawned <role> for <subject>"
|
||||
+- STOP
|
||||
```
|
||||
|
||||
**Spawn worker tool call**:
|
||||
|
||||
```
|
||||
Agent({
|
||||
agent_type: "team-worker",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: "review",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-review/role-specs/<role>.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: review
|
||||
requirement: <task-description>
|
||||
inner_loop: false
|
||||
|
||||
## Current Task
|
||||
- Task ID: <task-id>
|
||||
- Task: <subject>
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Handler: handleCheck
|
||||
|
||||
Read-only status report. No pipeline advancement.
|
||||
|
||||
**Output format**:
|
||||
Read-only status report, then STOP.
|
||||
|
||||
Output:
|
||||
```
|
||||
[coordinator] Review Pipeline Status
|
||||
[coordinator] Mode: <pipeline_mode>
|
||||
[coordinator] Progress: <completed>/<total> (<percent>%)
|
||||
|
||||
[coordinator] Pipeline Graph:
|
||||
SCAN-001: <status-icon> <summary>
|
||||
REV-001: <status-icon> <summary>
|
||||
FIX-001: <status-icon> <summary>
|
||||
SCAN-001: <done|run|wait|deleted> <summary>
|
||||
REV-001: <done|run|wait|deleted> <summary>
|
||||
FIX-001: <done|run|wait|deleted> <summary>
|
||||
|
||||
done=completed >>>=running o=pending x=deleted .=not created
|
||||
|
||||
[coordinator] Active Workers:
|
||||
> <subject> (<role>) - running
|
||||
done=completed >>>=running o=pending x=deleted
|
||||
|
||||
[coordinator] Active Workers: <list with elapsed time>
|
||||
[coordinator] Ready to spawn: <subjects>
|
||||
[coordinator] Commands: 'resume' to advance | 'check' to refresh
|
||||
```
|
||||
|
||||
Then STOP.
|
||||
|
||||
---
|
||||
## handleResume
|
||||
|
||||
### Handler: handleResume
|
||||
1. No active workers -> handleSpawnNext
|
||||
2. Has active -> check each status
|
||||
- completed -> mark done via TaskUpdate
|
||||
- in_progress -> still running
|
||||
- other -> worker failure -> reset to pending
|
||||
3. Some completed -> handleSpawnNext
|
||||
4. All running -> report status, STOP
|
||||
|
||||
Check active worker completion, process results, advance pipeline.
|
||||
## handleSpawnNext
|
||||
|
||||
Find ready tasks, spawn workers, STOP.
|
||||
|
||||
1. Collect from TaskList():
|
||||
- completedSubjects: status = completed
|
||||
- inProgressSubjects: status = in_progress
|
||||
- deletedSubjects: status = deleted
|
||||
- readySubjects: status = pending AND all blockedBy in completedSubjects
|
||||
|
||||
2. No ready + work in progress -> report waiting, STOP
|
||||
3. No ready + nothing in progress -> handleComplete
|
||||
4. Has ready -> take first ready task:
|
||||
a. Determine role from prefix (use Role-Worker Map)
|
||||
b. TaskUpdate -> in_progress
|
||||
c. team_msg log -> task_unblocked
|
||||
d. Spawn team-worker:
|
||||
|
||||
```
|
||||
Load active_workers from session
|
||||
+- No active workers -> handleSpawnNext
|
||||
+- Has active workers -> check each:
|
||||
+- status = completed -> mark done, remove from active_workers, log
|
||||
+- status = in_progress -> still running, log
|
||||
+- other status -> worker failure -> reset to pending
|
||||
After processing:
|
||||
+- Some completed -> handleSpawnNext
|
||||
+- All still running -> report status -> STOP
|
||||
+- All failed -> handleSpawnNext (retry)
|
||||
Agent({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn <role> worker for <subject>",
|
||||
team_name: "review",
|
||||
name: "<role>",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-review/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: review
|
||||
requirement: <task-description>
|
||||
inner_loop: <true|false>
|
||||
|
||||
## Current Task
|
||||
- Task ID: <task-id>
|
||||
- Task: <subject>
|
||||
|
||||
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).`
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
e. Add to active_workers
|
||||
5. Update session meta.json, output summary, STOP
|
||||
|
||||
### Handler: handleComplete
|
||||
## handleComplete
|
||||
|
||||
Pipeline complete. Generate summary and finalize session.
|
||||
Pipeline done. Generate report and completion action.
|
||||
|
||||
```
|
||||
All tasks completed or deleted (no pending, no in_progress)
|
||||
+- Read final session state from meta.json
|
||||
+- Generate pipeline summary:
|
||||
| - Pipeline mode
|
||||
| - Findings count
|
||||
| - Stages completed
|
||||
| - Fix results (if applicable)
|
||||
| - Deliverable paths
|
||||
|
|
||||
+- Update session:
|
||||
| session.pipeline_status = 'complete'
|
||||
| session.completed_at = <timestamp>
|
||||
| Write meta.json
|
||||
|
|
||||
+- team_msg log -> pipeline_complete
|
||||
+- Output summary to user
|
||||
+- STOP
|
||||
```
|
||||
1. All tasks completed or deleted (no pending, no in_progress)
|
||||
2. Read final session state from meta.json
|
||||
3. Generate pipeline summary: mode, target, findings_count, stages_completed, fix results (if applicable), deliverable paths
|
||||
4. Update session: pipeline_status='complete', completed_at=<timestamp>
|
||||
5. Read session.completion_action:
|
||||
- interactive -> AskUserQuestion (Archive/Keep/Export)
|
||||
- auto_archive -> Archive & Clean (status=completed, TeamDelete)
|
||||
- auto_keep -> Keep Active (status=paused)
|
||||
|
||||
---
|
||||
## handleAdapt
|
||||
|
||||
### Worker Failure Handling
|
||||
Capability gap reported mid-pipeline.
|
||||
|
||||
When a worker has unexpected status (not completed, not in_progress):
|
||||
1. Parse gap description
|
||||
2. Check if existing role covers it -> redirect
|
||||
3. Role count < 4 -> generate dynamic role-spec in <session>/role-specs/
|
||||
4. Create new task, spawn worker
|
||||
5. Role count >= 4 -> merge or pause
|
||||
|
||||
1. Reset task -> pending via TaskUpdate
|
||||
2. Remove from active_workers
|
||||
3. Log via team_msg (type: error)
|
||||
4. Report to user: task reset, will retry on next resume
|
||||
## 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
|
||||
|
||||
## Phase 4: State Persistence
|
||||
|
||||
After every handler action, before STOP:
|
||||
|
||||
| Check | Action |
|
||||
|-------|--------|
|
||||
| Session state consistent | active_workers matches TaskList in_progress tasks |
|
||||
| No orphaned tasks | Every in_progress task has an active_worker entry |
|
||||
| Meta.json updated | Write updated session state |
|
||||
| Completion detection | readySubjects=0 + inProgressSubjects=0 -> handleComplete |
|
||||
|
||||
```
|
||||
Persist:
|
||||
1. Reconcile active_workers with actual TaskList states
|
||||
2. Remove entries for completed/deleted tasks
|
||||
3. Write updated meta.json
|
||||
4. Verify consistency
|
||||
5. STOP (wait for next callback)
|
||||
```
|
||||
After every handler execution:
|
||||
1. Reconcile active_workers with actual TaskList states
|
||||
2. Remove entries for completed/deleted tasks
|
||||
3. Write updated meta.json
|
||||
4. STOP (wait for next callback)
|
||||
|
||||
## Error Handling
|
||||
|
||||
@@ -278,7 +186,7 @@ Persist:
|
||||
|----------|------------|
|
||||
| Session file not found | Error, suggest re-initialization |
|
||||
| Worker callback from unknown role | Log info, scan for other completions |
|
||||
| All workers still running on resume | Report status, suggest check later |
|
||||
| Pipeline stall (no ready, no running, has pending) | Check blockedBy chains, report to user |
|
||||
| 0 findings after scan | Delete remaining stages, complete pipeline |
|
||||
| User declines fix | Delete FIX tasks, complete with review-only results |
|
||||
| User declines fix | Delete FIX-* tasks, complete with review-only results |
|
||||
| Pipeline stall | Check blockedBy chains, report to user |
|
||||
| Worker failure | Reset task to pending, respawn on next resume |
|
||||
|
||||
@@ -1,152 +1,62 @@
|
||||
# Coordinator Role
|
||||
|
||||
Code review team coordinator. Orchestrates the scan-review-fix pipeline (CP-1 Linear): parse target, detect mode, dispatch task chain, drive sequential stage execution via Stop-Wait, aggregate results.
|
||||
Orchestrate team-review: parse target -> detect mode -> dispatch task chain -> monitor -> report.
|
||||
|
||||
## Identity
|
||||
|
||||
- **Name**: `coordinator` | **Tag**: `[coordinator]`
|
||||
- **Task Prefix**: RC-* (coordinator creates tasks, doesn't receive them)
|
||||
- **Responsibility**: Orchestration
|
||||
- Name: coordinator | Tag: [coordinator]
|
||||
- Responsibility: Target parsing, mode detection, task creation/dispatch, stage monitoring, result aggregation
|
||||
|
||||
## Boundaries
|
||||
|
||||
### MUST
|
||||
|
||||
- All output (SendMessage, team_msg, logs) prefixed with `[coordinator]`
|
||||
- Only: target parsing, mode detection, task creation/dispatch, stage monitoring, result aggregation
|
||||
- Create tasks via TaskCreate and assign to worker roles
|
||||
- Drive pipeline stages via Stop-Wait (synchronous Skill() calls)
|
||||
- Parse user requirements and clarify ambiguous inputs via AskUserQuestion
|
||||
- Maintain session state persistence
|
||||
- All output prefixed with `[coordinator]`
|
||||
- Parse task description and detect pipeline mode
|
||||
- Create team and spawn team-worker agents in background
|
||||
- Dispatch task chain with proper dependencies
|
||||
- Monitor progress via callbacks and route messages
|
||||
- Maintain session state
|
||||
- Execute completion action when pipeline finishes
|
||||
|
||||
### MUST NOT
|
||||
|
||||
- Run analysis tools directly (semgrep, eslint, tsc, etc.)
|
||||
- Modify source code files
|
||||
- Perform code review analysis
|
||||
- Bypass worker roles to do delegated work
|
||||
- Omit `[coordinator]` prefix on any output
|
||||
- Call implementation CLI tools directly
|
||||
|
||||
> **Core principle**: coordinator is the orchestrator, not the executor. All actual work delegated to scanner/reviewer/fixer via task chain.
|
||||
|
||||
---
|
||||
- Perform code review or scanning directly
|
||||
- Bypass worker roles
|
||||
- Spawn workers with general-purpose agent (MUST use team-worker)
|
||||
|
||||
## Command Execution Protocol
|
||||
|
||||
When coordinator needs to execute a command (dispatch, monitor):
|
||||
|
||||
1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
|
||||
2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
|
||||
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** -- complete the command workflow before proceeding
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
When coordinator is invoked, detect invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains role tag [scanner], [reviewer], [fixer] | -> handleCallback |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
|
||||
| Interrupted session | Active/paused session exists | -> Phase 0 (Session Resume Check) |
|
||||
| New session | None of above | -> Phase 1 (Parse Arguments) |
|
||||
| Worker callback | Message contains [scanner], [reviewer], [fixer] | -> handleCallback (monitor.md) |
|
||||
| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
|
||||
| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
|
||||
| Interrupted session | Active session in .workflow/.team/RV-* | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
|
||||
For callback/check/resume/adapt/complete: load commands/monitor.md, execute handler, STOP.
|
||||
|
||||
### Router Implementation
|
||||
## Phase 0: Session Resume Check
|
||||
|
||||
1. **Load session context** (if exists):
|
||||
- Scan `.workflow/.team-review/RC-*/.msg/meta.json` for active/paused sessions
|
||||
- If found, extract session folder path, status, and pipeline mode
|
||||
1. Scan .workflow/.team/RV-*/.msg/meta.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)
|
||||
4. Multiple -> AskUserQuestion for selection
|
||||
|
||||
2. **Parse $ARGUMENTS** for detection keywords:
|
||||
- Check for role name tags in message content
|
||||
- Check for "check", "status", "resume", "continue" keywords
|
||||
## Phase 1: Requirement Clarification
|
||||
|
||||
3. **Route to handler**:
|
||||
- For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
|
||||
- For Phase 0: Execute Session Resume Check
|
||||
- For Phase 1: Execute Parse Arguments below
|
||||
TEXT-LEVEL ONLY. No source code reading.
|
||||
|
||||
---
|
||||
|
||||
## Toolbox
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | File | Phase | Description |
|
||||
|---------|------|-------|-------------|
|
||||
| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | Task chain creation based on mode |
|
||||
| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | Stop-Wait stage execution loop |
|
||||
|
||||
### Tool Capabilities
|
||||
|
||||
| Tool | Type | Used By | Purpose |
|
||||
|------|------|---------|---------|
|
||||
| `TaskCreate` | Built-in | coordinator | Create tasks for workers |
|
||||
| `TaskUpdate` | Built-in | coordinator | Update task status |
|
||||
| `TaskList` | Built-in | coordinator | Check task states |
|
||||
| `AskUserQuestion` | Built-in | coordinator | Clarify requirements |
|
||||
| `Skill` | Built-in | coordinator | Spawn workers |
|
||||
| `SendMessage` | Built-in | coordinator | Receive worker callbacks |
|
||||
| `team_msg` | MCP | coordinator | Log communication |
|
||||
|
||||
---
|
||||
|
||||
## Message Types
|
||||
|
||||
| Type | Direction | Trigger | Description |
|
||||
|------|-----------|---------|-------------|
|
||||
| `dispatch_ready` | coordinator -> all | Phase 3 done | Task chain created, pipeline ready |
|
||||
| `stage_transition` | coordinator -> worker | Stage unblocked | Next stage starting |
|
||||
| `pipeline_complete` | coordinator -> user | All stages done | Pipeline finished, summary ready |
|
||||
| `error` | coordinator -> user | Stage failure | Blocking issue requiring attention |
|
||||
|
||||
## Message Bus
|
||||
|
||||
Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
|
||||
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: <session-id>,
|
||||
from: "coordinator",
|
||||
type: "dispatch_ready"
|
||||
})
|
||||
```
|
||||
|
||||
**CLI fallback** (when MCP unavailable):
|
||||
|
||||
```
|
||||
Bash("ccw team log --session-id <session-id> --from coordinator --type dispatch_ready --json")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution (5-Phase)
|
||||
|
||||
### Phase 1: Parse Arguments & Detect Mode
|
||||
|
||||
**Objective**: Parse user input and gather execution parameters.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. **Parse arguments** for explicit settings:
|
||||
1. Parse arguments for explicit settings:
|
||||
|
||||
| Flag | Mode | Description |
|
||||
|------|------|-------------|
|
||||
@@ -155,147 +65,65 @@ Bash("ccw team log --session-id <session-id> --from coordinator --type dispatch_
|
||||
| `-q` / `--quick` | quick | Quick scan only, no review/fix |
|
||||
| (none) | default | scan + review pipeline |
|
||||
|
||||
2. **Extract parameters**:
|
||||
2. Extract parameters: target, dimensions, auto-confirm flag
|
||||
3. Clarify if ambiguous (AskUserQuestion for target path)
|
||||
4. Delegate to commands/analyze.md
|
||||
5. Output: task-analysis.json
|
||||
6. CRITICAL: Always proceed to Phase 2, never skip team workflow
|
||||
|
||||
| Parameter | Extraction Method | Default |
|
||||
|-----------|-------------------|---------|
|
||||
| Target | Task description minus flags | `.` |
|
||||
| Dimensions | `--dimensions=sec,cor,perf,maint` | All 4 |
|
||||
| Auto-confirm | `-y` / `--yes` flag | false |
|
||||
## Phase 2: Create Team + Initialize Session
|
||||
|
||||
3. **Ask for missing parameters** via AskUserQuestion (if not auto-confirm):
|
||||
1. Generate session ID: RV-<slug>-<date>
|
||||
2. Create session folder structure (scan/, review/, fix/, wisdom/)
|
||||
3. TeamCreate with team name "review"
|
||||
4. Read specs/pipelines.md -> select pipeline based on mode
|
||||
5. Initialize pipeline via team_msg state_update:
|
||||
```
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log", session_id: "<id>", from: "coordinator",
|
||||
type: "state_update", summary: "Session initialized",
|
||||
data: {
|
||||
pipeline_mode: "<default|full|fix-only|quick>",
|
||||
pipeline_stages: ["scanner", "reviewer", "fixer"],
|
||||
team_name: "review",
|
||||
target: "<target>",
|
||||
dimensions: "<dimensions>",
|
||||
auto_confirm: "<auto_confirm>"
|
||||
}
|
||||
})
|
||||
```
|
||||
6. Write session meta.json
|
||||
|
||||
| Question | Options |
|
||||
|----------|---------|
|
||||
| "What code should be reviewed?" | Custom path, Uncommitted changes, Full project scan |
|
||||
## Phase 3: Create Task Chain
|
||||
|
||||
**Success**: All parameters captured, mode finalized.
|
||||
Delegate to commands/dispatch.md:
|
||||
1. Read specs/pipelines.md for selected pipeline's task registry
|
||||
2. Create tasks via TaskCreate with blockedBy
|
||||
3. Update session meta.json with pipeline.tasks_total
|
||||
|
||||
---
|
||||
## Phase 4: Spawn-and-Stop
|
||||
|
||||
### Phase 2: Initialize Session
|
||||
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
|
||||
|
||||
**Objective**: Initialize team, session file, and shared memory.
|
||||
## Phase 5: Report + Completion Action
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Generate session ID: `RC-<target-slug>-<date>`
|
||||
2. Create session folder structure:
|
||||
|
||||
```
|
||||
.workflow/.team-review/<workflow_id>/
|
||||
├── scan/
|
||||
├── review/
|
||||
├── fix/
|
||||
├── wisdom/
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── .msg/
|
||||
│ ├── messages.jsonl
|
||||
│ └── meta.json
|
||||
```
|
||||
|
||||
3. Initialize .msg/meta.json with pipeline metadata:
|
||||
```typescript
|
||||
// Use team_msg to write pipeline metadata to .msg/meta.json
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session-id>",
|
||||
from: "coordinator",
|
||||
type: "state_update",
|
||||
summary: "Session initialized",
|
||||
data: {
|
||||
pipeline_mode: "<default|full|fix-only|quick>",
|
||||
pipeline_stages: ["scanner", "reviewer", "fixer"],
|
||||
roles: ["coordinator", "scanner", "reviewer", "fixer"],
|
||||
team_name: "review",
|
||||
target: "<target>",
|
||||
dimensions: "<dimensions>",
|
||||
auto_confirm: "<auto_confirm>"
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Success**: Session folder created, shared memory initialized.
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Create Task Chain
|
||||
|
||||
**Objective**: Dispatch tasks based on mode with proper dependencies.
|
||||
|
||||
Delegate to `commands/dispatch.md` which creates the full task chain.
|
||||
|
||||
**Task Chain by Mode**:
|
||||
|
||||
| Mode | Chain | Description |
|
||||
|------|-------|-------------|
|
||||
| default | SCAN-001 -> REV-001 | scan + review |
|
||||
| full | SCAN-001 -> REV-001 -> FIX-001 | scan + review + fix |
|
||||
| fix-only | FIX-001 | fix only |
|
||||
| quick | SCAN-001 (quick=true) | quick scan only |
|
||||
|
||||
**Success**: Task chain created with correct blockedBy dependencies.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Sequential Stage Execution (Stop-Wait)
|
||||
|
||||
**Objective**: Spawn workers sequentially via Skill(), synchronous blocking until return.
|
||||
|
||||
> **Strategy**: Spawn-and-Stop + Callback pattern.
|
||||
> - Spawn workers with synchronous `Skill()` call -> blocking wait for return
|
||||
> - Worker return = stage complete. No polling.
|
||||
> - FORBIDDEN: `while` loop + `sleep` + check status
|
||||
> - REQUIRED: Synchronous `Skill()` call = natural callback
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Load `commands/monitor.md`
|
||||
2. Find next executable task (pending + blockedBy resolved)
|
||||
3. Spawn worker via Skill()
|
||||
4. Wait for worker return
|
||||
5. Process result -> advance to next stage
|
||||
6. Repeat until pipeline complete
|
||||
|
||||
**Stage Flow**:
|
||||
|
||||
| Stage | Worker | On Complete |
|
||||
|-------|--------|-------------|
|
||||
| SCAN-001 | scanner | Check findings count -> start REV |
|
||||
| REV-001 | reviewer | Generate review report -> [user confirm] -> start FIX |
|
||||
| FIX-001 | fixer | Execute fixes -> verify |
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Aggregate Results & Report
|
||||
|
||||
> See SKILL.md Shared Infrastructure -> Coordinator Phase 5
|
||||
|
||||
**Objective**: Completion report and follow-up options.
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Load session state -> count completed tasks, duration
|
||||
2. Calculate fix rate: (fixed_count / findings_count) * 100
|
||||
3. Build summary report with: mode, target, dimensions, findings_total, by_severity, by_dimension, fixed_count, fix_rate
|
||||
4. Log via team_msg
|
||||
5. SendMessage with `[coordinator]` prefix
|
||||
6. AskUserQuestion for next steps (unless auto-confirm)
|
||||
|
||||
---
|
||||
1. Generate summary (mode, target, findings_total, by_severity, fix_rate if applicable)
|
||||
2. Execute completion action per session.completion_action:
|
||||
- interactive -> AskUserQuestion (Archive/Keep/Export)
|
||||
- auto_archive -> Archive & Clean
|
||||
- auto_keep -> Keep Active
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Task too vague | AskUserQuestion for clarification |
|
||||
| Session corruption | Attempt recovery, fallback to manual |
|
||||
| Worker crash | Reset task to pending, respawn |
|
||||
| Scanner finds 0 findings | Report clean, skip review + fix stages |
|
||||
| Worker returns incomplete | Ask user: retry / skip / abort |
|
||||
| Fix verification fails | Log warning, report partial results |
|
||||
| Session folder missing | Re-create and log warning |
|
||||
| Target path invalid | AskUserQuestion for corrected path |
|
||||
| Task timeout | Log, mark failed, ask user to retry or skip |
|
||||
| Worker crash | Respawn worker, reassign task |
|
||||
| Dependency cycle | Detect, report to user, halt |
|
||||
|
||||
76
.claude/skills/team-review/roles/fixer/role.md
Normal file
76
.claude/skills/team-review/roles/fixer/role.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
role: fixer
|
||||
prefix: FIX
|
||||
inner_loop: true
|
||||
message_types:
|
||||
success: fix_complete
|
||||
error: fix_failed
|
||||
---
|
||||
|
||||
# Code Fixer
|
||||
|
||||
Fix code based on reviewed findings. Load manifest, plan fix groups, apply with rollback-on-failure, verify. Code-generation role -- modifies source files.
|
||||
|
||||
## Phase 2: Context & Scope Resolution
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Fix manifest | <session>/fix/fix-manifest.json | Yes |
|
||||
| Review report | <session>/review/review-report.json | Yes |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path, input path from task description
|
||||
2. Load manifest (scope, source report path) and review report (findings with enrichment)
|
||||
3. Filter fixable findings: severity in scope AND fix_strategy !== 'skip'
|
||||
4. If 0 fixable -> report complete immediately
|
||||
5. Detect quick path: findings <= 5 AND no cross-file dependencies
|
||||
6. Detect verification tools: tsc (tsconfig.json), eslint (package.json), jest (package.json), pytest (pyproject.toml), semgrep (semgrep available)
|
||||
7. Load wisdom files from `<session>/wisdom/`
|
||||
|
||||
## Phase 3: Plan + Execute
|
||||
|
||||
### 3A: Plan Fixes (deterministic, no CLI)
|
||||
1. Group findings by primary file
|
||||
2. Merge groups with cross-file dependencies (union-find)
|
||||
3. Topological sort within each group (respect fix_dependencies, append cycles at end)
|
||||
4. Sort groups by max severity (critical first)
|
||||
5. Determine execution path: quick_path (<=5 findings, <=1 group) or standard
|
||||
6. Write `<session>/fix/fix-plan.json`: `{plan_id, quick_path, groups[{id, files[], findings[], max_severity}], execution_order[], total_findings, total_groups}`
|
||||
|
||||
### 3B: Execute Fixes
|
||||
**Quick path**: Single code-developer agent for all findings.
|
||||
**Standard path**: One code-developer agent per group, in execution_order.
|
||||
|
||||
Agent prompt includes: finding list (dependency-sorted), file contents (truncated 8K), critical rules:
|
||||
1. Apply each fix using Edit tool in order
|
||||
2. After each fix, run related tests
|
||||
3. Tests PASS -> finding is "fixed"
|
||||
4. Tests FAIL -> `git checkout -- {file}` -> mark "failed" -> continue
|
||||
5. No retry on failure. Rollback and move on
|
||||
6. If finding depends on previously failed finding -> mark "skipped"
|
||||
|
||||
Agent returns JSON: `{results:[{id, status: fixed|failed|skipped, file, error?}]}`
|
||||
Fallback: check git diff per file if no structured output.
|
||||
|
||||
Write `<session>/fix/execution-results.json`: `{fixed[], failed[], skipped[]}`
|
||||
|
||||
## Phase 4: Post-Fix Verification
|
||||
|
||||
1. Run available verification tools on modified files:
|
||||
|
||||
| Tool | Command | Pass Criteria |
|
||||
|------|---------|---------------|
|
||||
| tsc | `npx tsc --noEmit` | 0 errors |
|
||||
| eslint | `npx eslint <files>` | 0 errors |
|
||||
| jest | `npx jest --passWithNoTests` | Tests pass |
|
||||
| pytest | `pytest --tb=short` | Tests pass |
|
||||
| semgrep | `semgrep --config auto <files> --json` | 0 results |
|
||||
|
||||
2. If verification fails critically -> rollback last batch
|
||||
3. Write `<session>/fix/verify-results.json`
|
||||
4. Generate `<session>/fix/fix-summary.json`: `{fix_id, fix_date, scope, total, fixed, failed, skipped, fix_rate, verification}`
|
||||
5. Generate `<session>/fix/fix-summary.md` (human-readable)
|
||||
6. Update `<session>/.msg/meta.json` with fix results
|
||||
7. Contribute discoveries to `<session>/wisdom/` files
|
||||
67
.claude/skills/team-review/roles/reviewer/role.md
Normal file
67
.claude/skills/team-review/roles/reviewer/role.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
role: reviewer
|
||||
prefix: REV
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: review_complete
|
||||
error: error
|
||||
---
|
||||
|
||||
# Finding Reviewer
|
||||
|
||||
Deep analysis on scan findings: triage, root cause / impact / optimization enrichment via CLI fan-out, cross-correlation, and structured review report generation. Read-only -- never modifies source code.
|
||||
|
||||
## Phase 2: Context & Triage
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Scan results | <session>/scan/scan-results.json | Yes |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path, input path, dimensions from task description
|
||||
2. Load scan results. If missing or empty -> report clean, complete immediately
|
||||
3. Load wisdom files from `<session>/wisdom/`
|
||||
4. Triage findings into two buckets:
|
||||
|
||||
| Bucket | Criteria | Action |
|
||||
|--------|----------|--------|
|
||||
| deep_analysis | severity in [critical, high, medium], max 15, sorted critical-first | Enrich with root cause, impact, optimization |
|
||||
| pass_through | remaining (low, info, or overflow) | Include in report without enrichment |
|
||||
|
||||
If deep_analysis empty -> skip Phase 3, go to Phase 4.
|
||||
|
||||
## Phase 3: Deep Analysis (CLI Fan-out)
|
||||
|
||||
Split deep_analysis into two domain groups, run parallel CLI agents:
|
||||
|
||||
| Group | Dimensions | Focus |
|
||||
|-------|-----------|-------|
|
||||
| A | Security + Correctness | Root cause tracing, fix dependencies, blast radius |
|
||||
| B | Performance + Maintainability | Optimization approaches, refactor tradeoffs |
|
||||
|
||||
If either group empty -> skip that agent.
|
||||
|
||||
Build prompt per group requesting 6 enrichment fields per finding:
|
||||
- `root_cause`: `{description, related_findings[], is_symptom}`
|
||||
- `impact`: `{scope: low/medium/high, affected_files[], blast_radius}`
|
||||
- `optimization`: `{approach, alternative, tradeoff}`
|
||||
- `fix_strategy`: minimal / refactor / skip
|
||||
- `fix_complexity`: low / medium / high
|
||||
- `fix_dependencies`: finding IDs that must be fixed first
|
||||
|
||||
Execute via `ccw cli --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause` (fallback: qwen -> codex). Parse JSON array responses, merge with originals (CLI-enriched replace originals, unenriched get defaults). Write `<session>/review/enriched-findings.json`.
|
||||
|
||||
## Phase 4: Report Generation
|
||||
|
||||
1. Combine enriched + pass_through findings
|
||||
2. Cross-correlate:
|
||||
- **Critical files**: file appears in >=2 dimensions -> list with finding_count, severities
|
||||
- **Root cause groups**: cluster findings sharing related_findings -> identify primary
|
||||
- **Optimization suggestions**: from root cause groups + standalone enriched findings
|
||||
3. Compute metrics: by_dimension, by_severity, dimension_severity_matrix, fixable_count, auto_fixable_count
|
||||
4. Write `<session>/review/review-report.json`: `{review_id, review_date, findings[], critical_files[], optimization_suggestions[], root_cause_groups[], summary}`
|
||||
5. Write `<session>/review/review-report.md`: Executive summary, metrics matrix (dimension x severity), critical/high findings table, critical files list, optimization suggestions, recommended fix scope
|
||||
6. Update `<session>/.msg/meta.json` with review summary
|
||||
7. Contribute discoveries to `<session>/wisdom/` files
|
||||
71
.claude/skills/team-review/roles/scanner/role.md
Normal file
71
.claude/skills/team-review/roles/scanner/role.md
Normal file
@@ -0,0 +1,71 @@
|
||||
---
|
||||
role: scanner
|
||||
prefix: SCAN
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: scan_complete
|
||||
error: error
|
||||
---
|
||||
|
||||
# Code Scanner
|
||||
|
||||
Toolchain + LLM semantic scan producing structured findings. Static analysis tools in parallel, then LLM for issues tools miss. Read-only -- never modifies source code. 4-dimension system: security (SEC), correctness (COR), performance (PRF), maintainability (MNT).
|
||||
|
||||
## Phase 2: Context & Toolchain Detection
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| .msg/meta.json | <session>/.msg/meta.json | No |
|
||||
|
||||
1. Extract session path, target, dimensions, quick flag from task description
|
||||
2. Resolve target files (glob pattern or directory -> `**/*.{ts,tsx,js,jsx,py,go,java,rs}`)
|
||||
3. If no source files found -> report empty, complete task cleanly
|
||||
4. Detect toolchain availability:
|
||||
|
||||
| Tool | Detection | Dimension |
|
||||
|------|-----------|-----------|
|
||||
| tsc | `tsconfig.json` exists | COR |
|
||||
| eslint | `.eslintrc*` or `eslint` in package.json | COR/MNT |
|
||||
| semgrep | `.semgrep.yml` exists | SEC |
|
||||
| ruff | `pyproject.toml` + ruff available | SEC/COR/MNT |
|
||||
| mypy | mypy available + `pyproject.toml` | COR |
|
||||
| npmAudit | `package-lock.json` exists | SEC |
|
||||
|
||||
5. Load wisdom files from `<session>/wisdom/` if they exist
|
||||
|
||||
## Phase 3: Scan Execution
|
||||
|
||||
**Quick mode**: Single CLI call with analysis mode, max 20 findings, skip toolchain.
|
||||
|
||||
**Standard mode** (sequential):
|
||||
|
||||
### 3A: Toolchain Scan
|
||||
Run detected tools in parallel via Bash backgrounding. Each tool writes to `<session>/scan/tmp/<tool>.{json|txt}`. After `wait`, parse each output into normalized findings:
|
||||
- tsc: `file(line,col): error TSxxxx: msg` -> dimension=correctness, source=tool:tsc
|
||||
- eslint: JSON array -> severity 2=correctness/high, else=maintainability/medium
|
||||
- semgrep: `{results[]}` -> dimension=security, severity from extra.severity
|
||||
- ruff: `[{code,message,filename}]` -> S*=security, F*/B*=correctness, else=maintainability
|
||||
- mypy: `file:line: error: msg [code]` -> dimension=correctness
|
||||
- npm audit: `{vulnerabilities:{}}` -> dimension=security, category=dependency
|
||||
|
||||
Write `<session>/scan/toolchain-findings.json`.
|
||||
|
||||
### 3B: Semantic Scan (LLM via CLI)
|
||||
Build prompt with target file patterns, toolchain dedup summary, and per-dimension focus areas:
|
||||
- SEC: Business logic vulnerabilities, privilege escalation, sensitive data flow, auth bypass
|
||||
- COR: Logic errors, unhandled exception paths, state management bugs, race conditions
|
||||
- PRF: Algorithm complexity, N+1 queries, unnecessary sync, memory leaks, missing caching
|
||||
- MNT: Architectural coupling, abstraction leaks, convention violations, dead code
|
||||
|
||||
Execute via `ccw cli --tool gemini --mode analysis --rule analysis-review-code-quality` (fallback: qwen -> codex). Parse JSON array response, validate required fields (dimension, title, location.file), enforce per-dimension limit (max 5 each), filter minimum severity (medium+). Write `<session>/scan/semantic-findings.json`.
|
||||
|
||||
## Phase 4: Aggregate & Output
|
||||
|
||||
1. Merge toolchain + semantic findings, deduplicate (same file + line + dimension = duplicate)
|
||||
2. Assign dimension-prefixed IDs: SEC-001, COR-001, PRF-001, MNT-001
|
||||
3. Write `<session>/scan/scan-results.json` with schema: `{scan_date, target, dimensions, quick_mode, total_findings, by_severity, by_dimension, findings[]}`
|
||||
4. Each finding: `{id, dimension, category, severity, title, description, location:{file,line}, source, suggested_fix, effort, confidence}`
|
||||
5. Update `<session>/.msg/meta.json` with scan summary (findings_count, by_severity, by_dimension)
|
||||
6. Contribute discoveries to `<session>/wisdom/` files
|
||||
102
.claude/skills/team-review/specs/pipelines.md
Normal file
102
.claude/skills/team-review/specs/pipelines.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Review Pipelines
|
||||
|
||||
Pipeline definitions and task registry for team-review.
|
||||
|
||||
## Pipeline Modes
|
||||
|
||||
| Mode | Description | Tasks |
|
||||
|------|-------------|-------|
|
||||
| default | Scan + review | SCAN -> REV |
|
||||
| full | Scan + review + fix | SCAN -> REV -> [confirm] -> FIX |
|
||||
| fix-only | Fix from existing manifest | FIX |
|
||||
| quick | Quick scan only | SCAN (quick=true) |
|
||||
|
||||
## Pipeline Definitions
|
||||
|
||||
### default Mode (2 tasks, linear)
|
||||
|
||||
```
|
||||
SCAN-001 -> REV-001
|
||||
```
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| SCAN-001 | scanner | (none) | Multi-dimension code scan (toolchain + LLM) |
|
||||
| REV-001 | reviewer | SCAN-001 | Deep finding analysis and review report |
|
||||
|
||||
### full Mode (3 tasks, linear with user checkpoint)
|
||||
|
||||
```
|
||||
SCAN-001 -> REV-001 -> [user confirm] -> FIX-001
|
||||
```
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| SCAN-001 | scanner | (none) | Multi-dimension code scan (toolchain + LLM) |
|
||||
| REV-001 | reviewer | SCAN-001 | Deep finding analysis and review report |
|
||||
| FIX-001 | fixer | REV-001 + user confirm | Plan + execute + verify fixes |
|
||||
|
||||
### fix-only Mode (1 task)
|
||||
|
||||
```
|
||||
FIX-001
|
||||
```
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| FIX-001 | fixer | (none) | Execute fixes from existing manifest |
|
||||
|
||||
### quick Mode (1 task)
|
||||
|
||||
```
|
||||
SCAN-001 (quick=true)
|
||||
```
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| SCAN-001 | scanner | (none) | Quick scan, max 20 findings, skip toolchain |
|
||||
|
||||
## Review Dimensions (4-Dimension System)
|
||||
|
||||
| Dimension | Code | Focus |
|
||||
|-----------|------|-------|
|
||||
| Security | SEC | Vulnerabilities, auth, data exposure |
|
||||
| Correctness | COR | Bugs, logic errors, type safety |
|
||||
| Performance | PRF | N+1, memory leaks, blocking ops |
|
||||
| Maintainability | MNT | Coupling, complexity, dead code |
|
||||
|
||||
## Fix Scope Options
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| all | Fix all findings |
|
||||
| critical,high | Fix critical and high severity only |
|
||||
| skip | Skip fix phase |
|
||||
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/RV-<slug>-<YYYY-MM-DD>/
|
||||
├── .msg/messages.jsonl # Message bus log
|
||||
├── .msg/meta.json # Session state + cross-role state
|
||||
├── wisdom/ # Cross-task knowledge
|
||||
│ ├── learnings.md
|
||||
│ ├── decisions.md
|
||||
│ ├── conventions.md
|
||||
│ └── issues.md
|
||||
├── scan/ # Scanner output
|
||||
│ ├── toolchain-findings.json
|
||||
│ ├── semantic-findings.json
|
||||
│ └── scan-results.json
|
||||
├── review/ # Reviewer output
|
||||
│ ├── enriched-findings.json
|
||||
│ ├── review-report.json
|
||||
│ └── review-report.md
|
||||
└── fix/ # Fixer output
|
||||
├── fix-manifest.json
|
||||
├── fix-plan.json
|
||||
├── execution-results.json
|
||||
├── verify-results.json
|
||||
├── fix-summary.json
|
||||
└── fix-summary.md
|
||||
```
|
||||
Reference in New Issue
Block a user