maestro-flow 0.1.0

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

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,163 @@
+# 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

@@ -0,0 +1,272 @@
+# 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.
+
+1. Read tasks.json
+2. Count tasks by status (pending, in_progress, completed, failed)
+
+```
+Pipeline Status (<mode>):
+  [DONE]  TDSCAN-001  (scanner)   -> scan complete
+  [DONE]  TDEVAL-001  (assessor)  -> assessment ready
+  [RUN]   TDPLAN-001  (planner)   -> planning...
+  [WAIT]  TDFIX-001   (executor)  -> blocked by TDPLAN-001
+  [WAIT]  TDVAL-001   (validator) -> blocked by TDFIX-001
+
+GC Rounds: 0/3
+Session: <session-id>
+Commands: 'resume' to advance | 'check' to refresh
+```
+
+Output status -- do NOT advance pipeline.
+
+## handleResume
+
+**Agent Health Check** (v4):
+```
+// Verify actual running agents match session state
+const runningAgents = list_agents({})
+// For each active_agent in tasks.json:
+//   - If agent NOT in runningAgents -> agent crashed
+//   - Reset that task to pending, remove from active_agents
+// This prevents stale agent references from blocking the pipeline
+```
+
+1. Read tasks.json, check active_agents
+2. Tasks stuck in "in_progress" -> reset to "pending"
+3. Tasks with completed deps but still "pending" -> include in spawn list
+4. -> handleSpawnNext
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, wait for completion, process results.
+
+1. Read tasks.json
+2. Collect: completedTasks, inProgressTasks, readyTasks (pending + all deps completed)
+3. No ready + work in progress -> report waiting, STOP
+4. No ready + nothing in progress -> handleComplete
+5. Has ready -> for each:
+   a. Check inner loop role with active worker -> skip (worker picks up)
+   b. Update task status in tasks.json -> in_progress
+   c. team_msg log -> task_unblocked
+
+### Spawn Workers
+
+For each ready task:
+
+```javascript
+// 1) Update status in tasks.json
+state.tasks[taskId].status = 'in_progress'
+
+// 2) Spawn worker
+const agentId = spawn_agent({
+  agent_type: "team_worker",
+  task_name: taskId,  // e.g., "TDSCAN-001" — enables named targeting
+  items: [
+    { type: "text", text: `## Role Assignment
+role: ${task.role}
+role_spec: ${skillRoot}/roles/${task.role}/role.md
+session: ${sessionFolder}
+session_id: ${sessionId}
+team_name: tech-debt
+requirement: ${task.description}
+inner_loop: ${task.role === 'executor'}` },
+
+    { type: "text", text: `Read role_spec file (${skillRoot}/roles/${task.role}/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).` },
+
+    { type: "text", text: `## Task Context
+task_id: ${taskId}
+title: ${task.title}
+description: ${task.description}` },
+
+    { type: "text", text: `## Upstream Context\n${prevContext}` }
+  ]
+})
+
+// 3) Track agent
+state.active_agents[taskId] = { agentId, role: task.role, started_at: now }
+```
+
+Stage-to-role mapping:
+| Task Prefix | Role |
+|-------------|------|
+| TDSCAN | scanner |
+| TDEVAL | assessor |
+| TDPLAN | planner |
+| TDFIX | executor |
+| TDVAL | validator |
+
+### Wait and Process Results
+
+After spawning all ready tasks:
+
+```javascript
+// 4) Batch wait — use task_name for stable targeting (v4)
+const taskNames = Object.keys(state.active_agents)
+const waitResult = wait_agent({ targets: taskNames, timeout_ms: 900000 })
+if (waitResult.timed_out) {
+  for (const taskId of taskNames) {
+    state.tasks[taskId].status = 'timed_out'
+    close_agent({ target: taskId })
+    delete state.active_agents[taskId]
+  }
+} else {
+  // 5) Collect results
+  for (const [taskId, agent] of Object.entries(state.active_agents)) {
+    state.tasks[taskId].status = 'completed'
+    close_agent({ target: taskId })  // Use task_name, not agentId
+    delete state.active_agents[taskId]
+  }
+}
+```
+
+### Checkpoint Processing
+
+After task completion, check for checkpoints:
+
+- **TDPLAN-001 completes** -> Plan Approval Gate:
+  ```javascript
+  request_user_input({
+    questions: [{
+      question: "Remediation plan generated. Review and decide:",
+      header: "Plan Review",
+      multiSelect: false,
+      options: [
+        { label: "Approve", description: "Proceed with fix execution" },
+        { label: "Revise", description: "Re-run planner with feedback" },
+        { label: "Abort", description: "Stop pipeline" }
+      ]
+    }]
+  })
+  ```
+  - Approve -> Worktree Creation -> continue handleSpawnNext loop
+  - Revise -> Add TDPLAN-revised task to tasks.json -> continue
+  - Abort -> Log shutdown -> handleComplete
+
+- **Worktree Creation** (before TDFIX):
+  ```
+  Bash("git worktree add .worktrees/TD-<slug>-<date> -b tech-debt/TD-<slug>-<date>")
+  ```
+  Update .msg/meta.json with worktree info.
+
+- **TDVAL-* completes** -> GC Loop Check:
+  Read validation results from .msg/meta.json
+
+  | Condition | Action |
+  |-----------|--------|
+  | No regressions | -> continue (pipeline complete) |
+  | Regressions AND gc_rounds < 3 | Add fix-verify tasks to tasks.json, increment gc_rounds |
+  | Regressions AND gc_rounds >= 3 | Accept current state -> handleComplete |
+
+  Fix-Verify Task Creation (add to tasks.json):
+  ```json
+  {
+    "TDFIX-fix-<round>": {
+      "title": "Fix regressions (Fix-Verify #<round>)",
+      "description": "PURPOSE: Fix regressions | Session: <session>",
+      "role": "executor",
+      "prefix": "TDFIX",
+      "deps": [],
+      "status": "pending",
+      "findings": null,
+      "error": null
+    },
+    "TDVAL-recheck-<round>": {
+      "title": "Recheck after fix (Fix-Verify #<round>)",
+      "description": "Re-validate after fix",
+      "role": "validator",
+      "prefix": "TDVAL",
+      "deps": ["TDFIX-fix-<round>"],
+      "status": "pending",
+      "findings": null,
+      "error": null
+    }
+  }
+  ```
+
+**Cross-Agent Supplementary Context** (v4):
+
+When spawning workers in a later pipeline phase, send upstream results as supplementary context to already-running workers:
+
+```
+// Example: Send scan results to running assessor
+send_message({
+  target: "<running-agent-task-name>",
+  items: [{ type: "text", text: `## Supplementary Context\n${upstreamFindings}` }]
+})
+// Note: send_message queues info without interrupting the agent's current work
+```
+
+Use `send_message` (not `assign_task`) for supplementary info that enriches but doesn't redirect the agent's current task.
+
+### Persist and Loop
+
+After processing all results:
+1. Write updated tasks.json
+2. Check if more tasks are now ready (deps newly resolved)
+3. If yes -> loop back to step 1 of handleSpawnNext
+4. If no more ready and all done -> handleComplete
+5. If no more ready but some still blocked -> report status, STOP
+
+## handleComplete
+
+**Cleanup Verification** (v4):
+```
+// Verify all agents are properly closed
+const remaining = list_agents({})
+// If any team agents still running -> close_agent each
+// Ensures clean session shutdown
+```
+
+Pipeline done. Generate report and completion action.
+
+1. Verify all tasks (including fix-verify tasks) have status "completed"
+2. If any not completed -> handleSpawnNext
+3. If all completed:
+   - Read final state from .msg/meta.json
+   - If worktree exists and validation passed: commit, push, gh pr create, cleanup worktree
+   - Compile summary: total tasks, completed, gc_rounds, debt_score_before, debt_score_after
+   - Transition to coordinator Phase 5
+4. Execute completion action per tasks.json completion_action:
+   - interactive -> request_user_input (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (rm -rf session folder)
+   - auto_keep -> Keep Active (status=paused)
+
+## 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 coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_agents with spawned successors
+3. No duplicate spawns

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

@@ -0,0 +1,172 @@
+# 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` / `assign_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("ccw cli ...")                           — 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 `assign_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.
+- **assign_task**: Assign new work and trigger processing. Use for: waking idle agents, redirecting work, requesting new output.
+
+### 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, assign_task, and close_agent calls.
+
+## 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 |