diff --git a/docs/claude/orchestrator.md b/docs/claude/orchestrator.md index 4a0392b..6105ddd 100644 --- a/docs/claude/orchestrator.md +++ b/docs/claude/orchestrator.md @@ -276,56 +276,92 @@ git push --- -## Compaction Protocol +## Context Threshold Protocol (Orchestrator Replacement) **Threshold:** 55-60% context usage -**CRITICAL:** Agents CANNOT trigger compaction. Only the user typing `/compact` works. +**Why replacement, not compaction?** -- ❌ "compact and continue" does NOT work (agent outputs summary but context is NOT compressed) -- ❌ Agent cannot invoke `/compact` programmatically -- ✅ User must type `/compact` directly in the CLI +- Compaction causes **protocol drift** — agent "remembers" gist but loses specifics +- Post-compaction agents may violate core rules (e.g., letting workers modify tasks.md) +- Fresh orchestrator has **100% protocol fidelity** +- All state lives in `docs/tasks.md` — the orchestrator is **stateless and replaceable** -**When approaching threshold (55-60%):** +**At threshold (55-60%):** 1. Complete current task 2. Persist all state: - Update docs/tasks.md with all progress - Update docs/orchestrator-learnings.json with variances - Commit and push both files -3. Output checkpoint using this EXACT format: +3. Output **ORCHESTRATOR HANDOFF** message with ready-to-use takeover kickstart +4. **STOP COMPLETELY** — do not continue working + +**Handoff message format:** ``` --- -⚠️ COMPACTION REQUIRED +⚠️ ORCHESTRATOR HANDOFF REQUIRED -Context: {X}% — Cannot continue without compaction. +Context: {X}% — Replacement recommended to prevent drift Progress: {completed}/{total} tasks ({percentage}%) -Next task: {task_id} +Current phase: Phase {N} ({phase_name}) -State persisted to: +State persisted: - docs/tasks.md ✓ - docs/orchestrator-learnings.json ✓ -ACTION REQUIRED: -1. Type `/compact` in the CLI (not in chat) -2. After compaction completes, say "continue" +## Takeover Kickstart -I will resume with {task_id} after compaction. +Copy and paste this to spawn a fresh orchestrator: + +--- +## Continuation Mission + +Continue {mission_description} from existing state. + +## Setup +- Project: /home/localadmin/src/mosaic-stack +- State: docs/tasks.md (already populated) +- Protocol: docs/claude/orchestrator.md +- Quality gates: pnpm lint && pnpm typecheck && pnpm test + +## Resume Point +- Next task: {task_id} +- Phase: {current_phase} +- Progress: {completed}/{total} tasks ({percentage}%) + +## Instructions +1. Read docs/claude/orchestrator.md for protocol +2. Read docs/tasks.md to understand current state +3. Continue execution from task {task_id} +4. Follow Two-Phase Completion Protocol +5. You are the SOLE writer of docs/tasks.md +--- + +STOP: Terminate this session and spawn fresh orchestrator with the kickstart above. --- ``` -4. **STOP COMPLETELY** — do not continue working -5. Wait for user to run `/compact` and say "continue" -6. Resume from next task +**Future: Coordinator Automation** + +When the Mosaic Stack Coordinator service is implemented, it will: + +- Monitor orchestrator stdout for context percentage +- Detect the handoff checkpoint message +- Parse the takeover kickstart +- Automatically spawn fresh orchestrator +- Log handoff events for debugging + +For now, the human acts as Coordinator. **Rules:** -- Do NOT output a summary and keep working -- Do NOT claim you can compact yourself -- Do NOT continue past 60% — the checkpoint is mandatory -- STOP means STOP — wait for user action +- Do NOT attempt to compact yourself — compaction causes drift +- Do NOT continue past 60% +- Do NOT claim you can "just continue" — protocol drift is real +- STOP means STOP — the user (Coordinator) will spawn your replacement ---