This is the first entry in a new track: real, downloadable tools from the spec-driven development (SDD) practice, not just field reports about it. Free while this track finds its readers, eventually the deeper installments here become a paid tier. This one is a small script called spec-lint, and it exists to catch the exact failure mode that costs you the most time with an AI coding agent: a specification vague enough that the agent has to guess.
The Problem It Catches
A spec that says a feature "should" work a certain way, or that a case will be "handled appropriately," reads fine to a person, because a person fills the gap with judgment. An agent fills the gap by picking something plausible and building on it. The failure shows up two steps downstream, dressed as a different bug entirely.
spec-lint checks a markdown spec for six required sections, four weak-language patterns, and any unresolved TBD or TODO markers. It is not smart. It is a fast, mechanical first pass that stops the worst specs before an agent ever sees them.
| Check | What it catches |
|---|---|
| Required sections | Goals, non-goals, data contract, edge cases, rollback, quality gate |
| Weak language | "should," "might," "handle appropriately," "as needed" |
| Open markers | TBD, TODO, ??? |
Try It
Download spec-lint.js, no dependencies, one file. Run it against any markdown spec:
node spec-lint.js path/to/spec.md
Point it at a spec that just says "add an export button, handle errors appropriately, TBD on format," and it comes back with nine flagged issues: six missing sections, two weak-language hits, one open marker. Point it at the same spec once it names the data contract, lists the edge cases, and states a rollback plan, and it passes clean. The gap between those two runs is the gap between a spec an agent can execute and one that just looks like it can.
What This Track Becomes
This script is generic on purpose, adjust the required sections and weak-word list to your own template. The deeper installments in this track, sharper linting rules, a spec-quality scoring rubric, the actual review-agent pattern, are the ones that eventually sit behind a paid tier. For now the whole track is free, because a paid tier with no readers is just a wall. Subscribe, use the tool, and tell me what it misses.