mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-28 09:23:08 +08:00
430d817e43
- 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)
383 lines
18 KiB
Markdown
383 lines
18 KiB
Markdown
---
|
|
name: team-lifecycle-v3
|
|
description: Unified team skill for full lifecycle - spec/impl/test. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team lifecycle".
|
|
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
|
|
---
|
|
|
|
# Team Lifecycle v3
|
|
|
|
Unified team skill: specification → implementation → testing → review. All team members invoke with `--role=xxx` to route to role-specific execution.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌───────────────────────────────────────────────────┐
|
|
│ Skill(skill="team-lifecycle-v3") │
|
|
│ args="任务描述" 或 args="--role=xxx" │
|
|
└───────────────────┬───────────────────────────────┘
|
|
│ Role Router
|
|
┌──── --role present? ────┐
|
|
│ NO │ YES
|
|
↓ ↓
|
|
Orchestration Mode Role Dispatch
|
|
(auto → coordinator) (route to role.md)
|
|
│
|
|
┌────┴────┬───────┬───────┬───────┬───────┬───────┬───────┐
|
|
↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
|
|
coordinator analyst writer discussant planner executor tester reviewer
|
|
↑ ↑
|
|
on-demand by coordinator
|
|
┌──────────┐ ┌─────────┐
|
|
│ explorer │ │architect│
|
|
└──────────┘ └─────────┘
|
|
┌──────────────┐ ┌──────┐
|
|
│ fe-developer │ │fe-qa │
|
|
└──────────────┘ └──────┘
|
|
```
|
|
|
|
## Role Router
|
|
|
|
### Input Parsing
|
|
|
|
Parse `$ARGUMENTS` to extract `--role`. If absent → Orchestration Mode (auto route to coordinator).
|
|
|
|
### Role Registry
|
|
|
|
| Role | File | Task Prefix | Type | Compact |
|
|
|------|------|-------------|------|---------|
|
|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | **⚠️ 压缩后必须重读** |
|
|
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | RESEARCH-* | pipeline | 压缩后必须重读 |
|
|
| writer | [roles/writer/role.md](roles/writer/role.md) | DRAFT-* | pipeline | 压缩后必须重读 |
|
|
| discussant | [roles/discussant/role.md](roles/discussant/role.md) | DISCUSS-* | pipeline | 压缩后必须重读 |
|
|
| planner | [roles/planner/role.md](roles/planner/role.md) | PLAN-* | pipeline | 压缩后必须重读 |
|
|
| executor | [roles/executor/role.md](roles/executor/role.md) | IMPL-* | pipeline | 压缩后必须重读 |
|
|
| tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | pipeline | 压缩后必须重读 |
|
|
| reviewer | [roles/reviewer/role.md](roles/reviewer/role.md) | REVIEW-* + QUALITY-* | pipeline | 压缩后必须重读 |
|
|
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | service (on-demand) | 压缩后必须重读 |
|
|
| architect | [roles/architect/role.md](roles/architect/role.md) | ARCH-* | consulting (on-demand) | 压缩后必须重读 |
|
|
| fe-developer | [roles/fe-developer/role.md](roles/fe-developer/role.md) | DEV-FE-* | frontend pipeline | 压缩后必须重读 |
|
|
| fe-qa | [roles/fe-qa/role.md](roles/fe-qa/role.md) | QA-FE-* | frontend pipeline | 压缩后必须重读 |
|
|
|
|
> **⚠️ COMPACT PROTECTION**: 角色文件是执行文档，不是参考资料。当 context compression 发生后，角色指令仅剩摘要时，**必须立即 `Read` 对应 role.md 重新加载后再继续执行**。不得基于摘要执行任何 Phase。
|
|
|
|
### Dispatch
|
|
|
|
1. Extract `--role` from arguments
|
|
2. If no `--role` → route to coordinator (Orchestration Mode)
|
|
3. Look up role in registry → Read the role file → Execute its phases
|
|
|
|
### Orchestration Mode
|
|
|
|
When invoked without `--role`, coordinator auto-starts. User just provides task description.
|
|
|
|
**Invocation**: `Skill(skill="team-lifecycle-v3", args="任务描述")`
|
|
|
|
**Lifecycle**:
|
|
```
|
|
用户提供任务描述
|
|
→ coordinator Phase 1-3: 需求澄清 → TeamCreate → 创建任务链
|
|
→ coordinator Phase 4: spawn 首批 worker (后台) → STOP
|
|
→ Worker 执行 → SendMessage 回调 → coordinator 推进下一步
|
|
→ 循环直到 pipeline 完成 → Phase 5 汇报
|
|
```
|
|
|
|
**User Commands** (唤醒已暂停的 coordinator):
|
|
|
|
| Command | Action |
|
|
|---------|--------|
|
|
| `check` / `status` | 输出执行状态图，不推进 |
|
|
| `resume` / `continue` | 检查 worker 状态，推进下一步 |
|
|
|
|
---
|
|
|
|
## Shared Infrastructure
|
|
|
|
以下模板适用于所有 worker 角色。每个 role.md 只需写 **Phase 2-4** 的角色特有逻辑。
|
|
|
|
### Worker Phase 1: Task Discovery (所有 worker 共享)
|
|
|
|
每个 worker 启动后执行相同的任务发现流程：
|
|
|
|
1. 调用 `TaskList()` 获取所有任务
|
|
2. 筛选: subject 匹配本角色前缀 + owner 是本角色 + status 为 pending + blockedBy 为空
|
|
3. 无任务 → idle 等待
|
|
4. 有任务 → `TaskGet` 获取详情 → `TaskUpdate` 标记 in_progress
|
|
|
|
**Resume Artifact Check** (防止恢复后重复产出):
|
|
- 检查本任务的输出产物是否已存在
|
|
- 产物完整 → 跳到 Phase 5 报告完成
|
|
- 产物不完整或不存在 → 正常执行 Phase 2-4
|
|
|
|
### Worker Phase 5: Report (所有 worker 共享)
|
|
|
|
任务完成后的标准报告流程:
|
|
|
|
1. **Message Bus**: 调用 `mcp__ccw-tools__team_msg` 记录消息
|
|
- 参数: operation="log", team=<team-name>, from=<role>, to="coordinator", type=<消息类型>, summary="[<role>] <摘要>", ref=<产物路径>
|
|
- **CLI fallback**: 当 MCP 不可用时 → `ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json`
|
|
2. **SendMessage**: 发送结果给 coordinator (content 和 summary 都带 `[<role>]` 前缀)
|
|
3. **TaskUpdate**: 标记任务 completed
|
|
4. **Loop**: 回到 Phase 1 检查下一个任务
|
|
|
|
### Wisdom Accumulation (所有角色)
|
|
|
|
跨任务知识积累。Coordinator 在 session 初始化时创建 `wisdom/` 目录。
|
|
|
|
**目录**:
|
|
```
|
|
<session-folder>/wisdom/
|
|
├── learnings.md # 模式和洞察
|
|
├── decisions.md # 架构和设计决策
|
|
├── conventions.md # 代码库约定
|
|
└── issues.md # 已知风险和问题
|
|
```
|
|
|
|
**Worker 加载** (Phase 2): 从 task description 提取 `Session: <path>`, 读取 wisdom 目录下各文件。
|
|
**Worker 贡献** (Phase 4/5): 将本任务发现写入对应 wisdom 文件。
|
|
|
|
### Role Isolation Rules
|
|
|
|
| 允许 | 禁止 |
|
|
|------|------|
|
|
| 处理自己前缀的任务 | 处理其他角色前缀的任务 |
|
|
| SendMessage 给 coordinator | 直接与其他 worker 通信 |
|
|
| 使用 Toolbox 中声明的工具 | 为其他角色创建任务 |
|
|
| 委派给 commands/ 中的命令 | 修改不属于本职责的资源 |
|
|
|
|
Coordinator 额外禁止: 直接编写/修改代码、调用实现类 subagent、直接执行分析/测试/审查。
|
|
|
|
---
|
|
|
|
## Pipeline Definitions
|
|
|
|
### Spec-only (12 tasks)
|
|
|
|
```
|
|
RESEARCH-001 → DISCUSS-001 → DRAFT-001 → DISCUSS-002
|
|
→ DRAFT-002 → DISCUSS-003 → DRAFT-003 → DISCUSS-004
|
|
→ DRAFT-004 → DISCUSS-005 → QUALITY-001 → DISCUSS-006
|
|
```
|
|
|
|
### Impl-only / Backend (4 tasks)
|
|
|
|
```
|
|
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
|
|
```
|
|
|
|
### Full-lifecycle (16 tasks)
|
|
|
|
```
|
|
[Spec pipeline] → PLAN-001(blockedBy: DISCUSS-006) → IMPL-001 → TEST-001 + REVIEW-001
|
|
```
|
|
|
|
### Frontend Pipelines
|
|
|
|
```
|
|
FE-only: PLAN-001 → DEV-FE-001 → QA-FE-001
|
|
(GC loop: QA-FE verdict=NEEDS_FIX → DEV-FE-002 → QA-FE-002, max 2 rounds)
|
|
|
|
Fullstack: PLAN-001 → IMPL-001 ∥ DEV-FE-001 → TEST-001 ∥ QA-FE-001 → REVIEW-001
|
|
|
|
Full + FE: [Spec pipeline] → PLAN-001 → IMPL-001 ∥ DEV-FE-001 → TEST-001 ∥ QA-FE-001 → REVIEW-001
|
|
```
|
|
|
|
### Cadence Control
|
|
|
|
**节拍模型**: 事件驱动，每个 beat = coordinator 唤醒 → 处理 → spawn → STOP。
|
|
|
|
```
|
|
Beat Cycle (单次节拍)
|
|
═══════════════════════════════════════════════════════════
|
|
Event Coordinator Workers
|
|
───────────────────────────────────────────────────────────
|
|
callback/resume ──→ ┌─ handleCallback ─┐
|
|
│ mark completed │
|
|
│ check pipeline │
|
|
├─ handleSpawnNext ─┤
|
|
│ find ready tasks │
|
|
│ spawn workers ───┼──→ [Worker A] Phase 1-5
|
|
│ (parallel OK) ──┼──→ [Worker B] Phase 1-5
|
|
└─ STOP (idle) ─────┘ │
|
|
│
|
|
callback ←─────────────────────────────────────────┘
|
|
(next beat) SendMessage + TaskUpdate(completed)
|
|
═══════════════════════════════════════════════════════════
|
|
```
|
|
|
|
**Pipeline 节拍视图**:
|
|
|
|
```
|
|
Spec-only (12 beats, 严格串行)
|
|
──────────────────────────────────────────────────────────
|
|
Beat 1 2 3 4 5 6 7 8 9 10 11 12
|
|
│ │ │ │ │ │ │ │ │ │ │ │
|
|
R1 → D1 → W1 → D2 → W2 → D3 → W3 → D4 → W4 → D5 → Q1 → D6
|
|
▲ ▲
|
|
pipeline sign-off
|
|
start pause
|
|
|
|
R=RESEARCH D=DISCUSS W=DRAFT(writer) Q=QUALITY
|
|
|
|
Impl-only (3 beats, 含并行窗口)
|
|
──────────────────────────────────────────────────────────
|
|
Beat 1 2 3
|
|
│ │ ┌────┴────┐
|
|
PLAN → IMPL ──→ TEST ∥ REVIEW ← 并行窗口
|
|
└────┬────┘
|
|
pipeline
|
|
done
|
|
|
|
Full-lifecycle (15 beats, spec→impl 过渡含检查点)
|
|
──────────────────────────────────────────────────────────
|
|
Beat 1-12: [Spec pipeline 同上]
|
|
│
|
|
Beat 12 (D6 完成): ⏸ CHECKPOINT ── 用户确认后 resume
|
|
│
|
|
Beat 13 14 15
|
|
PLAN → IMPL → TEST ∥ REVIEW
|
|
|
|
Fullstack (含双并行窗口)
|
|
──────────────────────────────────────────────────────────
|
|
Beat 1 2 3 4
|
|
│ ┌────┴────┐ ┌────┴────┐ │
|
|
PLAN → IMPL ∥ DEV-FE → TEST ∥ QA-FE → REVIEW
|
|
▲ ▲ ▲
|
|
并行窗口 1 并行窗口 2 同步屏障
|
|
```
|
|
|
|
**检查点 (Checkpoint)**:
|
|
|
|
| 触发条件 | 位置 | 行为 |
|
|
|----------|------|------|
|
|
| Spec→Impl 过渡 | DISCUSS-006 完成后 | ⏸ 暂停，等待用户 `resume` 确认 |
|
|
| GC 循环上限 | QA-FE max 2 rounds | 超出轮次 → 停止迭代，报告当前状态 |
|
|
| Pipeline 停滞 | 无 ready + 无 running | 检查缺失任务，报告用户 |
|
|
|
|
**Stall 检测** (coordinator `handleCheck` 时执行):
|
|
|
|
| 检查项 | 条件 | 处理 |
|
|
|--------|------|------|
|
|
| Worker 无响应 | in_progress 任务无回调 | 报告等待中的任务列表，建议用户 `resume` |
|
|
| Pipeline 死锁 | 无 ready + 无 running + 有 pending | 检查 blockedBy 依赖链，报告卡点 |
|
|
| GC 循环超限 | DEV-FE / QA-FE 迭代 > max_rounds | 终止循环，输出最新 QA 报告 |
|
|
|
|
### Task Metadata Registry
|
|
|
|
| Task ID | Role | Phase | Dependencies | Description |
|
|
|---------|------|-------|-------------|-------------|
|
|
| RESEARCH-001 | analyst | spec | (none) | Seed analysis and context gathering |
|
|
| DISCUSS-001 | discussant | spec | RESEARCH-001 | Critique research findings |
|
|
| DRAFT-001 | writer | spec | DISCUSS-001 | Generate Product Brief |
|
|
| DISCUSS-002 | discussant | spec | DRAFT-001 | Critique Product Brief |
|
|
| DRAFT-002 | writer | spec | DISCUSS-002 | Generate Requirements/PRD |
|
|
| DISCUSS-003 | discussant | spec | DRAFT-002 | Critique Requirements/PRD |
|
|
| DRAFT-003 | writer | spec | DISCUSS-003 | Generate Architecture Document |
|
|
| DISCUSS-004 | discussant | spec | DRAFT-003 | Critique Architecture Document |
|
|
| DRAFT-004 | writer | spec | DISCUSS-004 | Generate Epics & Stories |
|
|
| DISCUSS-005 | discussant | spec | DRAFT-004 | Critique Epics |
|
|
| QUALITY-001 | reviewer | spec | DISCUSS-005 | 5-dimension spec quality validation |
|
|
| DISCUSS-006 | discussant | spec | QUALITY-001 | Final review discussion and sign-off |
|
|
| PLAN-001 | planner | impl | (none or DISCUSS-006) | Multi-angle exploration and planning |
|
|
| IMPL-001 | executor | impl | PLAN-001 | Code implementation |
|
|
| TEST-001 | tester | impl | IMPL-001 | Test-fix cycles |
|
|
| REVIEW-001 | reviewer | impl | IMPL-001 | 4-dimension code review |
|
|
| DEV-FE-001 | fe-developer | impl | PLAN-001 | Frontend implementation |
|
|
| QA-FE-001 | fe-qa | impl | DEV-FE-001 | 5-dimension frontend QA |
|
|
|
|
## Coordinator Spawn Template
|
|
|
|
When coordinator spawns workers, use background mode (Spawn-and-Stop):
|
|
|
|
```
|
|
Task({
|
|
subagent_type: "general-purpose",
|
|
description: "Spawn <role> worker",
|
|
team_name: <team-name>,
|
|
name: "<role>",
|
|
run_in_background: true,
|
|
prompt: `你是 team "<team-name>" 的 <ROLE>.
|
|
|
|
## 首要指令
|
|
你的所有工作必须通过调用 Skill 获取角色定义后执行：
|
|
Skill(skill="team-lifecycle-v3", args="--role=<role>")
|
|
|
|
当前需求: <task-description>
|
|
Session: <session-folder>
|
|
|
|
## 角色准则
|
|
- 只处理 <PREFIX>-* 任务，不执行其他角色工作
|
|
- 所有输出带 [<role>] 标识前缀
|
|
- 仅与 coordinator 通信
|
|
- 不使用 TaskCreate 为其他角色创建任务
|
|
- 每次 SendMessage 前先调用 mcp__ccw-tools__team_msg 记录
|
|
|
|
## 工作流程
|
|
1. 调用 Skill → 获取角色定义和执行逻辑
|
|
2. 按 role.md 5-Phase 流程执行
|
|
3. team_msg + SendMessage 结果给 coordinator
|
|
4. TaskUpdate completed → 检查下一个任务`
|
|
})
|
|
```
|
|
|
|
## Session Directory
|
|
|
|
```
|
|
.workflow/.team/TLS-<slug>-<date>/
|
|
├── team-session.json # Session state
|
|
├── spec/ # Spec artifacts
|
|
│ ├── spec-config.json
|
|
│ ├── discovery-context.json
|
|
│ ├── product-brief.md
|
|
│ ├── requirements/
|
|
│ ├── architecture/
|
|
│ ├── epics/
|
|
│ ├── readiness-report.md
|
|
│ └── spec-summary.md
|
|
├── discussions/ # Discussion records
|
|
├── plan/ # Plan artifacts
|
|
│ ├── plan.json
|
|
│ └── .task/TASK-*.json
|
|
├── explorations/ # Explorer output (cached)
|
|
├── architecture/ # Architect assessments
|
|
├── qa/ # QA audit reports
|
|
├── wisdom/ # Cross-task knowledge
|
|
│ ├── learnings.md
|
|
│ ├── decisions.md
|
|
│ ├── conventions.md
|
|
│ └── issues.md
|
|
├── .msg/ # Team message bus logs (messages.jsonl)
|
|
└── shared-memory.json # Cross-role state
|
|
```
|
|
|
|
## Session Resume
|
|
|
|
Coordinator supports `--resume` / `--continue` for interrupted sessions:
|
|
|
|
1. Scan `.workflow/.team/TLS-*/team-session.json` for active/paused sessions
|
|
2. Multiple matches → AskUserQuestion for selection
|
|
3. Audit TaskList → reconcile session state ↔ task status
|
|
4. Reset in_progress → pending (interrupted tasks)
|
|
5. Rebuild team and spawn needed workers only
|
|
6. Create missing tasks with correct blockedBy
|
|
7. Kick first executable task → Phase 4 coordination loop
|
|
|
|
## Shared Spec Resources
|
|
|
|
| Resource | Path | Usage |
|
|
|----------|------|-------|
|
|
| Document Standards | [specs/document-standards.md](specs/document-standards.md) | YAML frontmatter, naming, structure |
|
|
| Quality Gates | [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gates |
|
|
| Product Brief Template | [templates/product-brief.md](templates/product-brief.md) | DRAFT-001 |
|
|
| Requirements Template | [templates/requirements-prd.md](templates/requirements-prd.md) | DRAFT-002 |
|
|
| Architecture Template | [templates/architecture-doc.md](templates/architecture-doc.md) | DRAFT-003 |
|
|
| Epics Template | [templates/epics-template.md](templates/epics-template.md) | DRAFT-004 |
|
|
|
|
## Error Handling
|
|
|
|
| Scenario | Resolution |
|
|
|----------|------------|
|
|
| Unknown --role value | Error with available role list |
|
|
| Missing --role arg | Orchestration Mode → coordinator |
|
|
| Role file not found | Error with expected path |
|
|
| Command file not found | Fallback to inline execution |
|