context-manager

Maintain a set of compiled context artifacts so any agent can spawn stateless and still get deep, up-to-date understanding without rereading the entire repo.

CMS produces:

• BOOT_CONTEXT - stable, curated project brain
• DELTA_CONTEXT - what changed since last compile
• Feature bundles - compartmentalized working sets for parallel agents
• MANIFEST - hashes, pointers, provenance for deterministic rehydration

Agents consume these artifacts on startup instead of scanning the repo.

All artifacts live in .claude/compiled/:

```

.claude/compiled/

├── BOOT_CONTEXT.md # Stable project brain (~500-1500 tokens)

├── DELTA_CONTEXT.md # Recent changes (~200-500 tokens)

├── FEATURES/ # Working-set context slices

│ ├── .md

│ └── ...

├── MANIFEST.json # Hashes, timestamps, provenance

└── FEATURE_MAP.yaml # Feature definitions

```

BOOT_CONTEXT.md

Goal: The smallest truthful "project brain" that doesn't change often.

Contains:

• Architecture overview
• Invariants and constraints
• Key flows
• File map
• Conventions
• "How to work here" guidance

Rules:

• Keep dense but stable
• Decision-oriented, not narrative
• Never include giant code blocks; only pointers
• Target: 500-1500 tokens

DELTA_CONTEXT.md

Goal: What changed since last compile, with implications.

Contains:

• Commit summary since baseline
• File changes with descriptions
• Behavior changes
• New decisions
• New open questions
• Agent action items

Rules:

• Always small (target: 200-500 tokens)
• Must answer: "What's different now and why it matters?"
• Reset on full compile

Feature Bundles (FEATURES/*.md)

Goal: Working-set context slices for parallel agents.

Each feature file includes:

• Purpose
• Key files (with line pointers where relevant)
• Invariants
• Current tasks
• Known issues
• Interface contracts (inputs/outputs)

MANIFEST.json

Goal: Deterministic rehydration + auditing.

Tracks:

• Hashes of source files considered
• Hashes of compiled artifacts
• Last compile time
• Commit baseline
• Feature definitions and membership

Every worker agent spawn uses this startup order:

1. Read .claude/compiled/BOOT_CONTEXT.md
2. Read .claude/compiled/DELTA_CONTEXT.md
3. If working on a scoped task: read .claude/compiled/FEATURES/.md
4. Only open raw files referenced by those docs

Hard prohibition: Do not scan directories or "rediscover architecture" unless CMS explicitly marks "unknown".

This is what makes the system save tokens.

Mode 1: Compile (Full Rebuild)

Triggers:

• "compile context" / "cms compile"
• No MANIFEST exists
• Major architecture changes
• BOOT_CONTEXT quality degraded (manual trigger)
• Baseline commit changed significantly

Output:

• BOOT_CONTEXT regenerated
• DELTA reset to "since compile"
• All features refreshed
• New MANIFEST written

Mode 2: Update (Incremental)

Triggers:

• "update context" / "cms update"
• New commits since baseline
• File timestamps changed
• Agent outcomes logged (new decisions/blockers)
• Feature bundle needs refresh

Output:

• DELTA_CONTEXT updated
• BOOT_CONTEXT updated only if stable knowledge truly changed
• Relevant feature bundles updated
• New MANIFEST written

Step 1: Establish Current State

```bash

PROJECT=$(basename $(pwd))

COMPILED_DIR=.claude/compiled

mkdir -p $COMPILED_DIR/FEATURES

# Get current git state

git rev-parse HEAD

git status --porcelain

```

Step 2: Read Key Architecture Files

Read to understand:

• Entry points (main files, index files)
• Configuration (package.json, tsconfig, etc.)
• Existing documentation (README, PROJECT.md)
• Core source files

Step 3: Generate BOOT_CONTEXT.md

Write using template from references/BOOT_CONTEXT_TEMPLATE.md:

```markdown

# BOOT_CONTEXT | |

[Dense overview - what this project IS]

[Rules that must never be broken]

[How data/control moves through the system]

[Critical files with purposes - NOT every file]

[Code style, naming, patterns to follow]

[Agent-specific guidance for this codebase]

```

Step 4: Generate DELTA_CONTEXT.md

On full compile, write:

```markdown

# DELTA_CONTEXT | |

Compiled from: [commit hash]

No prior delta - clean compile.

None - fresh compile.

Read BOOT_CONTEXT, then proceed with assigned task.

```

Step 5: Generate Feature Bundles

Read FEATURE_MAP.yaml (create if missing using template).

For each feature, generate FEATURES/.md:

```markdown

# Feature:

[What this feature does]

• path/file.ts:L10-50 - [what it does]

[Rules for this feature]

• [ ] Task from CONTEXT.md if applicable

• [Issue] → [Workaround]

Inputs: [what this feature receives]

Outputs: [what this feature produces]

Depends on: [other features]

```

Step 6: Write MANIFEST.json

```json

{

"compiled_at": "2026-01-20T23:00:00-05:00",

"mode": "compile",

"baseline": {

"git_commit": "abc123def",

"dirty": false

},

"inputs": {

"files": {

"src/index.ts": "sha256:...",

"package.json": "sha256:..."

}

},

"outputs": {

"BOOT_CONTEXT.md": "sha256:...",

"DELTA_CONTEXT.md": "sha256:...",

"FEATURES/api.md": "sha256:..."

},

"features": {

"api": {

"files": ["src/api/"],

"keywords": ["endpoint", "route", "handler"]

}

}

}

```

Step 7: Confirm

```

CMS Compile Complete

BOOT_CONTEXT.md: Generated (1,234 tokens)

- Architecture: 5 sections

- File map: 12 files

DELTA_CONTEXT.md: Reset (clean compile)

Features: 3 bundles

- api: 4 files tracked

- ui: 6 files tracked

- data: 2 files tracked

MANIFEST.json: Written

Baseline: abc123def

Compiled: 2026-01-20 23:00

```

Step 1: Read Existing Manifest

```bash

MANIFEST=.claude/compiled/MANIFEST.json

# If no manifest, trigger full compile instead

if [ ! -f "$MANIFEST" ]; then

echo "No manifest - run compile first"

exit 1

fi

BASELINE=$(jq -r '.baseline.git_commit' $MANIFEST)

```

Step 2: Detect Changes

```bash

# Files changed since baseline

git diff --name-only $BASELINE HEAD

# Uncommitted changes

git status --porcelain

```

Step 3: Classify Changes

Bucket each changed file:

• Hot files (core): affects architecture/flows
• Feature files: belongs to a feature bundle
• Noise: docs, formatting, unrelated

Step 4: Extract Facts

For each relevant changed file, record high-level changes:

• New endpoint added
• Function behavior changed
• Config flag added
• File created/deleted

Keep it factual, not narrative.

Step 5: Update DELTA_CONTEXT.md

```markdown

# DELTA_CONTEXT | |

Prior compile: [old commit] → Current: [new commit]

• src/api/routes.ts - Added /users/:id endpoint
• src/utils/cache.ts - NEW: caching utility
• config.json - Added CACHE_TTL setting

• New endpoint requires auth middleware
• Caching may affect test isolation

• Use in-memory cache for v1 (rationale: simplicity)

• Cache invalidation strategy TBD

1. When working on API: note new /users/:id endpoint
2. When writing tests: account for cache side effects

```

Step 6: Check if BOOT Needs Update

BOOT_CONTEXT changes only if:

• Architecture changed (new major component)
• Invariants changed
• File map changed (new critical file)
• Canonical flow changed

If only DELTA-level changes, BOOT stays stable.

Step 7: Update Feature Bundles

For each feature whose files changed:

• Update key files list
• Update current tasks
• Update pitfalls/gotchas
• Update interface contracts if changed
• Ensure cross-links valid

Step 8: Write New MANIFEST

Update all hashes, timestamp, and baseline.

Step 9: Confirm

```

CMS Update Complete

BOOT_CONTEXT.md: Unchanged

DELTA_CONTEXT.md: Updated

- 3 file changes

- 1 new decision

- 2 agent actions

Features: 1 updated

- api: +1 file, tasks updated

MANIFEST.json: Updated

Baseline: abc123 → def456

Updated: 2026-01-20 23:30

```

FEATURE_MAP.yaml

```yaml

# Feature definitions for parallel agent work

api:

description: REST API endpoints and handlers

files:

- src/api/

- src/routes/

keywords: ["endpoint", "route", "handler", "middleware"]

depends_on: []

ui:

description: Frontend components and views

files:

- src/components/

- src/views/

keywords: ["component", "render", "useState", "props"]

depends_on: [api]

data:

description: Data layer and storage

files:

- src/models/

- src/db/

keywords: ["model", "schema", "query", "database"]

depends_on: []

```

Feature Bundle Rules

A feature bundle must include:

• What it owns (files)
• What it depends on (other features)
• What it guarantees (contracts)
• Where to find truth (authoritative files)

Per-Agent Runtime Notes

```

.claude/runtime/agents//SESSION.md

```

Each agent writes its own session notes here.

Project-Wide State

.claude/CONTEXT.md remains the official shared human-approved state.

Agents propose updates, CMS (or human) merges them.

Merge Rule

• CMS can ingest SESSION logs from agents
• CMS must NOT overwrite shared context silently
• CMS writes:

- "Proposed additions" into DELTA

- "Conflicts detected" section if agents diverged

| Skill | Relationship |

|-------|--------------|

| session-save | Human-facing session handoff; CMS is agent-facing compiled context |

| context-extract | Verbose history archive; CMS is optimized snapshot |

| onboard | Should read BOOT_CONTEXT + DELTA if available |

When to Use Each

| Need | Use |

|------|-----|

| Quick human handoff | session-save |

| Full history archive | context-extract |

| Agent spawning | context-manager (this) |

| Getting up to speed | onboard + CMS artifacts |

Templates in references/:

• BOOT_CONTEXT_TEMPLATE.md - Template for BOOT_CONTEXT
• DELTA_CONTEXT_TEMPLATE.md - Template for DELTA_CONTEXT
• FEATURE_TEMPLATE.md - Template for feature bundles
• MANIFEST_SCHEMA.json - JSON schema for MANIFEST
• FEATURE_MAP_TEMPLATE.yaml - Template for feature definitions