Skip to content

Commit cbd1813

Browse files
author
catlog22
committed
feat(team-coordinate): align with team-skill-designer and team-lifecycle-v4 standards
Add quality-gates.md and knowledge-transfer.md specs. Update SKILL.md with Shared Constants, Specs Reference, and new user commands. Enhance coordinator role.md with frontmatter, Message Types, Message Bus Protocol, and Toolbox. Add When to Use + Strategy sections to all command files. Update role-spec-template with Identity/Boundaries blocks and validation checklist.
1 parent b2fc2f6 commit cbd1813

9 files changed

Lines changed: 397 additions & 42 deletions

File tree

‎.claude/skills/team-coordinate/SKILL.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,18 @@ Universal team coordination skill: analyze task -> generate role-specs -> dispat
3232
ccw cli --mode write - code generation and modification
3333
```
3434

35+
## Shared Constants
36+
37+
| Constant | Value |
38+
|----------|-------|
39+
| Session prefix | `TC` |
40+
| Session path | `.workflow/.team/TC-<slug>-<date>/` |
41+
| Worker agent | `team-worker` |
42+
| Message bus | `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` |
43+
| CLI analysis | `ccw cli --mode analysis` |
44+
| CLI write | `ccw cli --mode write` |
45+
| Max roles | 5 |
46+
3547
## Role Router
3648

3749
This skill is **coordinator-only**. Workers do NOT invoke this skill -- they are spawned as `team-worker` agents directly.
@@ -85,6 +97,9 @@ User provides task description
8597
|---------|--------|
8698
| `check` / `status` | Output execution status graph, no advancement |
8799
| `resume` / `continue` | Check worker states, advance next step |
100+
| `revise <TASK-ID> [feedback]` | Revise specific task with optional feedback |
101+
| `feedback <text>` | Inject feedback into active pipeline |
102+
| `improve [dimension]` | Auto-improve weakest quality dimension |
88103

89104
---
90105

@@ -150,6 +165,17 @@ AskUserQuestion({
150165

151166
---
152167

168+
## Specs Reference
169+
170+
| Spec | Purpose |
171+
|------|---------|
172+
| [specs/pipelines.md](specs/pipelines.md) | Dynamic pipeline model, task naming, dependency graph |
173+
| [specs/role-spec-template.md](specs/role-spec-template.md) | Template for dynamic role-spec generation |
174+
| [specs/quality-gates.md](specs/quality-gates.md) | Quality thresholds and scoring dimensions |
175+
| [specs/knowledge-transfer.md](specs/knowledge-transfer.md) | Context transfer protocols between roles |
176+
177+
---
178+
153179
## Session Directory
154180

155181
```

‎.claude/skills/team-coordinate/roles/coordinator/commands/analyze-task.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,20 @@ Parse user task description -> detect required capabilities -> build dependency
1616

1717
If task context requires codebase knowledge, set `needs_research: true`. Phase 2 will spawn researcher worker.
1818

19+
## When to Use
20+
21+
| Trigger | Condition |
22+
|---------|-----------|
23+
| New task | Coordinator Phase 1 receives task description |
24+
| Re-analysis | User provides revised requirements |
25+
| Adapt | handleAdapt extends analysis for new capability |
26+
27+
## Strategy
28+
29+
- **Delegation**: Inline execution (coordinator processes directly)
30+
- **Mode**: Text-level analysis only (no codebase reading)
31+
- **Output**: `<session>/task-analysis.json`
32+
1933
## Phase 2: Context Loading
2034

2135
| Input | Source | Required |

‎.claude/skills/team-coordinate/roles/coordinator/commands/dispatch.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,20 @@
44

55
Create task chains from dynamic dependency graphs. Builds pipelines from the task-analysis.json produced by Phase 1. Workers are spawned as team-worker agents with role-spec paths.
66

7+
## When to Use
8+
9+
| Trigger | Condition |
10+
|---------|-----------|
11+
| After analysis | Phase 1 complete, task-analysis.json exists |
12+
| After adapt | handleAdapt created new roles, needs new tasks |
13+
| Re-dispatch | Pipeline restructuring (rare) |
14+
15+
## Strategy
16+
17+
- **Delegation**: Inline execution (coordinator processes directly)
18+
- **Inputs**: task-analysis.json + team-session.json
19+
- **Output**: TaskCreate calls with dependency chains
20+
721
## Phase 2: Context Loading
822

923
| Input | Source | Required |

‎.claude/skills/team-coordinate/roles/coordinator/commands/monitor.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,22 @@
44

55
Event-driven pipeline coordination with Spawn-and-Stop pattern. Role names are read from `team-session.json#roles`. Workers are spawned as `team-worker` agents with role-spec paths. Includes `handleComplete` for pipeline completion action and `handleAdapt` for mid-pipeline capability gap handling.
66

7+
## When to Use
8+
9+
| Trigger | Condition |
10+
|---------|-----------|
11+
| Worker callback | Message contains [role-name] from session roles |
12+
| User command | "check", "status", "resume", "continue" |
13+
| Capability gap | Worker reports capability_gap |
14+
| Pipeline spawn | After dispatch, initial spawn needed |
15+
| Pipeline complete | All tasks done |
16+
17+
## Strategy
18+
19+
- **Delegation**: Inline execution with handler routing
20+
- **Beat model**: ONE_STEP_PER_INVOCATION — one handler then STOP
21+
- **Workers**: Spawned as team-worker via Agent() in background
22+
723
## Constants
824

925
| Constant | Value | Description |

‎.claude/skills/team-coordinate/roles/coordinator/role.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
role: coordinator
3+
---
4+
15
# Coordinator Role
26

37
Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec generation, task dispatching, progress monitoring, session state, and completion action. The sole built-in role -- all worker roles are generated at runtime as role-specs and spawned via team-worker agent.
@@ -33,6 +37,30 @@ Orchestrate the team-coordinate workflow: task analysis, dynamic role-spec gener
3337

3438
---
3539

40+
## Message Types
41+
42+
| Type | Direction | Trigger |
43+
|------|-----------|---------|
44+
| state_update | outbound | Session init, pipeline progress |
45+
| task_unblocked | outbound | Task ready for execution |
46+
| fast_advance | inbound | Worker skipped coordinator |
47+
| capability_gap | inbound | Worker needs new capability |
48+
| error | inbound | Worker failure |
49+
| impl_complete | inbound | Worker task done |
50+
| consensus_blocked | inbound | Discussion verdict conflict |
51+
52+
## Message Bus Protocol
53+
54+
All coordinator state changes MUST be logged to team_msg BEFORE SendMessage:
55+
56+
1. `team_msg(operation="log", ...)` — log the event
57+
2. `SendMessage(...)` — communicate to worker/user
58+
3. `TaskUpdate(...)` — update task state
59+
60+
Read state before every handler: `team_msg(operation="get_state", session_id=<session-id>)`
61+
62+
---
63+
3664
## Command Execution Protocol
3765

3866
When coordinator needs to execute a command (analyze-task, dispatch, monitor):
@@ -52,6 +80,20 @@ Phase 1 needs task analysis
5280
-> Continue to Phase 2
5381
```
5482

83+
## Toolbox
84+
85+
| Tool | Type | Purpose |
86+
|------|------|---------|
87+
| commands/analyze-task.md | Command | Task analysis and role design |
88+
| commands/dispatch.md | Command | Task chain creation |
89+
| commands/monitor.md | Command | Pipeline monitoring and handlers |
90+
| team-worker | Subagent | Worker spawning |
91+
| TeamCreate / TeamDelete | System | Team lifecycle |
92+
| TaskCreate / TaskList / TaskGet / TaskUpdate | System | Task lifecycle |
93+
| team_msg | System | Message bus operations |
94+
| SendMessage | System | Inter-agent communication |
95+
| AskUserQuestion | System | User interaction |
96+
5597
---
5698

5799
## Entry Router

‎.claude/skills/team-coordinate/specs/knowledge-transfer.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Knowledge Transfer Protocols
2+
3+
## 1. Transfer Channels
4+
5+
| Channel | Scope | Mechanism | When to Use |
6+
|---------|-------|-----------|-------------|
7+
| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
8+
| **State Updates** | Cross-role | `team_msg(operation="log", type="state_update", data={...})` / `team_msg(operation="get_state", session_id=<session-id>)` | Key findings, decisions, metadata (small, structured data) |
9+
| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
10+
| **Context Accumulator** | Intra-role (inner loop) | In-memory array, passed to each subsequent task in same-prefix loop | Prior task summaries within same role's inner loop |
11+
| **Exploration Cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
12+
13+
## 2. Context Loading Protocol (Phase 2)
14+
15+
Every role MUST load context in this order before starting work.
16+
17+
| Step | Action | Required |
18+
|------|--------|----------|
19+
| 1 | Extract session path from task description | Yes |
20+
| 2 | `team_msg(operation="get_state", session_id=<session-id>)` | Yes |
21+
| 3 | Read artifact files from upstream state's `ref` paths | Yes |
22+
| 4 | Read `<session>/wisdom/*.md` if exists | Yes |
23+
| 5 | Check `<session>/explorations/cache-index.json` before new exploration | If exploring |
24+
| 6 | For inner_loop roles: load context_accumulator from prior tasks | If inner_loop |
25+
26+
**Loading rules**:
27+
- Never skip step 2 -- state contains key decisions and findings
28+
- If `ref` path in state does not exist, log warning and continue
29+
- Wisdom files are append-only -- read all entries, newest last
30+
31+
## 3. Context Publishing Protocol (Phase 4)
32+
33+
| Step | Action | Required |
34+
|------|--------|----------|
35+
| 1 | Write deliverable to `<session>/artifacts/<task-id>-<name>.md` | Yes |
36+
| 2 | Send `team_msg(type="state_update")` with payload (see schema below) | Yes |
37+
| 3 | Append wisdom entries for learnings, decisions, issues found | If applicable |
38+
39+
## 4. State Update Schema
40+
41+
Sent via `team_msg(type="state_update")` on task completion.
42+
43+
```json
44+
{
45+
"status": "task_complete",
46+
"task_id": "<TASK-NNN>",
47+
"ref": "<session>/artifacts/<filename>",
48+
"key_findings": [
49+
"Finding 1",
50+
"Finding 2"
51+
],
52+
"decisions": [
53+
"Decision with rationale"
54+
],
55+
"files_modified": [
56+
"path/to/file.ts"
57+
],
58+
"verification": "self-validated | peer-reviewed | tested"
59+
}
60+
```
61+
62+
**Field rules**:
63+
- `ref`: Always an artifact path, never inline content
64+
- `key_findings`: Max 5 items, each under 100 chars
65+
- `decisions`: Include rationale, not just the choice
66+
- `files_modified`: Only for implementation tasks
67+
- `verification`: One of `self-validated`, `peer-reviewed`, `tested`
68+
69+
**Write state** (namespaced by role):
70+
```
71+
team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={
72+
"<role_name>": { "key_findings": [...], "scope": "..." }
73+
})
74+
```
75+
76+
**Read state**:
77+
```
78+
team_msg(operation="get_state", session_id=<session-id>)
79+
// Returns merged state from all state_update messages
80+
```
81+
82+
## 5. Exploration Cache Protocol
83+
84+
Prevents redundant research across tasks and discussion rounds.
85+
86+
| Step | Action |
87+
|------|--------|
88+
| 1 | Read `<session>/explorations/cache-index.json` |
89+
| 2 | If angle already explored, read cached result from `explore-<angle>.json` |
90+
| 3 | If not cached, perform exploration |
91+
| 4 | Write result to `<session>/explorations/explore-<angle>.json` |
92+
| 5 | Update `cache-index.json` with new entry |
93+
94+
**cache-index.json format**:
95+
```json
96+
{
97+
"entries": [
98+
{
99+
"angle": "competitor-analysis",
100+
"file": "explore-competitor-analysis.json",
101+
"created_by": "RESEARCH-001",
102+
"timestamp": "2026-01-15T10:30:00Z"
103+
}
104+
]
105+
}
106+
```
107+
108+
**Rules**:
109+
- Cache key is the exploration `angle` (normalized to kebab-case)
110+
- Cache entries never expire within a session
111+
- Any role can read cached explorations; only the creator updates them

‎.claude/skills/team-coordinate/specs/pipelines.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,17 @@ message_types:
8181
## Specs Reference
8282

8383
- [role-spec-template.md](role-spec-template.md) — Template for generating dynamic role-specs
84+
- [quality-gates.md](quality-gates.md) — Quality thresholds and scoring dimensions
85+
- [knowledge-transfer.md](knowledge-transfer.md) — Context transfer protocols between roles
86+
87+
## Quality Gate Integration
88+
89+
Dynamic pipelines reference quality thresholds from [specs/quality-gates.md](quality-gates.md).
90+
91+
| Gate Point | Trigger | Criteria Source |
92+
|------------|---------|----------------|
93+
| After artifact production | Producer role Phase 4 | Behavioral Traits in role-spec |
94+
| After validation tasks | Tester/analyst completion | quality-gates.md thresholds |
95+
| Pipeline completion | All tasks done | Aggregate scoring |
96+
97+
Issue classification: Error (blocks) > Warning (proceed with justification) > Info (log for future).

0 commit comments

Comments
 (0)