Operate Cliewen safely
This page is for a repository that has completed the disposable trial and is deciding whether to keep Cliewen. It defines the current support boundary and recovery paths that preserve repository history and the review boundary.
What Cliewen ships and checks
| Surface | Current support |
|---|---|
clue | Versioned release binaries for Windows, macOS, and Linux on amd64 and arm64; source installs are also available through Go |
| Test evidence | Classified Go test names such as TestAC001_UnitPositive_… or normalized TestSNAPSQS001_UnitPositive_…; Java and Kotlin executables whose own JUnit method annotations carry @Tag("AC_001") @Tag("UNIT") @Tag("POSITIVE") or @Tag("SNAP_SQS_001"), or whose stable name is testAC001_UnitPositive_… or testSNAPSQS001_UnitPositive_…; and Cucumber scenario tags such as @AC-001 @e2e @positive or @SNAP-SQS-001 @unit @positive |
| Agent guidance | Six generated Cliewen skills in .agents/skills/, mirrored to .claude/skills/ for Claude Code |
| Session-start discovery | You are told you are behind without asking: the clue workflow commands — init, scaffold, context, migrate, id, refs, and report — print one line to standard error when a newer release exists, and the AGENTS.md that clue init materializes also asks the agent to run clue latest --quiet before its first tool call, for sessions that run no clue command. Never clue validate or clue version, never with a non-empty CI, and never with CLUE_NO_UPDATE_NOTIFIER present at any value; standard output and the exit code never move. Cliewen emits no configuration for any assistant; the hub is the cross-agent file, and it is yours — clue init never overwrites it and clue migrate never rewrites it. |
| GitHub CI | clue init writes a thin caller for Cliewen's upstream reusable workflow; choose the runner and binary source, then require its exact validate check |
| Full-change merge | Human-controlled merge commits only; disable squash and rebase-and-merge so the proposal, implementation, digest, and durable corpus commits remain reachable from main |
| Validation | clue validate checks the repository-local corpus, including activated architecture and design overviews, generated indexes, skill ownership/version drift, and active-criterion evidence declarations and references; --forbid-changes also rejects an undigested /changes/ workspace. It also checks that a reference pointing outside the repository names what it points at: a bare forge number such as #42 fails, because it silently means "this repository" and is wrong the moment it does not. Citations inside the repository are untouched. |
| Focused context | clue context <id> prints the named artifact and its outgoing-link dependencies out to a stated depth, naming what the bound held back; --depth widens it and criterion and milestone IDs resolve to their declaring artifact |
| Release check | clue latest reports whether a newer clue release exists and how to install it on the machine it is running on. It reaches the network, so it is never part of a validation verdict and must never be a required check; it writes no file in your repository and never replaces the binary. Being unable to tell — offline, a timeout, a rate limit — is reported calmly and exits 0. |
| External addresses | clue refs resolves what the corpus points at and reports each as reachable, restricted, redirected, gone, or unreachable. Only a gone address is an error; a private target and an outage are normal answers, never failures. --apply rewrites redirected addresses, leaving completed plans alone because their addresses record what was observed. Keep it out of branch protection: another host's uptime must not gate a merge. |
Cliewen does not run your tests, synchronize tickets or wikis, or validate evidence across repositories. It does not update installed files in the background. It harvests only the supported Go, JVM, and Cucumber conventions above. On the JVM, all three parts belong to the same executable. Class tags and metadata split across methods do not count, and ambiguous or unsupported source syntax is diagnosed instead of guessed. A different framework needs the stable JVM named-executable form or another supported profile before its references can satisfy clue validate; an arbitrary comment or tag is not equivalent evidence.
A new or revised machine-proven criterion declares Test-type: Unit, Integration, E2E, or Performance, and the validator requires supported evidence classified with that type in positive and negative directions; (single-direction) is the explicit narrow exception. An unannotated legacy criterion retains its one-supported-reference rule. Test-type: Human uses the pull request acceptance brief rather than code evidence, and @draft exempts only the individual criterion that is not yet proven.
Preserve the full-change archive
For a full Cliewen change, configure the protected default branch to allow the hosting provider's merge commit mode and disable squash and merge and rebase and merge. A merge commit keeps the exact proposal, implementation, digest, and durable-corpus commits reachable from main. Squash and rebase-and-merge can produce the same final tree while discarding or rewriting the reviewed branch chain. A change branch is published from its first commit, so hosted history is never rebased or rewritten and human acceptance remains a merge commit.
Because merge shape is configured per branch or repository rather than per pull request, a default branch restricted this way applies the same shape to simple PRs. Repository owners choose that tradeoff and may integrate simple work by another permitted mechanism. Before adoption, run the CI wall's branch-protection probe and verify the settings. A forge that cannot enforce merge commits is outside Cliewen's supported full-change adoption path, not outside simple work or Cliewen ownership.
Upgrade one coordinated set
Start an upgrade by checking whether one exists. clue version tells you what is installed, but not whether it is current. clue latest checks the release list; immediately afterwards, always preview clue migrate without --apply, even when clue latest says the installed release is newest or cannot reach the release list. The first check asks whether a newer CLI is published, while the second checks whether this repository's managed carriers match the installed binary. A clean preview proves that the local carriers match the installed binary. The repository may be called current only when the release list was reachable and reported no newer release too. If the release list is unavailable and the preview is clean, report that release freshness is unknown and stop; do not ask for an upgrade with no known target. clue latest never installs anything, and the migration preview never writes, so the upgrade remains a reviewed change. If it cannot reach the release list, it says so and exits 0. --quiet prints one line only when you are behind; the answer is cached for a day. A direct clue latest call asks again even after a previous failed check, so it notices when your network recovers.
You and your agent do not have to remember to ask. The ordinary workflow commands — clue init, scaffold, context, migrate, id, refs, and report — print the same one-line notice to standard error when a newer release exists. The notice never goes to standard output or changes an exit code. Failed checks, such as an offline, timed-out, rate-limited, or unrecognized reply, are cached for an hour so repeated work does not wait for the same non-answer.
The notice appears in deliberately few places. Never from clue validate, whose output stays a statement about the repository, or from clue version, which is instant and offline. It also never runs when CI has a value, so runners do not make the request; CI= does not count. Set CLUE_NO_UPDATE_NOTIFIER, including to an empty value, when you want the tool to say only what it was asked.
The notice does not require a terminal. Coding agents often read command output through a pipe, so terminal-only output would not reach them. The values scripts consume stay fixed: standard output and the exit code are byte-identical with or without the notice. If you also capture standard error and need it clean, set CLUE_NO_UPDATE_NOTIFIER.
The AGENTS.md that clue init creates also tells the agent to run the quiet check before its first tool call and route a non-empty answer to clue-upgrade. That covers sessions where no clue command runs, such as a question or review. Cliewen ships no hook or settings file for an assistant. If you want a deterministic session-start check, configure clue latest --quiet in your own assistant; it is silent when current or offline and always exits 0.
One case cannot announce itself: a clue binary that predates the release check has neither a notice nor a latest command. If you see unknown command "latest", the binary is behind. One upgrade resolves it.
If you onboarded before this shipped, clue migrate reports a hub that never asks — run clue init if you have no hub at all, or add the line yourself to the one you wrote. It repairs neither, because your hub is your prose.
Keep the binary, generated skills, and CI caller on the same release when you upgrade. First make the current repository green and branch through its normal review process. An upgrade is simple work: the release's contract changes were argued and accepted upstream before it was published, so your repository's own accepted contract is unchanged and the upgrade owes no change identity, workspace, digest, or acceptance brief — run the checks its changed surfaces need and integrate it the way your repository integrates anything else. The one thing that escalates is a decision of your own the release forces on you: an obligation you must choose how to meet, or a reconciliation that changes what your criteria or your wall promise. Route that decision as a full change on its own terms; the version move around it stays simple. Then choose the release in the release list, verify the new platform binary against that release's SHA256SUMS, and confirm clue version prints the chosen version.
If migration adds or reports an unactivated architecture or design overview, have the agent draft the short system view from the code and current documentation. When an existing overview belongs elsewhere, review one proposed move and link-rewrite mapping before approving it; declining the move keeps the source and leaves a concise canonical pointer.
clue init is deliberately non-destructive: it skips existing files, so it is not an updater. Preview the coordinated upgrade with clue migrate; when the plan reports only deterministic work, apply it with clue migrate --apply --reversal-cost=low|high, choosing the routing class for the repository's previously inferred meaning. The command updates the corpus fields it can prove, the six Cliewen-owned generated skill directories and their .claude/skills mirror when present, and the thin caller's upstream uses reference and clue-version together. When a release introduces a whole skill directory, migration adds its canonical .agents/skills copy only if every remaining managed carrier exactly identifies a supported preceding release; the preview names that release and the target release whose bytes it writes. It leaves unrelated third-party skills, runner labels, clue-source, and clue-install-directory unchanged. If your repository has no caller at all — the usual case when you adopted before it shipped — the migration creates it at the template's default runner, clue-source, and clue-install-directory choices, so you adjust those once rather than writing the file yourself. If a job in one of your own workflows still runs the installed binary's clue validate beside it, that is reported with the file and job name and blocks the plan until you remove or reconcile it: two walls judge the same pull request under different rules, and the older one fails work the caller was configured to treat leniently. Migration never rewrites a workflow it did not write, so the resolution is yours; a source build such as go run ./cmd/clue validate is not a competing wall and is not reported. A missing semantic choice, unsupported old release, copied workflow, or locally edited generated file is reported without partial writes; resolve it in the repository's reviewed change and rerun the preview. The preview also lists every external reference that names no repository — a bare #42 — with its file and line, and repairs none of them: nothing in the file says which repository was meant, so a mechanical guess would make a wrong reference look deliberate. Those are yours to resolve, and clue validate fails until you do. Keep the existing required validate check in place throughout the upgrade; the stable job name lets the same required check verify this pull request. Make it required only when you arm the wall for the first time.
If a released binary reports skill drift, do not edit a version number to silence it. The message names both ways out: move forward — clue latest for the recipe, then clue migrate for the repository — or stay where you are, which is both halves: install the released binary matching the skills your repository carries, and pin the caller with clue-version=<x.y.z>. Either way, run clue validate afterwards. A checkout build reports dev and cannot detect binary-to-skill release drift, so use a released binary for this check.
Re-running the install script moves the binary and nothing else. In a repository already using Cliewen that produces exactly the drift report above, because the skills are committed repository files no installer can update: the machine moved ahead of the repository. This is the check working, not a broken upgrade. Resolve it by completing the coordinated set — skills, the caller reference, and either the vendored assets or its release-source version — in a normal reviewed change, or by pinning the release the repository still carries with clue-version=<x.y.z> if you are not ready to upgrade it yet.
Recover without bypassing the evidence
| Situation | Safe response |
|---|---|
clue init reports a skipped file | Read the skipped path and keep its local prose. Add the missing scaffolded structure or marked index block deliberately; rerunning init will not replace it for you. |
clue validate fails | Run it from the repository root, read the named file and rule, and repair the corpus or evidence on a branch. Run your normal test runner too: clue does not execute tests. Do not delete a rule, use an untracked copy, or bypass CI to obtain green. |
| CI rejects a transient workspace | Finish the change's tasks, digest its durable documentation into docs/, remove /changes/CH-xxx-*, and rerun clue validate --forbid-changes. |
| Extraction is still unmerged | Close the pull request and delete its branch. The target repository was not changed by the extraction workflow. |
| An accepted extraction or adoption must be undone | Create a new reviewed change that restores the previous repository state or retires the incorrect intent, then validate it. Do not force-push or leave two competing systems of record. |
| You no longer want the local tool | Remove the installed clue binary from the directory you added to your user PATH. This does not alter existing repositories; remove or retire their Cliewen files only through their normal reviewed change process. |
Evidence from other repositories
Cliewen's hyperfine and es-toolkit work were read-and-apply foreign-soil trials, not adoptions. They produced findings without branches, pull requests, or tracked changes in those repositories. They are useful evidence about methodology boundaries, not proof that those projects use or endorse Cliewen.
When your repository's ownership, test evidence, or merge boundary cannot meet these conditions, keep the existing lightweight notes and tests instead of forcing an adoption.