spec-lint

Analyze task specifications for AI agent readiness. Scores PRDs, tickets, and markdown specs for clarity, completeness, and executability.

Zero LLM dependencies — pure heuristic analysis that runs instantly, offline, in CI.

Why?

AI coding agents fail on vague specs. spec-lint catches ambiguity, missing sections, implicit assumptions, and untestable requirements before you hand a spec to an agent (or a human).

Install

npm install -g @phoenixaihub/spec-lint

Or use as a library:

npm install @phoenixaihub/spec-lint

CLI Usage

# Analyze a spec file
spec-lint analyze spec.md

# JSON output (for CI/pipelines)
spec-lint analyze spec.md --json

# List all rules
spec-lint rules

Example Output

📋 Spec Readiness Report
━━━━━━━━━━━━━━━━━━━━━━━━
Score: 42/100 (NOT READY)

❌ 🔍 Clarity: 35/100
  • Line 12: "handle edge cases appropriately" — vague, list specific edge cases to handle
  • Line 28: "should be fast" — vague, define latency target in ms

❌ 📋 Completeness: 45/100
  • Missing: acceptance criteria
  • Missing: error handling specification
  • Missing: input validation rules

⚠️ 🤔 Assumptions: 60/100
  • Line 5: "the database" — Which database? Connection details?
  • Line 15: "the API" — Which endpoint? Auth method?

✅ 🧪 Testability: 72/100
  • 3 of 5 requirements have measurable assertions

Exit code 0 = ready (score ≥ 70), 1 = not ready.

Library Usage

import { analyze } from '@phoenixaihub/spec-lint';

const spec = `
# My Feature
The system should handle requests and return appropriate responses.
`;

const result = analyze(spec, 'feature.md');

console.log(result.score);        // 42
console.log(result.ready);        // false
console.log(result.categories);   // { clarity: {...}, completeness: {...}, ... }
console.log(result.summary);      // "42/100 (NOT READY)"

Configuration

const result = analyze(spec, 'spec.md', {
  threshold: 80,                    // Custom readiness threshold (default: 70)
  rules: {
    'no-passive-voice': false,      // Disable specific rules
  },
});

Scoring

| Category | Weight | What it checks | |----------|--------|----------------| | Completeness | 30% | Required sections, input/output definitions, error handling | | Clarity | 25% | Vague language, passive voice, undefined pronouns, TODOs | | Assumptions | 15% | Implicit references, assumed knowledge, undefined acronyms | | Testability | 15% | Measurable criteria, examples, expected outputs, boundary values | | Edge Cases | 15% | Null handling, concurrency, timeouts, large inputs |

Rules (25 built-in)

Clarity (5 rules)

• no-vague-language — Detects "should work well", "as needed", "etc.", and 20+ vague patterns
• no-passive-voice — Flags passive voice that obscures responsibility
• no-undefined-pronouns — Catches "it should", "this must" without clear antecedents
• no-unclear-quantifiers — Flags "many", "some", "a lot" without specifics
• no-todo-placeholders — Catches TODO, TBD, FIXME, XXX placeholders

Completeness (5 rules)

• required-sections — Checks for acceptance criteria, error handling, I/O definitions
• input-validation — Ensures inputs have validation rules
• environment-spec — Checks for runtime/environment requirements
• auth-spec — Ensures auth mentions include implementation details
• data-model — Checks that data entities are defined

Assumptions (5 rules)

• no-implicit-references — Catches "the database", "the API" without specifics
• no-assumed-knowledge — Flags "obviously", "of course", "as you know"
• no-undefined-acronyms — Detects acronyms without definitions
• no-implicit-ordering — Suggests numbered lists for sequential steps
• no-platform-assumptions — Catches OS-specific paths without platform spec

Testability (5 rules)

• measurable-criteria — Checks if requirements have testable assertions
• has-examples — Looks for concrete examples or sample data
• expected-output — Ensures output format/structure is defined
• success-failure-defined — Checks both success and failure paths exist
• boundary-values — Looks for min/max/limit specifications

Edge Cases (5 rules)

• null-empty-handling — Checks for null/empty/undefined handling
• concurrency-handling — Flags write ops without concurrency strategy
• timeout-handling — Checks external calls have timeout/retry specs
• large-input-handling — Looks for pagination/batching strategy
• undiscovered-edge-cases — Suggests edge cases based on domain patterns

GitHub Actions

- name: Lint spec
  run: npx @phoenixaihub/spec-lint analyze spec.md

The CLI exits with code 1 when the spec isn't ready, failing your CI pipeline.

Contributing

See CONTRIBUTING.md.

License

MIT