DEV Community: Manuel Bruña

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.

Why I Made APX Stop Reading When You Take the Browser

Manuel Bruña — Mon, 19 Oct 2026 13:06:21 +0000

The browser is where agent work starts to feel useful—and where a vague idea of control becomes dangerous. An agent can open a page, read it, click through a flow, and fill ordinary fields. Then a login page, a 2FA challenge, or a payment form appears. At that moment I do not want a polite convention saying “the human is in charge.” I want the runtime to enforce it.

That is why I made APX stop reading a tab when I take the browser wheel. A handoff is not a message to the agent. It is a control-state change that blocks agent calls.

This sounds like a small implementation detail. It changed how I think about agent browser work.

Watching is not the same as controlling

APX V2 can give an agent an embedded browser tab. On desktop, I can see that tab while the agent works. The agent operates through a narrow set of browser tools: it opens and navigates tabs, takes an accessibility snapshot, reads visible text, clicks element references from that snapshot, and types into a referenced field.

That visible surface matters, but it is not enough. Seeing an agent move a cursor does not answer the important question: what happens when I intervene?

A weak answer would be “the agent should wait.” That leaves too much to timing and interpretation. A model might already be reading the page while I am entering a one-time code. A queued click might run after I decide to take over. A screenshot taken during a login flow can reveal information I intended to keep inside my own browser session.

So APX tracks control on each tab. A tab can be idle, controlled by an agent, in a temporary handoff, or controlled by the user. When I choose Take Control, the desktop host changes that tab to user. Every subsequent agent attempt to read or operate it fails with paused_by_user. This applies before a page read, not only before a click.

That last part is the point. A browser is both an action surface and an observation surface. If the human is typing a password, a 2FA code, card data, or private account details, blocking clicks alone is incomplete. The agent should not be able to inspect the page state either.

Login is a handoff, not a chat request

I also did not want an agent to ask for credentials in conversation. The browser tool exposes a browser_handoff action for login, password, 2FA, or CAPTCHA. It records a short reason, marks the browser card as handoff, and waits for the owner to finish for up to five minutes.

The agent gets only one of two answers: the owner finished, with the current URL; or the owner did not finish in time, so the agent stops. It does not receive the password, the code, or a stream of the human’s interaction.

This is intentionally less clever than trying to automate every authentication path. Auth flows are different across sites, often intentionally hostile to automation, and frequently involve secrets or identity decisions that do not belong in an agent transcript. A visible handoff gives the person one clear job and gives the agent one clear boundary.

There is a second, separate path for a site where I am already signed in through my own browser. APX can ask me to approve copying cookies for a specific domain into an APX browser profile. That operation is human-only. The runtime can inspect source names and domain counts, but cookie values stay on the desktop. The agent cannot turn this into a general “read my browser” permission.

Keeping these paths separate matters. Logging in myself is a direct interaction. Importing an existing session is a scoped transfer with a specific domain. Neither should silently become permission for unrelated tabs or tools.

Separate profiles prevent accidental shared steering

Control alone is not the full boundary. APX gives agents browser profiles and checks ownership before an operation. An agent may touch tabs from its own profile, but it cannot drive a tab assigned to another agent. If another agent is currently controlling a tab, APX rejects the request rather than letting two runs steer one page.

That is less dramatic than a large security feature, but it removes a surprisingly common source of ambiguity: a tab is not merely a URL. It has a profile, cookies, current state, and an operator. Treating it as shared global state would make a browser session hard to explain after anything unexpected happens.

The same design shapes the normal tool flow. Clicks reference an element from the latest accessibility snapshot. Typing is an external action and requires confirmation after untrusted page content has been read. Browser text is marked untrusted. The agent is pushed toward checking the new page state before claiming that a form was submitted or a message was sent.

None of that makes browser automation safe by declaration. It gives the system places to stop, ask, and show evidence.

The design rule I am keeping

My original instinct was to make the browser feel seamless: agent opens page, I help at login, agent continues. The better rule became more precise: seamless is fine only when ownership stays obvious.

A good handoff has four properties:

The human can take a tab without negotiating with the agent.
Agent reads stop as well as agent actions.
Sensitive input stays out of chat and tool output.
Returning control is explicit, so the agent does not guess when work may resume.

This adds state to the runtime. It also removes the kind of invisible state that causes trouble: an agent that assumes it still owns a page while a person believes they have taken over.

I am building APX around the idea that agents should be capable without becoming opaque. In a browser, the practical version of that idea is simple. If I take the wheel, the agent waits—and it cannot watch me type.

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.

The Model You Requested Is Not Always the Model That Ran

Manuel Bruña — Wed, 14 Oct 2026 22:39:51 +0000

I found a small but expensive ambiguity while building APX: the model selected in APX was easy to mistake for the model that an external coding runtime would actually run.

That sounds obvious once stated. APX can talk to its own configured engine, then delegate coding work to Codex or Claude Code. Those CLIs have their own configuration, their own supported model flags, and their own defaults. But a UI label is persuasive. If it says one model, people reasonably expect the next coding run to use it.

That expectation was not a contract. In one case, a session requested a model that did not belong to the external runtime, the CLI returned a 400, and the useful question—what exactly did APX ask it to run?—had no clear answer.

So I changed the boundary rather than trying to hide it. My rule is now: a requested model, a model passed to a runtime, and a model that actually ran are different facts. Record each one honestly.

`inherit` needed a precise meaning

APX supports agent model selection. External coding runtimes are different programs. Before this change, model: inherit could look like a promise that an external CLI would inherit APX's selected model. It is not.

The documented default is narrower: an unpinned runtime uses its own configured default. Codex reads its own configuration; Claude Code reads its own configuration. APX supplies the work and can capture the result, but it should not quietly claim control it does not have.

I kept that default. Changing it silently would have been worse than the original ambiguity: existing setups could start spending from, or behaving like, a different model without an intentional choice.

Instead, APX now makes the choice explicit in three ways:

A single runtime call can name that runtime's native model and, where supported, its reasoning effort.
Runtime configuration can pin a model and effort for future calls.
A runtime can opt in to following APX's selected model, but only when that provider is native to that runtime.

The ordering is deliberate: a direct call beats a runtime configuration, a runtime configuration beats the optional APX inheritance setting, and otherwise the CLI default wins. That makes the value's origin inspectable instead of accidental.

Never pass one model vocabulary into another program

The implementation detail that mattered most was refusing to treat model identifiers as interchangeable strings. An APX engine selection can include a provider, a model, and an effort. An external CLI may accept only a bare model id, may accept a separate effort flag, or may accept neither.

APX now splits that information before it reaches a runtime adapter. The Codex adapter can receive a model flag and a reasoning-effort setting; the Claude Code adapter can receive a model but not that effort setting. Other runtimes declare that they do not accept a model from APX.

That declaration prevents two bad outcomes. First, APX does not hand a provider-prefixed identifier to a CLI that cannot understand it. Second, it does not silently drop a requested flag and run something else. If a caller asks Codex to run an Anthropic model, or asks a runtime that has no APX model option to take one, the call fails before a process starts.

I prefer that failure. It is specific, cheap, and actionable. A silent fallback might finish successfully while violating the reason the person selected a model in the first place.

“Effective” cannot mean guessed

There is another boundary that was tempting to blur. A runtime can accept a model pin, but APX does not receive a universal, trustworthy report from every CLI saying which model ultimately executed the request.

So the result now returns a small model record: requested, passed, effort, source, and effective. When APX pinned a model, effective reports that pin. When it did not, the result says runtime default (not reported by the CLI).

That last string is intentionally plain. It does not pretend APX observed something it did not observe. It tells the person where the remaining uncertainty lives: inside the runtime's own configuration and reporting.

APX also writes the requested model and source into the runtime session record. A session should not become a mystery later, especially when it is resumed. The same resolution path applies to ordinary runtime calls and to agent-to-agent runtime replies, so a configured pin does not disappear just because the conversation arrived through a different route.

The tests were about the seam, not just the parser

I did not want this to be a nice resolver with no operational proof. The tests cover the precedence rules, provider mismatch errors, unsupported effort errors, and the unpinned default. They also run a fake Codex executable and inspect the arguments it receives for both a new run and a resumed one.

That distinction caught the real risk: a value can be resolved correctly and still be lost at the adapter boundary. The sandbox behavior remains separate too. A resumed Codex session inherits its sandbox from the first turn; adding a model pin must not accidentally rewrite that unrelated rule.

What I am keeping from this

Agent tooling creates lots of plausible-looking state: selected engines, model labels, project defaults, agent overrides, and external commands. The hard part is not collecting settings. It is preserving the line between a preference and an action that another program accepted.

My practical rule now is simple: if one system asks another system to use a model, keep four answers available. What was requested? What was actually passed? Why was that value chosen? What can the caller truly know about the result?

That is less magical than a single model label. It is also much easier to debug, audit, and trust.

DEV Community: Manuel Bruña

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

Why I Made APX Stop Reading When You Take the Browser

Watching is not the same as controlling

Login is a handoff, not a chat request

Separate profiles prevent accidental shared steering

The design rule I am keeping

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

The Model You Requested Is Not Always the Model That Ran

inherit needed a precise meaning

Never pass one model vocabulary into another program

“Effective” cannot mean guessed

The tests were about the seam, not just the parser

What I am keeping from this

`inherit` needed a precise meaning