Read Your Own AGENTS.md Whole; Bound Foreign Context
An agent runtime has two conflicting duties when it loads project instructions: preserve the rules that govern its own work, and keep an arbitrary external file from consuming the entire prompt. Treating both files the same creates a bad trade-off. A small universal limit can silently remove a project’s own critical rules; no limit lets any referenced repository take over the context window.
APX makes the distinction explicit. It treats APC as the portable context layer: AGENTS.md and the defined .apc/ files carry project-owned guidance. APX is the daily-use runtime and tooling layer that assembles this guidance into a live prompt, along with runtime state that remains local.
The practical rule is simple: APX reads the AGENTS.md for the project it is running inside in full. A foreign project’s file has a configurable budget.
Why one cap fails
Imagine a project’s AGENTS.md starts with code conventions and ends with a release safety rule:
## Release
Never publish before the integration suite passes.
A fixed cap can preserve the first section and cut the last one. The agent then receives a partial contract while believing it received project guidance. That is worse than a visible absence: it can follow some rules and violate rules it never saw.
APX had exactly this failure mode. Its prompt-builder regression test records that an earlier 6,000-character cap sliced the owning project’s contract mid-rule. The current implementation does not cap the project matching the runtime’s working directory. The project’s own contract reaches the prompt whole.
That is not a claim that every instruction file should be unlimited everywhere. It is an ownership decision. The repository running the agent owns its contract and should be able to review its full effect.
Foreign context needs a different policy
APX can also receive a project path that is not its own working project. That file might be useful context, but it is not safe to assume its size is reasonable for the current turn. APX therefore applies a default foreign-contract budget of 24,000 characters.
When it must shorten a file, it does two important things:
- It cuts on a line boundary instead of breaking a rule mid-sentence.
- It states that the result is truncated and reports how much was omitted.
The resulting prompt tells the agent to read the file directly before relying on rules not shown. This preserves an important fact: partial context is partial.
The foreign cap is also configurable through super_agent.project_agents_max_chars. A positive value changes the budget; 0 disables it. That makes prompt size a deliberate local runtime choice, not a hidden change to APC’s portable contract.
Keep the boundary clear
This division helps answer a common design question: should a project shorten its own instructions to fit a runtime? Sometimes, yes—but that should be a project authoring decision, made in the repository and reviewed like any other change. It should not be an invisible runtime truncation.
Likewise, a runtime may need to bound external context for cost and reliability. That safeguard belongs in APX, where prompt assembly happens. It does not redefine what APC files mean or what a project is allowed to document.
A useful test follows: when an agent acts inside your repository, can you show exactly which project rules reached it? If the answer is “only the first part, silently,” the boundary is wrong. Read the owning contract whole; bound foreign context visibly.
APC keeps the contract portable. APX applies it in a live runtime without pretending every source of context has the same ownership or budget.
Top comments (1)
Agreed on the ownership split, and the truncation notice is the detail most runtimes skip. The edge case I'd pressure-test is the monorepo one. Working directory as the ownership test gets blurry when one repo holds several AGENTS.md files and the agent starts at the root but edits a service three directories down. Every file is own-contract under one roof, so nothing gets the foreign budget, and a root file plus a service file can duplicate or contradict each other, the test command being the classic. I hit this with the CLAUDE.md/AGENTS.md pair, same disease. Worth giving the resolution rule the same explicit treatment as the cap: deepest match wins, or nearest ancestor, documented either way.