Skip to Content
Design DecisionsMethodology Agent Digest

Vendored per-stage methodology digest in cached system prompts

Status: Accepted as a proof of concept (as-is stage only; rollout to r2b/to-be and release-freezing still open) · Date: 2026-06-22/23 · Area: Agents

Context

Every stage agent and sub-agent working a solution needs the Trajectory methodology in context. The original mechanism — a load-as-is-spec skill whose file reads pulled in the README, stage spec, base format, and schemas — meant each agent pickup re-read roughly 74K tokens of methodology as uncached tool results, on every task, for every sub-agent.

Decision

  • A generated, per-stage methodology digest (~8.2K tokens for as-is) is injected as the first block of the cached system prompt of the stage’s orchestrator and every sub-agent persona — an identical prefix for best cache reuse.
  • The generator (trajectory-methodology/tooling/gen-agent-digest.mjs, zero-dependency Node) projects each digest from two deterministic sources: verbatim section slices of the prose (lossy by selection, not paraphrase — no wording drift) plus a compact field/enum reference distilled from the JSON Schemas. A TASKS manifest is the tuning knob; a --check mode is the staleness gate.
  • Digests are vendored with the pinned methodology copy (.generated/agent-digest/<version>/<stage>.md inside the solution’s vendored trajectory-methodology/), so a solution’s digest always matches its pinned methodology version.
  • The load-as-is-spec skill was thinned: it no longer re-reads what the digest covers, loading only solution-specific activated technology guides and assessment types, with the full methodology kept as an on-demand escape hatch.

Consequences

  • The measured reality is deliberately recorded next to the static claim, so expectations stay honest: the methodology slice shrank ~89% (74K → 8.2K, and moved from uncached tool reads into the cached prefix), but the live total gain is a modest ~9–13% of cost with ~30% lower orchestrator cache-read per message — real runs are dominated by the work context (code walked, artefacts read and written), which the digest does not touch.
  • A cost-accounting gotcha is part of the record: a task’s orchestrator-scoped summary.usage does not reconcile with costUsd (which includes all SDK sub-agents and runs ~12–15× higher); summing per-message usage double-counts overlapping cached tokens.
  • Operational sharp edge: the digest loader memoizes per process — after vendoring a digest into a solution, the agent must be restarted or it keeps a cached null.
  • Open before full rollout: r2b and to-be digests, stage set on the other stage agents, freezing digests into methodology releases/v<X.Y>/, the CI staleness gate, and syncing the thinned skill into live internal repos.

Evidence

  • trajectory-methodology/tooling/gen-agent-digest.mjs (in the sibling methodology repo) — the generator
  • implementation/maxq-orbit-agent/codebase/src/agents/methodologyDigest.ts — loadStageDigest and the system-prompt wiring
  • solution-template-internal — the thinned load-as-is-spec skill
  • memory/methodology-agent-digest.md (incl. the measured before/after)
Serial Task ProcessorNative Octokit Agent Tools