Cartographic Agentic Contexting

Cartographic Agentic Contexting is a framework to curate a cascaded contextual topology across evolving software ecosystems, through which both humans and agents sustain clean & navigable context over time.

Instead of treating repository instructions as one large prompt, this framework separates context into five main concepts:

• Context Key An initial preparatory contextual block to understand the system
• Context Tree The hierarchy of context across the entire project; the topology of the project itself
• Context Map An individual collection of reference pointers
• Context Route A predefined repeatable traversal used to rebuild a prior context state
• Context Atlas The index of existing Context Maps and Context Routes

The goal is to help agents operate with the smallest sufficient context: enough information to work coherently in the current context, without loading unrelated instructions, architecture notes, examples, validation steps, etc.

Why This Matters

Modern software repositories accumulate context faster than humans or agents can safely consume it. Instructions, architecture notes, validation steps, conventions, examples, exceptions, etc. often end up scattered across files, duplicated across folders, or compressed into one oversized prompt.

By treating the repository as something to be intentionally mapped, scoped, indexed, and traversed, this framework helps agents resolve only the context needed for the work at hand.

Governing Principle

"Resolve the smallest sufficient context for the current operating context"

This solves common token wasting behavior:

• Context Bloat placing too much detail in one file
• Context Overfitting placing overly narrow detail in one file
• Context Duplication repeating the same detail across multiple files

Context Key

The Context Key is the basic expanded structure of this system, and must be placed at the very top of every AGENTS.md file -- this preps the agent with the requisite expanded understanding. This boilerplate key functions as a minimal operating manual for interpreting Maps, Routes, and the Atlas before any project-specific instructions are loaded.

Note: as is popular convention, it is assumed that the agent will look for an AGENTS.md file initially. Adjust accordingly for models that do not match this convention.

This repository uses additional context file types.

| Type | File name | Purpose | When to read |
|---|---|---|---|
| Map | `AGENTS.map.<name>.md` | Pointers for one area, workflow, or concern | The task matches the map name or purpose |
| Route | `AGENTS.route.<name>.md` | Ordered traversal to rebuild a prior context state | Task setup depends on reading context in sequence |
| Atlas | `AGENTS.atlas.md` | Index of available maps and routes | Choosing which maps and/or routes to use |

Context Tree

A Context Tree is the hierarchical totality of all AGENTS.md files in the project, and their relation to each other.

Each AGENTS.md file contains the necessary location-aware metadata for the folder where it is located. Together, these files define the project’s contextual topology.

Context Tree files are located in each folder as:

AGENTS.md

Each AGENTS.md file defines context for one repository location:

• The Root file defines repository-wide context that applies across the project
• Branch files define context for intermediate scopes within narrower subtrees
• Leaf files define context for the most specific areas of the project

Example tree:

/AGENTS.md
  → /apps/api/AGENTS.md
    → /apps/api/src/auth/AGENTS.md

The Context Tree answers:

"What contextual locations exist in this project?"
"How are those locations arranged by scope, inheritance, and containment?"

The tree is not a generated artifact, it is the project’s contextual topology as expressed through AGENTS.md files.

Location-aware metadata

Each AGENTS.md file must contain metadata that describes its role in the Context Tree:

---
node: root | branch | leaf
scope: path/
parent: path | null
children: [...]
---

The metadata describes a tree node and its durable relationships.

• node defines its overall tree position
• scope narrows the context to its folder's locality
• parent identifies the parent context that this node inherits from
• children lists immediate child tree descendants (if any)

The metadata is for parsing.
The heading is for humans.

Example tree nodes

Root tree node

---
node: root
scope: .
parent: null
children:
  - apps/web/AGENTS.md
  - apps/api/AGENTS.md
  - packages/ui/AGENTS.md
---

# /AGENTS.md
Rules: use pnpm, keep changes small, run relevant tests.

Branch tree node

---
node: branch
scope: apps/api/
parent: ../../AGENTS.md
children:
  - src/auth/AGENTS.md
  - src/billing/AGENTS.md
---

# /apps/api/AGENTS.md
Rules: controllers route requests; services hold business logic.

Leaf tree node

---
node: leaf
scope: apps/api/src/auth/
parent: ../../AGENTS.md
children: []
---

# /apps/api/src/auth/AGENTS.md
Rules: protect sensitive auth values in logs and examples.
Validate: pnpm --filter api test auth.

Together, these files define the Context Tree.

Context Map

A Context Map is an individual and optional collection of reference pointers. It is created by necessity when a particular operating context needs an explicit collection of references.

A map links important contexts across the tree or externally, it is not restricted to the tree hierarchy, and does not need to follow parent-child relationships.

A map is represented as an individual file named:

AGENTS.map.<name>.md

The <name> identifies the operating context or purpose of the map.

Examples:

AGENTS.map.auth.md
AGENTS.map.release.md
AGENTS.map.billing-migration.md

Context Maps are located where appropriate.

A map answers:

"Which context references are needed for this operating context?"
"Why are these references grouped together?"
"What parts of the tree or external context does this map point to?"

Example map contents:

# AGENTS.map.auth.md

This map collects context references commonly needed for authentication work.

references:
  - /AGENTS.md
  - /apps/api/AGENTS.md
  - /apps/api/src/auth/AGENTS.md
  - /packages/db/AGENTS.md
  - /packages/observability/AGENTS.md
  - https://example.com/external-auth-spec

The references may point down one branch, across multiple branches, into related areas of the project, or to external context. The map is a contextual collection, not a new hierarchy.

Context Route

A Context Route is an individual and predefined stepped traversal through the project.

A route is meant to rebuild a prior context state that was established by traversing the project. It enables contextual repeatability by making a previously useful traversal explicit and reusable.

Routes are useful when an agent's contextual priming is necessary to performing the same task again. Instead of rediscovering the relevant context each time, an agent can follow the same route to reconstruct the context state needed for that task.

A route is not required; it is created by necessity when a repeated navigation path should be preserved because the order of exposure matters.

A route is represented as an individual file named:

AGENTS.route.<name>.md

The <name> identifies the route purpose.

Examples:

AGENTS.route.auth.md
AGENTS.route.release.md
AGENTS.route.incident-response.md

Routes are located where appropriate and are made discoverable by the root Context Atlas.

A route answers:

"What stepped route should an agent follow to rebuild a useful context state?"
"Which context reference comes first?"
"Which references come next?"
"Where does the route end?"
"What task does this route prepare the agent to perform again?"

Example route content:

# AGENTS.route.auth.md

This route rebuilds the context state needed to perform authentication work again.

route:
  - /AGENTS.md
  - /apps/api/AGENTS.md
  - /apps/api/src/auth/AGENTS.md
  - /packages/db/AGENTS.md

A route is about ordered contextual priming: replaying a useful traversal so an agent can rebuild the context state needed to perform a repeated task, or to return to the same state at a later time.

Context Atlas

A Context Atlas is the index of existing Context Maps and Context Routes.

It is represented as an individual file named:

AGENTS.atlas.md

The atlas is located at the project root.

The atlas does not replace the tree and does not define context by itself -- it exists to make previously defined maps and routes discoverable.

The atlas answers:

"Which maps and routes already exist?"
"What is each map and route for?"

Example atlas contents:

# AGENTS.atlas.md

maps:
  - file: /apps/api/AGENTS.map.auth.md
    context: authentication work

  - file: /docs/releases/AGENTS.map.release.md
    context: release preparation

routes:
  - file: /apps/api/AGENTS.route.auth.md
    context: rebuild authentication context state

  - file: /docs/releases/AGENTS.route.release.md
    context: ordered release preparation

The atlas is useful when a repository has multiple maps and routes -- a small repository may not need one.

Map vs Route

Context Map answers:

"Which references are relevant to this operating context?"

Context Route answers:

"What sequence should an agent follow to rebuild a useful prior context state?"

A map is useful when the agent needs a collection of related references. A route is useful when the order of exposure matters because the agent is being primed to perform a repeated task.

For example, authentication work may have a map containing references to API, database, logging, and security policy context -- that mapping defines what matters.

A release-preparation route may walk through repository rules, changelog policy, test requirements, deployment steps, and rollback notes in a specific order -- that routing rebuilds a prior context state.

How the Concepts Work Together

A typical resolution flow is:

1. Read the tree from available AGENTS.md files.
2. Check the root AGENTS.atlas.md if an atlas exists.
3. Reuse an existing AGENTS.map.<name>.md if it matches the operating context.
4. Follow an existing AGENTS.route.<name>.md if the atlas lists a relevant predefined traversal.
5. Create a new map only when an explicit reference collection is needed.
6. Load only the context references needed for the current operating context.

The responsibilities stay separate:

Tree  → project topology and hierarchy
Map   → reference pointer collection
Route → repeatable contextual priming and context-state reconstruction
Atlas → index of existing maps and routes

Inheritance and Precedence

Context flows downward through the Context Tree.

Root context
  → inherited by branch context
    → specialized by leaf context

• Inheritance belongs to the Context Tree
• Pointer collection belongs to Context Maps
• Map and Route indexing belongs to the Context Atlas
• Repeatable contextual priming belongs to Context Routes

Token Savings

The primary token savings come from avoiding broad, repeated context loading. Instead of pulling every root-level instruction, architecture note, sibling package convention, validation rule, and prior example into every task, an agent can resolve the relevant Context Tree chain and then follow only the maps or routes that match the current operating context.

Typical savings depend on how much irrelevant context was previously loaded:

Repository workflow	Expected context-token savings per task
Already well-scoped prompts or small touched area	10%–30%
Large repository with scattered docs and conventions	30%–60%
Very large repository with broad default context loading	60%–80%+

Example contrast:

Typical Agentic Workflow:
Root instructions -> broad architecture docs -> unrelated package notes -> validation docs → task files → agentic operation

Operationalized Cartographic Agentic Contexting Workflow:
Context Key ->  relevant Context Tree chain + Context Atlas → matching Context Map or Context Route -> task files → agentic operation

The savings are workload-dependent, not automatic. They are highest when the framework prevents agents from repeatedly loading unrelated project areas, stale instructions, or full-repository documentation for localized work.

Initial adoption also has a token cost. Applying the system to an unmapped large repository may require substantial upfront context consumption while the repo is surveyed and the first Tree, Map, Route, and Atlas artifacts are created. Treat that setup cost as a capital expense: it pays back fastest in repositories where agents repeatedly perform work across the same high-churn or high-confusion areas.

A practical adoption strategy is to avoid operationalizing the whole repository at once. Start with the most active or context-heavy areas, add maps only when cross-tree references are repeatedly needed, and add routes only when a traversal order has proven useful enough to preserve.

Relationship to Existing Patterns

This framework resembles nested AGENTS.md, CLAUDE.md, Copilot instructions, Cursor rules, cascading configuration files, and hierarchical retrieval systems.

The distinction is that the context concerns are separated instead of mixed together:

• Project topology and context hierarchy
• Reference pointer collections
• Indexing of existing maps and routes
• Repeatable contextual priming through predefined routes

It is not merely “put instructions near code.” It is a context-resolution model for agentic development.

Example Repository

A complete example repository is available under exampleRepo/. It shows Tree, Map, Atlas, and Route files working together as real repository artifacts rather than only conceptual examples.

The example includes:

• nested AGENTS.md files for root, branch, and leaf Context Tree nodes
• a root AGENTS.atlas.md that indexes available maps and routes
• API Context Maps and a Context Route for authentication work
• release, database, observability, web, and UI context files
• small application files that give the context artifacts something concrete to describe

Use this example to see how the framework can be applied across a small repository.