--- type: trekbrief brief_version: "2.2" created: 2026-06-26 task: "Relocate blocks out of voyage agent description frontmatter to cut always-loaded tokens" slug: agent-description-token-trim project_dir: .claude/projects/2026-06-26-agent-description-token-trim/ research_topics: 0 research_status: skipped auto_research: false interview_turns: 0 source: manual framing: refine phase_signals: - phase: research effort: low - phase: plan effort: standard - phase: execute effort: standard - phase: review effort: standard --- # Task: Trim voyage agent `description:` frontmatter — relocate `` 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 `` 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 `` 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 `` 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 `` 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 ``, 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 `` in any frontmatter `description`:** the frontmatter-only scan below prints `0`: ```bash 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('') if dm else 0) print(n) # must be 0 PY ``` - **Examples preserved in bodies:** `grep -l '' 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:` references). The `` auto-trigger blocks are therefore non-load-bearing for voyage's actual invocation path. - **[Q]** Do any voyage tests assert on `` 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' `` 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 `` blocks**, ~12,591 chars (~3,147 tok) inside `…`. 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 ```bash # (optional) confirm no test pins 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 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) ```