blue/.blue/docs/rfcs/0016-context-injection-architecture.md

RFC 0016: Context Injection Architecture

Status	Draft
Created	2026-01-25
Source	Alignment Dialogue (12 experts, 95% convergence)

---

Summary

Unified architecture for injecting knowledge into Claude's context, consolidating session hooks, MCP resources, and knowledge files into a manifest-driven system with three cognitive tiers.

Motivation

Blue currently has multiple context injection mechanisms that evolved organically:

• SessionStart hooks inject knowledge/*.md files
• Project-specific .blue/workflow.md auto-injects
• MCP Resources (blue://rfc/*) designed but not implemented
• Worktree context via hooks

This creates a "scattered hydration" pattern with no unified model. Users cannot audit what context Claude receives, and the system doesn't scale.

Principles

1. Context flows through explicit boundaries - System/project/session tiers with clear ownership
2. Artifacts are the only learning mechanism - Sessions don't learn; projects do through explicit artifacts
3. Manifest declares intent; visibility reveals reality - Single source of truth with audit capability
4. Push for bootstrap, pull for depth - Hooks provide essentials, MCP Resources provide enrichment

Design

Three-Tier Model

Tier	Name	Injection	Content	Budget
1	Identity	Always (SessionStart)	ADRs, voice patterns	~500 tokens
2	Workflow	Activity-triggered	Current RFC, active tasks	~2000 tokens
3	Reference	On-demand (MCP)	Full docs, dialogues	~4000 tokens

Cognitive framing from Strudel: Identity = "who am I", Workflow = "what should I do", Reference = "how does this work".

Manifest Format

# .blue/context.manifest.yaml
version: 1
generated_at: 2026-01-25T12:00:00Z
source_commit: abc123

identity:
  - uri: blue://docs/adrs/
  - uri: blue://context/voice
  max_tokens: 500

workflow:
  sources:
    - uri: blue://state/current-rfc
    - uri: blue://docs/rfcs/{active}
  refresh_triggers:
    - on_rfc_change
    - every_10_turns
  max_tokens: 2000

reference:
  graph: blue://context/relevance
  max_tokens: 4000
  staleness_days: 30

plugins:
  - uri: blue://jira/
    salience_triggers:
      - commit_msg_pattern: "^[A-Z]+-\\d+"

URI Addressing

Pattern	Description
blue://docs/{type}/	Document collections (adrs, rfcs, spikes)
blue://docs/{type}/{id}	Specific document
blue://context/{scope}	Injection bundles (voice, relevance)
blue://state/{entity}	Live state (current-rfc, active-tasks)
blue://{plugin}/	Plugin-provided context

Injection Flow

SessionStart Hook
       │
       ▼
┌──────────────────┐
│ Read manifest    │
│ Resolve Tier 1   │
│ Declare Tier 2   │
└──────────────────┘
       │
       ▼
┌──────────────────┐
│ MCP Resource     │
│ Resolver         │
│ (lazy Tier 2/3)  │
└──────────────────┘
       │
       ▼
┌──────────────────┐
│ Claude Context   │
└──────────────────┘

Hooks push URIs (references), MCP pulls content. This resolves the layering violation concern.

Visibility Commands

# Quick summary
blue context
# → Identity: 3 sources (487 tokens) | Workflow: 2 sources (1.2k tokens)

# Full manifest view
blue context show
# → Shows manifest with injection status per source

# Verbose audit
blue context show --verbose
# → Complete audit trail with timestamps and hashes

MCP equivalent: blue_context_status tool.

Security Model

1. Checksum verification - Manifest changes are detectable
2. Scope boundaries - Cannot reference outside project root without allow_external: true
3. Sensitive pattern deny-list - .env, *credentials*, *secret* blocked by default
4. Audit logging - Every injection logged: timestamp, source, content_hash, session_id

Generated Artifacts

Condensed knowledge files (e.g., knowledge/blue-adrs.md) must be generated, not hand-edited:

# Header in generated file
# Generated: 2026-01-25T12:00:00Z
# Source: .blue/docs/adrs/*.md
# Commit: abc123
# Regenerate: blue knowledge build

Build step updates manifest atomically with artifact regeneration.

Plugin Architecture

Plugins register URI schemes and salience triggers:

plugins:
  - uri: blue://jira/
    provides: [ticket-context, acceptance-criteria]
    salience_triggers:
      - commit_msg_pattern: "^[A-Z]+-\\d+"
      - file_annotation: "@jira"

Orchestrator handles budget allocation based on active triggers.

Implementation

Phase 1: Foundation

• Define manifest schema (JSON Schema)
• Implement blue context show command
• Refactor hooks/session-start to read manifest
• Add audit logging

Phase 2: MCP Resources

• Implement resources/list handler
• Implement resources/read handler for blue:// URIs
• Add URI resolution for all document types

Phase 3: Dynamic Activation

• Implement refresh triggers
• Add relevance graph computation
• Implement staleness detection and warnings

Consequences

Positive

• Single source of truth for injection policy
• Auditable, debuggable context delivery
• Graceful degradation if MCP fails
• Plugin extensibility without forking
• Token budget management

Negative

• Additional complexity vs. simple file concatenation
• Requires manifest maintenance
• MCP Resource implementation effort

Neutral

• Shifts context curation from implicit to explicit

Related

• Spike: Context Injection Mechanisms
• Spike: ADR Porting Inventory
• Dialogue: RFC Consolidation
• ADR 0005: Single Source
• ADR 0004: Evidence

---

Drafted from alignment dialogue with 12 domain experts achieving 95% convergence.