# 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

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:

```sh
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`.
