Context Manager Skill (CMS)

Triggers: "compile context", "update context", "cms compile", "cms update", "refresh context"

Purpose

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.

Output Artifacts

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
│   ├── <feature>.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

Agent Boot Contract

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/<feature>.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.

CMS Modes

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

Compile Protocol

Step 1: Establish Current State

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:

# BOOT_CONTEXT | <project> | <timestamp>

## Architecture
[Dense overview - what this project IS]

## Invariants
[Rules that must never be broken]

## Key Flows
[How data/control moves through the system]

## File Map
[Critical files with purposes - NOT every file]

## Conventions
[Code style, naming, patterns to follow]

## How to Work Here
[Agent-specific guidance for this codebase]

Step 4: Generate DELTA_CONTEXT.md

On full compile, write:

# DELTA_CONTEXT | <project> | <timestamp>

## Baseline
Compiled from: [commit hash]
No prior delta - clean compile.

## Changes
None - fresh compile.

## Agent Actions
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/<feature>.md:

# Feature: <name>

## Purpose
[What this feature does]

## Key Files
- `path/file.ts:L10-50` - [what it does]

## Invariants
[Rules for this feature]

## Current Tasks
- [ ] Task from CONTEXT.md if applicable

## Known Issues
- [Issue] → [Workaround]

## Interface
**Inputs:** [what this feature receives]
**Outputs:** [what this feature produces]
**Depends on:** [other features]

Step 6: Write MANIFEST.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

Update Protocol

Step 1: Read Existing Manifest

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

# 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

# DELTA_CONTEXT | <project> | <timestamp>

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

## Changes Since Baseline
- `src/api/routes.ts` - Added /users/:id endpoint
- `src/utils/cache.ts` - NEW: caching utility
- `config.json` - Added CACHE_TTL setting

## Implications
- New endpoint requires auth middleware
- Caching may affect test isolation

## New Decisions
- Use in-memory cache for v1 (rationale: simplicity)

## Risks / Blockers
- Cache invalidation strategy TBD

## Agent Actions
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 System

FEATURE_MAP.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)

Multi-Agent Safety

Per-Agent Runtime Notes

.claude/runtime/agents/<agent_id>/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

Integration with Existing Skills

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

Resources

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