team-tech-debt

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	["AskUserQuestion","Bash","Edit","Glob","Grep","Read","SendMessage","Write","mcp__maestro__edit_file","mcp__maestro__read_file","mcp__maestro__team_msg","mcp__maestro__write_file","teammate","todo"]
session-mode	run

<required_reading> @~/.maestro/workflows/run-mode-lite.md </required_reading>

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	Path	Prefix	Inner Loop
coordinator	roles/coordinator/role.md	—	—
scanner	roles/scanner/role.md	TDSCAN-*	false
assessor	roles/assessor/role.md	TDEVAL-*	false
planner	roles/planner/role.md	TDPLAN-*	false
executor	roles/executor/role.md	TDFIX-*	true
validator	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: {run_dir}/work/team/
• CLI tools: maestro delegate --mode analysis (read-only), maestro delegate --mode write (modifications)
• Message bus: mcp__maestro__team_msg(session_id=<run-id>, ...)
• Max GC rounds: 3

Worker Spawn Template

Coordinator spawns workers using this template:

teammate({ agent: "team-worker", name: "<role>", description: "Spawn <role> worker for <task-id>", context: "fresh" })

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 — Pipeline definitions and task registry

Session Directory

{run_dir}/work/team/
├── .msg/
│   ├── messages.jsonl      # Team message bus
│   └── meta.json           # Pipeline config + role state snapshot
├── {run_dir}/outputs/scan/                   # Scanner output
├── {run_dir}/outputs/assessment/             # Assessor output
├── {run_dir}/outputs/plan/                   # Planner output
├── {run_dir}/outputs/fixes/                  # Executor output
├── {run_dir}/outputs/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