feat: Add context isolation simulation and agent handoff protocols for 48% token reduction

.github/agents/AKIS.agent.md

@@ -205,6 +205,27 @@ runSubagent(
 | Resolution | 53.5 min | 8.1 min | **-56.0%** |
 | Success | 86.8% | 94.0% | **+7.1%** |
 
+## ⛔ Context Isolation (Clean Handoffs)
+**100k Projection**: Context isolation reduces tokens by 60-70%, cognitive load by 70%
+
+### Handoff Protocol
+When delegating to agents, use **artifact-based handoffs** (not conversation history):
+
+```yaml
+artifact:
+  type: "design_spec" | "research_findings" | "code_changes"
+  summary: "Brief distillation"
+  key_decisions: ["decision1", "decision2"]
+  files: ["file1.py", "file2.tsx"]
+  # NO conversation history, NO planning details
+```
+
+### Clean Context Rules
+1. **Planning phase outputs** → Summarize to artifact
+2. **Implementation agents** → Start fresh, only receive artifact
+3. **NO conversation history** passed between agents
+4. **Each agent is stateless** - Orchestrator manages state
+
 ## ⛔ Parallel (G7 - 60% Target)
 | Pair | Invoke Pattern |
 |------|---------------|

.github/agents/architect.agent.md

@@ -44,16 +44,30 @@ tools: ['read', 'search']
 [RETURN] ← architect | result: blueprint | components: N | next: code
 ```
 
+### Handoff Artifact (for code agent)
+```yaml
+artifact:
+  type: design_spec
+  summary: "Brief description of what to build"
+  components: ["component1", "component2"]
+  files_to_create: ["path/file1.py"]
+  files_to_modify: ["path/file2.tsx"]
+  key_decisions: ["use pattern X", "avoid approach Y"]
+  # NO planning rationale, NO alternatives discussion
+```
+
 ## ⚠️ Gotchas
 - **Over-engineering** | Keep designs simple, max 7 components
 - **Missing docs** | Document in docs/architecture/
 - **No approval** | Get approval before code
 - **Skipped research** | Call research agent first if needed
+- **Context pollution** | Output clean artifact, not full planning
 
 ## ⚙️ Optimizations
 - **Research-first**: Call research agent before complex designs
 - **Component limit**: 7 components max for cognitive clarity
 - **Template reuse**: Check existing blueprints in .project/
+- **Clean handoffs**: Produce distilled artifact for code agent
 
 ## Orchestration
 
@@ -70,4 +84,5 @@ handoffs:
   - label: Implement Blueprint
     agent: code
     prompt: 'Implement blueprint from architect'
+    artifact: design_spec  # Clean context handoff
 ```

.github/agents/code.agent.md

@@ -39,6 +39,18 @@ tools: ['read', 'edit', 'search', 'execute']
 ## Technologies
 Python, React, TypeScript, FastAPI, Zustand, Workflows, Docker, WebSocket, pytest, jest
 
+## Clean Context Input
+When receiving work from architect or research agent, expect a **clean artifact**:
+```yaml
+artifact:
+  type: design_spec | research_findings
+  summary: "What to implement"
+  files_to_modify: ["file1.py", "file2.tsx"]
+  key_decisions: ["use X", "avoid Y"]
+  # NO planning rationale, NO full conversation history
+```
+**Rule**: Start implementation from clean context. Do NOT need planning details.
+
 ## Output Format
 ```markdown
 ## Implementation: [Feature]
@@ -48,18 +60,29 @@ Python, React, TypeScript, FastAPI, Zustand, Workflows, Docker, WebSocket, pytes
 [RETURN] ← code | result: ✓ | files: N | tests: added
 ```
 
+### Output Artifact (for reviewer/docs)
+```yaml
+artifact:
+  type: code_changes
+  summary: "What was implemented"
+  files_modified: ["file1.py", "file2.tsx"]
+  tests_added: ["test_file1.py"]
+```
+
 ## ⚠️ Gotchas
 - **Style mismatch** | Match existing project code style
 - **No linting** | Run linting after changes
 - **Silent blockers** | Report blockers immediately
 - **Missing tests** | Add tests for new code
+- **Context pollution** | Ignore planning details, focus on artifact
 
 ## ⚙️ Optimizations
 - **Documentation pre-loading**: Load relevant docs before implementation ✓
 - **Test-aware mode**: Check existing tests, update when changing code ✓
 - **Operation batching**: Group related file edits to reduce token usage ✓
 - **Pattern reuse**: Check existing components before creating new
 - **Skills**: docker, documentation (auto-loaded when relevant)
+- **Clean context**: Start fresh from artifact, not conversation history
 
 ## Orchestration
 
@@ -73,6 +96,7 @@ handoffs:
   - label: Review Code
     agent: reviewer
     prompt: 'Review implementation for quality and security'
+    artifact: code_changes  # Clean context handoff
   - label: Debug Issue
     agent: debugger
     prompt: 'Debug issue in implementation'

.github/agents/debugger.agent.md

@@ -48,18 +48,32 @@ print(f"[DEBUG] EXIT func | result: {result}")
 [RETURN] ← debugger | result: fixed | file: path:line
 ```
 
+### Output Artifact (for code agent)
+```yaml
+artifact:
+  type: bug_diagnosis
+  summary: "Root cause in 1-2 sentences"
+  root_cause_file: "path/file.py"
+  root_cause_line: 123
+  fix_suggestion: "Change X to Y"
+  related_files: ["file1.py"]
+  # NO full debug logs, NO trace history
+```
+
 ## ⚠️ Gotchas
 - **Skip gotchas** | Check project_knowledge.json gotchas FIRST (75% known issues)
 - **No reproduce** | Reproduce before debugging
 - **Log overload** | Minimal logs only
 - **Logs remain** | Clean up after fix
+- **Context pollution** | Output clean artifact, not full trace
 
 ## ⚙️ Optimizations
 - **Test-aware mode**: Check existing tests before debugging, run tests to reproduce ✓
 - **Browser console first**: For frontend issues, check DevTools console for exact error
 - **Knowledge-first**: Check gotchas in project_knowledge.json before file reads ✓
 - **Binary search**: Isolate issue by halving search space
 - **Skills**: debugging, knowledge (auto-loaded)
+- **Clean handoffs**: Produce distilled artifact for code agent
 
 ## Orchestration
 
@@ -73,5 +87,6 @@ handoffs:
   - label: Implement Fix
     agent: code
     prompt: 'Implement fix for root cause identified by debugger'
+    artifact: bug_diagnosis  # Clean context handoff
 ```
 

.github/agents/devops.agent.md

@@ -43,6 +43,18 @@ tools: ['read', 'edit', 'execute']
 [RETURN] ← devops | result: configured | services: list
 ```
 
+## Clean Context Input
+When receiving work from architect, expect a **clean artifact**:
+```yaml
+artifact:
+  type: infrastructure_spec
+  summary: "What infrastructure to configure"
+  services: ["backend", "frontend", "db"]
+  requirements: ["resource limits", "health checks"]
+  # Only need service specs, not full design rationale
+```
+**Rule**: Configure based on spec artifact, not planning details.
+
 ## ⚠️ Gotchas
 - **No config test** | Run `docker-compose config` first
 - **Missing limits** | Check resource limits
@@ -54,6 +66,7 @@ tools: ['read', 'edit', 'execute']
 - **Incremental deploys**: Deploy one service at a time
 - **Health-first**: Wait for health checks before proceeding
 - **Skills**: docker (auto-loaded)
+- **Clean context**: Receive distilled artifact only
 
 ## Orchestration
 

.github/agents/documentation.agent.md

@@ -43,6 +43,18 @@ tools: ['read', 'edit', 'search']
 [RETURN] ← documentation | result: updated | files: N
 ```
 
+## Clean Context Input
+When receiving work from code agent, expect a **clean artifact**:
+```yaml
+artifact:
+  type: code_changes
+  summary: "What was implemented"
+  files_modified: ["file1.py"]
+  api_changes: ["new endpoint POST /api/x"]
+  # Only need code and API summary for docs
+```
+**Rule**: Document based on code artifact, not implementation details.
+
 ## ⚠️ Gotchas
 - **No index check** | Check docs/INDEX.md first
 - **Style mismatch** | Match existing style
@@ -55,6 +67,7 @@ tools: ['read', 'edit', 'search']
 - **Auto-generate tables**: Use consistent markdown table format
 - **Template reuse**: Use existing templates from docs/
 - **Skills**: documentation, knowledge (auto-loaded)
+- **Clean context**: Only receive code summary for docs
 
 ## Orchestration
 

.github/agents/research.agent.md

@@ -46,16 +46,29 @@ tools: ['read', 'search']
 [RETURN] ← research | sources: local:N, ext:M | confidence: high
 ```
 
+### Output Artifact (for architect/code)
+```yaml
+artifact:
+  type: research_findings
+  summary: "Brief distillation of key findings"
+  key_decisions: ["use X over Y because Z"]
+  recommendations: ["recommendation1", "recommendation2"]
+  references: ["source1", "source2"]
+  # NO full comparison matrix, NO detailed analysis
+```
+
 ## ⚠️ Gotchas
 - **External first** | Check local FIRST before external
 - **No citations** | Cite all sources
 - **Old sources** | Verify sources <1 year old
 - **No caching** | Cache findings in project_knowledge.json
+- **Context pollution** | Output clean artifact, not full research
 
 ## ⚙️ Optimizations
 - **Knowledge-first**: project_knowledge.json has pre-indexed entities
 - **Workflow mining**: Check log/workflow/ for past solutions
 - **Confidence levels**: Report high/medium/low confidence
+- **Clean handoffs**: Produce distilled artifact for downstream agents
 
 ## Orchestration
 
@@ -69,5 +82,6 @@ handoffs:
   - label: Design from Research
     agent: architect
     prompt: 'Design based on research findings'
+    artifact: research_findings  # Clean context handoff
 ```
 

.github/agents/reviewer.agent.md

@@ -61,6 +61,17 @@ tools: ['read', 'search']
 [RETURN] ← reviewer | verdict: PASS | blockers: 0 | warnings: N
 ```
 
+## Clean Context Input
+When receiving work from code agent, expect a **clean artifact**:
+```yaml
+artifact:
+  type: code_changes
+  summary: "What was implemented"
+  files_modified: ["file1.py", "file2.tsx"]
+  # NO full implementation details, just code to review
+```
+**Rule**: Review against acceptance criteria, not planning details.
+
 ## ⚠️ Gotchas
 - **Rubber-stamp** | Be objective, not approval-biased
 - **No citations** | Cite specific code file:line
@@ -71,6 +82,7 @@ tools: ['read', 'search']
 - **Checklist-driven**: Use checklist for consistent reviews
 - **Severity ordering**: Report blockers before warnings
 - **Pattern matching**: Check known vulnerability patterns first
+- **Clean context**: Only receive code changes, not planning
 
 ## Orchestration
 

.github/copilot-instructions.md

@@ -62,6 +62,15 @@
 | debugger | Fix bugs |
 | documentation | Docs (parallel) |
 
+## Context Isolation (Clean Handoffs)
+| Phase | Rule |
+|-------|------|
+| planning → code | Artifact only, no history |
+| research → design | Summary + decisions |
+| code → review | Code changes only |
+
+**Handoff Protocol**: Produce typed artifact, not conversation history.
+
 ## Parallel (G7: 60%)
 | Pair | Pattern |
 |------|---------|
@@ -81,3 +90,4 @@
 | Skip announcement | Announce before WORK |
 | Multiple ◆ | One only |
 | Auto-push | ASK first |
+| Context pollution | Use artifact handoffs |

.github/instructions/quality.instructions.md

@@ -59,3 +59,6 @@ description: 'Quality checks and common gotchas. Verification steps and error pr
 | Cache | Same skill reloaded | Load skill ONCE per domain, cache list |
 | JS | Empty object {} is truthy | Use `Object.keys(obj).length > 0` check |
 | WebSocket | execution_completed missing state | Include nodeStatuses in WS completion event |
+| Delegation | Context pollution in implementation | Use artifact-based handoffs (max 500 tokens) |
+| Delegation | Agent gets full planning history | Pass structured artifact, not conversation |
+| Delegation | High cognitive load in complex tasks | Enable context isolation, clean starts |