From e42597b1bcd34ec5945cd197b1467fb4f42774a8 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 28 Feb 2026 22:53:56 +0800 Subject: [PATCH] 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 --- .claude/agents/team-worker.md | 42 ++++++++++++++++++ .../specs/role-spec-template.md | 43 +++++++++++++++++++ .claude/skills/team-lifecycle-v5/SKILL.md | 4 +- .../roles/coordinator/commands/monitor.md | 14 +++++- 4 files changed, 101 insertions(+), 2 deletions(-) diff --git a/.claude/agents/team-worker.md b/.claude/agents/team-worker.md index e22e6bc6..ce4affed 100644 --- a/.claude/agents/team-worker.md +++ b/.claude/agents/team-worker.md @@ -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 | `/artifacts/*.md` | Read files listed in task description or dependency chain | +| Shared memory | `/shared-memory.json` | Read and parse JSON | +| Wisdom | `/wisdom/*.md` | Read all wisdom files | +| Exploration cache | `/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 `/artifacts/--.md` +2. **shared-memory.json**: Read-merge-write under role namespace + ```json + { "": { "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: "", + artifact: "", + key_decisions: [...], + summary: "", + 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: diff --git a/.claude/skills/team-coordinate-v2/specs/role-spec-template.md b/.claude/skills/team-coordinate-v2/specs/role-spec-template.md index bbb29b0a..1245b57b 100644 --- a/.claude/skills/team-coordinate-v2/specs/role-spec-template.md +++ b/.claude/skills/team-coordinate-v2/specs/role-spec-template.md @@ -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 `/artifacts/.md`, consumer reads in Phase 2 | Structured deliverables (reports, plans, specs) | +| **shared-memory.json** | Cross-role | Read-merge-write `/shared-memory.json` | Key findings, decisions, metadata (small, structured data) | +| **Wisdom** | Cross-task | Append to `/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 | `/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: +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: `{ "": { ... } }` +- **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": [...] } + } + ``` diff --git a/.claude/skills/team-lifecycle-v5/SKILL.md b/.claude/skills/team-lifecycle-v5/SKILL.md index 86a218a8..6c44baa7 100644 --- a/.claude/skills/team-lifecycle-v5/SKILL.md +++ b/.claude/skills/team-lifecycle-v5/SKILL.md @@ -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 ====================================================================== ``` diff --git a/.claude/skills/team-lifecycle-v5/roles/coordinator/commands/monitor.md b/.claude/skills/team-lifecycle-v5/roles/coordinator/commands/monitor.md index 072b13ac..1a18231f 100644 --- a/.claude/skills/team-lifecycle-v5/roles/coordinator/commands/monitor.md +++ b/.claude/skills/team-lifecycle-v5/roles/coordinator/commands/monitor.md @@ -59,7 +59,12 @@ Receive callback from [] +- 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 ```