SanvioLabs/sanvio-harness-starter

Built and maintained by Sanvio Labs. Free under MIT.
A harness is everything around the model: the rules it reads, the procedures it
follows, the checks that stop it, and the other agents it hands work to. The
model is the engine. The harness is what makes it safe to leave running.
This repo is the smallest harness that still does the job. The root is
generic: rules, skills, a reviewer, the checks, and a place for your company
and your code. One worked job sits in examples/proposal/, drafting client
proposals, because a proposal is where the cheap mistakes live: a placeholder
left in, a rate somebody made up, a total that doesn't add up. None of those are
hard. All of them ship anyway when the process lives in your head. You read
the example, then build your own job the same way at the root.
It works with Claude Code, Codex and Kiro. Nothing in it is tied to one tool.
Set up
**Don't skip the middle line.** Git won't run the hook in .githooks/ unless
you point it there, and the setting doesn't travel with a clone. Skip it and
every check in the hook silently does nothing. That exact line was missing from
a real harness for months, and nobody noticed because nothing failed.
You need Python 3.9 or newer and no packages.
In Claude Code, start it from the repo's root and say yes when it asks
whether you trust the folder. A line then sits above the prompt:
That's the harness lens. It names each layer as it acts on your session, and
/lens lists everything it did. No line? Your Claude Code may be older than
the version it was tested on (2.1.295), or the folder isn't trusted.
examples/mods/harness-lens/ has the two commands that install it from inside a
session. Codex and Kiro don't show it: neither has mods.
Trusting the folder also switches on Stelliad, an MIT-licensed set of
skills the starter uses for specs and tickets. There's no separate yes: the
trust is the yes. It's the one set of someone else's skills the starter
installs rather than has you review first, and Borrowing other people's
skills says why, what that trusts, and how to keep it off. Each one runs as
stelliad: , so /stelliad:create-spec starts a spec and
/stelliad:create-ticket writes an issue the loop can take.
Working through this on your own? Open the repo in your agent and run
/orientation in Claude Code, or say "get me started" in any of them.
skills/orientation/ checks your setup, asks where your company's data lives
and how the agent should reach it, then walks you through the five layers
around your own job.
Copied it a while ago? Ask your agent "what's new", or run /whats-new in
Claude Code. It compares your CHANGELOG.md with this repo's and tells you
what you don't have yet and what to do to take it.
python3 scripts/check_setup.py runs the setup check on its own: Python, the
hook, the links below, and whether origin is still this public repo. Make
your own private copy before any company material goes in.
On Windows, clone with git clone -c core.symlinks=true from a terminal with
Developer Mode on, or the two links below arrive as plain text files. If they
do, AGENTS.md still works for every tool.
The five layers, one step at a time
Each step is a tag. Check one out to see the harness as it stood at that point,
or diff two to see exactly what a layer adds.
| Tag | Adds | What it fixes |
|---|---|---|
| step-0 | A rate card, a template, one finished proposal | Nothing yet. The agent guesses |
| step-1 | AGENTS.md, the instructions file | The agent stops inventing rates and knows where things go |
| step-2 | skills/draft-proposal/, a skill | Drafting becomes the same procedure every time, with a defined output |
| step-3 | gates/proposal_gate.py, a gate | "Done" becomes something a script checks, not something the agent claims |
| step-4 | .githooks/pre-commit, a hook | The gate runs whether anyone remembers it or not, and secrets can't be committed |
| step-5 | agents/proposal-reviewer.md, a review agent | A second reader who reads like the client, and reports without editing |
The tags build the proposal job at the root, one layer at a time, which is
how the talk builds it. On main the same files live in examples/proposal/,
the reviewer is generic (agents/reviewer.md, with the proposal brief in the