Why APC Agents Should Default to model: inherit

APC agent files work best when they stay small, portable, and boring.

The strongest default is also the least flashy: use model: inherit unless the project truly needs a pinned model.

That rule keeps the APC layer clean. The repository keeps the project contract. The runtime keeps the machine-specific choice of model. APX then makes that contract executable on whatever tool or machine is active.

What an APC agent file should do

An APC agent is a named persona in .apc/agents/<slug>.md. The file can describe the agent with frontmatter such as name, description, role, language, skills, tools, and model.

The important part is what the file does not need to do. It does not need to hardcode the whole runtime stack. It does not need to force one vendor's model as the project default. It should describe the persona and leave the runtime room to do its job.

A minimal project agent looks like this:

---
name: reviewer
model: inherit
description: "Reviews PRs and pushes back on hand-wavy diffs."
role: Code reviewer
language: es
tools: read,write,run
skills: code-review,git
---

That file is enough to tell APX what the agent is for. The runtime fills in the rest.

Why inheritance is the better default

The APX docs recommend model: inherit because it lets each runtime apply its own configured default. That matters because APC is meant to be shared across tools.

A project might be opened in APX today, then in Codex, Claude Code, Cursor, or another APC-aware runtime tomorrow. If the agent file pins a specific model, the project becomes less portable. If the agent file inherits, the same contract still works, and each runtime can keep using its own local default.

That is the right split:

• APC says what the agent is.
• APX or the current runtime says how it should run here.

This keeps the repo from becoming a frozen snapshot of one machine's preferences.

What APX does with the inherited agent

When APX runs apx exec <slug> or an agent inside a routine, it builds the prompt in layers:

1. Identity block
2. Description from AGENTS.md
3. Role and language
4. Invocation channel
5. Memory
6. Skills
7. The APX meta-skill
8. The action-discipline footer

That order is useful because the agent file stays focused on intent, not implementation details. Memory stays local. Skills stay explicit. The runtime decides the actual model unless the project contract has a real reason to override it.

When to pin a model anyway

model: inherit is the default, not a law.

Use a specific provider:model-id only when the project contract truly depends on it. A cheap summarizer may need a small local model. A workflow may need a model with a known tool-use profile. A test fixture may need a predictable engine.

The docs show both ends of the spectrum:

• model: inherit for most agents
• model: ollama:llama3.2:3b or another explicit model when the project really needs it

The point is to make the exception visible. If the model choice matters, say so in the file. If it does not, do not freeze it.

Why hardcoding models causes drift

Hardcoding a model in every agent file looks precise, but it usually creates noise.

First, it couples project context to a specific provider setup. If the key is missing, the agent breaks.

Second, it hides the real decision. The agent file starts looking like infrastructure instead of context.

Third, it makes multi-runtime use awkward. A team member can clone the repo and still need to rewrite agent files just to make the project runnable in their own stack.

APC is supposed to reduce that kind of drift, not increase it.

The practical rule

Use this test before you pin a model:

• If the model is part of the project contract, pin it in .apc/agents/<slug>.md.
• If the model is just the local runtime choice, use model: inherit.
• If the value is secret or machine-specific, keep it in APX runtime config.

That split keeps APC portable and APX useful.

A repo with clean agent files is easier to audit, easier to import, and easier to run on a new machine. The runtime can change. The contract stays stable.

Bottom line

The default APC agent should not argue with the runtime.

model: inherit keeps the agent definition portable, lets APX or another runtime choose the local default, and reserves explicit model pins for the cases where they really matter.

That is the simplest way to keep agent files useful instead of sticky: describe the agent, not the machine.

Comments

[Alex Shev]

The model-inherit default makes sense because the agent should inherit the user's current capability contract unless there is a specific reason to override it. Hardcoding model choices inside agents turns a portable workflow into stale configuration.