Spec Linter

• 

  Actionable findings with exact file paths, sections, and implied task/test checks

• 

  Self-lint JSON output (ready: true, 0 errors) and 47/47 passing unit tests

• 

  Spec Linter catching cross-document contradictions and gaps on demo/broken-plan

Inspiration

AI-assisted development works best when project requirements are clear and consistent. We built Spec Linter to catch planning mistakes before they turn into coding problems.

What it does

Spec Linter is an offline Python CLI tool that checks scope.md, prd.md, spec.md, and checklist.md for missing information and contradictions. It provides actionable findings with file paths and helps developers validate their plans with one command.

Who it's for

Solo builders and learners who plan software with AI coding agents from a terminal and want deterministic, compiler-style checks on their planning documents before writing or shipping code.

How we built it

We built it with Python and automated tests, using transparent rule-based checks to validate project documents without requiring an internet connection or an AI API.

Challenges

One challenge was identifying inconsistencies across multiple documents while keeping the results clear and actionable. We also added JSON output to make results easier to inspect and automate.

What we learned

We learned how structured validation, clear planning documents, and automated tests can improve reliability in AI-assisted development.

Run It

Python 3.10+ standard library only (zero external packages, fully offline):

python3 -m spec_linter .                  # lint this repo's own plan (0 errors, ready: true, exit 0)
python3 -m spec_linter . --json           # structured JSON output
python3 -m spec_linter demo/broken-plan   # sample broken plan (5 errors, 3 warnings, 12 proposals, exit 1)
python3 -m unittest -q                    # 47 offline unit tests

Pre-Existing Material & License

• .claude/skills/ contains the unmodified official Devpost Learn Skill Pack (https://github.com/challengepost/learn-ai-basics, MIT License, Copyright (c) 2026 Devpost).
• All spec_linter/ code, 47 unit tests (tests/), demo/broken-plan/, planning docs (devpost/), and tools/ were newly created during the submission period under the MIT License (LICENSE).

Built With

• cli
• developer-tools
• markdown
• python
• static-analysis