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.

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

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