Agent Harness

Agent Harness

The agent harness makes a repo agent-ready with self-sustaining enforcement. This skill installs it; CI, hooks, and conventions then enforce it.

Modes

1. Verify (primary)

Always start here. From the target repo root, run:

scripts/verify-harness.sh

Analyse the output and fix or suggest fixes. Verification checks dead references, line counts, missing artefacts, and command/target alignment.

2. Bootstrap

When artefacts are missing, create them from templates:

Populate with repo-specific values; never overwrite existing files without confirmation.

3. Audit

Report the repo's maturity level (1, 2, or 3) and show what is needed to reach the next level. See references/maturity-levels.md for detailed criteria.

Key Principles

• AGENTS.md is an index, not an encyclopedia. Keep it under 150 lines. Put detail in docs/.
• Enforcement is project-level. CI workflows, git hooks, and branch protection enforce the harness -- not this skill at runtime.
• Verify first, bootstrap second. Always run verification before creating artefacts. The skill checks artefacts, not tools.
• Delegate specialist work. See references/skill-integration-map.md for skill routing (@agent-rules, @github-project, @enterprise-readiness, @retro).
• Does not own learning. Session retrospection, outcome review, and constitutional audits are delegated to retro-skill. The harness verifies integration points exist (AH-22, AH-23) but does not invoke retro at runtime.

Maturity Levels

Level 1 -- Basic: AGENTS.md exists, is an index, documents commands.

Level 2 -- Verified: CI enforces harness integrity, AGENTS.md references resolve, commands match Makefile/scripts, ARCHITECTURE.md exists.

Level 3 -- Enforced: Branch protection requires harness CI, git hooks auto-activate, PR template includes checklist, drift detection on push.

See references/maturity-levels.md for the full breakdown.

References

• references/maturity-levels.md -- Maturity criteria and progression
• references/agents-md-rules.md -- AGENTS.md authoring rules
• references/artefact-inventory.md -- Harness artefacts list
• references/harness-engineering-overview.md -- Theory: four functions, patterns
• references/agent-first-architecture.md -- Legibility, layered deps, agent-first tech
• references/enforcement-mechanisms.md -- 10-mechanism table (CI, hooks, protection, drift)
• references/skill-integration-map.md -- Skill routing map + integration contracts with companion skills

ADR-001: Verify-First Design

Status: Accepted Date: 2026-03-22 Context: The agent-harness skill could be designed as primarily a generator (creating files) or primarily a verifier (checking consistency). The initial design discussion suggested bootstrap-first, but was reversed. Decision: The skill is primarily a verifier, secondarily a bootstrapper. Consequences: Verification is the default mode; bootstrapping is explicit and optional.

Rationale

• Verification works on repos that built their harness manually -- no lock-in to skill-generated artefacts.
• It does not enforce a specific genesis path -- teams can adopt gradually.
• OpenAI's harness engineering paper (https://openai.com/index/harness-engineering/) emphasises mechanical verification over generation.
• Existing skills (agent-rules, github-project) already handle generation of specific artefacts.
• Verify-first means make verify-harness works even without the skill installed at runtime.

Detail

The skill's primary mode is "check this repo," not "set up this repo." When invoked, it inspects the repository for the presence, format, and consistency of harness artefacts (AGENTS.md, CI workflows, git hooks, documentation references). It reports what is present, what is missing, and what is inconsistent.

Bootstrap is a secondary mode triggered explicitly (for example, via agent-harness:bootstrap). It generates missing artefacts using sensible defaults, but never overwrites existing files without confirmation. The generated artefacts are the same ones the verifier checks, so the workflow is: bootstrap once, verify continuously.

The verification script (verify-harness.sh) is designed to be portable. It uses only standard shell utilities and has no dependency on the skill runtime, Claude, or any agent framework. A repository can copy the script into its own CI pipeline and run it independently.

Implications

• The skill must produce a standalone verification script that works without the skill installed.
• Bootstrap must be idempotent -- running it on an already-configured repo should report "nothing to do."
• Documentation must lead with the verification workflow, not the bootstrap workflow.
• Teams that set up harness artefacts manually get the same verification benefits as teams that used bootstrap.

ADR-002: Enforcement Layers

Status: Accepted Date: 2026-03-22 Context: We evaluated 10 enforcement mechanisms for making repos agent-ready: CI workflows, Branch Protection/Rulesets, Git Hooks, .envrc (direnv), Composer plugins/scripts, npm scripts, pre-commit framework, Makefile/justfile, AGENTS.md, PR Templates. The question was which to use and how to layer them. Decision: Three-layer enforcement model ordered by strength: hard (server-side), automatic (local), and soft (convention-based). Consequences: The skill must produce artefacts for all three layers. No single mechanism is sufficient alone.

The Three Layers

1. Hard Layer (server-side, nobody bypasses)

• CI workflows (.github/workflows/harness-verify.yml) -- runs on every PR, fails the build if harness artefacts are missing or inconsistent.
• Branch Protection / Rulesets -- harness-verify configured as a required status check, blocking merge on failure.

This layer is the backstop. It works regardless of contributor setup, editor, operating system, or whether they have the skill installed. If the CI check fails, the PR cannot merge.

2. Automatic Layer (activates on clone/install, local)

• `.envrc` (direnv) -- auto-sets core.hooksPath to .githooks/ when a developer enters the repo directory.
• `composer post-install-cmd` / `npm prepare` -- installs git hooks automatically when dependencies are installed.
• Git hooks (`.githooks/`) -- pre-commit checks run verification before each commit; pre-push runs full verification before push.

This layer provides fast feedback during development. Developers catch issues before pushing, reducing CI round-trip time. It activates without manual setup for anyone using direnv or the project's package manager.

3. Soft Layer (convention-based, visible)

• `AGENTS.md` -- every agent reads this at session start; it points to harness documentation and verification commands.
• PR Templates -- GitHub shows a checklist to PR creators, reminding them to run verification.
• `Makefile` targets -- make verify-harness provides a discoverable entry point for manual checks.

This layer guides behaviour through conventions and visibility. It works for contributors who may not have direnv or the project's package manager but can read instructions.

Rationale

• The hard layer ensures no unverified code merges, regardless of the contributor's local setup.
• The automatic layer gives fast feedback during development without manual configuration.
• The soft layer guides behaviour through conventions and visibility.
• The combination works for all four contributor types: humans with skills, humans without skills, AI agents with skills, AI agents without skills.
• Each layer is optional -- a repo at Level 1 (see ADR-005) may only have soft enforcement, while Level 3 has all three.

Trade-offs and Limitations

• .envrc requires direnv -- documented as recommended, not required.
• Composer/npm hooks only work for projects using those ecosystems. For other ecosystems, .envrc or manual git config core.hooksPath .githooks/ is the fallback.
• The hard layer requires repository admin access to configure branch protection.
• Git hooks can be bypassed with --no-verify locally, which is why the hard layer exists as backstop.

ADR-003: Skill Delegation Model

Status: Accepted Date: 2026-03-22 Context: The agent-harness skill could implement everything itself (AGENTS.md generation, branch protection setup, quality gates, test infrastructure) or delegate specialised work to existing skills. Several skills already exist in the Netresearch ecosystem: agent-rules, github-project, enterprise-readiness, typo3-testing, git-workflow, automated-assessment, and more. Decision: agent-harness delegates specialised work to existing skills and defines the integration contract (what artefacts it expects back). Consequences: The harness skill remains lean and focused on orchestration and verification. Delegation is advisory, not forced.

Delegation Map

How Delegation Works

The harness skill does not call delegated skills directly. Instead, it operates in two modes:

1. Verification mode -- checks whether the expected artefacts exist and are well-formed. This mode has no dependency on any delegated skill. It checks files and configurations, not tools.

2. Guidance mode -- when artefacts are missing or malformed, the skill reports what is wrong and which skill to invoke to fix it. For example: "AGENTS.md is 230 lines. Run agent-rules:agents to restructure it as an index (see ADR-004)."

This separation means teams can adopt harness verification without adopting all delegated skills. A team that manages AGENTS.md manually still gets verification. A team that uses agent-rules gets the same verification plus automated generation.

Rationale

• Avoids duplication -- each skill maintains its domain expertise.
• Allows the harness skill to remain lean and focused on orchestration.
• Skills evolve independently -- the harness skill does not need updating when agent-rules improves its AGENTS.md generation.
• Teams can adopt harness verification without adopting all delegated skills.

Implications

• The harness skill must clearly document when to invoke which delegate.
• The verification script works without delegated skills (it checks artefacts, not tools).
• The delegation map must be kept current as new skills are added to the ecosystem.
• Circular dependencies must be avoided -- delegated skills should not depend on agent-harness.

ADR-004: AGENTS.md as Index

Status: Accepted Date: 2026-03-22 Context: AGENTS.md files in practice tend to grow into encyclopedias -- long documents with detailed instructions, code patterns, API documentation, and architectural detail. This wastes agent context window (AGENTS.md is read every session), makes drift harder to detect, and duplicates information better stored elsewhere. OpenAI's harness engineering paper (https://openai.com/index/harness-engineering/) explicitly recommends AGENTS.md as a "table of contents" that points to detailed documentation elsewhere. Decision: AGENTS.md must be a compact index (hard limit: under 150 lines), not an encyclopedia. Detail lives in docs/ and other referenced files. Consequences: The verification script enforces the line limit and checks that all internal references resolve.

What AGENTS.md Should Contain

• Repo structure map -- where is what (10-15 lines). Enough for an agent to orient itself without reading every directory.
• Available commands -- build, test, lint, verify (10-15 lines). The commands an agent needs to validate its own work.
• Key rules -- architecture boundaries, commit format, coding standards (10-15 lines). Only rules that apply to every change.
• References -- links to ARCHITECTURE.md, design docs, ADRs, and other detailed documentation. The index entries.

What AGENTS.md Should NOT Contain

• Detailed API documentation (belongs in docs/ or inline code docs).
• Code patterns or examples (belongs in docs/patterns/ or a cookbook).
• Full architecture descriptions (belongs in docs/ARCHITECTURE.md).
• Historical context or ADRs (belongs in docs/adr/ or similar).
• CI/CD pipeline details (belongs in docs/ci.md or workflow comments).
• Troubleshooting guides (belongs in docs/troubleshooting.md).

Rationale

• Agents read AGENTS.md every session -- every line costs context window space.
• Short files are easier to keep current. Less drift surface means fewer stale instructions.
• The index pattern makes dead-reference detection mechanical: parse references, check they resolve.
• Detail in referenced files can be read on-demand, only when relevant to the current task.
• Multiple agents (Claude, Codex, Copilot, Gemini) all read AGENTS.md -- the compact format benefits all of them.

Enforcement

The verify-harness.sh script checks two things related to this ADR:

1. Line count -- AGENTS.md must be under 150 lines. If it exceeds this limit, verification fails with a message indicating the current line count and the limit.

2. Reference resolution -- every file path referenced in AGENTS.md (detected by patterns like docs/..., ./..., relative paths) must resolve to an existing file or directory in the repository. Dead references cause verification failure.

Migration Path for Existing Repos

Repos with long AGENTS.md files can migrate incrementally:

1. Identify sections that are detailed documentation (not index entries). 2. Move each section to an appropriate file in docs/. 3. Replace the section in AGENTS.md with a one-line reference to the new location. 4. Run make verify-harness to confirm the result is under 150 lines and all references resolve.

ADR-005: Checkpoint Maturity Model

Status: Accepted Date: 2026-03-22 Context: Binary "harness yes/no" is insufficient for gradual adoption. Teams need to understand their current maturity and what to do next. OpenAI's harness engineering paper describes maturity levels (single developer to small team to production). The Netresearch automated-assessment-skill already provides a checkpoint-based audit system. Decision: Three maturity levels, each with mechanical checkpoints that automated-assessment can evaluate. Consequences: Verification accepts a --level=N flag. Checkpoint IDs follow the scheme AH-0x (Level 1), AH-1x (Level 2), AH-2x (Level 3).

Level 1 -- Basic

Suitable for any repo at any team size. The minimum bar for agent-readiness.

Level 2 -- Verified

Suitable for team repos with CI. Adds consistency checks.

Level 3 -- Enforced

Suitable for production repos with full enforcement. Adds server-side guarantees.

Rationale

• Gradual adoption -- teams start at Level 1 and upgrade when ready.
• Each level is strictly additive -- Level 2 includes all of Level 1.
• Mechanical checkpoints make maturity measurable, not subjective. Every checkpoint can be evaluated by a script without human judgment.
• Integration with automated-assessment gives cross-skill audit capability.
• Levels map roughly to OpenAI's single-developer / small-team / production model.

Usage

The verification script accepts a level flag:

# Check Level 1 only (default)
./verify-harness.sh --level=1

# Check Levels 1 and 2
./verify-harness.sh --level=2

# Check all levels
./verify-harness.sh --level=3

Teams can set their target level in project configuration (for example, in .harness.yml or as a variable in the CI workflow). The skill reports the current level and what is needed to reach the next level.

Checkpoint ID Scheme

• AH-0x -- Level 1 (Basic). IDs 01 through 09.
• AH-1x -- Level 2 (Verified). IDs 11 through 19.
• AH-2x -- Level 3 (Enforced). IDs 21 through 29.

This scheme leaves room for additional checkpoints within each level without renumbering.

Agent-First Architecture

Design choices that make a repository legible and predictable for AI coding agents. These complement the four system functions (constrain, inform, verify, correct) by addressing what the agent sees when it runs the system, not just when it reads about it.

Source: OpenAI Harness Engineering (<https://openai.com/index/harness-engineering/>).

Application Legibility

For an agent to validate its own changes, it must be able to inspect the running system. Without this, the agent is flying blind and depends entirely on test-suite proxies for correctness.

Three legibility primitives:

• Isolated runtime per worktree. Every git worktree should be able to spin up an isolated instance of the product on a unique port/socket so the agent's branch and the agent's running system are tied together. Tools: ddev with project-scoped names, docker compose with project-name overrides, devcontainers per worktree.
• Visual inspection. Agents inspect rendered output, not just code. Wire up Chrome DevTools Protocol or Playwright so the agent can request DOM snapshots and screenshots. Frontend changes that look correct in JSX may render broken; the harness should let the agent see that.
• Queryable observability. Logs, metrics, and traces should be locally accessible to the agent in structured form. docker compose logs --since=30s --no-color is enough for many cases. Without observability, agents debug by intuition.

These belong in the project's dev-environment scripts and Makefile/composer/npm targets, surfaced through AGENTS.md so the agent knows they exist.

Layered Dependency Model

OpenAI enforces a strict layered architecture. Their canonical stack:

Types -> Config -> Repo -> Service -> Runtime -> UI

The specific layer names are not the point; the point is that the dependency graph is explicit, declared in code, and enforced by tooling. Agents do not absorb architecture from culture -- they follow rules that produce errors.

Read the diagram left-to-right as "depends only on the next layer to the left": UI depends on Runtime; Runtime depends on Service; Service depends on Repo; and so on. A UI module reaching past Runtime to import Service or Repo directly is a violation.

Custom linters check imports against this rule. When a violation occurs, the linter must produce an actionable error message aimed at the agent: name the file, name the rule, name the fix.

Compare:

• ❌ "Architectural violation in component.tsx"
• ✅ "component.tsx (UI layer) imports from src/service/payments.ts (Service layer); UI must access Service through the Runtime layer. See docs/ARCHITECTURE.md#layer-rules."

Recommended starting points for repos using this skill:

1. Document the layer model in docs/ARCHITECTURE.md with a dependency diagram. 2. Add a custom linter rule (eslint-plugin-boundaries, deptrac for PHP, or a small AST script) that enforces it. 3. Make the rule a hard CI gate, not advisory.

Agent-First Technology Choices

Prefer composable, boring technologies with stable APIs over cutting-edge libraries with opaque internals.

Why: agents reason from context. A library with predictable, well-documented behaviour fits in the context window and yields correct code. A library that "does magic" forces the agent to either guess or re-read its source -- both of which fail at scale.

Practical implications:

• Use libraries with stable, well-documented APIs over those that change frequently or rely on convention-over-configuration.
• When an external library proves consistently unpredictable for agents (mocks fail; generated code looks plausible but is wrong; the agent invents APIs that do not exist), consider reimplementing the slice you actually need in-repo. Repo code is fully legible to the agent; library code is not.
• Boring beats clever for harnessed repos. The cost of a less-clever library is paid once; the cost of an opaque library is paid on every agent interaction.

This is not a license to NIH everything. It is a deliberate trade-off: pay implementation cost once to get reliable agent behaviour forever after.

How These Relate to the Four Functions

These reinforce one another: a layered architecture composed of opaque libraries is no architecture at all, and legibility without constraint just shows the agent more chaos.

Enforcement Mechanisms Reference

This document covers all 10 enforcement instruments available for making repositories agent-ready. Mechanisms are ordered by enforcement strength, from hardest (server-side, nobody bypasses) to softest (convention-based, reminder only).

CI / Hook Parity Principle

The single most load-bearing rule across all 10 mechanisms: every fast, deterministic check that runs in CI must also run as a pre-commit hook. CI is the slow, parallel, authoritative backstop. It is not the first feedback loop. When a contributor (human or agent) commits broken code and learns about it 90 seconds later from a CI failure rather than 2 seconds earlier from a pre-commit hook, the harness has a gap — even if every CI gate is correctly configured.

The corollary: when CI catches a mechanical issue that a hook could have caught, the absence of the hook is the bug. Strengthen the harness rather than asking the operator to be more careful.

What counts as a fast check

A check qualifies for the hook layer if it:

• Completes in under ~5 seconds on a typical commit on the contributor's machine
• Is deterministic (same input → same result, no flakes)
• Has no external dependencies that the commit machine cannot satisfy (no remote API calls, no Docker pulls)
• Operates on the working tree or staged changes, not on a matrix of environments

Examples: linters, formatters, type-checkers, schema validators, AST-based static analysis, file-shape validators (e.g. SKILL.md word count, YAML well-formedness).

Examples that do NOT qualify and should stay CI-only: full test suites, mutation testing, security scanners with remote feeds, multi-version matrices, container builds, integration tests against live services.

Stack-native framework choice

Pick the hook framework the ecosystem already expects, not the one you personally prefer:

For skill repos specifically, prefer pre-commit over lefthook even though both work: skill repos contain Python helper scripts, contributors usually already have Python tooling (uv, ruff, validation scripts), and the upstream tools the validation pipeline depends on (markdownlint-cli2, yamllint, actionlint, ruff, shellcheck) all ship .pre-commit-hooks.yaml definitions that can be pinned by rev: and updated by dependency bots. See this repo's .pre-commit-config.yaml as the reference shape.

The framework choice is secondary to the principle. What matters is that the local set is a subset of the CI set — never a separate pipeline that drifts.

How parity fails in practice

Most parity gaps follow one of three patterns:

1. CI added a check, hook never updated. New linter, new validator, new format rule — wired into CI, forgotten locally. 2. Hook framework exists but is hollow. lefthook.yml is present and runs echo "lint", but the actual composer lint / go vet / validate-skill.sh invocation lives only in CI. 3. Hook bypassed by default. Contributors run git commit --no-verify because some hook step is slow or flaky. The fix is to make that step fast (or move it to pre-push / CI), not to tolerate the bypass.

Audit periodically: for each command line in CI workflows that meets the "fast check" definition above, grep the hook config files. If the command is not represented, that is the harness gap.

Mechanism Summary

Detailed Mechanisms

1. Branch Protection / Rulesets

What it is: GitHub server-side rules that block merging unless required conditions are met.

When it triggers: On merge attempt (merge button, API merge call, gh pr merge).

Who it affects: Everyone -- humans, agents, CI bots. No bypass without admin override.

Strength: Hard. Server-side enforcement cannot be circumvented locally.

Setup:

• Configure via GitHub UI: Settings > Branches > Branch protection rules, or Settings > Rules > Rulesets.
• Configure via API: gh api repos/OWNER/REPO/branches/main/protection -X PUT.
• Configure via github-project-skill: delegates branch protection setup.

Key configuration: Add harness-verify as a required status check. This means the CI workflow from mechanism 2 must pass before any PR can merge.

Limitations: Requires repository admin access. Does not provide fast local feedback.

GitLab equivalent:

• Configure via GitLab UI: Settings > Repository > Protected branches, or Settings > Merge requests > Merge checks.
• Configure via API: glab api projects/:id/protected_branches.
• Add harness-verify as a required pipeline job. Under Settings > Merge requests, enable "Pipelines must succeed".

---

2. CI Workflows

What it is: A GitHub Actions workflow (.github/workflows/harness-verify.yml) that runs verify-harness.sh on every pull request.

When it triggers: On every PR push event. Can also trigger on push to specific branches.

Who it affects: Everyone. CI runs regardless of contributor setup.

Strength: Hard (when combined with branch protection). Automatic (standalone -- visible but not blocking).

Setup:

Copy or generate the workflow from templates/harness-verify.yml.tmpl:

name: Harness Verify
on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Verify harness
        run: bash scripts/verify-harness.sh --level=2

The workflow uses only actions/checkout and bash -- no external action dependencies.

Reports: Results appear as GitHub Actions annotations (::error::, ::warning::) visible on the PR Files Changed tab.

Limitations: Requires a round-trip to CI. Local feedback is faster via hooks.

GitLab equivalent:

A GitLab CI job in .gitlab-ci.yml that runs verify-harness.sh on every merge request:

harness-verify:
  stage: test
  script:
    - bash scripts/verify-harness.sh --level=2 --format=gitlab
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

Results appear in the job log. GitLab does not have inline file annotations, but the structured output is visible in the pipeline job output.

---

3. Git Hooks

What it is: Local scripts in .githooks/ that run before commits (pre-commit) and before pushes (pre-push).

When it triggers: pre-commit runs before every git commit. pre-push runs before every git push.

Who it affects: Local developers who have hooks activated. Does not affect CI or web-based edits.

Strength: Automatic (once activated). Can be bypassed with git commit --no-verify.

Setup:

# Activate hooks for this repo
git config core.hooksPath .githooks

# Or system-wide
git config --global core.hooksPath .githooks

Hooks should call verify-harness.sh:

#!/usr/bin/env bash
# .githooks/pre-commit
bash scripts/verify-harness.sh --level=1 --format=text

Limitations: Requires activation. Bypassable with --no-verify. This is why the hard layer (CI + branch protection) exists as a backstop.

---

4. .envrc (direnv)

What it is: A direnv configuration file that activates automatically when a developer enters the repository directory.

When it triggers: On cd into the repo directory (if direnv is installed and allowed).

Who it affects: Local developers with direnv installed.

Strength: Automatic. Silent activation -- no manual step required after initial direnv allow.

Setup:

# .envrc
# Activate git hooks
git config core.hooksPath .githooks

# Add project scripts to PATH
PATH_add scripts
PATH_add bin

After creating .envrc, a developer entering the directory for the first time sees:

direnv: error .envrc is blocked. Run `direnv allow` to approve its content

After running direnv allow, all subsequent directory entries silently activate the configuration.

Limitations: Requires direnv installed. First-time direnv allow is a manual step. Not available in CI (not needed -- CI has its own workflow).

---

5. Composer post-install-cmd

What it is: A Composer lifecycle hook that runs after composer install or composer update.

When it triggers: After dependency installation in PHP projects.

Who it affects: PHP developers using Composer.

Strength: Automatic. Transparent to the developer -- hooks install as a side effect of normal workflow.

Setup:

Add to composer.json:

{
  "scripts": {
    "post-install-cmd": [
      "git config core.hooksPath .githooks || true"
    ],
    "post-update-cmd": [
      "git config core.hooksPath .githooks || true"
    ]
  }
}

The || true ensures the script does not fail in environments without git (CI Docker containers, production deploys).

Limitations: PHP/Composer projects only. Does not work for contributors who skip composer install.

---

6. npm prepare Script

What it is: An npm lifecycle script that runs after npm install.

When it triggers: After dependency installation in Node projects.

Who it affects: Node developers using npm/yarn/pnpm.

Strength: Automatic. Transparent to the developer.

Setup (direct):

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks || true"
  }
}

Setup (with Husky):

{
  "scripts": {
    "prepare": "husky"
  }
}

Then configure Husky hooks to call verify-harness.sh.

Limitations: Node projects only. Does not work if --ignore-scripts is used.

---

7. Makefile / justfile

What it is: A build automation target that runs harness verification on demand.

When it triggers: Manual invocation (make verify-harness or just verify-harness).

Who it affects: Everyone who can run make/just. Language-agnostic.

Strength: Soft. Requires the contributor to know about and choose to run it.

Setup:

.PHONY: verify-harness
verify-harness:
	bash scripts/verify-harness.sh --format=text

.PHONY: bootstrap-harness
bootstrap-harness:
	@echo "Run agent-harness:bootstrap via your agent framework"

.PHONY: harness-status
harness-status:
	bash scripts/verify-harness.sh --format=text --level=3 || true

Advantages: Works in any project regardless of language or package manager. Discoverable via make help or reading the Makefile. Can be called by CI workflows.

Limitations: Requires manual invocation. Not enforced.

---

8. AGENTS.md

What it is: A markdown file at the repo root read by AI agents at the start of every session.

When it triggers: Agent session start. Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, and other agents look for this file automatically.

Who it affects: AI agents. Humans can read it but it is optimised for agent consumption.

Strength: Soft. Convention-based. The agent reads it but is not mechanically forced to comply.

Setup:

Create AGENTS.md at the repo root following the index format (see ADR-004). Keep it under 150 lines. Reference detailed documentation in docs/ rather than inlining it.

# AGENTS.md

## Repo Structure
- `src/` -- application source
- `docs/` -- documentation (ARCHITECTURE.md, ADRs, design docs)
- `scripts/` -- automation scripts

## Commands
- `make build` -- build the project
- `make test` -- run all tests
- `make verify-harness` -- verify harness consistency

## Rules
- Follow conventional commits
- All new subsystems must be documented in ARCHITECTURE.md

Limitations: No mechanical enforcement. An agent can ignore instructions. This is why CI and hooks exist as harder layers.

---

9. PR Templates

What it is: A GitHub pull request template (.github/pull_request_template.md) that pre-fills the PR description with a checklist.

When it triggers: PR creation via GitHub UI or gh pr create.

Who it affects: PR authors. Visible reminder during PR creation.

Strength: Soft. Reminder only -- unchecked items do not block merge.

Setup:

Create .github/pull_request_template.md:

## Changes

<!-- Describe your changes -->

## Harness Checklist

- [ ] AGENTS.md updated (if commands or structure changed)
- [ ] docs/ updated (if architecture or design changed)
- [ ] New subsystems documented in ARCHITECTURE.md
- [ ] Exec plan created (if multi-file structural change)

Limitations: Reminder, not enforcement. Contributors can delete the template text. No merge blocking.

GitLab equivalent:

GitLab uses merge request templates stored in .gitlab/merge_request_templates/:

<!-- .gitlab/merge_request_templates/Default.md -->
## Changes

<!-- Describe your changes -->

## Harness Checklist

- [ ] AGENTS.md updated (if commands or structure changed)
- [ ] docs/ updated (if architecture or design changed)
- [ ] New subsystems documented in ARCHITECTURE.md
- [ ] Exec plan created (if multi-file structural change)

The Default.md template is automatically applied to new merge requests. Additional named templates can coexist in the same directory.

---

10. pre-commit Framework

What it is: A multi-language hook manager that standardises git hook setup via .pre-commit-config.yaml.

When it triggers: On commit (after pre-commit install has been run).

Who it affects: Local developers who have run pre-commit install.

Strength: Automatic (once installed). Bypassable with --no-verify.

Setup:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: verify-harness
        name: Verify harness consistency
        entry: bash scripts/verify-harness.sh --level=1 --format=text
        language: system
        pass_filenames: false
        always_run: true

Then: pre-commit install

Advantages: Standardised hook management. Easy to add additional hooks (linting, formatting). Supports auto-update of hook versions.

Limitations: Requires pre-commit installed (pip install pre-commit). Requires pre-commit install to be run once. Bypassable with --no-verify.

The Activation Chain

This diagram shows how enforcement mechanisms activate in sequence during a typical development workflow:

Developer clones repo
  |
  +---> .envrc detected by direnv
  |       +---> git config core.hooksPath .githooks
  |       +---> scripts/ added to PATH
  |
  +---> composer install / npm install
  |       +---> post-install-cmd / prepare script
  |       +---> git hooks confirmed active
  |
  +---> Developer makes changes, runs git commit
  |       +---> .githooks/pre-commit runs
  |       +---> verify-harness.sh --level=1 (fast check)
  |       +---> Commit succeeds or fails with feedback
  |
  +---> Developer runs git push
  |       +---> .githooks/pre-push runs
  |       +---> verify-harness.sh --level=2 (full check)
  |       +---> Push succeeds or fails with feedback
  |
  +---> PR/MR created
  |       +---> PR/MR template pre-fills harness checklist
  |       +---> CI workflow/pipeline triggers
  |       +---> verify-harness.sh runs in CI
  |       +---> Results reported as annotations (GitHub) or job log (GitLab)
  |
  +---> Merge attempted
          +---> Branch protection checks required status
          +---> harness-verify must be green
          +---> Merge succeeds or is blocked

Each layer catches issues that earlier layers missed or that bypassed them. The chain is designed so that the last layer (branch protection) is impossible to bypass without admin access.

Choosing Mechanisms for Your Project

Minimum (any project)

• AGENTS.md (mechanism 8)
• CI workflow (mechanism 2)
• Makefile target (mechanism 7)

This is the Level 1 baseline. Works for any language, any team size.

PHP project

All of the minimum, plus:

• Composer post-install-cmd (mechanism 5)
• .envrc (mechanism 4)
• Git hooks (mechanism 3)

Node project

All of the minimum, plus:

• npm prepare script (mechanism 6)
• Husky or direct hooks (mechanism 3)
• .envrc (mechanism 4)

Go project

All of the minimum, plus:

• .envrc (mechanism 4)
• Makefile targets (mechanism 7 -- Go projects already use Make heavily)
• Git hooks (mechanism 3)

Maximum (Level 3)

All mechanisms active:

• Branch protection with harness-verify as required check (mechanism 1)
• CI workflow (mechanism 2)
• Git hooks via .githooks/ (mechanism 3)
• .envrc for automatic activation (mechanism 4)
• Language-specific auto-setup (mechanism 5 or 6)
• Makefile targets (mechanism 7)
• AGENTS.md as index (mechanism 8)
• PR template with harness checklist (mechanism 9)
• pre-commit framework (mechanism 10, optional -- overlaps with direct hooks)

Harness Engineering Overview

What is Harness Engineering?

Harness engineering is the discipline of designing repo-level infrastructure that makes AI coding agents reliable at scale. It represents a fundamental shift in how teams work with AI: from "humans write code, AI helps" to "humans design environments, agents execute."

The metaphor is straightforward. Modern AI models are powerful but directionless. A model with no constraints, no context, and no verification will produce plausible-looking output that may or may not solve the actual problem. The harness channels that raw capability into productive, verifiable work -- the same way a test harness channels code execution into observable, repeatable outcomes.

The harness is everything the model reads and everything that checks its output: AGENTS.md, architecture docs, CI workflows, git hooks, branch protection, linting rules, test suites, and the structural conventions that tie them together.

The Four System Functions

OpenAI's harness engineering research (<https://openai.com/index/harness-engineering/>) identifies four system functions that a well-designed harness must provide. These are not sequential phases but concurrent, reinforcing layers.

1. Constrain

Define architectural boundaries and dependency rules. Tell the agent what it must not do, what patterns to follow, and where code belongs.

Constraining the solution space makes agents more productive, not less. An agent that knows "all database access goes through the repository layer" does not waste tokens exploring direct SQL in controllers. An agent that knows "this project uses conventional commits" does not invent its own commit message format.

Constraints live in AGENTS.md, ARCHITECTURE.md, linter configurations, and dependency rules.

2. Inform

Provide rich context so the agent understands the system it is working in. This includes architecture documentation, API specs, design decisions (ADRs), test expectations, and observability data.

The repository is the single source of truth. If the agent needs to know something to do its job, that information must be in the repo -- not in a team member's head, not in a Confluence page, not in a Slack thread. Context engineering is the practice of making relevant information discoverable and machine-readable within the repo structure.

Information lives in docs/, AGENTS.md references, inline code comments, and structured configuration files.

3. Verify

Test and validate agent output through mechanical means: linting, CI pipelines, structural tests, type checking, and harness consistency checks. Mechanical verification catches problems that human review misses or delays.

The key insight is that verification must be automatic and continuous. A verification step that requires a human to remember to run it is not verification -- it is a suggestion. CI workflows, pre-commit hooks, and required status checks provide genuine verification.

Verification lives in .github/workflows/, .githooks/, Makefile targets, and test suites.

4. Correct

Build feedback loops that let agents iterate until criteria are satisfied. When verification fails, the agent receives structured feedback (error messages, lint output, test failures) and tries again. Self-repair turns a single-shot interaction into a convergent loop.

Correction depends on clear, actionable error messages. A CI check that reports "harness verification failed" is less useful than one that reports "AGENTS.md references docs/API.md but that file does not exist." The more specific the feedback, the fewer iterations needed.

Correction lives in CI annotations, hook output, and structured error reporting from verification scripts.

The harness does not store learning itself. It provides the rails: memory files, rule files, CI checks, hooks, review templates. Learning — capturing reusable patterns from sessions and routing them to the correct destination — is performed by retro-skill (see skill-integration-map.md #12) and materialized through specialist skills (agent-rules, skill-repo, automated-assessment). The harness verifies the integration points exist (AH-22, AH-23) but does not own the learning loop.

Complementary Perspectives

Anthropic / Claude Code

Anthropic's agent development guidance (<https://docs.anthropic.com/en/docs/build-with-claude/agentic-systems>) emphasises:

• TDD-first workflows -- write tests before implementation so the agent has a concrete target.
• Plan mode -- agents propose a plan, get human approval, then execute. Separates thinking from doing.
• Compact context transfer -- keep instruction documents short and reference external files for detail. AGENTS.md as an index, not an encyclopedia.
• Dedicated review steps -- do not assume agent output is correct. Build review into the workflow.

LangGraph and Durable Execution

LangGraph and similar frameworks focus on runtime durability:

• Checkpointing -- save agent state at each step so work survives failures.
• Resume after failures -- crashed agents pick up where they left off instead of restarting.
• Human-in-the-loop -- pause execution for human approval at defined points.

These runtime concerns are complementary to repo-level harness engineering. This skill focuses on the repo structure and verification layer. Runtime durability (tracing, evals, checkpointing) is a future extension.

Industry Consensus

Across vendors and frameworks, several principles have converged:

• Large monolithic instruction files are counterproductive. Context must be structured and layered.
• Agents need external feedback loops. Self-assessment is unreliable; mechanical verification is essential.
• The repo itself is the best place to store agent instructions. External configuration drifts.
• Enforcement must work without the agent framework installed. Project-level mechanisms (CI, hooks, branch protection) outlive any specific tool.

Operational Patterns from OpenAI's Deployment

OpenAI's five-month internal deployment (~1,500 PRs, ~1M LOC, team scaled 3 to 7 engineers) surfaced operational patterns that go beyond the four system functions. These describe how to run a harnessed repo day-to-day, not how to structure it.

Merge Philosophy: Minimal Blocking Gates

Conventional code-review norms (two approvals, comprehensive manual QA, "every PR gets a comment") become bottlenecks once agents open dozens of PRs per day. OpenAI's stance:

• Minimal blocking merge gates -- only mechanical checks block (tests, linting, harness verification). Subjective gates do not.
• Short-lived pull requests -- merge fast, iterate via follow-up PRs.
• Higher tolerance for quick post-merge corrections -- "the cost of a quick correction is low when the agent can implement it in minutes. The cost of blocking every merge on comprehensive upfront validation compounds across hundreds of concurrent tasks."

This is consistent with the Level 3 stance that branch protection requires harness-verify to pass -- because that check is fast and mechanical. It is not consistent with stacking subjective approval gates, manual QA sign-off, or "minimum reviewer count" policies on top of an agent-driven workflow.

Continuous Entropy Management

Treat pattern drift as a continuous background process, not a periodic sprint:

• Define canonical patterns (logging format, naming conventions, component shape) as mechanical linter rules.
• Run recurring background agents that scan for deviations and open auto-mergeable refactor PRs.
• Treat technical debt as compound interest -- small continuous cleanup payments are far cheaper than waiting for a large refactor sprint.

The opposite pattern -- batching cleanup into periodic "fix the AI slop" sessions -- is explicitly called out as inefficient. Continuous correction beats episodic correction.

Additional Anti-Patterns

In addition to the anti-patterns covered earlier (monolithic instruction files, stale documentation), the article identifies two more:

• Unpredictable third-party dependencies. Libraries with opaque internals or unstable APIs make agents unreliable because they cannot reason about behaviour. See agent-first-architecture.md for the agent-first technology trade-off.
• Periodic cleanup sprints. Batching technical debt is more disruptive and more expensive than continuous background cleanup. See "Continuous entropy management" above.

The Key Principle

"The model is commodity; the harness is moat."

-- OpenAI, Harness Engineering

OpenAI's research demonstrated this quantitatively. Improving the harness -- without changing the underlying model -- raised task performance from 52.8% to 66.5%. The same model, given better constraints, better context, better verification, and better correction loops, produced dramatically better results.

This means that investment in harness engineering compounds. Every improvement to documentation, CI checks, architectural constraints, and feedback loops benefits every agent interaction going forward, regardless of which model or framework is used.

What This Skill Implements

The agent-harness skill implements the repo-structure and verification layer of harness engineering:

• Constrain: AGENTS.md with architectural rules, ARCHITECTURE.md with dependency boundaries.
• Inform: Structured docs/ directory, index-format AGENTS.md with references to detailed documentation.
• Verify: verify-harness.sh script, CI workflow (harness-verify.yml), git hooks, maturity-level checkpoints.
• Correct: Actionable error messages from verification, bootstrap mode to create missing artefacts, structured output for CI annotations.

Runtime concerns (agent tracing, evaluation frameworks, durable execution, LLM observability) are outside the current scope and tracked as future extensions.

Sources

• OpenAI Harness Engineering: <https://openai.com/index/harness-engineering/>
• SWE Quiz commentary on the OpenAI writeup (source of the deployment metrics and operational-pattern framing in this doc): <https://www.swequiz.com/articles/openai-harness-engineering>
• Anthropic Agent Development: <https://docs.anthropic.com/en/docs/build-with-claude/agentic-systems>
• Claude Code SDK: <https://docs.claude.com/en/api/agent-sdk>

Harness Maturity Levels

The harness maturity model defines three levels of agent-readiness for a repository. Each level builds on the previous one, adding stronger enforcement and more comprehensive verification. Levels are measured mechanically via checkpoints -- there is no subjective assessment.

Level Overview

Level 1 -- Basic

Target audience: Any repository, solo developer or small team, minimal effort to adopt.

Requirements

What it gives you

• Any AI agent can understand your repo. Claude Code, OpenAI Codex, GitHub Copilot, and Gemini CLI all read AGENTS.md at session start. A compact, well-structured AGENTS.md means every agent interaction starts with correct context.
• Contributors know what commands to run. New team members (human or AI) can find build, test, and lint commands without reading source code.
• Baseline for gradual improvement. Level 1 is the foundation. Everything at Level 2 and 3 builds on these artefacts.

What it does not give you

• No mechanical verification that docs are accurate.
• No CI enforcement.
• No protection against documentation drift.

How to set up

Manual:

1. Create AGENTS.md at the repo root. Use the index format -- keep it under 150 lines. Include sections for repo structure, commands, and rules. 2. Create a docs/ directory. Add at least a placeholder file. 3. Document your build, test, and lint commands in AGENTS.md.

With skill bootstrap:

agent-harness:bootstrap --level=1

The skill analyses the repo, detects available commands from Makefile/composer.json/package.json, and generates AGENTS.md from the template.

Verification

bash scripts/verify-harness.sh --level=1 --format=text

Example output:

Agent Harness Verification
==========================

Level 1 -- Basic
  ✓ AGENTS.md exists
  ✓ AGENTS.md is index-format (87 lines)
  ✓ Commands section found
  ✓ docs/ directory exists

Summary: Level 1 COMPLETE | 0 error(s), 0 warning(s)

---

Level 2 -- Verified

Target audience: Team repositories with CI, actively maintained, multiple contributors.

Requirements

All of Level 1, plus:

Note: AH-30..AH-33 and AH-36 are assessed via the automated-assessment checkpoint runner (/assess agent-harness), not by verify-harness.sh. The verification script covers structural harness checks; quality delegation checkpoints are evaluated by the assessment skill.

What it gives you

• Mechanical guarantee that docs are not lying. Every file path referenced in AGENTS.md is verified to exist. Every command documented in AGENTS.md is verified to match an actual build target. If someone renames a file or removes a Makefile target, verification catches it.
• Architecture is documented for onboarding. New contributors (human or AI) can read ARCHITECTURE.md to understand the system before modifying it. This is the "Inform" function from harness engineering.
• CI catches harness drift automatically. The harness verification workflow runs on every PR. If a PR changes the Makefile but does not update AGENTS.md, the CI check warns about it.

What it does not give you

• CI results are advisory, not blocking (unless branch protection is configured).
• No automatic hook setup -- contributors must manually activate hooks.
• No drift detection for structural file changes.

How to set up

Manual:

1. Complete all Level 1 requirements. 2. Audit every file reference in AGENTS.md. Fix or remove any that point to non-existent files. 3. Audit every command in AGENTS.md. Ensure each one matches an actual Makefile target, composer script, or npm script. 4. Create docs/ARCHITECTURE.md. Include at minimum: system overview (1 paragraph), component map, and dependency rules. 5. Create .github/workflows/harness-verify.yml using the template. This workflow runs verify-harness.sh on every PR. 6. GitLab alternative: If using GitLab, add a harness-verify job to .gitlab-ci.yml using the template. This job runs verify-harness.sh on every merge request.

With skill bootstrap:

agent-harness:bootstrap --level=2

The skill creates ARCHITECTURE.md from the template, generates the CI workflow, and fixes any broken references it can detect.

Verification

bash scripts/verify-harness.sh --level=2 --format=text

Example output:

Agent Harness Verification
==========================

Level 1 -- Basic
  ✓ AGENTS.md exists
  ✓ AGENTS.md is index-format (87 lines)
  ✓ Commands section found
  ✓ docs/ directory exists

Level 2 -- Verified
  ✓ All references resolve
  ✓ All make targets verified (3 targets)
  ✓ docs/ARCHITECTURE.md exists
  ✓ CI harness workflow exists

Summary: Level 2 COMPLETE | 0 error(s), 0 warning(s)

---

Level 3 -- Enforced

Target audience: Production repositories, full enforcement, drift-resistant. Repos where harness consistency is a hard requirement.

Requirements

All of Level 2, plus:

What it gives you

• No unverified code merges. harness-verify is a required status check in branch protection. If the harness is inconsistent, the PR cannot merge. This works for all contributors -- human or AI, with or without skills installed.
• New contributors get fast feedback immediately. Git hooks auto-activate on clone via the stack-native mechanism — the prepare script in package.json (Node), post-install-cmd in composer.json (PHP), or .envrc via direnv (any stack, especially Python-only / skill repos). No manual setup required. The first commit attempt runs verification.
• Structural changes cannot silently break documentation. Drift detection monitors changes to structural files (Makefile, composer.json, package.json, CI workflows). If these files change in a PR but AGENTS.md is not also updated, the verification emits a warning.
• Full enforcement works for everyone. The enforcement is project-level (CI workflows, branch protection, git hooks), not tool-level. It works whether the contributor uses Claude Code, VS Code, vim, or the GitHub web editor.

What it does not give you

• Runtime agent observability (tracing, evals).
• Automatic AGENTS.md updates (the skill detects drift but does not auto-fix).
• Cross-repo consistency (each repo is verified independently).

How to set up

Manual:

1. Complete all Level 2 requirements. 2. Configure branch protection: on GitHub, add harness-verify as a required status check on the default branch. On GitLab, enable 'Pipelines must succeed' under Settings > Merge requests. 3. Choose a hook framework appropriate for the stack:

• `pre-commit` (recommended for skill/Python projects) — add a .pre-commit-config.yaml referencing the hook providers and pre-commit install --install-hooks to activate. See references/enforcement-mechanisms.md § "Stack-native framework choice" and § "CI / Hook Parity Principle" for full rationale; skill repos consume validate-skill + check-version-parity from netresearch/skill-repo-skill@v1.22.0+ (pin a specific tag and let Renovate bump).
• captainhook/captainhook (PHP) — install via composer, configure captainhook.json.
• lefthook (Go binary-shipping projects, e.g. ofelia) — install the static binary, configure lefthook.yml.
• husky + lint-staged (Node-heavy frontends) — install via npm, wire into package.json.
• Direct .githooks/ + .envrc with git config core.hooksPath .githooks (zero-dependency fallback).

4. Wire hook auto-activation so contributors don't run the install command manually. Pick the option that matches the contributor's typical install step:

• pre-commit projects with package.json: add a prepare script under package.json's scripts running pre-commit install --install-hooks (silent no-op if pre-commit isn't on PATH).
• pre-commit projects with composer.json: add a post-install-cmd to composer.json doing the same.
• pre-commit projects with neither (pure Python / skill repos): add an .envrc (direnv) that runs pre-commit install --install-hooks on cd into the repo. This is the canonical Python-ecosystem path.
• Direct .githooks/ route: an .envrc with git config core.hooksPath .githooks works for direnv users.

5. Create the PR/MR template. For GitHub: copy to .github/pull_request_template.md. For GitLab: copy to .gitlab/merge_request_templates/Default.md. 6. Ensure the chosen hook framework's hook checks are a subset of CI — see references/enforcement-mechanisms.md § "CI / Hook Parity Principle". For the direct .githooks/ route, ensure .githooks/pre-commit and .githooks/pre-push exist and are executable. The structural-vs-quality split (structural harness checks via verify-harness.sh, quality checks delegated to the automated-assessment runner) is encoded in checkpoints.yaml — treat that file as the authoritative source for what each checkpoint requires.

With skill bootstrap:

agent-harness:bootstrap --level=3

The skill creates all missing artefacts and delegates branch protection setup to github-project-skill.

Verification

bash scripts/verify-harness.sh --level=3 --format=text

Example output:

Agent Harness Verification
==========================

Level 1 -- Basic
  ✓ AGENTS.md exists
  ✓ AGENTS.md is index-format (92 lines)
  ✓ Commands section found
  ✓ docs/ directory exists

Level 2 -- Verified
  ✓ All references resolve
  ✓ All make targets verified (6 targets)
  ✓ docs/ARCHITECTURE.md exists
  ✓ CI harness workflow exists

Level 3 -- Enforced
  ✓ Git hooks auto-setup via .envrc
  ✓ PR template exists (repo-level)
  ✓ No drift detected

Summary: Level 3 COMPLETE | 0 error(s), 0 warning(s)

---

Upgrade Paths

Level 1 to Level 2

1. Add the CI workflow. Copy templates/harness-verify.yml.tmpl to .github/workflows/harness-verify.yml. Adjust the level flag to --level=2. 2. Create ARCHITECTURE.md. Use templates/ARCHITECTURE.md.tmpl as a starting point. Document the system overview, component map, and dependency rules. 3. Fix dead references. Run verify-harness.sh --level=2 and fix any file paths in AGENTS.md that do not resolve. 4. Align commands. Ensure every command listed in AGENTS.md has a matching Makefile target, composer script, or npm script.

Level 2 to Level 3

1. Configure branch protection. Add harness-verify as a required status check. This is the single most impactful change -- it turns advisory CI into blocking enforcement. 2. Choose a hook framework (skill repos consume validate-skill + check-version-parity from netresearch/skill-repo-skill@v1.22.0+). Skill/Python projects: pre-commit with .pre-commit-config.yaml (recommended). PHP: captainhook. Go binary-shipping: lefthook. Node-heavy frontends: husky + lint-staged. Zero-dependency fallback: direct .githooks/ + .envrc. See references/enforcement-mechanisms.md § "Stack-native framework choice" for the full table. 3. Add hook auto-setup so contributors don't run install manually. Pick the option that matches the contributor's typical install step:

• pre-commit projects with package.json: a prepare script under scripts running pre-commit install --install-hooks.
• pre-commit projects with composer.json: a post-install-cmd doing the same.
• pre-commit projects with neither (pure Python / skill repos): an .envrc (direnv) running pre-commit install --install-hooks on cd.
• Direct .githooks/ route: .envrc with git config core.hooksPath .githooks.

4. Create the PR template. Copy templates/pull_request_template.md.tmpl to .github/pull_request_template.md. 5. Ensure CI/Hook parity. Whatever framework runs locally, its hook checks must be a subset of what CI runs (see references/enforcement-mechanisms.md § "CI / Hook Parity Principle"). checkpoints.yaml is the authoritative source for what each AH-* requires. For the direct route, add .githooks/pre-commit and .githooks/pre-push calling verify-harness.sh.

Measuring Maturity

Command-line usage

# Check current maturity level (runs all checks, reports highest passing level)
bash scripts/verify-harness.sh --format=text

# Check a specific level
bash scripts/verify-harness.sh --level=2 --format=text

# Use in CI (exits non-zero on failure)
bash scripts/verify-harness.sh --level=2

# Run a single check category
bash scripts/verify-harness.sh --check=refs --format=text

CI usage

# .github/workflows/harness-verify.yml
- name: Verify harness (Level 2)
  run: bash scripts/verify-harness.sh --level=2

The default output format uses GitHub Actions annotation syntax (::error::, ::warning::), which makes results visible directly on the PR Files Changed tab.

# .gitlab-ci.yml
harness-verify:
  stage: test
  script: bash scripts/verify-harness.sh --level=2 --format=gitlab
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

The GitLab format uses structured log output. Enable "Pipelines must succeed" in GitLab merge request settings to make it a hard gate.

Automated assessment usage

The checkpoints.yaml file integrates with automated-assessment-skill for batch auditing across multiple repositories:

# Audit a single repo
automated-assessment:audit --skill=agent-harness --target=/path/to/repo

# Audit all repos in an organisation
automated-assessment:audit --skill=agent-harness --org=netresearch

Checkpoint Reference

Skill Integration Map

The agent-harness skill does not operate in isolation. It delegates specialised work to other skills in the ecosystem and verifies that the output of those skills meets harness requirements. This document defines the integration contract for each skill.

Integration Principle

The harness skill checks artefacts, not tools. It verifies that the OUTPUT of delegated skills is present and consistent. It does not require the delegated skill to be installed. A team that creates AGENTS.md manually gets the same verification as a team that used agent-rules-skill to generate it.

This means:

• The harness skill never imports or calls another skill's code directly.
• Integration is through shared file conventions (AGENTS.md, ARCHITECTURE.md, CI workflows).
• Verification works on any repo, regardless of which skills were used to set it up.

Skill Integration Details

1. agent-rules-skill

What it provides: Generates AGENTS.md content following best practices for agent-readable repository documentation.

When harness delegates to it: When AGENTS.md needs to be created (bootstrap mode) or updated (after structural changes). The harness skill invokes agent-rules when it detects AGENTS.md is missing or when a user explicitly requests AGENTS.md generation.

What harness expects back:

• An AGENTS.md file at the repo root.
• Index format: compact, under 150 lines.
• Contains at minimum: repo structure section, commands section, rules section.
• References external documentation in docs/ rather than inlining detail.

What harness verifies:

• AGENTS.md exists (checkpoint AH-01).
• AGENTS.md is under 150 lines (checkpoint AH-02).
• AGENTS.md contains a commands section (checkpoint AH-03).
• All file references in AGENTS.md resolve to existing files (checkpoint AH-10).

---

2. github-project-skill / GitLab project settings

What it provides: Configures platform features: branch protection rules, PR/MR templates, CODEOWNERS/code owners, repository settings, label schemas.

Platform notes:

• GitHub: Delegates to github-project-skill for branch protection and PR template setup.
• GitLab: No equivalent skill exists yet. Configure branch protection and merge request settings manually via GitLab UI (Settings > Repository > Protected branches, Settings > Merge requests).

When harness delegates to it (GitHub): When Level 3 enforcement needs to be set up on GitHub, the harness skill delegates branch protection configuration and PR template creation to github-project-skill. On GitLab, the harness does not delegate these actions; it only verifies that branch protection and merge request templates have been configured manually as described above.

What harness expects back:

• Branch protection rule on the default branch with harness-verify as a required status/pipeline check.
• PR template at .github/pull_request_template.md (GitHub) or MR template at .gitlab/merge_request_templates/Default.md (GitLab).
• CODEOWNERS file if the project has designated maintainers.

What harness verifies:

• PR template exists (checkpoint AH-20).
• harness-verify is listed as a required status check (verified via gh api, not by file inspection).
• PR template contains harness-related checklist items.

---

3. enterprise-readiness-skill

What it provides: Quality gates, SLSA provenance configuration, SBOM generation, OpenSSF Scorecard integration, supply chain security setup.

When harness delegates to it: When assessing production-readiness of a repository. The harness skill does not directly invoke enterprise-readiness but references it when a repo needs to move beyond harness maturity into production-readiness concerns.

What harness expects back:

• Quality gate configuration in CI workflows.
• Security scanning enabled (dependency review, CodeQL, or equivalent).
• SLSA provenance configured for releases.

What harness verifies:

• Quality gate workflows exist (informational -- not a harness checkpoint).
• The harness skill reports enterprise-readiness as a separate concern, not a harness maturity requirement.

---

4. typo3-testing-skill

What it provides: Test infrastructure for TYPO3 extensions: PHPUnit configuration, functional test setup, CI test matrix, code coverage configuration.

When harness delegates to it: When the target repo is a TYPO3 extension and test infrastructure needs setup. The harness skill detects TYPO3 extensions by the presence of ext_emconf.php or TYPO3-specific composer types.

What harness expects back:

• Test commands defined in composer.json scripts (e.g., ci:test:php:unit, ci:test:php:functional).
• Test commands documented in AGENTS.md.
• CI workflow that runs tests.

What harness verifies:

• Documented test commands in AGENTS.md match actual composer.json script definitions (checkpoint AH-11).
• CI workflow exists and references the test commands.

---

5. go-development-skill

What it provides: Go application patterns, test infrastructure, linting configuration (golangci-lint), Makefile targets for Go projects.

When harness delegates to it: When the target repo is a Go project (detected by go.mod). Same delegation pattern as typo3-testing but for Go.

What harness expects back:

• Test commands defined as Makefile targets (e.g., make test, make lint).
• Test commands documented in AGENTS.md.
• CI workflow that runs Go tests and linting.

What harness verifies:

• Documented make targets in AGENTS.md match actual Makefile targets (checkpoint AH-11).
• CI workflow exists and runs tests.

---

6. git-workflow-skill

What it provides: Commit conventions, branching strategy, git hooks, changelog generation, release workflow patterns.

When harness delegates to it: When git workflow setup is needed (hooks, commit message format, branching rules). The harness skill delegates hook content and commit format rules to git-workflow-skill.

What harness expects back:

• Git hooks configured in .githooks/ directory.
• Commit format defined (conventional commits or project-specific).
• Hooks documented in AGENTS.md rules section.

What harness verifies:

• .githooks/ directory exists with executable hooks (checkpoint AH-21 -- partial).
• Hook auto-activation is configured via .envrc, composer, or npm (checkpoint AH-21).
• Commit format rules are documented in AGENTS.md.

---

7. concourse-ci-skill

What it provides: Concourse CI pipeline definitions, task configurations, resource types.

When harness delegates to it: When the target repo uses Concourse CI instead of or alongside GitHub Actions. The harness skill detects Concourse by the presence of ci/ or concourse/ directories with pipeline YAML files.

What harness expects back:

• Pipeline definition files in a standard location.
• CI commands documented in AGENTS.md.

What harness verifies:

• Documented CI commands match pipeline task definitions (checkpoint AH-11 -- adapted for Concourse).
• If both GitHub Actions and Concourse are present, both are documented.

---

8. docker-development-skill

What it provides: Docker setup, docker-compose configuration, multi-stage build patterns, development environment containerisation.

When harness delegates to it: When Docker-based development setup is needed. The harness skill does not directly manage Docker configuration but verifies that Docker commands are documented.

What harness expects back:

• Docker commands documented in AGENTS.md (e.g., docker compose up, make docker-build).
• docker-compose.yml or equivalent present if referenced.

What harness verifies:

• Documented Docker commands reference files that exist (checkpoint AH-10 -- general reference check).
• Docker-related commands in AGENTS.md match actual compose file service definitions (best-effort).

---

9. automated-assessment-skill

What it provides: Checkpoint-based audit system. Reads checkpoints.yaml from skills and evaluates them mechanically against a target repository.

When harness delegates to it: The relationship is inverted -- automated-assessment reads the harness skill's checkpoints, not the other way around. The harness skill provides checkpoints.yaml that defines what to check; automated-assessment provides the runtime that evaluates those checks.

What harness provides to it:

• checkpoints.yaml with maturity-level checks (AH-01 through AH-21).
• Preconditions (must be a git repository).
• Severity levels (error vs. warning) for each checkpoint.

What harness expects back:

• Assessment results in structured format (pass/fail per checkpoint).
• Maturity level determination (Level 1/2/3 based on which checkpoints pass).

What harness verifies: N/A -- automated-assessment is the verifier, not the verified.

Integration Rule: Assessment Before Enhancement

When any quality-related skill is invoked to ENHANCE (not just verify) a project's quality posture, the automated-assessment skill MUST run first. This applies to:

• typo3-testing invoked with "enhance", "improve", "strengthen"
• enterprise-readiness invoked with "audit", "production ready"
• php-modernization invoked with "upgrade", "modernize"
• security-audit invoked with "audit", "scan", "review"

The assessment generates a structured gap report from checkpoints. This report becomes the task list, preventing iterative manual discovery of issues that checkpoints would catch automatically.

The harness enforces this through AH-30..AH-35: if quality infrastructure is missing, the harness flags it before any enhancement work begins.

---

10. superpowers (writing-plans, executing-plans)

What it provides: Plan lifecycle management. Writing-plans creates structured execution plans; executing-plans tracks and executes them step by step.

When harness delegates to it: When the harness detects a complex change that should be planned before execution. The harness skill recommends plan creation for multi-file structural changes.

What harness expects back:

• docs/superpowers/plans/ directory exists if the project uses plans.
• Active plans are tracked with checkbox syntax.

What harness verifies:

• If docs/superpowers/plans/ is referenced in AGENTS.md, the directory exists (checkpoint AH-10 -- general reference check).
• Plan template is available for bootstrap mode (templates/exec-plan.md.tmpl).

---

11. skill-repo-skill

What it provides: Defines the structure of a skill repository: .claude-plugin/plugin.json, skills/<name>/SKILL.md, split licensing (MIT + CC-BY-SA-4.0), release workflows, composer integration. Also defines the materialization-contract.md followed by tools that submit PRs to skill repos (notably retro-skill).

When harness applies alongside it: Skill repos benefit from both layers: skill-repo-skill verifies skill-specific structure (.claude-plugin/plugin.json, skills/<name>/SKILL.md, composer.json conventions) via its own validate-skill.sh; harness layers generic agent-readiness on top (AGENTS.md as index, docs/ structure, .github/workflows/harness-verify.yml). The two verifiers don't overlap — they target different artefacts.

What harness expects back:

• An AGENTS.md index for the skill repo.
• The standard harness workflows (harness-verify.yml).

What harness verifies in skill repos:

• The same generic harness checkpoints apply as for any other repo (AH-01 AGENTS.md exists, AH-02 line count, AH-12 harness-verify.yml exists). Skill-specific structural validation is left to skill-repo-skill's own validate-skill.sh.

---

12. retro-skill

What it provides: LLM-driven session retrospection. Detects friction in agent sessions (~32 signals across 3 layers: mechanical pre-pass, LLM inference, cross-session) and materializes approved learnings into one of six destinations: user-memory, project-rule, skill-update, new-skill, checkpoint, harness-artefact.

When harness delegates to it: At end of any non-trivial session, or on-demand for specific issues. The harness does not invoke retro-skill at runtime; it verifies that the artefacts retro-skill needs to materialize learnings exist in the repo.

What harness expects back from a retro-active repo:

• PR/MR template contains a retro question (so contributors can flag reusable patterns to route).
• Optional SessionEnd hook (.claude/hooks/session-end.json) is present if the team wants auto-trigger of /retro.
• docs/feedback/ directory exists when project-rule learnings have been approved.
• Approved learnings in docs/feedback/ follow the feedback-memory-schema defined by agent-rules-skill.

What harness verifies:

• AH-22 (warning, Level 3): PR/MR template includes a retro question.
• AH-23 (info, Level 3): SessionEnd hook present (optional convenience).
• Indirect: AH-10 ensures any docs/feedback/<slug>.md referenced from AGENTS.md actually exists.

Why this delegation matters: The harness used to risk becoming the meta-owner for "anything agent-readiness-shaped", including learning. retro-skill carves out the learning ownership cleanly, leaving the harness as a thin verifier of integration points. See references/harness-engineering-overview.md for the principle.

Integration Flow Diagram

                    agent-harness (verify / bootstrap / audit)
                    |
        +-----------+-----------+------------------+
        |           |           |                  |
   [Verify]    [Bootstrap]  [Audit]           [Delegate]
        |           |           |                  |
        v           v           v                  v
  verify-harness.sh  templates/   checkpoints.yaml   Other skills
        |           |           |                  |
        |           |           |        +---------+---------+
        |           |           |        |         |         |
        |           |           |   agent-rules  github-  git-workflow
        |           |           |   (AGENTS.md)  project  (hooks)
        |           |           |                (branch
        |           |           |                protection)
        |           |           |
        +-----+-----+----------+
              |
              v
         Artefact checks
    (files exist, refs resolve,
     commands match targets)

The harness skill sits at the centre, delegating creation to specialised skills and verifying the output. The verification layer works independently of which skill created the artefacts.