Skip to content

Commit e42597b

Browse files
author
catlog22
committed
refactor(team): add fast-advance notification and knowledge transfer protocol
- team-worker: add fast_advance message bus log after spawning successor, closing coordinator state blind spot during fast-advance - team-worker: add Knowledge Transfer section with upstream loading, downstream publishing, and context_accumulator conventions - role-spec-template: add Knowledge Transfer Protocol with Transfer Channels table and shared-memory.json namespaced write convention - monitor.md (v2+v5): add fast-advance reconciliation step reading fast_advance messages, add State Sync section for coordinator wake - lifecycle-v5 SKILL.md: update cadence diagram with fast_advance log
1 parent 67b2129 commit e42597b

4 files changed

Lines changed: 101 additions & 2 deletions

File tree

.claude/agents/team-worker.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -404,6 +404,48 @@ Write discoveries to corresponding wisdom files:
404404

405405
---
406406

407+
## Knowledge Transfer
408+
409+
### Upstream Context Loading (Phase 2)
410+
411+
When executing Phase 2 of a role-spec, the worker MUST load available cross-role context:
412+
413+
| Source | Path | Load Method |
414+
|--------|------|-------------|
415+
| Upstream artifacts | `<session>/artifacts/*.md` | Read files listed in task description or dependency chain |
416+
| Shared memory | `<session>/shared-memory.json` | Read and parse JSON |
417+
| Wisdom | `<session>/wisdom/*.md` | Read all wisdom files |
418+
| Exploration cache | `<session>/explorations/cache-index.json` | Check before new explorations |
419+
420+
### Downstream Context Publishing (Phase 4)
421+
422+
After Phase 4 verification, the worker MUST publish its contributions:
423+
424+
1. **Artifact**: Write deliverable to `<session>/artifacts/<prefix>-<task-id>-<name>.md`
425+
2. **shared-memory.json**: Read-merge-write under role namespace
426+
```json
427+
{ "<role>": { "key_findings": [...], "decisions": [...], "files_modified": [...] } }
428+
```
429+
3. **Wisdom**: Append new patterns to `learnings.md`, decisions to `decisions.md`, issues to `issues.md`
430+
431+
### Inner Loop Context Accumulator
432+
433+
For `inner_loop: true` roles, `context_accumulator` is maintained in-memory:
434+
435+
```
436+
context_accumulator.append({
437+
task: "<task-id>",
438+
artifact: "<output-path>",
439+
key_decisions: [...],
440+
summary: "<brief>",
441+
files_modified: [...]
442+
})
443+
```
444+
445+
Pass the full accumulator to each subsequent task's Phase 3 subagent as `## Prior Context`.
446+
447+
---
448+
407449
## Message Bus Protocol
408450

409451
Always use `mcp__ccw-tools__team_msg` for logging. Parameters:

.claude/skills/team-coordinate-v2/specs/role-spec-template.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,3 +134,46 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
134134
- Phase 2: Detect test framework + identify changed files from upstream
135135
- Phase 3: Run test-fix cycle — iteration count and strategy determined by task
136136
- Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared-memory
137+
138+
---
139+
140+
## Knowledge Transfer Protocol
141+
142+
How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
143+
144+
### Transfer Channels
145+
146+
| Channel | Scope | Mechanism | When to Use |
147+
|---------|-------|-----------|-------------|
148+
| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
149+
| **shared-memory.json** | Cross-role | Read-merge-write `<session>/shared-memory.json` | Key findings, decisions, metadata (small, structured data) |
150+
| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
151+
| **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 |
152+
| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
153+
154+
### Phase 2 Context Loading (role-spec must specify)
155+
156+
Every generated role-spec Phase 2 MUST declare which upstream sources to load:
157+
158+
```
159+
1. Extract session path from task description
160+
2. Read upstream artifacts: <list which artifacts from which upstream role>
161+
3. Read shared-memory.json for cross-role decisions
162+
4. Load wisdom files for accumulated knowledge
163+
5. For inner_loop roles: load context_accumulator from prior tasks
164+
6. Check exploration cache before running new explorations
165+
```
166+
167+
### shared-memory.json Usage Convention
168+
169+
- **Read-merge-write**: Read current content -> merge new keys -> write back (NOT overwrite)
170+
- **Namespaced keys**: Each role writes under its own namespace: `{ "<role_name>": { ... } }`
171+
- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
172+
- **Example**:
173+
```json
174+
{
175+
"researcher": { "key_findings": [...], "scope": "..." },
176+
"writer": { "documents_created": [...], "style_decisions": [...] },
177+
"developer": { "files_changed": [...], "patterns_used": [...] }
178+
}
179+
```

.claude/skills/team-lifecycle-v5/SKILL.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,9 @@ Beat Cycle (single beat)
192192
Fast-Advance (skips coordinator for simple linear successors)
193193
======================================================================
194194
[Worker A] Phase 5 complete
195-
+- 1 ready task? simple successor? --> spawn team-worker B directly
195+
+- 1 ready task? simple successor?
196+
| --> spawn team-worker B directly
197+
| --> log fast_advance to message bus (coordinator syncs on next wake)
196198
+- complex case? --> SendMessage to coordinator
197199
======================================================================
198200
```

.claude/skills/team-lifecycle-v5/roles/coordinator/commands/monitor.md

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,12 @@ Receive callback from [<role>]
5959
+- None completed -> STOP
6060
```
6161

62-
**Fast-advance awareness**: Check if next task is already `in_progress` (fast-advanced by worker). If yes -> skip spawning, update active_workers.
62+
**Fast-advance reconciliation**: When processing any callback or resume:
63+
1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
64+
2. For each: add spawned successor to `active_workers` if not already present
65+
3. Check if expected next task is already `in_progress` (fast-advanced)
66+
4. If yes -> skip spawning (already running)
67+
5. If no -> normal handleSpawnNext
6368

6469
---
6570

@@ -205,6 +210,13 @@ Detect orphaned in_progress task (no active_worker):
205210
+- Reset to pending -> handleSpawnNext
206211
```
207212

213+
### Fast-Advance State Sync
214+
215+
On every coordinator wake (handleCallback, handleResume, handleCheck):
216+
1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
217+
2. For each entry: sync `active_workers` with the spawned successor
218+
3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
219+
208220
### Consensus-Blocked Handling
209221

210222
```

0 commit comments

Comments
 (0)