Kjell Tore Guttormsen
6bd50a42dd
Cross-session coordination brief from the config-audit machine-tuning session, dropped into voyage per operator instruction. brief_version 2.2, framing: refine. Locked as the next session's task (Alternative A). Tracking it makes the next session's /trekplan --brief input deterministic and durable on the private remote.
153 lines
11 KiB
Markdown
153 lines
11 KiB
Markdown
---
|
||
type: trekbrief
|
||
brief_version: "2.2"
|
||
created: 2026-06-26
|
||
task: "Relocate <example> 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 `<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`:
|
||
```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('<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
|
||
|
||
```bash
|
||
# (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)
|
||
```
|