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

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 Router

Parse

$ARGUMENTS

• Has

  --role <name>

  → Read

  roles/<name>/role.md

  , execute Phase 2-4
• No

  --role

  →

  roles/coordinator/role.md

  , execute entry router

Delegation Lock

Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.

Before calling ANY tool, apply this check:

spawn_agent

wait_agent

close_agent

send_message

followup_task

list_agents

request_user_input

mcp__ccw-tools__team_msg

Read/Write

.workflow/.team/

Read

roles/

commands/

specs/

Read/Grep/Glob

Edit

.workflow/

Bash("ccw cli ...")

Bash

If a tool call is BLOCKED: STOP. Create a task, spawn a worker.

No exceptions for "simple" tasks. Even a single-file read-and-report MUST go through spawn_agent.

Shared Constants

• Session prefix:

  TD

• Session path:

  .workflow/.team/TD-<date>-<slug>/

• 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

Worker Spawn Template

Coordinator spawns workers using this template:

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_turns: "none",
  message: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <task-description>
inner_loop: <true|false>

Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.

## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>

## Upstream Context
<prev_context>`
})

After spawning, use

wait_agent({ timeout_ms: 1800000 })

result.timed_out

close_agent({ target })

Model Selection Guide

Tech debt follows a discovery-to-fix pipeline. Scanner is broad/fast, later stages need deeper reasoning.

Pipeline Pattern: Scanner Results Inform Downstream

Scanner discoveries flow through the pipeline — each stage narrows and refines:

1. TDSCAN produces broad debt inventory
2. TDEVAL assesses and prioritizes (filters low-impact items)
3. TDPLAN creates sequenced fix plan from assessed items
4. TDFIX implements fixes per plan
5. TDVAL validates fixes against original debt findings

User Commands

check

status

resume

continue

--mode=scan

--mode=targeted

--mode=remediate

-y

--yes

Specs Reference

• specs/pipelines.md — Pipeline definitions and task registry

Session Directory

.workflow/.team/TD-<date>-<slug>/
├── .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

v4 Agent Coordination

Message Semantics

send_message

followup_task

list_agents

Agent Health Check

Use

list_agents({})

// Reconcile session state with actual running agents
const running = list_agents({})
// Compare with meta.json active tasks
// Reset orphaned tasks (in_progress but agent gone) to pending

Named Agent Targeting

Workers are spawned with

task_name: "<task-id>"

• send_message({ target: "TDSCAN-001", message: "..." })

  -- send additional scan scope to scanner

• followup_task({ target: "TDFIX-001", message: "..." })

  -- assign fix task from planner output

• close_agent({ target: "TDVAL-001" })

  -- cleanup after validation

Error Handling