@unityinflow/spec-linter

Lint CLAUDE.md and AI spec files — catches missing sections, secrets, and context bloat.

The Problem

CLAUDE.md, GEMINI.md, and AI spec files are written by hand with zero validation. Common mistakes:

• Missing required sections — the agent builds the wrong thing
• Accidentally committed API keys — security breach waiting to happen
• 80kb spec files — context window saturated, agent performance degrades

These mistakes degrade agent performance silently. No error is thrown. The agent just produces subtly wrong output.

Examples of Errors Caught

Missing required sections:

$ spec-linter check my-project/CLAUDE.md

my-project/CLAUDE.md
  error  Missing required section: "Project Overview"  (S001)
  error  Missing required section: "Acceptance Criteria"  (S001)

2 error(s), 0 warning(s)

Accidentally committed secret:

$ spec-linter check my-project/CLAUDE.md

my-project/CLAUDE.md
  :15 error  Possible OpenAI/Anthropic API key detected. Remove before committing.  (S003)

1 error(s), 0 warning(s)

Wildcard tool permissions:

$ spec-linter check my-project/CLAUDE.md

my-project/CLAUDE.md
  :42 error  Wildcard tool permission (Tool(*:*)) — use explicit tool names instead of wildcards.  (S005)

1 error(s), 0 warning(s)

Installation

npm install -g @unityinflow/spec-linter

Or run directly:

npx @unityinflow/spec-linter check CLAUDE.md

Usage

# Lint a specific file
spec-linter check CLAUDE.md

# Lint all spec files in current directory
spec-linter check .

# JSON output for CI
spec-linter check CLAUDE.md --format json

# Only show errors
spec-linter check CLAUDE.md --quiet

# List available rules
spec-linter rules

Rules

| ID | Name | Severity | Description | |---|---|---|---| | S001 | required-sections | error | Must have: Project Overview, Constraints, Acceptance Criteria | | S003 | no-secrets | error | No API keys, tokens, or private keys | | S004 | file-size | warning | >30kb warns, >50kb errors (context bloat) | | S005 | no-wildcard-permissions | error | No Bash(*:*) or "*" in tool permissions | | S006 | no-duplicate-headers | warning | No duplicate section headings at same level |

Exit Codes

• 0 — all checks passed
• 1 — errors found
• 2 — warnings only

License

MIT