Team Tech Debt

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

Architecture Overview

┌──────────────────────────────────────────────────────────┐
│  Skill(skill="team-tech-debt", args="--role=xxx")         │
└────────────────────────┬─────────────────────────────────┘
                         │ Role Router
    ┌────────┬───────────┼───────────┬──────────┬──────────┐
    ↓        ↓           ↓           ↓          ↓          ↓
┌────────┐┌────────┐┌──────────┐┌─────────┐┌────────┐┌─────────┐
│coordi- ││scanner ││assessor  ││planner  ││executor││validator│
│nator   ││TDSCAN-*││TDEVAL-*  ││TDPLAN-* ││TDFIX-* ││TDVAL-*  │
│ roles/ ││ roles/ ││ roles/   ││ roles/  ││ roles/ ││ roles/  │
└────────┘└────────┘└──────────┘└─────────┘└────────┘└─────────┘

Command Architecture

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 Router

Input Parsing

Parse $ARGUMENTS to extract --role and optional --agent-name, --team (default: “tech-debt”), --mode (scan/remediate/targeted).

If no --role -> Orchestration Mode (auto route to coordinator).

Role Registry

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):

Shared Infrastructure

以下为编排级概览。具体实现代码（Message Bus、Task Lifecycle、工具方法）在各 role.md 中自包含。

Team Configuration

Role Isolation Rules

核心原则: 每个角色仅能执行自己职责范围内的工作。

Output Tagging（强制）

所有角色的输出必须带 [role_name] 标识前缀。

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”, team=<team-name>, from=<role>, to=”coordinator”, type=<消息类型>, summary=”[<role>] <摘要>“, ref=<产物路径>
   • CLI fallback: 当 MCP 不可用时 -> ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json
2. SendMessage: 发送结果给 coordinator (content 和 summary 都带 [<role>] 前缀)
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: Subagent Exploration (并行 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

Fix-Verify Loop

TDFIX -> TDVAL -> (if regression or quality drop) -> TDFIX-fix -> TDVAL-2
                  (if all pass) -> report

Coordinator Spawn Template

Note: This skill uses Stop-Wait coordination (run_in_background: false). Each role completes before next spawns. This is intentionally different from the v3 default of 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.

以下模板作为 worker prompt 参考。在 Stop-Wait 策略下，coordinator 不在 Phase 2 预先 spawn 所有 worker。而是在 Phase 4 (monitor) 中，按 pipeline 阶段逐个 spawn worker（同步阻塞 Task(run_in_background: false)），worker 返回即阶段完成。详见 roles/coordinator/commands/monitor.md。

通用 Worker Spawn 格式:

Task({
  subagent_type: "general-purpose",
  description: "Spawn <role> worker",
  prompt: `你是 team "<team-name>" 的 <ROLE>.

## 首要指令（MUST）
你的所有工作必须通过调用 Skill 获取角色定义后执行，禁止自行发挥：
Skill(skill="team-tech-debt", args="--role=<role>")
此调用会加载你的角色定义（role.md）、可用命令（commands/*.md）和完整执行逻辑。

当前需求: <task-description>
约束: <constraints>

## 角色准则（强制）
- 你只能处理 <PREFIX>-* 前缀的任务，不得执行其他角色的工作
- 所有输出（SendMessage、team_msg）必须带 [<role>] 标识前缀
- 仅与 coordinator 通信，不得直接联系其他 worker
- 不得使用 TaskCreate 为其他角色创建任务

## 消息总线（必须）
每次 SendMessage 前，先调用 mcp__ccw-tools__team_msg 记录。

## 工作流程（严格按顺序）
1. 调用 Skill(skill="team-tech-debt", args="--role=<role>") 获取角色定义和执行逻辑
2. 按 role.md 中的 5-Phase 流程执行（TaskList -> 找到 <PREFIX>-* 任务 -> 执行 -> 汇报）
3. team_msg log + SendMessage 结果给 coordinator（带 [<role>] 标识）
4. TaskUpdate completed -> 检查下一个任务 -> 回到步骤 1`,
  run_in_background: false  // Stop-Wait: 同步阻塞，等待 worker 完成
})

各角色 Spawn 参数:

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):

Stall 检测 (coordinator monitor 时执行):

Task Metadata Registry

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}/
├── team-session.json
├── shared-memory.json          # 债务清单 / 评估矩阵 / 治理方案 / 修复结果 / 验证结果 / worktree 信息
├── 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

# shared-memory.json worktree 字段（TDFIX 前由 coordinator 写入）:
# {
#   ...
#   "worktree": {
#     "path": ".worktrees/TD-{slug}-{date}",
#     "branch": "tech-debt/TD-{slug}-{date}"
#   }
# }

Error Handling