maestro-flow 0.4.9 → 0.4.11

package/.agents/skills/team-review/roles/fixer/role.md

@@ -0,0 +1,78 @@
+---
+role: fixer
+prefix: FIX
+inner_loop: true
+message_types:
+  success: fix_complete
+  error: fix_failed
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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

package/.agents/skills/team-review/roles/reviewer/role.md

@@ -0,0 +1,70 @@
+---
+role: reviewer
+prefix: REV
+inner_loop: false
+message_types:
+  success: review_complete
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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 review specs: Run `ccw spec load --category review` for review standards, checklists, and approval gates
+3. 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 `maestro delegate --role review --mode analysis --rule analysis-diagnose-bug-root-cause`. 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

package/.agents/skills/team-review/roles/scanner/role.md

@@ -0,0 +1,81 @@
+---
+role: scanner
+prefix: SCAN
+inner_loop: false
+message_types:
+  success: scan_complete
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# 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 `maestro delegate --role review --mode analysis --rule analysis-review-code-quality`. 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`.
+
+### Tech Profile Scan
+
+After scan execution, emit context-aware trigger signals (based on detected codebase characteristics):
+
+1. Check security findings → signals (`injection_risk`, `eval_usage`, `sql_detected`, `auth_detected`)
+2. Check quality findings → risk signals (`legacy_patterns`, `test_gap`, `perf_sensitive`)
+3. Include `tech_profile` in Phase 5 state_update data
+
+## 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

package/.agents/skills/team-review/specs/dimensions.md

@@ -0,0 +1,82 @@
+# Review Dimensions (4-Dimension System)
+
+## Security (SEC)
+
+Vulnerabilities, attack surfaces, and data protection issues.
+
+**Categories**: injection, authentication, authorization, data-exposure, encryption, input-validation, access-control
+
+**Tool Support**: Semgrep (`--config auto`), npm audit, tsc strict mode
+**LLM Focus**: Business logic vulnerabilities, privilege escalation paths, sensitive data flows
+
+**Severity Mapping**:
+- Critical: RCE, SQL injection, auth bypass, data breach
+- High: XSS, CSRF, insecure deserialization, weak crypto
+- Medium: Missing input validation, overly permissive CORS
+- Low: Informational headers, minor config issues
+
+---
+
+## Correctness (COR)
+
+Bugs, logic errors, and type safety issues.
+
+**Categories**: bug, error-handling, edge-case, type-safety, race-condition, null-reference
+
+**Tool Support**: tsc `--noEmit`, ESLint error-level rules
+**LLM Focus**: Logic errors, unhandled exception paths, state management bugs, race conditions
+
+**Severity Mapping**:
+- Critical: Data corruption, crash in production path
+- High: Incorrect business logic, unhandled error in common path
+- Medium: Edge case not handled, missing null check
+- Low: Minor type inconsistency, unused variable
+
+---
+
+## Performance (PRF)
+
+Inefficiencies, resource waste, and scalability issues.
+
+**Categories**: n-plus-one, memory-leak, blocking-operation, complexity, resource-usage, caching
+
+**Tool Support**: None (LLM-only dimension)
+**LLM Focus**: Algorithm complexity, N+1 queries, unnecessary sync operations, memory leaks, missing caching
+
+**Severity Mapping**:
+- Critical: Memory leak in long-running process, O(n³) on user data
+- High: N+1 query in hot path, blocking I/O in async context
+- Medium: Suboptimal algorithm, missing obvious cache
+- Low: Minor inefficiency, premature optimization opportunity
+
+---
+
+## Maintainability (MNT)
+
+Code quality, readability, and structural health.
+
+**Categories**: code-smell, naming, complexity, duplication, dead-code, pattern-violation, coupling
+
+**Tool Support**: ESLint warning-level rules, complexity metrics
+**LLM Focus**: Architectural coupling, abstraction leaks, project convention violations
+
+**Severity Mapping**:
+- High: God class, circular dependency, copy-paste across modules
+- Medium: Long method, magic numbers, unclear naming
+- Low: Minor style inconsistency, commented-out code
+- Info: Pattern observation, refactoring suggestion
+
+---
+
+## Why 4 Dimensions (Not 7)
+
+The original review-cycle used 7 dimensions with significant overlap:
+
+| Original | Problem | Merged Into |
+|----------|---------|-------------|
+| Quality | Overlaps Maintainability + Best-Practices | **Maintainability** |
+| Best-Practices | Overlaps Quality + Maintainability | **Maintainability** |
+| Architecture | Overlaps Maintainability (coupling/layering) | **Maintainability** (structure) + **Security** (security architecture) |
+| Action-Items | Not a dimension — it's a report format | Standard field on every finding |
+
+4 dimensions = clear ownership, no overlap, each maps to distinct tooling.

package/.agents/skills/team-review/specs/finding-schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Finding",
+  "description": "Standardized finding format for team-review pipeline",
+  "type": "object",
+  "required": ["id", "dimension", "category", "severity", "title", "description", "location", "source", "effort", "confidence"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^(SEC|COR|PRF|MNT)-\\d{3}$",
+      "description": "{DIM_PREFIX}-{SEQ}"
+    },
+    "dimension": {
+      "type": "string",
+      "enum": ["security", "correctness", "performance", "maintainability"]
+    },
+    "category": {
+      "type": "string",
+      "description": "Sub-category within the dimension"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["critical", "high", "medium", "low", "info"]
+    },
+    "title": { "type": "string" },
+    "description": { "type": "string" },
+    "location": {
+      "type": "object",
+      "required": ["file", "line"],
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer" },
+        "end_line": { "type": "integer" },
+        "code_snippet": { "type": "string" }
+      }
+    },
+    "source": {
+      "type": "string",
+      "description": "tool:eslint | tool:tsc | tool:semgrep | llm | tool+llm"
+    },
+    "tool_rule": { "type": ["string", "null"] },
+    "suggested_fix": { "type": "string" },
+    "references": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "effort": { "type": "string", "enum": ["low", "medium", "high"] },
+    "confidence": { "type": "string", "enum": ["high", "medium", "low"] },
+    "root_cause": {
+      "type": ["object", "null"],
+      "description": "Populated by reviewer role",
+      "properties": {
+        "description": { "type": "string" },
+        "related_findings": { "type": "array", "items": { "type": "string" } },
+        "is_symptom": { "type": "boolean" }
+      }
+    },
+    "impact": {
+      "type": ["object", "null"],
+      "properties": {
+        "scope": { "type": "string", "enum": ["low", "medium", "high"] },
+        "affected_files": { "type": "array", "items": { "type": "string" } },
+        "blast_radius": { "type": "string" }
+      }
+    },
+    "optimization": {
+      "type": ["object", "null"],
+      "properties": {
+        "approach": { "type": "string" },
+        "alternative": { "type": "string" },
+        "tradeoff": { "type": "string" }
+      }
+    },
+    "fix_strategy": { "type": ["string", "null"], "enum": ["minimal", "refactor", "skip", null] },
+    "fix_complexity": { "type": ["string", "null"], "enum": ["low", "medium", "high", null] },
+    "fix_dependencies": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": []
+    }
+  }
+}

package/.agents/skills/team-review/specs/pipelines.md

@@ -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
+```

package/.agents/skills/team-review/specs/team-config.json

@@ -0,0 +1,27 @@
+{
+  "name": "team-review",
+  "description": "Code scanning, vulnerability review, optimization suggestions, and automated fix",
+  "sessionDir": ".workflow/.team-review/",
+  "msgDir": ".workflow/.team-msg/team-review/",
+  "roles": {
+    "coordinator": { "prefix": "RC", "type": "orchestration", "file": "roles/coordinator/role.md" },
+    "scanner":     { "prefix": "SCAN", "type": "read-only-analysis", "file": "roles/scanner/role.md" },
+    "reviewer":    { "prefix": "REV", "type": "read-only-analysis", "file": "roles/reviewer/role.md" },
+    "fixer":       { "prefix": "FIX", "type": "code-generation", "file": "roles/fixer/role.md" }
+  },
+  "collaboration_pattern": "CP-1",
+  "pipeline": ["scanner", "reviewer", "fixer"],
+  "dimensions": {
+    "security":        { "prefix": "SEC", "tools": ["semgrep", "npm-audit"] },
+    "correctness":     { "prefix": "COR", "tools": ["tsc", "eslint-error"] },
+    "performance":     { "prefix": "PRF", "tools": [] },
+    "maintainability": { "prefix": "MNT", "tools": ["eslint-warning"] }
+  },
+  "severity_levels": ["critical", "high", "medium", "low", "info"],
+  "defaults": {
+    "max_deep_analysis": 15,
+    "max_quick_findings": 20,
+    "max_parallel_fixers": 3,
+    "quick_fix_threshold": 5
+  }
+}

package/.agents/skills/team-tech-debt/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: team-tech-debt
+description: Unified team skill for tech debt identification and remediation. Scans codebase for tech debt, assesses severity, plans and executes fixes with validation. Uses team-worker agent architecture with roles/ for domain logic. Coordinator orchestrates pipeline, workers are team-worker agents. Triggers on "team tech debt".
+allowed-tools: delegate_subagent, ask_user, read_file, write_file, edit_file, shell, find_files, search, list_tasks, get_task, update_task, create_task, create_team, delete_team, send_message, mcp__ace-tool__search_context, mcp__ccw-tools__read_file, mcp__ccw-tools__write_file, mcp__ccw-tools__edit_file, mcp__ccw-tools__team_msg
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team Tech Debt
+
+Systematic tech debt governance: scan -> assess -> plan -> fix -> validate. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from `roles/<role>/role.md`.
+
+## Architecture
+
+```
+invoke_skill(skill="team-tech-debt", 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       v       v
+           [team-worker agents, each loads roles/<role>/role.md]
+          scanner  assessor  planner  executor  validator
+```
+
+## 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) | TDSCAN-* | false |
+| assessor | [roles/assessor/role.md](roles/assessor/role.md) | TDEVAL-* | false |
+| planner | [roles/planner/role.md](roles/planner/role.md) | TDPLAN-* | false |
+| executor | [roles/executor/role.md](roles/executor/role.md) | TDFIX-* | true |
+| validator | [roles/validator/role.md](roles/validator/role.md) | TDVAL-* | false |
+
+## 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**: `TD`
+- **Session path**: `.workflow/.team/TD-<slug>-<date>/`
+- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+- **Max GC rounds**: 3
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker for <task-id>",
+  team_name: "tech-debt",
+  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: tech-debt
+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 send_message.
+
+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 execution status graph |
+| `resume` / `continue` | Advance to next step |
+| `--mode=scan` | Run scan-only pipeline (TDSCAN + TDEVAL) |
+| `--mode=targeted` | Run targeted pipeline (TDPLAN + TDFIX + TDVAL) |
+| `--mode=remediate` | Run full pipeline (default) |
+| `-y` / `--yes` | Skip confirmations |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
+
+## Session Directory
+
+```
+.workflow/.team/TD-<slug>-<date>/
+├── .msg/
+│   ├── messages.jsonl      # Team message bus
+│   └── meta.json           # Pipeline config + role state snapshot
+├── scan/                   # Scanner output
+├── assessment/             # Assessor output
+├── plan/                   # Planner output
+├── fixes/                  # Executor output
+├── validation/             # Validator output
+└── wisdom/                 # Cross-task knowledge
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| Scanner finds no debt | Report clean codebase, skip to summary |