Harnesses
A harness is a versioned bundle of skills (SKILL.md procedures, with their references and scripts) plus an outline
of the stages a card goes through. Use one to give a team’s runs your own process, rather than a prompt somebody
retyped. A run records the harness it ran under by hash, so you can compare two runs: same harness, same model, a
different outcome is a real difference.
Import a harness on a machine
- Run
andon harness addwith a folder or a git URL. A git URL is cloned one commit deep, at the branch or tag--refnames (git can’t clone a bare commit this way). - Fix any errors it prints, and add it again.
- Run
andon harness approve <slug>on every machine that should run it, or pass--approvewhen you add it. - Attach it to a team on the board (below).
The andon harness commands:
andon harness add <path> # a local folderandon harness add https://github.com/<org>/<repo> --ref <branch or tag>andon harness add <path> --approve --no-registerandon harness list # slug, the start of its hash, skills, approved or notandon harness approve <slug> # this hash may run on this machineandon harness remove <slug> # forget it hereImport copies the bundle into the agent’s state folder, hashes every file’s path and bytes, checks the skills and
records the bundle on the board (--no-register skips that). Nothing in it runs during import. Symlinks are listed
and skipped, never followed. A bundle may hold up to 600 files and 8 MB.
Attach it to a team
The team’s harness is in a section the team page doesn’t show:
- Open Settings, search for Harness, choose the result Harness (Each team › Harness), and pick the team.
- Choose the imported harness. The section shows its stages.
Sub-teams inherit it. A team with no harness runs Andon’s own pipeline. Every imported harness is listed on its own page: search Settings for Harnesses.
The outline
A bundle declares its stages in harness.json, or in a fenced JSON block in OUTLINE.md. Without one it still
imports, with a warning, and runs Andon’s own review, CI and merge.
{ "harness": "my-process", "name": "My process", "version": "1.0.0", "description": "Plan, build, then QE", "entry": "router", "stages": [ { "key": "plan", "label": "Plan", "actor": "agent", "recipe": "generic", "gate": { "requires": ["a plan a person approved"], "max_rounds": 1 }, "produces": ["plan.md"] }, { "key": "build", "label": "Build", "actor": "agent", "depends_on": ["plan"] }, { "key": "qe", "label": "QE", "actor": "agent", "gate": { "requires": ["typecheck, lint and tests pass"] } } ]}| Field | Meaning |
|---|---|
key, label |
The stage’s id and the name the board shows. |
actor |
agent or human. |
recipe |
A recipe slug, when the stage isn’t run with the card’s own recipe. |
gate.requires |
What passes the stage. The run is told, and the board shows it. |
gate.max_rounds |
How many tries the stage gets. |
depends_on |
Stages that come first. |
produces |
Files the stage makes. |
review, ci and merge are Andon’s own stages: a bundle can’t redefine them, and they always come last. These are
import errors:
- a stage that depends on itself, or on a stage the outline doesn’t declare
- two skills with the same name
- an
entryskill that doesn’t exist
Approval
The machine’s own policy decides, as it does for recipes. policy.harnesses.mode is approve (the default) or
trust_org. With approve, a run whose team names a hash nobody approved on this machine doesn’t start: it fails with
blocked by machine policy and the andon harness approve <slug> command to run. A changed bundle has a new hash, so
it needs approving again.
What a run gets
- The skills, for a Claude Code run only. They are copied into a config folder of the run’s own, with the rest of
the account’s settings linked in. Your own
~/.claudeis never written to, and two runs never see each other’s skills. A Codex or Gemini CLI run gets the brief only. - A brief, after the run contract and before the recipe’s own text: the harness name and version, the stage the run is in, what passes that stage, and the skills with their descriptions. The run contract outranks the harness; the harness outranks the repository. When a skill’s plan lists work, the brief tells the run to propose it as steps, so the plan becomes cards on the board rather than files in the repository.
- Provenance: the run records the harness and its hash, shown on the run.
A run is always told it is in the outline’s first stage.
Andon’s own harness
Andon’s repository keeps its own harness in .claude/skills/, with a harness.json beside the skills. Import it
from a checkout with andon harness add .claude/skills.
