Add role and skill router templates for v3 style execution

- Introduced a comprehensive role template for generating per-role execution detail files, including purpose, style rules, and structured phases. - Added a skill router template to facilitate role-based routing in SKILL.md, detailing input parsing, role registry, orchestration mode, and shared infrastructure. - Both templates adhere to v3 conventions, emphasizing clarity and structured decision-making through markdown tables and diagrams.
2026-03-01 15:03:57 +08:00 · 2026-02-26 16:32:17 +08:00
parent 653ad10475
commit 1a1ca389f4
15 changed files with 5438 additions and 1723 deletions
--- a/.claude/skills_lib/team-skill-designer-v2/phases/01-requirements-collection.md
+++ b/.claude/skills_lib/team-skill-designer-v2/phases/01-requirements-collection.md
@@ -0,0 +1,200 @@
+# Phase 1: Requirements Collection (Task-Driven Inference)
+
+Analyze task requirements, infer appropriate roles, and generate team configuration.
+
+## Objective
+
+- Determine team name and display name
+- Analyze task description to infer needed roles (coordinator always included)
+- For each role: name, responsibility type, task prefix, capabilities
+- Build pipeline from inferred roles
+- Generate `team-config.json`
+
+## Input
+
+| Source | Description |
+|--------|-------------|
+| User request | `$ARGUMENTS` or interactive input |
+| Specification | `specs/team-design-patterns.md` (read in Phase 0) |
+
+## Execution Steps
+
+### Step 1: Team Name + Task Description
+
+Prompt the user for team name and core task description.
+
+```
+AskUserQuestion({
+  questions: [
+    { question: "Team name (lowercase, used as .claude/skills/team-{name}/)",
+      header: "Team Name",
+      options: ["custom", "dev", "spec", "security"] },
+    { question: "Core task of this team? (system will infer roles automatically)",
+      header: "Task Desc",
+      options: ["custom", "fullstack dev", "code review + refactor", "doc writing"] }
+  ]
+})
+```
+
+### Step 2: Role Inference (Task-Driven)
+
+Coordinator is **always** included. Scan the task description for intent signals to infer worker roles.
+
+#### Role Signal Detection Table
+
+| Role | Keywords (CN/EN) | Responsibility Type | Task Prefix |
+|------|-------------------|---------------------|-------------|
+| planner | plan, design, architect, explore, analyze requirements | Orchestration | PLAN |
+| executor | implement, develop, build, code, create, refactor, migrate | Code generation | IMPL |
+| tester | test, verify, validate, QA, regression, fix, bug | Validation | TEST |
+| reviewer | review, audit, inspect, code quality | Read-only analysis | REVIEW |
+| analyst | research, analyze, investigate, diagnose | Orchestration | RESEARCH |
+| writer | document, write doc, generate report | Code generation | DRAFT |
+| debugger | debug, troubleshoot, root cause | Orchestration | DEBUG |
+| security | security, vulnerability, OWASP, compliance | Read-only analysis | SEC |
+
+**Inference**: For each role, check if task description matches any keyword. Add matched roles to the inferred list.
+
+#### Implicit Role Completion Table
+
+| Condition | Add Role | Reason |
+|-----------|----------|--------|
+| Has executor, missing planner | Add planner (before executor) | Code needs planning first |
+| Has executor, missing tester | Add tester (after executor) | Code needs validation |
+| Has debugger, missing tester | Add tester | Bug fixes need verification |
+| Has writer, missing reviewer | Add reviewer | Documents need review |
+
+**Minimum guarantee**: If fewer than 2 worker roles inferred, fall back to standard set: planner + executor + tester + reviewer.
+
+**Pipeline type tag** (for Step 5):
+
+| Condition | Pipeline Type |
+|-----------|---------------|
+| Has writer role | Document |
+| Has debugger role | Debug |
+| Default | Standard |
+
+### Step 3: Role Confirmation (Interactive)
+
+Present the inferred roles to the user for confirmation.
+
+```
+AskUserQuestion({
+  questions: [
+    { question: "Inferred roles: <roles-summary>. Adjust?",
+      header: "Confirm",
+      options: ["Confirm (Recommended)", "Add role", "Remove role", "Re-describe"] }
+  ]
+})
+```
+
+| User Choice | Action |
+|-------------|--------|
+| Confirm | Proceed with inferred roles |
+| Add role | AskUserQuestion for new role name + responsibility type |
+| Remove role | AskUserQuestion for which role to remove |
+| Re-describe | Return to Step 1, re-enter task description |
+
+### Step 4: Capability Assignment (Per Role)
+
+For each worker role, assign capabilities based on responsibility type.
+
+#### Tool Assignment Table
+
+| Responsibility Type | Extra Tools (beyond base set) | Adaptive Routing |
+|---------------------|-------------------------------|------------------|
+| Read-only analysis | Task(*) | No |
+| Code generation | Write(*), Edit(*), Task(*) | Yes |
+| Orchestration | Write(*), Task(*) | Yes |
+| Validation | Write(*), Edit(*), Task(*) | No |
+
+> **Base tools** (all roles): SendMessage, TaskUpdate, TaskList, TaskGet, TodoWrite, Read, Bash, Glob, Grep
+
+#### Message Type Assignment Table
+
+| Responsibility Type | Message Types |
+|---------------------|---------------|
+| Read-only analysis | `<role>_result` (analysis complete), `error` |
+| Code generation | `<role>_complete`, `<role>_progress`, `error` |
+| Orchestration | `<role>_ready`, `<role>_progress`, `error` |
+| Validation | `<role>_result`, `fix_required`, `error` |
+
+**Coordinator** gets special tools: TeamCreate, TeamDelete, AskUserQuestion, TaskCreate + all base tools.
+**Coordinator** message types: `plan_approved`, `plan_revision`, `task_unblocked`, `shutdown`, `error`.
+
+#### Toolbox Assignment Table
+
+| Responsibility Type | Commands | Subagents | CLI Tools |
+|---------------------|----------|-----------|-----------|
+| Read-only analysis | review, analyze | (none) | gemini (analysis), codex (review) |
+| Code generation | implement, validate | code-developer | (none) |
+| Orchestration | explore, plan | cli-explore-agent, cli-lite-planning-agent | gemini (analysis) |
+| Validation | validate | code-developer | (none) |
+
+**Coordinator** always gets: commands=[dispatch, monitor], no subagents, no CLI tools.
+
+### Step 5: Pipeline Definition
+
+Sort roles into execution stages by weight, then build dependency chain.
+
+#### Stage Weight Table
+
+| Role | Weight | Stage Position |
+|------|--------|----------------|
+| analyst, debugger, security | 1 | Analysis/Exploration |
+| planner | 2 | Planning |
+| executor, writer | 3 | Implementation |
+| tester, reviewer | 4 | Validation/Review |
+
+**Pipeline construction flow**:
+
+1. Group worker roles by weight
+2. Sort groups by weight ascending (1 → 2 → 3 → 4)
+3. Within same weight → parallel (same stage)
+4. Each stage `blockedBy` all roles in previous stage
+5. Generate diagram: `Requirements → [Stage1] → [Stage2] → ... → Report`
+
+### Step 6: Generate Configuration
+
+Assemble all collected data into `team-config.json`.
+
+#### Config Schema
+
+| Field | Source | Example |
+|-------|--------|---------|
+| `team_name` | Step 1 | `"lifecycle"` |
+| `team_display_name` | Capitalized team_name | `"Lifecycle"` |
+| `skill_name` | `team-<team_name>` | `"team-lifecycle"` |
+| `skill_path` | `.claude/skills/team-<team_name>/` | |
+| `pipeline_type` | Step 2 tag | `"Standard"` |
+| `pipeline` | Step 5 output | `{ stages: [...], diagram: "..." }` |
+| `roles` | All roles with full metadata | Array |
+| `worker_roles` | Roles excluding coordinator | Array |
+| `all_roles_tools_union` | Union of all roles' allowed_tools | Comma-separated string |
+| `role_list` | All role names | Comma-separated string |
+
+```
+Write("<work-dir>/team-config.json", <config-json>)
+```
+
+## Output
+
+| Item | Value |
+|------|-------|
+| File | `team-config.json` |
+| Format | JSON |
+| Location | `<work-dir>/team-config.json` |
+
+## Quality Checklist
+
+- [ ] Team name is lowercase, valid as folder/skill name
+- [ ] Coordinator always included
+- [ ] At least 2 worker roles defined
+- [ ] Task prefixes are UPPERCASE and unique across roles
+- [ ] Pipeline stages reference valid roles
+- [ ] All roles have message types defined
+- [ ] Allowed tools include minimum set per responsibility type
+
+## Next Phase
+
+-> [Phase 2: Pattern Analysis](02-pattern-analysis.md)
--- a/.claude/skills_lib/team-skill-designer-v2/phases/02-pattern-analysis.md
+++ b/.claude/skills_lib/team-skill-designer-v2/phases/02-pattern-analysis.md
@@ -0,0 +1,180 @@
+# Phase 2: Pattern Analysis
+
+Analyze applicable patterns for each role in the team.
+
+## Objective
+
+- Per-role: find most similar existing command reference
+- Per-role: select infrastructure + collaboration patterns
+- Per-role: map 5-phase structure to role responsibilities
+- Generate `pattern-analysis.json`
+
+## Input
+
+| Source | Description |
+|--------|-------------|
+| `team-config.json` | Phase 1 output |
+| `specs/team-design-patterns.md` | Infrastructure patterns (read in Phase 0) |
+| `specs/collaboration-patterns.md` | Collaboration patterns (read in Phase 0) |
+
+## Execution Steps
+
+### Step 1: Load Configuration
+
+```
+Read("<work-dir>/team-config.json")
+```
+
+### Step 2: Per-Role Similarity Mapping
+
+For each worker role, find the most similar existing command based on responsibility type.
+
+#### Similarity Mapping Table
+
+| Responsibility Type | Primary Reference | Secondary Reference | Reason |
+|---------------------|-------------------|---------------------|--------|
+| Read-only analysis | review | plan | Both analyze code and report findings with severity classification |
+| Code generation | execute | test | Both write/modify code and self-validate |
+| Orchestration | plan | coordinate | Both coordinate sub-tasks and produce structured output |
+| Validation | test | review | Both validate quality with structured criteria |
+
+For each worker role:
+1. Look up responsibility type in table above
+2. Record `similar_to.primary` and `similar_to.secondary`
+3. Set `reference_command` = `.claude/commands/team/<primary>.md`
+
+### Step 3: Per-Role Phase Mapping
+
+Map the generic 5-phase structure to role-specific phase names.
+
+#### Phase Structure Mapping Table
+
+| Responsibility Type | Phase 2 | Phase 3 | Phase 4 |
+|---------------------|---------|---------|---------|
+| Read-only analysis | Context Loading | Analysis Execution | Finding Summary |
+| Code generation | Task & Plan Loading | Code Implementation | Self-Validation |
+| Orchestration | Context & Complexity Assessment | Orchestrated Execution | Result Aggregation |
+| Validation | Environment Detection | Execution & Fix Cycle | Result Analysis |
+
+> Phase 1 is always "Task Discovery" and Phase 5 is always "Report to Coordinator" for all roles.
+
+### Step 4: Per-Role Infrastructure Patterns
+
+#### Core Patterns (mandatory for all roles)
+
+| Pattern | Name |
+|---------|------|
+| pattern-1 | Message Bus |
+| pattern-2 | YAML Front Matter (adapted: no YAML in skill role files) |
+| pattern-3 | Task Lifecycle |
+| pattern-4 | Five Phase |
+| pattern-6 | Coordinator Spawn |
+| pattern-7 | Error Handling |
+
+#### Conditional Pattern Selection Table
+
+| Condition | Add Pattern |
+|-----------|-------------|
+| Role has `adaptive_routing = true` | pattern-5 (Complexity Adaptive) |
+| Responsibility type is Code generation or Orchestration | pattern-8 (Session Files) |
+
+#### Pattern 9 Selection
+
+| Condition | Uses Pattern 9 |
+|-----------|----------------|
+| Role has subagents defined (length > 0) | Yes |
+| Role has CLI tools defined (length > 0) | Yes |
+| Neither | No |
+
+### Step 5: Command-to-Phase Mapping
+
+For each worker role, map commands to phases and determine extraction reasons.
+
+**Per-command extraction reasons**:
+
+| Condition | Extraction Reason |
+|-----------|-------------------|
+| Role has subagents | `subagent-delegation` |
+| Role has CLI tools | `cli-fan-out` |
+| Role has adaptive routing | `complexity-adaptive` |
+
+Record `phase_commands` mapping (from config): which command runs in which phase.
+
+### Step 6: Collaboration Pattern Selection
+
+Select team-level collaboration patterns based on team composition.
+
+#### Collaboration Pattern Selection Decision Table
+
+| Condition | Pattern | Name |
+|-----------|---------|------|
+| Always | CP-1 | Linear Pipeline (base) |
+| Any role has Validation or Read-only analysis type | CP-2 | Review-Fix Cycle |
+| Any role has Orchestration type | CP-3 | Fan-out/Fan-in |
+| Worker roles >= 4 | CP-6 | Incremental Delivery |
+| Always | CP-5 | Escalation Chain |
+| Always | CP-10 | Post-Mortem |
+
+#### Convergence Defaults Table
+
+| Pattern | Max Iterations | Success Gate |
+|---------|----------------|--------------|
+| CP-1 | 1 | all_stages_completed |
+| CP-2 | 5 | verdict_approve_or_conditional |
+| CP-3 | 1 | quorum_100_percent |
+| CP-5 | null | issue_resolved_at_any_level |
+| CP-6 | 3 | all_increments_validated |
+| CP-10 | 1 | report_generated |
+
+### Step 7: Read Reference Commands
+
+For each unique `similar_to.primary` across all roles:
+
+```
+Read(".claude/commands/team/<primary-ref>.md")
+```
+
+Store content for Phase 3 reference. Skip silently if file not found.
+
+### Step 8: Generate Analysis Document
+
+Assemble all analysis results into `pattern-analysis.json`.
+
+#### Output Schema
+
+| Field | Source |
+|-------|--------|
+| `team_name` | config |
+| `role_count` / `worker_count` | config |
+| `role_analysis[]` | Steps 2-5 (per-role: similarity, phases, patterns, commands) |
+| `collaboration_patterns[]` | Step 6 |
+| `convergence_config[]` | Step 6 |
+| `referenced_commands[]` | Step 7 |
+| `pipeline` | config |
+| `skill_patterns` | Fixed: role_router, shared_infrastructure, progressive_loading |
+| `command_architecture` | Per-role command mapping + pattern-9 flag |
+
+```
+Write("<work-dir>/pattern-analysis.json", <analysis-json>)
+```
+
+## Output
+
+| Item | Value |
+|------|-------|
+| File | `pattern-analysis.json` |
+| Format | JSON |
+| Location | `<work-dir>/pattern-analysis.json` |
+
+## Quality Checklist
+
+- [ ] Every worker role has similarity mapping
+- [ ] Every worker role has 5-phase structure
+- [ ] Infrastructure patterns include all mandatory patterns
+- [ ] Collaboration patterns selected at team level
+- [ ] Referenced commands are readable
+- [ ] Skill-specific patterns documented
+
+## Next Phase
+
+-> [Phase 3: Skill Package Generation](03-skill-generation.md)
--- a/.claude/skills_lib/team-skill-designer-v2/phases/03-skill-generation.md
+++ b/.claude/skills_lib/team-skill-designer-v2/phases/03-skill-generation.md
@@ -0,0 +1,239 @@
+# Phase 3: Skill Package Generation
+
+> **COMPACT PROTECTION**: This is the core generation phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not generate from memory.
+
+Generate the unified team skill package: SKILL.md (role router) + per-role `role.md` + per-role `commands/*.md`.
+
+## Objective
+
+- Generate `SKILL.md` with role router and shared infrastructure
+- Generate `roles/coordinator/role.md` + `commands/`
+- Generate `roles/<worker>/role.md` + `commands/` for each worker role
+- Generate `specs/team-config.json`
+- All files written to `preview/` directory first
+
+## Input
+
+| Source | Description |
+|--------|-------------|
+| `team-config.json` | Phase 1 output (roles, pipeline, capabilities) |
+| `pattern-analysis.json` | Phase 2 output (patterns, phase mapping, similarity) |
+| `templates/skill-router-template.md` | SKILL.md generation template |
+| `templates/role-template.md` | role.md generation template |
+| `templates/role-command-template.md` | command file generation template |
+
+## Execution Steps
+
+### Step 1: Load Inputs + Create Preview Directory
+
+1. Read `<work-dir>/team-config.json` and `<work-dir>/pattern-analysis.json`
+2. Read all 3 template files from `templates/`
+3. Create directory structure:
+
+```
+Bash("mkdir -p <preview-dir>/roles/<role-name>/commands <preview-dir>/specs")
+```
+
+Repeat for every role in config.
+
+### Step 2: Generate SKILL.md (Role Router)
+
+Use `templates/skill-router-template.md` as the base. Fill the template using config values.
+
+#### Template Variable Mapping
+
+| Template Variable | Config Source |
+|-------------------|--------------|
+| `<skill-name>` | `config.skill_name` |
+| `<team-name>` | `config.team_name` |
+| `<team-display-name>` | `config.team_display_name` |
+| `<all-tools-union>` | `config.all_roles_tools_union` |
+| `<roles-table>` | Generated from `config.roles[]` (see Roles Table below) |
+| `<role-dispatch-entries>` | Per-role: `"<name>": { file, prefix }` |
+| `<message-bus-table>` | Per worker role: name + message types |
+| `<spawn-blocks>` | Per worker role: Task() spawn block |
+| `<pipeline-diagram>` | `config.pipeline.diagram` |
+| `<architecture-diagram>` | Generated from role names |
+
+#### Roles Table Generation
+
+For each role in `config.roles[]`, produce one row:
+
+```
+| <role-name> | <task-prefix> | <description> | [roles/<name>/role.md](roles/<name>/role.md) |
+```
+
+#### Spawn Block Generation
+
+For each worker role, generate a `Task()` spawn block containing:
+- `subagent_type: "general-purpose"`
+- `team_name: <team-name>`
+- `name: "<role-name>"`
+- Prompt with: primary directive (MUST call Skill), role constraints, message bus requirement, workflow steps
+
+**Spawn prompt must include**:
+1. Primary directive: `Skill(skill="<skill-name>", args="--role=<role-name>")`
+2. Task prefix constraint: only handle `<PREFIX>-*` tasks
+3. Output tag: all messages tagged `[<role-name>]`
+4. Communication rule: only talk to coordinator
+5. Message bus: call `team_msg` before every `SendMessage`
+
+```
+Write("<preview-dir>/SKILL.md", <generated-skill-md>)
+```
+
+### Step 3: Generate Coordinator Role File
+
+Build coordinator `role.md` with these sections:
+
+| Section | Content Source |
+|---------|---------------|
+| Role Identity | Fixed: name=coordinator, prefix=N/A, type=Orchestration |
+| Message Types | Fixed 5 types: plan_approved, plan_revision, task_unblocked, shutdown, error |
+| Execution Phase 1 | Requirement clarification via AskUserQuestion |
+| Execution Phase 2 | TeamCreate + spawn blocks (same as SKILL.md Step 2) |
+| Execution Phase 3 | Task chain creation from `config.pipeline.stages` |
+| Execution Phase 4 | Message-driven coordination loop |
+| Execution Phase 5 | Report + next steps (new requirement or shutdown) |
+| Error Handling | Fixed table: unresponsive, rejected plan, stuck tests, critical review |
+
+#### Task Chain Generation
+
+For each stage in `config.pipeline.stages[]`:
+1. Create task: `TaskCreate({ subject: "<PREFIX>-001: <role> work" })`
+2. Set owner: `TaskUpdate({ owner: "<role-name>" })`
+3. Set dependencies: `addBlockedBy` = all prefixes from the previous stage
+
+#### Coordination Handler Table
+
+For each worker role, generate one row:
+
+```
+| <ROLE-UPPER>: <trigger> | team_msg log -> TaskUpdate <PREFIX> completed -> check next |
+```
+
+```
+Write("<preview-dir>/roles/coordinator/role.md", <coordinator-md>)
+```
+
+Generate coordinator command files (dispatch.md, monitor.md) using `templates/role-command-template.md`.
+
+### Step 4: Generate Worker Role Files
+
+**For each worker role**, generate `role.md` using `templates/role-template.md`.
+
+#### Per-Role Template Variable Mapping
+
+| Template Variable | Source |
+|-------------------|--------|
+| `<role-name>` | `role.name` |
+| `<task-prefix>` | `role.task_prefix` |
+| `<responsibility-type>` | `role.responsibility_type` |
+| `<description>` | `role.description` |
+| `<message-types-table>` | From `role.message_types[]` |
+| `<primary-msg-type>` | First non-error, non-progress message type |
+| `<phase-2-name>` | From `pattern-analysis.phase_structure.phase2` |
+| `<phase-3-name>` | From `pattern-analysis.phase_structure.phase3` |
+| `<phase-4-name>` | From `pattern-analysis.phase_structure.phase4` |
+| `<commands-table>` | From `role.commands[]` with phase mapping |
+| `<subagents-table>` | From `role.subagents[]` |
+| `<cli-tools-table>` | From `role.cli_tools[]` |
+
+#### Role File Sections (v3 style)
+
+Each generated `role.md` must contain:
+
+1. **Role Identity**: name, prefix, output tag, responsibility, communication rule
+2. **Role Boundaries**: MUST / MUST NOT lists
+3. **Message Types**: table with type, direction, trigger
+4. **Message Bus**: `team_msg` call pattern + CLI fallback
+5. **Toolbox**: commands table, subagents table, CLI tools table
+6. **Execution (5-Phase)**:
+   - Phase 1: Task Discovery (TaskList -> filter by prefix -> TaskGet -> TaskUpdate in_progress)
+   - Phase 2-4: Content varies by responsibility type (see Phase Content Table below)
+   - Phase 5: Report to Coordinator (team_msg + SendMessage + TaskUpdate completed + check next)
+7. **Error Handling**: table with scenario/resolution
+
+#### Phase Content by Responsibility Type
+
+| Type | Phase 2 | Phase 3 | Phase 4 |
+|------|---------|---------|---------|
+| Read-only analysis | Load plan + get changed files + read contents | Domain-specific analysis per file | Classify findings by severity |
+| Code generation | Extract plan path + load plan tasks | Implement tasks (adaptive: direct edit or delegate to code-developer) | Self-validation (syntax check + auto-fix) |
+| Orchestration | Assess complexity (Low/Medium/High) | Execute (adaptive: direct search or delegate to sub-agent) | Aggregate results |
+| Validation | Detect changed files for scope | Iterative test-fix cycle (max 5 iterations) | Analyze results (iterations, pass rate) |
+
+```
+Write("<preview-dir>/roles/<role-name>/role.md", <role-md>)
+```
+
+### Step 5: Generate Command Files
+
+#### Command Extraction Decision Table
+
+| Condition | Extract to command file? |
+|-----------|--------------------------|
+| Role has subagents (delegation needed) | Yes |
+| Role has CLI tools (fan-out needed) | Yes |
+| Role has adaptive routing (complexity branching) | Yes |
+| None of the above | No (all phases execute inline in role.md) |
+
+For each role that needs command files, generate from `templates/role-command-template.md`.
+
+#### Pre-built Command Patterns
+
+| Command | Description | Delegation Mode | Used By Phase |
+|---------|-------------|-----------------|---------------|
+| explore | Multi-angle codebase exploration | Subagent Fan-out | Phase 2 |
+| analyze | Multi-perspective code analysis | CLI Fan-out | Phase 3 |
+| implement | Code implementation via delegation | Sequential Delegation | Phase 3 |
+| validate | Iterative test-fix cycle | Sequential Delegation | Phase 3 |
+| review | 4-dimensional code review | CLI Fan-out | Phase 3 |
+| dispatch | Task chain creation (coordinator) | Direct | Phase 3 |
+| monitor | Message-driven coordination (coordinator) | Message-Driven | Phase 4 |
+
+If command name not in pre-built list, generate a skeleton with TODO placeholders.
+
+```
+Write("<preview-dir>/roles/<role-name>/commands/<cmd>.md", <cmd-content>)
+```
+
+### Step 6: Copy Team Config
+
+```
+Write("<preview-dir>/specs/team-config.json", <config-json>)
+```
+
+### Step 7: Preview Checkpoint
+
+**PAUSE**: Present the generated preview structure to the user for confirmation before proceeding to Phase 4.
+
+Display:
+- File tree of `<preview-dir>/`
+- Role count and names
+- Pipeline diagram
+- Total file count
+
+Wait for user confirmation before advancing.
+
+## Output
+
+| Item | Value |
+|------|-------|
+| Directory | `<work-dir>/preview/` |
+| Files | SKILL.md + roles/*/role.md + roles/*/commands/*.md + specs/team-config.json |
+
+## Quality Checklist
+
+- [ ] SKILL.md has frontmatter, architecture diagram, role router, role dispatch, shared infrastructure
+- [ ] Every role has `role.md` with all 7 required sections
+- [ ] Coordinator has dispatch.md and monitor.md command files
+- [ ] Worker roles with delegation have command files
+- [ ] All generated files use v3 style: text + decision tables + flow symbols, no pseudocode
+- [ ] Spawn blocks include complete prompt with primary directive + constraints
+- [ ] All `<placeholder>` variables resolved (no `${variable}` syntax in output)
+- [ ] Pipeline diagram matches actual role stages
+
+## Next Phase
+
+-> [Phase 4: Integration Verification](04-integration-verification.md)
--- a/.claude/skills_lib/team-skill-designer-v2/phases/04-integration-verification.md
+++ b/.claude/skills_lib/team-skill-designer-v2/phases/04-integration-verification.md
@@ -0,0 +1,183 @@
+# Phase 4: Integration Verification
+
+Verify the generated skill package is internally consistent.
+
+## Objective
+
+- Verify SKILL.md role router references match actual role files
+- Verify task prefixes are unique across all roles
+- Verify message types are consistent between config and generated files
+- Verify coordinator spawn template uses correct skill invocation
+- Verify role file structural compliance
+- Verify coordinator commands alignment
+- Generate `integration-report.json`
+
+## Input
+
+| Source | Description |
+|--------|-------------|
+| `<work-dir>/preview/` | Phase 3 generated skill package |
+| `team-config.json` | Phase 1 configuration |
+
+## Execution Steps
+
+### Step 1: Load Generated Files
+
+1. Read `<work-dir>/team-config.json`
+2. Read `<preview-dir>/SKILL.md`
+3. Read each `<preview-dir>/roles/<role-name>/role.md`
+4. Read each `<preview-dir>/roles/<role-name>/commands/*.md`
+
+### Step 2: Run 6 Integration Checks
+
+#### Check 1: Router Consistency
+
+For each role in config, verify 3 conditions in SKILL.md:
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Router entry | SKILL.md contains `"<role-name>"` | Found |
+| Role file exists | `roles/<role-name>/role.md` is readable | File exists |
+| Role link valid | SKILL.md contains `roles/<role-name>/role.md` | Found |
+
+**Status**: PASS if all 3 conditions met for every role, FAIL otherwise.
+
+#### Check 2: Prefix Uniqueness
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| All task prefixes | Collect `task_prefix` from each worker role | No duplicates |
+
+**Status**: PASS if all prefixes unique, FAIL if any duplicate found.
+
+#### Check 3: Message Type Consistency
+
+For each worker role:
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Config message types | List types from `role.message_types[]` | Baseline |
+| Types in role file | Search role.md for each type string | All present |
+
+**Status**: PASS if all configured types found in role file, WARN if any missing.
+
+#### Check 4: Spawn Template Verification
+
+For each worker role, verify in SKILL.md:
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Spawn present | SKILL.md contains `name: "<role-name>"` | Found |
+| Skill call correct | Contains `Skill(skill="<skill-name>", args="--role=<role-name>")` | Found |
+| Prefix in prompt | Contains `<PREFIX>-*` | Found |
+
+**Status**: PASS if all 3 conditions met, FAIL otherwise.
+
+#### Check 5: Role File Pattern Compliance
+
+For each role file, check structural elements:
+
+| Item | Search Pattern | Required |
+|------|---------------|----------|
+| Role Identity section | `## Role Identity` | Yes |
+| 5-Phase structure | `Phase 1` and `Phase 5` both present | Yes |
+| Task lifecycle | `TaskList`, `TaskGet`, `TaskUpdate` all present | Yes |
+| Message bus | `team_msg` present | Yes |
+| SendMessage | `SendMessage` present | Yes |
+| Error Handling | `## Error Handling` | Yes |
+
+**Status**: PASS if all 6 items found, PARTIAL if some missing, MISSING if file not found.
+
+#### Check 5b: Command File Verification
+
+For each role's command files:
+
+| Item | Search Pattern | Required |
+|------|---------------|----------|
+| Strategy section | `## Strategy` | Yes |
+| Execution Steps | `## Execution Steps` | Yes |
+| Error Handling | `## Error Handling` | Yes |
+| When to Use | `## When to Use` | Yes |
+| Self-contained | No `Read("../` cross-command references | Yes |
+
+**Status**: PASS if all items found, PARTIAL if some missing, MISSING if file not found.
+
+#### Check 6: Coordinator Commands Alignment
+
+> **Critical**: dispatch.md and monitor.md are the most common source of integration failures.
+
+**6a: dispatch.md role names**
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Owner values | Extract all `owner: "<name>"` from dispatch.md | Every name exists in config roles |
+| No ghost roles | Compare dispatch roles vs config roles | No invalid role names |
+
+**6b: monitor.md spawn completeness**
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Has `description:` | Search for `description:` | Found |
+| Has `team_name:` | Search for `team_name:` | Found |
+| Has `name:` param | Search for `name:` | Found |
+| Has Skill callback | Search for `Skill(skill=` | Found |
+| Has role boundaries | Search for role constraint / MUST keywords | Found |
+| Not minimal prompt | No `prompt: \`Execute task` anti-pattern | Confirmed |
+
+**6c: Pipeline alignment**
+
+| Item | Method | Pass Criteria |
+|------|--------|---------------|
+| Pipeline task IDs | From `config.pipeline_tasks` (if defined) | Baseline |
+| Dispatch task IDs | Extract `subject: "<id>"` from dispatch.md | Match pipeline |
+
+**Status**: PASS if no mismatches, WARN if pipeline_tasks not defined, FAIL if mismatches found.
+
+### Step 3: Generate Report
+
+Compute overall status: PASS if all checks pass (excluding SKIP), NEEDS_ATTENTION otherwise.
+
+#### Report Schema
+
+| Field | Content |
+|-------|---------|
+| `team_name` | Config team name |
+| `skill_name` | Config skill name |
+| `checks.router_consistency` | Check 1 results per role |
+| `checks.prefix_uniqueness` | Check 2 result |
+| `checks.message_types` | Check 3 results per role |
+| `checks.spawn_template` | Check 4 results per role |
+| `checks.pattern_compliance` | Check 5 results per role |
+| `checks.command_files` | Check 5b results per role |
+| `checks.coordinator_commands` | Check 6a/6b/6c results |
+| `overall` | PASS or NEEDS_ATTENTION |
+| `file_count` | skill_md: 1, role_files: N, total: N+2 |
+
+```
+Write("<work-dir>/integration-report.json", <report-json>)
+```
+
+## Output
+
+| Item | Value |
+|------|-------|
+| File | `integration-report.json` |
+| Format | JSON |
+| Location | `<work-dir>/integration-report.json` |
+
+## Quality Checklist
+
+- [ ] Every role in config has a router entry in SKILL.md
+- [ ] Every role has a file in `roles/`
+- [ ] Task prefixes are unique
+- [ ] Spawn template uses correct `Skill(skill="...", args="--role=...")`
+- [ ] Spawn template includes `description`, `team_name`, `name` parameters
+- [ ] All role files have 5-phase structure
+- [ ] All role files have message bus integration
+- [ ] dispatch.md `owner` values all exist in config roles (no ghost roles)
+- [ ] monitor.md spawn prompt contains full Skill callback (not minimal)
+- [ ] Task IDs in dispatch.md match pipeline diagram in SKILL.md
+
+## Next Phase
+
+-> [Phase 5: Validation](05-validation.md)
--- a/.claude/skills_lib/team-skill-designer-v2/phases/05-validation.md
+++ b/.claude/skills_lib/team-skill-designer-v2/phases/05-validation.md
@@ -0,0 +1,209 @@
+# Phase 5: Validation
+
+Verify quality and deliver the final skill package.
+
+## Objective
+
+- SKILL.md structural completeness check
+- Per-role structural completeness check
+- Per-role command file quality check
+- Quality scoring across 5 dimensions
+- Deliver final skill package to `.claude/skills/team-<name>/`
+
+## Input
+
+| Source | Description |
+|--------|-------------|
+| `<work-dir>/preview/` | Phase 3 generated skill package |
+| `integration-report.json` | Phase 4 integration check results |
+| `specs/quality-standards.md` | Quality criteria (read in Phase 0) |
+
+## Execution Steps
+
+### Step 1: Load Files
+
+1. Read `<work-dir>/team-config.json`
+2. Read `<work-dir>/integration-report.json`
+3. Read `<preview-dir>/SKILL.md`
+4. Read each `<preview-dir>/roles/<role-name>/role.md`
+5. Read each `<preview-dir>/roles/<role-name>/commands/*.md`
+
+### Step 2: SKILL.md Structural Check
+
+#### SKILL.md Structure Checklist
+
+| # | Check Item | Search For |
+|---|------------|------------|
+| 1 | Frontmatter | `---` block at file start |
+| 2 | Architecture Overview | `## Architecture Overview` |
+| 3 | Role Router | `## Role Router` |
+| 4 | Role Dispatch Code | `VALID_ROLES` |
+| 5 | Orchestration Mode | `Orchestration Mode` |
+| 6 | Available Roles Table | `| Role | Task Prefix` |
+| 7 | Shared Infrastructure | `## Shared Infrastructure` |
+| 8 | Role Isolation Rules | `Role Isolation` |
+| 9 | Pipeline Diagram | `## Pipeline` |
+| 10 | Coordinator Spawn Template | `Coordinator Spawn` |
+| 11 | Spawn Skill Directive | `MUST` + primary directive |
+| 12 | Spawn Description Param | `description:` in spawn block |
+| 13 | Error Handling | `## Error Handling` |
+
+**SKILL.md score** = (passed items / 13) * 100
+
+### Step 3: Per-Role Structural Check
+
+#### Role Structure Checklist
+
+| # | Check Item | Search For |
+|---|------------|------------|
+| 1 | Role Identity | `## Role Identity` |
+| 2 | Role Boundaries | `## Role Boundaries` |
+| 3 | Output Tag | `Output Tag` |
+| 4 | Message Types Table | `## Message Types` |
+| 5 | Message Bus | `## Message Bus` |
+| 6 | CLI Fallback | `CLI` fallback section |
+| 7 | Toolbox Section | `## Toolbox` |
+| 8 | 5-Phase Execution | `## Execution` |
+| 9 | Phase 1 Task Discovery | `Phase 1` + `Task Discovery` |
+| 10 | TaskList Usage | `TaskList` |
+| 11 | TaskGet Usage | `TaskGet` |
+| 12 | TaskUpdate Usage | `TaskUpdate` |
+| 13 | team_msg Before SendMessage | `team_msg` |
+| 14 | SendMessage to Coordinator | `SendMessage` |
+| 15 | Error Handling | `## Error Handling` |
+
+**Per-role score** = (passed items / 15) * 100
+
+| Score | Status |
+|-------|--------|
+| >= 80% | PASS |
+| < 80% | PARTIAL |
+| File missing | MISSING (score = 0) |
+
+### Step 3b: Command File Quality Check
+
+For each role's command files:
+
+#### Command Quality Checklist
+
+| # | Check Item | Search For |
+|---|------------|------------|
+| 1 | When to Use section | `## When to Use` |
+| 2 | Strategy section | `## Strategy` |
+| 3 | Delegation mode declared | `Delegation Mode` |
+| 4 | Execution Steps section | `## Execution Steps` |
+| 5 | Error Handling section | `## Error Handling` |
+| 6 | Output Format section | `## Output Format` |
+| 7 | Self-contained (no cross-ref) | No `Read("../` patterns |
+
+**Per-command score** = (passed items / 7) * 100. Role command score = average of all commands.
+
+### Step 4: Quality Scoring
+
+#### Quality Scoring Table
+
+| Dimension | Weight | Source | Calculation |
+|-----------|--------|--------|-------------|
+| `skill_md` | Equal | Step 2 | SKILL.md checklist score |
+| `roles_avg` | Equal | Step 3 | Average of all role scores |
+| `integration` | Equal | Phase 4 report | PASS=100, otherwise=50 |
+| `consistency` | Equal | Cross-check | Start at 100, -20 per mismatch (see below) |
+| `command_quality` | Equal | Step 3b | Average of all command scores |
+
+**Consistency deductions**:
+
+| Mismatch | Deduction |
+|----------|-----------|
+| Skill name not in SKILL.md | -20 |
+| Team name not in SKILL.md | -20 |
+| Any role name not in SKILL.md | -10 per role |
+
+**Overall score** = average of all 5 dimension scores.
+
+#### Delivery Decision Table
+
+| Score Range | Gate | Action |
+|-------------|------|--------|
+| >= 80% | PASS | Deliver to `.claude/skills/team-<name>/` |
+| 60-79% | REVIEW | Deliver with warnings, suggest fixes |
+| < 60% | FAIL | Do not deliver, return to Phase 3 for rework |
+
+### Step 5: Generate Validation Report
+
+#### Report Schema
+
+| Field | Content |
+|-------|---------|
+| `team_name` | Config team name |
+| `skill_name` | Config skill name |
+| `timestamp` | ISO timestamp |
+| `scores` | All 5 dimension scores |
+| `overall_score` | Average score |
+| `quality_gate` | PASS / REVIEW / FAIL |
+| `skill_md_checks` | Step 2 results |
+| `role_results` | Step 3 results per role |
+| `integration_status` | Phase 4 overall status |
+| `delivery.source` | Preview directory |
+| `delivery.destination` | `.claude/skills/<skill-name>/` |
+| `delivery.ready` | true if gate is not FAIL |
+
+```
+Write("<work-dir>/validation-report.json", <report-json>)
+```
+
+### Step 6: Deliver Final Package
+
+**Only execute if `quality_gate` is not FAIL.**
+
+1. Create destination directory structure:
+
+```
+Bash("mkdir -p .claude/skills/<skill-name>/roles/<role-name>/commands .claude/skills/<skill-name>/specs")
+```
+
+2. Copy files from preview to destination:
+
+| Source | Destination |
+|--------|-------------|
+| `<preview-dir>/SKILL.md` | `.claude/skills/<skill-name>/SKILL.md` |
+| `<preview-dir>/roles/<name>/role.md` | `.claude/skills/<skill-name>/roles/<name>/role.md` |
+| `<preview-dir>/roles/<name>/commands/*.md` | `.claude/skills/<skill-name>/roles/<name>/commands/*.md` |
+| `<preview-dir>/specs/team-config.json` | `.claude/skills/<skill-name>/specs/team-config.json` |
+
+3. Report delivery summary:
+   - Destination path
+   - Skill name
+   - Quality score and gate
+   - Role list
+   - Usage examples: `Skill(skill="<skill-name>", args="--role=<role-name>")`
+
+4. List delivered files:
+
+```
+Bash("find .claude/skills/<skill-name> -type f | sort")
+```
+
+**If gate is FAIL**: Report failure with score, suggest returning to Phase 3 for rework.
+
+## Output
+
+| Item | Value |
+|------|-------|
+| File | `validation-report.json` |
+| Format | JSON |
+| Location | `<work-dir>/validation-report.json` |
+| Delivery | `.claude/skills/team-<name>/` (if gate passes) |
+
+## Quality Checklist
+
+- [ ] SKILL.md passes all 13 routing-level structural checks
+- [ ] All role files pass structural checks (>= 80%)
+- [ ] All command files pass quality checks (>= 80%)
+- [ ] Integration report is PASS
+- [ ] Overall score >= 80%
+- [ ] Final package delivered to `.claude/skills/team-<name>/`
+- [ ] Usage instructions provided to user
+
+## Completion
+
+This is the final phase. The unified team skill is ready for use.