A deterministic process around a probabilistic model. Created by Ron Brazil.
Everyone says their AI workflow is deterministic. Almost none of them are. The model guesses, and that part never changes. What can be deterministic is everything around the model: the order work is done in, the record it leaves, and the checks it has to pass. CorvusWing makes that part deterministic, and that part is the one you can check.
CorvusWing is a small kit of skills and templates for Claude Code, and for every coding agent that
reads AGENTS.md (Codex, Cursor, Copilot, Gemini CLI, Aider and others). It gives your agents rails:
a written order before every task, a git safety net under every change, notes that carry the work
from one session to the next and across the automatic summary, checks that are proven able to fail,
and one page where you can see all of it and leave the agent a note.
If your agents have been rewriting code you never asked them to touch, spending money on work you had to throw away, and leaving you no further along than months ago: that is a common pattern, and it is not a verdict on you. It mostly comes from a few missing brakes. Each one is small. This kit installs them.
A written rule drifts. A checked rule holds. Release 1 wrote the rules down as skills. Release 2 adds scripts that refuse: when a rule is broken, the work stops and says why, in words. It also adds a fixed order for research, and new rooms on the bench.
The scripts that refuse. Four skills now come with a script that stops the work when their rule is
broken: two-strikes, test-freeze, decide-first and shell-guards. Each script ships with its own
self-test, so every refusal is proven to work.
The research step. For a piece nobody has designed yet, bake-off fixes the order. The test is sealed
first. A deliberately bad version must fail it. Each candidate writes its elimination line before it runs.
Side effects are listed, not failed. A person picks, never the builder.
The bench, new rooms. Questions, where a decision is one click and the answer comes back with the commit that holds it. The Work log, each day's work with its proof. Checks history, each check's last 20 results at a glance. Each room reads a file in your project: QUESTIONS.md (answers go to INBOX.md), WORKLOG.md, and the checks ledger, .gates.jsonl.
Seven steps, one for each letter. Each is done by a skill in this kit.
| Step | What it means | Done by |
|---|---|---|
| Plan | Start at "done" and work backwards to today; test the riskiest assumption first, with the cheapest probe that could prove it false. | start-here, decide-first |
| Record | What is true, what is next and why things are the way they are live in short files every session reads, never in anyone's memory. | session-close |
| Order | Every task gets a written order first: its files, a size budget, a done-criterion, a cancel condition, and its own git branch; the second failure in a row of the same check stops it. | scope-guard, two-strikes |
| Prove | "It works" means a check anyone can rerun, and every check is proven able to fail; a test is never weakened without a written reason, and a piece nobody has designed is compared on rules frozen before any candidate; a surprising number is traced back to its cause before anyone acts on it. | gates, solution-integrity, test-freeze, bake-off, trace-back |
| Hand off | A session ends, or is summarized to free up room, without losing what cannot be worked out again; the next one tests the note before trusting it. | compaction, context-guard |
| Evolve | A mistake becomes a rule the same day, with its reason, and a mistake that keeps coming back becomes a lock that refuses it; a "cannot" is checked before it closes a door. | holding-the-goal, working-discipline, shell-guards |
| Trust | Trust is earned by checking: every number on the bench comes from a file, and anything missing shows as missing. | bench |
None of this makes the model deterministic. It makes the process deterministic, and the process is the part you can check.
- Agents rewrite things nobody asked for.
scope-guardmakes every task name its files and a size budget before it starts, makes the agent stop and ask before going outside them, and gives you a ten-second way to reject an oversized change without reading it. - Work is hard to recover. Every task starts with a commit and its own branch (a branch is a separate line of work in git that you can merge or throw away). Every unattended run starts with a tag (a named bookmark on a commit). Undoing a bad run is one command.
- Sessions lose state.
session-closewrites down what is true, what is next and what was decided. The next session checks those notes against the repository before trusting them. - The automatic summary takes unwritten work. When a conversation fills up, it is summarized,
and whatever was not written down is now a guess.
context-guardwatches how full the session is and, well before that point, hascompactionwrite a note that carries the work across: sorted by what each fact costs if it comes back wrong, with orders already carried out kept apart from rules still in force, and ending in a list of facts each with the command that checks it. - No route to done.
start-herewrites a plan with you (PLAN.md): it starts at "done", works backwards to today, and puts the riskiest assumption first. Every task after that has a place on the route, so an agent is never just "working on stuff". - Building before thinking.
solution-integrity,holding-the-goalandworking-disciplineare question lists to run before and after a change: is the premise measured, what would cancel this task, is this "cannot" real. - "It works" cannot be checked.
gatesbuilds one command that runs every check, a ledger that remembers each run against the files it checked, a deliberate fault per check that proves it can fail, and a progress window for long runs. - Notes that grow until nobody reads them. Finished work moves, unchanged, into an
archive/folder, leaving one pointer line behind, so the notes every session reads stay small: under 400 KB together, with a warning at 300 KB. Nothing is trimmed or deleted; it is moved and pointed to. - You cannot see the project at a glance, or leave the agent a note.
benchstarts one local page: what is true now, what is next, the tasks open, upcoming and closed, the checks, the newest decisions, and a Message Claude box whose notes the agent reads at its next step. A desktop icon opens it with one click; its Stop button, or simply closing the page, shuts it down. - An agent loops on the same failure.
two-strikescounts each check's failures in a row in a ledger. The second failure in a row of the same check stops the step and asks for a report, instead of a third variation; put it in front of the command and it records every pass and failure itself. - A changed test quietly weakens the suite.
test-freezerefuses a commit that changes, skips or deletes an existing test, with or without code beside it, unless its message says why in aTEST-CHANGE:line. - A design gets built before anyone measured it.
decide-firstmakes the cancel line get written first, keeps the measurement, and refuses a record that picks a build after the cancel line was met. - A piece nobody has designed gets its tests bent to fit.
bake-offfixes the order: the rules as tests, a dumb control marked where it passes, candidates with kill lines, a scoreboard that lists changes instead of failing them, and a pick with a reason.
Start every request with this, then say what you want:
Prior to any decisions or code design I want you to run the whole skill holding-the-goal, and then invoke the appropriate portions of the next two skills that allow you to successfully complete the task (name the parts you use of these two skills): solution-integrity, working-discipline.
Then your request, for example: "Then: add a CSV export to the reports page."
The same sentence is written into AGENTS.md by start-here, so the agent follows it even on the day
you forget to paste it. Pasting it anyway costs nothing and makes it the first thing the agent reads.
In the reply, the agent should name the parts it used; if it does not, ask.
| Path | What it is |
|---|---|
skills/start-here/ |
First-run interview. Keeps your original work safe, asks about your project, then sets up the notes, the house rules (AGENTS.md, which most agent tools read, and CLAUDE.md, which imports it for Claude Code), the plan and git. |
skills/scope-guard/ |
The anti-rewrite rules: commit, branch, scope, size budget, review, roll back. |
skills/session-close/ |
Ends a session: commits, brings the notes current, archives what finished, keeps the notes small, then runs compaction. |
skills/compaction/ |
Writes PICKUP.md, the note that carries a session across a summary or to the next day, and makes the next session check it first. |
skills/context-guard/ |
Watches how full the session is; at about 85% it starts nothing new and has the note written before the automatic summary can come. |
skills/solution-integrity/ |
Twelve questions before, during and after a change. |
skills/holding-the-goal/ |
Questions to run before saying "cannot", and before saying "we should fix this". |
skills/trace-back/ |
Follows a surprising number back to its cause before anyone acts on it: reproduce it, rule out the test and the tool, reconcile, ask the system why, and turn what is not known into the plan. |
skills/working-discipline/ |
Habits for arriving in a codebase, reading, measuring, building and reporting. |
skills/gates/ |
Builds the check suite: one command, a ledger, a proof that each check can fail, and a progress window. One part per session, after start-here. |
skills/bench/ |
The bench: serve.mjs (a small server, Node 18 or newer, no packages), bench.html (the page), shortcut.mjs (puts its icon on the desktop), rooms/ (extra tabs: Questions, a decision as one click and yes or no on screenshots; Checks history, each check's results over time; Work log, what got done each day with its proof, by day, week and month), and its images: the icon, the screenshot, and this README's pictures. |
skills/two-strikes/ |
Stops a step after the second failure in a row of the same check. scripts/two_strikes.py: run, strike, pass, reset, ledger, and a self-test. |
skills/test-freeze/ |
Refuses a commit that changes or deletes an existing test without a TEST-CHANGE: reason. scripts/test_freeze.py: check over a range of commits, commit by commit or --net, and a self-test. |
skills/decide-first/ |
Makes a design question get its cancel line, a measurement and a decision with a reason, in that order, before code. scripts/decide_first.py: open, probe, decide, check, and a self-test. |
skills/bake-off/ |
Builds a piece nobody has designed, in a fixed order: frozen rules, a dumb control, candidates on their own branches with kill lines, a scoreboard, a pick. scripts/bake_off.py: check, scoreboard, and a self-test. |
skills/shell-guards/ |
Two hooks that refuse shell commands which fail without saying so: a heredoc holding a backslash (or a Python with nothing to read), and an exit code logged after $(date), which is date's and not the run's. scripts/heredoc_guard.py, scripts/exit_status_guard.py (with --scan for files), a settings example to paste, and a self-test each. Optional: they work only once switched on. |
tests/ |
The kit's own tests, in Python's standard unittest. Each script's self-test runs green, each of its breaks turns only its expected row red, and each script runs once end to end from the command line. The bench's self-test (node skills/bench/serve.mjs --self-test) starts the real server on scratch projects; its breaks are checked the same way. .github/workflows/test.yml runs them on Linux, macOS and Windows with Python 3.8 and 3.12, and the bench on Node 18. |
templates/ |
Short starting versions of the loop documents: PLAN, STATE, HANDOFF, DECISIONS, PICKUP, FILEMAP, ORDER, REPORT, LESSONS, QUESTIONS, WORKLOG, AGENTS and CLAUDE, plus the archive's index (ARCHIVE-README). |
LICENSE |
The MIT License. |
NOTICE.md |
What the license covers, and the names and marks it does not. |
A skill is a folder with a SKILL.md file in it. Claude Code looks for skills in two places.
The easy way: download or clone this repository, open Claude Code in its folder, and paste:
Install this kit for every project: copy each folder under
skills/into my personal skills folder (~/.claude/skills/, on Windows%USERPROFILE%\.claude\skills\); copytemplates/into~/.claude/skills/start-here/templates/; and copyREADME.md,LICENSEandNOTICE.mdinto~/.claude/skills/bench/about/. If a skill with the same name is already there, stop and ask me before replacing it. Then list what you copied.
By hand, the same steps:
- Pick a place:
- For every project: your personal skills folder,
~/.claude/skills/(on Windows,%USERPROFILE%\.claude\skills\). - For one project only:
.claude/skills/inside that project.
- For every project: your personal skills folder,
- Copy each folder under
skills/into it, so you end up with.../skills/start-here/SKILL.md,.../skills/scope-guard/SKILL.md, and so on. - Copy the
templates/folder into the start-here folder, so it sits at.../skills/start-here/templates/. The start-here and session-close skills look for the templates there. - Copy
README.md,LICENSEandNOTICE.mdinto.../skills/bench/about/, so the bench's About tab can show them. - Optional: switch on the two shell guards. They are hooks, not instructions, so copying the folder
is not enough: paste the settings example from
skills/shell-guards/SKILL.mdinto your settings file. - Start a new Claude Code session so it picks up the skills. In recent versions, typing
/lists them (for example/start-here).
The six scripts (two-strikes, test-freeze, decide-first, bake-off, and the two in shell-guards) need Python 3.8 or newer;
test-freeze and bake-off also need git. They use no packages. Python is python3 on macOS and Linux, and python on Windows.
Once installed for every project, each script is at ~/.claude/skills/<skill>/scripts/. Commit what they
write into a project with the rest of its notes: strikes.jsonl (two-strikes), decisions/ (decide-first)
and bake-off/ (bake-off); test-freeze writes nothing there. To check the kit itself, from the top folder of
this repository (the one holding this README):
python3 -m unittest discover -s tests
If you already have skills with the same names, rename the folder and the name: line in its
SKILL.md together.
- First, your original is kept safe. Before anything changes,
start-heremakes a sealed snapshot of your project (a zip, with a list of every file's fingerprint, checked file by file and then made read-only) and a clean working copy beside it, checked the same way. Your original folder is never touched again, by the kit or by any agent after it. All work happens in the working copy. A note in it,SAFE-COPY.md, says where everything is and how to get anything back. - In the working copy, it adds the notes files (STATE, HANDOFF, PLAN, DECISIONS, LESSONS, PICKUP,
FILEMAP, ORDER, REPORT), the house rules (AGENTS.md and CLAUDE.md), an
archive/folder with its index, a.gitignore, and git itself if the project was not in git yet. The bench adds INBOX.md when you send it your first message. - It reads your code, your README and any notes or plans you already keep, and offers to copy their
open items into the plan, naming where each came from. With your yes, the loose notes files then move
into
archive/original-notes/, so the working copy's root is clean. - It never moves your code. Moving source files breaks imports and builds. If you want the code reorganized, it becomes a task in the plan, with an order, a branch and a review, like any other, and the snapshot means nothing can be lost doing it.
- The bench stays on your machine, and only while you use it. It listens on 127.0.0.1 only, refuses requests from other web pages, loads nothing from the internet, writes one file (INBOX.md), and stops by itself once you close its page. Its desktop icon starts it with no console window.
- Arrive. Paste PICKUP.md into a new session. The agent checks the notes against the repository
first:
git status,git log -3, and one test whose number the notes state. Then it reads any waiting messages in INBOX.md. - Pick one task. Take the top item from HANDOFF.md, which comes from the plan in PLAN.md. One task per session is plenty.
- Think before building. Run
solution-integrityon it. Write the probe that could cancel the task (a quick check that would show the task is not needed) and run it first. For an open design question,decide-firstkeeps the cancel line, the measurement and the decision in that order; for a piece nobody has designed yet,bake-offsets the order its candidates are built and judged in. - Write the order, then branch. Fill in ORDER.md: files in scope, size budget, done-criterion,
stop conditions. Commit, then
git switch -c task/<id>-<short-name>. - Let the agent work, then review. It stops when done, when it needs to go outside scope, or when
the same check fails twice in a row (
two-strikes). You checkgit diff --statagainst the budget, read the diff, run the tests, runtest-freezeover the branch to see every test it changed and why, and read REPORT.md. Then merge it, or throw the branch away. - Close. Run
session-close: commit, mark the task done in PLAN.md, update STATE.md and HANDOFF.md, add to DECISIONS.md, move what finished intoarchive/with a pointer, check the notes' size, and write PICKUP.md withcompaction.
Open Claude Code in your project folder and run the start-here skill (type /start-here, or say
"run the start-here skill"). It asks about ten short questions, one or two at a time, sets everything
up, writes the plan with you, and names one small first task. It does not build anything in that
session. That is on purpose: the first real work goes better on top of the rails.
How long the first setup takes depends on the project. A new project goes quickly. A large existing one can take hours: the sealed copy of your project, reading your code and the notes you already keep, and bringing their open items into the plan, with your yes before anything moves. Get comfortable and give it the time. It is done once, and every session after it starts from what it set up.
Then, if the project has no single command that runs every check, run the gates skill next
(/gates). It builds the suite one part per session; the first part alone gives every later task a
"done" anyone can check. And whenever you want to watch the project on one page, ask for the bench
(/bench); ask it for a desktop icon too, and from then on one click opens it.
- The model still varies. The process around it is deterministic; the model is not, and will not be. The rails make its variation visible and recoverable, not absent.
- These skills are instructions, not locks. An agent can still ignore them. The locks are git (you can always go back), your look at the diff (nothing merges unread), and, once you switch them on, the two shell guards, which refuse their two mistakes before the command runs.
- Small tasks feel slow. They are faster. A 50-line change you can review in two minutes beats a 2,000-line change you have to throw away.
- Change anything here to fit how you work. The templates are starting points, not law.
Corvus is the raven, the messenger of the old stories: it flies out, sees, and comes back with word. The wing is what carries the work across, from one session to the next and through the automatic summary, so nothing that was learned has to be learned twice.
The skills, templates, bench and text are released under the MIT License (LICENSE): use them,
change them and share them, in any project, including commercial ones. The names CorvusWing and PROPHET,
the CorvusWing wing icon, and the PROPHET emblem, wordmark and banner are not covered by that license;
NOTICE.md says what that means.
What you build with the kit is yours: your code, and the notes the kit writes about your project.
CorvusWing. Created by Ron Brazil, signed PROPHET.








