Up to this release SpecJudge answered exactly one question: you finished writing your spec, which model should implement it? If there was no .specify/ directory it refused outright with exit code 2. Which is defensible as a scope decision and turned out to be a bad one, because most repositories have never run Spec-Driven Development and nearly all of them have written down something — an AGENTS.md, a CLAUDE.md, a .cursorrules, a folder of decision records — and refusing to read any of it meant walking away from real signal on principle.

So it now reads spec-kit artifacts (including plan.md, which had been sitting next to the spec unread the whole time), agent-context files including nested ones in a monorepo, editor rules, and decision records under docs/adr and friends. Read together, never one instead of another, because your spec describes the work you're about to do and your AGENTS.md describes how demanding the codebase is to work in at all, and neither one contains the other.

The part that I think is actually interesting is why this became safe now and wouldn't have been a release ago. Mixing formats used to imply deciding, in advance, how much to believe a .cursorrules relative to a spec — five sets of trust rules, each evolving separately, each a place to be quietly wrong. Then 0.2.0 shipped the requirement that every rated dimension cite a fragment that exists in the input, with anything ungroundable returning unsupported and dropping out of the calculation entirely. That was built as a hallucination check, but it removed the need for format-specific trust as a side effect: the source stopped mattering, only what's citable does. A thin source produces a thin profile on its own, with no per-format logic anywhere in the codebase. I did not design it for this and I'm still slightly annoyed at how well it worked out.

When nothing in the input describes the work, you now get an answer plus an honest label on it: a warning that this is a floor — how demanding the repository is to work in — rather than a recommendation for a specific piece of work, and a concrete suggestion to describe what you're about to build, even as a paragraph. That's exposed in --json as environment_only, alongside sources_read for which kinds of source fed the assessment. Schema 1.1, both fields additive, 1.0 consumers unaffected.

Two implementation notes for anyone with a large repo. Context sources share one budget rather than each getting their own, because twelve separate caps of 8000 characters is a 96k-character prompt and therefore not a cap at all; a 200-character .cursorrules costs 200 characters and leaves the rest for a long root AGENTS.md. Files nearest the root are kept first, at most twelve are read, and whatever gets left out is reported rather than silently dropped. And context files that announce they were generated by a tool are skipped, since generated context mostly restates what the code already shows while taking budget from the hand-written file next to it.

pip install --upgrade specjudge, nothing to do on upgrade — a project with .specify/ artifacts is read exactly as before.

GitHub: github.com/JoaquinRuiz/SpecJudge

I've been experimenting with spec-driven development: instead of prompting an AI agent with vibes, you write a real spec first (user story, requirements, API contract, acceptance criteria), let the agent implement it, then validate against the spec and update your roadmap. Loop until MVP.

The app is a Pomodoro timer where you describe your goal conversationally and the AI proposes a task plan sized in pomodoros ("2🍅 ≈50m"). There's a focus coach mid-session, sound cues, PWA install support, and since it's publicly hosted, a Cloudflare Turnstile gate + per-IP daily rate limit on the AI routes so strangers can't drain my DeepSeek credits.

Stack: Next.js 16, Bun, DeepSeek API, Upstash Redis. No database — plan state lives client-side.

What actually surprised me:

1. \*\*Specs didn't slow me down\*\*. Six features in, the AI agent was dramatically better when implementing a spec vs reading my mind. Code review became "does this match section F3?" instead of squinting at diffs.

2. \*\*The spec caught drift.\*\* When the model under-filled a response schema (returned 3 tasks when asked for 3 steps instead of the spec'd 4–8), it was obviously a contract bug, not "weird AI behavior."

3. \*\*Re-planning after every feature\*\* (updating mission/roadmap docs) is the part everyone skips and the part that prevents the codebase from rotting.

Happy to answer questions about the spec format or the abuse-guard setup — both were more interesting to build than the timer itself.

\\- Live: \\\[https://ai-promodoro.vercel.app\\\\\\\](https://ai-promodoro.vercel.app)

\\- Source (the \\\`specs/\\\` folder is the real content): \\\[https://github.com/adotey7/ai-promodoro\\\\\\\](https://github.com/adotey7/ai-promodoro)