feat(skills): update 12 team skills to v3 design patterns

- Update all 12 team-* SKILL.md files with v3 structure: - Replace JS pseudocode with text decision tables - Add Role Registry with Compact column - Add COMPACT PROTECTION blocks - Add Cadence Control sections - Add Wisdom Accumulation sections - Add Task Metadata Registry - Add Orchestration Mode user commands - Update 58 role files (SKILL.md + roles/*): - Flat-file skills: team-brainstorm, team-issue, team-testing, team-uidesign, team-planex, team-iterdev - Folder-based skills: team-review, team-roadmap-dev, team-frontend, team-quality-assurance, team-tech-debt, team-ultra-analyze - Preserve special architectures: - team-planex: 2-member (planner + executor only) - team-tech-debt: Stop-Wait strategy (run_in_background:false) - team-iterdev: 7 behavior protocol tables in coordinator - All 12 teams reviewed for content completeness (PASS)
2026-02-28 09:23:08 +08:00 · 2026-02-26 21:14:45 +08:00
parent e228b8b273
commit 430d817e43
73 changed files with 13606 additions and 15439 deletions
--- a/.claude/skills/team-roadmap-dev/roles/planner/role.md
+++ b/.claude/skills/team-roadmap-dev/roles/planner/role.md
@@ -1,16 +1,14 @@
-# Role: planner
+# Planner Role

-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.
+Research and plan creation per phase. Gathers codebase context via cli-explore-agent and Gemini CLI, then generates wave-based execution plans with convergence criteria. Each plan is a self-contained unit of work that an executor can implement autonomously.

-## Role Identity
+## Identity

- **Name**: `planner`
+- **Name**: `planner` | **Tag**: `[planner]`
 - **Task Prefix**: `PLAN-*`
 - **Responsibility**: Orchestration (research + plan generation)
- **Communication**: SendMessage to coordinator only
- **Output Tag**: `[planner]`

-## Role Boundaries
+## Boundaries

 ### MUST

@@ -21,15 +19,42 @@ Research and plan creation per phase. Gathers codebase context via cli-explore-a
 - 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
+- Work strictly within Orchestration responsibility scope

 ### MUST NOT

+- Execute work outside this role's responsibility scope
 - 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
+- Communicate directly with other worker roles (must go through coordinator)
+- Omit `[planner]` identifier in any output
+
+---
+
+## 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 |
+
+### Tool Capabilities
+
+| Tool | Type | Used By | Purpose |
+|------|------|---------|---------|
+| `cli-explore-agent` | Subagent | planner | Codebase exploration, pattern analysis |
+| `action-planning-agent` | Subagent | planner | Task JSON + IMPL_PLAN.md generation |
+| `gemini` | CLI tool | planner | Deep analysis for complex phases (optional) |
+| `Read/Write` | File operations | planner | Context and plan file management |
+| `Glob/Grep` | Search | planner | File discovery and pattern matching |
+
+---

 ## Message Types

@@ -41,241 +66,171 @@ Research and plan creation per phase. Gathers codebase context via cli-explore-a

 ## Message Bus

-```javascript
+Before every SendMessage, log via `mcp__ccw-tools__team_msg`:
+
+```
 mcp__ccw-tools__team_msg({
-  operation: "log", team: "roadmap-dev",
-  from: "planner", to: "coordinator",
-  type: messageType,
-  summary: `[planner] ${messageSummary}`,
-  ref: artifactPath
+  operation: "log",
+  team: "roadmap-dev",
+  from: "planner",
+  to: "coordinator",
+  type: <message-type>,
+  summary: "[planner] <task-prefix> complete: <task-subject>",
+  ref: <artifact-path>
 })
 ```

-### CLI Fallback
+**CLI fallback** (when MCP unavailable):

-```javascript
-Bash(`ccw team log --team "roadmap-dev" --from "planner" --to "coordinator" --type "${type}" --summary "[planner] ${summary}" --json`)
+```
+Bash("ccw team log --team roadmap-dev --from planner --to coordinator --type <type> --summary \"[planner] <summary>\" --ref <artifact-path> --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
+## Execution (5-Phase)

 ### 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)
-)
+> See SKILL.md Shared Infrastructure -> Worker Phase 1: Task Discovery

-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
-}
+Standard task discovery flow: TaskList -> filter by prefix `PLAN-*` + owner match + pending + unblocked -> TaskGet -> TaskUpdate in_progress.

-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"
-```
+**Resume Artifact Check**: Check whether this task's output artifact already exists:
+- `<session>/phase-N/context.md` exists -> skip to Phase 3
+- Artifact incomplete or missing -> normal Phase 2-4 execution

 ### 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
-```
+**Objective**: Gather codebase context for plan generation.
+
+**Loading steps**:
+
+| Input | Source | Required |
+|-------|--------|----------|
+| roadmap.md | <session-folder>/roadmap.md | Yes |
+| Prior phase summaries | <session-folder>/phase-*/summary-*.md | No |
+| Wisdom | <session-folder>/wisdom/ | No |
+
+Delegate to `commands/research.md`:
+
+| Step | Action |
+|------|--------|
+| 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
+**Report progress via team_msg**:
+```
 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`
+  summary: "[planner] Research complete for phase <N>. Context written.",
+  ref: "<session>/phase-<N>/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
-```
+**Objective**: Generate wave-based execution plans.
+
+Delegate to `commands/create-plans.md`:
+
+| Step | Action |
+|------|--------|
+| 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`)
+**Objective**: Verify task JSONs before reporting.

-for (const taskFile of taskFiles) {
-  const taskJson = JSON.parse(Read(taskFile))
+**Validation checks**:

-  // 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
-        })
-      }
-    }
-  }
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Referenced files exist | `test -f <path>` for modify actions | All files found or warning logged |
+| Self-dependency | Check if depends_on includes own ID | No self-dependencies |
+| Convergence criteria | Check convergence.criteria exists | Each task has criteria |
+| Cross-dependency | Verify all depends_on IDs exist | All dependencies valid |

-  // 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
-    })
-  }
+**Validation steps**:

-  // 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
-    })
-  }
-}
+1. **File existence check** (for modify actions):
+   - For each task file with action="modify"
+   - Check file exists
+   - Log warning if not found

-// 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}`
-      })
-    }
-  }
-}
-```
+2. **Self-dependency check**:
+   - For each task, verify task.id not in task.depends_on
+   - Log error if self-dependency detected
+
+3. **Convergence criteria check**:
+   - Verify each task has convergence.criteria array
+   - Log warning if missing
+
+4. **Cross-dependency validation**:
+   - Collect all task IDs
+   - Verify each depends_on reference exists
+   - Log warning if unknown dependency

 ### Phase 5: Report to Coordinator

-```javascript
-const taskCount = allTasks.length
+> See SKILL.md Shared Infrastructure -> Worker Phase 5: Report

-// 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)
+Standard report flow: team_msg log -> SendMessage with `[planner]` prefix -> TaskUpdate completed -> Loop to Phase 1 for next task.

-// 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}/`
-})
+**Wave count computation**:

-// Send message to coordinator
+| Step | Action |
+|------|--------|
+| 1 | Start with wave=1, assigned=set() |
+| 2 | Find tasks with all dependencies in assigned |
+| 3 | Assign those tasks to current wave, add to assigned |
+| 4 | Increment wave, repeat until all tasks assigned |
+| 5 | Return wave count |
+
+**Report message**:
+```
 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(', ')}
+  message: "[planner] Phase <N> planning complete.
+- Tasks: <count>
+- Waves: <wave-count>
+- IMPL_PLAN: <session>/phase-<N>/IMPL_PLAN.md
+- Task JSONs: <file-list>

-All tasks validated. Ready for execution.`
+All tasks validated. Ready for execution."
 })
-
-// Mark task complete
-TaskUpdate({ taskId: planTask.id, status: "completed" })
 ```

+---
+
 ## Error Handling

 | Scenario | Resolution |
 |----------|------------|
+| No PLAN-* tasks available | Idle, wait for coordinator assignment |
+| Context/Plan file not found | Notify coordinator, request location |
+| Command file not found | Fall back to inline execution |
 | 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 |
@@ -284,3 +239,5 @@ TaskUpdate({ taskId: planTask.id, status: "completed" })
 | 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 |
+| Critical issue beyond scope | SendMessage fix_required to coordinator |
+| Unexpected error | Log error via team_msg, report to coordinator |