jev-spec
CLI and CI gate that asks Jev one yes/no question per Markdown requirement and fails the build when code drifts from the spec.
Overview
jev-spec checks code against the requirements written in Markdown specification files and fails when they drift apart. Each requirement becomes one focused Noul question in a typed jev-spec.config.ts; Choice and Score rubrics are also available. Jev reads the spec and code once and returns a probability for every question in the same request, which is compared with thresholds you set. It can also ask whether the code introduces unspecified behaviour, such as a bypass header nobody specified.
It targets teams doing AI-assisted development where code changes faster than anyone rereads the spec, and is small enough for a pre-commit hook and strict enough for CI. The README contrasts it with prompting a general LLM, where you parse prose whose shape varies between runs. Output is a check report per target with pass/fail per requirement and a non-zero exit on failure. It is published on npm, supports Node and Bun, has CI, and is an independent project not affiliated with TypeSafe.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Yes / no | Does this code satisfy requirement REQ-X as written in the spec? | — |
| Yes / no | Does the code introduce behaviour the specification does not describe? | — |
How it works
- Map spec files to code files and requirements in jev-spec.config.ts
- Send spec and code with one Noul per requirement in a single request
- Compare each probability with its threshold (e.g. min 0.85)
- Print a report and exit non-zero on violations, blocking the commit or build
Strengths
- Numeric, threshold-based gate instead of parsing prose
- One request answers all requirements for a target
- Fits in pre-commit hooks and CI
- Published npm package with CI
Caveats
- Probabilities need threshold tuning per project
- Requires a TypeSafe API key and sends code to the API
- Independent project, not affiliated with TypeSafe
Getting started
npx jev-spec checkAt a glance
- Type
- Project
- Status
- beta
- Language
- TypeScript
- Runtime
- Node / Bun CLI
- Has code
- yes
- Has tests
- yes
Use cases and integrations
How curated lists describe it
⚡ Catch spec drift on every commit: check your code against your Markdown specs with TypeSafe AI's Jev model.
hellogumbo/awesome-jevChecks each commit's code against the Markdown specs beside it and fails when they have drifted apart.
MrJev/awesome-jev
Frequently asked questions
What does jev-spec ask Jev?
One yes/no question per requirement asking whether the code satisfies it, plus optional checks for unspecified behaviour.
Why not just prompt an LLM?
The author notes LLM prose changes shape between runs and costs per token, which makes it awkward for a build gate.
How do I run it?
Run `npx jev-spec check` with a config file and a TypeSafe API key.
Related projects
Claude Code plugin with rules and checks that make agents prove their work; an optional Jev judge triages review findings.
PluginbetaMarkdown + shellSoftware-factory supervisor where Jev independently judges coding agents' completion, test sufficiency, progress and need for a human.
ProjectbetaPythonClaude Code plugin that scores a turn's redacted diff on eight Jev risk axes at Stop and asks Claude to reinvestigate once if high.
ProjectbetaGoClaude Code skills that wait for AI pull-request reviewers and judge whether their reports actually permit a merge, never inferring a pass.
ProjectbetaDesktop app running coding agents in parallel git worktrees, with optional Jev judgments of each changed file against the task.
AppbetaGitHub Action where an AI agent turns an issue into a PR behind guards, checks, a reviewer and a Jev gate that escalates when unsure.
ProjectprototypeTypeScript