context-kit

This is not a prompt library. It is infrastructure.

A version-controlled context layer for AI systems — a set of source-of-truth files that are composed and injected per surface (Slack, CRM, support, Gmail, …) by a runnable assembly engine, with CI validation and per-surface token-budget enforcement.

Hallucination is mostly a context problem, not a prompt problem. So the context lives as code: owned, reviewed, budgeted, and assembled deterministically — not pasted into a text box.

Reference implementation for a fictional company. The pattern is the product; the content is illustrative. The example business — Meridian Coffee Systems — and every brand, product, and competitor in it are invented.

---

30-second quickstart

pip install pyyaml
make manifest      # compute token counts, (re)generate manifest.yaml
make demo          # assemble + print the system prompt for slack-workflows, with a token report

Or directly:

python scripts/build-manifest.py
python scripts/assemble.py --surface slack-workflows
python scripts/assemble.py --surface crm-workflows --dry-run   # list files + tokens, no bodies
python scripts/validate.py                                      # CI guard

Requires Python 3.11+ and pyyaml. No frameworks.

---

Architecture

   context/  +  prompts/            scripts/assemble.py            per-surface
  ┌───────────────────────┐        ┌──────────────────┐        ┌────────────────┐
  │ core/      [all]       │        │ 1. select files  │        │ slack-workflows│
  │ catalog/   [all]       │        │    for surface   │        │ crm-workflows  │
  │ departments/ <dept>    │ ─────▶ │ 2. order by layer │ ─────▶ │ support-workfl.│
  │ prompts/    <surface>  │        │ 3. concatenate   │        │ gmail-workflows│
  │ _shared/   [all]       │        │ 4. enforce budget│        │ ...            │
  └───────────────────────┘        └──────────────────┘        └────────────────┘
         source files                 assembly engine               surfaces
              │                              ▲
              │   build-manifest.py          │
              └────────▶ manifest.yaml ──────┘
                 (computes tokens_approx; single source of truth)

Layer precedence (fixed): prompts/_shared → context/core → context/catalog → context/departments → prompts. A surface's assembled prompt is every populated file whose inject_into contains that surface or all, concatenated in that order.

---

How it works

• Every file carries front matter (title, owner, status, volatility, last_reviewed, inject_into, tokens_approx). inject_into decides which surfaces a file reaches.
• build-manifest.py is the single source of truth for token counts. Authors leave tokens_approx: 0; the script computes and writes manifest.yaml. CI runs it with --check and fails if the on-disk manifest is stale.
• assemble.py is the retrieval layer. It selects, orders, concatenates, and fails closed if a surface exceeds its token budget (config/budgets.yaml).
• validate.py is the CI guard. It fails the build on invalid front matter, a disallowed inject_into value, a populated file that is empty or contains a placeholder, a stale manifest, or any surface over budget.
• Stubs are first-class. A status: stub file is skipped by assembly and exempt from the placeholder check — so the stub→populate lifecycle is visible and safe.

---

What's in here

Path	What it is
context/core/	Company-wide truth injected into every surface ([all])
context/catalog/	What the company resells / makes / delivers ([all])
context/departments/	Function-specific knowledge (sales, marketing, operations, support)
prompts/	Per-surface task instructions; _shared/ holds rules for all surfaces
examples/	Gold-standard, reviewed outputs (here labeled illustrative)
scripts/	build-manifest.py, assemble.py, validate.py
config/budgets.yaml	Per-surface token budgets
tests/	Contract tests (pytest) mirroring the validator
docs/	Ownership model, contributing guide, changelog
.github/workflows/ci.yml	Runs validate.py + pytest on every push/PR

See DESIGN.md for the decisions behind it and docs/CONTRIBUTING.md for how to add or change context.

---

Every claim here is demonstrably true in the repo

• "CI validates the manifest is in sync" → build-manifest.py --check, run by validate.py and CI.
• "Budgets are enforced fail-closed" → assemble.py exits non-zero over budget; break a budget and make validate fails.
• "Stubs are skipped" → three stub files exist; assemble.py excludes them and tests/test_contract.py asserts it.

That accountability — README claims backed by a green CI check — is the point.