Harness Audit — Claude Code Skill / Plugin

A Claude Code skill that audits any workspace against the 5-layer Strategic Framework for Agentic Harnesses, produces a gap report, drives a plan through your existing approval surfaces, and delegates implementation to codex:rescue.

What it does

/harness-audit walks any Claude Code workspace through 6 phases:

1. Inventory (read-only) — what's there? CLAUDE.md, hooks, skills, plugins, MCP servers, language stack, scale.
2. Gap report (read-only) — what's missing, sub-optimal, or out-of-scope? Compared against the framework's 5 layers + 15 universal traps.
3. Magnitude classify — small/medium fixes use built-in plan mode; big fixes route through superpowers:writing-plans (falls back to built-in plan mode if Superpowers isn't installed).
4. Plan — proposes changes via plan mode or writing-plans. User approves at this gate.
5. Execute — delegates implementation to codex:rescue per task, with the Codex flag-loop guard prompt included verbatim (falls back to a manual task list if Codex isn't installed).
6. Verify — runs the workspace's test suite, confirms no regressions, reports the delta.

The skill is additive and idempotent: re-running on an optimized workspace produces no changes. Custom rules in existing CLAUDE.md are preserved.

What it does NOT do

• Optimize your project's source code (models, business logic). Harness-only.
• Manage credentials.
• Auto-install plugins you haven't enabled.
• LSP integration (folded into CI lint instead at small scale).
• Other AI coding tools (Aider, Cursor, etc.) — Claude Code only.

Install

As a Claude Code plugin (recommended)

This repo doubles as its own plugin marketplace (.claude-plugin/marketplace.json):

# 1. Add the marketplace (inside Claude Code, or `claude plugin marketplace add ...`):
/plugin marketplace add simp5layer/harness-audit-plugin

# 2. Install the plugin:
/plugin install harness-audit@harness-audit-marketplace

Installed as a plugin, the skill is namespaced — invoke it as:

/harness-audit:harness-audit

Personal symlink (no plugin install)

cd ~/.claude/skills
ln -s /path/to/cloned/harness-audit-plugin/skills/harness-audit harness-audit

Restart Claude Code. Then in any workspace it's un-namespaced:

/harness-audit

Neither Codex nor Superpowers is required — the skill prefers them when present and falls back to built-in plan mode / a manual task list when absent.

What's inside

harness-audit-plugin/
├── README.md                          # this file
├── LICENSE                            # MIT
├── CHANGELOG.md
├── .claude-plugin/
│   ├── plugin.json                    # Claude Code plugin manifest
│   └── marketplace.json               # self-hosted marketplace entry
├── skills/harness-audit/
│   ├── SKILL.md                       # the 6-phase pipeline
│   └── references/
│       ├── framework.md               # frozen Strategic Framework snapshot
│       ├── common-traps.md            # 15 universal traps + flag-loop guard prompt
│       └── inventory-checklist.md     # per-layer cheat sheet
└── tests/
    ├── fixtures/                      # four inert sample workspaces
    └── expectations/                  # expected gap report per fixture

Test fixtures

Four inert fixture workspaces live under tests/fixtures/; the expected audit outcome for each is written down in tests/expectations/<fixture>.md:

Fixture	What it tests
bare-python/	Plain pyproject.toml, no .claude/. Skill must produce a comprehensive gap report and bootstrap a full L1-L4 plan.
python-with-claude-md/	Custom CLAUDE.md rules. Skill must preserve them — never replace with a template.
fully-optimized/	Minimal complete harness. Skill must report ≤2 minor gaps; second run must be no-op.
node-monorepo/	Non-Python stack. Skill must auto-detect and produce TypeScript/npm recommendations, not Python ones.

How to evaluate

The fixtures are workspaces, not an automated suite — the system under test is an agent following SKILL.md, so evaluation is a manual (or subagent-driven) run:

1. cd tests/fixtures/<name> and start a fresh Claude Code session there (the skill requires cwd = audited workspace).
2. Run the skill and stop at Gate 1 (the gap report — phases 1–2 are read-only, so this is side-effect-free).
3. Diff the gap report against tests/expectations/<name>.md. Each expectations file lists findings that MUST appear and recommendations that MUST NOT appear.
4. Layer 5 hermetic scoring rule: score only workspace-owned .mcp.json; treat claude mcp list as environment context, never as workspace gap evidence. During fixture evaluation, do not score that environment output at all because it varies by machine.
5. For fully-optimized/ only: continue past Gate 1 and re-run the skill a second time — the second run must report no new gaps (idempotency).

Source attribution

The framework snapshot lives at references/framework.md — it is self-contained; no external document is needed. The 15 universal traps were distilled from real harness work, with the load-bearing patterns (walk-base path guard, _path_key normalization) inlined in references/common-traps.md.

License

MIT — see LICENSE.