chore(prompt-surface): put devflow on a diet — condense every installed surface without losing detail

[dean0x]

Motivation

Decision 2026-09-15: devflow's installed prompt surface is billed per spawn and per session (PF-026), and the right way to keep context small is to say the same thing in fewer words — dry, concise, no repetition, no lost detail — across the whole product, not only the Git agent. Byte ceilings are regression alarms, not the diet: they fire on growth and are lowered after each condensing pass (ADR-025 corollary: ceilings may be lowered, never raised). This issue is the devflow-wide diet.

Measurements (source files under src/assets, 2026-09-15, branch feat/324-tracker-phase-2-contract-mechanics-split)

Group	Files	Bytes	Largest
Agents	16	183,527	git 56k, code 17k, synthesize 15k
Skills — SKILL.md	41	218,105	feature-knowledge 14k, test-driven-development 10k, docs-framework 9k
Skills — references/	116	787,696	react 66k, patterns 50k, git 43k
Commands (hosts + partials)	26	265,202	14 hosts 204k, 12 partials 61k
Rules	13	6,409	compliance 1k
MDS reference modules	2	30,423	tracker/_github 23k, git/_references 8k
Installed surface (groups 1–5)	214	1,491,362	≈ 373k tokens at 4 chars/token

Per-spawn base load (agent file + frontmatter-preloaded SKILL.md files):

Agent	Agent bytes	Preloaded skills	Skills bytes	Base load
code	17,174	10	51,082	68,256
git	56,425	2	9,551	65,976
diagnose	10,345	8	32,981	43,326
synthesize	15,440	3	16,878	32,318
knowledge	6,039	4	24,034	30,073
design	5,061	5	24,387	29,448
review	11,348	4	14,537	25,885
triage	9,292	4	14,918	24,210
scrutinize	4,038	5	19,443	23,481
test	7,730	3	14,009	21,739

Per-session injected context: orchestrator charter 2,452; WORKING-MEMORY.md ≈ 7,100 (memory on); learning index.md ≈ 13,100 (learning on); preamble and session-start directives ≈ 1,400–1,800 variable.

Git agent per-spawn set as gated today: 77,143 chars vs ceiling 77,824 (BUDGET_LOADED_SET, tests/tracker/byte-budget.test.ts); dist/agents/git.md 55,776 vs 55,900 (BUDGET_GIT_MD).

Host constraints that make this matter beyond Claude Code (research 2026-09-15, .devflow/docs/research/codex-native-git/2026-09-15_1200/external.md, local artifact): Codex discovers skills through a skill-list budget of about 8,000 characters against devflow's 41 skill roots, and shares a 32 KiB AGENTS.md budget. See #333.

Scope

1. Agents — every src/assets/agents/*.md|.mds. Git first: git.md: second size cut — move the 8 PR/review op bodies to references (SG-7) #326 moves the eight PR/review op bodies (≈ 24,161 B ≈ 6,000 tokens) out of git.md; then a prose pass on what remains; make the worktree-support skill (2,942 chars) on-demand for the Git agent. Code agent: audit the ten preloaded skills — preload only what a majority of runs use, point to the rest.
2. Frontmatter skill preloads on all 16 agents — same majority-use rule; the table above is the ranking.
3. Skills — SKILL.md files toward the ~120–150 line target with progressive disclosure to references/; audit the largest reference trees (react, patterns, git) for restatement of what the SKILL.md or an agent already says. Agents reference skills, never duplicate them (CLAUDE.md).
4. Commands — the 14 hosts (204k) and 12 partials: remove restated phase prose, keep contracts.
5. Hook-injected context — orchestrator charter, the learning index (13k every session: compact the rendered index), the memory injection header.
6. Rules — already small; verify no overlap with skills.

Method (per surface, one PR each)

Measure → find restatement, duplicated skill content, transition narration and tombstones (ADR-003) → condense without dropping a rule, contract, or example the guards pin → verify: goldens regenerated only in fixture-only commits (PF-057), every named-collector guard and probe intact (ADR-024/PF-018), status-lines fixture untouched → lower the relevant ceiling to the new size in the same PR.

Acceptance criteria

• A before/after table per surface in the PR body, in chars and estimated tokens.
• Every applicable ceiling lowered; none raised; no floor lowered; no guard weakened or exempted.
• Zero user-visible behaviour change; full suite green.
• Git agent per-spawn set and dist/agents/git.md measurably below today's figures after the git pass.

Links

Depends on PR #339 merging first. Related: #326 (SG-7 second git.md cut), #333 (Codex compatibility), #321 (tracker tracking issue). Doctrine: PF-026, ADR-025, ADR-003, PF-057, ADR-024, PF-018.