Claude-Code-Workflow/.claude/skills/team-roadmap-dev/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
team-roadmap-dev	Unified team skill for roadmap-driven development workflow. Coordinator discusses roadmap with user, then dispatches phased execution pipeline (plan → execute → verify). All roles invoke this skill with --role arg. Triggers on "team roadmap-dev".	TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)

Team Roadmap Dev

Phased project execution team. Coordinator discusses roadmap with the user and manages phase transitions. Workers handle planning, execution, and verification per phase. Follows filesystem-based state machine pattern with fixed and dynamic artifacts.

Architecture Overview

┌───────────────────────────────────────────────┐
│  Skill(skill="team-roadmap-dev")                       │
│  args="任务描述" 或 args="--role=xxx"          │
└───────────────────┬───────────────────────────┘
                    │ Role Router
                    │
         ┌──── --role present? ────┐
         │ NO                      │ YES
         ↓                         ↓
  Orchestration Mode         Role Dispatch
  (auto → coordinator)      (route to role.md)
         │
    ┌────┴────┬───────────┬───────────┐
    ↓         ↓           ↓           ↓
┌──────────┐┌─────────┐┌──────────┐┌──────────┐
│coordinator││ planner ││ executor ││ verifier │
│ (human   ││ PLAN-*  ││ EXEC-*   ││ VERIFY-* │
│  交互)   ││         ││          ││          │
└──────────┘└─────────┘└──────────┘└──────────┘

Command Architecture

roles/
├── coordinator/
│   ├── role.md                # Orchestrator: roadmap discussion + phase management
│   └── commands/
│       ├── roadmap-discuss.md # Discuss roadmap with user, generate phase plan
│       ├── dispatch.md        # Create task chain per phase
│       ├── monitor.md         # Stop-Wait phase execution loop
│       ├── pause.md           # Save state and exit cleanly
│       └── resume.md          # Resume from paused session
├── planner/
│   ├── role.md                # Research + task JSON generation per phase
│   └── commands/
│       ├── research.md        # Context gathering + codebase exploration
│       └── create-plans.md    # action-planning-agent delegation → IMPL-*.json
├── executor/
│   ├── role.md                # Task execution with wave parallelism
│   └── commands/
│       └── implement.md       # Code implementation via code-developer
└── verifier/
    ├── role.md                # Goal-backward verification
    └── commands/
        └── verify.md          # Convergence criteria checking + gap detection

Role Router

Input Parsing

const args = "$ARGUMENTS"
const roleMatch = args.match(/--role[=\s]+(\w+)/)
const resumeMatch = args.match(/--resume[=\s]+(.+?)(?:\s|$)/)
const teamName = "roadmap-dev"

if (!roleMatch) {
  // No --role: Orchestration Mode → auto route to coordinator
  // If --resume present: coordinator handles resume via commands/resume.md
}

const role = roleMatch ? roleMatch[1] : "coordinator"
const agentName = args.match(/--agent-name[=\s]+([\w-]+)/)?.[1] || role

Role Dispatch

const VALID_ROLES = {
  "coordinator": { file: "roles/coordinator/role.md", prefix: null },
  "planner":     { file: "roles/planner/role.md",     prefix: "PLAN" },
  "executor":    { file: "roles/executor/role.md",     prefix: "EXEC" },
  "verifier":    { file: "roles/verifier/role.md",     prefix: "VERIFY" }
}

if (!VALID_ROLES[role]) {
  throw new Error(`Unknown role: ${role}. Available: ${Object.keys(VALID_ROLES).join(', ')}`)
}

Read(VALID_ROLES[role].file)

Orchestration Mode

if (!roleMatch) {
  const role = "coordinator"
  Read(VALID_ROLES[role].file)
}

Available Roles

Role	Task Prefix	Responsibility	Role File
coordinator	N/A	Human interaction, roadmap discussion, phase transitions, state management	roles/coordinator/role.md
planner	PLAN-*	Research, context gathering, task JSON generation via action-planning-agent	roles/planner/role.md
executor	EXEC-*	Code implementation following plans, wave-based parallel execution	roles/executor/role.md
verifier	VERIFY-*	Convergence criteria verification, gap detection, fix loop trigger	roles/verifier/role.md

Shared Infrastructure

Artifact System

Fixed Artifacts (session-level, persist throughout session):

Artifact	Path	Created By	Purpose
roadmap.md	{session}/roadmap.md	coordinator (roadmap-discuss)	Phase plan with requirements and success criteria
state.md	{session}/state.md	coordinator	Living memory (<100 lines), updated every significant action
config.json	{session}/config.json	coordinator	Session settings: mode, depth, gates

Dynamic Artifacts (per-phase, form execution history):

Artifact	Path	Created By	Purpose
context.md	{session}/phase-N/context.md	planner (research)	Phase context and requirements
IMPL_PLAN.md	{session}/phase-N/IMPL_PLAN.md	planner (create-plans)	Implementation overview with task dependency graph
IMPL-*.json	{session}/phase-N/.task/IMPL-*.json	planner (create-plans)	Task JSON files (unified flat schema with convergence criteria)
TODO_LIST.md	{session}/phase-N/TODO_LIST.md	planner (create-plans)	Checklist tracking for all tasks
summary-{ID}.md	{session}/phase-N/summary-{IMPL-ID}.md	executor (implement)	Execution record with requires/provides/convergence-met
verification.md	{session}/phase-N/verification.md	verifier (verify)	Convergence criteria check results + gap list

Init Prerequisite

Coordinator must ensure .workflow/project-tech.json exists before starting. If not found, invoke /workflow:init.

Team Configuration

const TEAM_CONFIG = {
  name: "roadmap-dev",
  sessionDir: ".workflow/.team/RD-{slug}-{date}/",
  msgDir: ".workflow/.team-msg/roadmap-dev/"
}

Role Isolation Rules

Output Tagging

All outputs must carry [role_name] prefix.

Coordinator Isolation

Allowed	Forbidden
Discuss roadmap with user (AskUserQuestion)	Direct code writing/modification
Create task chain (TaskCreate)	Calling implementation subagents
Dispatch tasks to workers	Direct analysis/testing/verification
Monitor progress (message bus)	Bypassing workers
Report results to user	Modifying source code

Worker Isolation

Allowed	Forbidden
Process own-prefix tasks only	Process other roles' tasks
SendMessage to coordinator only	Direct worker-to-worker communication
Use Toolbox-declared tools	TaskCreate for other roles
Delegate to commands/*.md	Modify resources outside scope

Message Bus & Task Lifecycle

Each role's role.md contains self-contained Message Bus and Task Lifecycle. See roles/{role}/role.md.

Pipeline

Phase N lifecycle:
  Coordinator (roadmap-discuss → dispatch phase N)
    → PLAN-N01: Planner (research → action-planning-agent → IMPL-*.json)
    → EXEC-N01: Executor (load IMPL-*.json → wave-based code-developer)
    → VERIFY-N01: Verifier (convergence criteria check)
    → Coordinator (transition: gap closure or next phase)

Cross-phase flow:
  Init → Roadmap Discussion → Phase 1 → Phase 2 → ... → Phase N → Complete
                                   ↑                          |
                                   └── gap closure loop ──────┘

Session lifecycle:
  Running → Pause (save coordinates) → Resume (re-enter monitor at coordinates)

Coordinator Spawn Template

TeamCreate({ team_name: "roadmap-dev" })

// Planner
Task({
  subagent_type: "general-purpose",
  team_name: "roadmap-dev",
  name: "planner",
  prompt: `你是 team "roadmap-dev" 的 PLANNER。

## 首要指令（MUST）
Skill(skill="team-roadmap-dev", args="--role=planner")

当前需求: ${taskDescription}
Session: ${sessionFolder}

## 角色准则
- 只处理 PLAN-* 前缀任务
- 所有输出带 [planner] 标识
- 仅与 coordinator 通信

## 工作流程
1. Skill(skill="team-roadmap-dev", args="--role=planner")
2. TaskList → PLAN-* 任务 → 执行 → 汇报
3. TaskUpdate completed → 检查下一个任务`
})

// Executor
Task({
  subagent_type: "general-purpose",
  team_name: "roadmap-dev",
  name: "executor",
  prompt: `你是 team "roadmap-dev" 的 EXECUTOR。

## 首要指令（MUST）
Skill(skill="team-roadmap-dev", args="--role=executor")

当前需求: ${taskDescription}
Session: ${sessionFolder}

## 角色准则
- 只处理 EXEC-* 前缀任务
- 所有输出带 [executor] 标识
- 仅与 coordinator 通信

## 工作流程
1. Skill(skill="team-roadmap-dev", args="--role=executor")
2. TaskList → EXEC-* 任务 → 执行 → 汇报
3. TaskUpdate completed → 检查下一个任务`
})

// Verifier
Task({
  subagent_type: "general-purpose",
  team_name: "roadmap-dev",
  name: "verifier",
  prompt: `你是 team "roadmap-dev" 的 VERIFIER。

## 首要指令（MUST）
Skill(skill="team-roadmap-dev", args="--role=verifier")

当前需求: ${taskDescription}
Session: ${sessionFolder}

## 角色准则
- 只处理 VERIFY-* 前缀任务
- 所有输出带 [verifier] 标识
- 仅与 coordinator 通信

## 工作流程
1. Skill(skill="team-roadmap-dev", args="--role=verifier")
2. TaskList → VERIFY-* 任务 → 执行 → 汇报
3. TaskUpdate completed → 检查下一个任务`
})

Error Handling

Scenario	Resolution
Unknown --role value	Error with available role list
Missing --role arg	Orchestration Mode → auto route to coordinator
Role file not found	Error with expected path
project-tech.json missing	Coordinator invokes /workflow:init
Phase verification fails with gaps	Coordinator triggers gap closure loop
Max gap closure iterations (3)	Report to user, ask for guidance