Repository Instructions Need a Release Process

An instruction edit can look harmless in review and still change which commands an agent runs. A client upgrade can alter discovery, ordering, imports, truncation, or load timing without changing a byte in the repository. The thing we release is therefore not AGENTS.md alone. It is the complete operational tuple:

release = (
  repository commit,
  client binary and requested model,
  observed model identity,
  loader-affecting settings,
  root and trust boundary,
  CWD class and target path,
  resolved instruction graph,
  load timing and context state
)

Call the tuple an instruction release. Give it an ID, evidence, an owner, and a last-known-good pointer. That turns a collection of Markdown files into something an engineer can qualify, promote, inspect, and restore.

This framing has an important limit. Repository instructions are context supplied to a probabilistic system. They are not authorization, isolation, or a security control. Keep tool permissions, credentials, sandboxes, branch protection, and deployment approvals outside this layer. Your AGENTS.md Is Not a Policy Boundary covers that separation in detail.

Release the tuple, not the text file

A pull request diff tells you which bytes changed. It does not tell you which bytes a particular client will see.

Suppose a monorepo has a root AGENTS.md, a nested services/payments/AGENTS.md, a CLAUDE.md that imports the root file, path-scoped Copilot instructions, and a GEMINI.md. A run from the repository root and a run from services/payments need not resolve the same context. A request that never touches the payments tree can differ from one that causes lazy loading there. Change the client, its settings, or the detected trust root and the graph can change again.

That is why the release identifier needs every field in the tuple. At minimum, record the repository commit, exact client artifact, requested model, model identity reported by the run, relevant settings, root, working-directory class, target fixture, ordered instruction graph, and load events. If the vendor does not expose a stable hosted-model revision, say so explicitly. Do not replace an unknown value with a comforting label.

The graph is product-specific. There is no cross-vendor AGENTS.md standard that makes these clients interchangeable:

• Codex: Current documentation says Codex checks AGENTS.override.md, then AGENTS.md, then configured fallback names in each directory. It selects at most one file per directory and concatenates the discovered files from project root to current working directory. Its documented default combined project-document budget is 32 KiB, and the chain is constructed once per run. These are Codex rules, including the byte budget, not defaults to project onto other products. Codex AGENTS.md guide and the pinned 0.147.0 loader implementation.
• Claude Code: Claude Code reads CLAUDE.md, not AGENTS.md natively. A CLAUDE.md containing @AGENTS.md, or a symlink, is a bridge and must be tested as one. Ancestor memory loads at launch, while nested files below the working directory and path-scoped rules can load later. Anthropic advises keeping each CLAUDE.md under 200 lines as an authoring target, but also says those files load in full regardless of length. The guidance is not a loader cap. Claude Code memory documentation.
• GitHub Copilot CLI: Copilot CLI recognizes several instruction families, including repository AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, and path-scoped .github/instructions/*.instructions.md. Applicable files are combined, but the documentation does not establish a universal precedence order. Its @ references are supported only in specific file families. Do not encode a generic nearest-file-wins rule. Copilot CLI custom-instruction documentation.
• Gemini CLI: Gemini CLI has hierarchical context plus just-in-time discovery under a trusted root. context.fileName can change the recognized memory filenames. The pinned 0.54.4 import processor tracks processed files, constrains real paths to the project root, and initializes a maximum import depth of five. Gemini memory documentation and the pinned import implementation.

Those facts were rechecked on August 9, 2026. Treat mutable documentation as input to the next qualification, not as an eternal contract.

Put the release contract in version control

Store the human-maintained manifest beside the instructions. Generate the resolved graph and evidence elsewhere, but make their hashes addressable from the manifest. Here is a compact example. The versions and local limits are illustrative pins for the process, not recommendations. Replace every placeholder with an artifact your team actually qualifies.

schema: repo-instructions/v1
release_id: ri-2026-08-candidate

repository:
  commit: "<git-sha>"
  trust_root_markers: [".git"]
  owners: ["@developer-experience", "@payments-platform"]

bundle:
  candidate_sha256: "<sha256-of-canonical-resolved-graph>"
  last_known_good:
    release_id: ri-lkg
    bundle_sha256: "<lkg-bundle-sha256>"
    behavior_baseline_sha256: "<lkg-baseline-sha256>"

execution_classes:
  - id: repo-root
    root: "."
    cwd: "."
    target_path: "README.md"
  - id: payments-leaf
    root: "."
    cwd: "services/payments"
    target_path: "services/payments/src/fixture.ts"

clients:
  codex:
    version: "0.147.0"
    support: "qualified"
    binary_sha256: "<codex-binary-sha256>"
    requested_model: "<qualified-model-id>"
    settings:
      project_root_markers: [".git"]
      project_doc_fallback_filenames: []
      project_doc_max_bytes: 32768
    sources:
      - "AGENTS.override.md"
      - "AGENTS.md"
  claude_code:
    version: "2.1.226"
    support: "qualified"
    binary_sha256: "<claude-binary-sha256>"
    requested_model: "<qualified-model-id>"
    settings:
      claude_md_excludes: []
      authoring_line_target: 200 # guidance, not a loader cap
      import_max_hops: 4
    sources:
      - "CLAUDE.md"
      - ".claude/rules/**/*.md"
    imports:
      - from: "CLAUDE.md"
        to: "AGENTS.md"
        bridge: "at-import"
  copilot_cli:
    version: "1.0.78"
    support: "qualified"
    binary_sha256: "<copilot-binary-sha256>"
    requested_model: "<qualified-model-id>"
    settings:
      custom_instructions_dir: []
    sources:
      - ".github/copilot-instructions.md"
      - ".github/instructions/**/*.instructions.md"
      - "AGENTS.md"
      - "CLAUDE.md"
      - ".claude/CLAUDE.md"
      - "GEMINI.md"
  gemini_cli:
    version: "0.54.4"
    support: "qualified"
    binary_sha256: "<gemini-binary-sha256>"
    requested_model: "<qualified-model-id>"
    settings:
      context.fileName: ["GEMINI.md"]
      discovery_boundary: [".git"]
      import_max_depth: 5
    sources:
      - "GEMINI.md"

declared_references:
  paths:
    - "services/payments/package.json"
    - "scripts/verify-payments.sh"
  commands:
    - id: payments_verify
      cwd: "services/payments"
      argv: ["npm", "run", "verify"]
  globs:
    - ".github/instructions/**/*.instructions.md"

typed_contracts:
  - key: verify_command
    scope: "services/payments/**"
    value: ["npm", "run", "verify"]
    source: "services/payments/AGENTS.md"
    conflict: "error"

canaries:
  - root-rule
  - payments-nested-rule
  - lazy-path-rule
  - claude-agents-bridge
  - typed-conflict
  - critical-command
  - truncation-tail

The illustrative snapshot uses Codex CLI 0.147.0, Claude Code 2.1.226, Copilot CLI 1.0.78, and Gemini CLI 0.54.4, the current releases observed on August 9, 2026. A tag is only the starting pin. The binary digest and behavioral evidence establish what the release actually qualified.

The manifest is deliberately asymmetric. Codex gets a byte budget because its loader exposes one. Claude gets an advisory line target and a separate import depth because those are different concepts. Copilot gets its own recognized families and import constraints. Gemini gets its configured filename list and discovery boundary. An empty or unknown field should remain explicit rather than inheriting another vendor's behavior.

typed_contracts is the small amount of instruction meaning that your release process truly depends on. Do not attempt to convert all prose into a schema. Extract operational values such as the required verification command, forbidden target directory, package manager, or migration entry point. Those values can be compared deterministically across scopes. Keep the original prose for the model and the typed projection for release engineering.

Gate one resolves bytes, paths, and scope

The integrity gate never invokes a model. Its job is to answer a narrower question: given the pinned loader contract and execution class, can we deterministically explain which instruction sources are eligible, in what order, through which imports, under which scopes, and up to which product-specific limits?

Implement each vendor as a versioned adapter. An adapter owns recognized filenames, root discovery, directory traversal, selection order, import grammar, path scoping, canonicalization, load phase, and budget behavior. Do not place a generic precedence algorithm underneath all clients and patch exceptions later. The exceptions are the loader.

for (const releaseCase of manifest.execution_classes) {
  for (const client of manifest.clients) {
    const adapter = adapters.require(client.name, client.version)
    const root = adapter.resolveRoot(repo, releaseCase, client.settings)

    assertRootAndCwdInsideFixture(root, releaseCase.cwd)
    assertExactCase(adapter.discoverCandidates(root, releaseCase.cwd))
    validateDeclaredPathsCommandsAndGlobs(manifest.declared_references)

    const graph = adapter.resolve({
      root,
      cwd: releaseCase.cwd,
      targetPath: releaseCase.target_path,
      settings: client.settings,
    })

    assertImportsInsideBoundary(graph)
    assertNoCycles(graph)
    assertDepthWithinPinnedLoader(graph, adapter)
    assertScopesAndOrder(graph, adapter)
    assertProductBudgetAndTruncation(graph, adapter)
    assertTypedContractsHaveNoDeclaredConflict(graph, manifest.typed_contracts)

    emitCanonicalGraph(graph)
    emitSha256(graph.nodes, graph.edges, graph.order, graph.effectiveBytes)
  }
}

There are several easy-to-miss details behind those assertions:

• Recognized names and exact case: Enumerate directory entries and compare byte-for-byte. A case-insensitive developer filesystem can hide agents.md while a pinned Linux loader looks only for AGENTS.md. Warn on instruction-like files the adapter does not recognize.
• Paths and commands: Resolve declared paths from the same root and CWD class as the agent. For a declared command, verify the executable or package script exists, its working directory exists, and referenced wrapper scripts remain executable. Do not execute production-mutating commands in this gate.
• Imports and globs: Parse only the import syntax implemented by that client and version. Canonicalize symlinks and real paths before cycle detection. Enforce the pinned client's boundary and depth. Compile every path-scope glob, then prove it matches the intended positive fixtures and misses explicit negative fixtures.
• Scope and order: Emit each source with an eligibility reason, scope, order index, and load phase. If order is undocumented, mark it as unspecified and require the behavioral gate to cover the conflict. Never manufacture precedence to make the resolver output tidy.
• Budgets and tails: Apply byte truncation only where the pinned loader applies it. Record included and excluded byte ranges plus the first excluded source. A rule placed after Codex's effective byte frontier needs a failing tail canary. Do not invent equivalent caps for Claude, Copilot, or Gemini.
• Generated hashes: Hash raw source bytes, normalized graph structure, loader settings, and the effective concatenation separately. The separate hashes tell you whether a diff came from source content, topology, configuration, or resolution.
• Typed conflicts: Resolve only declared keys. If two applicable sources give verify_command incompatible values and the manifest says conflict: error, fail. A classifier that flags phrases such as "always use npm" and "never use npm" may open a review task, but natural-language contradiction detection is a review signal, not proof.

A real repair in n8n shows why the reference checks are worth having. In commit 15cbd903, maintainers corrected stale paths and symbols in agent-facing documentation, including paths in AGENTS.md. This is bounded incident evidence for a specific drift class. It does not establish how common the problem is or what impact it had.

Gate one should fail fast, but it should not claim the release works. A perfect reimplementation of an obsolete assumption is still wrong. Gate two measures the client.

Gate two runs the actual clients

Build an isolated fixture repository with no production credentials, no network-dependent command, and disposable output. Install the exact client artifact from the manifest. Apply the exact loader settings. Initialize the expected root marker. Start each case in a fresh process or session so stale context cannot leak across tests.

Each canary should force an observable choice. Give the client two harmless fixture commands with distinguishable arguments, or ask it to create a marker file through its normal tool interface. The rule selects one command. The assertion reads the loader and tool-call evidence, not the assistant's prose. A model can say it followed a nested instruction while its command arguments prove otherwise.

The conflict canary deserves special treatment. When a vendor documents a deterministic order, assert it. When the vendor combines applicable instructions without a general precedence guarantee, do not pretend the text has a portable winner. Either remove the conflict from the production bundle or pin the currently observed behavior as a compatibility baseline and treat any change as a review-stopping diff.

Capture the best evidence each product exposes:

• Codex: Run the pinned client in non-interactive mode with JSONL output and retain command execution, file-change, and tool-call events. Bind those events to the resolver's expected source graph. Codex documents exec --json as a machine-readable event stream. Codex non-interactive documentation.
• Claude Code: Install an InstructionsLoaded hook in the fixture and retain its file_path, memory_type, load_reason, globs, trigger path, and parent path alongside stream JSON tool events. The hook was introduced in Claude Code 2.1.69 and is asynchronous observability, not a blocking enforcement point. Immutable 2.1.69 changelog entry and current hook schema.
• Copilot CLI: Capture /instructions output or the corresponding discovered-instruction view, /env details, and the exported session transcript. Assert the invoked tools and arguments. Start a new session after editing instructions because current documentation says active sessions do not receive those edits immediately. Copilot CLI programmatic reference.
• Gemini CLI: Capture /memory show or a reload result for the resolved hierarchical context, plus stream JSON tool_use and tool_result events. Exercise just-in-time loading by touching the scoped file through a tool, not by merely mentioning its path in the prompt. Gemini headless output documentation.

Normalize events into your own evidence schema, but preserve the raw stream. Normalization makes clients comparable at the level you care about: source loaded, reason, command, argv, CWD, result. Raw evidence lets you debug a new event shape or challenge an adapter assumption later.

The behavioral gate passes only if every required canary maps to the candidate release ID, exact repository commit, exact local client artifact, settings hash, requested and observed model identity, resolver graph hash, and clean fixture. If any of those bindings is missing, the trace may be useful debugging data, but it is not release evidence.

CI must trigger on the dependency closure

Running the gate only when AGENTS.md changes misses several ways the effective graph can move. The trigger classifier needs the manifest as its dependency index.

Run both gates when a recognized instruction source changes, appears, disappears, changes case, or moves. Also run them when a root marker or directory topology changes, a declared script or path changes, a matching path-scoped file moves, the client lock or binary digest changes, the requested model changes, or a loader-affecting setting changes. Detect renames with history-aware diff metadata rather than treating them as unrelated delete and add events.

Scheduled and manually dispatched runs should bypass the change classifier and execute the full matrix. The schedule below is intentionally a team-owned placeholder. Choose a cadence from your change tolerance and operating model. There is no universal interval to copy.

name: repository-instruction-release

on:
  pull_request:
  workflow_dispatch:
  schedule:
    - cron: "<team-owned-revalidation-cron>"

jobs:
  classify:
    runs-on: ubuntu-latest
    outputs:
      release_gate: ${{ steps.closure.outputs.release_gate }}
    steps:
      - uses: actions/checkout@<pinned-commit>
        with:
          fetch-depth: 0
      - id: closure
        run: ./tools/instruction-release/classify-change.sh \
          --manifest .agent-release.yaml \
          --diff-filter ACMRTD \
          --include-instruction-files \
          --include-topology \
          --include-declared-references \
          --include-client-locks \
          --include-loader-settings

  qualify:
    needs: classify
    if: >-
      github.event_name == 'schedule' ||
      github.event_name == 'workflow_dispatch' ||
      needs.classify.outputs.release_gate == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@<pinned-commit>
      - run: ./tools/instruction-release/resolve-and-lint .agent-release.yaml
      - run: ./tools/instruction-release/run-client-canaries .agent-release.yaml
      - uses: actions/upload-artifact@<pinned-commit>
        with:
          name: instruction-release-evidence
          path: .evidence/repo-instructions/

The classifier itself needs fixtures. Test an instruction rename, a root-marker addition, a referenced script move, a client lock update, and a settings-only change. A CI rule that silently skips its own dependency is part of the failure surface.

Emit one practical evidence bundle

Both gates should write into a single content-addressed directory. The index can stay compact while raw events and graphs live in adjacent files:

{
  "$schema": "evidence/repo-instructions-v1",
  "release_id": "ri-2026-08-candidate",
  "created_at": "<rfc3339>",
  "repository": {"commit": "<git-sha>", "dirty": false},
  "execution": {
    "client": "codex",
    "client_version": "0.147.0",
    "binary_sha256": "<sha256>",
    "requested_model": "<model-id>",
    "observed_model": "<reported-model-id-or-unknown>",
    "settings_sha256": "<sha256>",
    "root": "<fixture-root>",
    "cwd_class": "payments-leaf",
    "target_path": "services/payments/src/fixture.ts",
    "fresh_session": true
  },
  "integrity": {
    "status": "pass",
    "adapter": "codex@0.147.0",
    "graph_sha256": "<sha256>",
    "effective_bytes_sha256": "<sha256>",
    "sources": "integrity/sources.json",
    "graph": "integrity/graph.json",
    "diagnostics": "integrity/diagnostics.json"
  },
  "behavior": {
    "status": "pass",
    "baseline_sha256": "<sha256>",
    "cases": "behavior/cases.json",
    "normalized_events": "behavior/events.jsonl",
    "raw_events": "behavior/raw.jsonl",
    "tool_calls": "behavior/tool-calls.jsonl"
  },
  "approvals": [
    {"owner": "@developer-experience", "gate": "integrity", "result": "pass"},
    {"owner": "@payments-platform", "gate": "behavior", "result": "pass"}
  ]
}

Store the stdout and stderr digest, process exit status, sanitized environment allowlist, fixture tree hash, and client installation provenance as sibling artifacts. Redact credentials before upload. Retention and access belong to your normal audit policy, not the instruction format.

The evidence bundle answers the questions that matter during an incident: What did we intend to release? What did this client resolve? What did it actually load? Which tool call did it make? Which exact tuple was last known good?

Diff, stage, and roll back one release unit

An upgrade pull request should compare two releases, not just two package versions. Produce a machine diff with these sections:

• local client artifact, requested model, observed model, and loader settings;
• root and trust-boundary decisions for every execution class;
• graph nodes, import edges, scopes, order, and load phases;
• effective byte frontier and excluded tail for budgeted loaders;
• typed contract values and unresolved conflict signals;
• normalized loader events and tool calls, including tool name, argv, CWD, order, and exit status.

Ignore stylistic changes in the assistant's final prose unless they are themselves a stated product requirement. The release gate is there to catch operational compatibility, not to freeze every token. Review new tool calls, missing calls, argument changes, CWD changes, and changed source-load evidence first.

Promotion is a sequence of named environments or repositories, not an arbitrary percentage target. Start with the fixture suite. Then run the manifest's named canary repositories or execution classes with their owners watching the evidence. Advance only after the integrity artifact and actual-client artifact refer to the same candidate. Keep the current last-known-good release installed and addressable until the rollout completes.

If a canary fails, stop promotion and classify the diff. A resolver mismatch points to the adapter, topology, imports, or settings. A clean resolver plus a changed loader trace points to actual-client compatibility. An unchanged load trace plus a changed tool call points to model or backend behavior, prompt interaction, or nondeterminism. The evidence will not eliminate judgment, but it keeps the investigation attached to real inputs and actions.

Rollback must be atomic at the release-unit level:

Do not roll back only the Markdown while leaving the upgraded client and settings in place. Do not roll back only the CLI while retaining a bundle qualified against a different loader. Do not compare the restored run to the failed candidate's baseline. Client, settings, instruction bundle, and behavioral baseline move together.

This process extends the mechanics in Test AGENTS.md Changes in CI Before They Merge. The regression harness tells you whether expected repository behavior changed. The release contract makes the harness portable across upgrades, scoped loaders, imports, and rollback.

Frequently asked questions