DEV Community: Agent Project Context

Give APC Rules a Useful Counterexample

Manuel Bruña — Tue, 15 Sep 2026 13:07:54 +0000

A project rule can be clear about its preferred behavior and still leave its boundary unclear. One small counterexample can show where the rule stops applying.

My thesis: when an APC instruction is easy to overgeneralize, add a nearby case that looks similar but requires a different decision. This gives reviewers a concrete way to check the instruction's meaning.

APC is the portable context layer: repository-owned guidance in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer that works with that context. Neither distinction removes the need to write instructions that a new contributor can interpret correctly.

Show the boundary, not just the happy path

Consider a hypothetical repository with this instruction:

Every user-visible label starts with a capital letter.

An agent could reasonably apply that sentence to every string rendered on screen. That would include command names, file paths, and fragments inserted into a longer sentence. The instruction needs a sharper definition of “label.”

A more useful version might say:

Start interface labels with a capital letter: buttons, headings, and tabs.
Example: "Project memory".

Preserve literal commands and paths exactly.
Counterexample: displaying `apx restart` does not make it "Apx restart".

Sentence fragments follow the sentence they join.

The counterexample does useful work because it is close to the rule. Both cases involve text on screen. The difference is whether the text names an interface element or represents a literal value.

This example is grounded in the APX repository's engineering guide, which distinguishes labels, sentence fragments, and data such as commands and slugs. The shortened wording above is an illustration, not a replacement for that repository's full contract.

Choose a plausible mistake

“Do not capitalize binary files” would be a weak counterexample here. It is too far from the decision an agent is likely to face.

A useful counterexample has three properties:

It shares the feature that could trigger the rule: here, visible text.
It identifies the distinguishing property: here, an exact command spelling.
It states the correct action: preserve the literal value.

The same pattern works in other domains. A hypothetical instruction to retry read failures could distinguish a failed read from a write whose outcome is unknown. A rule to normalize display names could explicitly preserve stable identifiers. Those are writing examples; each repository must define its actual behavior and constraints.

Avoid building a catalog of every possible exception. Choose the nearest misunderstanding that changes the outcome. If many exceptions are necessary, rewrite the main rule or split it into narrower rules.

Keep examples beside the instruction

The APC rules specification separates the root contract in AGENTS.md from reusable or path-scoped guidance in .apc/rules/. It also asks that rules remain concise, concrete, and reviewable.

Put the boundary example next to the relevant rule, wherever that rule belongs. A counterexample buried in a separate chat will not help a reader who receives only the instruction. Duplicating it across several files creates another maintenance problem.

During review, ask someone to classify two cases: one that should follow the rule and one that should not. If reasonable readers disagree, the text still needs work. This is a proposed review technique, not an APC validator or an APX feature that automatically checks prose.

Executable checks remain valuable where the distinction can be tested. The written rule explains the intended boundary; a test can catch a specific violation. An example alone does not enforce anything.

Portable context should carry enough meaning to survive a change of reader. Sometimes the most useful addition is one sentence showing exactly where an otherwise sensible rule stops.

Explore Agent Project Context on GitHub.

APX Community is now on Discord: build and orchestrate agents together

Manuel Bruña — Mon, 14 Sep 2026 17:39:10 +0000

APX Community now has a home on Discord.

APX (Agent Project eXecutable) is a local runtime, CLI, and web admin for AI agents, built on the APC protocol. It brings portable project context to life while keeping runtime sessions and private state local.

What you’ll find in the community

Help with APX setup, runtimes, engines, and the local daemon
Practical MCP workflows and integrations
Multi-agent patterns, experiments, and lessons learned
APC discussions: portable context, agent roles, skills, and project memory
Roadmap updates, release news, and community showcases
Spanish and English spaces

Whether you use Codex, Claude Code, OpenCode, Aider, Gemini CLI, or local models, you’re welcome. Bring questions, show what you’re building, and help shape an open, local-first agent ecosystem.

👉 Join APX Community: https://discord.gg/vxdZuT5WuE

Quick start

npm install -g @agentprojectcontext/apx
apx setup
apx init

Learn more: https://agentprojectcontext.github.io/apx/

GitHub: https://github.com/agentprojectcontext/apx

Give Temporary APC Instructions an Exit Condition

Manuel Bruña — Mon, 14 Sep 2026 12:03:42 +0000

Temporary project instructions need an exit condition. Otherwise, an exception written for a migration can keep steering agents long after the migration ends.

Imagine a repository moving from a legacy invoice parser to a replacement. During the transition, agents should keep both implementations and test their outputs against the same fixtures. Six months later, the old parser is gone, but a project instruction still says to preserve it. The instruction is readable, versioned, and wrong.

APC is the portable context layer: project guidance lives in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer that works with that context. Portability makes an instruction available across tools; it does not make yesterday's exception correct today.

Make the condition visible

Consider this hypothetical addition to a repository's AGENTS.md:

Keep the legacy invoice parser. Run both parsers when changing invoice handling.

That leaves the next contributor guessing. Is the old parser a permanent compatibility requirement? A rollback mechanism? An unfinished experiment?

A more useful instruction records the temporary boundary:

While the invoice parser migration remains open:
- Keep the legacy parser available for rollback.
- Compare both parsers using the committed compatibility fixtures.

Retire this instruction when the migration owner accepts the replacement
and removes the legacy rollback path. Update this section in that same PR.

The second version does not automate the decision. It tells a reviewer what decision must happen before the instruction can disappear. The fixture names, owner, and acceptance record would need real project-specific references in an actual repository.

A calendar deadline alone is weaker. Reaching Friday does not prove the replacement works. A date can prompt a review; an observable project condition explains whether the exception still applies.

Keep the permanent rule separate

The lasting requirement might be “preserve invoice compatibility.” Running two parsers is only one temporary way to establish that compatibility.

Write those ideas separately. When the migration ends, remove the dual-parser procedure while keeping the compatibility requirement and its relevant tests. Otherwise, deleting the temporary instruction can accidentally delete the reason the team needed it.

This fits APC's definition of project context: information that remains meaningful across editors, machines, and runtimes. A temporary instruction can still be shared project guidance, provided its scope and retirement condition are explicit. Durability should mean maintained knowledge, rather than text that nobody touches again.

Review retirement alongside implementation

For a migration PR, I would add a short review question: which existing instructions become false if this change lands?

Check the root contract, relevant agent definitions, and reusable instructions that mention the old behavior. Follow references instead of searching only the file edited during implementation. If the migration is partial, narrow the instruction to the remaining legacy path and retain its exit condition.

The APX repository's engineering guide includes a related practice: comments describing migrations should change when those migrations finish or are abandoned. Applying that same maintenance habit to project guidance is a proposed review workflow, not a claim that APC or APX automatically detects stale instructions.

A useful completion note can stay small:

Legacy parser removed after acceptance.
Temporary dual-parser instruction retired.
Compatibility requirement and replacement tests retained.

That note explains why guidance changed without copying the migration's entire conversation into the repository.

Version control preserves old decisions when you need to investigate them. Active context should explain what applies now. Giving temporary instructions an exit condition helps the next agent tell the difference.

Explore the portable context format in Agent Project Context on GitHub.

Moving a Folder? Review Your APC Rule Globs

Manuel Bruña — Sat, 12 Sep 2026 12:04:01 +0000

A folder rename can leave your application healthy while quietly disconnecting its agent instructions. Imports resolve, tests pass, and the rule file still reads well. Its path selector now points at yesterday's repository.

Treat a directory move as a change to the context map: review the relevant APC rule globs in the same pull request.

APC is the portable context layer, keeping project instructions in AGENTS.md and .apc/. APX is the daily-use runtime and tooling layer around that context. This example concerns the project-owned rule, so the durable fix belongs in APC.

The instruction survived; its target moved

Imagine a project with payment handlers under src/payments/. Its .apc/rules/payments.mdc contains this illustrative rule:

---
description: "Payment handler conventions"
globs:
  - "src/payments/**/*.ts"
alwaysApply: false
---

- Preserve the existing retry behavior when changing a handler.
- Include a duplicate-request case when testing a write operation.

The APC rules specification describes path-scoped MDC files and distinguishes them from the repository-wide contract in AGENTS.md. Actual selection and projection depend on the compatible consumer; the format alone does not prove a particular tool loaded the rule.

Now move those handlers to packages/billing/src/. The old selector no longer names their location. Nothing about that mistake requires invalid Markdown or malformed YAML. A syntax check can pass while the intended coverage disappears.

For this hypothetical move, the relevant edit is small:

 globs:
-  - "src/payments/**/*.ts"
+  - "packages/billing/src/**/*.ts"

Do not stop at replacing the prefix. If the new package also contains unrelated code, that replacement may widen the rule beyond its original purpose. Inspect the destination tree and choose the boundary deliberately.

Review coverage with concrete files

For a move like this, I would put three paths in the review notes:

A moved handler that should receive the rule.
A file outside billing that should not receive it.
A remaining file under the old location, if the migration is partial.

Those examples make the intended selection reviewable. During a staged migration, both locations may need coverage. After the last handler moves, remove the obsolete selector instead of accumulating paths indefinitely.

Validate those examples using the matching behavior of the consumer you actually use. Do not substitute a different glob library and assume its result proves editor behavior. Where the tool exposes loaded rules or generated configuration, inspect that evidence too. Where it does not, record that limitation rather than treating the agent's verbal assurance as a loading trace.

This is a proposed review practice, not a claim that APC ships an automatic coverage checker or that APX guarantees every editor's rule projection.

Keep narrow instructions narrow

Setting alwaysApply: true merely to make the missing guidance reappear changes the scope of the instruction. Before doing that, decide whether the guidance truly belongs on every task. A billing-specific convention usually deserves a repaired selector; a repository-wide requirement belongs in the root contract.

The practical habit is small: whenever a pull request moves a subsystem, review its rule selectors alongside imports and configuration paths. Keep the code move and its context adjustment together so a reviewer can see why both changed.

A useful rule needs accurate instructions and an accurate address. Maintaining only the prose leaves half the contract unattended.

Source project: Agent Project Context on GitHub.

Refresh APX Skills Without Replacing Your Dev Install

Manuel Bruña — Fri, 11 Sep 2026 12:02:43 +0000

You edit an APX skill, open your coding assistant, and get the old instructions again. The Markdown change is correct. The assistant may simply be reading a different file.

For contributors working from a linked APX checkout, refreshing installed skills is a separate operation from upgrading APX. Use apx skills sync when the change needs to reach the external tools' global skill directories.

Follow the file the consumer reads

Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions shared by compatible tools. APX is the daily-use runtime and tooling layer, with a local daemon, CLI, and execution surfaces.

That division also helps explain skill delivery. A project contract and a machine's installed helper files have different lifecycles. Committing an instruction does not automatically refresh every copy already installed on a developer's machine.

APX has two relevant locations inside its package:

src/core/runtime-skills/ contains instructions consumed by APX's own runtime.
skills/ supplies the separate bundled catalog distributed to external tools.

The skills documentation distinguishes these catalogs. Editing one does not imply that a consumer of the other will see the change.

A small stale-copy example

Suppose a bundled helper still describes an outdated command. You correct its source in the development checkout, then ask an external coding tool to repeat the workflow. It suggests the outdated command again.

Before rewriting the instruction, inspect the delivery path:

Confirm that your apx executable resolves to the development installation you intend to test.
Run the bundled skill refresh.
Inspect the installed helper in the target tool's global skill directory.
Verify the corrected passage is present, then exercise the workflow in the consuming tool.

The refresh command is:

apx skills sync --verbose

APX's sync handler calls the shared installer and reports results by skill and destination. Its output distinguishes created, updated, unchanged, and pruned entries. Check the destination you actually use; a successful write elsewhere does not prove your assistant read the new text.

This workflow verifies distribution first. Whether an already-open external assistant reloads its instructions is a separate question, governed by that tool. Do not treat a copied file as proof that an existing conversation has refreshed its context.

Why an upgrade is the wrong repair here

The APX contributor guide warns against using apx update to refresh a linked development checkout. An upgrade can replace the global link with a published package, leaving subsequent commands pointed at released code instead of your working tree. See the development loop.

The update implementation installs a published version through a global package manager. That is appropriate when upgrading an installed release. It is unnecessary when the intended change is a local instruction file.

The package's postinstall hook also calls the skill installer. Merely editing a development checkout does not run that hook, which explains why an explicit sync is useful.

For APX's own runtime skills, the contributor guide documents loading from the package path on demand. Diagnose that path separately; refreshing external copies cannot fix a change made in the wrong catalog.

The useful debugging question is precise: which file does this consumer read, and what operation puts the new content there? Answer it before changing the prompt again.

Project: APX on GitHub.

Grow APC Context From Real Decisions

Manuel Bruña — Thu, 10 Sep 2026 12:08:11 +0000

A directory tree in documentation is easy to mistake for a setup checklist. You see agents, skills, rules, memory, and tool configuration, then create a placeholder for everything before an agent has done any useful work.

My recommendation for APC adoption is narrower: add a context file when you can explain which recurring decision it improves. A full-looking tree is not evidence of useful context.

Separate the contract from the example

Agent Project Context (APC) is the portable context layer: repository-owned instructions and definitions that compatible tools can share. APX is the daily-use runtime and tooling layer, providing local execution through its CLI, daemon, and other surfaces.

That distinction matters during onboarding. Designing project context and configuring an execution environment are separate jobs. Installing more runtime features does not make a vague project instruction more precise.

The APC draft identifies .apc/project.json as its metadata file. Its fields describe the project name, project version, APC target version, and creation time. That metadata has a specific purpose; it is not a place to collect every setting a developer might eventually need. See the workspace metadata specification.

Likewise, the folder structure specification explicitly describes path-scoped rules as optional. A canonical location tells you where content belongs when you need it. It does not make an empty file useful.

Start with an actual mistake

Consider a hypothetical API repository where agents repeatedly edit generated client files. Before designing several specialist roles, put the relevant instruction in the root contract:

# Project Context

- Generated clients live in `src/generated/`; change the schema instead.
- Regenerate clients after schema changes.
- Run the repository's documented API compatibility checks before merge.

These instructions identify a boundary, an alternative action, and a verification requirement. They are useful even before the team has a sophisticated agent setup. In a real repository, replace the generic check reference with the command your project actually documents.

Now suppose the same schema update requires a repeatable sequence: edit the schema, regenerate clients, inspect compatibility, and update examples. That is a reason to write a reusable project skill. Its value comes from preserving the sequence that people otherwise forget.

Later, if backend-only constraints start overwhelming the root contract, a path-scoped rule has a concrete job. You are moving an existing instruction to a more precise loading boundary, with the consuming tool's support checked explicitly.

This is a proposed adoption workflow, not a claim that every tool implements every APC directory or that this article defines a formal minimum layout.

Avoid speculative context

A placeholder such as “follow best practices” gives a reviewer almost nothing to verify. A fictional release process can be worse: an agent may follow it because the repository presents it as authoritative.

For each proposed file, ask:

Which repeated question does this answer?
Who can verify that the answer is current?
What future change should trigger an update?

If those answers are missing, investigate the workflow before writing instructions for it. Empty structure can wait; incorrect guidance creates work immediately.

APX remains useful on the execution side as the project grows. Its local sessions and message history should stay in runtime-owned storage, rather than becoming filler for .apc/. The APX repository documents that storage boundary and its CLI workflow.

The practical measure is whether the next contributor or compatible agent makes fewer avoidable mistakes. Grow the context around observed needs, and review each new instruction as carefully as the code it will influence.

Project: Agent Project Context on GitHub.

A Health Check Should Identify the Runtime It Found

Manuel Bruña — Wed, 09 Sep 2026 12:05:01 +0000

A Health Check Should Identify the Runtime It Found

A green health endpoint can answer the wrong question. It may prove that a process responds on a port without proving that it is the process, configuration, or local state your client expects.

APX hit this distinction in a concrete way. One daemon could serve the normal ~/.apx home while another started with a temporary APX_HOME. Under a wildcard-versus-loopback bind, both could hold the same port, and local traffic could quietly reach the more specific listener. No obvious bind error appeared. Both daemons could still report status: ok.

The thesis: local runtime health needs a minimal identity signal, not liveness alone.

Why `ok` was misleading

An APX daemon owns machine-local state: configuration, authentication tokens, registered projects, message history, and channel connections. The port is only an address. It does not define which state directory the process serves.

Imagine this sequence:

normal daemon  -> port 7430 -> ~/.apx
test daemon    -> port 7430 -> /tmp/test-home/.apx
CLI request    -> port 7430 -> test daemon

The test daemon is technically healthy. Its database opens. Its HTTP server replies. Yet it has the wrong token store, an empty project list, and no live channels. From the client view, authentication suddenly fails and conversations disappear. A boolean health check cannot explain why.

A PID file does not solve this across homes either. If each APX_HOME owns its own PID file, the two daemons cannot see each other's lock. The collision exists at the port boundary, outside either state directory.

Add identity without exposing paths

APX now includes home_id in its unauthenticated health response. The value is a truncated SHA-256 digest of the effective APX_HOME, not the filesystem path itself.

{
  "status": "ok",
  "version": "1.92.3",
  "uptime_s": 42,
  "home_id": "<path fingerprint>"
}

Before binding, a starting daemon asks the loopback health endpoint who is already serving the port. If the returned fingerprint belongs to a different home, startup stops with a useful error. The operator can stop the other daemon or assign a separate APX_PORT.

This is deliberately narrow. The check does not publish a private absolute path. It also does not reject every listener it cannot identify. An older APX version may not return home_id, and a normal restart can briefly overlap with the outgoing process. APX fails open for those ambiguous cases, preserving restart behavior while catching the collision it can prove.

APC defines context; APX identifies execution

Agent Project Context (APC) is the portable context layer. AGENTS.md and .apc/ carry durable project instructions, agent definitions, skills, and safe shared facts across tools and machines. They should not encode one computer's daemon port or state directory.

APX is the daily-use runtime and tooling layer. It turns that portable contract into local execution through its daemon, CLI, web admin, channels, sessions, and stores. Runtime identity therefore belongs in APX health and startup checks, not in APC project files.

That separation keeps the repository portable while making local operations diagnosable. The same APC project can move between machines; each APX runtime can still prove which local home it serves.

General rule

For any local agent daemon, ask three different questions:

Liveness: did something answer?
Readiness: can it serve requests?
Identity: is it serving the state this client expects?

Collapsing all three into ok creates failures that look impossible: healthy service, broken application. A small, non-secret identity fingerprint turns that mystery into an explicit startup decision.

A2A History Should Replay Speech, Not Tool Output

Manuel Bruña — Tue, 08 Sep 2026 12:03:55 +0000

A2A History Should Replay Speech, Not Tool Output

An agent-to-agent thread has two audiences: the next agent turn needs a clean conversation, while the human operator needs evidence of what each agent actually did. Treating both audiences as one transcript creates a subtle failure mode: raw tool output starts masquerading as dialogue.

APX separates those concerns. A peer receives the messages that participants said. Tool execution remains attached to the reply as trace metadata, available for inspection without being replayed as conversation.

The thesis is simple: preserve tool traces for accountability, but do not spend conversational context on them.

How a useful thread becomes noise

Consider an APX A2A exchange:

reviewer -> opencode: Check the rendering issue.
opencode -> tool: npm run lint
opencode -> tool: a complete HTML document
opencode -> reviewer: Fixed and verified.
reviewer -> opencode: Continue with the mobile view.

If APX rebuilds history by selecting every row shared by those two participants, the next prompt may include the lint output and full HTML document as if they were earlier messages. The peer must then recover six words of intent from thousands of characters of exhaust.

This is worse than cosmetic clutter. Tool output can dominate the context window, obscure decisions, and make an agent infer that machine-generated data was something a participant intentionally said. A long-running collaboration gradually becomes less coherent even though every individual tool call succeeded.

APX therefore filters A2A history to conversational rows. Earlier requests and final replies survive. Raw tool-result rows do not enter the reconstructed dialogue.

Keep evidence, change its lane

Filtering tool output from history must not make agent work invisible. A final reply such as "fixed and verified" is only a claim unless the operator can inspect the actions behind it.

APX keeps the tool trace on the agent reply's metadata. The thread viewer can expose that trace as an action group: which tools ran, their arguments, and their results. A reply with no tool calls carries no action group. That difference helps a human distinguish completed work from an unsupported assertion.

One event now serves two views without corrupting either:

conversational text becomes future agent context;
trace metadata becomes operator evidence.

The trace remains connected to the reply that produced it, but it is not promoted into the next turn's prose.

APC and APX own different parts

Agent Project Context (APC) is the portable context layer. It stores durable project instructions, agent definitions, skills, and safe shared facts in AGENTS.md and .apc/. Those artifacts explain how agents should work across tools and machines.

APX is the daily-use runtime and tooling layer. It executes A2A turns, stores local message history, runs tools, and shapes the thread shown to an operator. Tool traces and runtime transcripts belong there because they describe machine-local execution, not portable project truth.

This boundary matters. Copying raw A2A traces into APC would turn a stable project contract into an ever-growing activity log. Dropping traces entirely would make runtime claims hard to verify. APX can retain them locally while APC stays clone-safe.

A practical rule for agent systems

When designing multi-agent history, ask what each record is for.

A user request, delegation, decision, or final answer belongs in replayable dialogue. A shell dump, file body, HTTP response, or intermediate tool envelope belongs in an execution trace. Both may need persistence, search, and a UI, but they should not automatically share a prompt budget.

This separation gives future turns better signal and gives humans better evidence. Clean context and auditability are not competing goals. They only conflict when one storage shape is forced to do both jobs.

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

Manuel Bruña — Mon, 07 Sep 2026 12:04:39 +0000

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

A process can be alive while the capability you need is missing. For a local AI runtime, that distinction matters: an Ollama server answering HTTP requests does not prove that the configured model is installed.

APX treats those as separate facts. When routing a turn to an Ollama model, it checks both the server and the candidate model before accepting the route.

This is a small reliability rule with a broad lesson: health checks should test the dependency your operation actually requires, not merely the service around it.

The false-positive health check

Imagine this APX configuration:

{
  "super_agent": {
    "model": "ollama:qwen3:8b",
    "model_fallback": {
      "models": ["openrouter:openrouter/free"]
    }
  }
}

Ollama may answer GET /api/tags successfully while qwen3:8b is absent. A simple status-code check would mark Ollama healthy, select it, and delay failure until the actual model call. The router would have made a confident decision using incomplete evidence.

APX instead passes the candidate model into the provider health check. Its Ollama adapter reads the models returned by /api/tags and verifies that the requested model is available. If the server responds but the model is missing, the result is unhealthy for that route and includes the available model names for diagnosis.

The configured fallback chain can then continue naturally. No manual edit is needed just because a daemon was reachable but incomplete.

Why this belongs in APX, not APC

Agent Project Context (APC) is the portable context layer. It keeps durable project instructions, agent definitions, skills, and safe configuration hints in the repository. A project may state which model an agent should use, but it cannot guarantee that a particular machine has pulled that local model.

APX is the daily-use runtime and tooling layer. It knows the current machine, configured engines, credentials, endpoints, and locally available Ollama models. That makes APX the right place to turn a portable preference into a runtime decision.

Keeping this boundary clear prevents two bad outcomes. First, APC does not accumulate machine-specific availability state. Second, APX does not treat repository configuration as proof that an external capability exists.

Health must match the routing question

Different callers can ask different health questions. A general status screen may only need to know whether Ollama responds. A router evaluating ollama:qwen3:8b needs a stricter answer: can this provider serve this model now?

APX supports that distinction. Without a candidate model, the Ollama health probe can remain loose and report server reachability. With a candidate, it validates model presence. The router uses the strict form while walking its ordered model chain.

This avoids making every health probe unnecessarily expensive or specific, while still protecting the execution path that matters.

A practical design rule

When adding health checks to any agent runtime, write down the decision they guard.

If the decision is "show provider online," reachability may be enough.
If the decision is "send this turn to this model," verify that model.
If the decision is "run this tool," verify the tool's required dependency, not only its host process.

Also preserve diagnostic detail. "Unhealthy" is less useful than "server running; configured model not loaded." APX keeps the attempted models and reasons, so fallback behavior remains observable rather than mysterious.

Portable context gives every machine the same intent. Runtime-aware health checks let each machine execute that intent honestly.

Declare `tools` Only When Narrowing an APX Agent

Manuel Bruña — Sun, 06 Sep 2026 12:02:35 +0000

Declare `tools` Only When Narrowing an APX Agent

An agent definition should describe a durable role without freezing a temporary snapshot of the runtime around it. That is why APX treats an omitted tools field differently from a declared list.

The rule is small: omit tools when the agent should inherit APX's broad project-agent default. Declare a non-empty list only when you intentionally want a narrower allowlist.

This distinction connects the two layers. Agent Project Context (APC) is the portable context layer: the repository can carry an agent definition in .apc/agents/<slug>.md. APX is the daily-use runtime and tooling layer: it resolves that portable definition against the callable tools available on the current machine.

Omission preserves capability

Consider a project agent created without --tools:

apx agent add release-notes \
  --role Writer \
  --prompt-file ./prompts/release-notes.md

APX leaves the Tools frontmatter field undeclared. At runtime, that agent receives the broad default tool allowlist: the callable registry minus operations that belong only to the host, such as changing APX's identity, widening the permission mode, adding projects, or importing agents.

This default matters because real work crosses boundaries. A writing agent may need to read files today, call an MCP publishing tool tomorrow, and create a follow-up task next week. If creation writes today's catalog into the portable agent file, new runtime capabilities remain unavailable until someone edits the definition. The APC file becomes an accidental lockfile for APX internals.

Omission avoids that coupling. The agent keeps its stable role and instructions while APX supplies an appropriate default from the runtime it actually has.

Declaration means deliberate narrowing

Now consider a reviewer that should only inspect repository content:

apx agent add reviewer \
  --role Reviewer \
  --prompt-file ./prompts/reviewer.md \
  --tools read_file,glob

APX writes the selected tools into the agent definition. From then on, the list acts as an allowlist, not documentation or a suggestion. The reviewer does not gain run_shell, write_file, or call_mcp merely because those tools exist in the runtime.

That makes a declared list useful for agents with a genuinely constrained job:

a read-only reviewer
a documentation inspector that should not execute commands
a specialist that may call one approved MCP path but not general shell tools

The tradeoff is maintenance. A narrow list stays narrow when APX adds capabilities. That is the intended result, but only when restriction was the intent. Copying every currently available tool into the file creates maintenance cost without adding a meaningful boundary.

Capability is not prompt size

A broad allowlist sounds expensive if you imagine every tool schema entering every prompt. APX separates those concerns. The allowlist answers which tools the runtime may permit. Lightweight channels can still start with a small base set and discover additional tools when needed.

So narrowing an allowlist is a capability decision, not a prompt-budget optimization. Use it to remove powers, not to make an agent look tidy.

A practical review rule

When reviewing .apc/agents/*.md, ask why each tools list exists.

If the answer names a boundary — "this reviewer must remain read-only" — keep it. If the answer is "these were the tools available when we created the agent", remove the field and let APX resolve the default.

Also remember that runtime-specific overrides can be stricter for one execution. APX routines can replace an agent's normal allowance for a particular run, including running with no tools. That operational decision belongs in APX runtime configuration, while the APC agent file keeps the durable project-level intent.

Portable definitions work best when they state constraints that should survive across machines. Omitted tools says capability may evolve with the runtime. A declared list says this boundary must not.

APC's .gitignore Is a Safety Net, Not a Storage Policy

Manuel Bruña — Sat, 05 Sep 2026 12:03:17 +0000

APC's `.gitignore` Is a Safety Net, Not a Storage Policy

A .gitignore entry can prevent an accidental commit. It cannot turn the wrong storage location into the right one.

That distinction matters in Agent Project Context (APC). APC is the portable context layer: repository-owned rules, agent definitions, reusable skills, project metadata, and carefully curated memory. APX is the daily-use runtime and tooling layer: it runs agents and keeps sessions, conversations, messages, caches, and local state on the machine.

The thesis is simple: .apc/.gitignore is a defensive boundary for mistakes and legacy files, not permission to store runtime data under .apc/.

What the file protects

The APC folder specification recommends ignoring paths such as:

agents/*/sessions/
agents/*/conversations/
sessions/
conversations/
messages/
chats/
cache/
tmp/
private/
secrets/
*.local.json
*.secret.json
*.env
*.env.*
mcps.local.json
migrate.md

These patterns reduce damage when an older tool, manual script, or mistaken integration writes runtime artifacts inside .apc/. A session transcript containing a private prompt should not enter Git history merely because it appeared beside a valid agent definition.

But ignored does not mean correctly placed.

A growing .apc/sessions/ directory is still a design error. It remains tied to one runtime, machine, or provider. It does not become portable project context just because Git cannot see it.

The correct two-layer model

APC should answer: what must another contributor or compatible tool learn from this repository?

Examples include:

AGENTS.md for the broad project contract
.apc/project.json for stable project metadata
.apc/agents/<slug>.md for agent definitions
.apc/skills/ for reusable project instructions
.apc/memory.md or agent memory files for reviewed, team-safe facts
.apc/mcps.json for non-secret MCP hints

APX should answer a different question: what local state does the runtime need to continue operating?

APX stores runtime data under ~/.apx/projects/<project-id>/. That includes sessions, conversations, messages, and local runtime memory. Other IDEs and runtimes can use their own local stores. None of those stores need to be standardized by APC.

This separation keeps a clone useful without making it invasive. A new machine receives durable project context from Git, then its chosen runtime creates fresh local state outside the repository.

A practical review test

When a new file appears under .apc/, ask three questions:

Would every contributor benefit from reading it?
Is it safe to commit and review?
Does it remain useful after the current session, machine, and provider disappear?

If any answer is no, the file probably belongs in runtime-local storage. Adding another ignore rule may prevent leakage, but it does not fix ownership.

Suppose an agent finishes a long debugging session. The raw transcript belongs in APX or the originating runtime. A short, reviewed fact such as "the parser rejects duplicate keys" may deserve promotion into APC memory or project documentation. Promotion means extracting durable knowledge, not moving the transcript.

Why this matters beyond neat folders

Putting local data under .apc/ creates hidden coupling. Backup tools may copy it. Editors may index it. Scripts may mistake it for project input. Contributors may assume an ignored directory is part of the standard. Private material also sits unnecessarily close to files intended for publication.

Keeping runtime state outside .apc/ removes that ambiguity.

APC stays small, portable, inspectable, and safe to share. APX remains free to manage richer operational history locally. The ignore file catches boundary violations before they become permanent, while the storage model prevents those violations in the first place.

Use .apc/.gitignore as a seat belt. Do not use it as a parking permit.

Planning Is Not a Guardrail in APC and APX

Manuel Bruña — Fri, 04 Sep 2026 12:03:27 +0000

Planning Is Not a Guardrail in APC and APX

A planning note can explain why a project may change next week.

A guardrail has to explain how the project works today.

That difference matters more once you split portable context from runtime behavior.

APC is the portable context layer. It keeps project-owned facts in repository files such as AGENTS.md and .apc/, so another tool, another machine, or another contributor can recover the same contract from the clone itself.

APX is the daily-use runtime and tooling layer. It reads that contract, adds local runtime state, and turns it into actual work through the CLI, daemon, web admin, channels, sessions, and local stores.

That split only stays clean if durable rules live in tracked files, while planning stays local.

Why this boundary matters

The APX repo says it directly in spec/README.md: planning is not a guardrail.

That file keeps spec/ gitignored on purpose. Roadmaps, backlog notes, PRDs, and active design scratch work stay there because they are temporary, local, and often unsafe to publish as stable project truth.

The durable material lives elsewhere.

In the same repo, rules/ is the tracked engineering contract. It holds the workflow, architecture constraints, testing expectations, documentation rules, and decision records that contributors actually need in order to work correctly.

That is the right split.

If a new contributor clones the repo, a guardrail must already exist in the clone. A local planning note is not enough.

APC makes the distinction sharper

Without APC, many teams let this blur. A roadmap note, a scratch design doc, and an actual project rule all end up in some folder called docs or notes, and the runtime figures it out later.

APC makes that sloppiness more expensive.

Portable context is supposed to travel.

If you commit planning noise as if it were project contract, other tools will read unstable material as if it were durable truth. If you keep real rules only in local notes, fresh clones lose the instructions they actually need.

So APC should carry committed, reviewable project context.

APX should consume that context and keep its own local runtime state outside the repo.

Planning belongs to neither category. It is not stable enough for APC, and it is not runtime state either. It is just local working material.

Practical example

The APX repo uses three lanes that make the difference easy to see.

AGENTS.md is the always-read root contract for agents and repo rules.
rules/ holds tracked deep dives, workflows, and architectural decisions that other contributors must be able to read.
spec/ holds local planning documents that do not ship.

That means a contributor can clone the repo and get the durable contract immediately.

They do not depend on one maintainer's unfinished roadmap file.

It also prevents another common failure: tracked files linking to local-only planning docs. The APX spec/README.md calls this out explicitly because those links were dead in fresh clones and on GitHub. That is exactly what happens when a team mistakes internal planning for public contract.

Why APX benefits from this too

APX is a runtime, so it already has to separate what belongs in the repository from what belongs on one machine.

Sessions, conversations, messages, caches, and secrets stay under ~/.apx/ because they are runtime-local.

But that does not mean every important note should become runtime state.

The workflow rules, architecture boundaries, and contributor-facing decisions still belong in tracked repo files, because they define how humans and tools should operate on the project itself.

So the real split is three-way:

APC holds portable project context.
APX holds local runtime state and tooling behavior.
planning stays local until it becomes either durable project contract or disposable scratch work.

That middle step is easy to skip, but skipping it creates confusion fast.

Small rule, big payoff

The practical rule is simple:

If another contributor must rely on it today, track it.

If it only describes work in flight, keep it local.

That rule makes APC cleaner because portable context stays durable.

It makes APX cleaner because runtime storage does not become a dumping ground for project guidance.

And it makes the repo easier to trust, because readers can tell which files describe the project as it exists now versus one person's temporary plan.

Planning is useful.

It just is not the contract.

DEV Community: Agent Project Context

Give APC Rules a Useful Counterexample

Show the boundary, not just the happy path

Choose a plausible mistake

Keep examples beside the instruction

APX Community is now on Discord: build and orchestrate agents together

What you’ll find in the community

Quick start

Give Temporary APC Instructions an Exit Condition

Make the condition visible

Keep the permanent rule separate

Review retirement alongside implementation

Moving a Folder? Review Your APC Rule Globs

The instruction survived; its target moved

Review coverage with concrete files

Keep narrow instructions narrow

Refresh APX Skills Without Replacing Your Dev Install

Follow the file the consumer reads

A small stale-copy example

Why an upgrade is the wrong repair here

Grow APC Context From Real Decisions

Separate the contract from the example

Start with an actual mistake

Avoid speculative context

A Health Check Should Identify the Runtime It Found

A Health Check Should Identify the Runtime It Found

Why ok was misleading

Add identity without exposing paths

APC defines context; APX identifies execution

General rule

A2A History Should Replay Speech, Not Tool Output

A2A History Should Replay Speech, Not Tool Output

How a useful thread becomes noise

Keep evidence, change its lane

APC and APX own different parts

A practical rule for agent systems

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

A Running Ollama Server Does Not Mean Your APX Model Is Healthy

The false-positive health check

Why this belongs in APX, not APC

Health must match the routing question

A practical design rule

Declare `tools` Only When Narrowing an APX Agent

Declare tools Only When Narrowing an APX Agent

Omission preserves capability

Declaration means deliberate narrowing

Capability is not prompt size

A practical review rule

APC's .gitignore Is a Safety Net, Not a Storage Policy

APC's .gitignore Is a Safety Net, Not a Storage Policy

What the file protects

The correct two-layer model

A practical review test

Why this matters beyond neat folders

Planning Is Not a Guardrail in APC and APX

Planning Is Not a Guardrail in APC and APX

Why this boundary matters

APC makes the distinction sharper

Practical example

Why APX benefits from this too

Small rule, big payoff

Why `ok` was misleading

Declare `tools` Only When Narrowing an APX Agent

APC's `.gitignore` Is a Safety Net, Not a Storage Policy