Agent Context Planner

A deterministic, hash-aware context planner for coding agents.

It answers five questions before an agent starts reading a repository:

  1. Which files are authoritative?
  2. Which files are relevant to this task?
  3. Which files changed?
  4. Which downstream files are affected?
  5. Which unchanged files can be represented by a hash-bound structural digest?

The result is an explainable context plan:

  • MUST_READ_FULL
  • READ_VALID_DIGEST
  • MACHINE_VALIDATE_ONLY
  • ON_DEMAND
  • EXCLUDED
  • MISSING_REQUIRED_ARTIFACT
  • CONTRACT_DRIFT

Why this is not RAG

Search finds relevant text. Agent Context Planner decides what an agent must read, may summarize, should validate, or must exclude—and explains why.

Installation

python3 -m pip install -e .

No runtime dependencies beyond the Python standard library.

Quick start

contextctl init
contextctl verify
contextctl plan --bundle default
contextctl digest --bundle default
contextctl plan --bundle default
contextctl record --bundle default

Configuration lives in .context/:

.context/
├── canonical_sources.json
├── dependency_rules.json
└── bundles/
    └── default.json

Local cache lives in .cache/context/ and should not be committed.

Core model

Canonical Source Map
        ↓
Context Bundle
        ↓
Hash Preflight
        ↓
Dependency Propagation
        ↓
Hash-bound Digest
        ↓
Final Context Plan

Safety properties

  • Repository-relative paths only
  • .. and absolute paths rejected
  • Symlink escapes rejected
  • SHA-256 is the content-change source of truth
  • Stale digests are never accepted
  • plan is read-only
  • record is explicit
  • No module imports during Python digest generation
  • No network access

Generic agent skill

See skills/generic-context-planner/SKILL.md.

Project status

This is an initial v0.1 scaffold suitable for dogfooding. The configuration format may evolve before v1.0.