Mini-spec 2.0: Now with teeth

-

Three weeks ago I released mini-spec: a ~93-line skill for spec-driven development. The idea was simple—add a design layer between specs and code so you can catch AI hallucinations before they become phantom features.

It worked. But there was a problem: nothing enforced the workflow.

Claude could skip the requirements phase. It could forget to link requirements to design artifacts. It could mark things implemented that weren’t. The traceability was only as good as the AI’s attention span.

GitHub: https://github.com/zot/mini-spec

It’s still the same 3-level process but now the enforcement is way better:

Level 1: Specs      What you want (human-written)
Level 2: Design     What the AI understood (requirements, CRC cards, sequences)
Level 3: Code       What got built

The design level makes the AI’s interpretation explicit and reviewable before expensive code generation. Reviewing design documents is far cheaper than reviewing code.

What’s new in 2.0

The minispec CLI tool – automatically used by the mini-spec skill

A Go binary that validates your design structure:

minispec phase spec           # Verify spec files exist
minispec phase requirements   # Verify requirements.md format
minispec phase design         # Verify all Rn are covered by design artifacts
minispec phase implementation # Verify code has traceability comments
minispec validate             # Run everything

The tool catches:

  • Requirements not covered by any design artifact
  • CRC cards missing their Requirements field
  • Code files without traceability comments
  • Gaps section malformed
  • Design files not listed in Artifacts

This isn’t AI validation—it’s structural validation. The tool parses markdown and checks references. Fast, deterministic, no tokens burned.

requirements.md: The “nothing gets lost” layer

Before, specs linked directly to CRC cards. Now there’s an intermediate step:

specs/feature.md
    ↓
design/requirements.md    ← NEW: numbered requirements (R1, R2...)
    ↓
design/crc-*.md           ← References: R1, R3, R7
    ↓
src/*.ts                  ← Traceability comments

Every spec item becomes exactly one numbered requirement. Every CRC card declares which requirements it implements. The tool validates complete coverage.

Why this matters: When you have 50 spec items across 6 files, things get lost. A requirement might be clear in your head but never make it to design. Or it’s in design but no code implements it. Numbered requirements with tool validation close these gaps.

Phase gates

The skill now requires running minispec phase <name> after each workflow phase. Claude can’t jump from specs to implementation—it has to pass through requirements and design first, with validation at each step.

Mandatory task tracking

Before reading any files or doing any work, Claude must create tasks:

TaskCreate: "Spec Phase: user authentication"
TaskCreate: "Requirements Phase: user authentication"
TaskCreate: "Design Phase: user authentication"
TaskCreate: "Implementation Phase: user authentication"
...

This gives you real-time visibility into where Claude is in the workflow. You see tasks transition from pending → in_progress → completed. No more wondering “is it still designing or did it start coding?”

During implementation, Claude breaks down further into per-file tasks. You can watch progress file by file instead of waiting for a wall of code at the end.

Why a tool? Why not a database?

I considered several approaches:

Structured data (JSON/YAML/SQLite): Easier to parse, but harder to review. The whole point of mini-spec is human-readable design docs. If I can’t cat design/requirements.md and see what’s there, I’ve lost the plot.

AI-based validation: Burns tokens, non-deterministic, slow. The tool runs in milliseconds and gives the same answer every time.

No validation: What I had before. It worked until it didn’t.

A CLI tool parsing markdown threads the needle: design docs stay human-readable, but structure is enforced. The tool understands the format well enough to validate references and coverage without understanding intent.

The numbers

Metric Jan 7 (v0.9.3) Now (v2.1.0)
Skill lines ~93 ~267
Tool None ~2000 lines Go
Validation Manual Automated per-phase
Requirements Implicit Explicit, numbered
Progress visibility None Mandatory task tracking

The skill grew 3x because it now documents the requirements.md format, phase validation commands, and tool usage. Worth it for the guarantees.

What stayed the same

  • Three-level architecture (specs → design → code)
  • CRC cards, sequences, UI layouts
  • Traceability comments in code
  • Drift detection via Artifacts checkboxes
  • Gaps section for tracking discrepancies
  • Optional spec-agent for isolated context

Getting started

  1. Install the tool:

    # Download from https://github.com/zot/mini-spec/releases
chmod +x minispec
mv minispec ~/.claude/bin/

  2. Install the code-simplifier plugin:

    claude plugin install code-simplifier

  3. Copy mini-spec/ to your project’s .claude/skills/

  4. Write specs, then tell Claude: “/mini-spec design this”

Or if you already have mini-spec just tell claude, `update the mini-spec skill`!

The tool will keep Claude honest at every phase.

I've been using this heavily across four projects. It works. And the tool saves a lot of tokens by handling validation that would otherwise require AI parsing.

Comments

Post a Comment

Popular posts from this blog

Calculator/spreadsheet tool for Acme

-
I got Plan9 from User Space and started messing with it in the hopes of getting a nice toolbench going with Acme. Since I wrote Ober , I've been interested in this idea. Now, I'll probably rewrite it in Go. I'm wondering if I can just use named pipes to mimic what Acme does with its 9p interface. Anyway, I wrote a simplified version of the Calc tool I wrote for Ober and I put it, here . The calc tool searches an Acme window for variables and their values and some code at the bottom. Then, it executes the code, sending the variables and values to its stdin. The code is expected to output new values for some of the variables. Calc parses the output and replaces the new values into the window. I'm also including two wrappers that make it easy to write calc scripts in rc or Go, so you can say something like this: Bob's age=30, he is yearsleft=0 years away from retirement (calc). #!/usr/bin/env calcgo yearsleft = 55 - age If you middle-click "calc" in t...
Read more

Safe navigaion in Scala, take 2

-
OK, revisiting this topic after a very short time, I have a new implementation, again using that interesting anonymous class technique from James Iry's comment: implicit def richOption[T](x : T) = new { def ??[B](f : T => B):B = if (x != null) f(x) else null.asInstanceOf[B] } I changed the operator from "?!" to "??" because that's a lot easier to type and I chose "??" instead of "?" so people wouldn't confuse it with the questi-colon operator from Java and C. It's stand-alone (doesn't depend on Option or anything) and I had to use a cast to get the types to work out properly, but the test case from my last post does work println(p3??(_.bud)??(_.bud)??(_.bud)??(_.name.drop(1))) prints null and println(p3??(_.bud)??(_.bud)??(_.name.drop(1))) prints ubba. For those new to Scala, the expressions in parentheses are anonymous functions because they use "_" as identifiers. (_.bud) expands to (x => x.bud), where Sca...
Read more

Quick update on The Philosopher's Stone

-
I have changed TPS many times in the past year and a half, but the core idea is still to be a collaborative story telling RPG that feels like a traditional RPG. The latest version of it is called Death of the Vele and the (lame) website is here It has a link to the latest rules. Wow, taking a look at the old rules, I see that I have streamlined the mechanics a LOT since last year. They are simpler, lighter weight, and more intuitive. There are also tools to promote more integrated and structured stories (spotlights, hitting aspects, etc.). Death of the Vele also adds a back story (which you can remove if you don't like, of course). I'm hoping to publish Death of the Vele within the next 12 months. In the mean time, the rules are out there for free, so anyone who wants to can use them. Here is the feature list from the latest copy of the rules: Collaborative, but feels like a traditional RPG Your characters are yours Supports campaign-length stories Game play ...
Read more