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.
2026-03-10 17:11:04 +08:00 · 2026-03-07 13:32:04 +08:00
parent 7ee9b579fa
commit 29a1fea467
255 changed files with 14407 additions and 21120 deletions
--- a/.claude/skills/team-tech-debt/SKILL.md
+++ b/.claude/skills/team-tech-debt/SKILL.md
@@ -1,287 +1,74 @@
 ---
 name: team-tech-debt
-description: Unified team skill for tech debt identification and cleanup. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team tech-debt", "tech debt cleanup", "技术债务".
-allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
+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: Agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, TaskList, TaskGet, TaskUpdate, TaskCreate, TeamCreate, TeamDelete, SendMessage, 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
 ---

 # Team Tech Debt

-技术债务识别与清理团队。融合"债务扫描"、"量化评估"、"治理规划"、"清理执行"、"验证回归"五大能力域，形成"扫描->评估->规划->清理->验证"闭环。通过 Scanner 多维度扫描、Executor-Validator 修复验证循环、共享债务清单数据库，实现渐进式技术债务治理。所有成员通过 `--role=xxx` 路由到角色执行逻辑。
+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 Overview
+## Architecture

 ```
-+---------------------------------------------------+
-|  Skill(skill="team-tech-debt")                     |
-|  args="<task-description>"                         |
-+-------------------+-------------------------------+
+Skill(skill="team-tech-debt", args="task description")
                    |
-         Orchestration Mode (auto -> coordinator)
+         SKILL.md (this file) = Router
                    |
-              Coordinator (inline)
-              Phase 0-5 orchestration
-                    |
-    +-----+-----+-----+-----+-----+
-    v     v     v     v     v
- [tw]  [tw]  [tw]  [tw]  [tw]
-scann- asses- plan-  execu- valid-
-er     sor    ner    tor    ator
-
-(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       v       v
+           [team-worker agents, each loads roles/<role>/role.md]
+          scanner  assessor  planner  executor  validator
 ```

-## Command Architecture
+## Role Registry

-```
-roles/
-├── coordinator/
-│   ├── role.md              # Pipeline 编排（模式选择、任务分发、监控）
-│   └── commands/
-│       ├── dispatch.md      # 任务链创建
-│       └── monitor.md       # 进度监控
-├── scanner/
-│   ├── role.md              # 多维度技术债务扫描
-│   └── commands/
-│       └── scan-debt.md     # 多维度 CLI Fan-out 扫描
-├── assessor/
-│   ├── role.md              # 量化评估与优先级排序
-│   └── commands/
-│       └── evaluate.md      # 影响/成本矩阵评估
-├── planner/
-│   ├── role.md              # 治理方案规划
-│   └── commands/
-│       └── create-plan.md   # 分阶段治理方案生成
-├── executor/
-│   ├── role.md              # 债务清理执行
-│   └── commands/
-│       └── remediate.md     # 重构/清理/更新执行
-└── validator/
-    ├── role.md              # 清理结果验证
-    └── commands/
-        └── verify.md        # 回归测试与质量验证
-```
-
-**设计原则**: role.md 保留 Phase 1（Task Discovery）和 Phase 5（Report）内联。Phase 2-4 根据复杂度决定内联或委派到 `commands/*.md`。
+| 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

-### 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` and optional `--agent-name`, `--mode` (scan/remediate/targeted).
+## Shared Constants

-If no `--role` -> Orchestration Mode (auto route to coordinator).
+- **Session prefix**: `TD`
+- **Session path**: `.workflow/.team/TD-<slug>-<date>/`
+- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+- **Max GC rounds**: 3

-### Role Registry
+## Worker Spawn Template

-| 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) | TDSCAN-* | false |
-| assessor | [role-specs/assessor.md](role-specs/assessor.md) | TDEVAL-* | false |
-| planner | [role-specs/planner.md](role-specs/planner.md) | TDPLAN-* | false |
-| executor | [role-specs/executor.md](role-specs/executor.md) | TDFIX-* | true |
-| validator | [role-specs/validator.md](role-specs/validator.md) | TDVAL-* | false |
-
-> **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
-4. Unknown role -> Error with available role list: coordinator, scanner, assessor, planner, executor, validator
-
-### Orchestration Mode
-
-当不带 `--role` 调用时，自动进入 coordinator 编排模式。
-
-**触发方式**:
-
- 用户调用（无 --role）: `Skill(skill="team-tech-debt", args="扫描并清理项目中的技术债务")`
- 等价于: `Skill(skill="team-tech-debt", args="--role=coordinator 扫描并清理项目中的技术债务")`
-
-**完整调用链**:
-
-```
-用户: Skill(args="任务描述")
-  │
-  ├─ SKILL.md: 无 --role -> Orchestration Mode -> 读取 coordinator role.md
-  │
-  ├─ coordinator Phase 2: TeamCreate + 模式选择
-  │   按 pipeline 阶段逐个 spawn worker（同步阻塞）
-  │
-  ├─ coordinator Phase 3: dispatch 任务链
-  │
-  ├─ worker 收到任务 -> Skill(args="--role=xxx") -> SKILL.md Role Router -> role.md
-  │   每个 worker 自动获取:
-  │   ├─ 角色定义 (role.md: identity, boundaries, message types)
-  │   ├─ 可用命令 (commands/*.md)
-  │   └─ 执行逻辑 (5-phase process)
-  │
-  └─ coordinator Phase 4-5: 监控 -> 结果汇报
-```
-
-**User Commands** (唤醒已暂停的 coordinator):
-
-| Command | Action |
-|---------|--------|
-| `check` / `status` | 输出执行状态图，不推进 |
-| `resume` / `continue` | 检查 worker 状态，推进下一步 |
-
---
-
-## Shared Infrastructure
-
-> 以下为编排级概览。具体实现代码（Message Bus、Task Lifecycle、工具方法）在各 role.md 中自包含。
-
-### Team Configuration
-
-| Key | Value |
-|-----|-------|
-| name | tech-debt |
-| sessionDir | `.workflow/.team/TD-{slug}-{date}/` |
-| sharedMemory | team_msg(type="state_update") + .msg/meta.json |
-| worktree.basePath | `.worktrees` |
-| worktree.branchPrefix | `tech-debt/TD-` |
-| worktree.autoCleanup | true (remove worktree after PR creation) |
-| debtDimensions | code, architecture, testing, dependency, documentation |
-| priorityMatrix.highImpact_lowCost | 立即修复 (Quick Win) |
-| priorityMatrix.highImpact_highCost | 战略规划 (Strategic) |
-| priorityMatrix.lowImpact_lowCost | 待办处理 (Backlog) |
-| priorityMatrix.lowImpact_highCost | 暂缓接受 (Defer) |
-
-### Role Isolation Rules
-
-**核心原则**: 每个角色仅能执行自己职责范围内的工作。
-
-#### Output Tagging（强制）
-
-所有角色的输出必须带 `[role_name]` 标识前缀。
-
-#### Coordinator 隔离
-
-| 允许 | 禁止 |
-|------|------|
-| 需求澄清 (AskUserQuestion) | 直接扫描代码 |
-| 创建任务链 (TaskCreate) | 直接执行重构或清理 |
-| 模式选择 + 质量门控 | 直接评估或规划 |
-| 监控进度 (消息总线) | 绕过 worker 自行完成 |
-
-#### Worker 隔离
-
-| 允许 | 禁止 |
-|------|------|
-| 处理自己前缀的任务 | 处理其他角色前缀的任务 |
-| Share state via team_msg(type='state_update') | 为其他角色创建任务 |
-| SendMessage 给 coordinator | 直接与其他 worker 通信 |
-
-### Worker Phase 1: Task Discovery (所有 worker 共享)
-
-每个 worker 启动后执行相同的任务发现流程：
-
-1. 调用 `TaskList()` 获取所有任务
-2. 筛选: subject 匹配本角色前缀 + owner 是本角色 + status 为 pending + blockedBy 为空
-3. 无任务 -> idle 等待
-4. 有任务 -> `TaskGet` 获取详情 -> `TaskUpdate` 标记 in_progress
-
-**Resume Artifact Check** (防止恢复后重复产出):
- 检查本任务的输出产物是否已存在
- 产物完整 -> 跳到 Phase 5 报告完成
- 产物不完整或不存在 -> 正常执行 Phase 2-4
-
-### Worker Phase 5: Report (所有 worker 共享)
-
-任务完成后的标准报告流程:
-
-1. **Message Bus**: 调用 `mcp__ccw-tools__team_msg` 记录消息
-   - 参数: operation="log", session_id=<session-id>, from=`<role>`, type=`<消息类型>`, data={ref: "`<产物路径>`"}
-   - `to` 和 `summary` 自动生成 -- 无需显式指定
-   - **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --json`
-2. **SendMessage**: 发送结果给 coordinator
-3. **TaskUpdate**: 标记任务 completed
-4. **Loop**: 回到 Phase 1 检查下一个任务
-
---
-
-## Three-Mode Pipeline Architecture
-
-```
-Scan Mode (仅扫描评估):
-  TDSCAN-001(并行多维度扫描+多视角Gemini分析) -> TDEVAL-001(量化评估) -> 报告
-
-Remediate Mode (完整闭环):
-  TDSCAN-001(并行扫描) -> TDEVAL-001(评估) -> TDPLAN-001(规划) -> [Plan Approval] -> [Create Worktree] -> TDFIX-001(修复,worktree) -> TDVAL-001(验证,worktree) -> [Commit+PR] -> 报告
-
-Targeted Mode (定向修复):
-  TDPLAN-001(规划) -> [Plan Approval] -> [Create Worktree] -> TDFIX-001(修复,worktree) -> TDVAL-001(验证,worktree) -> [Commit+PR] -> 报告
-```
-
-### TDSCAN Parallel Fan-out Architecture
-
-```
-TDSCAN-001 内部并行架构:
-
-         ┌────────────────────────────────────────────────────┐
-         │                  Scanner Worker                     │
-         │                                                     │
-         │  Fan-out A: CLI Exploration (parallel CLI explore)    │
-         │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
-         │  │structure  │ │patterns  │ │deps      │            │
-         │  │角度       │ │角度      │ │角度      │             │
-         │  └─────┬────┘ └─────┬────┘ └─────┬────┘            │
-         │        └────────────┼────────────┘                  │
-         │                     ↓ merge                         │
-         │  Fan-out B: CLI Dimension Analysis (并行 gemini)    │
-         │  ┌──────┐┌────────┐┌───────┐┌──────┐┌─────┐        │
-         │  │code  ││arch    ││testing││deps  ││docs │         │
-         │  └──┬───┘└───┬────┘└──┬────┘└──┬───┘└──┬──┘        │
-         │     └────────┼────────┼────────┘       │            │
-         │              ↓ merge                   │            │
-         │  Fan-out C: Multi-Perspective Gemini (并行)         │
-         │  ┌────────┐┌──────────┐┌───────┐┌─────────┐        │
-         │  │security││perform.  ││quality││architect│         │
-         │  └───┬────┘└────┬─────┘└──┬────┘└────┬────┘        │
-         │      └──────────┼─────────┘          │              │
-         │                 ↓ Fan-in aggregate                  │
-         │            debt-inventory.json                      │
-         └────────────────────────────────────────────────────┘
-```
-
-### Mode Auto-Detection
-
-| Condition | Detected Mode |
-|-----------|--------------|
-| `--mode=scan` explicitly specified | scan |
-| `--mode=remediate` explicitly specified | remediate |
-| `--mode=targeted` explicitly specified | targeted |
-| Task description contains: 扫描, scan, 审计, audit, 评估, assess | scan |
-| Task description contains: 定向, targeted, 指定, specific, 修复已知 | targeted |
-| Default (no match) | remediate |
-
-### Fix-Verify Loop
-
-```
-TDFIX -> TDVAL -> (if regression or quality drop) -> TDFIX-fix -> TDVAL-2
-                  (if all pass) -> report
-```
-
---
-
-## Coordinator Spawn Template
-
-### v5 Worker Spawn (all roles)
-
-> **Note**: This skill uses Stop-Wait coordination (`run_in_background: false`). Each role completes before next spawns. This is intentionally different from the default `run_in_background: true` (Spawn-and-Stop). The Stop-Wait strategy ensures sequential pipeline execution where each phase's output is fully available before the next phase begins -- critical for the scan->assess->plan->execute->validate dependency chain.
-
-When coordinator spawns workers, use `team-worker` agent with role-spec path:
+Coordinator spawns workers using this template:

 ```
 Agent({
  subagent_type: "team-worker",
-  description: "Spawn <role> 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: .claude/skills/team-tech-debt/role-specs/<role>.md
+role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt
@@ -289,211 +76,47 @@ 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).`,
-  run_in_background: false  // Stop-Wait: synchronous blocking, wait for worker completion
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

-**Inner Loop roles** (executor): Set `inner_loop: true`.
+## User Commands

-**Single-task roles** (scanner, assessor, planner, validator): Set `inner_loop: false`.
+| 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 |

-**Role-specific spawn parameters**:
+## Specs Reference

-| Role | Prefix | inner_loop |
-|------|--------|------------|
-| scanner | TDSCAN-* | false |
-| assessor | TDEVAL-* | false |
-| planner | TDPLAN-* | false |
-| executor | TDFIX-* | true |
-| validator | TDVAL-* | false |
+- [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry

---
-
-## Completion Action
-
-When the pipeline completes (all tasks done, coordinator Phase 5):
+## Session Directory

 ```
-AskUserQuestion({
-  questions: [{
-    question: "Tech Debt 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-tech-debt", args="resume")` |
-| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
-
---
-
-## Cadence Control
-
-**节拍模型**: Sequential 5-beat -- 扫描->评估->规划->执行->验证，严格串行（Stop-Wait 策略）。
-
-```
-Sequential 5-Beat Cycle (Remediate Mode)
-===================================================================
-  Beat               Coordinator              Worker
-------------------------------------------------------------------
-  Beat 1: SCAN    ┌─ spawn scanner ──────┐
-                  │  run_in_background:   │
-                  │  false (阻塞等待) ────┼──> [Scanner] Phase 1-5
-                  │  scanner 返回 ────────┤        │
-                  └─ 收到结果 ───────────┘  <──────┘
-                       │
-  Beat 2: ASSESS  ┌─ spawn assessor ─────┐
-                  │  阻塞等待 ────────────┼──> [Assessor] Phase 1-5
-                  └─ 收到结果 ───────────┘  <──────┘
-                       │
-  Beat 3: PLAN    ┌─ spawn planner ──────┐
-                  │  阻塞等待 ────────────┼──> [Planner] Phase 1-5
-                  └─ 收到结果 ───────────┘  <──────┘
-                       │
-                  ⏸ CHECKPOINT ── Plan Approval (用户确认)
-                       │
-  Beat 4: FIX     ┌─ Create Worktree ────┐
-                  │  spawn executor ──────┼──> [Executor] Phase 1-5
-                  │  阻塞等待 ────────────┤        │
-                  └─ 收到结果 ───────────┘  <──────┘
-                       │
-  Beat 5: VALIDATE┌─ spawn validator ────┐
-                  │  阻塞等待 ────────────┼──> [Validator] Phase 1-5
-                  └─ 收到结果 ───────────┘  <──────┘
-                       │
-                  ┌─ Commit + PR ────────┐
-                  └─ Final Report ───────┘
-===================================================================
-```
-
-**Pipeline 节拍视图 (按模式)**:
-
-```
-Scan Mode (2 beats)
-──────────────────────────────────────────────────────────
-Beat  1          2
-      │          │
-      TDSCAN -> TDEVAL -> 报告
-
-Remediate Mode (5 beats, 严格串行 + 检查点)
-──────────────────────────────────────────────────────────
-Beat  1       2        3       ⏸      4       5
-      │       │        │       │       │       │
-      SCAN -> EVAL -> PLAN -> [OK?] -> FIX -> VAL -> Report
-                                ▲
-                          Plan Approval
-
-Targeted Mode (3 beats, 跳过扫描评估)
-──────────────────────────────────────────────────────────
-Beat  1       ⏸      2       3
-      │       │       │       │
-      PLAN -> [OK?] -> FIX -> VAL -> Report
-```
-
-**检查点 (Checkpoint)**:
-
-| 触发条件 | 位置 | 行为 |
-|----------|------|------|
-| Plan Approval | TDPLAN 完成后 | 暂停，等待用户确认治理方案 |
-| Fix-Verify Loop 上限 | TDVAL max 3 iterations | 超出轮次 -> 停止迭代，escalate to user |
-| Pipeline 停滞 | Worker 无响应 | 报告等待中的任务列表 |
-
-**Stall 检测** (coordinator monitor 时执行):
-
-| 检查项 | 条件 | 处理 |
-|--------|------|------|
-| Worker 无响应 | in_progress 任务长时间无返回 | Stop-Wait 下不适用（同步阻塞） |
-| Fix-Verify 循环超限 | TDFIX/TDVAL 迭代 > 3 rounds | 终止循环，输出最新验证报告 |
-| Scanner 无债务 | debt-inventory 为空 | 报告 clean codebase，跳过后续阶段 |
-
---
-
-## Task Metadata Registry
-
-| Task ID | Role | Phase | Dependencies | Description |
-|---------|------|-------|-------------|-------------|
-| TDSCAN-001 | scanner | scan | (none) | 多维度技术债务扫描（并行 Fan-out） |
-| TDEVAL-001 | assessor | assess | TDSCAN-001 | 量化评估与优先级排序 |
-| TDPLAN-001 | planner | plan | TDEVAL-001 (or none in targeted) | 分阶段治理方案规划 |
-| TDFIX-001 | executor | fix | TDPLAN-001 + Plan Approval | 债务清理执行（worktree） |
-| TDVAL-001 | validator | validate | TDFIX-001 | 回归测试与质量验证 |
-| TDFIX-002 | executor | fix (loop) | TDVAL-001 (if regression) | Fix-Verify 循环修复 |
-| TDVAL-002 | validator | validate (loop) | TDFIX-002 | Fix-Verify 循环验证 |
-
---
-
-## Wisdom Accumulation (所有角色)
-
-跨任务知识积累。Coordinator 在 session 初始化时创建 `wisdom/` 目录。
-
-**目录**:
-```
-<session-folder>/wisdom/
-├── learnings.md      # 模式和洞察
-├── decisions.md      # 架构和设计决策
-├── conventions.md    # 代码库约定
-└── issues.md         # 已知风险和问题
-```
-
-**Worker 加载** (Phase 2): 从 task description 提取 `Session: <path>`, 读取 wisdom 目录下各文件。
-**Worker 贡献** (Phase 4/5): 将本任务发现写入对应 wisdom 文件。
-
---
-
-## Unified Session Directory
-
-```
-.workflow/.team/TD-{slug}-{YYYY-MM-DD}/
+.workflow/.team/TD-<slug>-<date>/
 ├── .msg/
-│   ├── messages.jsonl              # Team message bus log
-│   └── meta.json                   # Session metadata + shared state
-├── scan/                       # Scanner output
-│   └── debt-inventory.json
-├── assessment/                 # Assessor output
-│   └── priority-matrix.json
-├── plan/                       # Planner output
-│   └── remediation-plan.md
-├── fixes/                      # Executor output
-│   └── fix-log.json
-├── validation/                 # Validator output
-│   └── validation-report.json
-└── wisdom/                     # Cross-task knowledge
-    ├── learnings.md
-    ├── decisions.md
-    ├── conventions.md
-    └── issues.md
-
-# .msg/meta.json worktree 字段（TDFIX 前由 coordinator 写入）:
-# {
-#   ...
-#   "worktree": {
-#     "path": ".worktrees/TD-{slug}-{date}",
-#     "branch": "tech-debt/TD-{slug}-{date}"
-#   }
-# }
+│   ├── 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 --role value | Error with available role list: coordinator, scanner, assessor, planner, executor, validator |
-| Missing --role arg | Orchestration Mode -> auto route to coordinator |
-| Role file not found | Error with expected path (roles/{name}/role.md) |
-| Command file not found | Fall back to inline execution in role.md |
-| Task prefix conflict | Log warning, proceed |
+| 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 |
-| Fix introduces regression | Trigger Fix-Verify loop (max 3 iterations) |
-| Validation repeatedly fails | Escalate to user with diagnosis |
--- a/.claude/skills/team-tech-debt/roles/assessor/role.md
+++ b/.claude/skills/team-tech-debt/roles/assessor/role.md
@@ -0,0 +1,69 @@
+---
+role: assessor
+prefix: TDEVAL
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Assessor
+
+Quantitative evaluator for tech debt items. Score each debt item on business impact (1-5) and fix cost (1-5), classify into priority quadrants, produce priority-matrix.json.
+
+## Phase 2: Load Debt Inventory
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Debt inventory | meta.json:debt_inventory OR <session>/scan/debt-inventory.json | Yes |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for team context
+3. Load debt_inventory from shared memory or fallback to debt-inventory.json file
+4. If debt_inventory is empty -> report empty assessment and exit
+
+## Phase 3: Evaluate Each Item
+
+**Strategy selection**:
+
+| Item Count | Strategy |
+|------------|----------|
+| <= 10 | Heuristic: severity-based impact + effort-based cost |
+| 11-50 | CLI batch: single gemini analysis call |
+| > 50 | CLI chunked: batches of 25 items |
+
+**Impact Score Mapping** (heuristic):
+
+| Severity | Impact Score |
+|----------|-------------|
+| critical | 5 |
+| high | 4 |
+| medium | 3 |
+| low | 1 |
+
+**Cost Score Mapping** (heuristic):
+
+| Estimated Effort | Cost Score |
+|------------------|------------|
+| small | 1 |
+| medium | 3 |
+| large | 5 |
+| unknown | 3 |
+
+**Priority Quadrant Classification**:
+
+| Impact | Cost | Quadrant |
+|--------|------|----------|
+| >= 4 | <= 2 | quick-win |
+| >= 4 | >= 3 | strategic |
+| <= 3 | <= 2 | backlog |
+| <= 3 | >= 3 | defer |
+
+For CLI mode, prompt gemini with full debt summary requesting JSON array of `{id, impact_score, cost_score, risk_if_unfixed, priority_quadrant}`. Unevaluated items fall back to heuristic scoring.
+
+## Phase 4: Generate Priority Matrix
+
+1. Build matrix structure: evaluation_date, total_items, by_quadrant (grouped), summary (counts per quadrant)
+2. Sort within each quadrant by impact_score descending
+3. Write `<session>/assessment/priority-matrix.json`
+4. Update .msg/meta.json with `priority_matrix` summary and evaluated `debt_inventory`
--- a/.claude/skills/team-tech-debt/roles/coordinator/commands/analyze.md
+++ b/.claude/skills/team-tech-debt/roles/coordinator/commands/analyze.md
@@ -0,0 +1,47 @@
+# Analyze Task
+
+Parse user task -> detect tech debt signals -> assess complexity -> determine pipeline mode and roles.
+
+**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
+
+## Signal Detection
+
+| Keywords | Signal | Mode Hint |
+|----------|--------|-----------|
+| 扫描, scan, 审计, audit | debt-scan | scan |
+| 评估, assess, quantify | debt-assess | scan |
+| 规划, plan, roadmap | debt-plan | targeted |
+| 修复, fix, remediate, clean | debt-fix | remediate |
+| 验证, validate, verify | debt-validate | remediate |
+| 定向, targeted, specific | debt-targeted | targeted |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Full codebase scope | +2 |
+| Multiple debt dimensions | +1 per dimension (max 3) |
+| Large codebase (implied) | +1 |
+| Targeted specific items | -1 |
+
+Results: 1-3 Low (scan mode), 4-6 Medium (remediate), 7+ High (remediate + full pipeline)
+
+## Pipeline Mode Determination
+
+| Score + Signals | Mode |
+|----------------|------|
+| scan/audit keywords | scan |
+| targeted/specific keywords | targeted |
+| Default | remediate |
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "pipeline_mode": "<scan|remediate|targeted>",
+  "scope": "<detected-scope>",
+  "focus_dimensions": ["code", "architecture", "testing", "dependency", "documentation"],
+  "complexity": { "score": 0, "level": "Low|Medium|High" }
+}
+```
--- a/.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md
+++ b/.claude/skills/team-tech-debt/roles/coordinator/commands/monitor.md
@@ -1,163 +1,118 @@
-# Command: Monitor
+# Monitor Pipeline

-Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, fix-verify loops, and completion.
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

 ## Constants

-| Key | Value |
-|-----|-------|
-| SPAWN_MODE | background |
-| ONE_STEP_PER_INVOCATION | true |
-| WORKER_AGENT | team-worker |
-| MAX_GC_ROUNDS | 3 |
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+- MAX_GC_ROUNDS: 3

-## Phase 2: Context Loading
+## Handler Router

-| Input | Source | Required |
-|-------|--------|----------|
-| Session state | <session>/session.json | Yes |
-| Task list | TaskList() | Yes |
-| Trigger event | From Entry Router detection | Yes |
-| Meta state | <session>/.msg/meta.json | Yes |
-| Pipeline definition | From SKILL.md | Yes |
+| Source | Handler |
+|--------|---------|
+| Message contains [scanner], [assessor], [planner], [executor], [validator] | handleCallback |
+| "capability_gap" | handleAdapt |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |

-1. Load session.json for current state, `pipeline_mode`, `gc_rounds`
-2. Run TaskList() to get current task statuses
-3. Identify trigger event type from Entry Router
+## handleCallback

-### Role Detection Table
+Worker completed. Process and advance.

-| Message Pattern | Role Detection |
-|----------------|---------------|
-| `[scanner]` or task ID `TDSCAN-*` | scanner |
-| `[assessor]` or task ID `TDEVAL-*` | assessor |
-| `[planner]` or task ID `TDPLAN-*` | planner |
-| `[executor]` or task ID `TDFIX-*` | executor |
-| `[validator]` or task ID `TDVAL-*` | validator |
+1. Find matching worker by role tag in message
+2. Check if progress update (inner loop) or final completion
+3. Progress update -> update session state, STOP
+4. Completion -> mark task done:
+   ```
+   TaskUpdate({ taskId: "<task-id>", status: "completed" })
+   ```
+5. Remove from active_workers, record completion in session

-### Pipeline Stage Order
+6. Check for checkpoints:
+   - **TDPLAN-001 completes** -> Plan Approval Gate:
+     ```
+     AskUserQuestion({
+       questions: [{ question: "Remediation plan generated. Review and decide:",
+         header: "Plan Review", multiSelect: false,
+         options: [
+           { label: "Approve", description: "Proceed with fix execution" },
+           { label: "Revise", description: "Re-run planner with feedback" },
+           { label: "Abort", description: "Stop pipeline" }
+         ]
+       }]
+     })
+     ```
+     - Approve -> Worktree Creation -> handleSpawnNext
+     - Revise -> Create TDPLAN-revised task -> handleSpawnNext
+     - Abort -> Log shutdown -> handleComplete
+
+   - **Worktree Creation** (before TDFIX):
+     ```
+     Bash("git worktree add .worktrees/TD-<slug>-<date> -b tech-debt/TD-<slug>-<date>")
+     ```
+     Update .msg/meta.json with worktree info.
+
+   - **TDVAL-* completes** -> GC Loop Check:
+     Read validation results from .msg/meta.json
+
+     | Condition | Action |
+     |-----------|--------|
+     | No regressions | -> handleSpawnNext (pipeline complete) |
+     | Regressions AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
+     | Regressions AND gc_rounds >= 3 | Accept current state -> handleComplete |
+
+     Fix-Verify Task Creation:
+     ```
+     TaskCreate({ subject: "TDFIX-fix-<round>", description: "PURPOSE: Fix regressions | Session: <session>" })
+     TaskCreate({ subject: "TDVAL-recheck-<round>", description: "...", blockedBy: ["TDFIX-fix-<round>"] })
+     ```
+
+7. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.

 ```
-TDSCAN -> TDEVAL -> TDPLAN -> TDFIX -> TDVAL
+Pipeline Status (<mode>):
+  [DONE]  TDSCAN-001  (scanner)   -> scan complete
+  [DONE]  TDEVAL-001  (assessor)  -> assessment ready
+  [RUN]   TDPLAN-001  (planner)   -> planning...
+  [WAIT]  TDFIX-001   (executor)  -> blocked by TDPLAN-001
+  [WAIT]  TDVAL-001   (validator) -> blocked by TDFIX-001
+
+GC Rounds: 0/3
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
 ```

-## Phase 3: Event Handlers
+Output status -- do NOT advance pipeline.

-### handleCallback
+## handleResume

-Triggered when a worker sends completion message.
+1. Audit task list:
+   - Tasks stuck in "in_progress" -> reset to "pending"
+   - Tasks with completed blockers but still "pending" -> include in spawn list
+2. -> handleSpawnNext

-1. Parse message to identify role and task ID using Role Detection Table
+## handleSpawnNext

-2. Mark task as completed:
+Find ready tasks, spawn workers, STOP.

-```
-TaskUpdate({ taskId: "<task-id>", status: "completed" })
-```
-
-3. Record completion in session state
-
-4. **Plan Approval Gate** (when planner TDPLAN completes):
-
-Before advancing to TDFIX, present the remediation plan to the user for approval.
-
-```
-// Read the generated plan
-planContent = Read(<session>/plan/remediation-plan.md)
-  || Read(<session>/plan/remediation-plan.json)
-
-AskUserQuestion({
-  questions: [{
-    question: "Remediation plan generated. Review and decide:",
-    header: "Plan Review",
-    multiSelect: false,
-    options: [
-      { label: "Approve", description: "Proceed with fix execution" },
-      { label: "Revise", description: "Re-run planner with feedback" },
-      { label: "Abort", description: "Stop pipeline, no fixes applied" }
-    ]
-  }]
-})
-```
-
-| Decision | Action |
-|----------|--------|
-| Approve | Proceed to handleSpawnNext (TDFIX becomes ready) |
-| Revise | Create TDPLAN-revised task, proceed to handleSpawnNext |
-| Abort | Log shutdown, transition to handleComplete |
-
-5. **GC Loop Check** (when validator TDVAL completes):
-
-Read `<session>/.msg/meta.json` for validation results.
-
-| Condition | Action |
-|-----------|--------|
-| No regressions found | Proceed to handleSpawnNext (pipeline complete) |
-| Regressions found AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
-| Regressions found AND gc_rounds >= 3 | Accept current state, proceed to handleComplete |
-
-**Fix-Verify Task Creation** (when regressions detected):
-
-```
-TaskCreate({
-  subject: "TDFIX-fix-<round>",
-  description: "PURPOSE: Fix regressions found by validator | Success: All regressions resolved
-TASK:
-  - Load validation report with regression details
-  - Apply targeted fixes for each regression
-  - Re-validate fixes locally before completion
-CONTEXT:
-  - Session: <session-folder>
-  - Upstream artifacts: <session>/.msg/meta.json
-EXPECTED: Fixed source files | Regressions resolved
-CONSTRAINTS: Targeted fixes only | Do not introduce new regressions",
-  blockedBy: [],
-  status: "pending"
-})
-
-TaskCreate({
-  subject: "TDVAL-recheck-<round>",
-  description: "PURPOSE: Re-validate after regression fixes | Success: Zero regressions
-TASK:
-  - Run full validation suite on fixed code
-  - Compare debt scores before and after
-  - Report regression status
-CONTEXT:
-  - Session: <session-folder>
-EXPECTED: Validation results with regression count
-CONSTRAINTS: Read-only validation",
-  blockedBy: ["TDFIX-fix-<round>"],
-  status: "pending"
-})
-```
-
-6. Proceed to handleSpawnNext
-
-### handleSpawnNext
-
-Find and spawn the next ready tasks.
-
-1. Scan task list for tasks where:
-   - Status is "pending"
-   - All blockedBy tasks have status "completed"
-
-2. If no ready tasks and all tasks completed, proceed to handleComplete
-
-3. If no ready tasks but some still in_progress, STOP and wait
-
-4. For each ready task, determine role from task subject prefix:
-
-```javascript
-const STAGE_WORKER_MAP = {
-  'TDSCAN': { role: 'scanner' },
-  'TDEVAL': { role: 'assessor' },
-  'TDPLAN': { role: 'planner' },
-  'TDFIX':  { role: 'executor' },
-  'TDVAL':  { role: 'validator' }
-}
-```
-
-5. Spawn team-worker (one at a time for sequential pipeline):
+1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed)
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. TaskUpdate -> in_progress
+   c. team_msg log -> task_unblocked
+   d. Spawn team-worker:

 ```
 Agent({
@@ -168,67 +123,54 @@ Agent({
  run_in_background: true,
  prompt: `## Role Assignment
 role: <role>
-role_spec: .claude/skills/team-tech-debt/role-specs/<role>.md
+role_spec: .claude/skills/team-tech-debt/roles/<role>/role.md
 session: <session-folder>
 session_id: <session-id>
 team_name: tech-debt
 requirement: <task-description>
-inner_loop: false
-
-## Current Task
- Task ID: <task-id>
- Task: <task-subject>
+inner_loop: <true|false>

 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.`
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
 })
 ```

-6. STOP after spawning -- wait for next callback
+Stage-to-role mapping:
+| Task Prefix | Role |
+|-------------|------|
+| TDSCAN | scanner |
+| TDEVAL | assessor |
+| TDPLAN | planner |
+| TDFIX | executor |
+| TDVAL | validator |

-### handleCheck
+5. Add to active_workers, update session, output summary, STOP

-Output current pipeline status.
+## handleComplete

-```
-Pipeline Status:
-  [DONE]  TDSCAN-001  (scanner)    -> scan complete
-  [DONE]  TDEVAL-001  (assessor)   -> assessment ready
-  [DONE]  TDPLAN-001  (planner)    -> plan approved
-  [RUN]   TDFIX-001   (executor)   -> fixing...
-  [WAIT]  TDVAL-001   (validator)  -> blocked by TDFIX-001
+Pipeline done. Generate report and completion action.

-GC Rounds: 0/3
-Session: <session-id>
-```
-
-Output status -- do NOT advance pipeline.
-
-### handleResume
-
-Resume pipeline after user pause or interruption.
-
-1. Audit task list for inconsistencies:
-   - Tasks stuck in "in_progress" -> reset to "pending"
-   - Tasks with completed blockers but still "pending" -> include in spawn list
-2. Proceed to handleSpawnNext
-
-### handleComplete
-
-Triggered when all pipeline tasks are completed.
-
-1. Verify all tasks (including any fix-verify tasks) have status "completed"
-2. If any tasks not completed, return to handleSpawnNext
+1. Verify all tasks (including fix-verify tasks) have status "completed"
+2. If any not completed -> handleSpawnNext
 3. If all completed:
-   - Read final state from `<session>/.msg/meta.json`
+   - Read final state from .msg/meta.json
+   - If worktree exists and validation passed: commit, push, gh pr create, cleanup worktree
   - Compile summary: total tasks, completed, gc_rounds, debt_score_before, debt_score_after
-   - If worktree exists and validation passed: commit changes, create PR, cleanup worktree
   - Transition to coordinator Phase 5

-## Phase 4: State Persistence
+## handleAdapt

-After every handler execution:
+Capability gap reported mid-pipeline.

-1. Update session.json with current state (active tasks, gc_rounds, last event)
-2. Verify task list consistency
-3. STOP and wait for next event
+1. Parse gap description
+2. Check if existing role covers it -> redirect
+3. Role count < 5 -> generate dynamic role spec in <session>/role-specs/
+4. Create new task, spawn worker
+5. Role count >= 5 -> merge or pause
+
+## 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
--- a/.claude/skills/team-tech-debt/roles/coordinator/role.md
+++ b/.claude/skills/team-tech-debt/roles/coordinator/role.md
@@ -3,8 +3,7 @@
 技术债务治理团队协调者。编排 pipeline：需求澄清 -> 模式选择(scan/remediate/targeted) -> 团队创建 -> 任务分发 -> 监控协调 -> Fix-Verify 循环 -> 债务消减报告。

 ## Identity
-
- **Name**: `coordinator` | **Tag**: `[coordinator]`
+- **Name**: coordinator | **Tag**: [coordinator]
 - **Responsibility**: Parse requirements -> Create team -> Dispatch tasks -> Monitor progress -> Report results

 ## Boundaries
@@ -25,245 +24,65 @@
 - Skip dependency validation when creating task chains
 - Omit `[coordinator]` identifier in any output

-> **Core principle**: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via TaskCreate.
-
---
-
 ## Command Execution Protocol

-When coordinator needs to execute a command (dispatch, monitor):
+When coordinator needs to execute a command (analyze, 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
-```
-
---
+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], [assessor], [planner], [executor], [validator] | -> 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) |
+| Worker callback | Message contains [scanner], [assessor], [planner], [executor], [validator] | -> handleCallback (monitor.md) |
+| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
+| Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
 | New session | None of above | -> Phase 1 |

-For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
-
-### Router Implementation
-
-1. **Load session context** (if exists):
-   - Scan `.workflow/.team/TD-*/.msg/meta.json` for active/paused sessions
-   - If found, extract session folder path, status, and pipeline mode
-
-2. **Parse $ARGUMENTS** for detection keywords:
-   - Check for role name tags in message content
-   - Check for "check", "status", "resume", "continue" keywords
-
-3. **Route to handler**:
-   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
-   - For Phase 0: Execute Session Resume Check below
-   - For Phase 1: Execute Requirement Clarification below
-
---
-
-## Toolbox
-
-### Available Commands
-
-| Command | File | Phase | Description |
-|---------|------|-------|-------------|
-| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | 任务链创建与依赖管理 |
-| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | 消息总线轮询与协调循环 |
-
-### Tool Capabilities
-
-| Tool | Type | Used By | Purpose |
-|------|------|---------|---------|
-| `TeamCreate` | Tool | Phase 2 | Team initialization |
-| `TaskCreate` | Tool | Phase 3 | Task chain creation |
-| `Task` | Tool | Phase 4 | Worker spawning |
-| `AskUserQuestion` | Tool | Phase 1 | Requirement clarification |
-
-> Coordinator does not directly use CLI analysis tools or CLI code generation
-
---
-
-## Message Types
-
-| Type | Direction | Trigger | Description |
-|------|-----------|---------|-------------|
-| `mode_selected` | coordinator -> all | 模式确定 | scan/remediate/targeted |
-| `plan_approval` | coordinator -> user | TDPLAN 完成 | 呈现治理方案供审批 |
-| `worktree_created` | coordinator -> user | TDFIX 前 | Worktree 和分支已创建 |
-| `pr_created` | coordinator -> user | TDVAL 通过 | PR 已创建，worktree 已清理 |
-| `quality_gate` | coordinator -> user | 质量评估 | 通过/不通过/有条件通过 |
-| `task_unblocked` | coordinator -> worker | 依赖解除 | 任务可执行 |
-| `error` | coordinator -> user | 协调错误 | 阻塞性问题 |
-| `shutdown` | coordinator -> all | 团队关闭 | 清理资源 |
-
-## 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: <message-type>,
-  ref: <artifact-path>
-})
-```
-
-**CLI fallback** (when MCP unavailable):
-
-```
-Bash("ccw team log --session-id <session-id> --from coordinator --type <message-type> --json")
-```
-
---
+For callback/check/resume/complete: load `commands/monitor.md`, execute matched handler, STOP.

 ## Phase 0: Session Resume Check

-**Objective**: Detect and resume interrupted sessions before creating new ones.
-
-**Workflow**:
-
-1. Scan session directory for sessions with status "active" or "paused"
-2. No sessions found -> proceed to Phase 1
-3. Single session found -> resume it (-> Session Reconciliation)
-4. Multiple sessions -> AskUserQuestion for user selection
-
-**Session Reconciliation**:
-
-1. Audit TaskList -> get real status of all tasks
-2. Reconcile: session state <-> TaskList status (bidirectional sync)
-3. Reset any in_progress tasks -> pending (they were interrupted)
-4. Determine remaining pipeline from reconciled state
-5. Rebuild team if disbanded (TeamCreate + spawn needed workers only)
-6. Create missing tasks with correct blockedBy dependencies
-7. Verify dependency chain integrity
-8. Update session file with reconciled state
-9. Kick first executable task's worker -> Phase 4
-
---
+1. Scan `.workflow/.team/TD-*/.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

 ## Phase 1: Requirement Clarification

-**Objective**: Parse user input and gather execution parameters.
+TEXT-LEVEL ONLY. No source code reading.

-**Workflow**:
+1. Parse arguments for explicit settings: mode, scope, focus areas
+2. Detect mode:

-1. **Parse arguments** for explicit settings: mode, scope, focus areas
+| Condition | Mode |
+|-----------|------|
+| `--mode=scan` or keywords: 扫描, scan, 审计, audit, 评估, assess | scan |
+| `--mode=targeted` or keywords: 定向, targeted, 指定, specific, 修复已知 | targeted |
+| `-y` or `--yes` specified | Skip confirmations |
+| Default | remediate |

-2. **Mode Detection**:
-
-| Detection | Condition | Mode |
-|-----------|-----------|------|
-| Explicit | `--mode=scan` specified | scan |
-| Explicit | `--mode=remediate` specified | remediate |
-| Explicit | `--mode=targeted` specified | targeted |
-| Keyword | Contains: 扫描, scan, 审计, audit, 评估, assess | scan |
-| Keyword | Contains: 定向, targeted, 指定, specific, 修复已知 | targeted |
-| Default | No match | remediate |
-
-3. **Auto mode detection**:
-
-| Flag | Behavior |
-|------|----------|
-| `-y` or `--yes` | Skip confirmations |
-
-4. **Ask for missing parameters** via AskUserQuestion (skip if auto mode):
-
-| Question | Options |
-|----------|---------|
-| Tech Debt Target | 自定义 / 全项目扫描 / 完整治理 / 定向修复 |
-
-5. **Store requirements**: mode, scope, focus, constraints
-
-**Success**: All parameters captured, mode finalized.
-
---
+3. Ask for missing parameters (skip if auto mode):
+   - AskUserQuestion: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
+4. Store: mode, scope, focus, constraints
+5. Delegate to commands/analyze.md -> output task-analysis context

 ## Phase 2: Create Team + Initialize Session

-**Objective**: Initialize team, session file, and wisdom directory.
-
-**Workflow**:
-
-1. Generate session ID: `TD-{slug}-{YYYY-MM-DD}`
-2. Create session folder structure:
-
-```
-<session-folder>/
-├── scan/
-├── assessment/
-├── plan/
-├── fixes/
-├── validation/
-└── wisdom/
-    ├── learnings.md
-    ├── decisions.md
-    ├── conventions.md
-    └── issues.md
-```
-
-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: "<scan|remediate|targeted>",
-    pipeline_stages: ["scanner", "assessor", "planner", "executor", "validator"],
-    roles: ["coordinator", "scanner", "assessor", "planner", "executor", "validator"],
-    team_name: "tech-debt",
-    debt_inventory: [],
-    priority_matrix: {},
-    remediation_plan: {},
-    fix_results: {},
-    validation_results: {},
-    debt_score_before: null,
-    debt_score_after: null
-  }
-})
-```
-
-4. Call TeamCreate with team name "tech-debt"
-
-5. **Do NOT spawn workers yet** - Workers are spawned on-demand in Phase 4 (Stop-Wait strategy)
-
-**Success**: Team created, session file written, wisdom initialized.
-
---
+1. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
+2. Create session folder structure (scan/, assessment/, plan/, fixes/, validation/, wisdom/)
+3. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
+4. TeamCreate(team_name="tech-debt")
+5. Do NOT spawn workers yet - deferred to Phase 4

 ## 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**:
+Delegate to commands/dispatch.md. Task chain by mode:

 | Mode | Task Chain |
 |------|------------|
@@ -271,146 +90,22 @@ Delegate to `commands/dispatch.md` which creates the full task chain.
 | remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
 | targeted | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |

-**Task Metadata**:
+## Phase 4: Spawn-and-Stop

-| Task ID | Role | Dependencies | Description |
-|---------|------|--------------|-------------|
-| TDSCAN-001 | scanner | (none) | 多维度技术债务扫描 |
-| TDEVAL-001 | assessor | TDSCAN-001 | 量化评估与优先级排序 |
-| TDPLAN-001 | planner | TDEVAL-001 (or none in targeted) | 分阶段治理方案规划 |
-| TDFIX-001 | executor | TDPLAN-001 + Plan Approval | 债务清理执行（worktree） |
-| TDVAL-001 | validator | TDFIX-001 | 回归测试与质量验证 |
-
-**Success**: Tasks created with correct dependencies, assigned to appropriate owners.
-
---
-
-## Phase 4: Sequential Stage Execution (Stop-Wait)
-
-> **Strategy**: Spawn workers stage-by-stage, synchronous blocking wait. Worker returns = stage complete. No polling needed.
-
-> **CRITICAL**: Use `Task(run_in_background: false)` for synchronous execution. This is intentionally different from the v3 default Spawn-and-Stop pattern.
-
-**Workflow**:
-
-1. Load `commands/monitor.md` if available
-2. Find tasks with: status=pending, blockedBy all resolved, owner assigned
-3. For each ready task -> spawn worker (see SKILL.md Spawn Template)
-4. Output status summary
-5. STOP after spawning (wait for worker callback)
-
-**Stage Transitions**:
-
-| Current Stage | Worker | After Completion |
-|---------------|--------|------------------|
-| TDSCAN-001 | scanner | -> Start TDEVAL |
-| TDEVAL-001 | assessor | -> Start TDPLAN |
-| TDPLAN-001 | planner | -> [Plan Approval Gate] -> [Create Worktree] -> Start TDFIX |
-| TDFIX-001 | executor (worktree) | -> Start TDVAL |
-| TDVAL-001 | validator (worktree) | -> Quality Gate -> [Commit+PR] |
-
-**Worker Spawn Template**:
-
-```
-Agent({
-  subagent_type: "team-worker",
-  description: "Spawn <role> worker",
-  prompt: `## Role Assignment
-role: <role>
-role_spec: .claude/skills/team-tech-debt/role-specs/<role>.md
-session: <session-folder>
-session_id: <session-id>
-team_name: tech-debt
-requirement: <task-description>
-inner_loop: false
-
-## Current Task
- Task ID: <task-id>
- Task: <PREFIX>-<NNN>
- Task Prefix: <PREFIX>
-
-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.`,
-  run_in_background: false  // Stop-Wait: synchronous blocking
-})
-```
-
-**Plan Approval Gate** (after TDPLAN completes):
-
-1. Read remediation plan
-2. Present to user via AskUserQuestion:
-
-| Option | Action |
-|--------|--------|
-| 批准 | Continue pipeline, create worktree |
-| 修订 | Request plan revision from planner |
-| 终止 | Stop pipeline, report current status |
-
-**Worktree Creation** (before TDFIX):
-
-1. Create worktree: `git worktree add <path> -b <branch>`
-2. Update .msg/meta.json with worktree info
-3. Notify user via team_msg
-
-**Fix-Verify Loop** (when TDVAL finds regressions):
-
-| Condition | Action |
-|-----------|--------|
-| regressionFound && iteration < 3 | Create TDFIX-fix + TDVAL-verify tasks, continue |
-| iteration >= 3 | Accept current state, report with warning |
-
---
+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

 ## Phase 5: Report + Debt Reduction Metrics + PR

-**Objective**: Completion report and follow-up options.
-
-**Workflow**:
-
-1. **Read shared memory** -> collect all results
-
-2. **PR Creation** (worktree mode, validation passed):
-
-| Step | Action |
-|------|--------|
-| Commit | `cd <worktree> && git add -A && git commit -m "tech-debt: <description>"` |
-| Push | `cd <worktree> && git push -u origin <branch>` |
-| Create PR | `cd <worktree> && gh pr create --title "Tech Debt: ..." --body "..."` |
-| Notify | team_msg with pr_created |
-| Cleanup | `git worktree remove <worktree>` (if validation passed) |
-
-3. **Calculate metrics**:
-
-| Metric | Calculation |
-|--------|-------------|
-| debt_items_found | debt_inventory.length |
-| items_fixed | fix_results.items_fixed |
-| reduction_rate | (items_fixed / debt_items_found) * 100 |
-
-4. **Generate report**:
-
-| Field | Value |
-|-------|-------|
-| mode | scan/remediate/targeted |
-| debt_items_found | Count |
-| debt_score_before | Initial score |
-| debt_score_after | Final score |
-| items_fixed | Count |
-| items_remaining | Count |
-| validation_passed | Boolean |
-| regressions | Count |
-
-5. **Output**: SendMessage with `[coordinator]` prefix + team_msg log
-
-6. **Ask next steps** (skip if auto mode):
-
-| Option | Action |
-|--------|--------|
-| 新目标 | New tech debt target |
-| 深度修复 | Continue with remaining high-priority items |
-| 关闭团队 | Cleanup and close |
-
---
+1. Read shared memory -> collect all results
+2. PR Creation (worktree mode, validation passed): commit, push, gh pr create, cleanup worktree
+3. Calculate: debt_items_found, items_fixed, reduction_rate
+4. Generate report with mode, debt scores, validation status
+5. Output with [coordinator] prefix
+6. Execute completion action (AskUserQuestion: 新目标 / 深度修复 / 关闭团队)

 ## Error Handling

@@ -421,8 +116,5 @@ Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`,
 | Dependency cycle | Detect, report to user, halt |
 | Invalid mode | Reject with error, ask to clarify |
 | Session corruption | Attempt recovery, fallback to manual reconciliation |
-| Teammate unresponsive | Send follow-up, 2x -> respawn |
 | Scanner finds no debt | Report clean codebase, skip to summary |
 | Fix-Verify loop stuck >3 iterations | Accept current state, continue pipeline |
-| Build/test environment broken | Notify user, suggest manual fix |
-| All tasks completed but debt_score_after > debt_score_before | Report with WARNING, suggest re-run |
--- a/.claude/skills/team-tech-debt/roles/executor/role.md
+++ b/.claude/skills/team-tech-debt/roles/executor/role.md
@@ -0,0 +1,76 @@
+---
+role: executor
+prefix: TDFIX
+inner_loop: true
+message_types: [state_update]
+---
+
+# Tech Debt Executor
+
+Debt cleanup executor. Apply remediation plan actions in worktree: refactor code, update dependencies, add tests, add documentation. Batch-delegate to CLI tools, self-validate after each batch.
+
+## Phase 2: Load Remediation Plan
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Remediation plan | <session>/plan/remediation-plan.json | Yes |
+| Worktree info | meta.json:worktree.path, worktree.branch | Yes |
+| Context accumulator | From prior TDFIX tasks (inner loop) | Yes (inner loop) |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for worktree path and branch
+3. Read remediation-plan.json, extract all actions from plan phases
+4. Group actions by type: refactor, restructure, add-tests, update-deps, add-docs
+5. Split large groups (> 10 items) into sub-batches of 10
+6. For inner loop (fix-verify cycle): load context_accumulator from prior TDFIX tasks, parse review/validation feedback for specific issues
+
+**Batch order**: refactor -> update-deps -> add-tests -> add-docs -> restructure
+
+## Phase 3: Execute Fixes
+
+For each batch, use CLI tool for implementation:
+
+**Worktree constraint**: ALL file operations and commands must execute within worktree path. Use `cd "<worktree-path>" && ...` prefix for all Bash commands.
+
+**Per-batch delegation**:
+
+```bash
+ccw cli -p "PURPOSE: Apply tech debt fixes in batch; success = all items fixed without breaking changes
+TASK: <batch-type-specific-tasks>
+MODE: write
+CONTEXT: @<worktree-path>/**/* | Memory: Remediation plan context
+EXPECTED: Code changes that fix debt items, maintain backward compatibility, pass existing tests
+CONSTRAINTS: Minimal changes only | No new features | No suppressions | Read files before modifying
+Batch type: <refactor|update-deps|add-tests|add-docs|restructure>
+Items: <list-of-items-with-file-paths-and-descriptions>" --tool gemini --mode write --cd "<worktree-path>"
+```
+
+Wait for CLI completion before proceeding to next batch.
+
+**Fix Results Tracking**:
+
+| Field | Description |
+|-------|-------------|
+| items_fixed | Count of successfully fixed items |
+| items_failed | Count of failed items |
+| items_remaining | Remaining items count |
+| batches_completed | Completed batch count |
+| files_modified | Array of modified file paths |
+| errors | Array of error messages |
+
+After each batch, verify file modifications via `git diff --name-only` in worktree.
+
+## Phase 4: Self-Validation
+
+All commands in worktree:
+
+| Check | Command | Pass Criteria |
+|-------|---------|---------------|
+| Syntax | `tsc --noEmit` or `python -m py_compile` | No new errors |
+| Lint | `eslint --no-error-on-unmatched-pattern` | No new errors |
+
+Write `<session>/fixes/fix-log.json` with fix results. Update .msg/meta.json with `fix_results`.
+
+Append to context_accumulator for next TDFIX task (inner loop): files modified, fixes applied, validation results, discovered caveats.
--- a/.claude/skills/team-tech-debt/roles/planner/role.md
+++ b/.claude/skills/team-tech-debt/roles/planner/role.md
@@ -0,0 +1,69 @@
+---
+role: planner
+prefix: TDPLAN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Planner
+
+Remediation plan designer. Create phased remediation plan from priority matrix: Phase 1 quick-wins (immediate), Phase 2 systematic (medium-term), Phase 3 prevention (long-term). Produce remediation-plan.md.
+
+## Phase 2: Load Assessment Data
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Priority matrix | <session>/assessment/priority-matrix.json | Yes |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for debt_inventory
+3. Read priority-matrix.json for quadrant groupings
+4. Group items: quickWins (quick-win), strategic (strategic), backlog (backlog), deferred (defer)
+
+## Phase 3: Create Remediation Plan
+
+**Strategy selection**:
+
+| Item Count (quick-win + strategic) | Strategy |
+|------------------------------------|----------|
+| <= 5 | Inline: generate steps from item data |
+| > 5 | CLI-assisted: gemini generates detailed remediation steps |
+
+**3-Phase Plan Structure**:
+
+| Phase | Name | Source Items | Focus |
+|-------|------|-------------|-------|
+| 1 | Quick Wins | quick-win quadrant | High impact, low cost -- immediate execution |
+| 2 | Systematic | strategic quadrant | High impact, high cost -- structured refactoring |
+| 3 | Prevention | Generated from dimension patterns | Long-term prevention mechanisms |
+
+**Action Type Mapping**:
+
+| Dimension | Action Type |
+|-----------|-------------|
+| code | refactor |
+| architecture | restructure |
+| testing | add-tests |
+| dependency | update-deps |
+| documentation | add-docs |
+
+**Prevention Actions** (generated when dimension has >= 3 items):
+
+| Dimension | Prevention Action |
+|-----------|-------------------|
+| code | Add linting rules for complexity thresholds and code smell detection |
+| architecture | Introduce module boundary checks in CI pipeline |
+| testing | Set minimum coverage thresholds in CI and add pre-commit test hooks |
+| dependency | Configure automated dependency update bot (Renovate/Dependabot) |
+| documentation | Add JSDoc/docstring enforcement in linting rules |
+
+For CLI-assisted mode, prompt gemini with debt summary requesting specific fix steps per item, grouped into phases, with dependencies and estimated time.
+
+## Phase 4: Validate & Save
+
+1. Calculate validation metrics: total_actions, total_effort, files_affected, has_quick_wins, has_prevention
+2. Write `<session>/plan/remediation-plan.md` (markdown with per-item checklists)
+3. Write `<session>/plan/remediation-plan.json` (machine-readable)
+4. Update .msg/meta.json with `remediation_plan` summary
--- a/.claude/skills/team-tech-debt/roles/scanner/role.md
+++ b/.claude/skills/team-tech-debt/roles/scanner/role.md
@@ -0,0 +1,81 @@
+---
+role: scanner
+prefix: TDSCAN
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Scanner
+
+Multi-dimension tech debt scanner. Scan codebase across 5 dimensions (code, architecture, testing, dependency, documentation), produce structured debt inventory with severity rankings.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Scan scope | task description (regex: `scope:\s*(.+)`) | No (default: `**/*`) |
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+
+1. Extract session path and scan scope from task description
+2. Read .msg/meta.json for team context
+3. Detect project type and framework:
+
+| Signal File | Project Type |
+|-------------|-------------|
+| package.json + React/Vue/Angular | Frontend Node |
+| package.json + Express/Fastify/NestJS | Backend Node |
+| pyproject.toml / requirements.txt | Python |
+| go.mod | Go |
+| No detection | Generic |
+
+4. Determine scan dimensions (default: code, architecture, testing, dependency, documentation)
+5. Detect perspectives from task description:
+
+| Condition | Perspective |
+|-----------|-------------|
+| `security\|auth\|inject\|xss` | security |
+| `performance\|speed\|optimize` | performance |
+| `quality\|clean\|maintain\|debt` | code-quality |
+| `architect\|pattern\|structure` | architecture |
+| Default | code-quality + architecture |
+
+6. Assess complexity:
+
+| Score | Complexity | Strategy |
+|-------|------------|----------|
+| >= 4 | High | Triple Fan-out: CLI explore + CLI 5 dimensions + multi-perspective Gemini |
+| 2-3 | Medium | Dual Fan-out: CLI explore + CLI 3 dimensions |
+| 0-1 | Low | Inline: ACE search + Grep |
+
+## Phase 3: Multi-Dimension Scan
+
+**Low Complexity** (inline):
+- Use `mcp__ace-tool__search_context` for code smells, TODO/FIXME, deprecated APIs, complex functions, dead code, missing tests
+- Classify findings into dimensions
+
+**Medium/High Complexity** (Fan-out):
+- Fan-out A: CLI exploration (structure, patterns, dependencies angles) via `ccw cli --tool gemini --mode analysis`
+- Fan-out B: CLI dimension analysis (parallel gemini per dimension -- code, architecture, testing, dependency, documentation)
+- Fan-out C (High only): Multi-perspective Gemini analysis (security, performance, code-quality, architecture)
+- Fan-in: Merge results, cross-deduplicate by file:line, boost severity for multi-source findings
+
+**Standardize each finding**:
+
+| Field | Description |
+|-------|-------------|
+| `id` | `TD-NNN` (sequential) |
+| `dimension` | code, architecture, testing, dependency, documentation |
+| `severity` | critical, high, medium, low |
+| `file` | File path |
+| `line` | Line number |
+| `description` | Issue description |
+| `suggestion` | Fix suggestion |
+| `estimated_effort` | small, medium, large, unknown |
+
+## Phase 4: Aggregate & Save
+
+1. Deduplicate findings across Fan-out layers (file:line key), merge cross-references
+2. Sort by severity (cross-referenced items boosted)
+3. Write `<session>/scan/debt-inventory.json` with scan_date, dimensions, total_items, by_dimension, by_severity, items
+4. Update .msg/meta.json with `debt_inventory` array and `debt_score_before` count
--- a/.claude/skills/team-tech-debt/roles/validator/role.md
+++ b/.claude/skills/team-tech-debt/roles/validator/role.md
@@ -0,0 +1,78 @@
+---
+role: validator
+prefix: TDVAL
+inner_loop: false
+message_types: [state_update]
+---
+
+# Tech Debt Validator
+
+Cleanup result validator. Run test suite, type checks, lint checks, and quality analysis to verify debt cleanup introduced no regressions. Compare before/after debt scores, produce validation-report.json.
+
+## Phase 2: Load Context
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Session path | task description (regex: `session:\s*(.+)`) | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Fix log | <session>/fixes/fix-log.json | No |
+
+1. Extract session path from task description
+2. Read .msg/meta.json for: worktree.path, debt_inventory, fix_results, debt_score_before
+3. Determine command prefix: `cd "<worktree-path>" && ` if worktree exists
+4. Read fix-log.json for modified files list
+5. Detect available validation tools in worktree:
+
+| Signal | Tool | Method |
+|--------|------|--------|
+| package.json + npm | npm test | Test suite |
+| pytest available | python -m pytest | Test suite |
+| npx tsc available | npx tsc --noEmit | Type check |
+| npx eslint available | npx eslint | Lint check |
+
+## Phase 3: Run Validation Checks
+
+Execute 4-layer validation (all commands in worktree):
+
+**1. Test Suite**:
+- Run `npm test` or `python -m pytest` in worktree
+- PASS if no FAIL/error/failed keywords; FAIL with regression count otherwise
+- Skip with "no-tests" if no test runner available
+
+**2. Type Check**:
+- Run `npx tsc --noEmit` in worktree
+- Count `error TS` occurrences for error count
+
+**3. Lint Check**:
+- Run `npx eslint --no-error-on-unmatched-pattern <modified-files>` in worktree
+- Count error occurrences
+
+**4. Quality Analysis** (optional, when > 5 modified files):
+- Use gemini CLI to compare code quality before/after
+- Assess complexity, duplication, naming quality improvements
+
+**Debt Score Calculation**:
+- debt_score_after = debt items NOT in modified files (remaining unfixed items)
+- improvement_percentage = ((before - after) / before) * 100
+
+**Auto-fix attempt** (when total_regressions <= 3):
+- Use CLI tool to fix regressions in worktree:
+  ```
+  Bash({
+    command: `cd "${worktreePath}" && ccw cli -p "PURPOSE: Fix regressions found in validation
+  TASK: ${regressionDetails}
+  MODE: write
+  CONTEXT: @${modifiedFiles.join(' @')}
+  EXPECTED: Fixed regressions
+  CONSTRAINTS: Fix only regressions | Preserve debt cleanup changes | No suppressions" --tool gemini --mode write`,
+    run_in_background: false
+  })
+  ```
+- Re-run validation checks after fix attempt
+
+## Phase 4: Compare & Report
+
+1. Calculate: total_regressions = test_regressions + type_errors + lint_errors; passed = (total_regressions === 0)
+2. Write `<session>/validation/validation-report.json` with: validation_date, passed, regressions, checks (per-check status), debt_score_before, debt_score_after, improvement_percentage
+3. Update .msg/meta.json with `validation_results` and `debt_score_after`
+4. Select message type: `validation_complete` if passed, `regression_found` if not
--- a/.claude/skills/team-tech-debt/specs/pipelines.md
+++ b/.claude/skills/team-tech-debt/specs/pipelines.md
@@ -0,0 +1,47 @@
+# Pipeline Definitions
+
+Tech debt pipeline modes and task registry.
+
+## Pipeline Modes
+
+| Mode | Description | Task Chain |
+|------|-------------|------------|
+| scan | Scan and assess only, no fixes | TDSCAN-001 -> TDEVAL-001 |
+| remediate | Full pipeline: scan -> assess -> plan -> fix -> validate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+| targeted | Skip scan/assess, direct fix path | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
+
+## Task Registry
+
+| Task ID | Role | Prefix | blockedBy | Description |
+|---------|------|--------|-----------|-------------|
+| TDSCAN-001 | scanner | TDSCAN | [] | Fan-out multi-dimension codebase scan (code, architecture, testing, dependency, documentation) |
+| TDEVAL-001 | assessor | TDEVAL | [TDSCAN-001] | Severity assessment with priority quadrant matrix |
+| TDPLAN-001 | planner | TDPLAN | [TDEVAL-001] | 3-phase remediation plan with effort estimates |
+| TDFIX-001 | executor | TDFIX | [TDPLAN-001] | Worktree-based incremental fixes (inner_loop: true) |
+| TDVAL-001 | validator | TDVAL | [TDFIX-001] | 4-layer validation: syntax, tests, integration, regression |
+
+## Checkpoints
+
+| Checkpoint | Trigger | Condition | Action |
+|------------|---------|-----------|--------|
+| Plan Approval Gate | TDPLAN-001 completes | Always | AskUserQuestion: Approve / Revise / Abort |
+| Worktree Creation | Plan approved | Before TDFIX | git worktree add .worktrees/TD-<slug>-<date> |
+| Fix-Verify GC Loop | TDVAL-* completes | Regressions found | Create TDFIX-fix-<round> + TDVAL-recheck-<round> (max 3 rounds) |
+
+## GC Loop Behavior
+
+| Condition | Action |
+|-----------|--------|
+| No regressions | Pipeline complete |
+| Regressions AND gc_rounds < 3 | Create fix-verify tasks, increment gc_rounds |
+| Regressions AND gc_rounds >= 3 | Accept current state, handleComplete |
+
+## Output Artifacts
+
+| Task | Output Path |
+|------|-------------|
+| TDSCAN-001 | <session>/scan/scan-report.json |
+| TDEVAL-001 | <session>/assessment/debt-assessment.json |
+| TDPLAN-001 | <session>/plan/remediation-plan.md |
+| TDFIX-001 | <session>/fixes/ (worktree) |
+| TDVAL-001 | <session>/validation/validation-report.md |