harness

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

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:

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"
)

On Codex, give the same prompt to a subagent. A project-local fix states the fact in .harness/config.toml or AGENTS.md's ## Project facts (${CLAUDE_SKILL_DIR}/project-facts.md), or edits a project-local skill, and commits normally. It never edits a vendored file; the edit check fails on that. A fork is only for a need the facts can't express, declared as an explicit decision with the user.

The upstream PR is reviewed and merged separately; the next update PR then brings the fix into every project. Encode behavioral gaps in skills through PRs rather than memories, because memories fade and skills persist. Done when the current task is unblocked and the fix is either committed locally or running in a background subagent.

Flag suspect guidance

Whenever guidance in a skill looks outdated or wrong, flag it in your reply and carry on working:

> ⚠️ FLAGGED: [brief reason this guidance may be outdated or wrong]

The flag is a lightweight in-flight signal that feeds the next audit.

Related

• The harness-builder agent: bootstrap mode dispatches it to analyze a codebase and recommend a harness.
• /session-retro: the session-side retrospective (documents the work, not the harness); run it alongside retro mode.
• /skill-writer: authoring guidance for skills and agents; audit checks against what it teaches.
• /doctor (bundled with Claude Code, alias /checkup): generic setup health such as installation, PATH, unused skills, slow hooks, and CLAUDE.md bloat. Audit invokes it rather than duplicating it.