English · 한국어

cladding

To trust AI with coding, an organization needs three things —
that the code can be trusted, that it's traced, and that it holds up as you scale. cladding builds those three.
True to its name (cladding = the outer layer), it wraps the host LLM and verifies what comes before and after.

The official reference implementation of the Ironclad standard.
Before your host LLM (Claude Code · Codex · Gemini · Cursor) starts work, cladding feeds it the project's intent;
after it finishes, cladding verifies the result with 41 detectors and a 15-stage gate.

• Only verified code ships as "done" — Even when the AI says "it's done," it has to clear the checks — so code that couldn't be verified is never recognized as complete.
• What shipped is on the record — What was verified is stamped into committed content, who and when land in the local session ledger, and why lives in the spec — so handoff and review can trace decisions without archaeology.
• It holds up as the team grows and you add more AIs — Because the spec is the shared baseline, conflicts and drift are blocked automatically.

This loop is after one thing — turning the AI's "it's done" from a claim into a proof.

So you can ship code an AI wrote with the same trust as code a human wrote.

cladding builds itself with cladding too — 242 of its 245 features cleared the same gate, the first L4 implementation of the Ironclad standard.

How it works with your host LLM

Before — inject the intent

So the LLM starts with the right context.

• Project map injected — every time a conversation starts, "how many features, what's in progress, the last verification result" is handed to the LLM automatically _{(now you can see it too ↓)}.
• Only the intent that matters — just the why of the feature at hand, its related features, and its acceptance criteria are pulled out (it does not dump the whole spec).
• Project rules applied — the forbidden and preferred patterns the team agreed on go in as standing instructions every time.

After — verify: the 15-stage gate, 41 drift detectors, and an implementation-blind grader (below).

_{Real-time intervention (map injection · instant block · stop-block) all works on Claude Code. On Codex · Gemini · Cursor the same verification runs through in-conversation tool calls plus the git · CI gate.}

"done" is earned, not declared

The chronic disease of AI coding is "it's done" declared with no verification behind it. In cladding, a feature's status: done is not a value you write — it's a value you earn.

1. When the AI tries to write the completion mark itself → it's blocked on the spot ("earn completion by verifying it").
2. When the AI requests completion → all 9 deterministic stages run, and it's recorded as done only if every one passes; one failure and it auto-reverts — the E2E · evidence stages are handled by CI's full 15.
3. The moment it passes, a verification signature is left behind — committable proof that "this code was verified at this point."
4. Try to end a conversation leaving a failure → it blocks you once (end again on the same failure and it records the fact rather than letting it through) and carries the repair card into the next conversation.

The limits are disclosed plainly too: bypass paths exist that the instant block can't see, and those are caught by after-the-fact verification (the gate · drift checks). The instant block is the first line of defense, after-the-fact verification the second — and neither is a standalone guarantee.

What changes

How a vanilla AI coding environment and a cladding environment behave in the same situation.

Project map — now you can see it and ask it _new

cladding always keeps a map inside it that connects spec · code · tests · docs. Now you can see that map with your own eyes.

Why this matters — the docs and the code don't drift apart. Docs lie as time passes — the code changes but the description stays put. cladding re-checks that connection every time the code is read, and blocks "done" while the two are out of sync.

Blue = spec (center), orange = code, green = tests, pink = docs; more-connected nodes grow larger and pull to the center.

• See — the whole project on one canvas — Run clad graph serve, open the printed localhost address in your browser, and you see what connects to what at a glance.
• Ask — "what breaks if I change this?" — Ask the map and it tells you what's affected and which tests to run — it doesn't guess.
• Measure — it shines brighter the larger the project — The amount you have to look at when fixing something drops sharply — on average 4× less than reading everything. (clad measure)

To launch it yourself — from your project folder:

clad graph serve                                  # live graph — localhost:3000, auto-reloads on save
clad graph export --format html --out graph.html  # or export to a single offline file (.html)

_{Both require cladding 0.7.0+.}

How it works

Spec → Code → Tests runs as a single cycle — the spec records the why, the gate verifies, and the detectors block drift.

1. Spec — the single source of intent (SSoT)

The spec records the why (what we're building and why). A 4-tier single source of truth — intent on top, the implementation below, code follows the spec.

A outranks every tier below it — if spec (A) and code (C) disagree, the code is the one that's wrong.

Sharded · multi-dev safe — like spec/features/<slug>-<hash8>.yaml, each feature gets its own file + an 8-char hash ID (e.g. F-d86375d8). Two devs creating new features at the same time land in different files with different IDs, so zero merge conflicts. Details: Hash-based feature IDs.

2. Gate — the 15-stage Iron Law

One check engine, bundled by cost: 3 at commit, 9 at push/completion, all 15 in CI. Only the depth differs.

3. Detector — 41 drift detectors

Drift in every direction across spec · code · test is detected automatically. Full catalog: detector catalog.

The knowledge graph these power is a traceability / retrieval capability, not a correctness one — cladding's own A/B record shows correctness is orthogonal to governance. It tells you what connects to what and what to re-check; it does not claim the code is correct.

4. Cycle — one feature's lifecycle

Define → Sync → Implement → Earn. You earn "done" only by passing every check.

Using cladding as your agent loop's verifier

You own the loop — whatever harness or orchestrator drives your agent. cladding is the verifier and state layer inside it: it doesn't run your loop, it tells the loop what's still wrong and when it's allowed to stop.

• Feedback signal — run clad check --json each iteration. The verdict is machine-readable: a top-level anyFailed and a worst severity, plus per-stage findings[] where each entry carries its detector, severity, and message. Feed that straight back as the loop's error signal — no scraping console text.
• Honest stop — gate the loop on clad done, not on the agent's say-so. It flips a feature to done only when the strict pre-push gate is GREEN, and reverts otherwise. "The loop says it's finished" becomes "the gate let it stand."
• Loop memory — the local event log (.cladding/events.log.jsonl, gitignored) carries what happened across iterations: gate runs (deduped per HEAD), done attempts, drift firings, value serves. The next iteration reads it as local working memory — not a durable or authoritative record, and it rotates at 5 MB (a single generation), so the oldest entries fall away.

The honest boundary: this hardens the loop's stop condition and feedback signal, not the model's code quality. cladding's own A/B record is the receipt — governance is orthogonal to correctness.

Multi-Agent — separating the builder from the verifier

The agents that build are kept separate from the agents that verify, so no agent can sign off on its own work. blind-author goes one step further — the agent that writes the tests has no tool to read the implementation at all (no Read/Grep granted). "Wrote it without looking at the implementation" becomes a structural fact, not a promise. This separation aligns with the segregation-of-duties principle that regulatory · audit regimes (EU AI Act · SOX) call for — it maps onto the spirit of those regimes, not a certification.

Ecosystem

cladding sits at the junction of three existing categories.

How it differs from the neighbors

• Spec Kit · OpenSpec · Tessl · Kiro — tools that help you write a good spec. On top of that, cladding keeps continuously cross-checking, inside the dev loop, that the spec and the actual code don't drift.
• BMAD · ChatDev · Claude Code Agent Teams — systems for splitting roles across multiple AI agents. cladding's agent division of labor runs with spec · gate · audit record combined on top.
• tdd-guard — a tool that forces the AI to write tests first. The Unit · Coverage · oracle stages among cladding's 15 do the same job, more structurally.
• OpenHands · Cline · Aider · Goose — runners that make the AI write code (pure executors). cladding is the upper layer that verifies and governs the code those runners produce.

cladding's distinction is the combination — binding the core of the categories above into one verification loop.

Install

Two steps — install the infrastructure → create the project spec.

Step 1 — Install the infrastructure (npm)

npm install -g cladding   # install the cladding CLI
cd <project>              # move into the project
clad setup                # auto-wire your AI tools (Claude / Codex / Gemini / Cursor)

Step 2 — Init (create the project spec)

From the project directory, call it once inside your AI tool:

[inside your AI tool] /cladding:init "B2B payment SaaS"

The project's spec.yaml and supporting docs are created — once per project.

To raise enforcement: clad init --with-hook (install pre-commit + pre-push git hooks) · clad init --with-ci (scaffold the CI gate — true enforcement lives in CI).

Three init scenarios

Init once, that's it

Init once and you're done — after that, just develop as usual. cladding runs the before/after loop in the background, so there are no commands to memorize.

Upgrading

npm update -g cladding     # 1. install the new version
cd <your project>          # 2. once per project
clad update                # 3. bring it in line with the new version

Your code · spec.yaml · docs are left untouched, so it's safe — and if the newer version is stricter and has something to flag, it just points it out (it won't block or fix anything).

Status

_{226 test files · 6 capabilities · coverage drop blocked by the COVERAGE_DROP detector}

Road to Ironclad 1.0 — 1.0 locks only when two independent implementations pass the L4 conformance fixtures (GOVERNANCE § 1). cladding is the first.

Docs

• Why cladding (project context)
• 4-tier governance model
• Hash-based feature IDs
• 41 detector catalog
• Glossary (EN · KO)
• Governance · roadmap to 1.0

License

MIT. LICENSE · Related: Ironclad (the standard cladding implements) · harness-boot (the seed).