squid-clean-harness

Clean harness — same logic, minimum tokens

You are the cleaner. You shrink the skills and resources a harness loads; you do not change what they make the agent do. Zero logic diff is the contract — every capability, step, and rule that holds before must hold after; only tokens die.

Output is a plan table, approved by the user, then applied as one commit per category.

$ARGUMENTS is an optional .agents/ path (e.g. ~/Vaults/Second-Brain/.agents). Empty means the repo's ./.agents.

When to use

• The harness has sedimented — stale layers of guidance, verbose prompts, dead helpers.
• Sessions burn tokens on skill descriptions and bodies that say little per word.

When NOT to use — out of scope, no exceptions

Step 1 — Resolve the target set

Inventory skills/*/SKILL.md and resources/** minus resources/datasets/ under the target .agents/. Everything must be revertible: clean in git, or snapshot first (cp -R .agents .agents.bak) when the tree isn't tracked.

Step 2 — Audit the contract (frontmatter)

Two questions per skill:

• Invocation type — auto-fired by the model, or only typed by the user? User-only → disable-model-invocation: true, keeping its description out of the always-loaded skill list. Flipping also cuts reach from other skills — grep the set for the skill's name first (Step 4's proof); one referrer means it stays model-invoked.
• Description — must match what the body does. Model-invoked → triggers only, one per branch: synonyms naming the same branch are duplication ("build with TDD" / "asks for test-first development" is one branch written twice). User-only → one sentence of what it does; trigger prose serves no router — delete it. A user-only skill with fifteen lines of "use for X, Y, Z" pays those tokens for nobody.

Done only when every skill in the set has both answers recorded — no sampling.

Step 3 — Apply the keep/delete test

An instruction survives only if deleting it would change what the agent does. The cuts apply to every file in the set — skill bodies and resources/ docs alike, datasets/ never. Five cuts:

Duplicates — the same rule twice in one skill, repeated across skills, or restating a resources/ doc the skill already points at (a skill body repeating glossary.md definitions) — the resource is the home, the skill keeps the pointer. Two resources repeating each other collapse to one home the same way, as does a block ≥2 skills share — Disclosure below says where it goes.

Baked-in claims — would the agent already behave this way with the line deleted (harness default, system-prompt rule)? Dead weight. "Read the file before editing it" dies; "write posts in the voice defined in resources/branding/" stays. The test is harness-relative — .agents/ serves non-Claude agents too: delete only defaults universal to whatever loads the skill; flag the Claude Code-specific ones. Test sentence by sentence; a failing sentence dies whole — never trim words from it.

Verbose logic — the exact same logic in the minimum words: collapse restatements, prefer a table row to a paragraph, caveman-terse wording. Collapse a restated quality into one pretrained leading word ("fast, deterministic, low-overhead" → a tight loop) — fewer tokens and a sharper hook. If the caveman plugin is installed, /caveman-compress per file is a good first draft — re-check afterwards that the frontmatter is still parseable YAML.

Merges — steps or sections nobody reads apart become one; reorder so each idea appears once, at the point the agent needs it.

Disclosure — a skill body is paid for on every invocation, including the branches that never read it. Inline what every branch needs; push what only some branches reach — a lookup table, a per-platform appendix, a rare edge-case procedure — into a resources/ doc loaded on demand. Same home for a block ≥2 skills share. Size decides: ~20+ lines earns its own file, below that indirection costs a Read for less than it saves. Per-invocation tokens fall even when total words don't. The pointer's wording, not its target, decides whether the agent reaches the material — say when to load it, not just where it lives ("for the Slack variants, read platforms.md", not "see platforms.md"). Theory: /squid-write-skill.

Done only when every file in the set is read whole and judged against all five cuts.

Step 4 — Dangling artifacts

A reference, script, agent, or resources/ doc is dead only with zero references outside its own definition:

grep -rn "helper.py" <harness-root> <project-root>   # prove it, don't assume

• A rule dangles by staleness, not references — nobody cites a rule, they read it. It dies when what it governs no longer exists: a step for a removed tool, a caveat for a branch that's gone.
• Referenced but missing → a broken contract, not a deletion: flag it and ask.
• Present but unreferenced → delete only on clean proof; a helper called from outside .agents/ (cron, vault automation) is invisible to grep — when unsure, flag, never auto-delete.

Done only when every artifact is proven dead, alive, or flagged.

Step 5 — Plan of attack (the output artifact)

Print one table in chat. Do not write it to disk unless the user asks.

Stop and wait for explicit approval. Do not edit before it.

Step 6 — Execute

Apply the approved plan, one commit per category (frontmatter, cuts, dangling) so any revert is surgical.

Step 7 — Verify

Logic must be provably unchanged before hand-off:

• Every SKILL.md frontmatter still parses as YAML with name + description — unparseable YAML loads the skill with every field silently dropped.
• Every remaining reference (file, skill, script, agent) resolves, and every disclosed file has a pointer that states when to load it.
• Per-file logic diff: every step and rule in the old version is still stated or merged — name its new home.
• No skill or argument was renamed.

Anything off: revert that commit (or restore the snapshot), do not "fix forward".

Step 8 — Hand-off

Report wc -w before → after per file, what moved into resources/, and every flagged dangling item. Point the user at /squid-write-skill for flagged items that need rewriting rather than cutting — an edit is theirs to make, and only they can invoke it.

Notes on shape

• Fewer tokens, never fewer capabilities. If a cut loses logic, it is an edit — out of scope.
• One home per idea. Shared blocks live in resources/; skills reference, never transclude.
• Datasets are cargo. resources/datasets/ is what skills operate on, not how they work — never in scope.