aispekt

Install

The tool is a single native binary (Rust, ~1.4 MB, no runtime) — a full repo analysis takes about 20 ms.

bunx aispekt <path>
# or install globally
npm install -g aispekt

cargo install --locked \
  --git https://github.com/erf1nd0r/aispekt aispekt

Usage

aispekt <file-or-dir> [--json] [--min <score>]

Point it at a single CLAUDE.md/AGENTS.md — or at a repo directory to unlock repo-aware checks: dead commands the file references but package.json doesn't define, paths that don't exist, lines that just restate the README, and a missing CLAUDE.md ↔ AGENTS.md bridge.

Exit codes: 0 score ≥ min · 1 below min · 2 usage or I/O error — drop it straight into CI:

# fail the build when the instruction file degrades
bunx aispekt . --min 75

False positive on a heuristic? Suppress a single finding with an aispekt-ignore marker on the flagged line or the line above — like eslint-disable-next-line.

Semantic judge — bring your own agent

Some questions no regex can answer: is this rule dead weight for a strong model? Do two instructions semantically contradict? aispekt ships that layer without asking for an API key — the judge is whatever AI agent you already run.

aispekt judge emit AGENTS.md --out brief.json
# any judge completes the brief: an agent, a BYOK script, a human
aispekt judge merge brief.json answers.json

The brief is self-contained JSON: the file content, one task per semantic check (each with its evidence citation), and the exact answer contract. For agent users it's one command — aispekt skill install drops an Agent Skill (the open SKILL.md standard read by Claude Code, Codex CLI, Cursor, Gemini CLI, and more) into .claude/skills/; then "judge this file with aispekt" runs the loop with your agent as judge.

The honesty rules are structural: answers are hash-bound to the exact content judged, validated for verbatim quotes and real line numbers, and rendered as a separate judge-labeled tier with a non-determinism caveat — semantic verdicts can never move the deterministic score. Judge checks live in rules/judgepack.json, same doctrine as the rulepack: adding one is a data edit.

How scoring works

Scoring is penalty-only: you start at 100 and lose points for content the evidence says hurts (redundancy, lint rules stated as prose, vague aspirations, dead commands). Nothing adds points, because the 2026 evidence's predictive signals are negative — completeness bonuses push files toward measurable harm. A lean, command-focused file scores an A by simply not doing the harmful things.

Every rule carries a citation and a confidence tier: measured study official docs community heuristic. Rules the studies contradict are labeled heuristic — never presented as fact.

The rules

Rendered live from rules/rulepack.json — the same versioned data file the CLI embeds. Updating the rubric is a data edit, not a code change.

Playground

Try the analyzer without installing anything — this is the same Rust engine compiled to WebAssembly, running entirely in your browser. Nothing is uploaded, ever.