mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-28 09:23:08 +08:00
6c16c121d2
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.
289 lines
11 KiB
Markdown
289 lines
11 KiB
Markdown
---
|
||
name: team-roadmap-dev
|
||
description: 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".
|
||
allowed-tools: 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
|
||
|
||
```javascript
|
||
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
|
||
|
||
```javascript
|
||
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
|
||
|
||
```javascript
|
||
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](roles/coordinator/role.md) |
|
||
| `planner` | PLAN-* | Research, context gathering, task JSON generation via action-planning-agent | [roles/planner/role.md](roles/planner/role.md) |
|
||
| `executor` | EXEC-* | Code implementation following plans, wave-based parallel execution | [roles/executor/role.md](roles/executor/role.md) |
|
||
| `verifier` | VERIFY-* | Convergence criteria verification, gap detection, fix loop trigger | [roles/verifier/role.md](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
|
||
|
||
```javascript
|
||
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
|
||
|
||
```javascript
|
||
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 |
|