Ship Types, Not Markdown

Ship types, not markdown.

That’s how we keep 100+ agents from breaking things.

We run a large swarm because precision requires specialization.

Each agent is a scalpel, not a Swiss army knife.

But precision falls apart if your safeguards live in markdown.

“Please don’t cast branded types.” “Please don’t mutate validated values.” “Please follow the rules.”

Please doesn’t scale.

Constraints do.

Nicolas Grislain put it well: guarantee by construction beats verify after the fact.

Zod branded types get you part of the way there. TypeScript still leaves 3 escape hatches:

as casts — forge the brand Direct type annotations — skip validation Mutation — invalidate a validated value

So I wrote 3 ESLint rules to close them.

Now branded values are immutable and unforgeable by default.

When I ran the rules on our own codebase, they found violations in code I’d already reviewed.

That’s the broader principle:

If a rule matters, don’t write it in markdown.

Encode it in types, linters, and permission gates.

When agents can’t break the rules, you don’t need to watch them.

h/t Nicolas Grislain’s “Don’t Vibe — Prove”

What’s non-negotiable in your system — and have you enforced it structurally, or just documented it?