Context Engineering & Tool Efficiency Standards

Status: Active standard (advisory + eval-backed; specific items are CI-enforced — see “Enforcement”). Owner: Enterprise Architect persona / dpf-platform:dpf-architecture-review. Rationale of record: docs/superpowers/specs/2026-06-20-context-engineering-tool-efficiency-design.md (research, current-state evaluation, and the full principle derivation). Live client facts: docs/architecture/agent-client-capability-parity.md (refreshed monthly — clients change weekly).

This is the canonical reference for how DPF spends context and tokens across its three model-facing surfaces — the MCP tool registry, Build Studio (CLI agents + native local LLM), and AI coworkers. Consult it when tuning prompts, adding or changing tools, sizing context, or reviewing a spec that touches any of these. It is the operational form of Anthropic’s context engineering: find the smallest set of high-signal tokens that maximize the likelihood of the desired outcome.

Why this is a first-order constraint here (not a nicety)

DPF is local-first by founder strategy: cloud frontier models are disabled by choice and the platform is tuned for budget / small-GPU deployments. The binding constraint is therefore the served local window of ~24,576 tokens (RECOMMENDED_BUILD_CONTEXT_TOKENS), not a 200K cloud window. Three consequences shape every rule below:

• The local-window contract. One DMR llama-server, one generation model, ~24,576 tokens. Anything that silently consumes that budget (an unbounded tool result, 50K of tool definitions, a forgotten plan) is an existential failure mode, not an inefficiency.
• The tool-count cliff. Tool-selection accuracy collapses past ~15 tools on small local models — encoded as LOCAL_FALLBACK_MAX_TOOLS = 15 (apps/web/lib/routing/fallback.ts). Above it, local fallback is skipped entirely.
• The host-capacity boundary. While governed local CI owns the installation host, the common provider adapter defers new local completion/embedding dispatch and fallback.ts may continue to an eligible cloud route. Exact documentation-only trees run their planner-bound evidence before admission and never reserve that host lane; missing or ambiguous classification falls back to exhaustive CI. Runtime-code callers derive an immutable gate identity before admission. One lease owner executes that identity; concurrent callers subscribe without receiving renew, release, or evidence-write authority, and a fresh terminal receipt is reused without reserving the host again. This policy is grounded in the observed overlap between provider/model residency and the Windows free-memory fence; Docker model residency, GPU VRAM, WSL/shared memory, and Windows physical memory remain separate measurements.
• The cheapest token is the one we never process. Every reduction (just-in-time loading, in-environment filtering, concise results) compounds with caching and tiering.

The three laws

1. Context is a finite resource with diminishing returns. Recall degrades as tokens grow (“context rot”). Default to removing, not adding.
2. Smallest high-signal set. Optimize signal-to-token ratio in every block: system prompt, tool definitions, examples, history, results.
3. Tool-selection accuracy collapses past a threshold. Few, consolidated, unambiguous tools beat many; keep exposed sets under the local cliff.

The standards (P1–P13)

Each is a rule + how DPF applies it. Items marked [ENFORCED] have an automatic guard; [REVIEW] are checked at architecture review.

• P1 — Spend context like a budget. Treat 24,576 as the binding window. [REVIEW]
• P2 — Smallest high-signal set. The L0/L1/L2 arbitrator (context-arbitrator.ts, EP-CTX-001) already does this for injected context; extend the discipline to tool definitions and results. [REVIEW]
• P3 — Right altitude for instructions. Heuristics and decision criteria over brittle hardcoded branches; labeled sections; prefer the kernel registry (data) over prose where enforcement matters. [REVIEW]
• P4 — Just-in-time over front-loading. Pass handles (paths, IDs, queries); retrieve bodies on demand; structure is signal. DPF: corpus slug-prefix retrieval, skill summaries not bodies, L3/L4 deferred to tools. External-CLI tools/list defaults clients without proven host-side lazy attachment to a lean core tier. Claude Code and Codex use explicit ?tier=full bootstrap URLs so their hosts can index the authorized catalogue and attach only a small task-relevant subset; generic/Grok/unknown callers keep the no-query core default (apps/web/lib/mcp/tool-tier.ts). The explicit URL is required because current Codex HTTP requests omit User-Agent and its top-level registry does not refresh after list_changed. The core tier also carries gated live-delivery tools external agents need after merge. Model-driven server deferral is shipped for notification-aware/re-listing clients through load_tools; Codex correctness comes from the initial host catalogue, not an unimplemented mid-turn registry refresh. Operational / system-of-record data (orders, invoices, customer accounts, quotes, token-usage and tool-execution ledgers, build activity) is fetched LIVE via Prisma and NEVER vectorized — memorizing a live record means reasoning over a stale snapshot. Only durable KNOWLEDGE (WWMD/WWWD corpus, documents, conversation/platform/capability memory) is embedded. [ENFORCED] apps/web/lib/inference/jit-retrieval-discipline.test.ts freezes the set of modules that may call generateEmbedding (the single embedding choke point). [REVIEW] for the handle/deferral aspects.
• P5 — Few, consolidated, unambiguous tools. “If a human can’t say which tool to use, neither can the agent.” Namespace; onboarding-doc descriptions; no provenance (Phase N, (BI-…), source paths) in model-facing descriptions — that belongs in code comments. [ENFORCED] apps/web/lib/tool-description-hygiene.test.ts.
• P6 — Token-efficient tool results. High-signal fields; concise by default; pagination/filter/range; truncate with a notice and a hard cap. [ENFORCED] apps/web/lib/tak/tool-result-budget.ts (native loop + MCP route).
• P7 — Code execution beats round-tripping. Have the model write code to call tools and filter results in the sandbox before they re-enter context (37–98% token cuts). Spike SHIPPED DARK — run_tool_script (apps/web/lib/tak/tool-script.ts), governed read-only programmatic tool calling, gated by the tool_script_exec grant + programmatic_tool_calling flag (both default-inert); live-verification pending per docs/superpowers/specs/2026-06-20-programmatic-tool-calling-native-loop-design.md §6.
• P8 — Cache the stable prefix. Largest stable content first behind the SYSTEM_PROMPT_DYNAMIC_BOUNDARY; volatile content last. Verify the local server exploits prefix-KV caching. [REVIEW]
• P9 — Isolate heavy work in sub-contexts — but multi-agent ≈ 15× tokens. Only when task value justifies it; poor fit for tightly-coupled/shared-context work. [REVIEW]
• P10 — Enforce non-negotiables deterministically. Hooks / the kernel runtime gate, not prompt hope, for security/audit. DPF is ahead of the field here. [ENFORCED] (kernel gate in executeTool).
• P11 — Persist + re-inject across compaction. Plans, memory, key instructions must survive the sliding window. The plan is re-injected each iteration (withPlanReminder) because it lives in the compacted message history; memory facts already survive — they live in the system prompt (arbitrated via assembleSystemPrompt), which compaction never touches and which is rebuilt per turn (verified 2026-06-20). Residual partially addressed (R9a shipped): compaction truncates rather than summarizes, but the dropped span’s tool activity is now preserved as a zero-inference extractive [System notice] digest (apps/web/lib/tak/compaction-digest.ts) — so the model doesn’t repeat completed work or re-hit a known failure. Arbitrary prose in a dropped message is still truncated (a faithful prose summary would need an LLM pass, avoided on the single-GPU local path). [REVIEW]
• P12 — Measure empirically. Track tokens-per-task, task success, tool-selection accuracy; watch the 15-tool cliff. Phase 1 shipped — a per-turn tool-surface + selection-accuracy gauge (apps/web/lib/tak/context-economy-metrics.ts, logged in the agentic loop as toolSurface/surfaceZone/toolAccuracy alongside ctxZone); surfaceZone=overload is the explicit cliff signal. Cross-task rollup staged (R8 Phase 2). [REVIEW]
• P13 — Do the simplest thing that works. Reuse substrate; spike before building. [REVIEW]
• P14 — The contributor instruction plane is a model-facing surface too, and it ratchets. P1–P13 govern what DPF ships to models; the always-on doctrine every external CLI session reads (AGENTS.md + pointers + injected skill frontmatter) is the fourth such surface and obeys the same three laws. Two tiers are measured, both shrink-only: pointer-forced whole files (manifest.alwaysOn) and harness-injected extracts — the name+description of every installed skill, which Claude Code and Codex load into every session while skill bodies stay progressive-disclosure. Measuring only the first lets a “split” relocate prose from AGENTS.md into skill descriptions and report a win that never happened. Shortening criterion: a rule may collapse to a one-line statement + pointer when a hook, CI gate, or tool schema enforces it deterministically — enforcement is surface-agnostic, so the shortening is safe on all four delivery surfaces; an unenforced rule must keep enough prose for the weakest surface (the ~24,576-token local window), not the strongest. [ENFORCED] scripts/check-instruction-plane-size.mjs (Instruction Plane Guard, scripts/lib/ci-policy-guards.mjs). Design: 2026-07-24-agent-instruction-plane-split-and-ratchet-design.md §4c (tier 1) and §12 (tier 2, surface asymmetry, and the shortening criterion). Per-skill ceiling: a description states WHEN to use the skill and nothing else — the body carries the how-to, and the body is progressive-disclosure while the description is not. That budget (maxExtractedItemChars, 300 bytes of serialised name+description) is a HARD failure via extractedItemStrict, deliberately independent of structuralStrict: the structural signal stays advisory until the Phase 1 AGENTS.md split lands, but skill descriptions are already separate files, so their budget was never blocked by that split. The aggregate ratchet alone would let one description balloon while the others shrink to pay for it. Recalibrated from 700 in the Opus 5 model-era review — 700 permitted ~90-word descriptions that taught rather than routed. Design: 2026-08-26-model-era-doctrine-curation-ab-measurement-design.md.

Enforcement (how subsequent changes stay conformant)

The criteria apply to future changes automatically, not by memory:

1. Runtime cap (P6). clampToolResultForModel bounds the native loop’s model-facing tool messages to a window-proportional cap (~10% of the known window, floored at 4,000 chars); the MCP route (/api/mcp/v1) bounds payloads to MCP_ROUTE_TOOL_RESULT_CHAR_CAP and no longer double-dumps data into both text and structuredContent. Truncation always carries a notice so the model knows to paginate/filter.
2. CI guard (P5). tool-description-hygiene.test.ts fails the build if any tool’s model-facing description carries Phase N / (BI-…) provenance or a leaked source path. (Input-schema property descriptions may still carry format examples like e.g. BI-E4A86393.)
3. Shift-left precheck (P5/P6). packages/dpf-skill-pack/hooks/tool-economy-precheck.mjs fires (Claude/Codex/Grok) when mcp-tools.ts, the MCP route, the agentic loop, or the budget module is edited, re-asserting these criteria before CI.
4. Review tie-in. docs/architecture/agent-standards-dpf-conformance.md carries a Context Economy control area so spec/architecture reviews check P1–P13.
5. Attachment budget on every model path. The per-turn tool-attachment budget (apps/web/lib/actions/coworker-tool-budget.ts — window-fit + local selection-cliff cap, load_tools deferral) applies to interactive chat AND to every autonomous run: scheduled tasks, dispatcher child threads, and remote MCP task submission all budget through resolveAutonomousWorkTools (BI-CAP-F2D39F8F). A coworker whose grants expand past the cap keeps full authority; the long tail loads on demand.
6. Admission follows authoritative evidence scope and identity. scripts/gate-worktree.mjs lets an exact, clean, up-to-date documentation tree complete doc-index, link, and repository-guard evidence before the scarce local-integration-ci lease. For runtime trees, the planner’s integration tree, evidence-plan digest, and toolchain fingerprint form the server-derived claim identity. The executor alone owns the lease; subscribers observe the canonical run, and only fresh identity-matched terminal evidence is reusable. The CI evidence planner is authoritative; any stale base, non-documentation path, workspace-required document, planner uncertainty, or evidence mismatch routes to exhaustive verification or fails closed.

How to apply (quick checklist when changing a model-facing surface)

• Adding a tool? Write the description like onboarding docs; no provenance; namespace it; ask “could a human pick this over its siblings?” If not, consolidate.
• Returning data from a tool? Default concise; paginate/filter; never return unbounded rows — the cap will truncate you and the model will have to re-fetch.
• Adding context to a prompt? Can it be a handle retrieved just-in-time instead? Does it survive compaction if it must persist?
• Exposing tools to a small local model? Keep the set under ~15; lean on phase/grant scoping.
• Bigger bet (code-exec, deferred CLI tools, registry convergence)? It’s in the spec backlog (R3/R4/R7) — design against this standard.

Related

• Full rationale & research: docs/superpowers/specs/2026-06-20-context-engineering-tool-efficiency-design.md
• Context budget arbitration: docs/superpowers/specs/2026-04-03-context-budget-arbitration-design.md (EP-CTX-001)
• Coworker memory shape: docs/superpowers/specs/2026-05-14-coworker-memory-shape-contracts-design.md
• AI cost governance: docs/superpowers/specs/2026-05-19-ai-cost-governance.md
• Local LLM build engine: docs/architecture/local-llm-build-engine.md
• Client capability parity (live): docs/architecture/agent-client-capability-parity.md