The design of Cliewen
Other guide pages explain Cliewen's rules. This page explains why those rules exist: the problem the design addresses, the parts that cannot change casually, and the limits the methodology accepts. If you are comparing Cliewen with another approach, this is the argument to evaluate.
The problem: acceptance is the new bottleneck
For most of software's history, writing a change cost more than accepting it. Review could afford to be informal because production was slow enough to keep up with.
Coding agents invert that. An agent can produce a plausible, well-tested, politely documented change faster than a person can decide whether it is correct. Plausible is the danger. Agent output can look careful, so ordinary review heuristics such as "is it tested?" and "is it tidy?" still pass. Those heuristics measure effort, and an agent's effort is cheap.
The scarce resource is now justified acceptance: the ability to say, with evidence, this change does what we intended, and we can still explain why the system looks the way it does. Cliewen treats acceptance as engineering work. It gives it structure, evidence requirements, and machine support instead of relying on a review ritual that can become rubber-stamping.
Everything in the methodology follows from that one move.
Learned, not invented
Cliewen is a second iteration, and that matters for how much to trust its rules.
The first iteration is Intent Engineering for Coding Agents: write the intent down before an agent implements it, keep the shared ground between human and agent in the repository, and practice it by extending a spec-driven tool with local instructions, scripts, and generated files. Its author practiced that method on real systems under delivery pressure, and running it exposed a set of failures that no amount of better discipline fixed:
- Completed changes never reached the documentation. The spec tool reconciled its own spec tree and nothing else. Change-scoped design lived inside each change, while durable architecture, design, and decision documents were updated only when someone remembered to ask. The documentation drifted from the system it described, which was the failure the method was meant to prevent. This is not a quirk of one tool. Spec-driven frameworks usually model the change, not the system, so their durable system description sits outside the loop. When a tool cannot express the central obligation that every change leaves documentation true, extensions stop being enough. The second iteration encoded that obligation directly.
- Finishing steps were skipped. Archiving a completed change was a manual ritual; changes sat unarchived indefinitely because nothing blocked a merge without it.
- Generated report files poisoned pull requests. A generated coverage registry meant large diffs, merge conflicts, and regeneration discipline — real friction attached to every change.
- Hand-maintained index files went stale, silently, because nothing checked them.
- Decisions were made but never recorded. Not an agent quirk — nobody thinks in decisions while working. A developer makes the choice and moves on; an agent leaves the reasoning in chat; and when the only recognized record was a human-authored, human-accepted document, most decisions simply never became one. The choices shaped the system; the paper trail did not exist.
- Decision ceremony was all-or-nothing. When every decision required a fully approved record, small decisions were either over-formalized or — more often — not recorded at all.
- Splitting an overgrown spec was a dreaded manual operation, so specs grew past the point where anyone could review a change against them.
- Humans paid for every review iteration. The agent produced a change, a human reviewed it, sent it back with findings, and reviewed it again — and again. The person was the iteration loop, spending their scarcest resource on rounds an agent could have run against itself first.
- The method itself was expensive to acquire. Practicing it meant reading a book and then hand-assembling local instructions, scripts, and conventions in every repository — and writing instructions good enough that an agent reliably follows them turned out to be much harder than anticipated. The method lived in prose and in people's heads, not in anything installable.
The lesson is simple: a ritual that depends on someone remembering or being willing will eventually be skipped. Not just by careless engineers. People forget, and they may not want to write a design or decision record even when they agree it matters. Cliewen makes two repairs. First, the agent maintains records, structure, and the digest as part of every change. Second, work that cannot be delegated becomes a merge gate. It is enforced rather than remembered.
That is why the digest happens inside the change, an undigested workspace fails validation, and indexes are generated. It is why decisions are typed artifacts, one capability owns one criteria file and ID prefix, and generated reports are not committed. An index belongs in a README a person wrote; a coverage registry can be derived from the corpus when needed. It is also why the method ships as a product rather than as a book: versioned skills teach the workflow and one small binary judges it. Each rule below replaces a ritual that had been observed failing.
One of those repairs is the standard the whole methodology accepts for itself: keeping the durable documentation true is the workflow's job, performed inside every change — never a chore a human occasionally remembers to assign. If the documentation can drift while every change follows the method, the method has failed at the one thing it exists to do.
The core: three elements and a red line
Cliewen is organized like a kernel: a small core whose meaning is protected, surrounded by periphery that exists to serve it and may change cheaply.
The verifiable thread. Goal → plan → change → capability → acceptance criterion → acceptance evidence. Every durable claim about the system traces to its declared proof: supported, classified executable evidence for machine-proven criteria or the pull request acceptance brief for genuine Human-class criteria. Every evidence carrier traces back to a reason. This is the thread the project is named for: a cliewen is the Old English ball of thread that became the word clue — the red thread you pick up at any artifact and follow back to answer why do we have this in our system? That question having a mechanical answer is what makes the documentation a system of record instead of well-intentioned prose — and "the agent decided" is never the answer.
The human acceptance boundary. When the user chooses the full loop, the agent never accepts its own change: a human-controlled merge is the acceptance act. Cliewen recommends that boundary for accepted-contract change but does not acquire authority over the repository. The user may choose simple work and integration follows explicit user authorization plus repository permission. Agents advise and do the work; humans own the truth and the repository.
The deterministic judge. clue validate is a small, stateless binary that checks the corpus's form: required fields, unique IDs, resolvable links, and the declared acceptance-evidence contract for every active criterion. It classifies supported Go, per-executable JVM, and Cucumber references, recognizes that a Human declaration requires no code reference, recognizes per-criterion @draft, and does not execute tests or inspect the pull request acceptance brief. The same binary runs locally and in CI, and branch protection makes it a wall. Because it is deterministic and boring, "the corpus is well-formed" is a fact rather than an opinion — and, just as important, everyone knows exactly what it does not check.
Remove any one element and the other two stop meaning anything: evidence without a thread is trivia, a thread without the merge boundary is unaccepted, and both without the judge are unenforced. That is why these three sit behind a red line: a change that alters what the thread connects, what a merge accepts, or what a green validate asserts always requires an explicit decision record and human acceptance. It never rides silently inside another change. Everything outside the core — guide prose, scaffold templates, skill wording, index generation — is periphery, changed at ordinary cost.
The principles, and why each one
Machines enforce form; humans verify meaning. The judge checks that every active criterion satisfies its declared evidence shape: classified positive/negative references at a machine proof type, an explicit single-direction exception, a Human declaration that waives code evidence and routes proof to the acceptance brief, an individual @draft, or the legacy one-reference rule. It does not check that a test establishes the right thing or that the brief contains the promised Human proof — those are review and human-merge responsibilities. Pretending a tool can verify meaning is how verification theater starts. Cliewen draws the line explicitly instead of letting it blur: everything mechanical is automated without apology, and what remains for the human is small, named, and genuinely theirs. The alternative — tools that claim to check semantics — produces reviewers who trust the green checkmark precisely where it is weakest.
The documentation is the spec, and the digest keeps it true. Change-centered workflows accumulate an archive of past proposals; to learn what the system does now, you reconstruct it from history. Cliewen inverts this: durable truth lives in /docs, describing the system as it exists. A full change works in a transient /changes workspace, and before merge that workspace is digested — its meaning folded into the durable corpus, the workspace deleted. Git keeps the proposal history; the corpus keeps only the present tense. Two systems of record is zero systems of record, so one of them has to die at the boundary, and it is always the transient one. Note what the digest does not do: it does not remove the finishing work — it moves that work before review and broadens it beyond behavior specs. What it removes is the ritual you could forget, because a change whose workspace survives cannot merge.
Decisions are routed by reversal cost. Not by importance, not by how wide a rule reaches — by what it would cost to undo. A cheap-to-reverse decision is one dated row in a log table. An expensive one gets a full record with context and rejected alternatives — split by subject into architecture decisions and decisions about how the project works, so each kind is found where a reader would look for it. This keeps the ceremony proportional to the stakes: the corpus does not fill with solemn documents about naming conventions, and the decisions that genuinely constrain the future are the ones with the paper trail. It is the direct repair of the all-or-nothing ceremony that the first iteration showed drives small decisions out of the record entirely.
Agent decisions are born inferred; merge binds, approval signs. An agent working a change makes real decisions, and hiding them in chat loses them. So Cliewen records them — marked inferred, meaning no human has endorsed the reasoning yet. Merging the pull request makes them binding: the project now lives by them. A later explicit human approval promotes them to verified. Separating the two keeps shipping unblocked without faking endorsement, and the CLI reports those decisions as their own signature backlog. Extracted non-decision meaning declares whether reversing it is cheap or expensive; cheap findings may remain inferred, but expensive inferred meaning cannot sit in an active capability's immediate graph slice.
Reality gets one repository-local edge back. When later evidence shows that a green corpus described the wrong capability or criterion, an incident analysis marks that contradiction and links the failed claim alongside the carriers that failed to prevent it. The CLI derives the affected-capability list from those edges. It does not ingest telemetry or operate production; that larger feedback loop remains deliberately outside the current system.
Acceptance criteria are meaning-immutable. Evidence tagged AC-042, SNAP-SQS-001, or ADP-045b must mean the same promise years later. When a criterion's meaning changes, the old ID is retired as a tombstone and a new ID is minted; a test still pointing at the retired ID fails loudly. Without this rule, IDs silently drift and the thread's edges stop meaning anything — traceability that permits redefinition is not traceability.
Full-loop work is challenged before a human sees it. Before a full change may become a ready pull request, it is reviewed in a fresh context where the coding agent supports that isolation. Blocking repairs invalidate the pass; advisories are carried forward. The bounded loop ends on a pass without blocking findings or reports its remaining findings for human direction. This cost belongs to the full recommendation rather than every repository edit.
Full changes branch from accepted main, one at a time per author. Each initiating author takes one full change to its pull request before starting the next; a sibling merge is incorporated and checks repeat without rewriting hosted history. Simple integration follows user authority and repository policy and consumes no full-change slot.
The reason is that Git merges text and not meaning: two large parallel changes can both be textually mergeable and semantically incompatible, and no tool will notice. Cliewen has no rule about how small a change must be, because no reader can determine whether a delta was small enough — a rule nobody can check is worse than none. What it has instead are the structural rules above, and they are what make a collision visible at the gate rather than after it. Team parallelism stays unlimited: the per-author limit does not prevent two authors from colliding, and reconcile-and-recheck is what catches it. The constraint is a cost, and it is paid deliberately — a merge boundary that humans cannot keep up with is not a boundary.
Process is recommended by accepted-contract impact. Simple work leaves the contract intact and carries no loop bookkeeping; full work changes criteria, capabilities, decisions, policy, plan promises, methodology, or uncovered behavior. The agent explains its recommendation before editing, reassesses on discovery and before integration, and never uses diff size or path as the semantic verdict. If the user rejects full, the agent proceeds as directed and records the override risk in Git history. Release remains repository-owned rather than a Cliewen route.
The full loop spends more tokens and time than simple work: it maintains durable meaning, verifies evidence, challenges the candidate, and exposes acceptance to a human. That cost is why routing is a recommendation tied to contract change rather than a universal tax. The user decides whether the additional provenance and acceptance boundary are worth paying for this integration.
How adopters extend it
The core deliberately does not enumerate what a corpus may contain.
Your corpus is yours: adopter-defined artifact types validate against the same form rules as everything else — core frontmatter, unique IDs, resolvable links, a default status lifecycle — without needing Cliewen's permission to exist. Your rules enter as constraints, each naming its source and whether a machine, an agent, or a human enforces it; a compliance rule, a coverage floor, and a license boundary all live in the same register and are assessed against every change. Repository-local conventions extend the methodology in AGENTS.md; they may add to the rules but never override them, and a conflict stops the change for a human decision instead of being resolved silently.
What you cannot do is redefine a chosen full loop and still call that loop Cliewen: a thread that skips evidence, an agent that accepts its own full change, or a judge whose verdict depends on where it runs are not extensions. Choosing simple instead is explicit user authority, not a weakened full loop.
What Cliewen does not solve
Stating limits plainly is part of the design — a methodology that overclaims trains its users to stop reading the claims.
A green corpus can still describe the wrong product. The thread runs from goal to acceptance evidence and stops at merge. If the goal itself is mistaken, or the shipped behavior disappoints users in ways no criterion anticipated, nothing turns red. Cliewen keeps intent and evidence connected; it does not validate the intent against reality. Production feedback is a deliberately closed door today: findings from operation re-enter the corpus as new goals or constraints through the ordinary loop, not through an automated pipeline.
The judge checks form, not semantic alignment. clue validate proves that AC-042 has the references its declared machine proof type requires, or that it explicitly declares the Human route or marks the criterion @draft. It cannot prove executable evidence asserts what the scenario states, inspect whether the acceptance brief supplies Human proof, or decide that a Human-class scenario is true. Those comparisons belong to the review loop and the human at the merge gate, and Cliewen's honesty about this split is the reason the green checkmark stays trustworthy.
Evidence harvesting has edges. The judge reads test evidence from the conventions it supports — classified Go test names, literal JUnit tags attached to one Java or Kotlin executable or the stable JVM named-executable fallback, and Cucumber scenario tags — and other frameworks need a supported profile before their references count. The JVM scanner is deliberately conservative: it recognizes ordinary, parameterized, repeated, factory, template, and nested executable declarations, credits each method once, ignores proximity comments, and diagnoses ambiguous, class-level, or unsupported evidence syntax instead of compiling source or guessing runner discovery. A project rule whose verification is inherently human — a cap on onboarding time, say — lives as a constraint with enforcement: human; a genuine Human-class acceptance criterion declares Test-type: Human and uses its acceptance-brief line as proof. A criterion that is merely not proven yet uses @draft on its own tag line without drafting the entire capability.
The human's half of the merge gate is written, but it is not automated. A full-change PR begins with a concise acceptance brief: the plan item and whether it remains wanted, the changed criteria and scenarios, advisory test-to-scenario verdicts, every newly or materially declared Human-class criterion whose brief line is its proof, and what merge binds. The validator does not pretend these are semantic facts; a green build and a confident agent do not establish that the requested outcome is right. The brief gives the human the remaining semantic decision in one place, and its one-screen cap pushes oversized changes to split rather than hide meaning.
It does not remove humans, and it does not manage projects. Cliewen is not an issue tracker, not an orchestration layer for agent swarms, and not a way to make engineering decisions without engineers. It assumes ordinary Git discipline and real tests, and it concentrates human attention on the one act that cannot be delegated: accepting a change as true.