maestro-flow 0.4.6 → 0.4.8

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

@@ -1,144 +1,214 @@
----
-name: team-tech-debt
-description: Team tech debt identification and remediation
-allowed-tools: spawn_agent(*), wait_agent(*), send_message(*), followup_task(*), close_agent(*), list_agents(*), report_agent_job_result(*), request_user_input(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__maestro-tools__read_file(*), mcp__maestro-tools__write_file(*), mcp__maestro-tools__edit_file(*), mcp__maestro-tools__team_msg(*)
----
-
-<purpose>
-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`.
-
-```
-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
-```
-
-</purpose>
-
-<context>
-$ARGUMENTS — task description and optional flags.
-
-**Role Router:**
-- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
-- No `--role` → `roles/coordinator/role.md`, execute entry router
-
-**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 |
-
-**User Commands:**
-| Command | Action |
-|---------|--------|
-| `check` / `status` | View execution status graph |
-| `resume` / `continue` | Advance to next step |
-| `--mode=scan` | Scan-only pipeline (TDSCAN + TDEVAL) |
-| `--mode=targeted` | Targeted pipeline (TDPLAN + TDFIX + TDVAL) |
-| `--mode=remediate` | Full pipeline (default) |
-| `-y` / `--yes` | Skip confirmations |
-
-**Delegation Lock — Coordinator is PURE ORCHESTRATOR:**
-| Tool Call | Verdict | Reason |
-|-----------|---------|--------|
-| `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration |
-| `list_agents`, `request_user_input`, `mcp__maestro-tools__team_msg` | ALLOWED | Coordination |
-| `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state |
-| `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading instructions |
-| `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker |
-| `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker |
-| `Bash` running build/test/lint | BLOCKED | Delegate to worker |
-
-**No exceptions.** Even single-file tasks MUST go through spawn_agent.
-
-**Shared Constants:**
-- Session prefix: `TD`
-- Session path: `.workflow/.team/TD-<slug>-<date>/`
-- CLI tools: `maestro delegate --mode analysis|write`
-- Max GC rounds: 3
-
-**Specs:** [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry
-
-**Session Directory:**
-```
-.workflow/.team/TD-<slug>-<date>/
-├── .msg/            # Team message bus
-├── scan/            # Scanner output
-├── assessment/      # Assessor output
-├── plan/            # Planner output
-├── fixes/           # Executor output
-├── validation/      # Validator output
-└── wisdom/          # Cross-task knowledge
-```
-</context>
-
-<invariants>
-1. **Coordinator never executes domain work** — only orchestrates via spawn_agent
-2. **Scanner results inform downstream** — each stage narrows and refines
-3. **Pipeline flow**: TDSCAN → TDEVAL → TDPLAN → TDFIX → TDVAL
-</invariants>
-
-<execution>
-
-### Worker Spawn Template
-
-Spawn via `team-worker` agent. Message includes: role, role_spec path, session folder/id, requirement, inner_loop flag, task context, upstream context. After spawning: `wait_agent` (30 min). Timeout: STATUS_CHECK (3 min) -> FINALIZE (3 min) -> close.
-
-### Model Selection Guide
-
-| Role | reasoning_effort |
-|------|-------------------|
-| scanner | medium |
-| assessor | high |
-| planner | high |
-| executor | high |
-| validator | medium |
-
-### v4 Agent Coordination
-
-**Message Semantics**: `send_message` for supplementary info to downstream. `followup_task` to assign fixes from planner output. `list_agents` for health checks.
-
-**Agent Health Check**: Reconcile `meta.json` active tasks with `list_agents({})`. Reset orphaned tasks to pending.
-
-**Named Targeting**: `send_message({ target: "TDSCAN-001" })`, `followup_task({ target: "TDFIX-001" })`, `close_agent({ target: "TDVAL-001" })`.
-</execution>
-
-<error_codes>
-| 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 |
-</error_codes>
-
-<success_criteria>
-- [ ] Role routing correct (coordinator vs worker)
-- [ ] Delegation lock enforced (coordinator never executes domain work)
-- [ ] Pipeline stages execute in order (scan → assess → plan → fix → validate)
-- [ ] Worker spawn uses correct template with role-spec paths
-- [ ] Timeout handling applied (STATUS_CHECK → FINALIZE → close)
-- [ ] Scanner results flow through downstream stages
-- [ ] Session directory structure maintained
-- [ ] Completion action presented to user
-</success_criteria>
+---
+name: team-tech-debt
+description: Team tech debt identification and remediation
+argument-hint: "[scope] [-y|--yes] [-c|--concurrency N] [--continue] [--mode scan|remediate|targeted]"
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Wave-based tech debt pipeline via `spawn_agents_on_csv`. Scan → Assess → Plan → Fix → Validate with user-gated remediation plan and fix-verify GC loops.
+
+```
++-------------------------------------------------------------------+
+|                 TECH DEBT CSV WAVE WORKFLOW                         |
++-------------------------------------------------------------------+
+|  Phase 1: Mode Selection + CSV Generation                          |
+|     +-- Detect mode (scan/remediate/targeted)                      |
+|     +-- Build tasks.csv from pipeline definition                   |
+|                                                                     |
+|  Phase 2: Wave Execution Engine                                    |
+|     +-- Sequential waves                                           |
+|     +-- User approval after TDPLAN (plan gate)                     |
+|     +-- Fix-Verify GC loop (max 3 rounds on regression)            |
+|                                                                     |
+|  Phase 3: Results Aggregation                                      |
++-------------------------------------------------------------------+
+```
+</purpose>
+
+<context>
+```bash
+$team-tech-debt "src/"
+$team-tech-debt -y --mode remediate "src/auth"
+$team-tech-debt --mode targeted "high-priority debt items"
+$team-tech-debt --continue "20260518-td-auth"
+```
+
+**Flags**: `-y` (auto), `-c N` (concurrency, default 3), `--continue` (resume), `--mode scan|remediate|targeted`
+
+### Role Registry (Fixed)
+
+| Role | Path | Prefix |
+|------|------|--------|
+| scanner | [roles/scanner/role.md](roles/scanner/role.md) | TDSCAN-* |
+| assessor | [roles/assessor/role.md](roles/assessor/role.md) | TDEVAL-* |
+| planner | [roles/planner/role.md](roles/planner/role.md) | TDPLAN-* |
+| executor | [roles/executor/role.md](roles/executor/role.md) | TDFIX-* |
+| validator | [roles/validator/role.md](roles/validator/role.md) | TDVAL-* |
+
+**Session**: `.workflow/.csv-wave/{YYYYMMDD}-td-{slug}/`
+
+### Scan Dimensions
+code, architecture, testing, dependency, documentation
+</context>
+
+<csv_schema>
+
+### tasks.csv (Input columns)
+
+```csv
+id,title,description,role,scan_dimension,deps,context_from,wave
+```
+
+| Column | Description |
+|--------|-------------|
+| `id` | Task ID: `{PREFIX}-{NNN}` |
+| `title` | Short task title |
+| `description` | PURPOSE/TASK/EXPECTED/CONSTRAINTS |
+| `role` | Fixed role name |
+| `scan_dimension` | code/arch/testing/deps/docs or empty |
+| `deps` | Semicolon-separated dependency IDs |
+| `context_from` | Context source IDs |
+| `wave` | Wave number |
+
+**Output columns** (via `output_schema` only):
+
+| Column | Description |
+|--------|-------------|
+| `result_status` | completed / failed / blocked |
+| `findings` | Key findings (max 500 chars) |
+| `files_modified` | Semicolon-separated paths |
+| `debt_count` | Number of debt items found/fixed |
+| `regression_detected` | true/false (for TDVAL tasks) |
+| `error` | Error message |
+
+**Column separation rule**: Input and Output MUST NOT share names.
+
+### Pipeline Wave Assignments
+
+#### scan (2 waves)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | TDSCAN-001 | scanner |
+| 2 | TDEVAL-001 | assessor |
+
+#### remediate (5+ waves, with plan gate + GC)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | TDSCAN-001 | scanner |
+| 2 | TDEVAL-001 | assessor |
+| 3 | TDPLAN-001 | planner |
+| — | User plan approval gate | — |
+| 4 | TDFIX-001 | executor |
+| 5 | TDVAL-001 | validator |
+| 5+ | GC: TDFIX+TDVAL if regression_detected (max 3) | executor, validator |
+
+#### targeted (3+ waves, skip scan)
+
+| Wave | Task | Role |
+|------|------|------|
+| 1 | TDPLAN-001 | planner |
+| — | User plan approval gate | — |
+| 2 | TDFIX-001 | executor |
+| 3 | TDVAL-001 | validator |
+| 3+ | GC if regression_detected (max 3) | executor, validator |
+</csv_schema>
+
+<invariants>
+1. **Wave Order Sacred**
+2. **CSV Source of Truth**
+3. **Column Separation Rule**
+4. **Plan Approval Gate**: User must approve remediation plan (skip if -y)
+5. **Fix-Verify GC Max 3**: On regression detection
+6. **Discovery Board Append-Only**
+7. **Cleanup Temp Files**
+8. **DO NOT STOP**: Continuous between gates
+9. **Role Files Authoritative**
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE       — Parse arguments, detect mode
+S_CSV_GEN     — Generate tasks.csv
+S_WAVE_{N}    — Execute wave N
+S_PLAN_GATE   — User approval of remediation plan
+S_GC_CHECK    — Regression check after TDVAL
+S_AGGREGATE   — Generate report
+</states>
+
+<transitions>
+S_PARSE → S_CSV_GEN
+S_CSV_GEN → S_WAVE_1
+S_WAVE_{N} → S_PLAN_GATE       WHEN: TDPLAN wave complete, TDFIX pending
+S_WAVE_{N} → S_GC_CHECK        WHEN: TDVAL wave complete, regression_detected possible
+S_WAVE_{N} → S_WAVE_{N+1}      WHEN: more waves
+S_WAVE_{N} → S_AGGREGATE       WHEN: last wave
+S_PLAN_GATE → S_WAVE_{N+1}     WHEN: user approves
+S_PLAN_GATE → S_WAVE_{N}       WHEN: user requests revision (re-run TDPLAN with feedback)
+S_PLAN_GATE → S_AGGREGATE      WHEN: user aborts
+S_GC_CHECK → S_AGGREGATE       WHEN: no regression or gc_rounds >= 3
+S_GC_CHECK → S_WAVE_{N+1}      WHEN: regression, add TDFIX+TDVAL rows
+</transitions>
+
+<actions>
+
+### Plan Gate
+
+After TDPLAN wave:
+1. Read planner's `findings` (remediation plan)
+2. Display: debt items, priority, estimated effort
+3. `request_user_input`: Approve / Revise / Abort
+4. Approve → continue to TDFIX wave
+5. Revise → re-run TDPLAN with feedback
+6. Abort → aggregate with scan+assess results only
+
+### Fix-Verify GC Loop
+
+After TDVAL wave:
+1. Read `regression_detected` from results
+2. No regression → complete
+3. Regression AND gc_rounds < 3 → add TDFIX+TDVAL rows, iterate
+4. gc_rounds >= 3 → escalate to user
+
+### Instruction Builder
+
+```
+You are a team-tech-debt agent.
+Role: read 'role' column. Task: read 'description' column.
+
+## Role Definition
+Read: {skillRoot}/roles/{role}/role.md
+
+## Context
+Session: {sessionFolder}
+Discovery board: {sessionFolder}/discoveries.ndjson
+Previous context: 'prev_context' column
+
+## Output
+result_status, findings, files_modified, debt_count, regression_detected (TDVAL), error
+```
+
+</actions>
+</state_machine>
+
+<error_codes>
+
+| Condition | Recovery |
+|-----------|----------|
+| Scanner found 0 debt items | Skip to aggregate, report clean |
+| Regression persists after 3 GC rounds | Escalate to user |
+| Plan rejected by user | Aggregate with scan results only |
+| Fix introduces new debt | Log warning, continue to validation |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode selected and CSV generated
+- [ ] Scan → Assess → Plan → Fix → Validate pipeline
+- [ ] User approval gate for remediation plan
+- [ ] Fix-Verify GC loop on regression (max 3)
+- [ ] Column separation maintained
+- [ ] results.csv and context.md generated
+</success_criteria>