An APX Project Is Not the Same Thing as a Git Repository

A common mistake in agent tooling is to define a project as a code repository. That works for a developer demo, then fails the moment the work is a client operation, a research effort, a household plan, or a creative production.

APX takes a wider view: a project is a place where a crew needs a shared working boundary. It can be a codebase, but it can also be any directory that deserves named agents, instructions, and repeatable work. Git is useful when you need history and collaboration. It is not the thing that makes work a project.

Start with the work, not the repository

APX can be set up on a machine first, then used for a real task with one agent. No repository is required for that starting point. This matters because useful agent work often begins before code exists:

• A small business needs a weekly research brief.
• A writer needs an editor and a publishing checklist.
• A household needs recurring planning and a record of decisions.
• A product team needs an exploration space before a repository is created.

In each case, the useful boundary is the work and the people or agents involved—not a .git directory.

Add portable context when a directory becomes a project

When a directory does need an explicit APX/APC project boundary, initialize it:

cd /path/to/project
apx init --name "Research Desk"

That creates AGENTS.md and .apc/. APC is the portable layer: it holds project instructions and durable, reviewable context that can travel with the directory. If that directory is later committed to Git, the same files can travel with the repository. If it is not, they are still a clear local contract for compatible tools.

APX supplies the daily-use runtime around that contract: agents, conversations, routines, channels, and local execution. Its runtime state stays outside the project directory under ~/.apx/; it should not be confused with portable project context.

That separation prevents two bad assumptions. First, it avoids treating every private conversation or credential as a file that belongs in source control. Second, it avoids denying non-code work the structure that code projects get by default.

A useful progression

A practical path is simple:

1. Use APX for one real task.
2. Create a project directory once work needs shared instructions or reusable roles.
3. Run apx init to create the APC contract.
4. Add Git only when version history or team collaboration actually calls for it.

This order keeps the tool aligned with the work. Git remains excellent infrastructure, but it is optional infrastructure. A project is the durable boundary where people and agents coordinate; a repository is only one way that boundary may be stored and shared.

APC makes that boundary portable. APX makes it useful every day. Neither requires pretending that every meaningful project begins as code.