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 + 11 universal traps.
3. Magnitude classify — small/medium fixes use built-in plan mode; big fixes route through superpowers:writing-plans.
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.
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)

# Via agent-installer skill (if you have it):
# In Claude Code: install plugin https://github.com/simp5layer/harness-audit-plugin

# Or via Claude Code marketplace (when published):
# claude plugin install 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:

/harness-audit

What's inside

harness-audit-plugin/
├── README.md                          # this file
├── LICENSE                            # MIT
├── CHANGELOG.md
├── .claude-plugin/plugin.json         # Claude Code plugin manifest
└── skills/harness-audit/
    ├── SKILL.md                       # the 6-phase pipeline
    └── references/
        ├── framework.md               # frozen Strategic Framework snapshot
        ├── common-traps.md            # 11 universal traps + flag-loop guard prompt
        └── inventory-checklist.md     # per-layer cheat sheet

Test fixtures

Four fixture workspaces under tests/fixtures/ validate behavior:

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.

Source attribution

The framework comes from Strategic_Framework_Agentic_Harnesses.md. The 11 universal traps were distilled from real harness work — see references/common-traps.md for citations.

License

MIT — see LICENSE.