Context management

Early Access. Commands and behavior can change between releases.

Context is what an agent reads before it touches your code: your project instructions, a map of your project, and the engineering rules and memory of each repository it works in. This page explains what loads and when, what a context exemption is, and how to configure one.

How context works

Architech doesn’t load everything at once. Each agent gets the context its work needs, at the moment it needs it.

Context	Where it lives	When it loads
Project instructions	`AGENTS.md` or `CLAUDE.md`	Every session, in every mode, and every sub-agent Architech starts.
Context map	`.memory/context-map.md` at the project root	When the Orchestrator or Architect starts. A Developer or LLM-Whisperer gets only the map’s navigation block.
Rules and memory	`.engineeringrules/` and `.memory/` in each repository	Before an agent works in a repository: one load per repository it touches.
Command context	Declared by each command	When the command runs, plus extra rules only when the task calls for them.

The context map

The context map is your project’s table of contents: which repositories exist, what each one does and where things live. Onboarding creates it at the project root. The Orchestrator and the Architect read the whole map when they start, to plan across repositories. An agent dispatched for one task reads only the map’s navigation block: the lines between  and . That keeps its first load small. A map without that block, or a project without a map, is a warning, not a stop.

Rules and memory, per repository

Before an agent works in a repository, it loads that repository’s rules and memory. In a monorepo, an agent that changes two packages loads each package’s files separately, so each one is held to its own standards.

Agent	Loads for each repository it works in
Developer	`coding-rules`, `testing-rules`, repository context, `design-principles`
LLM-Whisperer	`coding-rules`, `testing-rules`, `prompt-engineering-rules`, repository context, `tracing-rules` (if present)
Architect	`coding-rules`, `testing-rules`, `system-design-rules`, repository context

A rule name such as coding-rules means .engineeringrules/coding-rules.md. Repository context is .memory/repository-context.md, and design-principles is .memory/design-principles.md.

Progressive disclosure

Each command declares the context it needs. Some entries always load; others load only when the task matches their condition. For example, when the Developer runs /implement:

Rule	Loads when
`design-rules`	The repository is a UI or frontend repository.
`prompt-engineering-rules`	The task changes an LLM artifact: a prompt, an agent definition, a schema the model reads, or an eval.
`tracing-rules`	The task touches tracing or observability. Optional: a repository without the file isn’t a gap.

A backend change never loads your design system. A prompt change loads your prompt rules even if the file sits in an ordinary package.

When a file is missing

A file the repository carries itself always loads. When it doesn’t carry one, Architech decides in this order:

Your context rules

A declaration for that repository in your context rules decides: exempt, inherit, require, or follow the code beside the change.

The parent's file

With no declaration, a rule or memory file from the nearest parent folder, up to the project root, stands in.

Proceed with a warning

With nothing to inherit, the agent works from the conventions beside the change, records the gap and recommends an action. See when a file is missing.

design-principles is the exception to step 2. With no declaration, a repository’s design principles are its own: a parent’s file doesn’t stand in. A declaration that inherits changes that, including if-missing: inherit written out: with that line in your context rules, every repository without its own design-principles.md inherits the nearest parent’s. To keep design principles per repository, leave if-missing out (it defaults to inherit for everything else), and inherit them only where you mean to, with memory: { design-principles: inherit }. Only a declared required file stops anything, and then only the code-writing step that needs it. Reviews never block on missing context: the reviewer reports the gap and still gives a verdict.

Context exemptions

A context exemption declares that a repository doesn’t need a rule or memory file. The agent skips that file without a warning, and records the decision with your reason. Without one, a missing file still proceeds, but with a warning and a recommended action on every run. An exemption turns a recurring warning into a recorded decision.

When to use one

Your repository	Declare
Generated code (an SDK built from an API spec)	`exempt: all`: no rules, memory or repository context.
Docs-only, or one with no tests	Exempt only the files that don’t apply, such as `testing-rules`.
Standards being written	A per-file exemption with an `until` date.
Should follow a shared package	`inherit` from that package instead of exempting.
Deliberately has no rules document	`neighbouring-conventions`: the agent cites at least two examples beside the change.
Sensitive (payments, auth)	`required`: the repository must carry its own files. Review any entry for a folder inside it too (see below).

What an exemption doesn’t do

It doesn’t turn off project instructions. The repository’s AGENTS.md / CLAUDE.md still load, following the project-file precedence. There is no use: <file> option to point at them.
It doesn’t hide a file you have. A file the repository carries still loads.
The quick exemption doesn’t override required. exempt: all, rules or memory never silences a required declaration from any repository that covers the same folder. A more specific entry’s own rules: or memory: setting is different: it wins over a parent’s required. An entry for payments/ledger with rules: { exempt: [testing-rules] } exempts that folder even when payments requires testing-rules, so keep entries inside a required repository under the same review as the required itself.

Configure context rules

Where the configuration lives

Declare everything in one context: block, laid out by repository:

.architech/factory/factory.yaml — if your project has a Software Factory, put the block alongside repos, boards, labels and triggers.
.architech/context-rules.yaml — otherwise, the same top-level context: block in its own file.

Keep the configuration in one place. Don’t repeat it in AGENTS.md, CLAUDE.md or your onboarding notes.

The keys

Key	Value	Meaning
`context.if-missing`	`inherit` (default), `exempt`, `neighbouring-conventions`	What a missing file that no entry declares falls back to. Writing `inherit` out also inherits `design-principles`, which the default doesn’t.
`context.repos.<key>`	A folder relative to the project root (`.` is the root), or a separate repository’s name	One entry per repository. The most specific folder wins.
`exempt`	`all`, `rules`, `memory`	The quick exemption. `all` covers rules, memory and repository context.
`rules`	A word, `{ inherit: <folder> }`, or a mapping per file	Engineering rules (`.engineeringrules/<name>.md`).
`memory`	The same forms as `rules`	Memory (`.memory/<name>.md`). `repo` names repository context.
`why`	Text	Why this repository differs. Required for `exempt` and `required`.
`approved`	Text	Optional: who agreed, when, and a reference your team understands.
`until`	A quoted `"YYYY-MM-DD"` date	Optional. After that date, the entry reads as absent.

A repository key that isn’t a folder in the checkout names a separate repository. It matches a checkout whose folder name, or Git origin repository name, is the same. This is different from the Factory’s top-level repos list of owner/repo names. Under rules: or memory: you can write one word for the whole kind, or a mapping. Pick one form per kind:

# One word for every rule
rules: inherit
# That folder's files
rules: { inherit: packages/core }
# A list: exempt, required or neighbouring-conventions
rules: { exempt: [testing-rules] }
# One word per file
rules: { coding-rules: own, testing-rules: exempt }

Word	On a missing file
`own`	Use the repository’s own file; a miss falls back to `if-missing`.
`inherit`	Use the nearest parent folder’s file, up to the project root.
`{ inherit: <folder> }`	Use that folder’s file. The folder is relative to the project root.
`exempt`	Load nothing. Prints `EXEMPT` (severity `INFO`), not a warning, while your context rules are valid. If any entry has a problem, such as a missing `why`, it prints `WARNING` with a note naming it.
`neighbouring-conventions`	Follow the code beside the change, citing at least two examples.
`required`	Stop the code-writing step until the repository’s own file exists.

Within an entry, a file’s own setting wins over its kind (rules or memory), which wins over the quick exempt.

A worked example

A monorepo with a generated Python SDK, an adapter that should follow packages/core, a payments service with strict standards, and a legacy API whose testing standards are being rewritten:

acme/
├── .engineeringrules/coding-rules.md      ← shared coding rules
├── packages/
│   ├── core/.memory/repository-context.md
│   ├── adapter/                           ← no files of its own
│   └── web/.engineeringrules/testing-rules.md
├── sdk-python/                            ← generated
├── payments/                              ← no files yet
└── legacy-api/                            ← no testing rules yet

Add this to .architech/factory/factory.yaml, or to .architech/context-rules.yaml if you don’t use a Factory:

context:
  repos:
    sdk-python:
      exempt: all
      why: Generated from the OpenAPI spec; the generator governs changes
    packages/adapter:
      rules: inherit
      memory:
        repo: { inherit: packages/core }
    payments:
      rules:
        required: [coding-rules, testing-rules]
      why: Money movement needs this repository's own standards
      approved: Payments team, security review 2026-11
    legacy-api:
      rules:
        exempt: [testing-rules]
      why: Testing standards are being rewritten during the migration
      until: "2026-12-01"

What each repository gets for its rules and repository context:

Repository	`coding-rules`	`testing-rules`	Repository context
`sdk-python`	Exempt	Exempt	Exempt
`packages/adapter`	Inherited from the root	Warning: none found	Inherited from `packages/core`
`payments`	Blocked: add its own file	Blocked: add its own file	Warning: none found
`legacy-api`	The root’s file	Exempt until 2026-12-01	Warning: none found
`packages/web` (not declared)	The root’s file	Its own file	Warning: none found

payments shows what required means: the root’s coding-rules.md doesn’t satisfy it. Only the declaring repository’s own file does; a folder inside payments uses the payments file, unless its own, more specific entry sets those rules differently. Until the files exist, only the code-writing step that needs them is held. Planning and reviews continue, and neither a lead’s one-run instruction nor a quick exempt: all overrides the declaration. When 2026-12-01 has passed, the legacy-api entry reads as absent and normal lookup resumes, with a warning if nothing supplies the file. The date applies to the whole entry.

Check the result

Validate a factory file, then ask the resolver what a repository gets:

architech factory validate .architech/factory/factory.yaml --json
architech-shortcut-resolver --bundle '["@rule:coding-rules","@rule:testing-rules","@memory:repo"]' --cwd ./sdk-python

Factory validation checks the complete file, so it doesn’t apply to context-rules.yaml. Use the resolver for that file. For a single repository, declare it under repos: { ".": … } and run the resolver with --cwd .. Each declared decision prints a line, a sentence and a CONTEXT-HINT/1 record. For sdk-python (excerpt):

EXEMPT: @rule:testing-rules - @rule:testing-rules is declared not needed here (context rules: repo-file repo sdk-python (quick exemption)). Proceed and record it in CONTEXT_MANIFEST.context_decisions.
  → testing-rules: exempt for sdk-python (why: Generated from the OpenAPI spec; the generator governs changes) → proceed; record in CONTEXT_MANIFEST
  CONTEXT-HINT/1 {"v":1,"shortcut":"@rule:testing-rules","repo":"sdk-python","decision":"exempt","source":"repo-file","why":"Generated from the OpenAPI spec; the generator governs changes","approved":null,"action":"proceed-and-record"}

An exemption exits 0 and loads no content. A missing required file prints CRITICAL, with "decision":"block", and exits 1. Check the repository, source and decision, not only the exit code. source is factory for the factory file and repo-file for context-rules.yaml. With --json, the same record is context_hint and the full decision is context_decision.

Where Architech looks

A file the repository carries always wins. For a missing file, the sources are read in this order; a later source fills only what an earlier one leaves undeclared:

ARCHITECH_CONTEXT_RULES — a file with a top-level context: block. In Cloud, the platform sets it for each Factory stage session, including a session that resumes later, with your Factory’s rules. A workspace Environment can’t set it.
.architech/factory/factory.yaml — the checkout’s context: block.
.architech/context-rules.yaml — the repository fallback file.
The parent’s file, where inherit (the default) applies.
Proceed with a warning, with nothing to inherit.

Within a source, the most specific repository folder wins.

A lead’s context instruction in a task brief can fill an uncovered gap for one run. It never removes a required guard or replaces a file the repository has. Put lasting decisions in your context rules.

Invalid entries approve nothing

An unknown key, a misspelt word such as requird, or a malformed until makes the whole entry approve nothing: the resolver warns, names the problem and ignores the entry. Any required values in it still stand, so a typo can’t grant an exemption. Other entries keep working. A valid exemption or required without why still applies, with a note. architech factory validate refuses it, so add the reason. approved stays optional.

Move older declarations

If your project still uses inline Context: records in AGENTS.md / CLAUDE.md, or ONBOARD-PLAN.json with "memory_rules": "exempt", move the lasting decision into context:. Those legacy forms still work, with a deprecation note. "memory_rules": "exempt" reads as repos: { ".": { exempt: all } }. Check the repository with the resolver, then remove the old declaration. See the full context reference for every field, and onboarding for where your intent and setup notes live.

Memory and rules

What belongs in each file, and the warning you see when one is missing.

Project context

How AGENTS.md and CLAUDE.md load into every session.

Get started · Early Access

Architech

Configuration

Operate

Cloud

Reference

Context management

How context works

The context map

Rules and memory, per repository

Progressive disclosure

When a file is missing

Context exemptions

When to use one

What an exemption doesn’t do

Configure context rules

Where the configuration lives

The keys

A worked example

Check the result

Where Architech looks

Invalid entries approve nothing

Move older declarations

Memory and rules

Project context