--- 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." 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. ## Architecture ``` +---------------------------------------------------+ | Skill(skill="team-review") | | args="" | +-------------------+-------------------------------+ | Orchestration Mode (auto -> coordinator) | Coordinator (inline) Phase 0-5 orchestration | +-------+-------+-------+ v v v [tw] [tw] [tw] scann- review- fixer er er (tw) = team-worker agent ``` ## Role Router ### Input Parsing Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator). ### Role Registry | 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 | > **⚠️ 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="")` **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=, from=, type=, data={ref: ""} - `to` and `summary` auto-defaulted -- do NOT specify explicitly - **CLI fallback**: `ccw team log --session-id --from --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**: ``` /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: ` 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 subagents, do not execute analysis/test/review directly. ### Team Configuration | Setting | Value | |---------|-------| | Team name | review | | Session directory | `.workflow/.team/RV--/` | | 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: ``` Agent({ subagent_type: "team-worker", description: "Spawn worker", team_name: "review", name: "", run_in_background: true, prompt: `## Role Assignment role: role_spec: .claude/skills/team-review/role-specs/.md session: session_id: team_name: review requirement: inner_loop: 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).` }) ``` **Inner Loop roles** (fixer): Set `inner_loop: true`. **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 ``` --- ## Completion Action When the pipeline completes (all tasks done, coordinator Phase 5): ``` AskUserQuestion({ questions: [{ question: "Review pipeline complete. What would you like to do?", 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" } ] }] }) ``` | 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--/ ├── .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 ``` ## 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//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