DEV Community: Agent Project Context

Project Tasks Belong in APX, Not APC

Manuel Bruña — Tue, 14 Jul 2026 12:04:13 +0000

Project Tasks Belong in APX, Not APC

A project task is operational state.

That is why it belongs in APX, not APC.

APC is the portable context layer. It keeps the repository contract in files like AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It keeps the moving parts that should stay local: sessions, messages, conversations, caches, and, importantly, tasks.

That split matters because tasks feel deceptively simple. People often try to store everything in the same place: project rules, agent definitions, memory notes, TODOs, and runtime traces. The result is a blurred system where durable context and daily operations pollute each other.

APX draws a cleaner line.

In the implementation, project tasks live under:

~/.apx/projects/<project-id>/tasks/YYYY-MM.jsonl

That location says a lot.

The task log is per project, machine-local, append-only, and runtime-owned. APC does not need to version it inside the repository. The repository should define what the project is. APX should track what is happening around the project right now.

The current task store is also deliberately small. Each task is created as an event, then projected into current state. The lifecycle stays simple:

create
update
done
drop
reopen

Open tasks can also carry a workflow status such as pending, running, in_review, or blocked.

That design is practical for agent work.

If you ask APX to capture a follow-up, the CLI can write it without inventing a bigger project-management system:

apx task add "Review auth edge case" --tag bug --agent reviewer --due 2026-07-15
apx task list --state open
apx task done t_ab12cd

Those commands are useful precisely because they stay local to APX runtime state. They do not rewrite your repository contract. They do not pretend a temporary follow-up note is the same kind of artifact as AGENTS.md, .apc/project.json, or .apc/mcps.json.

There is also a structural reason this belongs in APX.

Tasks are tied to runtime activity. APX exposes per-project task APIs, a global task view across registered projects, task summaries for status screens, and task-aware tools for the super-agent. That is operational plumbing, not portable specification. APC-compatible tools may understand agent definitions or project metadata, but they should not be forced to inherit one runtime's transient TODO stream.

This is the same boundary APC and APX keep elsewhere.

APC stores durable, reviewable project intent.
APX stores live execution state.

A task like "re-run migration after vendor update" is real work, but it is not project contract. It may matter only on one machine, for one agent, during one week. Storing it in APX keeps the repo clean while still making the work visible and queryable.

The alternative looks worse in both directions.

If tasks go into APC, the repository starts collecting operational noise that should not travel forever. If tasks stay only inside ad hoc chat threads, they become hidden, vendor-tied, and hard to inspect later.

APX avoids both problems by giving tasks a first-class local store.

That also makes the APC/APX relationship easier to explain:

APC tells a runtime what this project means.

APX tracks what this project is doing.

For daily agent work, that is the right split. Keep the shared contract in APC. Keep the changing task flow in APX.

Project Config Should Travel With APC

Manuel Bruña — Mon, 13 Jul 2026 12:02:35 +0000

Project Config Should Travel With APC

When a team decides how an agent should behave in one repository, that decision should travel with the repository.

That is why project config should live in APC.

APC is the portable context layer. It keeps repository-owned agent context in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It reads that portable context, merges it with machine-local runtime settings, and keeps sessions, messages, and secrets outside the repo.

That split becomes especially useful with configuration.

APX documents two config layers.

Global config lives in ~/.apx/config.json.
Project config lives in .apc/config.json.

The rule is simple: machine-local settings stay machine-local, but repo-owned behavior travels with the project.

This is stronger than convenience. It is a boundary that prevents silent drift.

Imagine a team wants one project to route Telegram messages to a reviewer agent and to use a different super-agent model than the default machine setting. If that choice lives only in one developer's ~/.apx/config.json, the behavior is no longer really part of the project. Another clone on another machine can register the same APC project and get different operational behavior without noticing.

Putting that override in .apc/config.json fixes the problem.

A small example from the APX docs looks like this:

{
  "super_agent": {
    "model": "groq:llama-3.3-70b-versatile",
    "permission_mode": "total"
  },
  "telegram": {
    "route_to_agent": "reviewer"
  }
}

That file belongs in the repo because it expresses project intent. APX then applies it only for that project.

The CLI makes the workflow explicit:

apx project config set my-app super_agent.model groq:llama-3.3-70b-versatile
apx project config set my-app telegram.route_to_agent reviewer
apx project config show my-app --effective

This is the right division of labor.

APC owns the durable contract. APX owns the runtime merge.

The same docs also draw the line that matters most: never put secrets in .apc/config.json. API keys, provider credentials, daemon settings for your machine, and other private runtime details belong in ~/.apx/config.json, not in the repository. APC should carry safe, reviewable project behavior. APX should keep private operational state local.

That gives teams a clean model:

commit project overrides
keep credentials local
let APX merge both at runtime

Without this split, teams usually fall into one of two bad patterns.

The first bad pattern is hiding project behavior in one laptop. The project becomes harder to reproduce because important agent settings are no longer visible in code review.

The second bad pattern is committing too much. People start placing keys, local provider endpoints, or one-off machine tweaks into shared files because there is no clear boundary between project config and runtime config.

APC and APX avoid both mistakes by naming the boundary directly.

There is also a portability advantage here. APC does not need to know how APX stores sessions, messages, or caches. It only needs to preserve the project-owned facts another runtime could understand later. A committed .apc/config.json is part of that project contract. Even if another APC-compatible runtime eventually reads only part of it, the repository still has a visible, reviewable source of truth for its intended behavior.

So the practical thesis is small but important:

If a setting describes how this repository should behave, put it in APC.

If a setting describes your machine, your credentials, or your local runtime state, keep it in APX.

Portable context should travel. Private runtime state should not. Project config is one of the clearest places where that APC/APX boundary pays off every day.

Skill Bodies Should Load on Demand

Manuel Bruña — Sun, 12 Jul 2026 12:02:53 +0000

Skill Bodies Should Load on Demand

A good skill system has two jobs that pull in opposite directions.

First, the project needs durable instructions that live in version control. That is APC's job. A project can keep reusable skill files under .apc/skills/, and agents can reference those skills by name from AGENTS.md or .apc/agents/<slug>.md.

Second, the runtime needs to stay fast and focused during actual work. That is APX's job. If every skill body is injected into every turn, the prompt gets noisy, token costs rise, and the model starts seeing instructions that do not matter for the current request.

That is why APX is right to treat skill bodies as on-demand runtime material rather than permanent prompt baggage.

In APC, the skill file is the project-owned source. The spec keeps this simple: skills are reusable instruction files under .apc/skills/<name>.md, meant to avoid repeating the same operational guidance across many agents. That keeps the durable contract in the repo, reviewable like any other project artifact.

But APX does not have to dump that whole contract into the model on every turn.

The runtime code is explicit about this tradeoff. In src/core/agent/skills/catalog.js, APX builds a compact skills hint block that lists only slugs. It tells the model that bodies are not loaded, that it can call list_skills to browse one-line descriptions, and load_skill({slug}) to fetch the full body when exact syntax is needed. That is a better default than preloading everything.

Why? Because most turns do not need most skills.

If a user asks for a quick summary, a design opinion, or a small code fix, loading a release checklist, a deployment runbook, a security review guide, and a migration playbook all at once just burns attention. The model now has to separate relevant instructions from irrelevant ones before it can even start solving the task.

APX also keeps the loading order practical. In src/core/agent/skills/loader.js, project skills shadow global ones, and global skills shadow built-in runtime skills. So APC keeps ownership of project-specific behavior, while APX still provides a safe fallback catalog. That split matters: portable context stays in the repo, but runtime convenience does not get mistaken for project truth.

There is an even stronger version of the same idea in APX's optional Skill Inspector. When enabled, the runtime suppresses the static slug dump and re-evaluates the current prompt each turn. High-confidence matches can inline one skill body. Lower-confidence matches become hints. Everything else stays out. The point is not magic retrieval. The point is prompt discipline.

This is the deeper APC/APX boundary:

APC should preserve reusable knowledge.
APX should decide how much of that knowledge becomes active for this turn.

A concrete example makes the split clearer.

Imagine a repo with these skills:

release-checklist
security-review
support-triage
docs-style

Those files belong in .apc/skills/ because they are durable project instructions. But if the user asks, "Explain this error log and suggest the smallest patch," APX should not inject all four bodies. A small hint that those skills exist is enough. Only if the turn becomes a release task or a security audit should the runtime pay to load the matching body.

That behavior keeps APC portable and APX usable.

Portable context is not the same as always-active context. A project can own many valid instructions without forcing every runtime turn to carry all of them. Once you accept that distinction, the architecture gets cleaner: APC stores the skill files, APX routes them into the prompt only when the request actually needs them.

That is the right default for daily agent work.

Path-Scoped Rules Belong in APC

Manuel Bruña — Sat, 11 Jul 2026 12:05:45 +0000

Path-Scoped Rules Belong in APC

A repository should not need different hidden rule copies for different tools.

That is why path-scoped rules belong in APC.

APC is the portable context layer. It keeps repository-owned meaning in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer. It helps current agents and runtimes work with that portable context while still keeping sessions, messages, and other runtime state outside the repo.

The split matters most when one rule should apply only to one part of the codebase.

One repo, different rule zones

Most projects do not have one flat instruction surface.

Frontend code may need accessibility checks and bundle-size discipline. Backend code may need input validation at the route boundary. Support content may need a specific tone and escalation path. If all of that lives only in one giant root prompt, agents either ignore the details or carry too much irrelevant guidance into every task.

APC gives a cleaner shape:

AGENTS.md for repository-wide rules
.apc/rules/ for reusable or path-scoped rules

The APC rules spec is explicit about this. AGENTS.md is the broad root contract. .apc/rules/ is where rules can become smaller and more targeted.

A recommended file can look like this:

---
description: "Backend API rules"
globs:
  - "src/api/**/*.ts"
alwaysApply: false
---

- Validate request input at the route boundary.
- Keep database writes inside service functions.

That is a better boundary than copying the same instructions into Cursor rules, Claude-specific files, and a runtime-local note that no one reviews.

Why APC should own these rules

Path-scoped rules are still project meaning.

They describe how this repository wants work done in these paths. That is exactly the kind of information that should survive a fresh clone, code review, and a runtime change. If the rules live only in one editor's private directory, they stop being part of the project contract and start being workstation trivia.

APC fixes that by keeping the source in .apc/rules/.

The folder structure docs make the intent clear: path-scoped .mdc rules are project-owned, safe to commit, and distinct from runtime state. Sessions, conversations, messages, caches, and private memory do not belong there. APX keeps those under ~/.apx/ instead.

That separation keeps two different concerns from bleeding together:

APC stores durable guidance worth reviewing.
APX stores local operational history worth keeping out of git.

Why this also helps APX

APX works best when the repository already has a clean contract.

The APC reference docs describe APX as the runtime bridge that makes .apc/ usable today. It handles the daemon, CLI, runtimes, engines, and local storage. It should not become a second source of truth for project rules.

If path-scoped guidance already lives in APC, APX can stay thin. It can help compatible runtimes use the repo context without owning a second project-specific rules database.

That is also future-proof. The APC rules docs explicitly allow compatible consumers to project .apc/rules/*.mdc into tool-specific rule systems when needed. The important part is not the projection target. The important part is the source stays in the repo.

Practical example

Suppose a monorepo has these needs:

AGENTS.md: run tests before merge, never commit secrets, keep migrations reversible
.apc/rules/frontend.mdc: preserve keyboard navigation and avoid text-only icon buttons
.apc/rules/backend.mdc: validate input at the boundary and keep writes inside services

Now the project can move across tools without rewriting its own discipline each time.

APC keeps the rule map portable. APX keeps the runtime local. That is the right division of labor.

Bottom line

Path-scoped rules belong in APC because they are part of the repository contract, not part of one runtime's private memory.

Keep broad rules in AGENTS.md. Keep narrower, reusable, path-aware rules in .apc/rules/. Let APX handle execution, sessions, and local tooling around that contract instead of duplicating it.

Project Skills Should Override Global Skills

Manuel Bruña — Fri, 10 Jul 2026 12:04:48 +0000

Project Skills Should Override Global Skills

When an agent needs operational instructions, the worst outcome is ambiguous precedence. A project wants one behavior, your machine has another, and the runtime quietly picks the wrong one.

APC and APX avoid that by making skill scope explicit.

APC is the portable context layer. It keeps project-owned instructions in the repository, including .apc/skills/. APX is the daily-use runtime and tooling layer. It discovers those skills, lets the super-agent load them on demand, and still keeps a machine-wide skill catalog under ~/.apx/skills/ plus its own built-in runtime skills.

The important rule is simple: project skills win.

Three skill lanes, one precedence order

The APX skills docs and loader code define one runtime catalog with three sources, in this order:

<project>/.apc/skills/<slug>/SKILL.md or <slug>.md
~/.apx/skills/<slug>/SKILL.md
APX built-in runtime skills under src/core/runtime-skills/

The first matching slug wins. That means a project skill can override a user-global skill, and a user-global skill can override a built-in one.

That is the right order because APC owns project meaning.

If a repository says its deploy-checklist skill should work a certain way, that project-local instruction should beat whatever happens to be installed globally on one laptop. Otherwise the same APC project would behave differently depending on whose machine ran it.

Why APC needs the top slot

Portable context only works if the repository can carry its own exceptions.

Imagine you keep a global release-notes skill in ~/.apx/skills/ that fits most projects. Then one repository has stricter rules: mention migration risk, list MCP changes separately, and never claim a release is safe without test output.

That repository should not need a forked runtime or a custom machine setup. It should only need:

.apc/skills/release-notes/SKILL.md

Now APX reads the project skill first, and the super-agent loads the correct instructions for that repository.

That is APC doing its job: project-specific context travels with the repo.

Why global skills still matter

Global skills are still useful. They are the machine-wide layer for habits you want everywhere on one workstation.

Examples:

personal writing style
preferred debugging checklist
local publishing workflow
a custom skill for a tool only you use

APX stores those in ~/.apx/skills/, so they stay available across projects on that machine without polluting any repository.

That is also the APC/APX split in miniature:

APC keeps shared, reviewable, repo-owned instructions.
APX keeps operator-local runtime customizations.

A global skill should be convenient. It should not outrank a project contract.

Why built-in skills stay as the safety net

APX keeps a third lane for built-in runtime skills. The docs describe those as private: always available, always active, and not deletable from scope settings.

That matters because APX ships its own operational knowledge there: apx-* skills, apc-context, and runtime-specific guidance. If users could accidentally delete or fully disable that foundation, the runtime would lose basic self-knowledge about how to use its own commands and structures.

So the full design is not just “project overrides global.” It is:

project wins when the repo needs a local rule
global wins when the operator wants a machine-wide customization
built-in remains as the fallback safety net

On-demand loading keeps prompt cost low

This precedence model works well because APX does not dump full skill bodies into every prompt.

The runtime exposes list_skills and load_skill, and APX documents that load_skill pulls the full body only for the current turn. The baseline prompt stays small, while exact instructions stay available when needed.

That means you can keep project-specific skill overrides in APC without paying for all of them on every message.

Practical rule

Use each lane for its real job.

Put repo-owned exceptions in .apc/skills/.
Put personal machine-wide helpers in ~/.apx/skills/.
Leave built-in APX runtime skills alone unless you are intentionally shadowing them with a better local or project version.

If one slug means different things in two repositories, that is not a bug. That is exactly why the project lane exists.

Bottom line

Project skills should override global skills because APC owns portable project intent.

APX makes that practical with a clear precedence chain, built-in fallback skills, and turn-local skill loading. The result is predictable behavior: the repo decides project meaning, the machine adds personal convenience, and the runtime still keeps its own minimum operational floor.

A Stable Project ID Keeps APC Portable and APX Local

Manuel Bruña — Thu, 09 Jul 2026 12:04:01 +0000

A Stable Project ID Keeps APC Portable and APX Local

A lot of agent tooling problems start with a bad identity model. If a runtime treats a folder path as the project identity, everything looks fine until you rename the repo, move it to another machine, or register the same code from a different checkout.

APC and APX avoid that trap by splitting identity from runtime state.

APC is the portable context layer. It keeps the committed project contract in the repository. APX is the daily-use runtime and tooling layer. It reads that contract, then keeps sessions, messages, caches, and other machine-local state outside the repo.

A small file is what makes that split work: .apc/project.json.

`project.json` gives the project a durable identity

The APC docs define .apc/project.json as the canonical metadata file for a project. Its job is intentionally boring: say what the project is called, which APC version it targets, and when that metadata set was created.

A minimal APC shape looks like this:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}

APX extends that practical story with one more field when it initializes a real working project:

{
  "name": "my-app",
  "version": "0.1.0",
  "apf": "0.1.0",
  "created": "2026-01-15T10:00:00Z",
  "apx_id": "077078af9dd7"
}

That apx_id is the key detail. APX documents it as the stable identifier that links the committed APC definition to local runtime state under ~/.apx/projects/<apx_id>/.

So folder path is not the identity. Repo display name is not enough either. The stable id is the bridge.

Why that matters in daily work

Imagine this sequence:

You run apx init in a repository.
APX creates .apc/project.json and generates apx_id once.
You register the project with APX.
APX stores runtime state under ~/.apx/projects/<apx_id>/.

Now later you:

rename the repo directory
move it to another path
clone it on another machine
reopen it from a different tool

The APC contract still travels with the repo, because it lives in AGENTS.md and .apc/. The APX runtime state still has a clear local home, because it hangs off the stable id, not off an unstable folder name.

That is exactly the APC/APX division in practice:

APC says what project this is.
APX says what happened while this machine worked on it.

Without a stable id, a runtime has to guess. It may create duplicate local projects, lose message history after a rename, or tie private runtime state too tightly to one filesystem path.

Portable definition, local runtime

The APX project docs make the storage split explicit:

<repo>/.apc/ holds agent definitions, skills, MCP hints, and project config.
~/.apx/projects/<id>/ holds sessions, conversations, messages, caches, task logs, and other runtime files.

That design has two benefits.

First, the repository stays reviewable and clone-safe. APC contains portable context, not machine junk.

Second, APX stays honest about privacy and locality. Runtime transcripts, caches, and logs do not quietly end up in git just because a tool needed somewhere convenient to put them.

One practical rule

Treat .apc/project.json like identity, not like a scratchpad.

Do not turn it into a dump of runtime flags, private state, or session metadata. The APC spec keeps it small for a reason. The more stable it stays, the more reliable the bridge to APX becomes.

Likewise, do not change apx_id casually. APX documents that field as the permanent key for the local runtime folder. If you break that link, APX will not know that old local state belongs to the same committed project. If you move the repo, the APX docs point to apx project rebuild as the right repair step.

Bottom line

Portable context needs a stable identity, not a lucky pathname.

APC provides the committed project contract. APX provides the local runtime layer. .apc/project.json is the small boundary object that lets both sides do their job without leaking into each other.

That is not glamorous design. It is better: it keeps project meaning portable and runtime state local.

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Manuel Bruña — Wed, 08 Jul 2026 12:03:00 +0000

Agent Slugs Are the Smallest Handoff Key Between APC and APX

A lot of APC and APX discussion happens at the level of folders, memory, or runtimes. But there is a smaller boundary that matters every day: the agent slug.

APC is the portable context layer. It keeps the project contract in the repository: AGENTS.md, .apc/project.json, .apc/agents/<slug>.md, skills, commands, and curated memory that is safe to share. APX is the daily-use runtime and tooling layer. It reads that contract, runs agents, stores local runtime state under ~/.apx/, and gives you CLI, daemon, and web admin workflows.

The slug is where those two layers meet.

In APC, the slug identifies the structured agent definition. In APX, the same slug becomes the routing key for commands like apx run <slug>, apx exec -a <slug>, apx memory <slug>, and apx session new <slug>. APX also uses it to place runtime files under per-agent paths such as ~/.apx/projects/<project-id>/agents/<slug>/sessions.

That sounds small, but it solves a real design problem: how do you keep a portable project contract and a local runtime aligned without inventing hidden IDs for every agent?

The answer is not to make the runtime smarter. The answer is to keep the join key boring.

Why this matters

If the shared name for an agent is unstable, everything around it gets noisy.

Session history stops feeling continuous.
Runtime memory becomes harder to inspect.
Telegram routing, CLI commands, and follow-up sessions become less predictable.
Teams start treating agent definitions like disposable prompts instead of durable project roles.

A stable slug avoids that.

For example, if a repository defines .apc/agents/reviewer.md, APX can keep using reviewer everywhere:

apx run reviewer --runtime claude-code "Review the open PRs"
apx exec -a reviewer "Summarize test risk"
apx memory reviewer
apx session new reviewer --title "Follow-up audit"

That is a better contract than a display name. You can rename a role description, change the model, or expand the skills list, and the runtime history still lands under the same agent lane.

What should stay stable

The slug should describe the durable responsibility, not the mood of the prompt.

Good slugs:

reviewer
planner
backend
release-manager

Weak slugs:

smart-reviewer-v2
best-agent-final
claude-helper
telegram-reviewer-temporary

Those weaker names leak implementation details into the project contract. They age badly when you switch models, channels, or runtimes. APC should describe the project role. APX should decide how that role runs today.

APC side, APX side

APC keeps the definition portable:

AGENTS.md holds repository-wide rules.
.apc/agents/<slug>.md holds the structured agent definition.
.apc/agents/<slug>/memory.md can hold curated, team-safe memory.

APX keeps the runtime local:

sessions
conversations
message logs
runtime memory and caches

That split only stays clean if both sides can point to the same agent identity without translation glue. The slug is enough.

This is also why APX does not need a second hidden naming system for normal agent work. The portable name from APC already gives the runtime a stable filesystem lane, command target, and audit trail anchor.

Practical rule

Pick slugs like you would pick API names.

Stable over clever
Role-based over model-based
Short over decorative
Reusable over temporary

If you need to change how an agent behaves, edit the definition. If you need a different responsibility, create another slug.

That keeps APC readable in the repo and APX readable on disk.

The bigger APC/APX idea is often described as portable context plus local runtime. That is true. But in daily use, the smallest piece doing real work is often just one good slug.

Not Every Memory Belongs in APC

Manuel Bruña — Tue, 07 Jul 2026 12:03:53 +0000

Not Every Memory Belongs in APC

A lot of agent setups fail for the same reason: they treat all memory as one bucket.

That is not what APC and APX are trying to do.

APC is the portable context layer. It should keep only durable project facts that are safe to share, review, and commit.
APX is the daily runtime layer. It should keep local agent memory, cross-channel recall, sessions, and other runtime state outside the repo.

That split matters because different kinds of memory solve different problems.

If you put everything into APC, the repo fills with private notes, temporary conclusions, and stale conversation debris.
If you keep everything in APX, the project loses durable knowledge every time a machine, runtime, or session changes.

The better model is simple: APC stores what the project should remember. APX stores what the runtime needs in order to work.

APC memory: portable, curated, team-safe

In APC, curated memory lives with the project under:

.apc/agents/<slug>/memory.md

That file is for durable facts tied to the agent's project role. Good examples are:

long-lived constraints
team conventions
architectural decisions
recurring responsibilities
stable domain facts

This kind of memory is boring in the best way. It is plain Markdown, easy to diff, easy to review, and easy to migrate to another tool.

A reviewer agent might keep something like this:

# Memory - reviewer

## Project facts
- Prefer findings-first reviews.
- API compatibility matters more than internal file layout during v0.1.

## Durable decisions
- Use pnpm, never npm.

That belongs in APC because another contributor, another IDE, or another runtime should be able to read the same project rule later.

APX memory: local, operational, runtime-owned

APX has a different job. It is the runtime and tooling layer, so it keeps machine-local memory where the repo should not.

Per-agent runtime memory lives under:

~/.apx/projects/<project-id>/agents/<slug>/memory.md

That file is injected into the agent prompt on every call. It is useful for local operational context, owner preferences, and durable notes that help the runtime, but should not automatically travel with the repository.

APX also has a separate cross-channel memory system:

~/.apx/memory.md
~/.apx/memory.db

That layer powers automatic recall across channels. It can remember recent facts, retrieve semantically relevant past messages, and compact long histories without turning the repo into a session dump.

So APX already tells us something important: not all memory should be committed, and not all memory should be global.

Practical rule: decide by visibility, not by format

The mistake teams make is judging memory by file type instead of visibility.
A memory.md file can still be the wrong place if the content is private, temporary, or unreviewed.

A better rule is:

Put it in APC if the whole project may need it later and it is safe to commit.
Keep it in APX if it is runtime-local, personal, temporary, or derived from ongoing sessions.
Leave it out of both if it is raw noise.

For example:

"Use pnpm, never npm" belongs in APC.
"Owner prefers short PR summaries" may belong in APX runtime memory.
"This session explored three bad refactors before finding the safe path" belongs in session history, not in either memory file.

That last example is the real trap. Raw transcripts feel informative, but they age badly. Future contributors do not need every thought. They need the final durable fact, constraint, or decision.

Why APC and APX fit together here

This is where the APC/APX split becomes useful instead of abstract.

APC gives the project one portable place for curated meaning.
APX gives daily work a local runtime that can keep richer state without leaking it into the repo.

That means you can switch tools, machines, or runtimes without losing the project contract, while still letting the runtime keep the messy memory it needs.

The clean workflow is:

Work in APX.
Let sessions, recall, and runtime memory stay local.
Extract only durable, sanitized facts into APC.

Not every memory deserves version control.
But every durable project fact should have a portable home.

APC Plans Keep Durable Work Out of the Chat

Manuel Bruña — Mon, 06 Jul 2026 12:04:19 +0000

APC Plans Keep Durable Work Out of the Chat

APC plans exist for one reason: some work should survive the session, but not the noise that produced it.

That is the clean split between APC and APX.
APC is the portable context layer, so it holds project-owned facts that should travel with the repo.
APX is the daily runtime and tooling layer, so it holds the messy work: sessions, transcripts, scratch notes, local state, and all the back-and-forth that gets you to a decision.

The mistake is simple: people either keep too little, or keep too much.
If you keep only the final code diff, you lose the reasoning that made the change safe.
If you dump raw chat into the repo, you import noise, private data, and half-finished ideas that nobody can trust later.
.apc/plans/ is the middle path.

A good APC plan is not a transcript and not a task board. It is a durable artifact that answers a specific question for future work.
The spec is explicit about what belongs there:

implementation plans that are approved or still useful later
migration plans
release plans
investigation summaries with next steps
open decisions and constraints

That sounds small, but it is a strong rule.
It means a plan stays useful after the original session is gone.
It also means another tool, another machine, or another contributor can pick up the work without replaying the whole conversation.

A concrete example helps.
Imagine you are moving auth checks from a service into a gateway.
During the APX session, you may explore three designs, reject two, and test a couple of edge cases.
That process belongs in APX runtime state, because it is temporary and often noisy.
But the final shared decision is different:

---
title: "Auth migration"
status: active
owner: architect
updated: 2026-07-06
---

# Auth migration

## Goal
- Move token validation to the gateway.

## Constraints
- Preserve existing session cookies during migration.
- Keep the old path working until rollout is complete.

## Steps
- Add gateway validation middleware.
- Add compatibility tests.
- Remove duplicate service checks after rollout.

That file is worth keeping because it compresses a long conversation into something actionable.
It tells a future contributor what the project decided, what still matters, and what should happen next.
It does not ask them to trust a transcript.
It gives them the current contract.

This is the deeper point: APC plans are not for storing thought streams.
They are for storing decisions that have already earned their place in the repo.
That makes them reviewable, diffable, and portable.
A plan can move through code review like any other project artifact.
A raw session cannot.

APX still matters here, because APX is where the work happens day to day.
It is the runtime that can collect the session, keep the local audit trail, and help you recover the useful part.
But APX should not become a dumping ground for durable project intent.
The clean workflow is: work in APX, extract the stable facts, then write them into APC when they are safe and useful for the team.

That rule is easy to apply:

If only the current session needs it, keep it in APX.
If the whole project may need it later, put it in APC.
If it is still fuzzy, keep it local until the decision settles.

Plans are the part of APC that makes projects remember how they move.
Not every conversation deserves a permanent record.
But every durable decision deserves a home.

External Runtimes Should Read `AGENTS.md` Directly

Manuel Bruña — Sun, 05 Jul 2026 12:03:43 +0000

External Runtimes Should Read `AGENTS.md` Directly

The cleanest APX design is not a translation layer. It is a handoff.

APC is the portable context layer. APX is the daily-use runtime and tooling layer. When APX launches an external runtime like Claude Code, Codex, OpenCode, or Aider, the job is simple: locate the project, start the runtime, and let that runtime read the project's own contract.

That keeps one source of truth in the repo and keeps APX thin.

Why this matters

The failure mode is easy to miss. A tool starts helpful, then begins copying project rules into machine-local prompt blobs, cached summaries, or hidden adapter state. At first it looks convenient. Later it drifts.

Once a runtime-specific copy exists, every change has to move twice:

once in APC, where the project contract lives
once in the runtime wrapper, where the copied version got stuck

That is how teams end up with one repo, two realities.

APX avoids that by staying at the execution boundary. It does not need to rewrite the contract. It only needs to preserve the path to it.

What APX should do

APX already has the right job shape:

apx init creates the APC project structure
apx project add registers the repo as a project
apx run delegates work to a runtime
runtime state, sessions, and message logs stay local in ~/.apx/

That split is the point. APC keeps the repo portable. APX keeps the machine-local work local.

So when an external runtime starts, the best outcome is boring: it reads AGENTS.md, loads the repo rules, and acts on them directly.

No duplicate prompt store. No mirrored policy file. No runtime-only copy of the project contract.

A concrete example

Imagine a repo with this shape:

project-root/
├── AGENTS.md
└── .apc/
    ├── project.json
    └── agents/
        └── reviewer.md

A review task might look like this:

apx run reviewer --runtime claude-code "Review the open PR and summarize risk"

The repo already defines the project intent. APX does not need to restate it in a second format. It can pass control to the runtime, and the runtime can read the same contract the next developer or agent would read from disk.

That is valuable because the repo stays reviewable. If AGENTS.md changes, you see the change in git. If the runtime behavior changes, you inspect APX. Each layer has one job.

What not to do

Do not treat APX as a place to accumulate project meaning.

If a rule should travel with the repo, keep it in APC. If a rule only matters on this machine or in this session, keep it in APX runtime state. If you blur that line, the project stops being portable.

A common mistake is to think more adaptation means better UX. Usually the opposite is true. Extra translation layers add ambiguity. They also make debugging harder, because no one knows whether the bug lives in the repo contract or in the wrapper that copied it.

Bottom line

APC should define the project contract once.

APX should execute that contract, not rewrite it.

When external runtimes read AGENTS.md directly, the repo stays the source of truth, the runtime stays thin, and the whole system gets easier to trust.

That is the real value of the split.

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

Manuel Bruña — Sat, 04 Jul 2026 12:03:27 +0000

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.

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.

APX Skills Are the Adoption Layer for APC

Manuel Bruña — Fri, 03 Jul 2026 12:18:52 +0000

APX Skills Are the Adoption Layer for APC

APC is the project contract. APX is the runtime layer that makes that contract usable today. The most practical bridge between both is APX skill installation.

That sounds small, but it solves a real adoption problem.

A protocol can be clean and still be ignored. If a tool does not know how to read .apc/, it will keep inventing its own local habits. One runtime may look at AGENTS.md. Another may ignore it. A third may store sessions in a vendor-specific cache and never touch the repo at all. APC only wins when the runtime learns to treat the repository contract as the source of truth.

That is where APX matters.

APX is not trying to replace APC. It is the layer that teaches compatible runtimes how to use APC correctly. The APX docs are explicit: it installs APC-aware skills into runtimes like Claude Code and Codex, so they know how to read .apc/, which agents exist, and which skills apply. In other words, APX turns a file convention into behavior.

Why skills matter

A skill is more than a prompt snippet. In this stack, it is the smallest useful unit of operational knowledge.

Without skills, a runtime has to rediscover the project on every turn. It may still work, but it will work inconsistently. With skills, the runtime gets a stable local rule set:

read the root contract first
respect the agent layout in .apc/
keep runtime state outside the repo
treat curated memory as project knowledge, not transcript dumps

That makes APC portable in practice, not just in theory.

A good test is simple: if a new compatible tool can open the repo and immediately understand where project rules live, where durable memory lives, and where raw runtime state should stay, APC is doing its job. APX skills are what make that possible before every vendor ships native APC support.

The adoption loop

The flow is straightforward:

The repo carries APC files such as AGENTS.md, .apc/project.json, and curated agent memory.
APX installs skills into the local runtime.
The runtime reads the APC contract the same way every time.
Runtime state stays in ~/.apx/, not inside the repo.
The project stays portable across tools and machines.

That loop matters because it keeps the repo and the runtime in their proper roles.

APC says what the project is.

APX says how to work with it today.

Concrete example

Imagine a repo with one agent for reviews and one for implementation. The APC side can define the agent files and memory. The APX side can install the skills that teach a compatible runtime to:

discover the project root
load the correct agent context
use local runtime storage for sessions and messages
avoid treating transient output as committed project knowledge

The result is not just nicer ergonomics. It is less drift.

If the runtime knows the contract, the same repo behaves the same way across tools. That is a stronger guarantee than hoping every tool author independently recreates the same folder rules.

The deeper reason

APC is not a dashboard feature. It is a protocol for project meaning.

APX is not just a CLI wrapper. It is the adoption layer that makes the protocol real on day one.

That is why the two projects belong together but do not overlap:

APC stays durable, portable, and repo-owned.
APX stays local, operational, and runtime-owned.
Skills are the glue that lets the runtime respect the contract.

If you want the short version: APC defines the contract, APX teaches the runtime to obey it.

That is the useful path from spec to daily use.

DEV Community: Agent Project Context

Project Tasks Belong in APX, Not APC

Project Tasks Belong in APX, Not APC

Project Config Should Travel With APC

Project Config Should Travel With APC

Skill Bodies Should Load on Demand

Skill Bodies Should Load on Demand

Path-Scoped Rules Belong in APC

Path-Scoped Rules Belong in APC

One repo, different rule zones

Why APC should own these rules

Why this also helps APX

Practical example

Bottom line

Project Skills Should Override Global Skills

Project Skills Should Override Global Skills

Three skill lanes, one precedence order

Why APC needs the top slot

Why global skills still matter

Why built-in skills stay as the safety net

On-demand loading keeps prompt cost low

Practical rule

Bottom line

A Stable Project ID Keeps APC Portable and APX Local

A Stable Project ID Keeps APC Portable and APX Local

project.json gives the project a durable identity

Why that matters in daily work

Portable definition, local runtime

One practical rule

Bottom line

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Agent Slugs Are the Smallest Handoff Key Between APC and APX

Why this matters

What should stay stable

APC side, APX side

Practical rule

Not Every Memory Belongs in APC

Not Every Memory Belongs in APC

APC memory: portable, curated, team-safe

APX memory: local, operational, runtime-owned

Practical rule: decide by visibility, not by format

Why APC and APX fit together here

APC Plans Keep Durable Work Out of the Chat

APC Plans Keep Durable Work Out of the Chat

External Runtimes Should Read `AGENTS.md` Directly

External Runtimes Should Read AGENTS.md Directly

Why this matters

What APX should do

A concrete example

What not to do

Bottom line

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

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

What .apc/commands/ is for

Why markdown works

What belongs there

What does not belong there

Why the boundary matters

Bottom line

APX Skills Are the Adoption Layer for APC

APX Skills Are the Adoption Layer for APC

Why skills matter

The adoption loop

Concrete example

The deeper reason

`project.json` gives the project a durable identity

External Runtimes Should Read `AGENTS.md` Directly

What `.apc/commands/` is for