Term Drift: Adding then removing a TERMS.md from my workflow.

In my coding workflow, Plumbline, each skill is loaded cold, by a fresh agent, sometimes a different model. As I refine each part I write terms for the handoffs in each skill. But every rewrite is a chance for those terms to drift between skills. A stamp spelled two ways, a status line the orchestrator no longer recognized — and nothing errors. The chain just quietly mis-routes or drifts

The fix was TERMS.md: one contract file defining every shared token, and a rule that every skill reads it first and stops if it can't. Drift stopped.

Then I looked at the bill. TERMS.md was ~2,300 words, and an unattended build spawns around ten subagents — every one paying to load the full contract, including sections that didn't bind it. The scaffold skill, which uses almost none of it, paid the same as the inspector. Roughly 30k tokens a run, re-verifying something that never changes mid-run.

That was the insight: the protection was never the runtime read. It was verification — and verification belongs where the contract changes, not where it's used. A deterministic script now audits every skill against TERMS.md in CI, on every push.

So TERMS.md left the runtime. Each section now carries an audience tag, a generator cuts per-skill slices, and each skill reads only its slice — 20–67% smaller, audit-enforced so a slice can't drift from its source. TERMS.md still exists; no agent reads all of it anymore.

The lesson is one I keep relearning: every gate has to earn its place. A runtime check that re-proves what CI already proved isn't safety. It's ceremony with a token bill.

My thoughts are now on taking this lesson and can I turn it into a skill I can reuse in future.

2 comments

Term Drift: Adding then removing a TERMS.md from my workflow.