Spec-driven development, built for coding agents.
misterspec is a Go binary that gives a coding agent a deterministic backbone — IDs, paths, fingerprints, structural validation, and a local context engine — so the agent can spend its own reasoning on what actually needs judgment, and nothing else.
A coding agent working from Markdown specs alone has to rediscover, every single time, things that are actually mechanical: what's the next free ID for a new Spec? Is this artifact's frontmatter well-formed? Does this file already exist? What does this Spec actually depend on, and what does that depend on? None of that requires judgment — it requires correct, repeatable computation. Doing it by reasoning instead of computing it is slow, and occasionally wrong in ways that are hard to notice (a duplicate ID, a drifted path, a stale fingerprint).
misterspec draws one hard line and never crosses it:
If an answer depends on what project information means,
the coding agent decides it. If an answer can be
computed from repository structure, the
misterspec binary computes it — and the agent calls
that operation instead of reasoning its way to the same answer.
Concretely: misterspec is a single static Go
binary. It owns ID allocation, canonical paths, content
fingerprints, structural validation, and — its most advanced
capability — a local, deterministic Context
Engine that retrieves exactly the project context a
given operation needs, ranked and budgeted, without the agent
re-exploring the whole repository by hand every time. Every one
of these is exposed as a stable, machine-readable JSON command
under a hidden misterspec internal … surface — see
the Command Reference. The agent's
own job — understanding requirements, designing a solution,
writing code — is never touched.
Every unit of work moves through the same fixed sequence of
Markdown-with-frontmatter artifacts, all stored under a
project's own ai/ directory:
A Constitution records the project's own non-negotiable rules. A Program groups related Features; each Feature decomposes into one or more Specs (requirements, testable and unambiguous). Each Spec gets a Plan (technical strategy) and Tasks (ordered, independently verifiable units of work); Implementation happens directly against the real repository; and Validation records, per requirement, whether it is genuinely satisfied — with real evidence, not intent. See the full workflow walkthrough for exactly which command drives each stage.
- Core Foundation — deterministic IDs, paths, fingerprints, atomic entity creation, structural validation.
- Agent Adapters & CLI — a Cobra-based CLI, an interactive setup TUI, and canonical Skill content for coding agents.
- The Context Engine — wikilinks with chunk-level provenance, a reference graph, a disposable BM25-ranked local search index, and intent-aware ranked/budgeted retrieval.
- Multi-Agent Skill Integration — six supported coding agents, all sharing the same canonical Skills.
- Dogfooding & Evaluation — the Context Engine tested against this project's own real development history, now backed by a reusable, CI-runnable evaluation harness.
Development continued past the MVP milestone —
misterspec --version/--update for
checking and self-updating the installed binary; robust,
punctuation-safe free-text search with real BM25 ranking; a
reusable evaluation harness (internal eval-retrieval/
internal eval-compare) for gating future retrieval
changes on evidence; and chunk-level wikilink provenance,
explaining exactly which artifact, section, and line justified
including something in a Context Pack. See the full
Command Reference for the
project's actual, current command surface.