maestro-flow 0.2.0 → 0.2.2

package/.claude/skills/team-quality-assurance/roles/executor/role.md

@@ -0,0 +1,66 @@
+---
+role: executor
+prefix: QARUN
+inner_loop: true
+additional_prefixes: [QARUN-gc]
+message_types:
+  success: tests_passed
+  failure: tests_failed
+  coverage: coverage_report
+  error: error
+---
+
+# Test Executor
+
+Run test suites, collect coverage data, and perform automatic fix cycles when tests fail. Implements the execution side of the Generator-Executor (GC) loop.
+
+## Phase 2: Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Test strategy | meta.json -> test_strategy | Yes |
+| Generated tests | meta.json -> generated_tests | Yes |
+| Target layer | task description `layer: L1/L2/L3` | Yes |
+
+1. Extract session path and target layer from task description
+2. Load validation specs: Run `ccw spec load --category validation` for verification rules and acceptance criteria
+3. Read .msg/meta.json for strategy and generated test file list
+3. Detect test command by framework:
+
+| Framework | Command |
+|-----------|---------|
+| vitest | `npx vitest run --coverage --reporter=json --outputFile=test-results.json` |
+| jest | `npx jest --coverage --json --outputFile=test-results.json` |
+| pytest | `python -m pytest --cov --cov-report=json -v` |
+| mocha | `npx mocha --reporter json > test-results.json` |
+| unknown | `npm test -- --coverage` |
+
+4. Get test files from `generated_tests[targetLayer].files`
+
+## Phase 3: Iterative Test-Fix Cycle
+
+**Max iterations**: 5. **Pass threshold**: 95% or all tests pass.
+
+Per iteration:
+1. Run test command, capture output
+2. Parse results: extract passed/failed counts, parse coverage from output or `coverage/coverage-summary.json`
+3. If all pass (0 failures) -> exit loop (success)
+4. If pass rate >= 95% and iteration >= 2 -> exit loop (good enough)
+5. If iteration >= MAX -> exit loop (report current state)
+6. Extract failure details (error lines, assertion failures)
+7. Delegate fix via CLI tool with constraints:
+   - ONLY modify test files, NEVER modify source code
+   - Fix: incorrect assertions, missing imports, wrong mocks, setup issues
+   - Do NOT: skip tests, add `@ts-ignore`, use `as any`
+8. Increment iteration, repeat
+
+## Phase 4: Result Analysis & Output
+
+1. Build result data: layer, framework, iterations, pass_rate, coverage, tests_passed, tests_failed, all_passed
+2. Save results to `<session>/results/run-<layer>.json`
+3. Save last test output to `<session>/results/output-<layer>.txt`
+4. Update `<session>/wisdom/.msg/meta.json` under `execution_results[layer]` and top-level `execution_results.pass_rate`, `execution_results.coverage`
+5. Message type: `tests_passed` if all_passed, else `tests_failed`

package/.claude/skills/team-quality-assurance/roles/generator/role.md

@@ -0,0 +1,68 @@
+---
+role: generator
+prefix: QAGEN
+inner_loop: false
+additional_prefixes: [QAGEN-fix]
+message_types:
+  success: tests_generated
+  revised: tests_revised
+  error: error
+---
+
+# Test Generator
+
+Generate test code according to strategist's strategy and layers. Support L1 unit tests, L2 integration tests, L3 E2E tests. Follow project's existing test patterns and framework conventions.
+
+## Phase 2: Strategy & Pattern Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Test strategy | meta.json -> test_strategy | Yes |
+| Target layer | task description `layer: L1/L2/L3` | Yes |
+
+1. Extract session path and target layer from task description
+2. Read .msg/meta.json for test strategy (layers, coverage targets)
+3. Determine if this is a GC fix task (subject contains "fix")
+4. Load layer config from strategy: level, name, target_coverage, focus_files
+5. Learn existing test patterns -- find 3 similar test files via Glob(`**/*.{test,spec}.{ts,tsx,js,jsx}`)
+6. Detect test conventions: file location (colocated vs __tests__), import style, describe/it nesting, framework (vitest/jest/pytest)
+
+## Phase 3: Test Code Generation
+
+**Mode selection**:
+
+| Condition | Mode |
+|-----------|------|
+| GC fix task | Read failure info from `<session>/results/run-<layer>.json`, fix failing tests only |
+| <= 3 focus files | Direct: inline Read source -> Write test file |
+| > 3 focus files | Batch by module, delegate via CLI tool |
+
+**Direct generation flow** (per source file):
+1. Read source file content, extract exports
+2. Determine test file path following project conventions
+3. If test exists -> analyze missing cases -> append new tests via Edit
+4. If no test -> generate full test file via Write
+5. Include: happy path, edge cases, error cases per export
+
+**GC fix flow**:
+1. Read execution results and failure output from results directory
+2. Read each failing test file
+3. Fix assertions, imports, mocks, or test setup
+4. Do NOT modify source code, do NOT skip/ignore tests
+
+**General rules**:
+- Follow existing test patterns exactly (imports, naming, structure)
+- Target coverage per layer config
+- Do NOT use `any` type assertions or `@ts-ignore`
+
+## Phase 4: Self-Validation & Output
+
+1. Collect generated/modified test files
+2. Run syntax check (TypeScript: `tsc --noEmit`, or framework-specific)
+3. Auto-fix syntax errors (max 3 attempts)
+4. Write test metadata to `<session>/wisdom/.msg/meta.json` under `generated_tests[layer]`:
+   - layer, files list, count, syntax_clean, mode, gc_fix flag
+5. Message type: `tests_generated` for new, `tests_revised` for GC fix iterations

package/.claude/skills/team-quality-assurance/roles/scout/role.md

@@ -0,0 +1,67 @@
+---
+role: scout
+prefix: SCOUT
+inner_loop: false
+message_types:
+  success: scan_ready
+  error: error
+  issues: issues_found
+---
+
+# Multi-Perspective Scout
+
+Scan codebase from multiple perspectives (bug, security, test-coverage, code-quality, UX) to discover potential issues. Produce structured scan results with severity-ranked findings.
+
+## Phase 2: Context & Scope Assessment
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | No |
+
+1. Extract session path and target scope from task description
+2. Determine scan scope: explicit scope from task or `**/*` default
+3. Get recent changed files: `git diff --name-only HEAD~5 2>/dev/null || echo ""`
+4. Read .msg/meta.json for historical defect patterns (`defect_patterns`)
+5. Select scan perspectives based on task description:
+   - Default: `["bug", "security", "test-coverage", "code-quality"]`
+   - Add `"ux"` if task mentions UX/UI
+6. Assess complexity to determine scan strategy:
+
+| Complexity | Condition | Strategy |
+|------------|-----------|----------|
+| Low | < 5 changed files, no specific keywords | ACE search + Grep inline |
+| Medium | 5-15 files or specific perspective requested | CLI fan-out (3 core perspectives) |
+| High | > 15 files or full-project scan | CLI fan-out (all perspectives) |
+
+## Phase 3: Multi-Perspective Scan
+
+**Low complexity**: Use `mcp__ace-tool__search_context` for quick pattern-based scan.
+
+**Medium/High complexity**: CLI fan-out -- one `maestro cli --mode analysis` per perspective:
+
+For each active perspective, build prompt:
+```
+PURPOSE: Scan code from <perspective> perspective to discover potential issues
+TASK: Analyze code patterns for <perspective> problems, identify anti-patterns, check for common issues
+MODE: analysis
+CONTEXT: @<scan-scope>
+EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
+CONSTRAINTS: Focus on actionable findings only
+```
+Execute via: `maestro cli -p "<prompt>" --tool gemini --mode analysis`
+
+After all perspectives complete:
+- Parse CLI outputs into structured findings
+- Deduplicate by file:line (merge perspectives for same location)
+- Compare against known defect patterns from .msg/meta.json
+- Rank by severity: critical > high > medium > low
+
+## Phase 4: Result Aggregation
+
+1. Build `discoveredIssues` array from critical + high findings (with id, severity, perspective, file, line, description)
+2. Write scan results to `<session>/scan/scan-results.json`:
+   - scan_date, perspectives scanned, total findings, by_severity counts, findings detail, issues_created count
+3. Update `<session>/wisdom/.msg/meta.json`: merge `discovered_issues` field
+4. Contribute to wisdom/issues.md if new patterns found

package/.claude/skills/team-quality-assurance/roles/strategist/role.md

@@ -0,0 +1,71 @@
+---
+role: strategist
+prefix: QASTRAT
+inner_loop: false
+message_types:
+  success: strategy_ready
+  error: error
+---
+
+# Test Strategist
+
+Analyze change scope, determine test layers (L1-L3), define coverage targets, and generate test strategy document. Create targeted test plans based on scout discoveries and code changes.
+
+## Phase 2: Context & Change Analysis
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| .msg/meta.json | <session>/wisdom/.msg/meta.json | Yes |
+| Discovered issues | meta.json -> discovered_issues | No |
+| Defect patterns | meta.json -> defect_patterns | No |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for scout discoveries and historical patterns
+3. Analyze change scope: `git diff --name-only HEAD~5`
+4. Categorize changed files:
+
+| Category | Pattern |
+|----------|---------|
+| Source | `\.(ts|tsx|js|jsx|py|java|go|rs)$` |
+| Test | `\.(test|spec)\.(ts|tsx|js|jsx)$` or `test_` |
+| Config | `\.(json|yaml|yml|toml|env)$` |
+
+5. Detect test framework from package.json / project files
+6. Check existing coverage baseline from `coverage/coverage-summary.json`
+7. Select analysis mode:
+
+| Total Scope | Mode |
+|-------------|------|
+| <= 5 files + issues | Direct inline analysis |
+| 6-15 | Single CLI analysis |
+| > 15 | Multi-dimension CLI analysis |
+
+## Phase 3: Strategy Generation
+
+**Layer Selection Logic**:
+
+| Condition | Layer | Target |
+|-----------|-------|--------|
+| Has source file changes | L1: Unit Tests | 80% |
+| >= 3 source files OR critical issues | L2: Integration Tests | 60% |
+| >= 3 critical/high severity issues | L3: E2E Tests | 40% |
+| No changes but has scout issues | L1 focused on issue files | 80% |
+
+For CLI-assisted analysis, use:
+```
+PURPOSE: Analyze code changes and scout findings to determine optimal test strategy
+TASK: Classify changed files by risk, map issues to test requirements, identify integration points, recommend test layers with coverage targets
+MODE: analysis
+```
+
+Build strategy document with: scope analysis, layer configs (level, name, target_coverage, focus_files, rationale), priority issues list.
+
+**Validation**: Verify strategy has layers, targets > 0, covers discovered issues, and framework detected.
+
+## Phase 4: Output & Persistence
+
+1. Write strategy to `<session>/strategy/test-strategy.md`
+2. Update `<session>/wisdom/.msg/meta.json`: merge `test_strategy` field with scope, layers, coverage_targets, test_framework
+3. Contribute to wisdom/decisions.md with layer selection rationale

package/.claude/skills/team-quality-assurance/specs/pipelines.md

@@ -0,0 +1,115 @@
+# QA Pipelines
+
+Pipeline definitions and task registry for team-quality-assurance.
+
+## Pipeline Modes
+
+| Mode | Description | Entry Role |
+|------|-------------|------------|
+| discovery | Scout-first: issue discovery then testing | scout |
+| testing | Skip scout, direct test pipeline | strategist |
+| full | Complete QA closed loop + regression scan | scout |
+
+## Pipeline Definitions
+
+### Discovery Mode (5 tasks, serial)
+
+```
+SCOUT-001 -> QASTRAT-001 -> QAGEN-001 -> QARUN-001 -> QAANA-001
+```
+
+| Task ID | Role | Dependencies | Description |
+|---------|------|-------------|-------------|
+| SCOUT-001 | scout | (none) | Multi-perspective issue scanning |
+| QASTRAT-001 | strategist | SCOUT-001 | Change scope analysis + test strategy |
+| QAGEN-001 | generator | QASTRAT-001 | L1 unit test generation |
+| QARUN-001 | executor | QAGEN-001 | L1 test execution + fix cycles |
+| QAANA-001 | analyst | QARUN-001 | Defect pattern analysis + quality report |
+
+### Testing Mode (6 tasks, progressive layers)
+
+```
+QASTRAT-001 -> QAGEN-L1-001 -> QARUN-L1-001 -> QAGEN-L2-001 -> QARUN-L2-001 -> QAANA-001
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| QASTRAT-001 | strategist | (none) | — | Test strategy formulation |
+| QAGEN-L1-001 | generator | QASTRAT-001 | L1 | L1 unit test generation |
+| QARUN-L1-001 | executor | QAGEN-L1-001 | L1 | L1 test execution + fix cycles |
+| QAGEN-L2-001 | generator | QARUN-L1-001 | L2 | L2 integration test generation |
+| QARUN-L2-001 | executor | QAGEN-L2-001 | L2 | L2 test execution + fix cycles |
+| QAANA-001 | analyst | QARUN-L2-001 | — | Quality analysis report |
+
+### Full Mode (8 tasks, parallel windows + regression)
+
+```
+SCOUT-001 -> QASTRAT-001 -> [QAGEN-L1-001 || QAGEN-L2-001] -> [QARUN-L1-001 || QARUN-L2-001] -> QAANA-001 -> SCOUT-002
+```
+
+| Task ID | Role | Dependencies | Layer | Description |
+|---------|------|-------------|-------|-------------|
+| SCOUT-001 | scout | (none) | — | Multi-perspective issue scanning |
+| QASTRAT-001 | strategist | SCOUT-001 | — | Test strategy formulation |
+| QAGEN-L1-001 | generator-1 | QASTRAT-001 | L1 | L1 unit test generation (parallel) |
+| QAGEN-L2-001 | generator-2 | QASTRAT-001 | L2 | L2 integration test generation (parallel) |
+| QARUN-L1-001 | executor-1 | QAGEN-L1-001 | L1 | L1 test execution + fix cycles (parallel) |
+| QARUN-L2-001 | executor-2 | QAGEN-L2-001 | L2 | L2 test execution + fix cycles (parallel) |
+| QAANA-001 | analyst | QARUN-L1-001, QARUN-L2-001 | — | Quality analysis report |
+| SCOUT-002 | scout | QAANA-001 | — | Regression scan after fixes |
+
+## GC Loop
+
+Generator-Executor iterate per test layer until coverage targets are met:
+
+```
+QAGEN -> QARUN -> (if coverage < target) -> QAGEN-fix -> QARUN-gc
+                  (if coverage >= target) -> next layer or QAANA
+```
+
+- Max iterations: 3 per layer
+- After 3 iterations: accept current coverage with warning
+
+## Coverage Targets
+
+| Layer | Name | Default Target |
+|-------|------|----------------|
+| L1 | Unit Tests | 80% |
+| L2 | Integration Tests | 60% |
+| L3 | E2E Tests | 40% |
+
+## Scan Perspectives
+
+| Perspective | Focus |
+|-------------|-------|
+| bug | Logic errors, crash paths, null references |
+| security | Vulnerabilities, auth bypass, data exposure |
+| test-coverage | Untested code paths, missing assertions |
+| code-quality | Anti-patterns, complexity, maintainability |
+| ux | User-facing issues, accessibility (optional) |
+
+## Session Directory
+
+```
+.workflow/.team/QA-<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/                       # Scout output
+│   └── scan-results.json
+├── strategy/                   # Strategist output
+│   └── test-strategy.md
+├── tests/                      # Generator output
+│   ├── L1-unit/
+│   ├── L2-integration/
+│   └── L3-e2e/
+├── results/                    # Executor output
+│   ├── run-001.json
+│   └── coverage-001.json
+└── analysis/                   # Analyst output
+    └── quality-report.md
+```

package/.claude/skills/team-quality-assurance/specs/team-config.json

@@ -0,0 +1,131 @@
+{
+  "team_name": "quality-assurance",
+  "version": "1.0.0",
+  "description": "质量保障团队 - 融合\"软件测试\"和\"问题发现\"两大能力域，形成发现→验证→修复→回归的闭环",
+  "skill_entry": "team-quality-assurance",
+  "invocation": "Skill(skill=\"team-quality-assurance\", args=\"--role=coordinator ...\")",
+
+  "roles": {
+    "coordinator": {
+      "name": "coordinator",
+      "responsibility": "Orchestration",
+      "task_prefix": null,
+      "description": "QA 团队协调者。编排 pipeline：需求澄清 → 模式选择 → 团队创建 → 任务分发 → 监控协调 → 质量门控 → 结果汇报",
+      "message_types_sent": ["mode_selected", "gc_loop_trigger", "quality_gate", "task_unblocked", "error", "shutdown"],
+      "message_types_received": ["scan_ready", "issues_found", "strategy_ready", "tests_generated", "tests_revised", "tests_passed", "tests_failed", "analysis_ready", "quality_report", "error"],
+      "commands": ["dispatch", "monitor"]
+    },
+    "scout": {
+      "name": "scout",
+      "responsibility": "Orchestration (多视角扫描编排)",
+      "task_prefix": "SCOUT-*",
+      "description": "多视角问题侦察员。主动扫描代码库，从 bug、安全、UX、测试覆盖、代码质量等多个视角发现潜在问题",
+      "message_types_sent": ["scan_ready", "issues_found", "error"],
+      "message_types_received": [],
+      "commands": ["scan"],
+      "cli_tools": ["gemini"],
+      "cli_tools": ["gemini"]
+    },
+    "strategist": {
+      "name": "strategist",
+      "responsibility": "Orchestration (策略制定)",
+      "task_prefix": "QASTRAT-*",
+      "description": "测试策略师。分析变更范围，确定测试层级（L1-L3），定义覆盖率目标",
+      "message_types_sent": ["strategy_ready", "error"],
+      "message_types_received": [],
+      "commands": ["analyze-scope"],
+      "cli_tools": ["gemini"],
+      "cli_tools": ["gemini"]
+    },
+    "generator": {
+      "name": "generator",
+      "responsibility": "Code generation (测试代码生成)",
+      "task_prefix": "QAGEN-*",
+      "description": "测试用例生成器。按策略和层级生成测试代码，支持 L1/L2/L3",
+      "message_types_sent": ["tests_generated", "tests_revised", "error"],
+      "message_types_received": [],
+      "commands": ["generate-tests"],
+      "cli_tools": ["gemini"],
+      "cli_tools": ["gemini"]
+    },
+    "executor": {
+      "name": "executor",
+      "responsibility": "Validation (测试执行与修复)",
+      "task_prefix": "QARUN-*",
+      "description": "测试执行者。运行测试套件，收集覆盖率数据，失败时自动修复循环",
+      "message_types_sent": ["tests_passed", "tests_failed", "coverage_report", "error"],
+      "message_types_received": [],
+      "commands": ["run-fix-cycle"],
+      "cli_tools": ["gemini"]
+    },
+    "analyst": {
+      "name": "analyst",
+      "responsibility": "Read-only analysis (质量分析)",
+      "task_prefix": "QAANA-*",
+      "description": "质量分析师。分析缺陷模式、覆盖率差距、测试有效性，生成综合质量报告",
+      "message_types_sent": ["analysis_ready", "quality_report", "error"],
+      "message_types_received": [],
+      "commands": ["quality-report"],
+      "cli_tools": ["gemini"]
+    }
+  },
+
+  "pipeline_modes": {
+    "discovery": {
+      "description": "Scout先行扫描 → 全流程",
+      "stages": ["SCOUT", "QASTRAT", "QAGEN", "QARUN", "QAANA"],
+      "entry_role": "scout"
+    },
+    "testing": {
+      "description": "跳过 Scout → 直接测试",
+      "stages": ["QASTRAT", "QAGEN-L1", "QARUN-L1", "QAGEN-L2", "QARUN-L2", "QAANA"],
+      "entry_role": "strategist"
+    },
+    "full": {
+      "description": "完整 QA 闭环 + 回归扫描",
+      "stages": ["SCOUT", "QASTRAT", "QAGEN-L1", "QAGEN-L2", "QARUN-L1", "QARUN-L2", "QAANA", "SCOUT-REG"],
+      "entry_role": "scout",
+      "parallel_stages": [["QAGEN-L1", "QAGEN-L2"], ["QARUN-L1", "QARUN-L2"]]
+    }
+  },
+
+  "gc_loop": {
+    "max_iterations": 3,
+    "trigger": "coverage < target",
+    "participants": ["generator", "executor"],
+    "flow": "QAGEN-fix → QARUN-gc → evaluate"
+  },
+
+  "shared_memory": {
+    "file": "shared-memory.json",
+    "fields": {
+      "discovered_issues": { "owner": "scout", "type": "array" },
+      "test_strategy": { "owner": "strategist", "type": "object" },
+      "generated_tests": { "owner": "generator", "type": "object" },
+      "execution_results": { "owner": "executor", "type": "object" },
+      "defect_patterns": { "owner": "analyst", "type": "array" },
+      "coverage_history": { "owner": "analyst", "type": "array" },
+      "quality_score": { "owner": "analyst", "type": "number" }
+    }
+  },
+
+  "collaboration_patterns": [
+    "CP-1: Linear Pipeline (Discovery/Testing mode)",
+    "CP-2: Review-Fix Cycle (GC loop: Generator ↔ Executor)",
+    "CP-3: Fan-out (Scout multi-perspective scan)",
+    "CP-5: Escalation (Worker → Coordinator → User)",
+    "CP-9: Dual-Track (Full mode: L1 + L2 parallel)",
+    "CP-10: Post-Mortem (Analyst quality report)"
+  ],
+
+  "session_directory": {
+    "pattern": ".workflow/.team/QA-{slug}-{date}",
+    "subdirectories": ["scan", "strategy", "results", "analysis"]
+  },
+
+  "test_layers": {
+    "L1": { "name": "Unit Tests", "default_target": 80 },
+    "L2": { "name": "Integration Tests", "default_target": 60 },
+    "L3": { "name": "E2E Tests", "default_target": 40 }
+  }
+}

package/.claude/skills/team-review/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: 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(*), mcp__ccw-tools__team_msg(*)
+---
+
+# Team Review
+
+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.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  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
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `RV`
+- **Session path**: `.workflow/.team/RV-<slug>-<date>/`
+- **Team name**: `review`
+- **CLI tools**: `maestro cli --mode analysis` (read-only), `maestro cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "review",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: review
+requirement: <task-description>
+inner_loop: <true|false>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final SendMessage.
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View 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 pipeline completes, coordinator presents:
+
+```
+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 team" },
+      { label: "Keep Active", description: "Keep session for follow-up work" },
+      { label: "Export Results", description: "Export deliverables to target directory" }
+    ]
+  }]
+})
+```
+
+## Session Directory
+
+```
+.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 |
+| 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 |