feat(skills): add team-roadmap-dev skill with phased execution pipeline

Roadmap-driven development team skill with coordinator/planner/executor/verifier roles. Features action-planning-agent integration (IMPL-*.json task format), convergence criteria verification, pause/resume support, and wave-based execution.
2026-02-28 09:23:08 +08:00 · 2026-02-24 23:32:32 +08:00
parent dadcc1af5e
commit 6c16c121d2
15 changed files with 3740 additions and 0 deletions
--- a/.claude/skills/team-roadmap-dev/roles/planner/role.md
+++ b/.claude/skills/team-roadmap-dev/roles/planner/role.md
@@ -0,0 +1,286 @@
+# Role: planner
+
+Research and plan creation per phase. Gathers codebase context via cli-explore-agent and Gemini CLI, then generates wave-based execution plans with must_haves verification criteria. Each plan is a self-contained unit of work that an executor can implement autonomously.
+
+## Role Identity
+
+- **Name**: `planner`
+- **Task Prefix**: `PLAN-*`
+- **Responsibility**: Orchestration (research + plan generation)
+- **Communication**: SendMessage to coordinator only
+- **Output Tag**: `[planner]`
+
+## Role Boundaries
+
+### MUST
+
+- All outputs must carry `[planner]` prefix
+- Only process `PLAN-*` prefixed tasks
+- Only communicate with coordinator (SendMessage)
+- Delegate research to commands/research.md
+- Delegate plan creation to commands/create-plans.md
+- Reference real files discovered during research (never fabricate paths)
+- Verify plans have no dependency cycles before reporting
+
+### MUST NOT
+
+- Direct code writing or modification
+- Call code-developer or other implementation subagents
+- Create tasks for other roles (TaskCreate)
+- Interact with user (AskUserQuestion)
+- Process EXEC-* or VERIFY-* tasks
+- Skip the research phase
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `plan_ready` | planner -> coordinator | Plans created | Plan files written with wave structure |
+| `plan_progress` | planner -> coordinator | Research complete | Context gathered, starting plan creation |
+| `error` | planner -> coordinator | Failure | Research or planning failed |
+
+## Message Bus
+
+```javascript
+mcp__ccw-tools__team_msg({
+  operation: "log", team: "roadmap-dev",
+  from: "planner", to: "coordinator",
+  type: messageType,
+  summary: `[planner] ${messageSummary}`,
+  ref: artifactPath
+})
+```
+
+### CLI Fallback
+
+```javascript
+Bash(`ccw team log --team "roadmap-dev" --from "planner" --to "coordinator" --type "${type}" --summary "[planner] ${summary}" --json`)
+```
+
+## Toolbox
+
+### Available Commands
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `research` | [commands/research.md](commands/research.md) | Phase 2 | Context gathering via codebase exploration |
+| `create-plans` | [commands/create-plans.md](commands/create-plans.md) | Phase 3 | Wave-based plan file generation |
+
+### Available Subagents
+
+| Subagent | Purpose | When |
+|----------|---------|------|
+| `cli-explore-agent` | Codebase exploration (file discovery, pattern analysis) | Phase 2: Research |
+| `action-planning-agent` | Task JSON + IMPL_PLAN.md generation | Phase 3: Create Plans |
+
+### CLI Tools
+
+| Tool | Mode | When |
+|------|------|------|
+| `gemini` | analysis | Deep analysis for complex phases (optional, depth=comprehensive) |
+
+## Execution
+
+### Phase 1: Task Discovery
+
+```javascript
+// Find assigned PLAN-* task
+const tasks = TaskList()
+const planTask = tasks.find(t =>
+  t.subject.startsWith('PLAN-') &&
+  t.status === 'pending' &&
+  (!t.blockedBy || t.blockedBy.length === 0)
+)
+
+if (!planTask) {
+  mcp__ccw-tools__team_msg({
+    operation: "log", team: "roadmap-dev",
+    from: "planner", to: "coordinator",
+    type: "error",
+    summary: "[planner] No available PLAN-* task found"
+  })
+  return
+}
+
+TaskUpdate({ taskId: planTask.id, status: "in_progress" })
+
+// Parse task description for session context
+const taskDetails = TaskGet({ taskId: planTask.id })
+const sessionFolder = parseSessionFolder(taskDetails.description)
+const phaseNumber = parsePhaseNumber(taskDetails.description)
+const depth = parseDepth(taskDetails.description) || "standard"
+```
+
+### Phase 2: Research (via command)
+
+```javascript
+// Delegate to research command
+Read("commands/research.md")
+// Execute research steps:
+//   1. Read roadmap.md for phase goal and requirements
+//   2. Read prior phase summaries (if any)
+//   3. Launch cli-explore-agent for codebase exploration
+//   4. Optional: Gemini CLI for deeper analysis (if depth=comprehensive)
+//   5. Write context.md to {sessionFolder}/phase-{N}/context.md
+//
+// Produces: {sessionFolder}/phase-{N}/context.md
+```
+
+**Command**: [commands/research.md](commands/research.md)
+
+```javascript
+// Report research progress
+mcp__ccw-tools__team_msg({
+  operation: "log", team: "roadmap-dev",
+  from: "planner", to: "coordinator",
+  type: "plan_progress",
+  summary: `[planner] Research complete for phase ${phaseNumber}. Context written.`,
+  ref: `${sessionFolder}/phase-${phaseNumber}/context.md`
+})
+```
+
+### Phase 3: Create Plans (via command)
+
+```javascript
+// Delegate to create-plans command
+Read("commands/create-plans.md")
+// Execute plan creation steps:
+//   1. Load context.md for phase
+//   2. Prepare output directories (.task/)
+//   3. Delegate to action-planning-agent
+//   4. Agent produces IMPL_PLAN.md + .task/IMPL-*.json + TODO_LIST.md
+//   5. Validate generated artifacts
+//   6. Return task count and dependency structure
+//
+// Produces: {sessionFolder}/phase-{N}/IMPL_PLAN.md
+//           {sessionFolder}/phase-{N}/.task/IMPL-*.json
+//           {sessionFolder}/phase-{N}/TODO_LIST.md
+```
+
+**Command**: [commands/create-plans.md](commands/create-plans.md)
+
+### Phase 4: Self-Validation
+
+```javascript
+// Verify task JSONs before reporting
+const taskFiles = Glob(`${sessionFolder}/phase-${phaseNumber}/.task/IMPL-*.json`)
+
+for (const taskFile of taskFiles) {
+  const taskJson = JSON.parse(Read(taskFile))
+
+  // 4a. Verify referenced files exist (for modify actions only)
+  for (const fileEntry of (taskJson.files || [])) {
+    if (fileEntry.action === 'modify') {
+      const exists = Bash(`test -f "${fileEntry.path}" && echo "EXISTS" || echo "NOT_FOUND"`).trim()
+      if (exists === "NOT_FOUND") {
+        mcp__ccw-tools__team_msg({
+          operation: "log", team: "roadmap-dev",
+          from: "planner", to: "coordinator",
+          type: "plan_progress",
+          summary: `[planner] Warning: ${taskJson.id} references ${fileEntry.path} for modify but file not found`,
+          ref: taskFile
+        })
+      }
+    }
+  }
+
+  // 4b. Self-dependency check
+  if ((taskJson.depends_on || []).includes(taskJson.id)) {
+    mcp__ccw-tools__team_msg({
+      operation: "log", team: "roadmap-dev",
+      from: "planner", to: "coordinator",
+      type: "error",
+      summary: `[planner] Self-dependency detected: ${taskJson.id}`,
+      ref: taskFile
+    })
+  }
+
+  // 4c. Convergence criteria check
+  if (!taskJson.convergence?.criteria?.length) {
+    mcp__ccw-tools__team_msg({
+      operation: "log", team: "roadmap-dev",
+      from: "planner", to: "coordinator",
+      type: "plan_progress",
+      summary: `[planner] Warning: ${taskJson.id} has no convergence criteria`,
+      ref: taskFile
+    })
+  }
+}
+
+// 4d. Cross-dependency validation
+const allTasks = taskFiles.map(f => JSON.parse(Read(f)))
+const taskIds = new Set(allTasks.map(t => t.id))
+for (const task of allTasks) {
+  for (const dep of (task.depends_on || [])) {
+    if (!taskIds.has(dep)) {
+      mcp__ccw-tools__team_msg({
+        operation: "log", team: "roadmap-dev",
+        from: "planner", to: "coordinator",
+        type: "plan_progress",
+        summary: `[planner] Warning: ${task.id} depends on unknown task ${dep}`
+      })
+    }
+  }
+}
+```
+
+### Phase 5: Report to Coordinator
+
+```javascript
+const taskCount = allTasks.length
+
+// Compute wave count from dependency graph
+function computeWaveCount(tasks) {
+  const waves = {}
+  const assigned = new Set()
+  let wave = 1
+  while (assigned.size < tasks.length) {
+    const ready = tasks.filter(t =>
+      !assigned.has(t.id) &&
+      (t.depends_on || []).every(d => assigned.has(d))
+    )
+    if (ready.length === 0) break
+    for (const t of ready) { waves[t.id] = wave; assigned.add(t.id) }
+    wave++
+  }
+  return wave - 1
+}
+const waveCount = computeWaveCount(allTasks)
+
+// Log plan_ready message
+mcp__ccw-tools__team_msg({
+  operation: "log", team: "roadmap-dev",
+  from: "planner", to: "coordinator",
+  type: "plan_ready",
+  summary: `[planner] Phase ${phaseNumber} planned: ${taskCount} tasks across ${waveCount} waves`,
+  ref: `${sessionFolder}/phase-${phaseNumber}/`
+})
+
+// Send message to coordinator
+SendMessage({
+  to: "coordinator",
+  message: `[planner] Phase ${phaseNumber} planning complete.
+- Tasks: ${taskCount}
+- Waves: ${waveCount}
+- IMPL_PLAN: ${sessionFolder}/phase-${phaseNumber}/IMPL_PLAN.md
+- Task JSONs: ${taskFiles.map(f => f).join(', ')}
+
+All tasks validated. Ready for execution.`
+})
+
+// Mark task complete
+TaskUpdate({ taskId: planTask.id, status: "completed" })
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| roadmap.md not found | Error to coordinator -- dispatch may have failed |
+| cli-explore-agent fails | Retry once. If still fails, use direct ACE search as fallback |
+| Gemini CLI fails | Skip deep analysis, proceed with basic context |
+| action-planning-agent fails | Retry once. If still fails, error to coordinator |
+| No task JSONs generated | Error to coordinator -- agent may have misunderstood input |
+| No requirements found for phase | Error to coordinator -- roadmap may be malformed |
+| Dependency cycle detected | Log warning, break cycle |
+| Referenced file not found | Log warning. If file is from prior wave, acceptable |