harness-score

Deterministic harness-maturity scanner for AI-assisted repositories — Cursor-first, zero LLM calls.

harness-score measures how well a repository is set up for reliable AI-assisted development: AGENTS.md, Cursor rules/skills/commands/subagents, hooks, tests/linters/types, CI, and secret hygiene. It scores 36 checks across 6 dimensions and reports a maturity level from L0 (Unharnessed) to L4 (Self-correcting).

The scan reads your filesystem and parses config — that's it. No network calls, no telemetry, no model in the loop. Same repo in, same score out, every time.

Repository discovery walks the complete relevant filesystem tree without a production depth cap, including tracked, untracked, and ignored files. Known dependency and generated directories are skipped, followed symlink targets must remain inside the scan root, and file bodies above 512 KiB are not read. A 1,000,000-file emergency fuse protects against pathological trees; reaching it, finding an out-of-root symlink, or encountering an unreadable relevant path marks the affected snapshot as incomplete instead of authoritative.

Full maturity model, check catalog, and remediation guide: paladini.github.io/harness-score

Install

# run once, no install
npx harness-score

# install globally
npm install -g harness-score
harness-score

# install as a dev dependency (recommended for CI reproducibility)
npm install --save-dev harness-score

Also published on GitHub Packages as @paladini/harness-score and on JSR for Deno/Bun users.

Usage

harness-score [path]              # human-readable report (default: cwd)
harness-score --json              # full report as JSON
harness-score --md report.md      # markdown report ("-" for stdout)
harness-score --badge badge.svg   # SVG pill: harness + detected level (L0–L4)
harness-score --min-level 3       # exit 1 if below L3 — the CI gate

Example:

  harness-score v1.0.0  /work/my-app

  Maturity: L2 · Guided   Score: 66/108 (61%)
  Detected: Cursor, Claude Code

  Context & Guides     ████████████████░░░░  80%
  Hooks & Guardrails   ░░░░░░░░░░░░░░░░░░░░   0%
  ...
  To reach L3: sensors ≥ 60%; ci ≥ 50%

Programmatic API

import { score } from 'harness-score';

const report = score('/path/to/repo');
console.log(report.level.index, report.level.name, report.score.percent);

Report, Check, DimensionScore, and every other shape are exported as TypeScript types, resolved via an explicit "types" field — no extra config needed in a consuming project. dist/ is a small, bundled build (tsup, ESM only); verified against attw and a packaging-level type smoke test in CI, and against a real npm pack install in an external project before each release.

CI gate

- run: npx harness-score --min-level 3

The exit status follows the snapshot selected by --gate. An incomplete gated snapshot exits 2. If maturity is complete and only an additional effective scope is incomplete, --gate maturity can still pass and reports the effective snapshot as unavailable. JSON output keeps incomplete values for diagnosis and marks their authority through verdicts.

Or use the packaged GitHub Action, which also emits the badge.

Two branded SVG formats (README badge + share card). Copy-paste embeds: Embed snippets. Gallery and CI wiring: Show your maturity.

Cursor plugin

Install Harness Score from its plugin directory in this repo for a /harness-audit command and a remediation skill that fixes gaps directly in your editor. (Cursor Marketplace listing submitted, pending review.)

License

MIT — github.com/paladini/harness-score