Agent Slugs Are the Smallest Handoff Key Between APC and APX

APC and APX, two layers of a developer toolchain, use a stable 'agent slug' as the smallest handoff key between portable project contracts and local runtime state. The slug, defined in APC's structured agent definitions, serves as the routing key for APX commands and runtime file paths, avoiding hidden IDs and keeping the join key simple. Good slugs describe durable responsibilities like 'reviewer' or 'planner', while weak ones leak implementation details and age poorly.

A lot of APC and APX discussion happens at the level of folders, memory, or runtimes. But there is a smaller boundary that matters every day: the agent slug. APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md , .apc/project.json , .apc/agents/<slug .md , skills, commands, and curated memory that is safe to share. APX is the daily-use runtime and tooling layer. It reads that contract, runs agents, stores local runtime state under ~/.apx/ , and gives you CLI, daemon, and web admin workflows. The slug is where those two layers meet. In APC, the slug identifies the structured agent definition. In APX, the same slug becomes the routing key for commands like apx run <slug , apx exec -a <slug , apx memory <slug , and apx session new <slug . APX also uses it to place runtime files under per-agent paths such as ~/.apx/projects/<project-id /agents/<slug /sessions . That sounds small, but it solves a real design problem: how do you keep a portable project contract and a local runtime aligned without inventing hidden IDs for every agent? The answer is not to make the runtime smarter. The answer is to keep the join key boring. If the shared name for an agent is unstable, everything around it gets noisy. A stable slug avoids that. For example, if a repository defines .apc/agents/reviewer.md , APX can keep using reviewer everywhere: apx run reviewer --runtime claude-code "Review the open PRs" apx exec -a reviewer "Summarize test risk" apx memory reviewer apx session new reviewer --title "Follow-up audit" That is a better contract than a display name. You can rename a role description, change the model, or expand the skills list, and the runtime history still lands under the same agent lane. The slug should describe the durable responsibility, not the mood of the prompt. Good slugs: reviewer planner backend release-manager Weak slugs: smart-reviewer-v2 best-agent-final claude-helper telegram-reviewer-temporary Those weaker names leak implementation details into the project contract. They age badly when you switch models, channels, or runtimes. APC should describe the project role. APX should decide how that role runs today. APC keeps the definition portable: AGENTS.md holds repository-wide rules. .apc/agents/<slug .md holds the structured agent definition. .apc/agents/<slug /memory.md can hold curated, team-safe memory.APX keeps the runtime local: That split only stays clean if both sides can point to the same agent identity without translation glue. The slug is enough. This is also why APX does not need a second hidden naming system for normal agent work. The portable name from APC already gives the runtime a stable filesystem lane, command target, and audit trail anchor. Pick slugs like you would pick API names. If you need to change how an agent behaves, edit the definition. If you need a different responsibility, create another slug. That keeps APC readable in the repo and APX readable on disk. The bigger APC/APX idea is often described as portable context plus local runtime. That is true. But in daily use, the smallest piece doing real work is often just one good slug.