A Project Command Can Travel With APC. Its Execution Should Stay Local.

A useful command definition is part of project context.

Its execution environment is not.

That is a small distinction, but it matters if you want APC and APX to stay clean.

APC is the portable context layer. It is where a repository can keep durable agent-facing files like AGENTS.md, .apc/agents/, .apc/skills/, and .apc/commands/.

APX is the daily-use runtime and tooling layer. It is what turns that context into real work on one machine: CLI sessions, web admin actions, Telegram turns, MCP calls, engines, and runtime state under ~/.apx/.

Project commands sit right on that boundary.

What should travel

A command body that explains a repeatable workflow belongs with the project.

For example, a repo might ship a markdown command in .apc/commands/release-checklist.md or .apc/commands/bug-triage.md.

That file is portable context. It tells any compatible tool, "when someone asks for this named workflow, here is the project-specific instruction body."

That is exactly the kind of thing APC should carry.

It is durable, reviewable, and tied to the repository rather than one operator's laptop.

What should not travel

The way that command gets resolved and executed should stay local.

APX's CLI code makes that boundary explicit.

apx command list and apx command show read markdown files from .apc/commands/, but they do not treat execution state as part of APC. First APX resolves which project you mean. In resolveCommandRoot(), it can use an explicit --project, the nearest APC root found from the current working directory, or a registered project path resolved through APX.

That path resolution is runtime behavior, not repository contract.

The project file travels.

The machine-specific answer to "which registered project does this command refer to right now?" does not.

That second part depends on local registration, current cwd, and APX runtime state.

Why this split matters

If you collapse those two layers, command systems get brittle fast.

One bad design is to store only runtime aliases and assume the command body lives in some hidden local database. Then the workflow stops being part of the project contract.

The opposite bad design is to push runtime details into APC, such as local execution history, channel bindings, machine-specific paths, or per-user resolution caches. Then the repository starts carrying private or unstable state it should never own.

The cleaner rule is simpler:

• APC stores the command definition.
• APX decides how to find the active project and run work from the current machine.

That keeps project intent portable without pretending execution context is portable too.

Practical example

The APX command implementation is deliberately modest.

listCommandFiles() scans .apc/commands/ for markdown files. cmdCommandShow() prints the requested file. And resolveProjectId() handles runtime-friendly lookup rules such as project id, exact path, exact name, fuzzy match, current APC root, or auto-registration.

That is a good division of labor.

The repository owns the workflow text.

APX owns the local question of which project instance the operator is currently talking about.

So if two developers clone the same repository, they can share the same command body through APC while APX still resolves each clone locally on each machine.

APC portable, APX practical

This is the deeper APC/APX pattern in miniature.

APC should carry durable project meaning.

APX should supply local resolution, execution, logging, and runtime coordination.

A project command can travel with the repo because the instruction body is part of project truth.

Its execution should stay local because runtimes, registrations, channels, and machine paths are not.

That separation is what keeps portable context useful instead of leaky.