Claude-Code-Workflow/.claude/skills_lib/team-skill-designer-v2/specs/team-design-patterns.md

# Team Command Design Patterns

> Extracted from 5 production team commands: coordinate, plan, execute, test, review
> Extended with 10 collaboration patterns for diverse team interaction models

---

## Pattern Architecture

```
Team Design Patterns
├── Section A: Infrastructure Patterns (9)    ← HOW to build a team command
│   ├── Pattern 1: Message Bus Integration
│   ├── Pattern 2: YAML Front Matter
│   ├── Pattern 3: Task Lifecycle
│   ├── Pattern 4: Five-Phase Execution
│   ├── Pattern 5: Complexity-Adaptive Routing
│   ├── Pattern 6: Coordinator Spawn Integration
│   ├── Pattern 7: Error Handling Table
│   └── Pattern 8: Session File Structure
│
└── Section B: Collaboration Patterns (10)    ← HOW agents interact
    ├── CP-1: Linear Pipeline (线性流水线)
    ├── CP-2: Review-Fix Cycle (审查修复循环)
    ├── CP-3: Parallel Fan-out/Fan-in (并行扇出扇入)
    ├── CP-4: Consensus Gate (共识门控)
    ├── CP-5: Escalation Chain (逐级升级)
    ├── CP-6: Incremental Delivery (增量交付)
    ├── CP-7: Swarming (群策攻关)
    ├── CP-8: Consulting/Advisory (咨询顾问)
    ├── CP-9: Dual-Track (双轨并行)
    └── CP-10: Post-Mortem (复盘回顾)
```

**Section B** collaboration patterns are documented in: [collaboration-patterns.md](collaboration-patterns.md)

---

## When to Use

| Phase | Usage | Section |
|-------|-------|---------|
| Phase 0 | Understand all patterns before design | All sections |
| Phase 2 | Select applicable infrastructure + collaboration patterns | Pattern catalog |
| Phase 3 | Apply patterns during generation | Implementation details |
| Phase 4 | Verify compliance | Checklists |

---

# Section A: Infrastructure Patterns

## Pattern 1: Message Bus Integration

Every teammate must use `mcp__ccw-tools__team_msg` for persistent logging before every `SendMessage`.

### Structure

```javascript
// BEFORE every SendMessage, call:
mcp__ccw-tools__team_msg({
  operation: "log",
  team: teamName,
  from: "<role-name>",       // planner | executor | tester | <new-role>
  to: "coordinator",
  type: "<message-type>",
  summary: "<human-readable summary>",
  ref: "<optional file path>",
  data: { /* optional structured payload */ }
})
```

### Standard Message Types

| Type | Direction | Trigger | Payload |
|------|-----------|---------|---------|
| `plan_ready` | planner -> coordinator | Plan generation complete | `{ taskCount, complexity }` |
| `plan_approved` | coordinator -> planner | Plan reviewed | `{ approved: true }` |
| `plan_revision` | planner -> coordinator | Plan modified per feedback | `{ changes }` |
| `task_unblocked` | coordinator -> any | Dependency resolved | `{ taskId }` |
| `impl_complete` | executor -> coordinator | Implementation done | `{ changedFiles, syntaxClean }` |
| `impl_progress` | any -> coordinator | Progress update | `{ batch, total }` |
| `test_result` | tester -> coordinator | Test cycle end | `{ passRate, iterations }` |
| `review_result` | tester -> coordinator | Review done | `{ verdict, findings }` |
| `fix_required` | any -> coordinator | Critical issues | `{ details[] }` |
| `error` | any -> coordinator | Blocking error | `{ message }` |
| `shutdown` | coordinator -> all | Team dissolved | `{}` |

### Collaboration Pattern Message Types

| Type | Used By | Direction | Trigger |
|------|---------|-----------|---------|
| `vote` | CP-4 Consensus | any -> coordinator | Agent casts vote on proposal |
| `escalate` | CP-5 Escalation | any -> coordinator | Agent escalates unresolved issue |
| `increment_ready` | CP-6 Incremental | executor -> coordinator | Increment delivered for validation |
| `swarm_join` | CP-7 Swarming | any -> coordinator | Agent joins swarm on blocker |
| `consult_request` | CP-8 Consulting | any -> specialist | Agent requests expert advice |
| `consult_response` | CP-8 Consulting | specialist -> requester | Expert provides advice |
| `sync_checkpoint` | CP-9 Dual-Track | any -> coordinator | Track reaches sync point |
| `retro_finding` | CP-10 Post-Mortem | any -> coordinator | Retrospective insight |

### Adding New Message Types

When designing a new role, define role-specific message types following the convention:
- `{action}_ready` - Work product ready for review
- `{action}_complete` - Work phase finished
- `{action}_progress` - Intermediate progress update

### CLI Fallback

When `mcp__ccw-tools__team_msg` MCP is unavailable, use `ccw team` CLI as equivalent fallback:

```javascript
// Fallback: Replace MCP call with Bash CLI (parameters map 1:1)
Bash(`ccw team log --team "${teamName}" --from "<role>" --to "coordinator" --type "<type>" --summary "<summary>" [--ref <path>] [--data '<json>'] --json`)
```

**Parameter mapping**: `team_msg(params)` → `ccw team <operation> --team <team> [--from/--to/--type/--summary/--ref/--data/--id/--last] [--json]`

**Coordinator** uses all 4 operations: `log`, `list`, `status`, `read`
**Teammates** primarily use: `log`

### Message Bus Section Template

```markdown
## 消息总线

每次 SendMessage **前**，必须调用 `mcp__ccw-tools__team_msg` 记录消息：

\`\`\`javascript
mcp__ccw-tools__team_msg({ operation: "log", team: teamName, from: "<role>", to: "coordinator", type: "<type>", summary: "<summary>" })
\`\`\`

### 支持的 Message Types

| Type | 方向 | 触发时机 | 说明 |
|------|------|----------|------|
| `<type>` | <role> → coordinator | <when> | <what> |

### CLI 回退

当 `mcp__ccw-tools__team_msg` MCP 不可用时，使用 `ccw team` CLI 作为等效回退：

\`\`\`javascript
// 回退: 将 MCP 调用替换为 Bash CLI（参数一一对应）
Bash(\`ccw team log --team "${teamName}" --from "<role>" --to "coordinator" --type "<type>" --summary "<summary>" --json\`)
\`\`\`

**参数映射**: `team_msg(params)` → `ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "<text>" [--ref <path>] [--data '<json>'] [--json]`
```

---

## Pattern 2: YAML Front Matter

Every team command file must start with standardized YAML front matter.

### Structure

```yaml
---
name: <command-name>
description: Team <role> - <capabilities in Chinese>
argument-hint: ""
allowed-tools: SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), Task(*)
group: team
---
```

### Field Rules

| Field | Rule | Example |
|-------|------|---------|
| `name` | Lowercase, matches filename | `plan`, `execute`, `test` |
| `description` | `Team <role> -` prefix + Chinese capability list | `Team planner - 多角度代码探索、结构化实现规划` |
| `argument-hint` | Empty string for teammates, has hint for coordinator | `""` |
| `allowed-tools` | Start with `SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*)` | See each role |
| `group` | Always `team` | `team` |

### Minimum Tool Set (All Teammates)

```
SendMessage(*), TaskUpdate(*), TaskList(*), TaskGet(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Grep(*)
```

### Role-Specific Additional Tools

| Role Type | Additional Tools |
|-----------|-----------------|
| Read-only (reviewer, analyzer) | None extra |
| Write-capable (executor, fixer) | `Write(*), Edit(*)` |
| Agent-delegating (planner, executor) | `Task(*)` |

---

## Pattern 3: Task Lifecycle

All teammates follow the same task discovery and lifecycle pattern.

### Standard Flow

```javascript
// Step 1: Find my tasks
const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('<PREFIX>-') &&  // PLAN-*, IMPL-*, TEST-*, REVIEW-*
  t.owner === '<role-name>' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0              // Not blocked
)

// Step 2: No tasks -> idle
if (myTasks.length === 0) return

// Step 3: Claim task (lowest ID first)
const task = TaskGet({ taskId: myTasks[0].id })
TaskUpdate({ taskId: task.id, status: 'in_progress' })

// Step 4: Execute work
// ... role-specific logic ...

// Step 5: Complete and loop
TaskUpdate({ taskId: task.id, status: 'completed' })

// Step 6: Check for next task
const nextTasks = TaskList().filter(t =>
  t.subject.startsWith('<PREFIX>-') &&
  t.owner === '<role-name>' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0
)
if (nextTasks.length > 0) {
  // Continue with next task -> back to Step 3
}
```

### Task Prefix Convention

| Prefix | Role | Example |
|--------|------|---------|
| `PLAN-` | planner | `PLAN-001: Explore and plan implementation` |
| `IMPL-` | executor | `IMPL-001: Implement approved plan` |
| `TEST-` | tester | `TEST-001: Test-fix cycle` |
| `REVIEW-` | tester | `REVIEW-001: Code review and requirement verification` |
| `<NEW>-` | new role | Must be unique, uppercase, hyphen-suffixed |

### Task Chain (defined in coordinate.md)

```
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
         ↑ blockedBy    ↑ blockedBy
```

---

## Pattern 4: Five-Phase Execution Structure

Every team command follows a consistent 5-phase internal structure.

### Standard Phases

| Phase | Purpose | Common Actions |
|-------|---------|----------------|
| Phase 1: Task Discovery | Find and claim assigned tasks | TaskList, TaskGet, TaskUpdate |
| Phase 2: Context Loading | Load necessary context for work | Read plan/config, detect framework |
| Phase 3: Core Work | Execute primary responsibility | Role-specific logic |
| Phase 4: Validation/Summary | Verify work quality | Syntax check, criteria verification |
| Phase 5: Report + Loop | Report to coordinator, check next | SendMessage, TaskUpdate, TaskList |

### Phase Structure Template

```markdown
### Phase N: <Phase Name>

\`\`\`javascript
// Implementation code
\`\`\`
```

---

## Pattern 5: Complexity-Adaptive Routing

All roles that process varying-difficulty tasks should implement adaptive routing.

### Decision Logic

```javascript
function assessComplexity(description) {
  let score = 0
  if (/refactor|architect|restructure|module|system/.test(description)) score += 2
  if (/multiple|across|cross/.test(description)) score += 2
  if (/integrate|api|database/.test(description)) score += 1
  if (/security|performance/.test(description)) score += 1
  return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low'
}
```

### Routing Table

| Complexity | Direct Claude | CLI Agent | Sub-agent |
|------------|---------------|-----------|-----------|
| Low | Direct execution | - | - |
| Medium | - | `cli-explore-agent` / `cli-lite-planning-agent` | - |
| High | - | CLI agent | `code-developer` / `universal-executor` |

### Sub-agent Delegation Pattern

```javascript
Task({
  subagent_type: "<agent-type>",
  run_in_background: false,
  description: "<brief description>",
  prompt: `
## Task Objective
${taskDescription}

## Output Location
${sessionFolder}/${outputFile}

## MANDATORY FIRST STEPS
1. Read: .workflow/project-tech.json (if exists)
2. Read: .workflow/project-guidelines.json (if exists)

## Expected Output
${expectedFormat}
`
})
```

---

## Pattern 6: Coordinator Spawn Integration

New teammates must be spawnable from coordinate.md using standard pattern.

### Skill Path Format (Folder-Based)

Team commands use folder-based organization with colon-separated skill paths:

```
File location:  .claude/commands/team/{team-name}/{role-name}.md
Skill path:     team:{team-name}:{role-name}

Example:
  .claude/commands/team/spec/analyst.md  →  team:spec:analyst
  .claude/commands/team/security/scanner.md  →  team:security:scanner
```

### Spawn Template

> **⚠️ CRITICAL**: Spawn prompt 必须包含完整的 Skill 回调指令。如果 prompt 过于简化（如仅 "Execute task X"），agent 会自行发挥而非通过 Skill → role.md 加载角色定义。

```javascript
Task({
  subagent_type: "general-purpose",
  description: `Spawn ${roleName} worker`,  // ← 必填参数
  team_name: teamName,
  name: "<role-name>",
  prompt: `You are team "${teamName}" <ROLE>.

## ⚠️ 首要指令（MUST）
你的所有工作必须通过调用 Skill 获取角色定义后执行，禁止自行发挥：
Skill(skill="team-${teamName}", args="--role=<role-name>")

When you receive <PREFIX>-* tasks, execute via the Skill callback above.

Current requirement: ${taskDescription}
Constraints: ${constraints}

## Message Bus (Required)
Before each SendMessage, call mcp__ccw-tools__team_msg:
mcp__ccw-tools__team_msg({ operation: "log", team: "${teamName}", from: "<role>", to: "coordinator", type: "<type>", summary: "<summary>" })

Workflow:
1. 调用 Skill(skill="team-${teamName}", args="--role=<role-name>") 获取角色定义
2. 按 role.md 中的 5-Phase 流程执行（TaskList → 找到 <PREFIX>-* 任务 → 执行 → 汇报）
3. team_msg log + SendMessage results to coordinator
4. TaskUpdate completed -> check next task`
})
```

### Spawn Anti-Patterns（必须避免）

| Anti-Pattern | 后果 | 正确做法 |
|-------------|------|---------|
| prompt 中缺少 `Skill(...)` 回调 | agent 自行发挥，不加载 role.md | 必须包含完整 Skill 回调指令 |
| 缺少 `description` 参数 | Task() 调用失败（必填参数） | 始终提供 `description` |
| 缺少 `team_name` 参数 | agent 不属于团队，无法收发消息 | 始终提供 `team_name` |
| 缺少 `name` 参数 | agent 无角色标识 | 始终提供 `name` |
| dispatch/monitor 中 `owner` 值不在 VALID_ROLES | Skill 路由失败 | owner 必须精确匹配 VALID_ROLES key |

---

## Pattern 7: Error Handling Table

Every command ends with a standardized error handling table.

### Template

```markdown
## Error Handling

| Scenario | Resolution |
|----------|------------|
| No tasks available | Idle, wait for coordinator assignment |
| Plan/Context file not found | Notify coordinator, request location |
| Sub-agent failure | Retry once, then fallback to direct execution |
| Max iterations exceeded | Report to coordinator, suggest intervention |
| Critical issue beyond scope | SendMessage fix_required to coordinator |
```

---

## Pattern 8: Session File Structure

Roles that produce artifacts follow standard session directory patterns.

### Convention

```
.workflow/.team-<purpose>/{identifier}-{YYYY-MM-DD}/
├── <work-product-files>
├── manifest.json (if multiple outputs)
└── .task/ (if generating task files)
    ├── TASK-001.json
    └── TASK-002.json
```

---

# Section B: Collaboration Patterns

> Complete specification: [collaboration-patterns.md](collaboration-patterns.md)

## Collaboration Pattern Quick Reference

Every collaboration pattern has these standard elements:

| Element | Description |
|---------|-------------|
| **Entry Condition** | When to activate this pattern |
| **Workflow** | Step-by-step execution flow |
| **Convergence Criteria** | How the pattern terminates successfully |
| **Feedback Loop** | How information flows back to enable correction |
| **Timeout/Fallback** | What happens when the pattern doesn't converge |
| **Max Iterations** | Hard limit on cycles (where applicable) |

### Pattern Selection Guide

| Scenario | Recommended Pattern | Why |
|----------|-------------------|-----|
| Standard feature development | CP-1: Linear Pipeline | Well-defined sequential stages |
| Code review with fixes needed | CP-2: Review-Fix Cycle | Iterative improvement until quality met |
| Multi-angle analysis needed | CP-3: Fan-out/Fan-in | Parallel exploration, aggregated results |
| Critical decision (architecture, security) | CP-4: Consensus Gate | Multiple perspectives before committing |
| Agent stuck / self-repair failed | CP-5: Escalation Chain | Progressive expertise levels |
| Large feature (many files) | CP-6: Incremental Delivery | Validated increments reduce risk |
| Blocking issue stalls pipeline | CP-7: Swarming | All resources on one problem |
| Domain-specific expertise needed | CP-8: Consulting | Expert advice without role change |
| Design + Implementation parallel | CP-9: Dual-Track | Faster delivery with sync checkpoints |
| Post-completion learning | CP-10: Post-Mortem | Capture insights for future improvement |
| Multi-issue plan + execute overlap | CP-11: Beat Pipeline | Per-item dispatch eliminates stage idle time |

---

## Pattern Summary Checklist

When designing a new team command, verify:

### Infrastructure Patterns
- [ ] YAML front matter with `group: team`
- [ ] Message bus section with `team_msg` logging
- [ ] CLI fallback section with `ccw team` CLI examples and parameter mapping
- [ ] Role-specific message types defined
- [ ] Task lifecycle: TaskList -> TaskGet -> TaskUpdate flow
- [ ] Unique task prefix (no collision with existing PLAN/IMPL/TEST/REVIEW, scan `team/**/*.md`)
- [ ] 5-phase execution structure
- [ ] Complexity-adaptive routing (if applicable)
- [ ] Coordinator spawn template integration
- [ ] Error handling table
- [ ] SendMessage communication to coordinator only
- [ ] Session file structure (if producing artifacts)

### Collaboration Patterns
- [ ] At least one collaboration pattern selected
- [ ] Convergence criteria defined (max iterations / quality gate / timeout)
- [ ] Feedback loop implemented (how results flow back)
- [ ] Timeout/fallback behavior specified
- [ ] Pattern-specific message types registered
- [ ] Coordinator aware of pattern (can route messages accordingly)
- [ ] If using CP-11: intermediate artifact protocol defined (file path + format)
- [ ] If using CP-11: inline conflict check implemented (no heavy subagent for dependency detection)

---

## Pattern 9: Parallel Subagent Orchestration

Roles that need to perform complex, multi-perspective work can delegate to subagents or CLI tools rather than executing everything inline. This pattern defines three delegation modes and context management rules.

### Delegation Modes

#### Mode A: Subagent Fan-out

Launch multiple Task agents in parallel for independent work streams.

```javascript
// Launch 2-4 parallel agents for different perspectives
const agents = [
  Task({
    subagent_type: "cli-explore-agent",
    run_in_background: false,
    description: "Explore angle 1",
    prompt: `Analyze from perspective 1: ${taskDescription}`
  }),
  Task({
    subagent_type: "cli-explore-agent",
    run_in_background: false,
    description: "Explore angle 2",
    prompt: `Analyze from perspective 2: ${taskDescription}`
  })
]
// Aggregate results after all complete
```

**When to use**: Multi-angle exploration, parallel code analysis, independent subtask execution.

#### Mode B: CLI Fan-out

Launch multiple `ccw cli` calls for multi-perspective analysis.

```javascript
// Parallel CLI calls for different analysis angles
Bash(`ccw cli -p "PURPOSE: Analyze from security angle..." --tool gemini --mode analysis`, { run_in_background: true })
Bash(`ccw cli -p "PURPOSE: Analyze from performance angle..." --tool gemini --mode analysis`, { run_in_background: true })
// Wait for all CLI results, then synthesize
```

**When to use**: Multi-dimensional code review, architecture analysis, security + performance audits.

#### Mode C: Sequential Delegation

Delegate a single heavy task to a specialized agent.

```javascript
Task({
  subagent_type: "code-developer",
  run_in_background: false,
  description: "Implement complex feature",
  prompt: `## Goal\n${plan.summary}\n\n## Tasks\n${taskDetails}`
})
```

**When to use**: Complex implementation, test-fix cycles, large-scope refactoring.

### Context Management Hierarchy

| Level | Location | Context Size | Use Case |
|-------|----------|-------------|----------|
| Small | role.md inline | < 200 lines | Simple logic, direct execution |
| Medium | commands/*.md | 200-500 lines | Structured delegation with strategy |
| Large | Subagent prompt | Unlimited | Full autonomous execution |

**Rule**: role.md Phase 1/5 are always inline (standardized). Phases 2-4 either inline (small) or delegate to commands (medium/large).

### Command File Extraction Criteria

Extract a phase into a command file when ANY of these conditions are met:

1. **Subagent delegation**: Phase launches Task() agents
2. **CLI fan-out**: Phase runs parallel `ccw cli` calls
3. **Complex strategy**: Phase has >3 conditional branches
4. **Reusable logic**: Same logic used by multiple roles

If none apply, keep the phase inline in role.md.

### Relationship to Other Patterns

- **Pattern 5 (Complexity-Adaptive)**: Pattern 9 provides the delegation mechanisms that Pattern 5 routes to. Low complexity → inline, Medium → CLI agent, High → Subagent fan-out.
- **CP-3 (Parallel Fan-out)**: Pattern 9 Mode A/B are the implementation mechanisms for CP-3 at the role level.
- **Pattern 4 (Five-Phase)**: Pattern 9 does NOT replace the 5-phase structure. It provides delegation options WITHIN phases 2-4.

### Checklist

- [ ] Delegation mode selected based on task characteristics
- [ ] Context management level appropriate (small/medium/large)
- [ ] Command files extracted only when criteria met
- [ ] Subagent prompts include mandatory first steps (read project config)
- [ ] CLI fan-out uses `--mode analysis` by default
- [ ] Results aggregated after parallel completion
- [ ] Error handling covers agent/CLI failure with fallback