npm package: @spekn/check
Description: Governance Health Score scanner for any repository
Author: Spekn
Latest version: 0.0.7

# @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

```bash
# 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:

```json
{
  "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:

```bash
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:

```typescript
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