cladding

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 your host LLM (Claude Code · Codex · Gemini · Cursor): before it starts, cladding feeds it the project's intent; after it finishes, cladding verifies the result with 41 detectors and a 15-stage gate.

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

So you can ship AI-written code held to the same standard as human-written code — the three things an organization needs to hand coding to AI:

• Trusted — only code that cleared every check is recognized as done; an "it's done" you can't verify never passes.
• Traced — What shipped is on the record: what was verified is stamped into committed content, who and when land in the local session ledger, and the why lives in the spec — so handoff and review skip the archaeology.
• Scales — adding people and AIs would normally multiply conflicts and drift; because everyone works from one shared spec, those get caught automatically — so you can grow without it breaking down.

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

What changes

The same situation, in a vanilla AI setup and in cladding.

Situation	Vanilla AI coding	cladding
Code drifts from the spec	fixed if a reviewer notices	auto-detected right after the edit · "done" can't pass while it's drifting
The AI says "it's done"	you take its word	done earned only when the gate is GREEN
Ending a session in a failing state	exits as-is, forgotten next time	the exit is blocked once, the failing checks handed off as a repair card
Two devs add a feature at the same time	merge conflict	hash-8 IDs · separate files → 0 conflicts
Who verifies the AI-written code?	the AI that wrote it self-certifies (risky)	an implementation-blind grader + the mechanical gate
Switching AI tools	reconfigure per tool	one spec → 4 hosts wired automatically

Who it's for

• A developer who has an AI write code — when the AI says "it's done," cladding doesn't take its word for it: it checks whether the work actually passes, and only then counts it as done. (Automating it in a loop? That's the loop section.)
• A team of people and AIs — everyone works from the same spec, so when their changes clash or drift apart it's caught automatically, and no one breaks someone else's work by accident.
• An organization that has to prove its work — every done is recorded with the proof that it actually passed, so months later "was this verified? why was it built this way?" is answered by the repo, not by memory.

How cladding wraps your host LLM

Before — inject the intent, so the LLM starts with the right context:

• Only the intent that matters — the why of the feature at hand, its related features, and its acceptance criteria (never the whole spec).
• Project map injected — feature counts, what's in progress, and the last verification result, handed over at the start of every conversation _{(and now you can see it too ↓)}.
• Team rules applied — the forbidden and preferred patterns you agreed on, as standing instructions every time.

After — verify the result: the 15-stage gate, 41 drift detectors, and an implementation-blind grader — an agent that checks the work against the spec with no tool to read the implementation, so it can't rubber-stamp what it wrote.

_{Real-time intervention (map injection · instant block · stop-block) runs fully 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 nothing behind it. In cladding, status: done is not a value you write — it's a value you earn.

• Try to write the completion mark yourself → blocked on the spot ("earn it by verifying it").
• Request completion → all 9 deterministic stages run; recorded as done only if every one passes, else it auto-reverts (the E2E · evidence stages run in CI's full 15).
• The moment it passes, a verification signature is committed — proof that "this code was verified at this point."
• Try to end a session on a failure → blocked once (end again on the same failure and it's logged as a known-failing exit rather than let through), and the repair card carries into the next conversation.

Stated plainly: bypass paths exist that the instant block can't see; those are caught by the after-the-fact gate. Instant block is the first line of defense, the gate the second — neither is a standalone guarantee.

cladding backs your AI loop

Loop engineering is a shift in how you use an AI: instead of prompting it step by step, you build a loop that drives it toward a goal and runs on its own — discover, plan, execute, verify, iterate. But a loop is only as honest as its verify step, and an AI left to check its own work just passes itself. So you put something in the loop that can truly say "no" — that's cladding: the check that grades your code against your spec, not the AI's opinion of its own work.

Three things it gives your loop:

• A signal it can act on — every pass you get back a plain, machine-readable result: what failed, where, and how bad. Feed it straight into the loop, no console-scraping (clad check --json).
• An honest stop — the loop ends on the gate, not the AI's word. A feature turns done only when the strict gate is GREEN, and reverts if it isn't. "The AI says it's finished" becomes "the gate let it stand."
• A memory across passes — a local log (.cladding/events.log.jsonl) remembers the last pass's checks, tries, and drift, so the next one doesn't start blind.

Project graph — see it and ask it

This is cladding's internal graph of your project — spec · code · tests · docs, all connected. Now you can see it and ask it.

Why it matters — docs and code don't drift apart. Docs lie as time passes: the code changes, the description doesn't. cladding re-checks that link every time it reads the code, and blocks "done" while the two are out of sync.

_{Blue = spec (center) · orange = code · green = tests · pink = docs; the more a node connects, the larger it grows and the more it pulls toward the center.}

• See — run clad graph serve and the whole project opens in your browser; what connects to what, at a glance.
• Ask — "what breaks if I change this?" The graph answers with the affected code and the tests to run — it doesn't guess.
• Measure — the bigger the project, the more it saves: a median 4× less to read when fixing something (clad measure · how it's measured).

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

_{Requires cladding 0.7.0+.}

Under the hood

Spec → Code → Tests as one cycle — the spec records the why, the gate verifies, the detectors block drift.

Spec — the project's long-term memory. An LLM forgets everything between sessions, so the spec is where the project's intent lives: durable, versioned in git, and fed to the model before it starts. It holds the why and the what; the design tier just below holds the how. (It's the memory of intent, not a log of what happened.) Four tiers, top to bottom: intent (A) — sealed until a human signs off — then design (B), code + attestation (C), and audit (D). A outranks all — if the spec and the code ever disagree, the code is the one that's wrong.

Each feature is its own sharded file with an 8-char hash ID, so two devs adding features at once never collide. A feature reads like this — the what, written as a testable acceptance criterion:

# spec/features/checkout-a1b2c3d4.yaml
id: F-a1b2c3d4
slug: checkout-idempotency
status: done
acceptance_criteria:
  - id: AC-9f3e21a0
    text: "When a charge is retried with the same idempotency key, the system
            shall return the original result and never double-charge."
    test_refs: ["tests/checkout/idempotency.test.ts#retry returns the original charge"]

_{EARS keeps every criterion testable — WHEN <trigger> … the system SHALL <response>, the shape of the text: field above.}

→ 4-tier model · hash-based IDs

Gate — the 15-stage Iron Law. One check engine, bundled by cost — 3 run at commit, 9 at push/completion, all 15 in CI:

• Static (6) — Type · Lint · Drift · Commit-clean · Architecture · Secrets
• Test & conformance (4) — Unit · Coverage · Spec-conformance (the impl-blind grader) · Deliverable smoke (blocks the empty green: tests pass but the deliverable never runs)
• End-to-end (3) — Smoke · Performance · Visual
• Evidence (2) — Audit (every acceptance criterion has evidence) · UAT (every done feature has evidence)

→ the 15 stages

Detectors — 41 drift detectors. They catch every direction spec · code · test can diverge:

Direction	Catches	#
spec ↔ code	in the spec but missing from code, or code that strays from it	10
code ↔ test	code with no test · coverage drop · leaked secrets	6
spec ↔ test	an acceptance criterion no test verifies · false status	6
spec hygiene	the spec's own integrity — id collisions · dependency cycles	8
environment	build environment · meta files	3
verification freshness	code changed since its verify signature	1
governance · docs	policy violations · doc drift · claims beyond the evidence	4
graph · doc links	broken doc ↔ spec links · missing dependency edges	3

The graph these power is that long-term memory made queryable — traceability / retrieval, not a correctness claim: what connects to what and what to re-check, not that the code is right. → full detector catalog

One feature's lifecycle runs Define → Sync → Implement → Earn — you earn done only by passing every check.

Multi-Agent — separating the builder from the verifier

The agents that build are kept apart from the agents that verify, so no agent signs off on its own work. blind-author goes one step further: the agent that writes the tests literally can't read the code (it's given no Read/Grep tool). So "wrote the tests without looking at the code" is a fact about how it's wired, not a promise. It's the same separation of duties that audit rules like the EU AI Act and SOX ask for — in spirit, not a certification.

Ecosystem

cladding sits at the junction of three existing categories.

• Spec Kit · OpenSpec · Tessl · Kiro help you write a good spec. cladding adds the part that keeps cross-checking, inside the dev loop, that the spec and the code haven't drifted.
• BMAD · ChatDev · Claude Code Agent Teams split roles across AI agents. cladding's division of labor runs with spec · gate · audit record on top.
• tdd-guard forces the AI to write tests first. cladding's Unit · Coverage · oracle stages do the same job, more structurally.
• OpenHands · Cline · Aider · Goose are runners that make the AI write code. cladding is the upper layer that verifies and governs what they produce.

The distinction is the combination — binding those cores into one verification loop.

Install

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

_{Each host wires cladding as an MCP server the AI calls on its own — there's no /mcp command and no manual connect step; you just chat.}

Then, once per project, call init inside your AI tool:

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

It creates the project's spec.yaml and supporting docs. After that, just develop as usual — cladding runs the before/after loop in the background, with nothing to memorize. Raise enforcement with clad init --with-hook (pre-commit + pre-push git hooks) or clad init --with-ci (scaffold the CI gate, where true enforcement lives).

Starting point	Command	What happens
An idea, nothing else	/cladding:init "I'm going to build a B2B payment SaaS"	the LLM analyzes the domain → spec · docs · policies + 2–3 follow-up questions
A planning doc	/cladding:init docs/plan.md	loads the file and uses its contents as intent
An existing project	/cladding:init "apply cladding to this project"	scans the existing code → observed patterns merged with your intent

Host support (honest): Claude Code is fully verified through real-usage campaigns (incl. real-time intervention). Codex · Gemini CLI wire automatically; their behavior isn't verified yet. Cursor wires automatically, but real-usage verification is still pending. → setup details · host wiring · MCP · upgrading

Update

Staying current is two commands — or one line to your AI tool.

npm update -g cladding   # 1. get the new version
clad update              # 2. once per project — bring it in line

Your code · spec.yaml · docs are left untouched — a stricter version only points things out, it never blocks or fixes on its own. If those two commands flag fresh drift, hand it to your AI tool:

[inside your AI tool] reconcile the drift the update flagged

…or skip the commands and just ask, the same way you ran init — it runs the update for you:

[inside your AI tool] update cladding to the latest version

Status

Version	Conformance	Tests	Gate	Features
v0.8.3 (2026-07)	L4 · self-declared	2497 / 2497	15 stages · 41 detectors	254 (251 done)

_{234 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)
• A/B & real-usage evidence
• 4-tier governance model
• The 15 gate stages
• Hash-based feature IDs
• 41 detector catalog
• Setup · host wiring · upgrading
• Glossary (EN · KO)
• Governance · roadmap to 1.0

License

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