spec-lint

A linter for spec-driven development. Checks that specification markdown files are complete, well-structured, and ready for implementation — by humans or AI agents.

Install

npm install -g @umxr/spec-lint

Usage

# Lint a single spec
spec-lint docs/specs/auth.md

# Lint all specs in a directory (recursive)
spec-lint docs/specs/

# JSON output for CI/agent consumption
spec-lint docs/specs/ --json

# Read from stdin
cat my-spec.md | spec-lint --stdin

# AI-powered semantic rules (requires ANTHROPIC_API_KEY)
spec-lint docs/specs/auth.md --ai

# Fail on warnings (default: fail on errors only)
spec-lint docs/specs/ --fail-on warning

# Custom config file
spec-lint docs/specs/ --config .speclintrc.json

# Verbose output
spec-lint docs/specs/ --verbose

Exit codes

Code	Meaning
0	All specs pass (or only info-level findings)
1	Errors found (or warnings, if --fail-on warning)
2	Usage error (bad arguments, missing files)

Rules

Structural rules (always run, fast, free)

Rule	Default	Description
has-required-sections	error	Spec must contain all required sections
sections-not-empty	error	Every section must have content
has-acceptance-criteria	error	At least one acceptance criterion must exist
acceptance-criteria-are-checkboxes	warning	Criteria should use - [ ] checkbox format
has-problem-statement	error	Problem section must be more than one sentence
no-todo-placeholders	warning	Flags TODO, TBD, FIXME, XXX, [placeholder], ...

Semantic rules (behind --ai flag, requires API key)

Rule	Default	Description
detect-vague-language	warning	Flags weasel words, vague quantifiers, and ambiguity
criteria-are-testable	warning	Checks if acceptance criteria can be objectively tested
suggest-missing-edge-cases	info	Suggests edge cases not covered in the spec

The detect-vague-language rule also includes a fast heuristic pass that works without an API key.

Configuration

Create a .speclintrc.json in your project root:

{
  "requiredSections": ["Problem", "Approach", "Acceptance Criteria"],
  "recommendedSections": ["Edge Cases", "Boundaries"],
  "rules": {
    "has-required-sections": "error",
    "sections-not-empty": "error",
    "has-acceptance-criteria": "error",
    "acceptance-criteria-are-checkboxes": "warning",
    "has-problem-statement": "error",
    "no-todo-placeholders": "warning",
    "detect-vague-language": "warning",
    "criteria-are-testable": "warning",
    "suggest-missing-edge-cases": "info"
  },
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Each rule can be set to "error", "warning", "info", or "off".

AI-powered rules

To use semantic rules, set the ANTHROPIC_API_KEY environment variable and pass the --ai flag:

export ANTHROPIC_API_KEY=your-key-here
spec-lint docs/specs/ --ai

If --ai is passed without a key, semantic rules are skipped gracefully (structural rules still run).

Output

Text (default)

docs/specs/auth.md
  ✗ error   has-required-sections    Missing required section: "Edge Cases"
  ✗ error   sections-not-empty       Section "Approach" is empty
  ⚠ warning no-todo-placeholders     Found "TODO" on line 23
  ✓ 3 rules passed

Summary: 1 file, 2 errors, 1 warning

JSON (--json)

{
  "files": [{
    "path": "docs/specs/auth.md",
    "results": [{
      "rule": "has-required-sections",
      "severity": "error",
      "message": "Missing required section: \"Edge Cases\"",
      "suggestion": "Add a ## Edge Cases section"
    }],
    "summary": { "errors": 2, "warnings": 1, "info": 0, "passed": 3 }
  }],
  "summary": { "files": 1, "errors": 2, "warnings": 1, "info": 0 }
}

License

MIT