APX Should Assemble Context, Not Dump APC Into Every Prompt

A portable context system becomes less useful the moment a runtime treats it like a blob.

That is the line APC and APX need to keep clear.

APC is the portable context layer. It gives a repository durable project meaning through AGENTS.md, .apc/, agent files, skills, and other committed artifacts. APX is the daily-use runtime and tooling layer. Its job is not to shovel all of that into every turn. Its job is to assemble the smallest useful prompt for the current surface and request.

That distinction matters because prompt assembly is a runtime problem, not a file-format problem.

If an agent runtime blindly dumps full project context into every prompt, three things usually go wrong:

• prompt budgets get wasted on context that does not matter for this turn
• the model gets nudged toward irrelevant instructions
• the portable layer starts getting blamed for runtime bloat it did not cause

APX avoids that by treating APC as a source of durable context, then selecting pieces deliberately.

What APX actually assembles

In src/core/agent/prompt-builder.js, buildSuperAgentSystem() builds the final system prompt as layered blocks instead of one giant static file. The assembled prompt can include role, user context, memory, active threads, channel rules, project guidance, skills hints, lazy tools, voice mode, and final format directives.

That design matters because different turns need different slices.

A web-admin session can tolerate longer markdown guidance. A one-shot CLI call should stay tighter. Voice mode is not even treated as its own channel. APX keeps channels as surfaces and layers voice on top as a mode. That avoids fake channel duplication and keeps formatting rules narrower.

APC stays durable; APX stays selective

The useful APC lesson here is simple: durable context should exist in the repo, but runtime injection should stay selective.

APX even caps raw project guidance when it reads AGENTS.md into a prompt. The project guidance block is size-limited instead of assuming every repository rule file should enter every turn in full. That is exactly the right boundary.

APC preserves the contract. APX decides how much of that contract belongs in this specific interaction.

That same pattern shows up in skills.

buildSkillsHintBlock() does not preload every skill body. It exposes a catalog hint with slugs and explicitly tells the runtime to load details on demand through list_skills and load_skill({slug}). In other words, APC can hold durable skill files, but APX does not pay the full prompt cost unless the current request needs exact syntax.

That is a better use of both portability and tokens.

Why on-demand skill loading matters

This is also why the optional skill inspector in APX is interesting.

In src/core/agent/skills/inspector.js, inspectPromptForSkills() checks whether the feature is enabled, ignores prompts below a floor, refreshes stale indexes in the background, and only then tries to inject matching skill context. If the embedder does not match the saved index, it refuses to mix vector spaces and asks the operator to re-index instead.

That is not accidental complexity. It is runtime discipline.

The portable layer says, "These skills exist."

The runtime layer says, "For this turn, only these parts are worth paying for."

Without that separation, an APC-compatible project with many skills would quietly punish every request, even simple ones.

Practical takeaway

If you are building on APC, resist the urge to equate portability with maximum injection.

A good APC project should be rich enough that multiple tools can understand it. A good APX runtime should still be strict about what enters the prompt each turn.

That usually means:

• keep durable project facts in APC
• keep prompt assembly decisions in APX
• load skill bodies only when exact detail matters
• keep channel formatting scoped to the current surface
• treat prompt budget as part of runtime architecture, not as an afterthought

That is the deeper reason the pair works well together.

APC gives the project one portable home for context.

APX makes that context usable every day by refusing to turn portability into prompt spam.