harness

Files (24)

• SKILL.md
• architecture-patterns.md
• audit.md
• bootstrap.md
• check-snapshot.sh
• design-principles.md
• discover-verification-cmd.sh
• external-plugins.md
• find-python.sh
• github-action.md
• harness-update.sh
• harness-update.yml
• hoist.md
• hooks-patterns.md
• hooks-reference.md
• migrate-inventory.sh
• migrate.md
• project-facts.md
• release-please-reference.md
• resolve-upstream.sh
• retro.md
• update.md
• vendor-snapshot.sh
• vendoring.md

SKILL.md (first lines)

# Harness

Quality gates for an agent harness: the skills, agents, hooks, and docs that
teach agents how to work in a project. Harness quality is agent quality; a
stale or badly structured skill gets followed exactly as written.

The skill works on a project that has harness content in `.claude/`,
`.agents/`, or `.codex/`, or one you are bootstrapping. Generic skills and
agents arrive as a vendored snapshot that nobody edits (ADR 0001): what is
specific to the project lives in facts, and a need the facts can't express
becomes a declared fork. `.harness/lock.json` lists the snapshot's files;
anything else in the host trees is project-local. The project's verification
command must be runnable.

## Pick the mode

On Claude Code the modes are `/harness <mode>`; on Codex, `$harness <mode>`.

```text
harness              Auto-detect: bootstrap if no harness, audit if one exists
harness audit        Audit the current harness (delegates setup health to /doctor)
harness bootstrap    Analyze the project, write its facts and project-specific additions, vendor the generic set
harness update       Re-vendor the snapshot from a newer harness-kit release
harness add <repo>   Vendor skills from another repository
harness migrate      Move a copy-and-edit harness (.harness-lock.json) to a vendored snapshot
harness retro        Post-session retrospective on the environment
harness hoist        Propose generic local improvements back upstream
```

With no mode given, run `bootstrap` if none of `.claude/`, `.agents/`, or
`.codex/` holds harness content, and `audit` otherwise. A project with a
`.harness-lock.json` predates vendoring: suggest `migrate` before auditing.

Read the file for the selected mode before doing any work, and only that one;
each is self-contained.

| Mode | Read | What it covers |
| --- | --- | --- |
| `audit` | `${CLAUDE_SKILL_DIR}/audit.md` | Audit protocol, `/doctor` division of labor, gap classification, output format |
| `bootstrap` | `${CLAUDE_SKILL_DIR}/bootstrap.md` | harness-builder handoff, approval gate, facts and project-local content, vendoring the snapshot |
| `update` | `${CLAUDE_SKILL_DIR}/update.md` | Running the vendoring script against a newer release; acting on its report |
| `add` | `${CLAUDE_SKILL_DIR}/update.md` | Adding third-party skills to the vendored set (second half of the file) |
| `migrate` | `${CLAUDE_SKILL_DIR}/migrate.md` | Inventory of `.harness-lock.json` copies, each edit to a fact or fork, preview gate, vendoring |
| `retro` | `${CLAUDE_SKILL_DIR}/retro.md` | Environment audit, gap classification A/B/C/D/E, routing lessons to facts, local skills, or hoist |
| `hoist` | `${CLAUDE_SKILL_DIR}/hoist.md` | Proposing project-local content, facts patterns, and forks back upstream |

Done when the mode file is read and its final step reports done.

## Topic references

Read these as needed from any mode; each is linked directly from here.

| Topic | Read | When |
| --- | --- | --- |
| Project facts and `.harness/config.toml` | `${CLAUDE_SKILL_DIR}/project-facts.md` | Stating a project's verification command or other facts; deciding prose (`AGENTS.md`) versus config; reading or writing the config's keys |
| Vendoring a snapshot and `.harness/lock.json` | `${CLAUDE_SKILL_DIR}/vendoring.md` | Writing or rewriting a project's vendored skills, agents, and hooks with `vendor-snapshot.sh`; reading the lock; checking the snapshot is unedited with `check-snapshot.sh` |
| Skill and agent design patterns | `${CLAUDE_SKILL_DIR}/design-principles.md` | Writing or reviewing a skill or agent; deciding what belongs upstream vs local |
| Hook staging and exit codes | `${CLAUDE_SKILL_DIR}/hooks-patterns.md` | Configuring or auditing hooks (PostToolUse stages, Stop hooks); a hook that exits non-zero on a no-op is covered under Hook Exit Code Safety |
| Bundled skills and official plugin catalog | `${CLAUDE_SKILL_DIR}/external-plugins.md` | Bootstrap or audit needs bundled-skill delegation targets, stack-matched plugin recommendations, and overlap flags |
| Multi-agent architecture patterns | `${CLAUDE_SKILL_DIR}/architecture-patterns.md` | Bootstrap picks an architecture pattern for the project |
| Plugin `hooks.json` schema | `${CLAUDE_SKILL_DIR}/hooks-reference.md` | Writing or debugging a plugin's `hooks/hooks.json` |
| Claude Code GitHub Action in CI | `${CLAUDE_SKILL_DIR}/github-action.md` | Setting up or auditing a workflow that runs `claude-code-action` on a repo with a vendored snapshot |
| Release Please setup | `${CLAUDE_SKILL_DIR}/release-please-reference.md` | Recommending automated semver releases for a Conventional Commits + GitHub project |

## Treat the audit as advice

Run `harness audit` before shipping a skill. It catches what nothing else
does: invalid frontmatter, unrestricted "read-only" agents, oversized or vague
skills. Fix its defects (a frontmatter field the runtime silently ignores is a
defect) and weigh its recommendations (whether a description reads vague is
your call). It is advisory, not a gate.

## Classify every finding

Every finding from audit or retro gets a type, which decides where the fix
goes:

- **Type A**: content gap in an existing skill. Fix the skill.
- **Type B**: skill missing entirely. Add it.
- **Type C**: the builder template would not have generated this. Fix the
  builder; this double loop is the most valuable fix.
- **Type D**: a lightweight pattern not worth a skill. Store it in memory or
  `.claude/patterns/` (retro only).
- **Type E**: an environment change (a check, hook, CI job, standard, doc
  pointer, or access grant) made in the project; also Type C when the builder
  should have recommended it (retro only).

A vendored file (one `.harness/lock.json` lists) is never the fix site: a
Type A on it is a project fact, a project-local skill, or an upstream fix,
and a generic Type B goes upstream too. Retro mode routes each one.

## Fix gaps as you meet them

When any session (not only harness work) exposes a behavioral gap in the
harness:

1. Fix the immediate issue in the current task.
2. Decide the scope: upstream (a generic workflow that helps every project) or
   project-local (a fact, or a domain-specific skill).
3. Hand the fix to a background subagent and keep working.

An upstream fix clones harness-kit (or the other upstream source), fixes it,
and opens a PR. On Claude Code:

```text
Agent(
  description: "fix harness gap: [brief description]",
  run_in_background: true,
  prompt: "Fix [gap] in harness-kit.
    1. git clone --depth 1 https://github.com/dougborg/harness-kit /tmp/harness-fix
    2. cd /tmp/harness-fix && git checkout -b fix/[name]
    3. Fix skills/<area>/[skill]/SKILL.md (find it with ls skills/*/[skill])
       or agents/[agent].md, then run scripts/generate-claude-skills.sh.
       A new skill goes in a topic-area folder and that area's README.md.
       If fixing inline bash, extract it to a script instead of patching
       in place.
    4. Commit, push, open PR with gh
    5. Clean up: rm -rf /tmp/harness-fix"
)

From dougborg/harness-kit, Apache-2.0.

More from dougborg/harness-kit