Skip to content
AndonDocs
GitHub
Run machines and deploy / Machines

Harnesses

View as MarkdownThe same text, at this page's address plus .mdOpen in ClaudeAsk questions about this pageOpen in ChatGPTAsk questions about this page

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

  1. Run andon harness add with a folder or a git URL. A git URL is cloned one commit deep, at the branch or tag --ref names (git can’t clone a bare commit this way).
  2. Fix any errors it prints, and add it again.
  3. Run andon harness approve <slug> on every machine that should run it, or pass --approve when you add it.
  4. Attach it to a team on the board (below).

The andon harness commands:

shell
andon harness add <path> # a local folder
andon harness add https://github.com/<org>/<repo> --ref <branch or tag>
andon harness add <path> --approve --no-register
andon harness list # slug, the start of its hash, skills, approved or not
andon harness approve <slug> # this hash may run on this machine
andon harness remove <slug> # forget it here

Import 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:

  1. Open Settings, search for Harness, choose the result Harness (Each team › Harness), and pick the team.
  2. 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.

JSON
{
"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 entry skill 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

  1. 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 ~/.claude is never written to, and two runs never see each other’s skills. A Codex or Gemini CLI run gets the brief only.
  2. 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.
  3. 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.