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 init creates the APC project structure
• apx project add registers the repo as a project
• apx run delegates 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.