DEV Community

Cover image for APC Commands Stay in the Repo. APX Just Reads Them.
Agent Project Context profile image Manuel Bruña
Manuel Bruña for Agent Project Context

Posted on

APC Commands Stay in the Repo. APX Just Reads Them.

#ai #opensource #devtools #tutorial

APC Commands Stay in the Repo. APX Just Reads Them.

The easiest way to weaken APC is to treat .apc/commands/ like a random dump for shell snippets.

That misses the point.

APC is the portable context layer. APX is the daily-use runtime and tooling layer. Commands sit on the APC side because they describe project behavior, not machine behavior.

APX makes that folder useful. APC keeps it portable.

What .apc/commands/ is for

The APX docs already treat commands as part of the project layout. apx init creates .apc/agents/, .apc/skills/, and .apc/commands/ together. That matters because it turns commands into a first-class project artifact, not an afterthought.

APX also exposes them directly through the CLI:

  • apx command list lists workflow commands in .apc/commands/
  • apx command show <name> prints the command content

So the runtime does not own the command. It only discovers and reads it.

That is the right split.

Why markdown works

A command file in APC should be easy to review, easy to diff, and easy to copy to another repo.

Markdown gives you that.

It lets you keep the file small and readable while still documenting intent. A command can look like this:

# Release checklist

1. Run tests.
2. Check the diff.
3. Summarize risk before merge.
Enter fullscreen mode Exit fullscreen mode

That is useful even before APX touches it. A teammate can read it. A future agent can read it. Git can review it.

The point is not that markdown is magical. The point is that markdown keeps the command portable.

What belongs there

Put workflow-level instructions in .apc/commands/ when they answer a project question like:

  • How do we review a PR here?
  • How do we prepare a release?
  • How do we summarize a change safely?
  • What steps do we follow before merging?

Those are project rules. They belong with the project.

A good test is simple: if you want the same command on a clean clone, or on another machine, it belongs in APC.

What does not belong there

Do not put runtime noise in .apc/commands/.

That includes:

  • API keys
  • session history
  • machine-specific paths
  • temporary output
  • anything that only makes sense on one laptop

If the file is about state, secrets, or one-off execution details, keep it in APX runtime storage instead.

APX already has a place for that local state. APC should stay clone-safe.

Why the boundary matters

This is the real value of the split:

  • APC stores the project contract.
  • APX reads that contract and runs with it.

When commands live in APC, you can move the repo and keep the workflow.
When commands live in APX runtime, you get local flexibility without polluting the repo.

That means fewer surprises when tools change. It also means less drift between agents, because the workflow is versioned with the code.

Bottom line

.apc/commands/ is not a junk drawer.

It is a portable workflow layer, owned by the project and surfaced by APX.

If a command explains how this repo works, commit it to APC.
If it only explains what happened on this machine, keep it in APX.

That boundary is small, but it saves a lot of confusion later.

Top comments (0)