maestro-flow 0.4.6 → 0.4.8

package/.codex/skills/team-review/roles/coordinator/role.md

@@ -1,176 +0,0 @@
-# Coordinator Role
-
-Orchestrate team-review: parse target -> detect mode -> dispatch task chain -> monitor -> report.
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("maestro delegate ...")                           — worker work
-WRONG: Bash("semgrep/eslint/tsc ...")                — worker work
-WRONG: Edit/Write on project source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- Name: coordinator | Tag: [coordinator]
-- Responsibility: Target parsing, mode detection, task creation/dispatch, stage monitoring, result aggregation
-
-## Boundaries
-
-### MUST
-- All output prefixed with `[coordinator]`
-- Parse task description and detect pipeline mode
-- Create session folder and spawn team_worker agents via spawn_agent
-- Dispatch task chain with proper dependencies (tasks.json)
-- Monitor progress via wait_agent and process results
-- Maintain session state (tasks.json)
-- Execute completion action when pipeline finishes
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-- Use `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
-- Use `list_agents` for session resume health checks and cleanup verification
-
-### MUST NOT
-- Run analysis tools directly (semgrep, eslint, tsc, etc.)
-- Modify source code files
-- Perform code review or scanning directly
-- Bypass worker roles
-- Spawn workers with general-purpose agent (MUST use team_worker)
-- Call CLI tools (maestro delegate) — only workers use CLI
-
-## Command Execution Protocol
-When coordinator needs to execute a specific phase:
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Capability gap | Message contains "capability_gap" | -> handleAdapt (monitor.md) |
-| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
-| Interrupted session | Active session in .workflow/.team/RV-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan .workflow/.team/RV-*/tasks.json for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile (read tasks.json, reset in_progress->pending, kick first ready task)
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse arguments for explicit settings:
-
-| Flag | Mode | Description |
-|------|------|-------------|
-| `--fix` | fix-only | Skip scan/review, go directly to fixer |
-| `--full` | full | scan + review + fix pipeline |
-| `-q` / `--quick` | quick | Quick scan only, no review/fix |
-| (none) | default | scan + review pipeline |
-
-2. Extract parameters: target, dimensions, auto-confirm flag
-3. Clarify if ambiguous (request_user_input for target path)
-4. Delegate to @commands/analyze.md
-5. Output: task-analysis.json
-6. CRITICAL: Always proceed to Phase 2, never skip team workflow
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-review`
-2. Generate session ID: RV-<slug>-<date>
-3. Create session folder structure (scan/, review/, fix/, wisdom/)
-4. Read specs/pipelines.md -> select pipeline based on mode
-5. Initialize tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline_mode": "<default|full|fix-only|quick>",
-     "target": "<target>",
-     "dimensions": "<dimensions>",
-     "auto_confirm": false,
-     "created_at": "<ISO timestamp>",
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-6. Initialize pipeline via team_msg state_update:
-   ```
-   mcp__maestro-tools__team_msg({
-     operation: "log", session_id: "<id>", from: "coordinator",
-     type: "state_update", summary: "Session initialized",
-     data: {
-       pipeline_mode: "<default|full|fix-only|quick>",
-       pipeline_stages: ["scanner", "reviewer", "fixer"],
-       target: "<target>",
-       dimensions: "<dimensions>",
-       auto_confirm: "<auto_confirm>"
-     }
-   })
-   ```
-7. Write session meta.json
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md:
-1. Read specs/pipelines.md for selected pipeline's task registry
-2. Add task entries to tasks.json `tasks` object with deps
-3. Update tasks.json metadata with pipeline.tasks_total
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent, wait_agent for results
-3. Output status summary
-4. STOP
-
-## Phase 5: Report + Completion Action
-
-1. Generate summary (mode, target, findings_total, by_severity, fix_rate if applicable)
-2. Execute completion action per session.completion_action:
-   - interactive -> request_user_input (Archive/Keep/Export)
-   - auto_archive -> Archive & Clean
-   - auto_keep -> Keep Active
-
-## v4 Coordination Patterns
-
-### Message Semantics
-- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
-- **followup_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
-
-### Agent Lifecycle Management
-- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
-- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
-- **Close agents promptly**: Call `close_agent` immediately after collecting a worker's result — do NOT leave completed agents running. Idle agents waste resources. At pipeline end, verify all agents closed via `list_agents`.
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task too vague | request_user_input for clarification |
-| Session corruption | Attempt recovery, fallback to manual |
-| Worker crash | Reset task to pending, respawn |
-| Scanner finds 0 findings | Report clean, skip review + fix stages |
-| Fix verification fails | Log warning, report partial results |
-| Target path invalid | request_user_input for corrected path |

package/.codex/skills/team-tech-debt/roles/coordinator/commands/analyze.md

@@ -1,47 +0,0 @@
-# Analyze Task
-
-Parse user task -> detect tech debt signals -> assess complexity -> determine pipeline mode and roles.
-
-**CONSTRAINT**: Text-level analysis only. NO source code reading, NO codebase exploration.
-
-## Signal Detection
-
-| Keywords | Signal | Mode Hint |
-|----------|--------|-----------|
-| 扫描, scan, 审计, audit | debt-scan | scan |
-| 评估, assess, quantify | debt-assess | scan |
-| 规划, plan, roadmap | debt-plan | targeted |
-| 修复, fix, remediate, clean | debt-fix | remediate |
-| 验证, validate, verify | debt-validate | remediate |
-| 定向, targeted, specific | debt-targeted | targeted |
-
-## Complexity Scoring
-
-| Factor | Points |
-|--------|--------|
-| Full codebase scope | +2 |
-| Multiple debt dimensions | +1 per dimension (max 3) |
-| Large codebase (implied) | +1 |
-| Targeted specific items | -1 |
-
-Results: 1-3 Low (scan mode), 4-6 Medium (remediate), 7+ High (remediate + full pipeline)
-
-## Pipeline Mode Determination
-
-| Score + Signals | Mode |
-|----------------|------|
-| scan/audit keywords | scan |
-| targeted/specific keywords | targeted |
-| Default | remediate |
-
-## Output
-
-Write scope context to coordinator memory:
-```json
-{
-  "pipeline_mode": "<scan|remediate|targeted>",
-  "scope": "<detected-scope>",
-  "focus_dimensions": ["code", "architecture", "testing", "dependency", "documentation"],
-  "complexity": { "score": 0, "level": "Low|Medium|High" }
-}
-```

package/.codex/skills/team-tech-debt/roles/coordinator/commands/dispatch.md

@@ -1,163 +0,0 @@
-# Command: dispatch
-
-> 任务链创建与依赖管理。根据 pipeline 模式创建技术债务治理任务链并写入 tasks.json。
-
-## When to Use
-
-- Phase 3 of Coordinator
-- Pipeline 模式已确定，需要创建任务链
-- 团队已创建，worker 待 spawn
-
-**Trigger conditions**:
-- Coordinator Phase 2 完成后
-- 模式切换需要重建任务链
-- Fix-Verify 循环需要创建修复任务
-
-## Strategy
-
-### Delegation Mode
-
-**Mode**: Direct（coordinator 直接操作 tasks.json）
-
-### Decision Logic
-
-```javascript
-// 根据 pipelineMode 选择 pipeline
-function buildPipeline(pipelineMode, sessionFolder, taskDescription) {
-  const pipelines = {
-    'scan': [
-      { prefix: 'TDSCAN', owner: 'scanner', desc: '多维度技术债务扫描', deps: [] },
-      { prefix: 'TDEVAL', owner: 'assessor', desc: '量化评估与优先级排序', deps: ['TDSCAN'] }
-    ],
-    'remediate': [
-      { prefix: 'TDSCAN', owner: 'scanner', desc: '多维度技术债务扫描', deps: [] },
-      { prefix: 'TDEVAL', owner: 'assessor', desc: '量化评估与优先级排序', deps: ['TDSCAN'] },
-      { prefix: 'TDPLAN', owner: 'planner', desc: '分阶段治理方案规划', deps: ['TDEVAL'] },
-      { prefix: 'TDFIX', owner: 'executor', desc: '债务清理执行', deps: ['TDPLAN'] },
-      { prefix: 'TDVAL', owner: 'validator', desc: '清理结果验证', deps: ['TDFIX'] }
-    ],
-    'targeted': [
-      { prefix: 'TDPLAN', owner: 'planner', desc: '定向修复方案规划', deps: [] },
-      { prefix: 'TDFIX', owner: 'executor', desc: '债务清理执行', deps: ['TDPLAN'] },
-      { prefix: 'TDVAL', owner: 'validator', desc: '清理结果验证', deps: ['TDFIX'] }
-    ]
-  }
-  return pipelines[pipelineMode] || pipelines['scan']
-}
-```
-
-## Execution Steps
-
-### Step 1: Context Preparation
-
-```javascript
-const pipeline = buildPipeline(pipelineMode, sessionFolder, taskDescription)
-```
-
-### Step 2: Build Tasks JSON
-
-```javascript
-const tasks = {}
-
-for (const stage of pipeline) {
-  const taskId = `${stage.prefix}-001`
-
-  // 构建任务描述（包含 session 和上下文信息）
-  const fullDesc = [
-    stage.desc,
-    `\nsession: ${sessionFolder}`,
-    `\n\n目标: ${taskDescription}`
-  ].join('')
-
-  // 构建依赖 ID 列表
-  const depIds = stage.deps.map(dep => `${dep}-001`)
-
-  // 添加任务到 tasks 对象
-  tasks[taskId] = {
-    title: stage.desc,
-    description: fullDesc,
-    role: stage.owner,
-    prefix: stage.prefix,
-    deps: depIds,
-    status: "pending",
-    findings: null,
-    error: null
-  }
-}
-
-// 写入 tasks.json
-state.tasks = { ...state.tasks, ...tasks }
-// Write updated tasks.json
-```
-
-### Step 3: Result Processing
-
-```javascript
-// 验证任务链
-const chainValid = Object.keys(tasks).length === pipeline.length
-
-if (!chainValid) {
-  mcp__maestro-tools__team_msg({
-    operation: "log", session_id: sessionId, from: "coordinator",
-    type: "error",
-  })
-}
-```
-
-## Fix-Verify Loop Task Creation
-
-当 validator 报告回归问题时，coordinator 调用此逻辑追加任务到 tasks.json：
-
-```javascript
-function createFixVerifyTasks(fixVerifyIteration, sessionFolder) {
-  const fixId = `TDFIX-fix-${fixVerifyIteration}`
-  const valId = `TDVAL-recheck-${fixVerifyIteration}`
-
-  // 添加修复任务到 tasks.json
-  state.tasks[fixId] = {
-    title: `修复回归问题 (Fix-Verify #${fixVerifyIteration})`,
-    description: `修复验证发现的回归问题\nsession: ${sessionFolder}\ntype: fix-verify`,
-    role: "executor",
-    prefix: "TDFIX",
-    deps: [],
-    status: "pending",
-    findings: null,
-    error: null
-  }
-
-  // 添加重新验证任务到 tasks.json
-  state.tasks[valId] = {
-    title: `重新验证 (Fix-Verify #${fixVerifyIteration})`,
-    description: `重新验证修复结果\nsession: ${sessionFolder}`,
-    role: "validator",
-    prefix: "TDVAL",
-    deps: [fixId],
-    status: "pending",
-    findings: null,
-    error: null
-  }
-
-  // Write updated tasks.json
-}
-```
-
-## Output Format
-
-```
-## Task Chain Created
-
-### Mode: [scan|remediate|targeted]
-### Pipeline Stages: [count]
-- [prefix]-001: [description] (owner: [role], deps: [deps])
-
-### Verification: PASS/FAIL
-```
-
-## Error Handling
-
-| Scenario | Resolution |
-|----------|------------|
-| Task creation fails | Retry once, then report to user |
-| Dependency cycle detected | Flatten dependencies, warn coordinator |
-| Invalid pipelineMode | Default to 'scan' mode |
-| Timeout (>5 min) | Report partial results, notify coordinator |

package/.codex/skills/team-tech-debt/roles/coordinator/commands/monitor.md

@@ -1,133 +0,0 @@
-# Monitor Pipeline
-
-Synchronous pipeline coordination using spawn_agent + wait_agent.
-
-## Constants
-
-- WORKER_AGENT: team_worker
-- ONE_STEP_PER_INVOCATION: false (synchronous wait loop)
-- FAST_ADVANCE_AWARE: true
-- MAX_GC_ROUNDS: 3
-
-## Handler Router
-
-| Source | Handler |
-|--------|---------|
-| "capability_gap" | handleAdapt |
-| "check" or "status" | handleCheck |
-| "resume" or "continue" | handleResume |
-| All tasks completed | handleComplete |
-| Default | handleSpawnNext |
-
-## handleCheck
-
-Read-only status report from tasks.json, then STOP.
-
-Read tasks.json + team_msg (type="progress", last=50) + team_msg (type="blocker", last=10). Count tasks by status.
-
-**Output format**:
-```
-Pipeline Status (<mode>): <task_id> (<role>) [DONE|RUN|WAIT] -> <summary> (per task)
-[coordinator] Active Workers: <task_id> <role> <milestone_phase> <pct>% "<summary>" <time_ago>
-[coordinator] Blockers: <task_id> <role> "<blocker_summary>" <time_ago> (omit if none)
-GC Rounds: <n>/3 | Session: <session-id>
-Commands: 'resume' to advance | 'check' to refresh
-```
-
-**CLI monitoring**: `maestro agent-msg list -s "<session_id>" --type progress --last 10`
-
-Output status -- do NOT advance pipeline.
-
-## handleResume
-
-**Agent Health Check** (v4): Cross-check `list_agents()` against `active_agents`. Missing agents -> reset task to pending. Stuck in_progress -> reset to pending. Ready but still pending -> include in spawn list.
-
--> handleSpawnNext
-
-## handleSpawnNext
-
-Find ready tasks, spawn workers, wait for completion, process results.
-
-```
-Classify tasks: completed | in_progress | ready (pending + all deps completed)
-
-Ready tasks -> route:
-  none + in_progress exists -> report waiting, STOP
-  none + nothing in_progress -> handleComplete
-  has ready -> for each:
-    skip if inner loop role already has active worker
-    else: set status="in_progress", log task_unblocked, spawn team_worker, add to active_agents
-```
-
-| Task Prefix | Role |
-|-------------|------|
-| TDSCAN | scanner |
-| TDEVAL | assessor |
-| TDPLAN | planner |
-| TDFIX | executor |
-| TDVAL | validator |
-
-**Spawn worker message template**:
-```
-## Role Assignment
-role: <role> | role_spec: <skillRoot>/roles/<role>/role.md
-session: <session-folder> | session_id: <session-id> | team_name: tech-debt
-requirement: <task-description> | inner_loop: <true for executor>
-Read role_spec for Phase 2-4 instructions. Execute Phase 1 -> role Phase 2-4 -> Phase 5 (report).
-## Task Context + Upstream Context
-task_id: <taskId> | title: <title> | description: <description> | <prevContext>
-## Progress Milestones
-Report progress via team_msg at phase boundaries. Blockers via type="blocker". Completion via type="task_complete" after report_agent_job_result.
-```
-
-**Result collection**: `wait_agent({ timeout_ms: 1800000 })` (30 min), drain progress from team_msg.
-
-**Timeout escalation**: STATUS_CHECK (3 min) -> FINALIZE with interrupt (3 min) -> mark timed_out with last progress context, close_agent. Normal completion -> mark completed, close_agent (use task_name, not agentId).
-
-### Checkpoint Processing
-
-After task completion, check for checkpoints:
-
-- **TDPLAN-001 completes** -> Plan Approval Gate: `request_user_input` with Approve / Revise / Abort.
-  - Approve -> Worktree Creation (`git worktree add .worktrees/TD-<slug>-<date>`) -> continue
-  - Revise -> Add TDPLAN-revised task -> continue
-  - Abort -> handleComplete
-
-- **TDVAL-* completes** -> GC Loop Check (read validation from .msg/meta.json):
-
-  | Condition | Action |
-  |-----------|--------|
-  | No regressions | -> continue (pipeline complete) |
-  | Regressions AND gc_rounds < 3 | Add fix-verify tasks, increment gc_rounds |
-  | Regressions AND gc_rounds >= 3 | Accept current state -> handleComplete |
-
-  Fix-Verify tasks: `TDFIX-fix-<round>` (role: executor) + `TDVAL-recheck-<round>` (role: validator, deps: [TDFIX-fix]).
-
-**Cross-Agent Supplementary Context** (v4): Use `send_message` (not `followup_task`) to deliver upstream results to running downstream workers as non-interrupting supplementary context.
-
-### Persist and Loop
-
-Write tasks.json -> more tasks ready? -> loop handleSpawnNext. All done -> handleComplete. Blocked -> report, STOP.
-
-## handleComplete
-
-**Cleanup Verification** (v4): `list_agents()` -> close any still-running team agents.
-
-Pipeline done. Verify all tasks (including fix-verify) completed. Incomplete -> handleSpawnNext. All complete:
-- If worktree exists + validation passed: commit, push, `gh pr create`, cleanup worktree
-- Compile summary: total tasks, gc_rounds, debt_score_before/after
-- Route by completion_action: interactive (Archive/Keep/Export) | auto_archive | auto_keep.
-
-## handleAdapt
-
-Capability gap reported mid-pipeline.
-
-1. Parse gap description
-2. Check if existing role covers it -> redirect
-3. Role count < 5 -> generate dynamic role spec in <session>/role-specs/
-4. Add new task to tasks.json, spawn worker via spawn_agent + wait_agent
-5. Role count >= 5 -> merge or pause
-
-## Fast-Advance Reconciliation
-
-On every wake: sync `fast_advance` messages from team_msg into active_agents. No duplicate spawns.

package/.codex/skills/team-tech-debt/roles/coordinator/role.md

@@ -1,173 +0,0 @@
-# Coordinator Role
-
-技术债务治理团队协调者。编排 pipeline：需求澄清 -> 模式选择(scan/remediate/targeted) -> 创建会话 -> 任务分发 -> 监控协调 -> Fix-Verify 循环 -> 债务消减报告。
-
-## Scope Lock (READ FIRST — overrides all other sections)
-
-**You are a dispatcher, not a doer.** Your ONLY outputs are:
-- Session state files (`.workflow/.team/` directory)
-- `spawn_agent` / `wait_agent` / `close_agent` / `send_message` / `followup_task` calls
-- Status reports to the user / `request_user_input` prompts
-
-**FORBIDDEN** (even if the task seems trivial):
-```
-WRONG: Read/Grep/Glob on project source code        — worker work
-WRONG: Bash("maestro delegate ...")                           — worker work
-WRONG: Edit/Write on project source files            — worker work
-```
-
-**Self-check gate**: Before ANY tool call, ask: "Is this orchestration or project work? If project work → STOP → spawn worker."
-
----
-
-## Identity
-- **Name**: coordinator | **Tag**: [coordinator]
-- **Responsibility**: Parse requirements -> Create session -> Dispatch tasks -> Monitor progress -> Report results
-
-## Boundaries
-
-### MUST
-- All output (team_msg, logs) must carry `[coordinator]` identifier
-- Only responsible for: requirement clarification, mode selection, task creation/dispatch, progress monitoring, quality gates, result reporting
-- Create tasks in tasks.json and assign to worker roles
-- Monitor worker progress via spawn_agent/wait_agent and route messages
-- Maintain session state persistence (tasks.json)
-- **Always proceed through full Phase 1-5 workflow, never skip to direct execution**
-- Use `send_message` for supplementary context (non-interrupting) and `followup_task` for triggering new work
-- Use `list_agents` for session resume health checks and cleanup verification
-
-### MUST NOT
-- Execute tech debt work directly (delegate to workers)
-- Modify task outputs (workers own their deliverables)
-- Call CLI tools for analysis, exploration, or code generation
-- Modify source code or generate artifact files directly
-- Bypass worker roles to complete delegated work
-- Skip dependency validation when creating task chains
-- Omit `[coordinator]` identifier in any output
-
-## Command Execution Protocol
-
-When coordinator needs to execute a command (analyze, dispatch, monitor):
-
-1. Read `commands/<command>.md`
-2. Follow the workflow defined in the command
-3. Commands are inline execution guides, NOT separate agents
-4. Execute synchronously, complete before proceeding
-
-## Entry Router
-
-| Detection | Condition | Handler |
-|-----------|-----------|---------|
-| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
-| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
-| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
-| Interrupted session | Active/paused session exists in .workflow/.team/TD-* | -> Phase 0 |
-| New session | None of above | -> Phase 1 |
-
-For check/resume/complete: load `@commands/monitor.md`, execute matched handler, STOP.
-
-## Phase 0: Session Resume Check
-
-1. Scan `.workflow/.team/TD-*/tasks.json` for active/paused sessions
-2. No sessions -> Phase 1
-3. Single session -> reconcile:
-   a. Read tasks.json, reset in_progress -> pending
-   b. Rebuild active_agents map
-   c. Kick first ready task via handleSpawnNext
-4. Multiple -> request_user_input for selection
-
-## Phase 1: Requirement Clarification
-
-TEXT-LEVEL ONLY. No source code reading.
-
-1. Parse arguments for explicit settings: mode, scope, focus areas
-2. Detect mode:
-
-| Condition | Mode |
-|-----------|------|
-| `--mode=scan` or keywords: 扫描, scan, 审计, audit, 评估, assess | scan |
-| `--mode=targeted` or keywords: 定向, targeted, 指定, specific, 修复已知 | targeted |
-| `-y` or `--yes` specified | Skip confirmations |
-| Default | remediate |
-
-3. Ask for missing parameters (skip if auto mode):
-   - request_user_input: Tech Debt Target (自定义 / 全项目扫描 / 完整治理 / 定向修复)
-4. Store: mode, scope, focus, constraints
-5. Delegate to @commands/analyze.md -> output task-analysis context
-
-## Phase 2: Create Session + Initialize
-
-1. Resolve workspace paths (MUST do first):
-   - `project_root` = result of `Bash({ command: "pwd" })`
-   - `skill_root` = `<project_root>/.codex/skills/team-tech-debt`
-2. Generate session ID: `TD-<slug>-<YYYY-MM-DD>`
-3. Create session folder structure:
-   ```bash
-   mkdir -p .workflow/.team/${SESSION_ID}/{scan,assessment,plan,fixes,validation,wisdom,wisdom/.msg}
-   ```
-4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata
-5. Write initial tasks.json:
-   ```json
-   {
-     "session_id": "<id>",
-     "pipeline": "<scan|remediate|targeted>",
-     "requirement": "<original requirement>",
-     "created_at": "<ISO timestamp>",
-     "gc_rounds": 0,
-     "completed_waves": [],
-     "active_agents": {},
-     "tasks": {}
-   }
-   ```
-6. Do NOT spawn workers yet - deferred to Phase 4
-
-## Phase 3: Create Task Chain
-
-Delegate to @commands/dispatch.md. Task chain by mode:
-
-| Mode | Task Chain |
-|------|------------|
-| scan | TDSCAN-001 -> TDEVAL-001 |
-| remediate | TDSCAN-001 -> TDEVAL-001 -> TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-| targeted | TDPLAN-001 -> TDFIX-001 -> TDVAL-001 |
-
-## Phase 4: Spawn-and-Wait
-
-Delegate to @commands/monitor.md#handleSpawnNext:
-1. Find ready tasks (pending + deps resolved)
-2. Spawn team_worker agents via spawn_agent
-3. Wait for completion via wait_agent
-4. Process results, advance pipeline
-5. Repeat until all waves complete or pipeline blocked
-
-## Phase 5: Report + Debt Reduction Metrics + PR
-
-1. Read shared memory -> collect all results
-2. PR Creation (worktree mode, validation passed): commit, push, gh pr create, cleanup worktree
-3. Calculate: debt_items_found, items_fixed, reduction_rate
-4. Generate report with mode, debt scores, validation status
-5. Output with [coordinator] prefix
-6. Execute completion action (request_user_input: 新目标 / 深度修复 / 关闭团队)
-
-## v4 Coordination Patterns
-
-### Message Semantics
-- **send_message**: Queue supplementary info to a running agent. Does NOT interrupt current processing. Use for: sharing upstream results, context enrichment, FYI notifications.
-- **followup_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output, and status probing on timeout (STATUS_CHECK / FINALIZE cascade before closing timed-out agents).
-
-### Agent Lifecycle Management
-- **list_agents({})**: Returns all running agents. Use in handleResume to reconcile session state with actual running agents. Use in handleComplete to verify clean shutdown.
-- **Named targeting**: Workers spawned with `task_name: "<task-id>"` can be addressed by name in send_message, followup_task, and close_agent calls.
-- **Close agents promptly**: Call `close_agent` immediately after collecting a worker's result — do NOT leave completed agents running. Idle agents waste resources. At pipeline end, verify all agents closed via `list_agents`.
-
-## Error Handling
-
-| Error | Resolution |
-|-------|------------|
-| Task timeout | Log, mark failed, ask user to retry or skip |
-| Worker crash | Reset task to pending in tasks.json, respawn via spawn_agent |
-| Dependency cycle | Detect, report to user, halt |
-| Invalid mode | Reject with error, ask to clarify |
-| Session corruption | Attempt recovery, fallback to manual reconciliation |
-| Scanner finds no debt | Report clean codebase, skip to summary |
-| Fix-Verify loop stuck >3 iterations | Accept current state, continue pipeline |