tiny-spec

<img src="images/logo.png" alt="tiny-spec" width="200">

<h1 align="center">tiny-spec</h1>

<a href="https://pypi.org/project/tiny-spec/"><img src="https://img.shields.io/pypi/v/tiny-spec.svg?color=d97757" alt="PyPI version"></a> <a href="https://pypi.org/project/tiny-spec/"><img src="https://img.shields.io/pypi/dm/tiny-spec.svg?color=d97757" alt="PyPI downloads"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a> <a href="https://docs.claude.com/en/docs/claude-code/overview"><img src="https://img.shields.io/badge/Claude%20Code-skills-d97757.svg" alt="Claude Code"></a> <a href="https://github.com/GrayMa77er/tiny-spec/stargazers"><img src="https://img.shields.io/github/stars/GrayMa77er/tiny-spec?color=d97757" alt="Stars"></a>

<code>uvx tiny-spec install</code>

<!-- DEMO GIF SLOT — images/demo.gif Record the FAIL -> fix -> PASS loop, then uncomment: <img src="images/demo.gif" alt="tiny-spec build loop: the reviewer fails a task, the executor fixes it, the task commits" width="800"> -->

tiny-spec is a four-step workflow for Claude Code that turns a ticket into shipped, reviewed code. You write the intent, it produces a design, a task list, and then builds the work one task at a time. Every task is implemented by one agent and graded by an independent reviewer that runs the real tests before anything is committed.

That core is three skills and two agents. In front of it sit two front doors — pick the one that matches where you're starting. Over the top sits one router, tiny-spec-run, which drives the chain and, when you ask it to, works a whole list of features through to merged code. No config file, no build step.

   GREENFIELD                        BROWNFIELD
   starting from an idea             starting from a codebase
   tiny-spec-scope                   tiny-spec-adopt
   idea → Features                   real code → constitution
   BREAKDOWN.md                      constitution.md
            \                         /
             └───────────┬───────────┘
                         ▼
   tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-build
   intent               design + tasks      per-task loop
   SPEC.md              PLAN.md             plan → implement
                        (+ ## Tasks)        → review → commit

   tiny-spec-run      one router. Walks the chain and stops before build —
                      or, asked to, builds each feature and merges it.
   tiny-spec-design   optional. Wireframes → tokens + gradeable screens.

Pick one front door, once per project. Starting from an idea with no code yet? Run tiny-spec-scope — it interviews the idea into a BREAKDOWN.md, a flat list of well-defined Features with draft acceptance criteria. Working in a codebase that already exists? Run tiny-spec-adopt — it reads your repo and derives the constitution from what's actually there: your real lint and test commands, your real layout, your real conventions. Have a single known ticket in a project that's already set up? Skip both and start at tiny-spec-create.

Already have a PRD? Commit it as PRD.md (or name its path) and ask /tiny-spec-run to build it. The run carves the PRD into features with tiny-spec-scope, then for each feature it cuts a branch, specs it from the PRD and the breakdown (asking you only what they leave open), drafts the plan in plan mode for you to approve, and builds it once you do.

Neither builds anything. They set the project up so the three core skills have something true to work from, and both write a regenerable file you can edit freely.

How small

Every other kit in this space is bigger. That is the whole pitch, so here is the receipt rather than the adjective:

The whole of tiny-spec is 2,195 lines of markdown across 7 skills and 2 agents. No config file, no build step, no orchestrator, no CLI to initialize a project — the skills are the product.

_{Counted on 2026-08-03 from each project's own repository, not its marketing copy — Spec Kit's templates/commands/, OpenSpec's skills/, BMAD's SKILL.md and customize.toml files on main. All three are far more popular than tiny-spec, and being smaller is a bet, not a proof of quality — re-run the counts yourself before believing them.}

Why it's small

Most spec frameworks are generous by default: many phases, many agents, many generated documents. tiny-spec makes the opposite bet — keep one safeguard, drop the rest. That safeguard is the independent reviewer, which exercises acceptance criteria end to end, because a green unit test suite is not the same as working software.

The case for staying small:

• Documents are context, and context isn't free. Every paragraph the agent has to hold is room it no longer has for your actual code. tiny-spec keeps the spine small — a constitution and a short memory — and injects only what each task needs.
• Real work is a ticket inside a system, not a greenfield repo. tiny-spec binds to a ticket and references your task platform instead of re-describing the world.
• Rigid pipelines fight the user. Mandatory phases impose ceremony on work that doesn't need it. The extra structure here is optional — add shape where it pays.
• More moving parts is more to maintain. Orchestrators, ownership contracts, and config files are themselves a system you have to keep in sync. Two agents are not.
• Generated docs can fake rigor. A folder of polished planning artifacts looks like progress, but the proof is the reviewer running your real tests before each commit.

That's the whole trade: where larger kits add machinery, tiny-spec adds one independent reviewer and stops.

Does the trade hold up?

Smaller is easy to claim, so the suite ships a harness that measures it. docs/eval/ runs tiny-spec headlessly on benchmark tasks in hermetic sandboxes, grades the produced code with held-out tests the suite never sees, and checks the reviewer's own verdict against that ground truth. The number that matters is false-PASS rate — how often the gate blesses code that is actually broken.

Most recent run — 5 benchmark tasks on v1.0.0:

Two earlier versions scored identically, which is the more interesting result: the loop is stable across releases rather than tuned to one commit — including through 1.0, which rebuilt the planning chain underneath it.

See docs/eval/README.md for the method and docs/sdd-evaluation-rubric.md for the rubric. Read both skeptically: it is my benchmark, of my own tool, scored by me, on small self-contained tasks — so it measures the loop on well-specified work, not large-codebase performance. The harness is in the repo so you don't have to take my word for it.

New to spec-driven development?

Spec-driven development (SDD) means writing down what you want and why before any code exists, then letting that spec drive the build. Instead of prompting an agent and hoping, you hand it a small, explicit contract — the intent, a design, and an ordered list of tasks. The payoff: the agent stops guessing, you review the plan before a line is written, and the result is checked against the spec rather than vibes.

Quickstart

Install the skills and agents into your Claude Code config with uv:

uvx tiny-spec install

Restart Claude Code so it picks up the new skills, then run the flow in your project:

/tiny-spec-scope     # starting from an idea: interview it into features (BREAKDOWN.md)
/tiny-spec-adopt     # starting from a codebase: derive the constitution from real code
/tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
/tiny-spec-plan      # design it, harden the constitution, slice the task list
/tiny-spec-build     # build each task: implement, review, commit

Run one of the two front doors once per project, then create → plan → build per ticket. Or let the router drive:

/tiny-spec-run       # walks the chain, reconciling anything stale; stops before build
/tiny-spec-build     # build each task: implement, review, commit

tiny-spec-run resolves where your work stands and invokes whichever skill moves it forward. It writes nothing itself, it only delegates. By default it stops before tiny-spec-build — that's where you actually review the work.

Ask it to build and it goes all the way instead:

/tiny-spec-run build the backlog     # per feature: branch → plan → build → merge → next

It reads your BREAKDOWN.md (or a list you paste) and works the features one after another, merging each finished branch into main locally before starting the next — until it's done or reaches a terminal state it names out loud. See Working a whole list. Which of the two it does is decided from your opening request and never changes mid-run — a run you started as "get it ready" will not talk itself into building.

Building from a mockup? Run /tiny-spec-design after create. Commit your exports to design/ first; it reads what's there and asks which screens this ticket covers. Designs, if you have them walks through it.

Re-run install any time to update; tiny-spec uninstall removes only what it installed, and tiny-spec version prints the installed version. Each skill is copied (not symlinked) so every install is self-contained.

The skills and agents are plain markdown — copy them in by hand. Claude Code loads skills from ~/.claude/skills/ and agents from ~/.claude/agents/:

git clone https://github.com/GrayMa77er/tiny-spec.git
cd tiny-spec

mkdir -p "$HOME/.claude/skills" "$HOME/.claude/agents"
for s in tiny-spec-scope tiny-spec-adopt tiny-spec-run tiny-spec-create tiny-spec-design tiny-spec-plan tiny-spec-build; do
  cp -R "$s" "$HOME/.claude/skills/$s"
done
cp agents/*.md "$HOME/.claude/agents/"

If a skill name collides with one you already have, rename these before copying, or install one set at a time.

The repo is also a plugin and a one-plugin marketplace. A plugin is the only way to load the suite into a Claude Code Project, whose cloud threads load plugins rather than ~/.claude/skills:

/plugin marketplace add GrayMa77er/tiny-spec
/plugin install tiny-spec@tiny-spec

Installed this way, everything is namespaced: /tiny-spec:tiny-spec-run, and the agents are tiny-spec:tiny-spec-build-executor / -reviewer (the build skill dispatches either form). Pick one install method. A plugin plus uvx tiny-spec install loads every skill twice.

The plugin also carries the in-session run view (/tiny-spec), which needs Claude Code v2.1.287 or later. Older versions load the skills and agents and skip the view.

Watching a run

A long build-through run is easier to follow with a view of it. There are two, and both read only git and .spec/. They write nothing and keep no state file, so you can close them at any point and lose nothing.

• In Claude Code: /tiny-spec (plugin install, Claude Code v2.1.287+). A one-line band above the prompt appears while a run is in flight, showing the batch, each active feature's progress, and how many executor or reviewer agents are running right now. /tiny-spec opens a pane with Run / Graph / Report / Explorer tabs.
• In a browser: uvx tiny-spec view. It serves the same four tabs on 127.0.0.1 and refreshes every few seconds. Tick watch PRs to also git fetch and gh pr list once a minute, so a run happening in a Project's cloud threads shows up on your laptop, branch by branch.

uvx tiny-spec state --pretty prints the same derived state as JSON.

See a finished run first

examples/todo-cli/ is a real run of the flow on one small ticket, committed verbatim — the TICKET.md that went in, the SPEC.md, PLAN.md and constitution.md the suite wrote, and the code and tests it produced. The tests pass; you can clone it and run the gate yourself.

How it works

The constitution (constitution.md) is the spine. tiny-spec-adopt derives it from your codebase, or tiny-spec-create seeds it from a short interview; tiny-spec-plan hardens it with concrete engineering rules, and every task's executor and reviewer read it whole. It holds your style, standards, invariants, definition of done, and verification commands.

On an existing codebase, deriving beats asking. Your test command, layout, and conventions are already written down — in package.json, in CI, in your linter config, in the shape of the tree. tiny-spec-adopt reads them, marks each section as declared or inferred so you know which parts to distrust, then runs the verification commands it derived and reports which went green. A gate that has never been run turns every future review into theatre.

Because it is project-wide the constitution can also go missing — deleted, or never committed — while your specs survive. Re-running tiny-spec-adopt (or tiny-spec-create, on a project with no code yet) repairs it, and marks completed tasks stale, since they were reviewed against a document that wasn't there.

Designs, if you have them

Wireframes usually get read once and forgotten. tiny-spec turns them into two durable things — a project-wide token system in the constitution, and a per-screen entry in the spec — so "does this look right?" becomes something the reviewer can fail a task on. Skip all of it for a CLI or a library; the constitution simply has no design section.

Designs enter by convention, not by argument. No skill takes a design flag or a path parameter. tiny-spec-design reads every file in design/ at your project root and asks which screens this ticket covers; you can also just hand it paths. Change an export later and tiny-spec-run notices — it re-hashes every anchored export on its way down the chain, and routes a mismatch back to tiny-spec-design, marking the spec stale exactly like editing a requirement.

1. Commit your exports. Any format an agent can read — a Figma export, an HTML mockup, an Excalidraw file, a photo of a whiteboard.

your-project/
  design/
    signup.png
    dashboard.png

2. tiny-spec-design looks at them and proposes a design system. Actually looks — they are read as images. It infers one coherent scale across all of them rather than measuring each screen separately, tells you what it rounded ("your wireframes had 19px and 21px — proposing space.5=20px for both"), and on your approval writes it into .spec/constitution.md:

## Design system
- color:  `color.surface.base` #FFFFFF · `color.text.default` #111111
          `color.text.muted` #6B7280 · `color.text.danger` #B91C1C
- space:  `space.1`=4px · `space.2`=8px · `space.4`=16px · `space.6`=24px
- type:   `type.heading.lg` 24px/600/1.25 · `type.body` 16px/400/1.5
          `type.caption` 13px/400/1.4
- states: every interactive surface defines default, focus, disabled, loading, empty, error

Since it is project-wide, every screen from here on speaks this vocabulary — and a redesign edits this one table instead of every file.

3. Each screen becomes a D<n> in SPEC.md, written in those token names:

## Design

- D1 — Signup form
  - source: figma.com/file/abc#node-12:34 (view-only)
  - export: design/signup.png
  - sha256: d21d6330648c504edeb924b5398bf7fb6485d3a4c1907e43d800970f39622a1d
  - layout: single centered column, max 420px; title → field → error → submit
  - elements:
    - card    `[data-testid="signup-card"]`   → space.6 padding, color.surface.base
    - title   `[data-testid="signup-title"]`  → type.heading.lg, space.4 below
    - field   `[data-testid="signup-email"]`  → type.body, space.2 below
    - error   `[data-testid="signup-error"]`  → type.caption, color.text.danger
  - states: error (caption under the field), loading (spinner replaces button label)

The selectors are a contract, not a hint — the reviewer measures exactly these, so your markup carries them verbatim. Prefer test ids over CSS classes: classes get renamed by refactors and mangled by CSS-in-JS, and a selector that silently stops matching is the failure this exists to prevent.

4. Tag the tasks that build the surface — and only those, not the API call behind it. This is your blast radius:

- [ ] T4 — Build the signup form
  - acceptance: submitting a valid email advances to the verify step
  - design: D1

5. The reviewer measures it, then looks at it, and fails on both:

DESIGN: D1 — Signup form
  [data-testid="signup-card"]  padding 19px — not on the space.* scale (4/8/16/24)
  [data-testid="signup-email"] MISSING FROM DOM — never built, or renamed
  [data-testid="signup-error"] rgb(204,0,0) — color.text.danger is #B91C1C
  state "loading" never renders: button label stays "Continue", no spinner
  judge: read states default, error — compared against design/signup.png
    state "error": signup-error sits behind the card — every token right, and the
      user sees nothing where the export shows the red caption
    state "default": submit label "Create account" truncates to "Create acco…"
FINDINGS:
- flag: title/field gap feels tight (on-scale — does not fail the task)

Numbers first, and never a screenshot diff — pixel comparison goes flaky on font antialiasing and teams end up muting it. But no measurement catches an element that is present, on-token, and still not on screen: occluded, clipped, truncated, or the same color as what's behind it. So the last step reads a screenshot of each state next to your export and grades presence, legibility, and correspondence. Where a number already settled the question the eye may only flag, which keeps the two halves from contradicting each other — measurable or visible violations fail, taste comes back as flag: notes. A task with no design: tag is graded exactly as before.

tiny-spec ships no script — it can't know your stack. Write one, put it in the constitution's Verification commands, and the reviewer runs it:

## Verification commands
- test:   `npm test`
- visual: `node visual.mjs`

// visual.mjs — node visual.mjs '<selector>' ['<selector>'...]
import { chromium } from 'playwright';

const b = await chromium.launch({ channel: 'chrome' });   // your Chrome, no download
const p = await b.newPage({ viewport: { width: 900, height: 700 } });
await p.goto('http://localhost:3000/signup');             // your dev server + route

for (const sel of process.argv.slice(2)) {
  const el = await p.$(sel);
  if (!el) { console.log(`${sel}\n  MISSING FROM DOM`); continue; }   // required
  console.log(sel, JSON.stringify(await el.evaluate(n => {
    const c = getComputedStyle(n), r = n.getBoundingClientRect();
    return { padding: c.padding, margin: c.margin, fontSize: c.fontSize,
             fontWeight: c.fontWeight, lineHeight: c.lineHeight, color: c.color,
             background: c.backgroundColor, border: c.border,
             opacity: c.opacity, visibility: c.visibility,
             top: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) };
  })));
}

const state = process.env.STATE ?? 'default';      // however you drive states
const shot = `/tmp/visual-${state}.png`;
await p.screenshot({ path: shot, fullPage: true });
console.log('SCREENSHOT', state, shot);            // this line arms the judge

await b.close();

The missing-selector branch must print something — that is what turns a renamed element into a failure instead of a silent skip. top feeds the layout-order check, and opacity/visibility turn the cheapest kind of invisible element into a numeric failure. The SCREENSHOT line arms the judge; drop it and the numeric half still gates exactly as before, with the reviewer reporting judge: not run rather than quietly skipping it. Without a visual: command at all, a task tagged design: raises a blocker rather than passing quietly.

No Figma token, plugin, or design SaaS. A view-only account works fine: the committed export is what the agents read, and source: keeps the trail back. Change an export and its recorded sha256 stops matching, which marks the spec stale exactly like editing a requirement — so a design that moved under finished work can't pass unnoticed.

tiny-spec-build walks the task list top to bottom. Each task runs through one loop:

1. Plan the task against the constitution (inline, brief).
2. Implement it with a fresh tiny-spec-build-executor agent.
3. Review it with an independent tiny-spec-build-reviewer agent that runs the gate and grades against the constitution and the task's acceptance.
4. On pass, commit the code plus a checklist tick. On fail, loop back to the executor with the findings. After two failed attempts the run halts exhausted.

Every task's acceptance is exercised end to end, black-box, by the reviewer — that part never varies. What does vary is how much of the toolchain gets re-proven around it: a clean install → build runs on the first task, the last one, anything touching dependency or build config, and anything carrying design:; in between the reviewer runs lint and tests against the existing build. It escalates back to the full gate whenever the narrower one can't carry the verdict, and the authoritative clean run happens once more over the whole project as the final smoke. Re-installing from scratch on every task proved the same thing repeatedly and was the slowest part of the loop.

Both agents run on Sonnet by default. To change one for a single run, say so in the request, e.g. /tiny-spec-build executor on opus or reviewer on opus (or /tiny-spec-run build the backlog, reviewer on opus). To make it stick, set `TINY_SPEC_EXECUTOR_MODE