APC Agent Files Are Contracts, Not Personas

The clean way to think about APC agent files is simple: they define a contract, not a personality.

That sounds small, but it prevents a lot of bad design. When people treat an agent file like a chat persona, they start stuffing it with habits, one-off notes, and runtime guesses. When they treat it like a contract, the file stays stable, reviewable, and useful across tools.

APC makes that possible by keeping structured agent definitions in .apc/agents/<slug>.md, while APX handles the local runtime around them. APC says what the project needs. APX says how this machine runs it.

What belongs in the agent file

The APC spec keeps agent files narrow on purpose. A structured agent definition usually has a few fields:

• name
• model
• description
• optional skills
• optional UI hints like color, emoji, vibe
• optional is_background

That is enough to answer the useful questions:

• What is this agent for?
• When should it activate?
• Which capabilities usually matter?
• Should a compatible runtime treat it as background work?

Example:

---
name: reviewer
model: inherit
description: "Reviews behavior changes and risks."
skills: documentation, release-checklist
is_background: true
---

Focus on regressions, edge cases, and missing tests.

That file is compact, but it is not vague. It gives another tool enough signal to behave consistently without dragging in machine-local noise.

What does not belong there

If the data only makes sense on one laptop, it does not belong in APC.

Bad fits for .apc/agents/<slug>.md:

• session transcripts
• private runtime memory
• tokens or credentials
• temporary paths
• debug output from one run
• tool-specific state that will not travel with the repo

APX keeps those things local under ~/.apx/. That split matters because runtime state changes every day, but the agent contract should not.

Why the contract matters

A contract gives you two wins.

First, portability. Another compatible runtime can read the same agent file and get the same intent. The project does not depend on one vendor's hidden settings.

Second, reviewability. A teammate can open the file and ask a direct question: is this the right agent shape for the project? That is much easier than reverse-engineering a blob of runtime state.

This is also why APX leans on APC instead of replacing it. APX is the local daemon and CLI that makes the protocol usable today. It can list agents, run them, read memory, and keep local history, but it does not own the project meaning itself.

The useful boundary

A good test is boring, but it works:

• If it should survive a clone, keep it in APC.
• If it should die with the machine or session, keep it in APX.

Applied to agent files:

• role and responsibility? APC
• default model choice? APC, unless the project truly needs a fixed one
• reusable skills? APC
• per-session output or scratch state? APX
• local execution history? APX

That line keeps the agent file from turning into a junk drawer.

Why model: inherit helps

The docs recommend inherit unless the project truly needs a specific model. That keeps the contract portable. The runtime can still choose its configured default, whether that runtime is APX, another CLI, or an IDE that understands APC.

In practice, that means the repo states the job, not the workstation.

A small workflow that fits the model

A simple APC/APX workflow looks like this:

apx init
apx agent add reviewer --role "Software Developer" --model inherit
apx agent list
apx memory reviewer

apx init makes the repo legible to the runtime. apx agent add writes a structured agent definition. apx agent list shows what is available. apx memory reviewer reads the curated project memory for that agent.

The point is not the commands themselves. The point is the boundary they respect.

Bottom line

APC agent files are contracts, not personas.

Keep them small, stable, and portable. Put runtime state in APX. Put project meaning in APC. That is the shape that lets one repo work across tools without losing the plot.