voyage/docs/agent-description-token-trim-brief.md

type	brief_version	created	task	slug	project_dir	research_topics	research_status	auto_research	interview_turns	source	framing	phase_signals
trekbrief	2.2	2026-06-26	Relocate <example> blocks out of voyage agent description frontmatter to cut always-loaded tokens	agent-description-token-trim	.claude/projects/2026-06-26-agent-description-token-trim/	0	skipped	false	0	manual	refine	phase effort research low phase effort plan standard phase effort execute standard phase effort review standard

Task: Trim voyage agent description: frontmatter — relocate <example> blocks into the agent body

Cross-session coordination brief. Authored 2026-06-26 by the config-audit machine-tuning session (a parallel session that audits this machine's Claude Code always-loaded token footprint). It is dropped here per operator instruction so the voyage session owns the implementation — config-audit does not edit the voyage repo. The source measurement lives in config-audit's local worklist (config-audit/docs/machine-tuning-worklist.local.md, item M4, session m). This brief is the contract; /trekplan can consume it directly.

TL;DR

voyage's 24 agent description: fields cost ~4,418 always-loaded tokens every turn (injected into the system prompt of every session that has voyage enabled). 17 of those agents carry two <example> blocks each (34 total, ~3,147 tok) in their frontmatter description. Those example blocks exist to drive autonomous agent-selection — but voyage agents are launched by explicit name from the orchestrator commands, so the examples are cost without function. Move them into each agent's body (preserve, don't delete). Expected saving: ~2,500–3,100 always-loaded tokens. framing: refine — this continues the token-trim line started in M1a (v5.6.1).

Intent

The machine's #1 tuning lever is always-loaded tokens — context injected on every turn, paid on every request. config-audit's Fase-1 measurement (2026-06-26) found the machine's global layer is already lean (CLAUDE.md trimmed, rules/agents empty, output style off, MCP deferred), and the single largest remaining tunable source is voyage's agent listing (~4,418 tok). The bulk of that is <example> blocks in the spawnable agents' description: frontmatter. These blocks follow the documented agent-authoring pattern whose purpose is to help the main loop autonomously decide when to delegate to an agent. voyage doesn't rely on that path: /trekplan, /trekresearch, and /trekreview launch their agents deterministically by name ("Launch the architecture-mapper agent", explicit per-codebase-size launch tables, explicit voyage:review-coordinator references). So the examples are paying a per-turn token tax for an auto-selection behavior voyage never uses.

Goal

Each of the 17 example-bearing voyage agents has its frontmatter description: reduced to its triggering lead sentence(s) (the "Use this agent to/when…" summary — what any residual autonomous selection actually needs), with the <example> blocks relocated verbatim into the agent's markdown body under a clearly-marked section (e.g. ## When to use — examples). No agent is deleted, no behavior changes, no example content is lost. The injected agent-listing cost drops by ~2,500–3,100 tokens, landing on every machine that reloads voyage after release.

Non-Goals

• Do NOT delete the examples — relocate them into the body. They remain useful documentation and /trekbrief/onboarding reference.
• Do NOT change any agent's system prompt, body logic, tools, model, or name (name is the agent's identity).
• Do NOT touch the 7 zero-example agents (planning-orchestrator, research-orchestrator, review-orchestrator, synthesis-agent, review-coordinator, code-correctness-reviewer, brief-conformance-reviewer) — already lean (M1a handled the reference/dormant ones; the orchestrators keep their pinned "reference document, not a spawnable capability" phrasing).
• Do NOT modify the orchestrator commands (/trekplan etc.) or change which agents exist.
• This is not a behavioral or capability change — purely a token/packaging optimization.

Constraints

• Frontmatter must remain valid YAML. The retained description: must keep a meaningful triggering lead sentence, because a few agents (notably the *-researcher agents) can legitimately be selected autonomously when a user asks a research question directly — keep their first 1–2 sentences descriptive enough to still trigger.
• The test suite must stay green. node --test 'tests/**/*.test.mjs' is the gate. voyage has inventory/frontmatter-pin tests — M1a's note warned that "synthesis-schema + inventory tests may pin description content." If any test asserts on <example> presence/count or description length, update that test's expectation deliberately (it is asserting the old structure) and document why.
• Follow voyage's release discipline: version-sync (plugin.json + package.json + README badge/What's-new + CHANGELOG), annotated tag, and catalog ref bump with check-versions green. This is a perf/token change → a patch release (e.g. v5.6.2) or fold into the work already in progress on the branch.
• The saving only reaches a machine after the operator reloads voyage (/plugin marketplace update + update + /exit) — note this in the CHANGELOG so the delta isn't expected instantly.

Preferences

• Relocate the two examples per agent into a single body section with a stable heading so they're easy to find and so any future inventory test can pin the body instead of the frontmatter.
• Keep the diff mechanical and uniform across the 17 agents (same heading, same ordering) for reviewability.
• If a lead sentence is currently entangled with the first <example>, lightly rewrite it into a clean 1–2 sentence trigger — minimal, not a rewrite.

Non-Functional Requirements

• Zero new dependencies.
• Always-loaded description budget: total frontmatter description chars across all 24 agents drops from ~17,672 to ≤ ~6,000 (~2,500–3,100 tok saved).
• No regression in agent auto-selection for the agents that are legitimately autonomous (the researchers) — spot-check that a direct research-style prompt still routes sensibly.

Success Criteria

• Full suite green: node --test 'tests/**/*.test.mjs' exits 0 (same pass count, or deliberately updated pins with rationale).
• No <example> in any frontmatter description: the frontmatter-only scan below prints 0:

  python3 - <<'PY'
  import re,glob
  n=0
  for f in glob.glob('agents/*.md'):
      t=open(f).read(); m=re.match(r'^---\n(.*?)\n---', t, re.S)
      fm=m.group(1) if m else ''
      dm=re.search(r'description:\s*(.*?)(?=\n[a-zA-Z_][a-zA-Z_-]*:\s|\Z)', fm, re.S)
      n+=(dm.group(1).count('<example>') if dm else 0)
  print(n)   # must be 0
  PY
  

• Examples preserved in bodies: grep -l '<example>' agents/*.md still lists the 17 agents (the blocks moved, not vanished).
• Agent count unchanged: 24 agents, each with non-empty name + description. Plugin validates (plugin-validator / inventory tests green).
• Token budget met: total frontmatter description chars ≤ ~6,000 (measure with the per-agent script in the worklist / the snippet above adapted to sum lengths).
• Behavior unchanged: /trekplan (and trekresearch/trekreview) still launch the same agents by name — diff touches only agents/*.md, no command files.

Research Plan

No external research needed — the codebase and this brief contain sufficient context for planning. (research_topics = 0.)

Open Questions / Assumptions

• [ASSUMPTION] The 17 example-bearing agents are invoked by name from orchestrator commands — verified by the config-audit session against voyage/commands/*.md (explicit "Launch the X agent" prose + per-size launch tables + explicit voyage:<name> references). The <example> auto-trigger blocks are therefore non-load-bearing for voyage's actual invocation path.
• [Q] Do any voyage tests assert on <example> presence/count or description length in agents/*.md? Check first (grep -rn 'example\|description' tests/), so a pin is updated intentionally, not discovered as a red test.
• [ASSUMPTION] The *-researcher agents (community/contrarian/docs/security) and gemini-bridge may also be autonomously selected outside the trek pipeline → keep their lead sentences trigger-worthy (don't reduce to a bare label).

Prior Attempts

• M1a — voyage v5.6.1 (2026-06-24): trimmed the 4 non-spawnable reference/dormant agents' (planning/research/review-orchestrator + synthesis-agent) verbose description: fields to one-liners; orchestrators kept their pinned phrase, synthesis kept its DORMANT flag. Suite stayed green (756). M4 extends that same always-loaded-token-trim to the 17 spawnable agents' <example> blocks — the larger remaining chunk M1a deliberately left.

Reference data (config-audit Fase-1 measurement, 2026-06-26)

24 agents, 17,672 description chars (~4,418 tok), 34 <example> blocks, ~12,591 chars (~3,147 tok) inside <example>…</example>. The 17 example-bearing agents (descending description size):

agent	desc chars	examples
community-researcher	1280	2
contrarian-researcher	1270	2
gemini-bridge	1226	2
security-researcher	1207	2
docs-researcher	1138	2
session-decomposer	946	2
convention-scanner	939	2
brief-reviewer	870	2
research-scout	847	2
test-strategist	823	2
dependency-tracer	818	2
task-finder	817	2
git-historian	795	2
risk-assessor	794	2
architecture-mapper	789	2
scope-guardian	750	2
plan-critic	692	2

Zero-example (leave as-is): review-coordinator (345), code-correctness-reviewer (292), brief-conformance-reviewer (266), synthesis-agent (228), planning-orchestrator (184), research-orchestrator (179), review-orchestrator (177).

Metadata

• Created: 2026-06-26
• Interview turns: 0
• Auto-research opted in: no
• Source: manual (cross-session coordination brief from the config-audit machine-tuning session)

---

How to continue

# (optional) confirm no test pins <example> in descriptions first:
grep -rn 'example' tests/ | grep -i descr

# plan + execute via the voyage pipeline:
/trekplan --project .claude/projects/2026-06-26-agent-description-token-trim/
/trekexecute --project .claude/projects/2026-06-26-agent-description-token-trim/

# or implement directly (it's a uniform, mechanical 17-file edit) and release as a patch (v5.6.2):
#   - move each agent's 2 <example> blocks from frontmatter description into a body
#     "## When to use — examples" section
#   - node --test 'tests/**/*.test.mjs'  (green)
#   - version-sync + CHANGELOG + tag + catalog ref-bump (check-versions green)