Context Layers
Description
Section titled “Description”Context does not arrive at an agent in one undifferentiated block. It has natural scope boundaries that determine how broadly it applies, how frequently it changes, and who is responsible for maintaining it. Treating all context as equivalent and pasting everything into a single prompt violates the density constraint described in Context and creates a deeper problem: it becomes difficult to reason about which parts are current, which parts an agent already holds, and which parts must be resolved before dispatch.
This page defines five canonical scope layers, establishes their change rate and ownership, and describes the dispatch-time resolution problem: the same task may be sent to agents with very different existing context states.
The Five Layers
Section titled “The Five Layers”1. World Context
Section titled “1. World Context”Scope: knowledge that is true regardless of who the agent is working for or what system it is running in.
Examples: widely understood programming patterns, language semantics, protocol standards, publicly documented API behavior, and general domain knowledge.
World context is the foundation layer. Agents absorb most of it through pre-training. It is not authored by any single team and is not directly owned. It changes on the timescale of years (language versions, protocol updates) and is treated as ambient unless a specific correction or override is required.
Who manages it: nobody directly. Surfaced as corrections or overrides when built-in understanding is wrong or outdated.
2. Organisation Context
Section titled “2. Organisation Context”Scope: knowledge about an organisation as a whole, including standards and non-negotiable constraints.
Examples: coding standards, security policy, naming conventions, approved toolchains, architectural principles, deployment policy, and data classification rules.
Organisation context applies across projects and repositories. It changes slowly and deliberately. It is typically the most stable authored layer and the most authoritative.
Who manages it: platform or engineering leadership. Distributed as a context package (see Context Development Lifecycle) and versioned explicitly so agents can detect stale copies.
3. Project Context
Section titled “3. Project Context”Scope: knowledge about a specific product, service cluster, or delivery initiative, potentially spanning multiple repositories.
Examples: product domain model, cross-service contracts, architecture decisions for the product, accepted technical debt, roadmap constraints, sprint goals, and known failure modes.
Project context is narrower than organisation context but wider than any single repository. It changes at the pace of product evolution.
Who manages it: the team or cohort responsible for the product. A project context package should be a declared dependency of any Agent Pool assigned to that project.
4. Repository Context
Section titled “4. Repository Context”Scope: knowledge about a single repository, including structure, conventions, active work, and current state.
Examples: module layout, local naming conventions, build system specifics, active branches and open PRs, known issues, test coverage state, changed hotspots, dependency graph.
Repository context is largely derivable from the repository itself. This is where context engines transform raw repository state into structured, queryable context rather than requiring agents to re-derive it by reading files. Repository context changes as fast as the codebase.
Who manages it: context engines for structural facts and teams for conventions and decision records. Any new agent assigned to repository work should pull current repository context on demand.
5. Task Context
Section titled “5. Task Context”Scope: knowledge specific to the current unit of work and its execution so far.
Examples: the issue or ticket being addressed, plan artifact, prior tool outputs in this run, test results, review comments, interim decisions, and correlation IDs.
Task context is the most ephemeral layer. It is assembled at dispatch time and extended as work progresses. Task context from one run must not silently contaminate another run.
Who manages it: the Orchestrator.
Dispatch-Time Context Resolution
Section titled “Dispatch-Time Context Resolution”The layers above describe where context lives and who owns it. The harder problem is what to do at dispatch time when the target agent may already hold some layers, may hold them at a different version, or may have accumulated drift.
The Problem: Agents Are Not Context-Identical
Section titled “The Problem: Agents Are Not Context-Identical”Long-running agents are not blank slates. They carry persistent memory, prior task residue, and potentially stale context packages. The orchestrator cannot safely assume two agents of the same type have equivalent context states.
Resolution Strategy: Declare, Diff, Inject
Section titled “Resolution Strategy: Declare, Diff, Inject”1. Declare what the task requires
A plan artifact declares required context references: organisation version, project package, repository target, and task state prerequisites.
2. Diff against what the agent already holds
For long-running agents, query declared context state and classify each layer:
- Current and present - no action needed.
- Present but stale - inject delta, inject full replacement, or route elsewhere.
- Absent - inject before or with task payload.
For ephemeral agents, all layers are absent by definition.
3. Inject the delta
Inject lower layers as durable packages and higher layers as run-scoped dispatch payload.
Injection must be explicit. If context state cannot be verified, treat it as absent.
Priority and Override Rules
Section titled “Priority and Override Rules”When layers conflict, narrower scope wins: task over repository, repository over project, project over organisation.
Exception: hard organisation constraints (for example security and governance) are not overridable by narrower layers.
Relationship to Agent Types
Section titled “Relationship to Agent Types”Ephemeral agents receive full context inject at start. This is deterministic but has larger initial context cost.
Long-running agents require state negotiation and diff before dispatch. This can reduce repeated injection cost but risks stale context if diff is skipped.
The Agent Pool declares baseline context packages for an agent class. The Orchestrator verifies and resolves runtime gaps.
Related Concepts
Section titled “Related Concepts”- Context - Foundational model for density, hierarchy, curation, and evolution.
- Context Development Lifecycle - How context packages are generated, evaluated, distributed, and observed.
- Context Evaluation - Metrics for context quality.
- Agent - Lifecycle determines context resolution strategy.
- Skills - A packaging and distribution pattern for bounded context artifacts.
- Context Engines - Tooling layer that makes repository and project context queryable at runtime.