> ## Documentation Index > Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt > Use this file to discover all available pages before exploring further. # Context management > What Architech's agents read before they change your code, and how to exempt, inherit or require rules and memory per repository. > [!NOTE] > > **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](https://docs.mutagent.io/architech/features/project-context.md) | `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](https://docs.mutagent.io/architech/features/memory-and-rules.md) | `.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](https://docs.mutagent.io/architech/onboard.md) 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: **1. Your context rules** A declaration for that repository in your [context rules](#configure-context-rules) decides: exempt, inherit, require, or follow the code beside the change. **2. The parent's file** With no declaration, a rule or memory file from the nearest parent folder, up to the project root, stands in. **3. 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](https://docs.mutagent.io/architech/features/memory-and-rules.md#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](https://docs.mutagent.io/architech/features/project-context.md#which-file-wins). There is no `use: ` 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](https://docs.mutagent.io/factory/overview.md), 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.` | 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: }`, or a mapping per file | Engineering rules (`.engineeringrules/.md`). | | `memory` | The same forms as `rules` | Memory (`.memory/.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: ```yaml theme={null} # 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: }` | 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: ```text theme={null} 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: ```yaml theme={null} 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: ```bash theme={null} 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): ```text theme={null} 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: 1. **`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. 2. **`.architech/factory/factory.yaml`** — the checkout's `context:` block. 3. **`.architech/context-rules.yaml`** — the repository fallback file. 4. **The parent's file**, where `inherit` (the default) applies. 5. **Proceed with a warning**, with nothing to inherit. Within a source, the most specific repository folder wins. > [!NOTE] > > 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](https://docs.mutagent.io/factory/reference/factory-yaml#context-rules) for every field, and [onboarding](https://docs.mutagent.io/architech/onboard.md#what-onboarding-keeps) for where your intent and setup notes live. > [card] [Memory and rules](https://docs.mutagent.io/architech/features/memory-and-rules.md) > > What belongs in each file, and the warning you see when one is missing. > [card] [Project context](https://docs.mutagent.io/architech/features/project-context.md) > > How `AGENTS.md` and `CLAUDE.md` load into every session. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.