maestro-flow 0.3.9 → 0.3.11

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

@@ -4,12 +4,9 @@ description: Unified team skill for tech debt identification and remediation. Sc
 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(*)
 ---
 
-# Team Tech Debt
-
+<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`.
 
-## Architecture
-
 ```
 Skill(skill="team-tech-debt", args="task description")
                     |
@@ -29,9 +26,16 @@ Skill(skill="team-tech-debt", args="task description")
            [team-worker agents, each loads roles/<role>/role.md]
           scanner  assessor  planner  executor  validator
 ```
+</purpose>
+
+<context>
+$ARGUMENTS — task description and optional flags.
 
-## Role Registry
+**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) | — | — |
@@ -41,48 +45,59 @@ Skill(skill="team-tech-debt", args="task description")
 | executor | [roles/executor/role.md](roles/executor/role.md) | TDFIX-* | true |
 | validator | [roles/validator/role.md](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
-
-## Delegation Lock
-
-**Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.**
-
-Before calling ANY tool, apply this check:
+**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` | ALLOWED | Agent health check |
-| `request_user_input` | ALLOWED | User interaction |
-| `mcp__maestro-tools__team_msg` | ALLOWED | Message bus |
+| `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 own instructions |
+| `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("maestro delegate ...")` | BLOCKED | Only workers call CLI |
-| `Bash` running build/test/lint commands | BLOCKED | Delegate to worker |
+| `Bash` running build/test/lint | BLOCKED | Delegate to worker |
 
-**If a tool call is BLOCKED**: STOP. Create a task, spawn a worker.
+**No exceptions.** Even single-file tasks MUST go through spawn_agent.
 
-**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-<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
 
-## Shared Constants
+**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>
 
-- **Session prefix**: `TD`
-- **Session path**: `.workflow/.team/TD-<slug>-<date>/`
-- **CLI tools**: `maestro delegate --mode analysis` (read-only), `maestro delegate --mode write` (modifications)
-- **Message bus**: `mcp__maestro-tools__team_msg(session_id=<session-id>, ...)`
-- **Max GC rounds**: 3
+<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>
 
-## Worker Spawn Template
+<execution>
 
-Coordinator spawns workers using this template:
+### Worker Spawn Template
 
 ```
 spawn_agent({
@@ -97,7 +112,7 @@ 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.
+Read role_spec file to load Phase 2-4 domain instructions.
 
 ## Task Context
 task_id: <task-id>
@@ -110,90 +125,41 @@ pipeline_phase: <pipeline-phase>
 })
 ```
 
-After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results (30 min). If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target })` each worker.
-
+After spawning: `wait_agent({ timeout_ms: 1800000 })` (30 min). Timeout handling: STATUS_CHECK (3 min) → FINALIZE with interrupt (3 min) → mark timed_out, close.
 
 ### Model Selection Guide
 
-Tech debt follows a discovery-to-fix pipeline. Scanner is broad/fast, later stages need deeper reasoning.
-
 | Role | reasoning_effort | Rationale |
 |------|-------------------|-----------|
-| scanner | medium | Broad codebase scan, pattern matching over deep analysis |
-| assessor | high | Severity assessment requires understanding impact and risk |
-| planner | high | Remediation planning must prioritize and sequence fixes |
-| executor | high | Code fixes must preserve behavior while removing debt |
-| validator | medium | Validation follows defined acceptance criteria |
+| scanner | medium | Broad scan, pattern matching |
+| assessor | high | Impact and risk assessment |
+| planner | high | Prioritize and sequence fixes |
+| executor | high | Code fixes must preserve behavior |
+| validator | medium | Follows defined acceptance criteria |
 
-### 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
-
-| 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](specs/pipelines.md) — Pipeline definitions and task registry
-
-## Session Directory
-
-```
-.workflow/.team/TD-<slug>-<date>/
-├── .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
+### v4 Agent Coordination
 
+**Message Semantics:**
 | Intent | API | Example |
 |--------|-----|---------|
-| Queue supplementary info (don't interrupt) | `send_message` | Send scan findings to running assessor |
-| Assign fix from remediation plan | `followup_task` | Assign TDFIX task from planner output |
+| Queue supplementary info | `send_message` | Send scan findings to running assessor |
+| Assign fix from plan | `followup_task` | Assign TDFIX task from planner output |
 | Check running agents | `list_agents` | Verify agent health during resume |
 
-### Agent Health Check
-
-Use `list_agents({})` in handleResume and handleComplete:
-
+**Agent Health Check:**
 ```
-// 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>"` enabling direct addressing:
-- `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
+**Named Agent Targeting:**
+- `send_message({ target: "TDSCAN-001", message: "..." })` — additional scan scope
+- `followup_task({ target: "TDFIX-001", message: "..." })` — assign fix from planner
+- `close_agent({ target: "TDVAL-001" })` — cleanup after validation
+</execution>
 
+<error_codes>
 | Scenario | Resolution |
 |----------|------------|
 | Unknown command | Error with available command list |
@@ -202,3 +168,15 @@ Workers are spawned with `task_name: "<task-id>"` enabling direct addressing:
 | 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>