External Runtimes Should Read AGENTS.md Directly
The cleanest APX design is not a translation layer. It is a handoff.
APC is the portable context layer. APX is the daily-use runtime and tooling layer. When APX launches an external runtime like Claude Code, Codex, OpenCode, or Aider, the job is simple: locate the project, start the runtime, and let that runtime read the project's own contract.
That keeps one source of truth in the repo and keeps APX thin.
Why this matters
The failure mode is easy to miss. A tool starts helpful, then begins copying project rules into machine-local prompt blobs, cached summaries, or hidden adapter state. At first it looks convenient. Later it drifts.
Once a runtime-specific copy exists, every change has to move twice:
- once in APC, where the project contract lives
- once in the runtime wrapper, where the copied version got stuck
That is how teams end up with one repo, two realities.
APX avoids that by staying at the execution boundary. It does not need to rewrite the contract. It only needs to preserve the path to it.
What APX should do
APX already has the right job shape:
-
apx initcreates the APC project structure -
apx project addregisters the repo as a project -
apx rundelegates work to a runtime - runtime state, sessions, and message logs stay local in
~/.apx/
That split is the point. APC keeps the repo portable. APX keeps the machine-local work local.
So when an external runtime starts, the best outcome is boring: it reads AGENTS.md, loads the repo rules, and acts on them directly.
No duplicate prompt store. No mirrored policy file. No runtime-only copy of the project contract.
A concrete example
Imagine a repo with this shape:
project-root/
├── AGENTS.md
└── .apc/
├── project.json
└── agents/
└── reviewer.md
A review task might look like this:
apx run reviewer --runtime claude-code "Review the open PR and summarize risk"
The repo already defines the project intent. APX does not need to restate it in a second format. It can pass control to the runtime, and the runtime can read the same contract the next developer or agent would read from disk.
That is valuable because the repo stays reviewable. If AGENTS.md changes, you see the change in git. If the runtime behavior changes, you inspect APX. Each layer has one job.
What not to do
Do not treat APX as a place to accumulate project meaning.
If a rule should travel with the repo, keep it in APC. If a rule only matters on this machine or in this session, keep it in APX runtime state. If you blur that line, the project stops being portable.
A common mistake is to think more adaptation means better UX. Usually the opposite is true. Extra translation layers add ambiguity. They also make debugging harder, because no one knows whether the bug lives in the repo contract or in the wrapper that copied it.
Bottom line
APC should define the project contract once.
APX should execute that contract, not rewrite it.
When external runtimes read AGENTS.md directly, the repo stays the source of truth, the runtime stays thin, and the whole system gets easier to trust.
That is the real value of the split.
Top comments (5)
Reading AGENTS.md directly is the right instinct, but I would still treat it as project input, not authority. External runtimes need precedence rules so repo instructions cannot override user or security boundaries.
Agreed. “Source of truth” here means project contract, not highest authority. APX should avoid duplicating or translating repo instructions, but external runtimes still need precedence rules: user intent and security boundaries must outrank anything read from AGENTS.md.
Exactly. I like the "project contract, not highest authority" wording. The repo should declare defaults and local operating rules, but the runtime still needs a clear precedence stack so a stale or hostile instruction file cannot override the human or the safety boundary.
Exactly. That is the boundary I want to keep explicit: AGENTS.md can define the repo contract, but it should never become a way for the repo to escalate authority.
For APX, the practical rule is: preserve the project contract, do not reinterpret it, and let the runtime apply its own precedence stack. The repo should be inspectable and portable, but user intent, runtime policy, and security limits still sit above it.
Yes. I like treating AGENTS.md as a project contract that is directly readable, but never sovereign. It can describe local rules; it should not outrank user intent, runtime policy, or security boundaries.