DEV Community: Agent Project Context

Load Nested AGENTS.md Rules at the Folder Boundary

Manuel Bruña — Fri, 23 Oct 2026 13:43:24 +0000

Load Nested AGENTS.md Rules at the Folder Boundary

A project needs shared instructions, but it does not need every instruction in every turn. The useful rule is: put folder-specific guidance in that folder's AGENTS.md, then load it when work reaches that folder.

That sounds like a small organization detail. It is actually a context-quality boundary. If a repository-wide agent prompt carries every rule for the mobile app, deployment scripts, data migration, and marketing site, most of those rules are irrelevant most of the time. The important instruction becomes harder to notice precisely when it matters.

Keep root guidance truly shared

An APC project keeps portable context in the repository. Root AGENTS.md is the place for rules that apply across the project: conventions, commands, safety constraints, and an index of the project-level agent setup. It should answer questions that matter no matter which directory a task touches.

For example, a root file might say:

Run the repository test suite before changing shared packages.
Do not commit credentials or generated runtime state.
Use the documented release workflow.

Those are project facts. They are useful to a compatible tool from a fresh checkout, and they stay useful whether the next edit is in api/, web/, or infra/.

Put local rules next to local work

Now consider a migration directory that needs a special ordering rule, or a service folder that has a separate test command and an external API contract. Those instructions should not become permanent background for an unrelated documentation edit. Give the directory its own AGENTS.md instead:

repo/
├── AGENTS.md
├── api/
│   ├── AGENTS.md
│   └── migrations/
└── web/
    └── AGENTS.md

The api/AGENTS.md can explain migration safety and API checks. The web/AGENTS.md can describe component conventions and browser tests. Each file has a narrow owner: the folder beneath it.

This is not an excuse to hide global policy in a deep directory. A rule belongs there only when its scope really starts there. A ban on secrets belongs at the root; a warning about a destructive database fixture can belong with the fixture. Scope should follow the work boundary, not the writer's desire to keep a file short.

Attach instructions when the tool crosses the boundary

APX makes this structure operational. For a project turn, it supplies the project AGENTS.md and identifies subfolders with their own instruction files. When a tool first touches one of those folders in that turn, APX attaches the folder's rules to the tool result. The agent receives the local rule at the moment it has evidence that the task reached that part of the tree.

That timing matters. Imagine a request to update a landing-page headline. The agent should not begin with database migration instructions. If the same task later changes an API schema, the API guidance appears when the work enters api/. The context grows with the actual path of work instead of arriving as an unfiltered manual.

Portable contract, local execution

APC provides the portable contract: committed AGENTS.md files travel with the repository and can be reviewed like other project decisions. APX is the daily-use runtime: it selects relevant project context during a turn while keeping conversations, tool history, and private runtime state local.

Together, they support a simple habit: write root rules for the whole project, write nested rules for real local boundaries, and let the runtime reveal local guidance when the task crosses that boundary. Less prompt noise is not merely tidier. It gives the right instruction a better chance to govern the right action.

A Runnable Project Needs Both Instructions and Identity

Manuel Bruña — Thu, 22 Oct 2026 11:57:59 +0000

A Runnable Project Needs Both Instructions and Identity

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

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

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

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

Why one file is not enough

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

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

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

A small, reliable setup

Start with a repository root like this:

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

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

Then register the project explicitly:

apx project add .

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

apx project rebuild <id|name|path>

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

The useful rule

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

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

Create a Specialist Agent Only After Its Work Boundary Is Stable

Manuel Bruña — Wed, 21 Oct 2026 12:03:08 +0000

Create a Specialist Agent Only After Its Work Boundary Is Stable

Adding an agent is easy. Giving it a durable job is harder.

The useful rule is: create a specialist only when its work boundary is stable enough to write down, review, and reuse. Until then, keep the work with a main agent and improve the shared project guidance.

This is where APC and APX have different jobs. APC is the portable layer: it keeps a project's shared rules, structured agent definitions, reusable skills, and safe curated context in the repository. APX is the runtime layer: it makes those agents useful in daily work through conversations, tools, routines, and local state. A runtime can start an agent immediately; that does not make the agent design ready to travel.

A role is not a label

A weak specialist is only a name: researcher, writer, or support. It sounds organized, but it does not tell another person—or another runtime—what the agent owns, what it must consult, or where it must stop.

A stronger role has a boundary. Consider a support workflow:

The agent handles first responses and routine refund triage.
It uses the project's refund policy and escalation skill.
It escalates large refunds rather than approving them.
It writes in the project's customer-facing language.

That is a contract, not a personality. It can live in an APC agent definition and linked skills, be reviewed in a pull request, and be read by compatible tooling after a fresh checkout.

Start with one repeated decision

Do not split work because a team diagram looks better with more nodes. Split it when one decision pattern keeps returning and has clear inputs, constraints, and handoff conditions.

For example, a main agent may initially answer support questions, check policy, and call for human review when needed. After that pattern is repeated, the project can extract a support specialist. The extraction should preserve the decision boundary:

Inputs: customer request and account context
Rules: published refund window and escalation threshold
Output: response, or a clearly named escalation
Not owned: legal negotiation or approval beyond the threshold

This small shape prevents a common mistake: creating a specialist that overlaps every other agent and silently makes choices outside its intended role.

Put durable detail in the right place

APC gives the boundary a portable home:

AGENTS.md holds project-wide rules.
.apc/agents/<name>.md states the specialist's role and instructions.
.apc/skills/ holds reusable procedures shared by one or more agents.
.apc/ excludes raw conversations, credentials, and runtime caches.

APX can then use that contract while keeping the daily machinery local: sessions, messages, private runtime memory, provider credentials, and tool execution belong to the runtime rather than the repository.

That separation matters during change. Updating a support rule is a project decision. It should be visible in the portable contract. A chat transcript from yesterday is runtime evidence, not the new source of policy.

A practical test before adding an agent

Before creating a specialist, write four lines: purpose, inputs, constraints, and handoff. If those lines stay vague, the work is probably still main-agent work. If they are precise, the project has something worth encoding in APC.

Then APX can run the agent in the places people actually work. The runtime gives the role a daily presence; APC keeps the role from becoming a local, unreviewed convenience.

A good specialist is therefore not another prompt to maintain. It is a portable promise about a narrow kind of work.

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

Manuel Bruña — Tue, 20 Oct 2026 12:04:30 +0000

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

A permission prompt looks small: approve or deny. But the important question is not only whether an agent may run a tool. It is how far that approval reaches.

APX treats that reach as an explicit boundary. A one-time approval is one execution. A session approval belongs to one conversation. An always approval belongs to one agent, including later conversations and a restart. Those are different decisions, so they must not blur into one friendly-looking button.

The dangerous shortcut

Many agent products make approval feel like a binary switch. A person allows a harmless read, then later discovers that the agent stopped asking. The original decision silently became broader than the person intended.

That is especially risky when a tool can receive different arguments over time. Approving a request to read one note is not necessarily approval to read every note, call a different endpoint, or let a second agent act in another chat.

APX starts from the narrowest useful default: once. The approval runs the pending tool call, then disappears. The next request creates a new prompt. No permanent grant is created as a side effect.

Agent: use notes.search({ query: "release checklist" })
Human: approve once
APX: runs that call

Agent: use notes.search({ query: "customer contracts" })
APX: asks again

The second prompt is not friction by accident. It preserves a chance to notice that intent or data changed.

Choose scope deliberately

APX exposes three scopes for an eligible approval:

once: only pending call; no saved grant.
session: later turns in same chat can use tool, even when arguments change. Other chats still ask. Revocation can remove grant.
always: same agent can use tool across its chats and after runtime restart. Other agents still ask.

This makes a practical review habit possible. Start with once while learning what an MCP tool does. Move to session when a single conversation needs repeated work. Choose always only when tool, agent, and long-term purpose are all known and acceptable.

The boundary is not merely user-interface language. APX tests that a session grant does not unlock another chat, that an always grant remains tied to its agent, and that revocation restores a prompt. It also rejects attempts to turn a denial into a wider grant; agents themselves cannot grant permissions.

Separate tool trust from project context

This is runtime policy, not portable project context. APC carries the repository-owned contract: AGENTS.md, .apc/, agent definitions, skills, and durable team guidance. It can say that a project uses a particular workflow or needs careful handling.

APX is the local runtime that executes a particular conversation. Approval records, pending prompts, and revocations describe a local operational decision. They should not become a hidden rule inside a portable repository. A fresh checkout should inherit documented project intent, not someone else's unreviewed tool grant.

That separation also keeps responsibility clear. APC can explain why a project needs a tool. APX asks a human whether this agent may use it now, and for how long.

A small rule that scales

Treat every broader scope as a new claim:

This call is safe now.
This conversation can repeat it.
This agent may keep doing it later.

Each step needs more evidence than the last. A scope selector that reflects that difference turns permission from a vague comfort signal into an auditable control boundary.

APC keeps project intent portable. APX keeps operational authority local, explicit, and revocable. That is slower than silently upgrading one approval into permanent trust—but much easier to trust in real work.

An Interrupted Tool Call Needs an Explicit Ending

Manuel Bruña — Mon, 19 Oct 2026 12:05:11 +0000

An Interrupted Tool Call Needs an Explicit Ending

An agent can begin a tool call and lose its turn before receiving a result. A browser closes, a provider times out, a runtime restarts, or a person stops the work. That gap is ordinary. Pretending it never happened is not.

The useful rule is small: an interrupted tool call needs an explicit ending in conversation history. APX follows that rule when it repairs chat history. Rather than leaving an unanswered request dangling, it records that the tool was not run because the turn was interrupted.

Why a dangling call is a problem

Tool-using model APIs expect a strict sequence. An assistant message requests a tool, then a corresponding tool result returns. If history contains the first half but not the second, the next turn inherits an ambiguous state.

Did the browser search happen? Did a file get written? Is a retry safe? A model should not have to guess. Nor should a later reader infer success from an assistant message that only asked for an action.

Consider a short history:

User: Check the deployment dashboard.
Assistant: calls browser_text({ url: ... })
[process interrupted]
User: What did it find?

Without repair, the last question invites invention. A plausible answer may sound like a dashboard summary even though no result exists. That is worse than a visible interruption because it turns missing evidence into a claim.

Repair the structure, not the story

APX's runtime-history repair logic starts at a real user item, ignores orphaned tool results, and checks each assistant tool call for its matching result. When a new non-tool item arrives—or history ends—any unanswered call is closed with this explicit record:

not run: the turn was interrupted

The repaired version becomes:

User: Check the deployment dashboard.
Assistant: calls browser_text({ url: ... })
Tool: not run: the turn was interrupted
User: What did it find?

That line is deliberately narrow. It does not claim the action failed in the outside world. A request might have reached an external service before the runtime lost contact. It only says APX has no completed tool result for this turn.

This distinction matters for retries. A safe next step may be to inspect current state, ask the user, or run an idempotent check. It is not automatically “do it again.”

Keep portable context out of the repair

This is runtime work, not a change to project context. APC keeps the portable contract: AGENTS.md, .apc/ metadata, agent definitions, skills, and safe shared guidance in a repository. A compatible tool can read that contract from another checkout.

APX is the daily-use runtime. Its chat history, tool-call records, sessions, and interruption markers are local execution state. They must describe what happened in a particular conversation, but they do not belong in a portable project contract.

The boundary makes recovery easier to reason about. APC still tells an agent what project rules and skills apply after a restart. APX separately tells it whether the last tool call produced evidence. One layer supplies durable intent; the other preserves honest operational facts.

A practical recovery habit

When a tool-backed turn is interrupted, keep three questions separate:

Was a tool requested?
Did APX receive a matching result?
What check is safe before continuing?

Only the second question has a certain answer from the repaired history. The third depends on the operation: inspect a read-only dashboard, check a task status, or ask before repeating a write.

An explicit interruption marker is not glamorous, but it prevents a subtle class of agent mistakes. APC keeps project context portable. APX keeps execution history accountable. The next turn can then continue from evidence instead of from a gap that looks like success.

Name the Project Before the Conversation Drifts

Manuel Bruña — Sun, 18 Oct 2026 12:03:26 +0000

Name the Project Before the Conversation Drifts

A useful agent conversation needs more than a capable model. It needs a clear answer to a smaller question: which project does this turn belong to?

If that answer changes invisibly, an agent can read the wrong rules, suggest the wrong specialist, or look at the wrong local history. The failure is subtle because the reply may still sound reasonable.

APX makes project selection a per-turn decision. It uses the project already active on the surface, otherwise a project named in the message, otherwise the project named earlier in that conversation. That order gives a practical rule: when the project matters, name it before the conversation has a chance to drift.

A project is more than a folder

In APC, a project carries portable context: AGENTS.md, agent definitions, skills, shared MCP hints, and project metadata under .apc/. That is the contract a compatible tool can read from a checkout.

APX is the runtime layer. It uses the selected APC project to decide which agents, MCP servers, root guidance, and durable agent memory belong in the turn. Its conversations, sessions, task logs, and private runtime state remain local under ~/.apx/.

So selecting a project is not a cosmetic label in a chat sidebar. It is the boundary that tells APX which portable contract and which local working state apply.

Let the surface decide when the surface is clear

A project chat or code session already has useful scope. If you open the storefront project and ask for a checkout review, APX can use that project directly. The work surface and the project contract agree.

That is the best case for sustained work: stay in the project surface while the task belongs there. The conversation gets its agents and guidance from the same project whose files the work will touch.

But not every request begins there. A person might be in a general chat, replying from a message channel, or returning to an old conversation after changing tasks. In those cases, make the target explicit in ordinary language:

For storefront, review the release checklist.

In the data-pipeline project, summarize the failed import.

The project name is short context with a large effect. It avoids relying on a previous topic that may no longer be relevant.

Do not turn conversational carryover into ownership

Using a project named earlier in the same conversation is helpful for follow-up questions. After discussing storefront, a later “what should we test first?” can keep the same scope without repeating the name every turn.

That convenience should not become hidden ownership. Switch deliberately when the work changes:

Now for data-pipeline: list likely causes of yesterday's import failure.

A new project name is better than assuming that the last active project remains correct. It gives the next turn an observable boundary and gives a reviewer a simple explanation for why certain context was present.

Keep chat scope and command scope aligned

A terminal command has the same problem in a different form. When the current directory is not a reliable signal, pin the project:

apx messages tail --project storefront
apx agent list --project data-pipeline

The message-level name and the command-level --project flag serve one idea: state the intended owner at the moment it matters. Neither copies project rules into runtime history, and neither makes private session data portable. They only select the correct boundary.

A small habit that prevents quiet mistakes

Use the project surface for ongoing project work. Name the project in a neutral conversation when scope is important. Repeat the name when the subject changes. Pin commands when the shell location is incidental.

APC keeps the project contract portable. APX makes that contract useful turn by turn. Naming the project is the small bridge between them—and it is easier to trust than a guess based on whatever the conversation happened to discuss last.

The APX Default Project Is a Scratchpad, Not a Workspace

Manuel Bruña — Sat, 17 Oct 2026 12:06:55 +0000

The APX Default Project Is a Scratchpad, Not a Workspace

Agent tools need somewhere to put work when no project is active. APX has that place: its built-in default project under ~/.apx/projects/default/. It lets the super-agent handle general, unscoped work without first asking someone to create a repository.

That convenience becomes dangerous when default quietly turns into the home of real project work. A default workspace is shared across contexts. It has no repository contract to carry intent, no committed agent definitions, and no portable boundary another machine can pick up. It is a fallback, not ownership.

The useful rule is simple: use default for scratch work; create or register an APC project when work belongs to a project.

What scratch work looks like

A few examples fit the default project well:

Ask APX to explain a command, compare two ideas, or make a temporary checklist.
Start a personal conversation not attached to a codebase, client, or team.
Try a model or a tool before deciding whether it belongs in a project.

Those actions need local runtime state, but they do not yet need a durable project agreement. A transcript, a short-lived task, or an experiment can remain local to APX.

The boundary changes when the work needs shared rules, repeatable agent roles, reusable skills, or review in version control. Then the work has a project shape even if it is not a Git repository.

Give durable work an explicit home

An APX project is a directory containing AGENTS.md and .apc/project.json. The APC files hold portable project context: agent definitions, skills, MCP hints, and project metadata. APX registers that directory and stores its runtime-only state separately under ~/.apx/projects/<apx_id>/.

For a new project, start in its directory:

apx init
apx project add .

For an existing APC project, registration is enough:

apx project add /path/to/project

After that, target it deliberately when your current directory is not reliable:

apx agent list --project my-project
apx exec reviewer --project my-project "Review the release notes"

That choice answers two separate questions. APC answers what the project means and which guidance can travel with it. APX answers where local conversations, sessions, task logs, credentials, and machine-specific settings belong. Neither side needs to pretend it owns the other.

Why implicit ownership causes trouble

Suppose a team uses the default project for release planning because it is already open. The plan may look available in the panel, but a teammate who clones the repository cannot discover its rules or agent roles from the repository. Later, unrelated personal chats and project history also share one runtime bucket. Context becomes hard to review, move, or clean up safely.

Putting the same work in an APC project does not make every conversation portable. It should not. Raw sessions and private runtime memory still stay local. What moves is the contract: the project instructions, named agents, reusable skills, and safe shared metadata. A second machine can register the project and build its own local runtime state around that contract.

Make the fallback visible

The default project is valuable precisely because it is temporary and unowned. Do not delete or over-engineer it. Just avoid giving it work that needs a durable boundary.

When a task is only a question, scratch is fine. When it needs teammates, review, repeatability, or a future checkout, give it a project directory and APC context.

A fallback keeps APX helpful. An explicit project keeps the work understandable.

A Running Task Column Is Not Proof of Execution

Manuel Bruña — Fri, 16 Oct 2026 12:05:14 +0000

A Running Task Column Is Not Proof of Execution

A task board needs a running column. It is useful for workflow: someone has picked up the card, or the team wants to see it in progress. But a board column is a claim about process, not evidence that a process is alive.

That distinction matters in agent systems. A task can remain in running after a runtime session ends. An agent can be active on a task thread while the card still says pending. A human can move a card manually for planning reasons. If a dashboard turns any of those cases into “work is definitely happening,” it reports confidence it has not earned.

APX separates these two questions. The task workflow records the column chosen for an open task. Its execution view asks a different question: what evidence exists now?

One label, several realities

Suppose a task called “Review the authentication flow” sits in running. There are at least four possible realities:

An agent turn is currently working on the task thread.
A linked coding-runtime session is still open.
A linked session already finished or failed.
Nothing linked is active; the column was moved earlier and never changed.

Only the first two support “working now.” The third supports “execution ended.” The fourth supports “not verified,” not “running successfully.”

This is why APX does not treat the status field as a liveness signal. Its task execution view combines specific evidence: a currently running agent turn, runtime sessions explicitly linked from task comments, and the latest activity such as a comment or session start/end. When no evidence is alive but the workflow column says running, the verdict is not_verified.

That phrase is deliberately less comforting than a green dot. It tells the owner what the system knows without pretending to know more.

Inspect the task before reporting progress

For an agent, the practical rule is simple: use get_task when a title or board column is not enough. The response includes an execution object with separate workflow and runtime information. A useful progress report can then distinguish these cases:

Workflow: running
Execution: working
Evidence: linked runtime session is open

Workflow: running
Execution: not verified
Evidence: no live task turn or linked open session

Workflow: in_review
Execution: ended
Evidence: latest linked session finished

These are not cosmetic wording changes. They lead to different next actions. “Working” may mean wait or inspect the live session. “Not verified” means check the task thread, ask the assignee, or move the card only after learning what happened. “Ended” means read the result and review it; it does not mean automatically close the task.

In particular, a successful process exit is not a business approval. A runtime can exit with code zero after producing a draft, a partial investigation, or a result that needs human review. APX keeps execution evidence separate from task closure so an agent cannot silently turn “command finished” into “work accepted.”

Why the link must be explicit

APX finds a task's relevant runtime sessions through task comments that carry the session identity and path. That is narrower than scanning every agent history. It prevents an unrelated session from making a task look active, and it keeps the evidence attached to the card where a reviewer expects to find it.

The same boundary explains APC's role. APC is the portable project context layer: AGENTS.md, agent definitions, skills, and durable rules travel with the project. APX is the daily-use runtime and tooling layer: it keeps local sessions, task activity, and execution evidence outside that portable contract.

A portable task instruction can say what success requires. Only the runtime can say whether a particular session is still alive.

A better board question

When you see a task in running, do not ask only, “Which column is it in?” Ask, “What evidence says it is running now?”

That small separation produces calmer automation. It avoids duplicate launches for live work, exposes stale cards before they become false reassurance, and leaves approval where it belongs: with a review of the actual result.

A board tracks workflow. Evidence tracks execution. Reliable agent operations need both.

A Project Rule Projection Needs One Owner

Manuel Bruña — Thu, 15 Oct 2026 12:05:21 +0000

A Project Rule Projection Needs One Owner

A project can need rules in more than one tool format. That does not mean it needs more than one rule source.

This is the useful boundary behind APC rule projections: keep the project-owned instruction in .apc/rules/; let a compatible IDE or runtime create the format it needs to execute that instruction. The projection is useful. Editing both copies as if they were peers is where drift starts.

Source versus projection

Imagine a repository with a TypeScript API. The project wants every compatible agent working on routes to validate input at the boundary. APC can express that once:

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

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

That file says both what to do and where it applies. It belongs to the repository, can be reviewed with code, and travels when the repository moves.

A runtime may need that same rule under its own directory. For example, a compatible consumer can project .apc/rules/backend.mdc into a tool-specific rules folder. That derived file lets the runtime use its native loading mechanism. It should not become a second place where the team edits the policy.

Why two editable copies fail

At first, duplicate rule files look harmless. One is for an IDE. One is for another agent runtime. Then the API moves, an exception is added, or a review clarifies the wording. Someone updates only one copy.

Now the project has two answers to the same question. Both may be valid Markdown. Only one is current. Agents receive different instructions based on the tool that opened the repository, and reviewers have no reliable place to verify intent.

The problem is not that a runtime has its own configuration. Runtime-specific files can be necessary. The problem is unclear ownership. A projection is an adapter, not a competing contract.

Keep the split small

Use the broadest APC surface that matches the instruction:

Put repository-wide rules in AGENTS.md.
Put path-scoped or task-scoped rules in .apc/rules/.
Put reusable procedures in .apc/skills/.
Keep runtime-only setup, sessions, messages, and private state outside the portable contract.

This split makes an important maintenance question simple: where should a change be made? For shared project meaning, change APC first. Regenerate or update the runtime projection from that source. For a setting that only controls one local runtime, keep it local instead of pretending it is portable.

Where APX fits

APC is the portable context layer: repository-owned rules, agent definitions, skills, and other durable project meaning. It deliberately does not define every runtime's storage or execution behavior.

APX is the daily-use runtime and tooling layer. It bridges APC into compatible workflows, while keeping operational state such as sessions, messages, and caches outside .apc/. APX therefore benefits from a clear source of truth: it can consume project context without turning its local state into the project contract.

A review check

When a project adds a tool-specific rules file, ask one question: where is the canonical edit made?

If the answer is .apc/rules/, the team can review, version, and move shared guidance once. If the answer is “whichever copy someone remembers,” the repository has already started to fork its own context.

Portable context is not about banning adapters. It is about making sure adapters do not become authors.

Unregistering an APX Project Should Not Erase Its APC Contract

Manuel Bruña — Wed, 14 Oct 2026 22:40:09 +0000

Unregistering an APX Project Should Not Erase Its APC Contract

A project can stop being active on one machine without stopping being a project. That distinction matters when you clean up an APX installation, move between computers, or register the wrong directory by mistake.

The practical rule is simple: removing an APX project registration should remove the local runtime relationship, not the portable APC contract.

APC is the portable context layer. Its AGENTS.md and .apc/ directory live with the project and can be reviewed, copied, or committed. APX is the daily-use runtime and tooling layer. It registers that project with a local daemon, runs agents against it, and keeps runtime state under ~/.apx/. Those layers have different owners and different lifetimes.

The cleanup command is deliberately narrow

APX registers a project explicitly:

apx project add /path/to/repo

During registration, APX reads the project's AGENTS.md and .apc/project.json. The filesystem remains the source of truth for portable context; APX records enough local information to work with that project on this machine.

Later, this command removes that local registration:

apx project remove /path/to/repo

The command does not delete the project files. In particular, it does not delete AGENTS.md, .apc/project.json, agent definitions, skills, or shared MCP hints. The project folder remains a valid APC project for Codex, Claude Code, APX on another machine, or another compatible tool.

That restraint is useful. A developer may unregister a temporary checkout. A team may remove an old path after a disk migration. A person may decide that a research directory no longer needs an active APX runtime. None of those decisions means the project's shared instructions should vanish.

Runtime cleanup is a separate decision

APX also keeps machine-local state under ~/.apx/projects/<apx_id>/: conversations, messages, task logs, cached data, routine state, and agent runtime memory. That state is intentionally not part of APC and should never be confused with the portable project definition.

Unregistering a project therefore answers one question only: should this local APX daemon keep this project in its active registry? It does not answer whether the repository should keep its instructions, or whether local runtime history should be retained for later inspection.

This split avoids two opposite mistakes:

Treating a local cleanup command as permission to destroy shared project context.
Treating runtime state as if it were safe to ship with the project just because it exists near the project in the APX UI.

Re-register from the contract

If the project becomes relevant again, register the same directory again:

cd /path/to/repo
apx project add .

APX can read the portable files again because they never depended on the old registration. The stable apx_id in .apc/project.json identifies the project definition; it is not a reason to bury runtime history inside the repository.

This gives project maintenance a clean boundary. Keep APC files when the project still needs durable, shareable guidance. Remove an APX registration when this machine no longer needs to operate that project. Decide separately what to do with local runtime state.

Portable context should outlive a local registry entry. APC preserves the contract; APX makes that contract useful while the project is active.

A Path-Scoped Rule Is a Matching Contract, Not Just a Note

Manuel Bruña — Sun, 11 Oct 2026 12:04:53 +0000

A Path-Scoped Rule Is a Matching Contract, Not Just a Note

A rule that applies everywhere is easy to write and expensive to live with.

Projects accumulate instructions: validate API input, preserve migration compatibility, write release notes, keep documentation examples current. Those instructions are all useful. They are not all relevant while an agent is editing the same file.

APC gives this distinction a portable shape. Repository-wide expectations belong in AGENTS.md. A rule that only matters for a slice of the tree belongs in .apc/rules/ with frontmatter that says where it applies. The thesis is simple: a path-scoped rule is a matching contract. Its glob is part of its meaning.

The small rule

Imagine a repository with an API and a documentation site. The API needs request-boundary validation and careful compatibility handling. Documentation pages need accurate examples, but do not need a warning about route validation on every edit.

Put the API-specific instruction in a rule file such as .apc/rules/backend.mdc:

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

- Validate request input at the route boundary.
- Keep public API compatibility during migrations.

The file holds two different facts. The Markdown body explains what to do. The frontmatter explains when the instruction matters. Removing either half changes the contract.

Why `alwaysApply: false` matters

alwaysApply: false expresses a useful restraint: do not make this a project-wide command. A task that changes src/api/orders.ts should receive backend rules. A task that updates docs/getting-started.mdx should not have to treat those rules as the primary context.

This is not an attempt to hide important constraints. It is how you make constraints easier to follow. A relevant, narrow rule is more likely to be noticed and less likely to be diluted among unrelated instructions.

The alternative is one enormous root file. That starts well: every rule is visible in one place. Later, a docs change arrives with database migration advice, UI conventions, deployment commands, and incident procedures attached. The agent must guess which parts matter. Humans do the same thing during review.

The matching surface is part of maintenance

A glob can become wrong without the rule text becoming wrong. Suppose an API moves from src/api/ to services/http/. The validation rule may still describe the right practice, but src/api/**/*.ts no longer names the files that need it. The rule has silently lost its reach.

Treat that rename as a contract change:

---
description: HTTP service rules
globs:
  - "services/http/**/*.ts"
alwaysApply: false
---

- Validate request input at the route boundary.
- Keep public API compatibility during migrations.

This gives code review a concrete question: did the matching surface move with the code?

Where APC and APX meet

APC is the portable context layer. It keeps the root contract, reusable skills, agent definitions, and scoped rules in the project rather than a tool-branded folder. The .mdc rule can travel with a checkout because its target is described relative to that project.

APX is the daily-use runtime and tooling layer. It can consume that project context while its sessions, messages, routines, and private runtime state remain local. The boundary matters here: a scoped rule is durable shared project knowledge; a runtime conversation about one particular edit is not.

A practical check before merging

When you add or edit a scoped APC rule, ask three questions:

Does the body state one behavior that is genuinely local to these files?
Does globs match every file that needs the behavior, without catching unrelated work?
Would a folder rename require updating this file?

If the answer to the last question is yes, the rule is doing useful work. Keep its matching surface visible in the review. Portable context stays trustworthy when its instructions have a clear home and a clear boundary.

Pin the APX Project Before You Run the Command

Manuel Bruña — Sat, 10 Oct 2026 12:04:27 +0000

Pin the APX Project Before You Run the Command

The current directory is a convenient default. It is not a reliable identity.

That is why APX accepts --project <name|id|path> on most project-aware commands. The flag is a small guardrail: it makes the target explicit before APX reads agents, chooses runtime state, or writes a task, routine, message query, or configuration change.

APC is the portable context layer: AGENTS.md and .apc/ describe a project in a repository. APX is the local runtime and tooling layer: it uses that context while keeping sessions, messages, and operational state on the machine. A command needs to know which APC project it serves.

The helpful default

When no project is named, APX walks upward from the current directory looking for an APC root. If it finds a registered project, it uses it. If it finds an APC project that is not registered yet, it can register it. If it finds neither, some commands fall back to APX's built-in default workspace.

That behavior makes the common case pleasant:

cd ~/code/storefront
apx agent list
apx run reviewer --runtime codex "Review the checkout changes"

Working from the project root is a good default because the shell location, source files, and APC contract all point to the same place.

Where the default becomes risky

Now imagine a terminal that is not in the intended repository: a monorepo parent folder, a notes directory, a temporary checkout, or a shell reused after another task. The command can still be syntactically valid while targeting the wrong project or the default scratch workspace.

That is especially costly for commands that change state. A routine created in the wrong project runs with the wrong agents and context. A project config update changes a different local runtime profile. A message search can make you inspect the wrong evidence trail.

The failure is not that APX cannot infer a project. The failure is asking inference to carry authority when you already know the target.

Use an explicit pin for cross-project work

Use --project whenever your shell location is incidental rather than meaningful:

# From any directory, inspect one project's agent definitions
apx agent list --project storefront

# Keep routine ownership unambiguous
apx routine add daily-review --project storefront --schedule "0 9 * * 1-5"

# Query runtime evidence for that project only
apx messages tail --project storefront

# Run a coding agent against the intended APC contract
apx run reviewer --runtime codex --project storefront "Review the checkout changes"

APX accepts a numeric id, an exact project name, an absolute path, or a relative path resolved from the current directory. If a short name matches more than one registered project, it refuses the ambiguity instead of choosing silently. apx project list is the quick way to inspect available names and ids.

The important distinction

--project does not turn runtime state into portable context. It does the opposite: it preserves the ownership boundary.

APC remains the committed definition of storefront: agents, skills, shared MCP hints, and project rules. APX uses the selected project's stable apx_id to locate its local sessions, messages, tasks, routines, and machine-specific configuration.

So one explicit flag connects two layers without mixing them:

APC answers what project context should travel.
APX answers which local runtime state belongs to that project today.

A practical rule

Trust the current directory when you deliberately opened a shell inside one project. Pin --project when working from a shared terminal, automation, another repository, or a directory where project inference would be a guess.

This is not extra ceremony. It is a short, readable record of intent beside the command that matters. In agent tooling, the safest target is often the one you name.

DEV Community: Agent Project Context

Load Nested AGENTS.md Rules at the Folder Boundary

Load Nested AGENTS.md Rules at the Folder Boundary

Keep root guidance truly shared

Put local rules next to local work

Attach instructions when the tool crosses the boundary

Portable contract, local execution

A Runnable Project Needs Both Instructions and Identity

A Runnable Project Needs Both Instructions and Identity

Why one file is not enough

A small, reliable setup

The useful rule

Create a Specialist Agent Only After Its Work Boundary Is Stable

Create a Specialist Agent Only After Its Work Boundary Is Stable

A role is not a label

Start with one repeated decision

Put durable detail in the right place

A practical test before adding an agent

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

An APX Approval Scope Is a Real Boundary, Not a Convenience Button

The dangerous shortcut

Choose scope deliberately

Separate tool trust from project context

A small rule that scales

An Interrupted Tool Call Needs an Explicit Ending

An Interrupted Tool Call Needs an Explicit Ending

Why a dangling call is a problem

Repair the structure, not the story

Keep portable context out of the repair

A practical recovery habit

Name the Project Before the Conversation Drifts

Name the Project Before the Conversation Drifts

A project is more than a folder

Let the surface decide when the surface is clear

Do not turn conversational carryover into ownership

Keep chat scope and command scope aligned

A small habit that prevents quiet mistakes

The APX Default Project Is a Scratchpad, Not a Workspace

The APX Default Project Is a Scratchpad, Not a Workspace

What scratch work looks like

Give durable work an explicit home

Why implicit ownership causes trouble

Make the fallback visible

A Running Task Column Is Not Proof of Execution

A Running Task Column Is Not Proof of Execution

One label, several realities

Inspect the task before reporting progress

Why the link must be explicit

A better board question

A Project Rule Projection Needs One Owner

A Project Rule Projection Needs One Owner

Source versus projection

Why two editable copies fail

Keep the split small

Where APX fits

A review check

Unregistering an APX Project Should Not Erase Its APC Contract

Unregistering an APX Project Should Not Erase Its APC Contract

The cleanup command is deliberately narrow

Runtime cleanup is a separate decision

Re-register from the contract

A Path-Scoped Rule Is a Matching Contract, Not Just a Note

A Path-Scoped Rule Is a Matching Contract, Not Just a Note

The small rule

Why alwaysApply: false matters

The matching surface is part of maintenance

Where APC and APX meet

A practical check before merging

Pin the APX Project Before You Run the Command

Pin the APX Project Before You Run the Command

The helpful default

Where the default becomes risky

Use an explicit pin for cross-project work

The important distinction

A practical rule

Why `alwaysApply: false` matters