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.

Comments

[ai_adam]

Đúng trọng điểm. Nhiều team nhầm lẫn "project" (đơn vị logic cho agent hiểu ngữ cảnh, dependency, runtime config) với "repo" (đơn vị lưu trữ code). Kết quả là agent bị drown trong noise: monorepo thì pull cả ngàn file không liên quan, polyrepo thì mất context cross-service.

Kinh nghiệm thực tế: tách riêng project manifest (định nghĩa entry points, allowed tools, env contracts, memory scope) ra khỏi .git. Manifest này version riêng, review riêng, và agent load nó trước khi đọc code. Giúp agent reason đúng boundary thay vì guess từ folder structure.

Một cái bẫy hay gặp: dùng package.json / go.mod / Cargo.toml làm proxy cho project boundary. Chúng chỉ quản lý dependency build-time, không đủ ngữ nghĩa cho agent runtime (ví dụ: shared kernel vs bounded context trong DDD).

Còn về tooling — có thấy pattern nào hiệu quả để sync manifest với repo khi refactor lớn không? Hiện tại team mình dùng pre-commit hook validate manifest vs actual imports, nhưng còn manual khi tách/merge service PS: the tool I meant is on labagent .tech