What is Cliewen?

Cliewen is a methodology and command-line tool for teams that build software with coding agents. It keeps intent, implementation, and evidence connected. Its name comes from the Old English word for a ball of thread, which became clue.

The central idea is simple: the durable documentation describes the system as it exists, not a pile of past change requests. A goal leads to a capability, a capability owns acceptance criteria, and each active criterion reaches its declared acceptance evidence. Machine-proven criteria use supported, classified test references; genuine Human-class criteria use the pull request acceptance brief. The clue command checks that this thread is intact.

That diagram is the core of the product. The rest of this guide explains how to keep those links intact while an agent works quickly.

Evidence-backed Intent Engineering

That phrase is Cliewen's own description of its approach, not an established industry label, so here is exactly what it means:

1. Human intent is recorded as durable goals, capabilities, decisions, constraints, and acceptance criteria.
2. Every active acceptance criterion declares the evidence by which it is accepted.
3. That evidence is either a classified executable test reference or explicitly identified human verification.
4. Tooling checks mechanically that the chain from intent to evidence is complete.
5. A human decides whether a full change is accepted and merged.

The important word is backed. Cliewen makes the connection between intent and acceptance evidence explicit, reviewable, and mechanically checkable. It does not prove that your software fulfills its intent. clue validates structure, links, declarations, and supported evidence references, but it does not execute tests, decide whether a test checks the right behavior, or know whether the intent was right. Review and the human at the merge gate make that semantic decision. The design of Cliewen explains the boundary in detail.

Why another workflow?

Coding agents can produce changes faster than people can review them. That moves the bottleneck from writing code to deciding whether a change is correct and safe to merge. A patch can look convincing while missing why the system exists, updating a specification without its tests, leaving a decision in chat, or changing the meaning of an acceptance criterion.

Cliewen first recommends simple work when the accepted contract remains intact and the full loop when it changes; the user chooses, and repository policy controls integration. Inside a chosen full loop it separates mechanical checks from human judgment:

• The corpus under /docs is the system of record.
• A branch is a proposal, and the pull request is the authorization boundary: the agent may publish a full candidate but cannot accept that full change into main.
• A full change keeps its working delta in /changes/CH-xxx-*; the digest deletes that workspace before merge.
• The clue CLI checks structure, links, and acceptance-evidence traceability without executing tests.
• A human controls full-loop acceptance by merging; this safeguard does not require repeating a code review already completed locally. Simple integration instead requires explicit user authority and repository permission.

The pull request is also where hosted CI becomes enforceable when the repository requires its status check and protects main. A pull request without a required check and branch protection only displays CI; the combination is what prevents an agent from silently skipping the gate.

Born from Intent Engineering and spec-driven development

Cliewen builds on Intent Engineering for Coding Agents by Cliewen's author, Flemming N. Larsen. That approach records human intent before an agent implements it and keeps the shared context under version control. Cliewen adds the evidence-backed part: intent lives in durable documentation, and clue checks the links that discipline alone can miss.

The book's working spec-driven-development example is OpenSpec. It proposes a change-sized spec, applies it, and archives it afterwards. Cliewen keeps a proposal layer for full work, but not an archive: before merge, the transient /changes workspace is digested into /docs and deleted. The supported merge commit keeps the accepted branch history in the repository. The pull request authorizes a full-loop merge but is not the system of record, so squash and rebase-and-merge are outside the full-change support boundary. In Cliewen, the documentation is the specification and every integration must leave it true, whether the recommended route was simple or full. A repository using the book's extended OpenSpec format can be adopted with its IDs and test traceability intact; see Greenfield and brownfield.

Decisions inside a full loop follow the same rhythm. A future-shaping choice routes by subject to ADR, PDR, or IDR. A decision an agent records is born inferred; merging the pull request makes it binding, and later explicit human approval promotes it to verified. A user who declines the full recommendation chooses simple process for that integration; the agent records the override risk in Git history rather than manufacturing a corpus decision.

This avoids two common failures of change-centered specifications: an archive of stale proposals that readers must reconstruct, and a permanent specification that only appears connected to executable evidence.

What Cliewen is not

Cliewen is not an issue tracker, a project-management service, or a way to remove humans from engineering decisions. It is also not a replacement for test runners: clue validates references but does not execute tests.

The exact evidence rules — the reference your agent needs, not your first read

Canonical criterion IDs use <PREFIX>-<digits>[lowercase-suffix], so brownfield identities such as SNAP-SQS-001 and ADP-045b remain stable; Go/JVM named forms remove prefix hyphens and literal JVM/Cucumber tags may use underscores as documented aliases. A new or revised machine-proven criterion declares its proof type and needs classified positive and negative evidence through supported Go test names, per-executable Java/Kotlin JUnit method tags or the stable JVM test-name form, or Cucumber scenario tags, unless it explicitly records (single-direction). JVM metadata split across methods or inherited from a class receives no evidence credit. An unannotated legacy criterion keeps the one-supported-reference rule. A genuine Test-type: Human criterion is proven by its acceptance-brief line without fake code evidence, while @draft exempts only one not-yet-proven criterion inside an otherwise active file.

Next

See what you can actually do with it.