A Runnable Project Needs Both Instructions and Identity

A folder is not automatically an agent project. It may contain code, notes, and a useful prompt, but an agent runtime still needs two answers before it can treat that folder as durable work: what guidance applies here, and which project is this?

APC and APX make those answers explicit with two small files:

• AGENTS.md holds shared instructions: conventions, constraints, commands, and project-specific context.
• .apc/project.json holds stable metadata, including the project name and a stable apx_id when APX manages the project.

That pair is a practical boundary. In APX, apx project add reads both files. If either is missing, registration stops rather than guessing that a random directory is a complete project.

Why one file is not enough

An AGENTS.md without metadata can explain how work should happen, but it does not give the runtime a stable identity for its local state. Two checkouts can have similar instructions; the runtime still needs to know which local project store belongs to this one.

A project.json without instructions has the opposite problem. It can name a project, but it cannot tell an agent the repository's rules, safe boundaries, or expected workflow. Identity without guidance turns registration into a label, not a usable contract.

The two files also keep responsibilities clear. APC is the portable context layer: commit the shared contract with the repository. APX is the daily-use runtime: it uses that contract while keeping sessions, conversations, messages, caches, task logs, and machine-specific configuration under ~/.apx/projects/<apx_id>/.

A small, reliable setup

Start with a repository root like this:

my-project/
├── AGENTS.md
└── .apc/
    └── project.json

Keep AGENTS.md focused on guidance that teammates and compatible tools should share. Keep project.json focused on stable metadata. Do not put API keys, raw session logs, or private runtime memory in either file.

Then register the project explicitly:

apx project add .

APX can link the committed project definition to its local runtime directory through apx_id. If the repository moves and the runtime needs to re-scan the on-disk contract, use:

apx project rebuild <id|name|path>

The important detail is not the command. It is the refusal to invent missing context. A runtime that silently registers a folder without instructions might use generic behavior where project rules mattered. A runtime that invents an identity can attach local history to the wrong work boundary.

The useful rule

Before you ask an agent runtime to own ongoing work, give the project both instructions and identity. AGENTS.md says how contributors should act. .apc/project.json says what durable project definition they are acting within.

That is the division of labor: APC keeps the contract portable and reviewable; APX makes it operational on one machine without committing private runtime state back into the repository.