Context Architecture

The problem with context today

AI coding agents are remarkably capable at generating code, but they share a fundamental weakness: they operate with incomplete and unstructured knowledge of the projects they work on. When an agent needs to implement a feature, it has to figure out which specifications govern the relevant files, what architectural decisions constrain the design, and which norms apply to the codebase. Today, agents solve this in one of three ways, and all three are inadequate.

Manual injection. The developer pastes specs, READMEs, and code snippets into the prompt. This works for small tasks, but scales poorly. The developer becomes a human context router, deciding what the agent needs to see before the agent even starts reasoning. Context is incomplete, biased by what the developer remembers, and impossible to reproduce.

RAG and embedding search. The agent queries a vector store for “relevant” documents. This approach is probabilistic: it returns documents that are semantically similar to the query, but offers no guarantee that the results are complete, correct, or even relevant to the actual task. A specification that uses different terminology than the query may never surface. A critical architectural decision made six months ago may rank below a recent README edit.

Dump everything. The entire codebase or documentation set is loaded into the context window. This works until it doesn’t — which is the moment the project exceeds the token budget. Even when it fits, the agent spends tokens processing irrelevant information, diluting its attention on what actually matters.

Context Architecture is a fourth approach: deterministic, link-driven context assembly. Instead of searching for relevant context or relying on humans to supply it, the agent follows explicit links between artifacts to assemble exactly the context it needs.

What is Context Architecture?

Context Architecture is an information architecture — a structured way to organize project knowledge so that both humans and AI agents can navigate it predictably. It is described in the paper Context Architecture: An Information Architecture for AI-Assisted Software Development, and Contextia is its reference implementation.

The core thesis is this:

The central claim

If project knowledge is organized into typed artifacts with explicit links between them, an AI agent can deterministically assemble the right context for any task — without semantic search, without embeddings, and without human intervention.

This is not a new idea in software engineering. Traceability matrices, design documents, and requirements management systems have existed for decades. What is new is the consumer: an AI agent that can invoke tools, follow links, and build its own context window programmatically. Context Architecture provides the structure that makes this possible.

The three layers

Context Architecture organizes project knowledge into three layers, each serving a distinct purpose:

Identity layer

The identity layer answers: who is this project?

It consists of a single file — identity.md — that provides the project’s name, purpose, tech stack, and high-level description. This is the first thing any agent (or human) reads when entering the project. It is always loaded into context as an MCP resource.

---
project: my-api
version: "2.1"
languages: [python]
frameworks: [fastapi, sqlalchemy]
---

# My API

A REST API for managing customer subscriptions.
Built with FastAPI and SQLAlchemy, deployed on AWS ECS.

The identity layer is deliberately small. Its job is orientation, not detail. An agent reading identity.md knows enough to calibrate its assumptions — which language, which framework, what domain — before diving deeper.

System layer

The system layer answers: what are the rules?

This layer contains the durable knowledge that persists across tasks and sessions:

Directory	Purpose	Example
system/specs/	Behavioral contracts for components	SPEC-AUTH-001.md — how authentication works
system/norms/	Coding standards and conventions	NORM-ERROR-001.md — error handling patterns
system/rationale/	Architectural decisions and their reasoning	DEC-DB-001.md — why PostgreSQL over MongoDB

Each artifact is a Markdown file with YAML frontmatter that declares its type, status, relationships, and metadata. The frontmatter is not decoration — it is the structure that enables deterministic navigation.

---
type: spec
id: SPEC-AUTH-001
title: Authentication and Authorization
status: current
links:
  decisions: [DEC-AUTH-001, DEC-AUTH-002]
  norms: [NORM-ERROR-001, NORM-LOG-001]
paths:
  - src/auth/**
  - src/middleware/auth.py
---

# Authentication and Authorization

Users authenticate via OAuth 2.0 with PKCE flow...

The links field is what makes deterministic context assembly possible. When an agent loads this spec, it knows exactly which decisions and norms are relevant — not because they were similar in embedding space, but because a human explicitly connected them.

Operational layer

The operational layer answers: what are we doing right now?

This layer contains transient state tied to active work:

Directory	Purpose	Lifecycle
work/tasks/	Work orders with linked specs	Created at task start, completed at finish
work/plans/	Step-by-step implementation plans	Lives with the task
work/active/{task}/logs/	Session logs recording what happened	Accumulated during work
work/active/{task}/proposals/	Proposed spec changes for review	Promoted or discarded
work/active/{task}/scratch/	Temporary working notes	Discarded after task

The operational layer is explicitly transient. Tasks complete. Plans are executed. Logs are archived. But the knowledge they generate — new specs, updated decisions, refined norms — flows upward into the system layer, where it persists.

How layers connect

The power of Context Architecture comes from the connections between layers. These connections are explicit, declared in frontmatter, and navigable programmatically.

TASK-042
  ├── implements: [SPEC-AUTH-001, SPEC-SESSION-003]
  ├── follows: [NORM-ERROR-001]
  └── informed_by: [DEC-AUTH-002]

SPEC-AUTH-001
  ├── decisions: [DEC-AUTH-001, DEC-AUTH-002]
  ├── norms: [NORM-ERROR-001, NORM-LOG-001]
  └── paths: [src/auth/**, src/middleware/auth.py]

src/auth/handler.py
  └── @spec SPEC-AUTH-001 (annotation in code comment)

When an agent runs contextia context TASK-042, the system follows these links to assemble a complete context bundle:

1. Load the task and its metadata
2. Follow implements to load the referenced specs
3. Follow each spec’s decisions and norms links
4. Include the paths fields so the agent knows which code files are governed
5. Respect the token budget, using progressive disclosure to fit within limits

Every step is deterministic. Given the same task and the same .contextia/ directory, the same context is always produced. There is no ranking, no scoring, no probability involved.

Why determinism matters

Deterministic assembly means context is auditable. If an agent makes a mistake, you can inspect exactly what it was given. If a spec was missing from context, you can trace exactly which link was absent. This is impossible with RAG, where the retrieval is a black box.

Context Architecture vs. traditional approaches

Property	Manual injection	RAG / embeddings	Context Architecture
Completeness	Depends on developer memory	Probabilistic, no guarantees	Guaranteed by link structure
Reproducibility	Low	Low (depends on query phrasing)	Exact: same links, same result
Auditability	None	Opaque ranking scores	Full: every link is traceable
Maintenance cost	High (humans route context)	Medium (index management)	Low (links maintained with code)
Token efficiency	Variable	Poor (irrelevant results)	Good (only linked artifacts)
Setup cost	None	High (embedding pipeline)	Medium (frontmatter authoring)

The role of Contextia

Contextia is the tooling that makes Context Architecture practical. Without tooling, maintaining frontmatter links, validating references, and assembling context would be manual drudgery. Contextia automates the mechanical parts:

• contextia init scaffolds the .contextia/ directory with sensible defaults
• contextia new generates new artifacts from templates with correct frontmatter
• contextia find searches across artifacts by type, status, tags, and text
• contextia context assembles context by following links from a task
• contextia check validates that all links resolve and annotations match specs
• contextia refresh scans code for @spec annotations and updates the index

The MCP server exposes the same capabilities as tools that AI agents invoke directly. The agent does not copy-paste from a CLI — it calls find_spec or load_context programmatically, receiving structured results optimized for its context window.

CLI (humans)    →  core.context(root, task_id)  →  formatted for terminal
MCP (AI agents) →  core.context(root, task_id)  →  formatted for LLM context

Both interfaces call the same core logic. The difference is only in formatting: humans get colors and tables, agents get compact text optimized for token efficiency.

Guiding principles

Context Architecture rests on several design principles that inform every decision in Contextia:

Explicit over implicit. Links between artifacts are declared in frontmatter, not inferred. If a spec governs a file, that relationship is written down. Inference is brittle; declaration is reliable.

Deterministic over probabilistic. Given the same inputs, context assembly always produces the same output. There are no embedding models, no similarity thresholds, no ranking algorithms.

Structured over narrative. Frontmatter provides machine-readable structure. Markdown body provides human-readable explanation. Both are needed. Structure enables tools; narrative enables understanding.

Two layers over one. System knowledge and operational work are separated because they have different lifecycles. Mixing them creates artifacts that are simultaneously permanent specifications and temporary task notes.

Progressive disclosure over all-or-nothing. Context has a budget. The --depth flag controls how much of each artifact is loaded: meta (frontmatter only), summary (first section), or full (entire document). This lets the agent start shallow and go deep only where needed.

Bidirectional links over one-way references. Specs link down to code paths. Code annotations link up to specs. Both directions are maintained and validated. A broken link in either direction is caught by contextia check.

Note

Context Architecture is not a replacement for good documentation practices. It is a structure that makes existing documentation navigable by AI agents. The quality of the context depends on the quality of the artifacts — Contextia ensures the agent can find them and assemble them correctly.