Team Designer

Team Skill Designer

Generate complete team skills following the team-lifecycle-v4 architecture: SKILL.md as universal router, coordinator with beat model, worker roles with optional commands/, shared specs, and templates.

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│  Team Skill Designer (SKILL.md)                                  │
│  → Orchestrator: gather requirements, generate files, validate   │
└───────────────────────────┬──────────────────────────────────────┘
                            │
    ┌───────────┬───────────┼───────────┬───────────┐
    ↓           ↓           ↓           ↓
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
│ Require │ │ Scaffold│ │ Content │ │ Valid   │
│ Analysis│ │  Gen    │ │  Gen    │ │ & Report│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
     ↓           ↓           ↓           ↓
  teamConfig  SKILL.md    roles/      Validated
              + dirs     specs/       skill pkg
                         templates/

Key Design Principles

1. v4 Architecture Compliance: Generated skills follow team-lifecycle-v4 pattern — SKILL.md = pure router, beat model = coordinator-only, unified structure (roles/ + specs/ + templates/) 2. Golden Sample Reference: Uses team-lifecycle-v4 as reference implementation at ~ or <project>/.claude/skills/team-lifecycle-v4/ 3. Intelligent Commands Distribution: Auto-determines which roles need commands/ (2+ commands) vs inline logic (1 command) 4. team-worker Compatibility: Role.md files include correct YAML frontmatter for team-worker agent parsing

Execution Flow

Input Parsing:
   └─ Parse user requirements (skill name, roles, pipelines, domain)

Phase 1: Requirements Analysis
   └─ Ref: phases/01-requirements-analysis.md
      ├─ Tasks: Detect input → Gather roles → Define pipelines → Build teamConfig
      └─ Output: teamConfig

Phase 2: Scaffold Generation
   └─ Ref: phases/02-scaffold-generation.md
      ├─ Tasks: Create dirs → Generate SKILL.md router → Verify
      └─ Output: SKILL.md + directory structure

Phase 3: Content Generation
   └─ Ref: phases/03-content-generation.md
      ├─ Tasks: Coordinator → Workers → Specs → Templates
      └─ Output: roles/**/*.md, specs/*.md, templates/*.md

Phase 4: Validation
   └─ Ref: phases/04-validation.md
      └─ Output: Validation report (PASS/REVIEW/FAIL)

Return:
   └─ Summary with skill location and usage instructions

Phase Reference Documents (read on-demand when phase executes):

Golden Sample

Generated skills follow the architecture of ~ or <project>/.claude/skills/team-lifecycle-v4/:

.claude/skills/<skill-name>/
├── SKILL.md                              # Universal router (all roles read)
├── roles/
│   ├── coordinator/
│   │   ├── role.md                       # Orchestrator + beat model + entry router
│   │   └── commands/
│   │       ├── analyze.md                # Task analysis
│   │       ├── dispatch.md               # Task chain creation
│   │       └── monitor.md                # Beat control + callbacks
│   ├── <inline-worker>/
│   │   └── role.md                       # Phase 2-4 embedded (simple role)
│   └── <command-worker>/
│       ├── role.md                       # Phase 2-4 dispatcher
│       └── commands/
│           ├── <cmd-1>.md
│           └── <cmd-2>.md
├── specs/
│   ├── pipelines.md                      # Pipeline definitions + task registry
│   └── <domain-specs>.md                 # Domain-specific specifications
└── templates/                            # Optional document templates

Data Flow

User Input (skill name, roles, pipelines)
    ↓
Phase 1: Requirements Analysis
    ↓ Output: teamConfig
    ↓
Phase 2: Scaffold Generation
    ↓ Input: teamConfig
    ↓ Output: SKILL.md + skillDir
    ↓
Phase 3: Content Generation
    ↓ Input: teamConfig + skillDir
    ↓ Output: roles/, specs/, templates/
    ↓
Phase 4: Validation
    ↓ Input: teamConfig + all files
    ↓ Output: validation report
    ↓
Return summary to user

Core Rules

1. Start Immediately: First action is Phase 1 execution 2. Parse Every Output: Extract teamConfig from Phase 1 for subsequent phases 3. Auto-Continue: After each phase, automatically execute next phase 4. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute 5. Golden Sample Fidelity: Generated files must match team-lifecycle-v4 patterns 6. DO NOT STOP: Continuous workflow until all 4 phases complete

Input Processing

Convert user input to structured format:

SKILL_NAME: [kebab-case name, e.g., team-code-review]
DOMAIN: [what this team does, e.g., "multi-stage code review with security analysis"]
ROLES: [worker roles beyond coordinator, e.g., "analyst, reviewer, security-expert"]
PIPELINES: [pipeline types and flows, e.g., "review-only: SCAN-001 → REVIEW-001 → REPORT-001"]
SESSION_PREFIX: [3-4 char, e.g., TCR]

Error Handling

• Invalid role name: Must be lowercase alphanumeric with hyphens, max 20 chars
• Circular dependencies: Detect and report in pipeline validation
• Missing golden sample: Fall back to embedded templates in phase files
• Directory conflict: Warn if skill directory already exists, ask user to confirm overwrite

Phase 1: Requirements Analysis

Gather team skill requirements from user input and build the teamConfig data structure that drives all subsequent phases.

Objective

• Parse user input (text description, reference skill, or interactive)
• Determine roles, pipelines, specs, templates
• Auto-decide commands distribution (inline vs commands/ folder)
• Build comprehensive teamConfig object
• Confirm with user before proceeding

Step 1.1: Detect Input Source

function detectInputSource(userInput) {
  // Source A: Reference to existing skill
  if (userInput.includes('based on') || userInput.includes('参考') || userInput.includes('like')) {
    return { type: 'reference', refSkill: extractSkillName(userInput) };
  }
  // Source B: Structured input with roles/pipelines
  if (userInput.includes('ROLES:') || userInput.includes('PIPELINES:')) {
    return { type: 'structured', data: parseStructuredInput(userInput) };
  }
  // Source C: Natural language description
  return { type: 'natural', description: userInput };
}

For reference source: Read the referenced skill's SKILL.md and role files to extract structure.

For natural language: Use AskUserQuestion to gather missing details interactively.

Step 1.2: Gather Core Identity

const coreIdentity = AskUserQuestion({
  questions: [
    {
      question: "团队技能名称？(kebab-case, e.g., team-code-review)",
      header: "Skill Name",
      multiSelect: false,
      options: [
        { label: suggestedName, description: "Auto-suggested from description" },
        { label: "Custom", description: "Enter custom name" }
      ]
    },
    {
      question: "会话前缀？(3-4字符用于任务ID, e.g., TCR)",
      header: "Prefix",
      multiSelect: false,
      options: [
        { label: suggestedPrefix, description: "Auto-suggested" },
        { label: "Custom", description: "Enter custom prefix" }
      ]
    }
  ]
});

If user provided clear name/prefix in input, skip this step.

Step 1.3: Determine Roles

Role Discovery from Domain

Analyze domain description to identify required roles:

function discoverRoles(domain) {
  const rolePatterns = {
    'analyst': ['分析', 'analyze', 'research', 'explore', 'investigate', 'scan'],
    'planner': ['规划', 'plan', 'design', 'architect', 'decompose'],
    'writer': ['文档', 'write', 'document', 'draft', 'spec', 'report'],
    'executor': ['实现', 'implement', 'execute', 'build', 'code', 'develop'],
    'tester': ['测试', 'test', 'verify', 'validate', 'qa'],
    'reviewer': ['审查', 'review', 'quality', 'check', 'audit', 'inspect'],
    'security-expert': ['安全', 'security', 'vulnerability', 'penetration'],
    'performance-optimizer': ['性能', 'performance', 'optimize', 'benchmark'],
    'data-engineer': ['数据', 'data', 'pipeline', 'etl', 'migration'],
    'devops-engineer': ['部署', 'devops', 'deploy', 'ci/cd', 'infrastructure'],
  };

  const matched = [];
  for (const [role, keywords] of Object.entries(rolePatterns)) {
    if (keywords.some(kw => domain.toLowerCase().includes(kw))) {
      matched.push(role);
    }
  }
  return matched;
}

Role Configuration

For each discovered role, determine:

function configureRole(roleName) {
  return {
    name: roleName,
    prefix: determinePrefix(roleName),
    inner_loop: determineInnerLoop(roleName),
    hasCommands: false,  // determined in Step 1.5
    commands: [],
    message_types: determineMessageTypes(roleName),
    path: `roles/${roleName}/role.md`
  };
}

// Standard prefix mapping
const prefixMap = {
  'analyst': 'RESEARCH',
  'writer': 'DRAFT',
  'planner': 'PLAN',
  'executor': 'IMPL',
  'tester': 'TEST',
  'reviewer': 'REVIEW',
  // Dynamic roles use uppercase role name
};

// Inner loop: roles that process multiple tasks sequentially
const innerLoopRoles = ['executor', 'writer', 'planner'];

// Message types the role handles
const messageMap = {
  'analyst': ['state_update'],
  'writer': ['state_update', 'discuss_response'],
  'planner': ['state_update'],
  'executor': ['state_update', 'revision_request'],
  'tester': ['state_update'],
  'reviewer': ['state_update', 'discuss_request'],
};

Step 1.4: Define Pipelines

Pipeline Types from Role Combination

function definePipelines(roles, domain) {
  const has = name => roles.some(r => r.name === name);

  // Full lifecycle: analyst → writer → planner → executor → tester → reviewer
  if (has('analyst') && has('writer') && has('planner') && has('executor'))
    return [{ name: 'full-lifecycle', tasks: buildFullLifecycleTasks(roles) }];

  // Spec-only: analyst → writer → reviewer
  if (has('analyst') && has('writer') && !has('executor'))
    return [{ name: 'spec-only', tasks: buildSpecOnlyTasks(roles) }];

  // Impl-only: planner → executor → tester → reviewer
  if (has('planner') && has('executor') && !has('analyst'))
    return [{ name: 'impl-only', tasks: buildImplOnlyTasks(roles) }];

  // Custom: user-defined
  return [{ name: 'custom', tasks: buildCustomTasks(roles, domain) }];
}

Task Schema

const taskSchema = {
  id: 'PREFIX-NNN',       // e.g., RESEARCH-001
  role: 'analyst',        // which role executes
  name: 'Seed Analysis',  // human-readable name
  dependsOn: [],          // task IDs that must complete first
  isCheckpoint: false,    // true for quality gates
  isConditional: false,   // true for routing decisions
  description: '...'
};

Step 1.5: Determine Commands Distribution

Rule: 1 action → inline in role.md. 2+ distinct actions → commands/ folder.

function determineCommandsDistribution(roles) {
  // Coordinator: always has commands/
  // coordinator.commands = ['analyze', 'dispatch', 'monitor']

  // Standard multi-action roles:
  // executor → implement + fix → commands/
  // reviewer (if both code & spec review) → review-code + review-spec → commands/
  // All others → typically inline

  for (const role of roles) {
    const actions = countDistinctActions(role);
    if (actions.length >= 2) {
      role.hasCommands = true;
      role.commands = actions.map(a => a.name);
    }
  }
}

Step 1.6: Determine Specs and Templates

// Specs: always include pipelines, add domain-specific
const specs = ['pipelines'];
if (hasQualityGates) specs.push('quality-gates');
if (hasKnowledgeTransfer) specs.push('knowledge-transfer');

// Templates: only if writer role exists
const templates = [];
if (has('writer')) {
  // Detect from domain keywords
  if (domain.includes('product')) templates.push('product-brief');
  if (domain.includes('requirement')) templates.push('requirements');
  if (domain.includes('architecture')) templates.push('architecture');
  if (domain.includes('epic')) templates.push('epics');
}

Step 1.7: Build teamConfig

const teamConfig = {
  skillName: string,          // e.g., "team-code-review"
  sessionPrefix: string,      // e.g., "TCR"
  domain: string,             // domain description
  title: string,              // e.g., "Code Review Team"
  roles: Array<RoleConfig>,   // includes coordinator
  pipelines: Array<Pipeline>,
  specs: Array<string>,       // filenames without .md
  templates: Array<string>,   // filenames without .md
  conditionalRouting: boolean,
  dynamicSpecialists: Array<string>,
};

Step 1.8: Confirm with User

╔══════════════════════════════════════════╗
║  Team Skill Configuration Summary        ║
╠══════════════════════════════════════════╣

Skill Name:     ${skillName}
Session Prefix: ${sessionPrefix}
Domain:         ${domain}

Roles (N):
  ├─ coordinator (commands: analyze, dispatch, monitor)
  ├─ role-a [PREFIX-*] (inline) 🔄
  └─ role-b [PREFIX-*] (commands: cmd1, cmd2)

Pipelines:
  └─ pipeline-name: TASK-001 → TASK-002 → TASK-003

Specs: pipelines, quality-gates
Templates: (none)

╚══════════════════════════════════════════╝

Use AskUserQuestion to confirm or allow modifications.

Output

• Variable: teamConfig — complete configuration for all subsequent phases
• Next: Phase 2 - Scaffold Generation

Phase 2: Scaffold Generation

Generate the SKILL.md universal router and create the directory structure for the team skill.

Objective

• Create directory structure (roles/, specs/, templates/)
• Generate SKILL.md as universal router following v4 pattern
• SKILL.md must NOT contain beat model, pipeline details, or role Phase 2-4 logic

Step 2.1: Create Directory Structure

skillDir=".claude/skills/${teamConfig.skillName}"
mkdir -p "${skillDir}"

# Create role directories
for role in teamConfig.roles:
  mkdir -p "${skillDir}/roles/${role.name}"
  if role.hasCommands:
    mkdir -p "${skillDir}/roles/${role.name}/commands"

# Create specs directory
mkdir -p "${skillDir}/specs"

# Create templates directory (if needed)
if teamConfig.templates.length > 0:
  mkdir -p "${skillDir}/templates"

Step 2.2: Generate SKILL.md

The SKILL.md follows a strict template. Every generated SKILL.md contains these sections in order:

Section 1: Frontmatter

---
name: ${teamConfig.skillName}
description: "${teamConfig.domain}. Triggers on ${teamConfig.skillName}."
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---

Section 2: Title + Architecture Diagram

# ${Title}

${One-line description}

## Architecture

\```
Skill(skill="${teamConfig.skillName}", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze → dispatch → spawn workers → STOP
                                    |
                    +-------+-------+-------+
                    v       v       v       v
                 [team-worker agents, each loads roles/<role>/role.md]
\```

Section 3: Role Registry

## Role Registry

| Role | Path | Prefix | Inner Loop |
|------|------|--------|------------|
| coordinator | roles/coordinator/role.md | — | — |
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
  `| ${r.name} | ${r.path} | ${r.prefix}-* | ${r.inner_loop} |`
).join('\n')}

Section 4: Role Router

## Role Router

Parse `$ARGUMENTS`:
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
- No `--role` → Read `roles/coordinator/role.md`, execute entry router

Section 5: Shared Constants

## Shared Constants

- **Session prefix**: `${teamConfig.sessionPrefix}`
- **Session path**: `.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/`
- **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications)
- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`

Section 6: Worker Spawn Template

## Worker Spawn Template

Coordinator spawns workers using this template:

\```
Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: <team-name>,
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: .claude/skills/${teamConfig.skillName}/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})
\```

Section 7: User Commands

## User Commands

| Command | Action |
|---------|--------|
| `check` / `status` | View execution status graph |
| `resume` / `continue` | Advance to next step |
| `revise <TASK-ID> [feedback]` | Revise specific task |
| `feedback <text>` | Inject feedback for revision |
| `recheck` | Re-run quality check |
| `improve [dimension]` | Auto-improve weakest dimension |

Section 8: Completion Action

## Completion Action

When pipeline completes, coordinator presents:

\```
AskUserQuestion({
  questions: [{
    question: "Pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
      { label: "Keep Active", description: "Keep session for follow-up work" },
      { label: "Export Results", description: "Export deliverables to target directory" }
    ]
  }]
})
\```

Section 9: Specs Reference

## Specs Reference

${teamConfig.specs.map(s =>
  `- [specs/${s}.md](specs/${s}.md) — ${specDescription(s)}`
).join('\n')}

Section 10: Session Directory

## Session Directory

\```
.workflow/.team/${teamConfig.sessionPrefix}-<slug>-<date>/
├── team-session.json           # Session state + role registry
├── spec/                       # Spec phase outputs
├── plan/                       # Implementation plan + TASK-*.json
├── artifacts/                  # All deliverables
├── wisdom/                     # Cross-task knowledge
├── explorations/               # Shared explore cache
├── discussions/                # Discuss round records
└── .msg/                       # Team message bus
\```

Section 11: Error Handling

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| CLI tool fails | Worker fallback to direct implementation |
| Fast-advance conflict | Coordinator reconciles on next callback |
| Completion action fails | Default to Keep Active |

Step 2.3: Assemble and Write

Assemble all sections into a single SKILL.md file and write to ${skillDir}/SKILL.md.

Quality Rules: 1. SKILL.md must NOT contain beat model (ONE_STEP_PER_INVOCATION, spawn-and-stop) 2. SKILL.md must NOT contain pipeline task details (task IDs, dependencies) 3. SKILL.md must NOT contain role Phase 2-4 logic 4. SKILL.md MUST contain role registry table with correct paths 5. SKILL.md MUST contain worker spawn template with correct role_spec paths

Output

• File: .claude/skills/${teamConfig.skillName}/SKILL.md
• Variable: skillDir (path to skill root directory)
• Next: Phase 3 - Content Generation

Next Phase

Return to orchestrator, then auto-continue to Phase 3: Content Generation.

Phase 3: Content Generation

Generate all role files, specs, and templates based on teamConfig and the generated SKILL.md.

Objective

• Generate coordinator role.md + commands/ (analyze, dispatch, monitor)
• Generate each worker role.md (inline or with commands/)
• Generate specs/ files (pipelines.md + domain specs)
• Generate templates/ if needed
• Follow team-lifecycle-v4 golden sample patterns

Golden Sample Reference

Read the golden sample at ~ or <project>/.claude/skills/team-lifecycle-v4/ for each file type before generating. This ensures pattern fidelity.

Step 3.1: Generate Coordinator

The coordinator is the most complex role. It always has 3 commands.

coordinator/role.md

---
role: coordinator
---

# Coordinator — ${teamConfig.title}

## Identity

You are the coordinator for ${teamConfig.title}. You orchestrate the ${teamConfig.domain} pipeline by analyzing requirements, dispatching tasks, and monitoring worker progress.

## Boundaries

- **DO**: Analyze, dispatch, monitor, reconcile, report
- **DO NOT**: Implement domain work directly — delegate to workers

## Command Execution Protocol

Read command file → Execute ALL steps sequentially → Return to entry router.
Commands: `commands/analyze.md`, `commands/dispatch.md`, `commands/monitor.md`.

## Entry Router

On each invocation, detect current state and route:

| Condition | Handler |
|-----------|---------|
| First invocation (no session) | → Phase 1: Requirement Clarification |
| Session exists, no team | → Phase 2: Team Setup |
| Team exists, no tasks | → Phase 3: Dispatch (analyze.md → dispatch.md) |
| Tasks exist, none started | → Phase 4: Spawn First (monitor.md → handleSpawnNext) |
| Callback received | → monitor.md → handleCallback |
| User says "check"/"status" | → monitor.md → handleCheck |
| User says "resume"/"continue" | → monitor.md → handleResume |
| All tasks completed | → Phase 5: Report & Completion |

## Phase 0: Session Resume

If `.workflow/.team/${teamConfig.sessionPrefix}-*/team-session.json` exists:
- Load session state, verify team, reconcile task status
- Route to appropriate handler based on current state

## Phase 1: Requirement Clarification

- Parse user's task description at TEXT LEVEL
- Use AskUserQuestion if requirements are ambiguous
- Execute `commands/analyze.md` for signal detection + complexity scoring

## Phase 2: Team Setup

- TeamCreate with session ID: `${teamConfig.sessionPrefix}-<slug>-<date>`
- Initialize team_msg message bus
- Create session directory structure

## Phase 3: Dispatch

- Execute `commands/dispatch.md`
- Creates TaskCreate calls, then sets dependencies via TaskUpdate({ addBlockedBy })

## Phase 4: Spawn & Monitor

- Execute `commands/monitor.md` → handleSpawnNext
- Spawn ready workers as team-worker agents
- **STOP after spawning** — wait for callback

## Phase 5: Report & Completion

- Aggregate all task artifacts
- Present completion action to user

coordinator/commands/analyze.md

Template based on golden sample — includes:

• Signal detection (keywords → capabilities)
• Dependency graph construction (tiers)
• Complexity scoring (1-3 Low, 4-6 Medium, 7+ High)
• Role minimization (cap at 5)
• Output: task-analysis.json

# Command: Analyze

## Signal Detection

Scan requirement text for capability signals:
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r =>
  `- **${r.name}**: [domain-specific keywords]`
).join('\n')}

## Dependency Graph

Build 4-tier dependency graph:
- Tier 0: Independent tasks (can run in parallel)
- Tier 1: Depends on Tier 0
- Tier 2: Depends on Tier 1
- Tier 3: Depends on Tier 2

## Complexity Scoring

| Score | Level | Strategy |
|-------|-------|----------|
| 1-3 | Low | Direct implementation, skip deep planning |
| 4-6 | Medium | Standard pipeline with planning |
| 7+ | High | Full spec → plan → implement cycle |

## Output

Write `task-analysis.json` to session directory:
\```json
{
  "signals": [...],
  "roles_needed": [...],
  "dependency_tiers": [...],
  "complexity": { "score": N, "level": "Low|Medium|High" },
  "pipeline": "${teamConfig.pipelines[0].name}"
}
\```

coordinator/commands/dispatch.md

Template — includes:

• Topological sort from dependency graph
• TaskCreate + TaskUpdate({ addBlockedBy }) for dependencies
• Task description template (PURPOSE/TASK/CONTEXT/EXPECTED/CONSTRAINTS)

coordinator/commands/monitor.md

Template — includes:

• Beat model constants (ONE_STEP_PER_INVOCATION, SPAWN_MODE: spawn-and-stop)
• 6 handlers: handleCallback, handleCheck, handleResume, handleSpawnNext, handleComplete, handleAdapt
• Checkpoint detection for quality gates
• Fast-advance reconciliation

Critical: This is the ONLY file that contains beat model logic.

Step 3.2: Generate Worker Roles

For each worker role in teamConfig.roles:

Inline Role Template (no commands/)

---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---

# ${capitalize(role.name)} — ${teamConfig.title}

## Identity

You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`

## Phase 2: Context Loading

- Read task description from TaskGet
- Load relevant session artifacts from session directory
- Load specs from `specs/` as needed

## Phase 3: Domain Execution

[Domain-specific execution logic for this role]

### Execution Steps

1. [Step 1 based on role's domain]
2. [Step 2]
3. [Step 3]

### Tools Available

- CLI tools: `ccw cli --mode analysis|write`
- Direct tools: Read, Write, Edit, Bash, Grep, Glob
- Message bus: `mcp__ccw-tools__team_msg`
- **Cannot use Agent()** — workers must use CLI or direct tools

## Phase 4: Output & Report

- Write artifacts to session directory
- Log state_update via team_msg
- Publish wisdom if cross-task knowledge discovered

Command-Based Role Template (has commands/)

---
role: ${role.name}
prefix: ${role.prefix}
inner_loop: ${role.inner_loop}
message_types: [${role.message_types.join(', ')}]
---

# ${capitalize(role.name)} — ${teamConfig.title}

## Identity

You are the ${role.name} for ${teamConfig.title}.
Task prefix: `${role.prefix}-*`

## Phase 2: Context Loading

Load task description, detect mode/command.

## Phase 3: Command Router

| Condition | Command |
|-----------|---------|
${role.commands.map(cmd =>
  `| [condition for ${cmd}] | → commands/${cmd}.md |`
).join('\n')}

Read command file → Execute ALL steps → Return to Phase 4.

## Phase 4: Output & Report

Write artifacts, log state_update.

Then generate each commands/<cmd>.md with domain-specific logic.

Step 3.3: Generate Specs

specs/pipelines.md

# Pipeline Definitions

## Available Pipelines

${teamConfig.pipelines.map(p => `
### ${p.name}

| Task ID | Role | Name | Depends On | Checkpoint |
|---------|------|------|------------|------------|
${p.tasks.map(t =>
  `| ${t.id} | ${t.role} | ${t.name} | ${t.dependsOn.join(', ') || '—'} | ${t.isCheckpoint ? '✓' : '—'} |`
).join('\n')}
`).join('\n')}

## Task Metadata Registry

Standard task description template:

\```
PURPOSE: [goal]
TASK: [steps]
CONTEXT: [session artifacts + specs]
EXPECTED: [deliverable format]
CONSTRAINTS: [scope limits]
\```

## Conditional Routing

${teamConfig.conditionalRouting ? `
PLAN-001 complexity assessment routes to:
- Low (1-3): Direct implementation
- Medium (4-6): Standard planning
- High (7+): Full spec → plan → implement
` : 'No conditional routing in this pipeline.'}

## Dynamic Specialist Injection

${teamConfig.dynamicSpecialists.length > 0 ?
  teamConfig.dynamicSpecialists.map(s => `- ${s}: Injected when domain keywords detected`).join('\n') :
  'No dynamic specialists configured.'
}

Additional Specs

For each additional spec in teamConfig.specs (beyond pipelines), generate domain-appropriate content:

• quality-gates.md: Thresholds (Pass≥80%, Review 60-79%, Fail<60%), scoring dimensions, per-phase gates
• knowledge-transfer.md: 5 transfer channels, Phase 2 loading protocol, Phase 4 publishing protocol

Step 3.4: Generate Templates

For each template in teamConfig.templates:

1. Check if golden sample has matching template at ~ or <project>/.claude/skills/team-lifecycle-v4/templates/ 2. If exists: copy and adapt for new domain 3. If not: generate domain-appropriate template structure

Step 3.5: Generation Order

Execute in this order (respects dependencies):

1. specs/ — needed by roles for reference 2. coordinator/ — role.md + commands/ (3 files) 3. workers/ — each role.md (+ optional commands/) 4. templates/ — independent, generate last

For each file: 1. Read golden sample equivalent (if exists) 2. Adapt content for current teamConfig 3. Write file 4. Verify file exists

Output

• Files: All role.md, commands/.md, specs/.md, templates/*.md
• Next: Phase 4 - Validation

Phase 4: Validation

Validate the generated team skill package for structural completeness, reference integrity, role consistency, and team-worker compatibility.

Objective

• Verify all required files exist
• Validate SKILL.md role registry matches actual role files
• Check role.md frontmatter format for team-worker compatibility
• Verify pipeline task references match existing roles
• Report validation results

Step 4.1: Structural Validation

function validateStructure(teamConfig) {
  const skillDir = `.claude/skills/${teamConfig.skillName}`;
  const results = { errors: [], warnings: [], info: [] };

  // Check SKILL.md exists
  if (!fileExists(`${skillDir}/SKILL.md`)) {
    results.errors.push('SKILL.md not found');
  }

  // Check coordinator structure
  if (!fileExists(`${skillDir}/roles/coordinator/role.md`)) {
    results.errors.push('Coordinator role.md not found');
  }
  for (const cmd of ['analyze', 'dispatch', 'monitor']) {
    if (!fileExists(`${skillDir}/roles/coordinator/commands/${cmd}.md`)) {
      results.errors.push(`Coordinator command ${cmd}.md not found`);
    }
  }

  // Check worker roles
  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
    if (!fileExists(`${skillDir}/roles/${role.name}/role.md`)) {
      results.errors.push(`Worker role.md not found: ${role.name}`);
    }
    if (role.hasCommands) {
      for (const cmd of role.commands) {
        if (!fileExists(`${skillDir}/roles/${role.name}/commands/${cmd}.md`)) {
          results.errors.push(`Worker command not found: ${role.name}/commands/${cmd}.md`);
        }
      }
    }
  }

  // Check specs
  if (!fileExists(`${skillDir}/specs/pipelines.md`)) {
    results.errors.push('specs/pipelines.md not found');
  }

  return results;
}

Step 4.2: SKILL.md Content Validation

function validateSkillMd(teamConfig) {
  const skillDir = `.claude/skills/${teamConfig.skillName}`;
  const results = { errors: [], warnings: [], info: [] };
  const skillMd = Read(`${skillDir}/SKILL.md`);

  // Required sections
  const requiredSections = [
    'Role Registry', 'Role Router', 'Shared Constants',
    'Worker Spawn Template', 'User Commands', 'Session Directory'
  ];
  for (const section of requiredSections) {
    if (!skillMd.includes(section)) {
      results.errors.push(`SKILL.md missing section: ${section}`);
    }
  }

  // Verify role registry completeness
  for (const role of teamConfig.roles) {
    if (!skillMd.includes(role.path || `roles/${role.name}/role.md`)) {
      results.errors.push(`Role registry missing path for: ${role.name}`);
    }
  }

  // Verify session prefix
  if (!skillMd.includes(teamConfig.sessionPrefix)) {
    results.warnings.push(`Session prefix ${teamConfig.sessionPrefix} not found in SKILL.md`);
  }

  // Verify NO beat model content in SKILL.md
  const beatModelPatterns = [
    'ONE_STEP_PER_INVOCATION',
    'spawn-and-stop',
    'SPAWN_MODE',
    'handleCallback',
    'handleSpawnNext'
  ];
  for (const pattern of beatModelPatterns) {
    if (skillMd.includes(pattern)) {
      results.errors.push(`SKILL.md contains beat model content: ${pattern} (should be in coordinator only)`);
    }
  }

  return results;
}

Step 4.3: Role Frontmatter Validation

Verify role.md files have correct YAML frontmatter for team-worker agent compatibility:

function validateRoleFrontmatter(teamConfig) {
  const skillDir = `.claude/skills/${teamConfig.skillName}`;
  const results = { errors: [], warnings: [], info: [] };

  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
    const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);

    // Check frontmatter exists
    if (!roleMd.startsWith('---')) {
      results.errors.push(`${role.name}/role.md missing YAML frontmatter`);
      continue;
    }

    // Extract frontmatter
    const fmMatch = roleMd.match(/^---\n([\s\S]*?)\n---/);
    if (!fmMatch) {
      results.errors.push(`${role.name}/role.md malformed frontmatter`);
      continue;
    }

    const fm = fmMatch[1];

    // Required fields
    if (!fm.includes(`role: ${role.name}`)) {
      results.errors.push(`${role.name}/role.md frontmatter missing 'role: ${role.name}'`);
    }
    if (!fm.includes(`prefix: ${role.prefix}`)) {
      results.errors.push(`${role.name}/role.md frontmatter missing 'prefix: ${role.prefix}'`);
    }
    if (!fm.includes(`inner_loop: ${role.inner_loop}`)) {
      results.warnings.push(`${role.name}/role.md frontmatter missing 'inner_loop: ${role.inner_loop}'`);
    }
    if (!fm.includes('message_types:')) {
      results.warnings.push(`${role.name}/role.md frontmatter missing 'message_types'`);
    }
  }

  return results;
}

Step 4.4: Pipeline Consistency

function validatePipelines(teamConfig) {
  const skillDir = `.claude/skills/${teamConfig.skillName}`;
  const results = { errors: [], warnings: [], info: [] };

  // Check every role referenced in pipelines exists
  const definedRoles = new Set(teamConfig.roles.map(r => r.name));

  for (const pipeline of teamConfig.pipelines) {
    for (const task of pipeline.tasks) {
      if (!definedRoles.has(task.role)) {
        results.errors.push(
          `Pipeline '${pipeline.name}' task ${task.id} references undefined role: ${task.role}`
        );
      }
    }

    // Check for circular dependencies
    const visited = new Set();
    const stack = new Set();
    for (const task of pipeline.tasks) {
      if (hasCycle(task, pipeline.tasks, visited, stack)) {
        results.errors.push(`Pipeline '${pipeline.name}' has circular dependency involving ${task.id}`);
      }
    }
  }

  // Verify specs/pipelines.md contains all pipelines
  const pipelinesMd = Read(`${skillDir}/specs/pipelines.md`);
  for (const pipeline of teamConfig.pipelines) {
    if (!pipelinesMd.includes(pipeline.name)) {
      results.warnings.push(`specs/pipelines.md missing pipeline: ${pipeline.name}`);
    }
  }

  return results;
}

Step 4.5: Commands Distribution Validation

function validateCommandsDistribution(teamConfig) {
  const skillDir = `.claude/skills/${teamConfig.skillName}`;
  const results = { errors: [], warnings: [], info: [] };

  for (const role of teamConfig.roles.filter(r => r.name !== 'coordinator')) {
    if (role.hasCommands) {
      // Verify commands/ directory exists and has files
      const cmdDir = `${skillDir}/roles/${role.name}/commands`;
      if (role.commands.length < 2) {
        results.warnings.push(
          `${role.name} has commands/ but only ${role.commands.length} command(s) — consider inline`
        );
      }
      // Verify role.md references commands
      const roleMd = Read(`${skillDir}/roles/${role.name}/role.md`);
      for (const cmd of role.commands) {
        if (!roleMd.includes(`commands/${cmd}.md`)) {
          results.warnings.push(
            `${role.name}/role.md doesn't reference commands/${cmd}.md`
          );
        }
      }
    } else {
      // Verify no commands/ directory exists
      const cmdDir = `${skillDir}/roles/${role.name}/commands`;
      if (directoryExists(cmdDir)) {
        results.warnings.push(
          `${role.name} is inline but has commands/ directory`
        );
      }
    }
  }

  return results;
}

Step 4.6: Aggregate Results and Report

function generateValidationReport(teamConfig) {
  const structural = validateStructure(teamConfig);
  const skillMd = validateSkillMd(teamConfig);
  const frontmatter = validateRoleFrontmatter(teamConfig);
  const pipelines = validatePipelines(teamConfig);
  const commands = validateCommandsDistribution(teamConfig);

  const allErrors = [
    ...structural.errors, ...skillMd.errors,
    ...frontmatter.errors, ...pipelines.errors, ...commands.errors
  ];
  const allWarnings = [
    ...structural.warnings, ...skillMd.warnings,
    ...frontmatter.warnings, ...pipelines.warnings, ...commands.warnings
  ];

  const gate = allErrors.length === 0 ? 'PASS' :
               allErrors.length <= 2 ? 'REVIEW' : 'FAIL';

  const skillDir = `.claude/skills/${teamConfig.skillName}`;

  console.log(`
╔══════════════════════════════════════╗
║   Team Skill Validation Report       ║
╠══════════════════════════════════════╣
║  Skill: ${teamConfig.skillName.padEnd(28)}║
║  Gate:  ${gate.padEnd(28)}║
╚══════════════════════════════════════╝

Structure:
  ${skillDir}/
  ├── SKILL.md                                    ✓
  ├── roles/
  │   ├── coordinator/
  │   │   ├── role.md                             ✓
  │   │   └── commands/ (analyze, dispatch, monitor)
${teamConfig.roles.filter(r => r.name !== 'coordinator').map(r => {
  const structure = r.hasCommands
    ? `  │   ├── ${r.name}/ (role.md + commands/)`
    : `  │   ├── ${r.name}/role.md`;
  return `${structure.padEnd(50)}✓`;
}).join('\n')}
  ├── specs/
  │   └── pipelines.md                            ✓
  └── templates/                                  ${teamConfig.templates.length > 0 ? '✓' : '(empty)'}

${allErrors.length > 0 ? `Errors (${allErrors.length}):\n${allErrors.map(e => `  ✗ ${e}`).join('\n')}` : 'Errors: None ✓'}

${allWarnings.length > 0 ? `Warnings (${allWarnings.length}):\n${allWarnings.map(w => `  ⚠ ${w}`).join('\n')}` : 'Warnings: None ✓'}

Usage:
  Skill(skill="${teamConfig.skillName}", args="<task description>")
  `);

  return { gate, errors: allErrors, warnings: allWarnings };
}

Step 4.7: Error Recovery

if (report.gate === 'FAIL') {
  const recovery = AskUserQuestion({
    questions: [{
      question: `Validation found ${report.errors.length} errors. How to proceed?`,
      header: "Recovery",
      multiSelect: false,
      options: [
        { label: "Auto-fix", description: "Attempt automatic fixes (missing files, frontmatter)" },
        { label: "Regenerate", description: "Re-run Phase 3 with fixes" },
        { label: "Accept as-is", description: "Manual fix later" }
      ]
    }]
  });
}

Output

• Report: Validation results with quality gate (PASS/REVIEW/FAIL)
• Completion: Team skill package ready at .claude/skills/${teamConfig.skillName}/

Completion

Team Skill Designer has completed. The generated team skill is ready for use.

Next Steps:
  1. Review SKILL.md router for correctness
  2. Review each role.md for domain accuracy
  3. Test: Skill(skill="${teamConfig.skillName}", args="<test task>")
  4. Iterate based on execution results