@spekn/check

Governance Health Score for any repository.

Scans any repository and produces a Governance Health Score from 0 to 100, grading how well your project is set up for spec-driven development, agent collaboration, and long-term maintainability.

Quick Start

# Run with AI analysis (default)
npx @spekn/check

# Run without AI
npx @spekn/check --no-ai

What It Checks

| Check | Weight | Description | | --- | --- | --- | | Agent Context Depth | 40% | Evaluates CLAUDE.md, AGENTS.md, .claude/rules/, and multi-agent coverage | | Spec Traceability | 22% | Checks for specification documents, anchors, and code-spec linkage | | Governance Structure | 18% | Validates README, CONTRIBUTING, LICENSE, and project structure | | Decision Governance | 12% | Assesses ADR presence, format quality, and decision coverage | | Terminology | 8% | Detects naming drift against configured product terms |

Additional checks are planned for future releases.

Output Formats

• Terminal (default) -- color-coded summary with grade and findings
• JSON (--json) -- machine-readable output for CI pipelines
• Markdown (--md) -- suitable for embedding in PRs or reports

CLI Options

--with-ai [agent]   Enable AI analysis via agent (DEFAULT)
                     Supported: claude, codex, vibe, opencode, cline, gemini
--no-ai             Disable AI analysis
--fun               Enable emoji-rich output
--verbose           Show all findings
--no-color          Disable color output
--json              JSON output
--md                Markdown output
--out <file>        Write output to file
--config <path>     Custom config path
--version           Show version
--help              Show help

Configuration

Create a .speknrc.json file at the root of your repository to customize behavior:

{
  "ignore": ["vendor/", "dist/"],
  "checks": {
    "agentContextDepth": { "weight": 40, "enabled": true },
    "specTraceability": { "weight": 22, "enabled": true },
    "governanceStructure": { "weight": 18, "enabled": true },
    "decisionGovernance": { "weight": 12, "enabled": true },
    "terminology": { "weight": 8, "enabled": true }
  },
  "productName": "MyProduct"
}

• ignore -- paths to exclude from scanning.
• checks -- override the default weight or disable individual checks.
• productName -- the canonical product name used by the Terminology check.

AI Enhancement

By default, @spekn/check runs with AI analysis enabled (--with-ai). This uses the Agent Client Protocol (ACP) to connect to a supported coding agent and provide deeper, context-aware findings.

To run a purely static scan without any AI calls, pass --no-ai.

You can also target a specific agent:

npx @spekn/check --with-ai claude
npx @spekn/check --with-ai codex

Grading Scale

| Grade | Score Range | | --- | --- | | A | 90 -- 100 | | B | 75 -- 89 | | C | 60 -- 74 | | D | 40 -- 59 | | F | 0 -- 39 |

Programmatic API

You can use @spekn/check as a library in your own tools:

import { loadConfig, scanRepo, checks, calculateScore, assignGrade } from "@spekn/check";
import type { ReportData, CheckResult } from "@spekn/check";

const config = loadConfig("/path/to/repo");
const scan = scanRepo("/path/to/repo", config);
const results = checks.map(c => c.run({ repoPath: "/path/to/repo", config, scan }));
const score = calculateScore(results);
const grade = assignGrade(score);

License

MIT