# Auditing your agent harness with @wondelai/harness-audit

URL: https://developertoolkit.ai/en/workflows/harness/harness-audit-guide/
Description: Score any repo across six Software Factory stations locally with @wondelai/harness-audit—Level 0–5 checks, fix prompts, and CI gates.

`@wondelai/harness-audit` is an open-source CLI that scores any repository from Level 0 to Level 5 across the six Software Factory stations—Intent, Harness, Loop, Graph, Verification, and Release—by inspecting committed files, CI gates, test oracles, and agent configurations locally in under two seconds. Developers, tech leads, and CTOs use it to replace subjective self-assessment with verifiable repository evidence.

Most engineering teams overestimate their autonomy level because questionnaires measure aspirations rather than what actually sits in Git. A team lead may believe strict guardrails are live while `CLAUDE.md` has bloated past 400 lines, `.codex/config.toml` still specifies the retired `untrusted` approval policy, and CI runs zero protection against agents weakening test files.

## What an automated harness audit measures

Subjective forms record how a team hopes it works. `@wondelai/harness-audit` reads the exact environment Claude Code, Codex, and Cursor encounter when opening a session, mapping every finding onto Dan Shapiro's Autonomy Ladder (January 2026) and the [six Software Factory stations](/en/ladder/one-map/):

| Station | What deterministic repository checks verify | Core canon guide |
| --- | --- | --- |
| **1. Intent** | Concise `AGENTS.md` (≤ 150 lines), thin `@AGENTS.md` delegation in `CLAUDE.md`, scoped rules, skills, and spec/PR templates | [AGENTS.md & context](/en/workflows/context/agents-md-context/) |
| **2. Harness** | Explicit permission/sandbox posture (flagging retired Codex `untrusted`), lifecycle hooks with `stop_hook_active`, MCP hygiene, and secret protection | [Permissions & sandboxes](/en/workflows/harness/permissions-and-sandboxing/) · [Agent hooks](/en/workflows/harness/agent-hooks/) |
| **3. Loop** | Unified single-command verification (`lint`, `typecheck`, `test`, `build`), strict static typing, deterministic formatter, committed lockfile | [Agent-ready codebase](/en/workflows/harness/agent-ready-codebase/) |
| **4. Graph** | Worktree workflow scripts or `.worktreeinclude`, isolated local ports/state, and scoped subagent definitions | [Git worktrees](/en/workflows/harness/git-worktrees/) · [Ephemeral environments](/en/workflows/harness/ephemeral-environments/) |
| **5. Verification** | Real unit and E2E suites, `CODEOWNERS`/CI oracle protection, low `.skip`/suppression slop, automated PR review (e.g. `.cursor/BUGBOT.md`), fitness functions | [Oracle strength](/en/workflows/test/oracle-strength/) · [Protecting the oracle](/en/workflows/test/protect-the-oracle/) |
| **6. Release** | PR CI gates, evidence-bundle PR template, automated dependency checks, and production error/telemetry observability | [Evidence bundle](/en/workflows/ship/evidence-bundle/) · [Codebase health](/en/workflows/operate/codebase-health/) |

For the complete per-check inventory, see the [harness audit checks reference](/en/reference/harness-audit-checks/).

## Why hard level caps prevent inflated Level 4 scores

A repository with a spotless `AGENTS.md` and twenty Agent Skills—yet no test suite, no oracle protection, and weak CI gates—still operates at Level 2. Averaging raw points hides structural weaknesses, so `@wondelai/harness-audit` applies non-negotiable level caps:

| Claimed Level | Required minimum evidence in the repository |
| --- | --- |
| **Level 1–2** | Baseline instruction file and reproducible build/test commands |
| **Level 3** | Single-source instructions, deterministic verification loop, explicit permission posture, and CI gates |
| **Level 4** | Strong Verification station (real tests, oracle protection, automated PR review) plus Graph isolation |
| **Level 5** | Full six-station coverage including evidence bundles, architectural fitness functions, and release observability |

Level caps make the audit useful for CTOs and platform leads comparing dozens of repositories: a high Intent score cannot disguise an unguarded test oracle or missing sandbox boundary.

## Run the audit and close gaps step by step

1. **Run the zero-config local scan.** Execute from any repository root—zero API keys, zero network calls, zero code uploaded:

   ```bash
   npx @wondelai/harness-audit
   ```

2. **Capture workflow signals files cannot show.** Add the optional 7-question terminal interview for team adoption, PR review queue age, and cost visibility:

   ```bash
   npx @wondelai/harness-audit --interview --role lead
   ```

3. **Generate a tailored fix prompt or minimal baseline.** Export a repository-specific remediation prompt for Claude Code, Codex, or Cursor—or preview a clean non-destructive scaffold before writing anything:

   ```bash
   npx @wondelai/harness-audit --prompt --out HARNESS-FIX-PROMPT.md
   npx @wondelai/harness-audit init --dry-run
   ```

4. **Share reports and enforce a regression floor in CI.** Export a standalone HTML report for leadership reviews and add a CI gate so harness scores never silently decay on future PRs:

   ```bash
   npx @wondelai/harness-audit --format html --out harness-report.html
   npx @wondelai/harness-audit --ci --min-score 65
   ```

**Optional deep qualitative review (--deep)**

Static file scans cannot judge whether a test suite asserts real behaviour or whether instructions carry high signal-to-noise. Pass `--deep` to run an optional qualitative review of instruction clarity, oracle strength, and architectural legibility using your local `claude` or `codex` CLI (or your own API key). Nothing leaves your machine unless you invoke `--deep`.

## Verify that audit remediation actually improved safety

Raising a score only counts when the underlying controls catch real defects. Pair every audit-driven pull request with three verification checks:

- **Re-run the deterministic scan in CI:** Confirm `--ci --min-score` passes without weakening thresholds and that no level cap remains active on the station you fixed.
- **Run live canary probes:** Adding a hook file or sandbox block satisfies static detection; prove refusal with [hook fixtures](/en/workflows/harness/agent-hooks/), a [sandbox canary](/en/workflows/harness/permissions-and-sandboxing/), and a [codebase defect canary](/en/workflows/harness/agent-ready-codebase/).
- **Track multi-repo baselines over time:** Store periodic HTML or JSON outputs across core repositories so engineering leadership tracks real structural progress rather than raw AI code volume ([metrics frameworks](/en/org/metrics-frameworks/)).

## When harness audits mislead teams

- **Teams game the score with empty boilerplate.** Adding placeholder `AGENTS.md` files, dummy hooks, or tautological tests ticks static checkboxes without improving safety. Pair static scans with `--deep` inspection, [slop detection](/en/workflows/test/slop-detection/), and canary tests.
- **Engineers chase points in strong stations while ignoring level caps.** Polishing Intent from 85 to 95 does not raise an organization capped at Level 2 by weak Verification. Fix the lowest-scoring gating station first.
- **Running `init` without auditing existing configs.** Always preview with `npx @wondelai/harness-audit init --dry-run` first so generated scaffolds align with your team's existing `AGENTS.md`, package manager, and CI layout.
- **Treating one audit as a permanent certification.** Tool conventions, model capabilities, and CI configs drift every quarter. Keep `--ci --min-score` in pull-request workflows and re-evaluate your threshold after every major upgrade.

## Interactive guide, books, and team support

Explore the interactive breakdown at [`/en/harness-audit/`](/en/harness-audit/), browse the open canon editions at [`/en/books/`](/en/books/), or consult official vendor documentation for tool-specific remediation syntax: [Claude Code docs](https://code.claude.com/docs), [OpenAI Codex docs](https://developers.openai.com/codex), [Cursor docs](https://cursor.com/docs), [Agent Skills](https://agentskills.io), and [MCP](https://modelcontextprotocol.io).

- [Harness audit checks reference](/en/reference/harness-audit-checks/) — Inspect every deterministic check evaluated across all six Software Factory stations.
- [Interactive harness audit page](/en/harness-audit/) — Review command options, sample output, and station weightings.
- [Pruning context files](/en/workflows/context/pruning-context-files/) — Resolve bloated or duplicated instruction findings from Station 1.
- [Repo Diagnostic & Team Working Day](/en/services/) — Bring in hands-on help for multi-repo harness rollouts and engineering leadership alignment.
