Harness Audit Skill

Walk any workspace through a 6-phase audit against the 5-layer Strategic Framework. Phases 1-3 are read-only; phases 4-5 use the user's existing approval surfaces (plan mode + superpowers:writing-plans + codex:rescue); phase 6 verifies. The skill is additive and idempotent — re-running on a fully-optimized workspace must be a no-op.

When to invoke

• User types /harness-audit explicitly (installed as a plugin, the command is namespaced: /harness-audit:harness-audit).
• Do NOT auto-trigger on SessionStart, phrasing about "optimization", or related drift. The user owns the entry point.

Preconditions

• Current working directory must equal the workspace being audited. Phase 1 inventory commands (ls, find, cat .claude/settings.json, git log, etc.) all run relative to cwd. To audit a workspace other than the one this session was launched in, open a new Claude Code session there — do not attempt to drive the audit from a parent session via cd prefixes, since phase 4 plan paths and phase 5 dispatch inherit cwd implicitly.
• Codex availability is detected at phase 5. The check inspects user-level and workspace-level settings plus PATH. If Codex isn't available in the dispatching session, the skill falls back to a manual-task instruction list — see phase 5.
• Superpowers availability is detected at phase 4. The big-work path prefers superpowers:writing-plans; if the Superpowers plugin isn't enabled, the skill falls back to built-in plan mode with a full plan document — see phase 4. Neither Codex nor Superpowers is a hard dependency: every phase has a fallback that uses only built-in tools.

References

This file is the procedure. The content lives in three reference files loaded on demand:

• references/framework.md — frozen snapshot of the Strategic Framework. Canonical definition of the 5 layers.
• references/common-traps.md — 15 universal traps + the Codex flag-loop guard prompt for phase 5.
• references/inventory-checklist.md — per-layer cheat sheet for phase 1.

Read each reference at the start of the phase that uses it. Do NOT pre-load them at skill discovery.

Precedence: where framework.md and common-traps.md conflict, the traps file wins. Two known conflicts: (1) framework §3.2 describes a Stop hook that "writes optimized, fresh learnings back into the corresponding CLAUDE.md" — trap #6 classifies silent governance-file writes as an antipattern; audit against trap #6. (2) framework §5 Phase 1 recommends .agentignore files — Claude Code has no .agentignore mechanism; read that as .gitignore hygiene plus permissions.deny path rules in .claude/settings.json.

Phase 1 — Inventory (read-only)

Read references/inventory-checklist.md first.

Walk the workspace and build a structured inventory in your context. Output: a Markdown table with one row per inventory category, columns for "what's there" and "shape signal".

Concrete checks

# Workspace metadata
ls -la                                          # top-level layout
# CLAUDE.md hierarchy — full depth, pruning vendored/generated trees
# (a monorepo's sub-CLAUDE.md can sit 3+ levels deep; -maxdepth 2 misses it)
find . \( -name node_modules -o -name .venv -o -name venv -o -name vendor \
       -o -name .git -o -name dist -o -name build -o -name target \) -prune \
       -o -name 'CLAUDE.md' -print
cat .claude/settings.json 2>/dev/null           # tracked harness state
cat .claude/settings.local.json 2>/dev/null     # per-user overlay
ls .claude/agents/ 2>/dev/null                  # subagent definitions
ls .claude/skills/ 2>/dev/null                  # project-scoped skills
ls .claude/commands/ 2>/dev/null                # project slash commands
cat .gitignore 2>/dev/null                      # protection coverage

# Stack detection
ls pyproject.toml setup.py package.json Cargo.toml go.mod 2>/dev/null

# Activity + scale
git log --oneline -10 2>/dev/null
git log --format='%ae' -100 2>/dev/null | sort -u | wc -l   # team signal
git status --porcelain                                       # dirty baseline?

# MCP servers
# Layer 5 hermetic scoring rule: score only workspace-owned .mcp.json; treat claude mcp list as environment context, never as workspace gap evidence.
cat .mcp.json 2>/dev/null   # workspace-owned MCP config; the only L5 scoring input
claude mcp list 2>/dev/null # all scopes; environment context only, never scored

For each hook entry in .claude/settings.json, confirm the referenced script exists and read the first 20 lines to characterize its shape (does it filter by suffix? does it use walk-base resolution? does it write to governance files?).

No writes in this phase.

Phase 2 — Gap report (read-only)

Read references/framework.md and references/common-traps.md first.

Compare the inventory against the 5 layers + 15 traps. Emit a Markdown table with columns:

• Layer / Trap — L1 CLAUDE.md, L2 Hooks, L3 Skills/Commands/Agents, L4 Plugins, L5 MCP, Trap N.
• Status — ✅ Present and working / ⚠️ Sub-optimal / ❌ Missing / 🚫 Out of scope for this workspace's scale.
• Finding — what was observed.
• Why it's a gap — connect to the framework / trap reference.
• Cost-benefit — S / M / L estimate of effort vs. value.
• Proposed fix (high-level) — one sentence.

After the table, list any non-framework checks (cleanup pass, CI hygiene, self-improvement loop wired — see end of inventory-checklist.md) as separate gap entries.

Gate 1

Present the gap report to the user. Ask:

"Proceed with all N gaps? Refine scope (drop some)? Or end here?"

If declined or scope refined, loop back to phase 1 with the new scope. If empty (zero gaps), report "Workspace already aligned with the 5-layer framework — no work to do" and stop.

Phase 3 — Magnitude classify

Apply the two-tier split (CLAUDE.md rule #6 in workspaces that have it; otherwise use the heuristic below):

• Big work — any single fix needs a written spec to be reviewable (e.g., new self-improvement loop with new scripts + new skill + new memory), OR total task count > 5.
• Small/medium work — otherwise.

Announce the routing decision to the user verbatim:

"Audit found N gaps. M of them need a written spec OR total > 5 — routing through superpowers:writing-plans."

or

"Audit found N gaps. All single-file edits, total ≤ 5 — routing through built-in plan mode."

User can override the routing if they prefer the other path.

Phase 4 — Plan

Small/medium

Use built-in plan mode:

1. Call EnterPlanMode.
2. Write the plan to the path the harness provides.
3. Each task in the plan must be one of:
   • Direct Edit (single-file, single-change — the main agent handles it).
   • Codex dispatch (anything else — phase 5 dispatches codex:rescue per task).
4. Call ExitPlanMode.

Big

Check Superpowers availability first: run the plugin-enablement probe from phase 5 with superpowers in place of codex (no CLI check — Superpowers is a plugin only).

• Enabled → invoke superpowers:writing-plans to produce a plan at docs/superpowers/plans/YYYY-MM-DD-harness-audit-<workspace>.md. The writing-plans skill enforces TDD-shaped task decomposition; the audit just provides the gap list as input.
• Not enabled → fall back to built-in plan mode (same flow as small/medium), but write the plan at full spec fidelity: per-task file pointers, acceptance criteria, and a verification command for each task — the detail writing-plans would have enforced. Announce: "Superpowers not installed — using built-in plan mode with a full plan document."

Gate 2

Plan mode / writing-plans review IS the gate. User approves or sends back to phase 2 for scope refinement. If user rejects, do NOT silently re-plan — loop back explicitly.

Phase 5 — Execute

Codex availability check (run FIRST, before any task)

Detect whether codex:rescue is available:

# Two signals: the Codex plugin must be enabled AND the CLI must be on PATH.
# Enablement can live at user level (~/.claude/settings.json), workspace level
# (.claude/settings.json), or workspace-local (.claude/settings.local.json) —
# all three count; later scopes override earlier ones. Parse the JSON instead
# of grepping for a literal key: a string match breaks on minified or
# hand-formatted JSON and on marketplace renames (the part after '@' in the
# plugin key varies by marketplace).
python3 - <<'EOF'
import json, os
enabled = {}
for p in [os.path.expanduser("~/.claude/settings.json"),
          ".claude/settings.json", ".claude/settings.local.json"]:
    try:
        with open(p) as f:
            enabled.update(json.load(f).get("enabledPlugins") or {})
    except (OSError, ValueError):
        pass
ok = any(k.split("@")[0] == "codex" and v for k, v in enabled.items())
print(f"PLUGIN={'yes' if ok else 'no'}")
EOF
command -v codex >/dev/null 2>&1 && echo "CLI=yes" || echo "CLI=no"

• Both yes → Codex path. Proceed to the dispatch loop below.
• Either no → Manual fallback. Do NOT hard-fail. Emit a per-task instruction list:
  • For each task in the plan, write a Markdown checklist entry to a temp file at <workspace>/.claude/harness-audit-manual-tasks.md (or surface inline if the workspace is read-only).
  • Each entry: task description verbatim from the plan, relevant file pointers, the change to make.
  • Surface to the user: "Codex unavailable (plugin: <yes/no>, CLI: <yes/no>). Wrote N manual tasks to <path>. Install Codex or apply tasks manually, then re-run /harness-audit to verify."
  • Skip phase 6 in manual-fallback mode — the user controls when to verify.

Codex dispatch loop (only if availability check passed)

Per task in the approved plan:

1. Trivial task (single Edit closes it cleanly — typo, gitignore line, single setting key) → main agent does it directly.
2. Non-trivial task → dispatch codex:rescue with:
   • The task description from the plan.
   • The relevant file pointers (paths + line ranges).
   • The Codex flag-loop guard prompt verbatim from references/common-traps.md (the fenced block at the top of that file).
   • Hard invariants the rescue must preserve (existing tests pass; existing rules preserved; etc.).
3. After each Codex return:
   • Read the diff.
   • Run associated tests (auto-detect: pytest, npm test, cargo test, go test).
   • Proceed to next task.

No per-task user gate — the plan approved at phase 4 is the mandate.

Halt conditions

• A Codex task fails → halt, surface failure to user, do NOT hand-fix, do NOT retry.
• Two consecutive Codex rescues flag the same class on the same finding → halt, surface as a Codex disagreement loop, ask user for direction (per trap #1).
• A test regression appears → halt, surface, user decides revert vs. continue.

Phase 6 — Verify

• Auto-detect and run the workspace's test runner (pytest, npm test, cargo test, go test, etc.). Capture pass/fail counts.
• git status --porcelain — confirm the working-tree delta matches the plan's intended changes (no surprise files).

• Produce a one-paragraph summary for the user:

  "Audited <workspace>. Closed N gaps across layers L1-L5 + M non-framework items. Files touched: <count>. Tests: <pre>→<post> passing. Remaining deferred: <list>."

Optional: persist a per-workspace memory entry

If the workspace has a memory directory under ~/.claude/projects/-<slugified-workspace-path>/memory/, append an entry:

- [Harness Audit YYYY-MM-DD](harness_audit_YYYY_MM_DD.md) — gaps closed: <list>; deferred: <list>

Otherwise skip silently.

Hard rules

1. Additive and idempotent. Re-running on an optimized workspace is a no-op. Never apply templates over custom content.
2. Phases 1-3 are read-only. No file writes, no git ops, no settings edits.
3. Phase 5 uses codex:rescue for non-trivial work. Never hand-fix multi-step changes.
4. Respect existing rules. Do not delete or rewrite custom CLAUDE.md rules. Adding new rules is fine; removing requires user confirmation.
5. References load on demand. Read each reference at the start of the phase that uses it.
6. The Codex flag-loop guard prompt is non-negotiable. Include it verbatim in every codex:rescue dispatch from phase 5.

Error semantics