Claude-Code-Workflow/.claude/skills/team-lifecycle-v3/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
team-lifecycle-v3	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".	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	(none)	orchestrator	⚠️ 压缩后必须重读
analyst	roles/analyst/role.md	RESEARCH-*	pipeline	压缩后必须重读
writer	roles/writer/role.md	DRAFT-*	pipeline	压缩后必须重读
discussant	roles/discussant/role.md	DISCUSS-*	pipeline	压缩后必须重读
planner	roles/planner/role.md	PLAN-*	pipeline	压缩后必须重读
executor	roles/executor/role.md	IMPL-*	pipeline	压缩后必须重读
tester	roles/tester/role.md	TEST-*	pipeline	压缩后必须重读
reviewer	roles/reviewer/role.md	REVIEW-* + QUALITY-*	pipeline	压缩后必须重读
explorer	roles/explorer/role.md	EXPLORE-*	service (on-demand)	压缩后必须重读
architect	roles/architect/role.md	ARCH-*	consulting (on-demand)	压缩后必须重读
fe-developer	roles/fe-developer/role.md	DEV-FE-*	frontend pipeline	压缩后必须重读
fe-qa	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=, from=, to="coordinator", type=<消息类型>, summary="[] <摘要>", 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	YAML frontmatter, naming, structure
Quality Gates	specs/quality-gates.md	Per-phase quality gates
Product Brief Template	templates/product-brief.md	DRAFT-001
Requirements Template	templates/requirements-prd.md	DRAFT-002
Architecture Template	templates/architecture-doc.md	DRAFT-003
Epics Template	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