Skip to content

Commit a512564

Browse files
author
catlog22
committed
Add integration verification and validation phases, role templates, and static graph tests
- Implement Phase 4: Integration Verification to ensure skill package consistency. - Implement Phase 5: Validation to verify quality and deliver the final skill package. - Create role-template.md for generating per-role execution detail files. - Create skill-router-template.md for generating SKILL.md with role-based routing. - Add tests for static graph relationship writing during index build in test_static_graph_integration.py.
1 parent 6054a01 commit a512564

14 files changed

Lines changed: 2897 additions & 51 deletions

File tree

‎.claude/skills/team-command-designer/specs/team-design-patterns.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -452,6 +452,7 @@ When designing a new team command, verify:
452452
### Infrastructure Patterns
453453
- [ ] YAML front matter with `group: team`
454454
- [ ] Message bus section with `team_msg` logging
455+
- [ ] CLI fallback section with `ccw team` CLI examples and parameter mapping
455456
- [ ] Role-specific message types defined
456457
- [ ] Task lifecycle: TaskList -> TaskGet -> TaskUpdate flow
457458
- [ ] Unique task prefix (no collision with existing PLAN/IMPL/TEST/REVIEW, scan `team/**/*.md`)

‎.claude/skills/team-skill-designer/SKILL.md‎

Lines changed: 285 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,285 @@
1+
---
2+
name: team-skill-designer
3+
description: Design and generate unified team skills with role-based routing. All team members invoke ONE skill, SKILL.md routes to role-specific execution via --role arg. Triggers on "design team skill", "create team skill", "team skill designer".
4+
allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep
5+
---
6+
7+
# Team Skill Designer
8+
9+
Meta-skill for creating unified team skills where all team members invoke ONE skill with role-based routing. Generates a complete skill package with SKILL.md as role router and `roles/` folder for per-role execution detail.
10+
11+
## Architecture Overview
12+
13+
```
14+
┌─────────────────────────────────────────────────────────────────┐
15+
│ Team Skill Designer (this meta-skill) │
16+
│ → Collect requirements → Analyze patterns → Generate skill pkg │
17+
└───────────────┬─────────────────────────────────────────────────┘
18+
│
19+
┌───────────┼───────────┬───────────┬───────────┐
20+
↓ ↓ ↓ ↓ ↓
21+
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
22+
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │ │ Phase 5 │
23+
│ Require │ │ Pattern │ │ Skill │ │ Integ │ │ Valid │
24+
│ Collect │ │ Analyze │ │ Gen │ │ Verify │ │ │
25+
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
26+
↓ ↓ ↓ ↓ ↓
27+
team- patterns SKILL.md + report validated
28+
config.json .json roles/*.md .json skill pkg
29+
```
30+
31+
## Key Innovation: Unified Skill + Role Router
32+
33+
**Before (command approach)**:
34+
```
35+
.claude/commands/team/
36+
├── coordinate.md → /team:coordinate
37+
├── plan.md → /team:plan
38+
├── execute.md → /team:execute
39+
├── test.md → /team:test
40+
└── review.md → /team:review
41+
```
42+
→ 5 separate command files, 5 separate skill paths
43+
44+
**After (unified skill approach)**:
45+
```
46+
.claude/skills/team-{name}/
47+
├── SKILL.md → Skill(skill="team-{name}", args="--role=xxx")
48+
├── roles/
49+
│ ├── coordinator.md
50+
│ ├── planner.md
51+
│ ├── executor.md
52+
│ ├── tester.md
53+
│ └── reviewer.md
54+
└── specs/
55+
└── team-config.json
56+
```
57+
→ 1 skill entry point, --role arg routes to per-role execution
58+
59+
**Coordinator spawns teammates with**:
60+
```javascript
61+
Task({
62+
prompt: `...调用 Skill(skill="team-{name}", args="--role=planner") 执行规划...`
63+
})
64+
```
65+
66+
## Target Output Structure
67+
68+
```
69+
.claude/skills/team-{name}/
70+
├── SKILL.md # Role router + shared infrastructure
71+
│ ├─ Frontmatter
72+
│ ├─ Architecture Overview (role routing diagram)
73+
│ ├─ Role Router (parse --role → Read roles/{role}.md → execute)
74+
│ ├─ Shared Infrastructure (message bus, task lifecycle)
75+
│ ├─ Coordinator Spawn Template
76+
│ └─ Error Handling
77+
├── roles/ # Role-specific execution detail
78+
│ ├── coordinator.md # Orchestration logic
79+
│ ├── {role-1}.md # First worker role
80+
│ ├── {role-2}.md # Second worker role
81+
│ └── ...
82+
└── specs/ # [Optional] Team-specific config
83+
└── team-config.json
84+
```
85+
86+
## Core Design Patterns
87+
88+
### Pattern 1: Role Router (Unified Entry Point)
89+
90+
SKILL.md parses `$ARGUMENTS` to extract `--role`:
91+
```
92+
Input: Skill(skill="team-{name}", args="--role=planner")
93+
↓ Parse --role=planner
94+
↓ Read roles/planner.md
95+
↓ Execute planner-specific 5-phase logic
96+
```
97+
98+
No --role → error (role is required, set by coordinator spawn).
99+
100+
### Pattern 2: Shared Infrastructure in SKILL.md
101+
102+
SKILL.md defines ONCE, all roles inherit:
103+
- Message bus pattern (team_msg + CLI fallback)
104+
- Task lifecycle (TaskList → TaskGet → TaskUpdate)
105+
- Team name and session directory conventions
106+
- Error handling and escalation rules
107+
108+
### Pattern 3: Role Files = Full Execution Detail
109+
110+
Each `roles/{role}.md` contains:
111+
- Role-specific 5-phase implementation
112+
- Per-role message types
113+
- Per-role task prefix
114+
- Complete code (no `Ref:` back to SKILL.md)
115+
116+
### Pattern 4: Batch Role Generation
117+
118+
Phase 1 collects ALL roles at once (not one at a time):
119+
- Team name + all role definitions in one pass
120+
- Coordinator is always generated
121+
- Worker roles collected as a batch
122+
123+
### Pattern 5: Spec Reference (No Duplication)
124+
125+
Design pattern specs are referenced from team-command-designer:
126+
```
127+
specs → ../team-command-designer/specs/team-design-patterns.md
128+
specs → ../team-command-designer/specs/collaboration-patterns.md
129+
specs → ../team-command-designer/specs/quality-standards.md
130+
```
131+
132+
---
133+
134+
## Mandatory Prerequisites
135+
136+
> **Do NOT skip**: Read these before any execution.
137+
138+
### Specification Documents (Required Reading)
139+
140+
| Document | Purpose | When |
141+
|----------|---------|------|
142+
| [../team-command-designer/specs/team-design-patterns.md](../team-command-designer/specs/team-design-patterns.md) | Infrastructure patterns (8) + collaboration index | **Must read** |
143+
| [../team-command-designer/specs/collaboration-patterns.md](../team-command-designer/specs/collaboration-patterns.md) | 10 collaboration patterns with convergence control | **Must read** |
144+
| [../team-command-designer/specs/quality-standards.md](../team-command-designer/specs/quality-standards.md) | Quality criteria | Must read before generation |
145+
146+
### Template Files (Must read before generation)
147+
148+
| Document | Purpose |
149+
|----------|---------|
150+
| [templates/skill-router-template.md](templates/skill-router-template.md) | Generated SKILL.md template with role router |
151+
| [templates/role-template.md](templates/role-template.md) | Generated role file template |
152+
153+
### Existing Reference
154+
155+
| Document | Purpose |
156+
|----------|---------|
157+
| `.claude/commands/team/coordinate.md` | Coordinator spawn patterns |
158+
| `.claude/commands/team/plan.md` | Planner role reference |
159+
| `.claude/commands/team/execute.md` | Executor role reference |
160+
| `.claude/commands/team/test.md` | Tester role reference |
161+
| `.claude/commands/team/review.md` | Reviewer role reference |
162+
163+
---
164+
165+
## Execution Flow
166+
167+
```
168+
Phase 0: Specification Study (MANDATORY)
169+
-> Read: ../team-command-designer/specs/team-design-patterns.md
170+
-> Read: ../team-command-designer/specs/collaboration-patterns.md
171+
-> Read: templates/skill-router-template.md + templates/role-template.md
172+
-> Read: 1-2 existing team commands for reference
173+
-> Output: Internalized requirements (in-memory)
174+
175+
Phase 1: Requirements Collection
176+
-> Ref: phases/01-requirements-collection.md
177+
- Collect team name and ALL role definitions (batch)
178+
- For each role: name, responsibility, task prefix, capabilities
179+
- Pipeline definition (task chain order)
180+
- Output: team-config.json (team-level + per-role config)
181+
182+
Phase 2: Pattern Analysis
183+
-> Ref: phases/02-pattern-analysis.md
184+
- Per-role: find most similar existing command
185+
- Per-role: select infrastructure + collaboration patterns
186+
- Per-role: map 5-phase structure
187+
- Output: pattern-analysis.json
188+
189+
Phase 3: Skill Package Generation
190+
-> Ref: phases/03-skill-generation.md
191+
- Generate SKILL.md (role router + shared infrastructure)
192+
- Generate roles/*.md (per-role execution detail)
193+
- Generate specs/team-config.json
194+
- Output: .claude/skills/team-{name}/ complete package
195+
196+
Phase 4: Integration Verification
197+
-> Ref: phases/04-integration-verification.md
198+
- Verify role router references match role files
199+
- Verify task prefixes are unique across roles
200+
- Verify message type compatibility
201+
- Output: integration-report.json
202+
203+
Phase 5: Validation
204+
-> Ref: phases/05-validation.md
205+
- Structural completeness per role file
206+
- Pattern compliance per role file
207+
- Quality scoring and delivery
208+
- Output: validation-report.json + delivered skill package
209+
```
210+
211+
**Phase Reference Documents** (read on-demand):
212+
213+
| Phase | Document | Purpose |
214+
|-------|----------|---------|
215+
| 1 | [phases/01-requirements-collection.md](phases/01-requirements-collection.md) | Batch collect team + all role definitions |
216+
| 2 | [phases/02-pattern-analysis.md](phases/02-pattern-analysis.md) | Per-role pattern matching and phase mapping |
217+
| 3 | [phases/03-skill-generation.md](phases/03-skill-generation.md) | Generate unified skill package |
218+
| 4 | [phases/04-integration-verification.md](phases/04-integration-verification.md) | Verify internal consistency |
219+
| 5 | [phases/05-validation.md](phases/05-validation.md) | Quality gate and delivery |
220+
221+
## Directory Setup
222+
223+
```javascript
224+
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
225+
const workDir = `.workflow/.scratchpad/team-skill-${timestamp}`;
226+
227+
Bash(`mkdir -p "${workDir}"`);
228+
```
229+
230+
## Output Structure
231+
232+
```
233+
.workflow/.scratchpad/team-skill-{timestamp}/
234+
├── team-config.json # Phase 1 output (team + all roles)
235+
├── pattern-analysis.json # Phase 2 output (per-role patterns)
236+
├── integration-report.json # Phase 4 output
237+
├── validation-report.json # Phase 5 output
238+
└── preview/ # Phase 3 output (preview before delivery)
239+
├── SKILL.md
240+
├── roles/
241+
│ ├── coordinator.md
242+
│ └── {role-N}.md
243+
└── specs/
244+
└── team-config.json
245+
246+
Final delivery:
247+
.claude/skills/team-{name}/
248+
├── SKILL.md
249+
├── roles/
250+
│ ├── coordinator.md
251+
│ └── ...
252+
└── specs/
253+
└── team-config.json
254+
```
255+
256+
## Comparison: Command Designer vs Skill Designer
257+
258+
| Aspect | team-command-designer | team-skill-designer |
259+
|--------|----------------------|---------------------|
260+
| Output | N separate .md command files | 1 skill package (SKILL.md + roles/) |
261+
| Entry point | N skill paths (/team:xxx) | 1 skill path + --role arg |
262+
| Shared infra | Duplicated in each command | Defined once in SKILL.md |
263+
| Role isolation | Complete (separate files) | Complete (roles/ directory) |
264+
| Coordinator spawn | `Skill(skill="team:plan")` | `Skill(skill="team-{name}", args="--role=planner")` |
265+
| Role generation | One role at a time | All roles in batch |
266+
| Template | command-template.md | skill-router-template.md + role-template.md |
267+
268+
## Error Handling
269+
270+
| Scenario | Resolution |
271+
|----------|------------|
272+
| Specs not found | Fall back to inline pattern knowledge |
273+
| Role name conflicts | AskUserQuestion for rename |
274+
| Task prefix conflicts | Suggest alternative prefix |
275+
| Template variable unresolved | FAIL with specific variable name |
276+
| Quality score < 60% | Re-run Phase 3 with additional context |
277+
278+
## Debugging
279+
280+
| Issue | Solution |
281+
|-------|----------|
282+
| Generated SKILL.md missing router | Check templates/skill-router-template.md |
283+
| Role file missing message bus | Check templates/role-template.md |
284+
| Integration check fails | Review phases/04-integration-verification.md |
285+
| Quality score below threshold | Review specs/quality-standards.md |

0 commit comments

Comments
 (0)