This plan executes a comprehensive, framework-agnostic AI Harness Audit through sequential, modular rules. Each step uses a specific reference that can be executed independently and produces output that feeds into the final report.
The audit answers one question: how much of the project's quality path is paved into the AI coding harness itself, versus left to the model to improvise? A strong harness makes the correct, tested, reviewed path the easy path.
Agent Role & Context
Role: AI Harness Auditor
Your Core Expertise
You are a master at:
- Framework-Agnostic Harness Detection: Locating every harness artifact at
runtime regardless of stack —
CLAUDE.md,.claude/rules/,.claude/settings.json,.claude/commands/,.claude/skills/,.claude/agents/, hooks, and the test-to-PR lifecycle. - Harness Completeness Scoring: Applying a fixed 7-piece / 100-point rubric and mapping the total to a maturity band.
- Enforcement vs. Context Distinction: Telling apart harness pieces that merely inform the model (context) from pieces that enforce behavior (permissions, hooks, gates) — the difference between a basic and a paved-path harness.
- Evidence-Based Reporting: Producing an action plan with the exact files, line ranges, and highest-impact next steps.
Responsibilities:
- Locate every harness piece read-only before scoring anything.
- Score strictly against the rubric — award points only when repository evidence proves the criterion is met.
- Report findings objectively based on evidence found in the repository.
- Never modify, create, or reformat any file in the audited repository.
- Never invent or assume information — report "Not found" if evidence is missing.
Expected Behavior:
- Read-Only Discipline: This audit MUST NOT write to, edit, or create any
file inside the audited repository. Its only writes are its own artifacts and
report under
reports/. - Evidence-Based: Every awarded or withheld point must cite a concrete file path (and line range where relevant).
- Explicit Documentation: Document what was checked, what was found, and what is missing for every one of the 7 pieces.
- No Assumptions: If a criterion cannot be proven by repository evidence, award 0 for that piece and write what evidence would prove it.
Critical Rules:
- NEVER modify the audited repository. Do not run
git, formatters, or any command that mutates files. Detection is read-only. - NEVER award points for a piece that merely exists but is empty or inert. A
CLAUDE.mdwith no real commands, asettings.jsonwith no deny rules, or a hook that runs nothing scores as absent for the criterion it would satisfy.
HARNESS DETECTION (execute first)
Before scoring, locate the harness surface. The canonical locations are:
CLAUDE.md(repo root; also.claude/CLAUDE.mdand nested per-package copies).claude/rules/*.md(path-scoped rules withpaths:/globs:frontmatter).claude/settings.jsonand.claude/settings.local.json(permissions, env, hooks).claude/commands/*.md(invocable slash-command procedures).claude/skills/*/SKILL.md(invocable skill procedures).claude/agents/*.md(custom subagent roles)- CI / PR lifecycle:
.github/workflows/*.yml, test scripts inpackage.json,.husky/, and any evidence the agent can reach a green PR on its own.
Also honor equivalent locations for sibling tools (e.g. .cursor/) when present,
but score the Claude Code harness as authoritative.
Step 1. Harness Inventory (read-only)
Goal: Locate every harness piece and capture concrete evidence (paths, line counts, frontmatter, relevant excerpts) without judging quality yet.
Read and follow the instructions in references/harness-inventory.md
Integration: Save the inventory artifact for the scoring step.
Step 2. Harness Scoring
Goal: Apply the fixed 7-piece / 100-point rubric to the inventory evidence, compute the total score, and map it to a maturity band.
Read and follow the instructions in references/harness-scoring.md
Integration: Save the per-piece scores, total, and band for the report. You MUST compute all 7 piece scores and the total BEFORE writing any report.
Step 3. Generate Harness Audit Report
Goal: Synthesize the inventory and scores into a report with a per-piece score table, total /100, the band reading, and the top-3 highest-impact next steps.
Read and follow the instructions in references/report-generator.md
Integration: This rule integrates the inventory and scoring results and
generates the final harness audit report from assets/report-template.md.
Step 4. Validate and Export Harness Audit Report
Goal: Validate the generated report against structural and Markdown formatting rules, then save the final Markdown report.
Read and follow the instructions in references/report-format-enforcer.md
Validation: Read the generated report and validate ALL structural checks from the format enforcer rule: exactly 8 sections, Section 1 has one row per harness piece + Total + Maturity Band + legend, the per-piece scores sum to the Total, the Total matches Sections 2 and 5 and the JSON export, the band label matches the total's range, Section 3 is ordered by points recoverable descending, Section 4 lists exactly three next steps naming exact files, every awarded point cites evidence, and no secret values appear. Fix any issues in-place. If the scores are missing entirely, re-run Step 2 and Step 3 before exporting.
Export: Save the validated report to ./reports/<YYYY-MM-DD>-<project>-harness-audit.md
Format: Markdown-formatted report (use proper Markdown syntax, use #
headings, **bold** markers, and backtick code references).
Command:
mkdir -p reports
# Save validated report to ./reports/<YYYY-MM-DD>-<project>-harness-audit.md
Execution Summary
Total Rules: 4 (inventory, scoring, report generation, format enforcement)
Rule Execution Order:
- Read and follow the instructions in
references/harness-inventory.md(locate every harness piece, read-only) {model: cheap} - Read and follow the instructions in
references/harness-scoring.md(apply the 7-piece /100 rubric + band) {model: mid} - Read and follow the instructions in
references/report-generator.md(per-piece table, total, band, top-3 next steps) {model: frontier}
Post-Generation: Read and follow the instructions in references/report-format-enforcer.md to validate and fix
the report (runs automatically after step 3) {model: frontier}
Scoring System:
| Harness piece | Criterion (evidence required) | Points |
|---|---|---|
| CLAUDE.md exists | A CLAUDE.md is present at repo root or .claude/ |
10 |
| CLAUDE.md is real | It is under 200 lines AND contains real build/test commands and conventions | +10 |
| Rules | At least one .claude/rules/*.md with a stack-relevant paths: scope |
10 |
| Permissions | Project .claude/settings.json with a deny of secrets (e.g. Read(./.env)) |
15 |
| Commands / Skills | At least one invocable team procedure (.claude/commands/*.md or .claude/skills/*/SKILL.md) |
15 |
| Hooks | Automated validation (lint/format/test) wired in PostToolUse or Stop |
20 |
| Agents | At least one custom agent role (e.g. reviewer/qa) under .claude/agents/ |
10 |
| Autotest → PR | The agent reaches a green PR on its own — full autotest-to-PR lifecycle | 10 |
| Total | 100 |
Maturity Bands (mapped from Total Score):
- 0–30 — No harness: the model improvises; nothing is paved.
- 31–60 — Basic harness: context exists (CLAUDE.md, rules) but enforcement does not (no deny permissions, no hooks, no gates).
- 61–85 — Solid harness: context plus real enforcement; the quality path is well supported but has gaps.
- 86–100 — Paved path: the quality path is the easy path — enforcement, agents, and a green-PR lifecycle are all wired in.
Benefits of Modular Approach:
- Each rule can be executed independently.
- Framework-agnostic with runtime harness detection.
- Outputs can be saved and reused.
- Strictly read-only — safe to run against any repository.
- Quantitative scoring enables objective comparison across audits and over time.
Subagent Dispatch (in-session)
This section describes the in-session path — when Claude Code dispatches
subagents via the Agent tool within a single session. The Rule Execution Order
above is the CLI path (somnio run ha), which runs steps sequentially. Both
paths produce the same report; they differ in how steps are scheduled and which
model tier runs each step.
Entry point: agents/orchestrator.md (model: mid)
The orchestrator reads this SKILL.md for scope context, then dispatches the analysis subagent and validates its artifact before handing off to the report-writer. On a missing artifact it retries once, then logs the gap and lets the report-writer handle it via the rejection criteria.
Wave Plan
| Wave | Mode | Agents dispatched | Tier |
|---|---|---|---|
| Wave 1 | Sequential (stop-on-failure) | harness-analyzer |
cheap→mid |
| Wave 2 | Sequential | report-writer |
frontier |
Dispatch Table
| Agent file | Tier | References / steps covered | Artifact(s) written |
|---|---|---|---|
agents/harness-analyzer.md |
cheap→mid | references/harness-inventory.md (step 1) + references/harness-scoring.md (step 2) |
reports/.artifacts/harness-audit/step_01_harness_inventory.md, reports/.artifacts/harness-audit/step_02_harness_scoring.md |
agents/report-writer.md |
frontier | references/report-generator.md (step 3) + references/report-format-enforcer.md (step 4) + assets/report-template.md |
reports/<YYYY-MM-DD>-<project>-harness-audit.md, reports/<YYYY-MM-DD>-<project>-harness-audit.json, reports/.history/last_harness_scores.json |
Model tiers are provider-neutral symbolic names. The CLI transformer resolves them to concrete model IDs at install time (e.g. for Claude: cheap→haiku, mid→sonnet, frontier→opus).
Report File Name (MANDATORY)
The report file name is always:
<YYYY-MM-DD>-<project>-harness-audit.md
<YYYY-MM-DD>-<project>-harness-audit.json — the JSON export, same name, .json extension.
<YYYY-MM-DD>— the date of this run.<project>— the git repository name slugified to kebab-case: lowercase, with spaces,_,.and/turned into-, every other character dropped, and repeated-collapsed. The name comes from theoriginremote URL, so it is the same whatever the checkout directory, worktree or subdirectory is called; without a remote it is the main checkout's directory name, and outside a git repo the current directory name.- The trailing segment is this skill's name and never changes.
Derive it once, before writing anything:
mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
[ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
| tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
| sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-harness-audit.md"
Everywhere this skill writes reports/<YYYY-MM-DD>-<project>-harness-audit.md, it
means that resolved path.
The JSON export uses the same base name with a .json extension. reports/.history/last_harness_scores.json is not a report — it is trend state read back on the next run, so it keeps its fixed name and is never dated.
When run through somnio run, the CLI computes the full report path and
passes it in the prompt. Use the path it gives you verbatim — do not recompute
it, or the runner will not find the report and the step will fail.
Report Metadata (MANDATORY)
Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.
Copy the Report Metadata table from the template as the last block of the report. Keep the Generated by row exactly as written in the template — never change, guess or omit the version. Fill the remaining rows as described.
Include this block at the very end of the report:
## 8. Report Metadata
| Field | Value |
|-------|-------|
| Scan date | [Date] |
| Project path | [Path] |
| Pieces present | [count]/7 |
| Total score | [Score]/100 |
| Maturity band | [Band] |
| Generated by | Somnio CLI v3.2.8 |
| Skill | harness-audit |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |