mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
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
This commit is contained in:
@@ -404,6 +404,48 @@ Write discoveries to corresponding wisdom files:
|
||||
|
||||
---
|
||||
|
||||
## Knowledge Transfer
|
||||
|
||||
### Upstream Context Loading (Phase 2)
|
||||
|
||||
When executing Phase 2 of a role-spec, the worker MUST load available cross-role context:
|
||||
|
||||
| Source | Path | Load Method |
|
||||
|--------|------|-------------|
|
||||
| Upstream artifacts | `<session>/artifacts/*.md` | Read files listed in task description or dependency chain |
|
||||
| Shared memory | `<session>/shared-memory.json` | Read and parse JSON |
|
||||
| Wisdom | `<session>/wisdom/*.md` | Read all wisdom files |
|
||||
| Exploration cache | `<session>/explorations/cache-index.json` | Check before new explorations |
|
||||
|
||||
### Downstream Context Publishing (Phase 4)
|
||||
|
||||
After Phase 4 verification, the worker MUST publish its contributions:
|
||||
|
||||
1. **Artifact**: Write deliverable to `<session>/artifacts/<prefix>-<task-id>-<name>.md`
|
||||
2. **shared-memory.json**: Read-merge-write under role namespace
|
||||
```json
|
||||
{ "<role>": { "key_findings": [...], "decisions": [...], "files_modified": [...] } }
|
||||
```
|
||||
3. **Wisdom**: Append new patterns to `learnings.md`, decisions to `decisions.md`, issues to `issues.md`
|
||||
|
||||
### Inner Loop Context Accumulator
|
||||
|
||||
For `inner_loop: true` roles, `context_accumulator` is maintained in-memory:
|
||||
|
||||
```
|
||||
context_accumulator.append({
|
||||
task: "<task-id>",
|
||||
artifact: "<output-path>",
|
||||
key_decisions: [...],
|
||||
summary: "<brief>",
|
||||
files_modified: [...]
|
||||
})
|
||||
```
|
||||
|
||||
Pass the full accumulator to each subsequent task's Phase 3 subagent as `## Prior Context`.
|
||||
|
||||
---
|
||||
|
||||
## Message Bus Protocol
|
||||
|
||||
Always use `mcp__ccw-tools__team_msg` for logging. Parameters:
|
||||
|
||||
@@ -134,3 +134,46 @@ Coordinator MAY reference these patterns when composing Phase 2-4 content for a
|
||||
- Phase 2: Detect test framework + identify changed files from upstream
|
||||
- Phase 3: Run test-fix cycle — iteration count and strategy determined by task
|
||||
- Phase 4: Verify pass rate + coverage (Behavioral Traits) + update shared-memory
|
||||
|
||||
---
|
||||
|
||||
## Knowledge Transfer Protocol
|
||||
|
||||
How context flows between roles. Coordinator MUST reference this when composing Phase 2 of any role-spec.
|
||||
|
||||
### Transfer Channels
|
||||
|
||||
| Channel | Scope | Mechanism | When to Use |
|
||||
|---------|-------|-----------|-------------|
|
||||
| **Artifacts** | Producer -> Consumer | Write to `<session>/artifacts/<name>.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) |
|
||||
| **shared-memory.json** | Cross-role | Read-merge-write `<session>/shared-memory.json` | Key findings, decisions, metadata (small, structured data) |
|
||||
| **Wisdom** | Cross-task | Append to `<session>/wisdom/{learnings,decisions,conventions,issues}.md` | Patterns, conventions, risks discovered during execution |
|
||||
| **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 |
|
||||
| **Exploration cache** | Cross-role | `<session>/explorations/cache-index.json` + per-angle JSON | Codebase discovery results, prevents duplicate exploration |
|
||||
|
||||
### Phase 2 Context Loading (role-spec must specify)
|
||||
|
||||
Every generated role-spec Phase 2 MUST declare which upstream sources to load:
|
||||
|
||||
```
|
||||
1. Extract session path from task description
|
||||
2. Read upstream artifacts: <list which artifacts from which upstream role>
|
||||
3. Read shared-memory.json for cross-role decisions
|
||||
4. Load wisdom files for accumulated knowledge
|
||||
5. For inner_loop roles: load context_accumulator from prior tasks
|
||||
6. Check exploration cache before running new explorations
|
||||
```
|
||||
|
||||
### shared-memory.json Usage Convention
|
||||
|
||||
- **Read-merge-write**: Read current content -> merge new keys -> write back (NOT overwrite)
|
||||
- **Namespaced keys**: Each role writes under its own namespace: `{ "<role_name>": { ... } }`
|
||||
- **Small data only**: Key findings, decision summaries, metadata. NOT full documents
|
||||
- **Example**:
|
||||
```json
|
||||
{
|
||||
"researcher": { "key_findings": [...], "scope": "..." },
|
||||
"writer": { "documents_created": [...], "style_decisions": [...] },
|
||||
"developer": { "files_changed": [...], "patterns_used": [...] }
|
||||
}
|
||||
```
|
||||
|
||||
@@ -192,7 +192,9 @@ Beat Cycle (single beat)
|
||||
Fast-Advance (skips coordinator for simple linear successors)
|
||||
======================================================================
|
||||
[Worker A] Phase 5 complete
|
||||
+- 1 ready task? simple successor? --> spawn team-worker B directly
|
||||
+- 1 ready task? simple successor?
|
||||
| --> spawn team-worker B directly
|
||||
| --> log fast_advance to message bus (coordinator syncs on next wake)
|
||||
+- complex case? --> SendMessage to coordinator
|
||||
======================================================================
|
||||
```
|
||||
|
||||
@@ -59,7 +59,12 @@ Receive callback from [<role>]
|
||||
+- None completed -> STOP
|
||||
```
|
||||
|
||||
**Fast-advance awareness**: Check if next task is already `in_progress` (fast-advanced by worker). If yes -> skip spawning, update active_workers.
|
||||
**Fast-advance reconciliation**: When processing any callback or resume:
|
||||
1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
|
||||
2. For each: add spawned successor to `active_workers` if not already present
|
||||
3. Check if expected next task is already `in_progress` (fast-advanced)
|
||||
4. If yes -> skip spawning (already running)
|
||||
5. If no -> normal handleSpawnNext
|
||||
|
||||
---
|
||||
|
||||
@@ -205,6 +210,13 @@ Detect orphaned in_progress task (no active_worker):
|
||||
+- Reset to pending -> handleSpawnNext
|
||||
```
|
||||
|
||||
### Fast-Advance State Sync
|
||||
|
||||
On every coordinator wake (handleCallback, handleResume, handleCheck):
|
||||
1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
|
||||
2. For each entry: sync `active_workers` with the spawned successor
|
||||
3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
|
||||
|
||||
### Consensus-Blocked Handling
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user