diff --git a/docs/agent-description-token-trim-brief.md b/docs/agent-description-token-trim-brief.md new file mode 100644 index 0000000..2dfb3ab --- /dev/null +++ b/docs/agent-description-token-trim-brief.md @@ -0,0 +1,153 @@ +--- +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) +```