tiny-spec 0.1.0__tar.gz → 0.3.0__tar.gz

{tiny_spec-0.1.0 → tiny_spec-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-spec
-Version: 0.1.0
+Version: 0.3.0
 Summary: A tiny, opinionated take on spec-driven development.
 Project-URL: Homepage, https://github.com/GrayMa77er/tiny-spec
 Project-URL: Source, https://github.com/GrayMa77er/tiny-spec
@@ -54,15 +54,31 @@ 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.
 
-It is four skills and two agents. No orchestrator, no config file, no build step.
+That core is **four skills and two agents**. In front of it sit **two optional
+planning on-ramps** — `tiny-spec-prd` (idea → PRD) and `tiny-spec-breakdown`
+(PRD → stories) — for when you're starting from an idea rather than a ready ticket.
+`tiny-spec-run` walks the three planning steps in one command. No config file, no
+build step.
 
 ```
-tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
-   intent               design             tasks            per-task loop
-   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
-                        constitution
+                                           ┌───────────────── tiny-spec-run ─────────────────┐
+                                           │     optional: one command, stops before build   │
+                                           ▼                                                 ▼
+PLANNING (optional on-ramps)              EXECUTION (the core loop, one story at a time)
+  tiny-spec-prd  ⇢  tiny-spec-breakdown ⇢  tiny-spec-create → tiny-spec-plan → tiny-spec-tasks → tiny-spec-build
+  idea → PRD        PRD → stories           intent             design           tasks            per-task loop
+  PRD.md            BREAKDOWN.md            SPEC.md            PLAN.md +        tasks.md         plan → implement → review → commit
+                                                              constitution
 ```
 
+The two on-ramps are **optional** and stack. Have nothing written down? Run
+`tiny-spec-prd` to interview your idea into a `PRD.md`. Have a PRD already? Run
+`tiny-spec-breakdown` to carve it into a `BREAKDOWN.md` — a flat list of
+Features → Stories with draft acceptance criteria. Have a single known piece of
+work? Skip both and start at `tiny-spec-create`. Both on-ramps write a regenerable
+file at your project root (not under `.spec/`); `tiny-spec-create` then reads the
+breakdown one story at a time.
+
 ## New to spec-driven development?
 
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -85,12 +101,26 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
-/tiny-spec-plan     # turn the spec into a design and harden the constitution
-/tiny-spec-tasks    # slice the plan into an ordered checklist
-/tiny-spec-build    # build each task: implement, review, commit
+/tiny-spec-prd       # optional: interview a rough idea into a PRD (PRD.md)
+/tiny-spec-breakdown # optional: carve a PRD + wireframes into stories (BREAKDOWN.md)
+/tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan      # turn the spec into a design and harden the constitution
+/tiny-spec-tasks     # slice the plan into an ordered checklist
+/tiny-spec-build     # build each task: implement, review, commit
+```
+
+Or collapse the three planning steps into one and go straight to building:
+
+```
+/tiny-spec-run       # create → plan → tasks in one pass; stops before build
+/tiny-spec-build     # build each task: implement, review, commit
 ```
 
+`tiny-spec-run` resolves where your ticket stands and invokes whichever of
+`create` / `plan` / `tasks` moves it forward, reconciling anything stale first. It
+**stops before `tiny-spec-build`** — that's where you actually review the work — and
+it writes nothing itself, it only delegates.
+
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
 installed. Each skill is copied (not symlinked) so every install is
 self-contained.
@@ -106,7 +136,7 @@ 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-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+for s in tiny-spec-prd tiny-spec-breakdown tiny-spec-run tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
   cp -R "$s" "$HOME/.claude/skills/$s"
 done
 cp agents/*.md "$HOME/.claude/agents/"
@@ -124,6 +154,33 @@ short interview, `tiny-spec-plan` hardens it with concrete engineering rules, an
 `tiny-spec-build` injects it whole into every task. It holds your style, standards,
 invariants, definition of done, and verification commands.
 
+Because it is project-wide it can also go missing — deleted, or never committed —
+while your specs survive. Re-running `tiny-spec-create` then repairs it: it rebuilds
+the constitution from whatever is already written down and marks completed tasks
+stale, since they were reviewed against a document that wasn't there.
+
+### Designs, if you have them
+
+Drop your exported wireframes in a `design/` directory and `tiny-spec-create` will
+look at them — actually look, they are read as images. From all of them together it
+proposes one coherent **design system** (spacing scale, type scale, color roles) for
+your approval and writes it into the constitution, then describes each screen as a
+`D<n>` entry in `SPEC.md`: its layout, its elements with a selector each, and the
+states it must render — all in those token names.
+
+The point is what happens at build time. Tag a task with `design: D1` and the
+reviewer renders that surface, measures the selectors the entry names, and **fails the
+task** on a value that isn't on your scale, an element that never got built, or a
+state the design calls for and the code doesn't render. It measures numbers rather
+than diffing screenshots, because pixel diffs go flaky and get muted. Tasks without a
+`design:` tag are graded exactly as before.
+
+No Figma token, no plugin, no design SaaS — a view-only Figma works fine, since the
+committed export is what the agents read and the `source:` link keeps the trail back.
+Change an export and its recorded hash stops matching, which marks the spec stale the
+same way editing a requirement does. Skip the whole thing for a CLI or a library; the
+constitution simply has no design section.
+
 `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).
@@ -147,11 +204,14 @@ flowchart TB
 
     CON([constitution.md]) -.-> P & I & R
     MEM([memory.md]) -.-> I & R
+    DES([SPEC.md D-n + design/ export]) -.->|only on a design: task| I & R
 ```
 
 Solid arrows are the flow. Dotted arrows show the persistent context injected into
 a step: the `constitution.md` goes into planning, implementation, and review, while
-`memory.md` is handed to the executor and reviewer.
+`memory.md` is handed to the executor and reviewer. A task tagged `design:` also
+carries its screen's `D<n>` entry into both agents — and the review step then runs
+the `visual:` gate on top of the usual one.
 
 A small `memory.md` carries operational lessons between runs, so the executor and
 reviewer (which start fresh each time) don't relearn the same pitfalls.
@@ -190,7 +250,7 @@ The case for staying small:
   optional by design — add shape where it pays, skip it where it doesn't.
 - **More moving parts is more to maintain.** Orchestrators, ownership contracts,
   checkpoint matrices, and config files are themselves a system you have to learn
-  and keep in sync. Four skills and two agents are not.
+  and keep in sync. A few small skills and two agents are not.
 - **Generated docs can fake rigor.** A folder of polished planning artifacts looks
   like progress, but it isn't proof. The proof is the reviewer running your real
   tests before each commit.
@@ -200,22 +260,26 @@ independent reviewer and stops.
 
 ## Project layout
 
-Each skill is self-contained. It carries its own templates and refers to them by
-relative path, with no absolute paths and no shared parent required at runtime, so
-a skill folder works wherever you drop it.
+Each skill is one self-contained `SKILL.md`, with every document skeleton inline in
+it — no companion template files, no absolute paths, and no shared parent required
+at runtime, so a skill works wherever you drop it. (It also means a run never stops
+to ask permission to read a template out of your Claude config directory.)
 
 tiny-spec creates a `.spec/` directory in your project root, never inside a skill.
 It is namespaced per ticket, with a shared spine at the root:
 
 ```
 .spec/
-  ACTIVE                    the active ticket directory name (resolution pointer)
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
     SPEC.md  PLAN.md  tasks.md  decisions.md
 ```
 
+`PRD.md`, `BREAKDOWN.md`, and `design/` sit at your project root rather than inside
+`.spec/`, because they are yours: the first two are regenerable pre-spec planning
+files, and the design exports are project files no skill ever writes.
+
 `CONTRACTS.md` documents the formats for maintainers. The skills do not read it at
 runtime; each is self-sufficient.
 

{tiny_spec-0.1.0 → tiny_spec-0.3.0}/README.md

@@ -17,15 +17,31 @@ 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.
 
-It is four skills and two agents. No orchestrator, no config file, no build step.
+That core is **four skills and two agents**. In front of it sit **two optional
+planning on-ramps** — `tiny-spec-prd` (idea → PRD) and `tiny-spec-breakdown`
+(PRD → stories) — for when you're starting from an idea rather than a ready ticket.
+`tiny-spec-run` walks the three planning steps in one command. No config file, no
+build step.
 
 ```
-tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
-   intent               design             tasks            per-task loop
-   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
-                        constitution
+                                           ┌───────────────── tiny-spec-run ─────────────────┐
+                                           │     optional: one command, stops before build   │
+                                           ▼                                                 ▼
+PLANNING (optional on-ramps)              EXECUTION (the core loop, one story at a time)
+  tiny-spec-prd  ⇢  tiny-spec-breakdown ⇢  tiny-spec-create → tiny-spec-plan → tiny-spec-tasks → tiny-spec-build
+  idea → PRD        PRD → stories           intent             design           tasks            per-task loop
+  PRD.md            BREAKDOWN.md            SPEC.md            PLAN.md +        tasks.md         plan → implement → review → commit
+                                                              constitution
 ```
 
+The two on-ramps are **optional** and stack. Have nothing written down? Run
+`tiny-spec-prd` to interview your idea into a `PRD.md`. Have a PRD already? Run
+`tiny-spec-breakdown` to carve it into a `BREAKDOWN.md` — a flat list of
+Features → Stories with draft acceptance criteria. Have a single known piece of
+work? Skip both and start at `tiny-spec-create`. Both on-ramps write a regenerable
+file at your project root (not under `.spec/`); `tiny-spec-create` then reads the
+breakdown one story at a time.
+
 ## New to spec-driven development?
 
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -48,12 +64,26 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
-/tiny-spec-plan     # turn the spec into a design and harden the constitution
-/tiny-spec-tasks    # slice the plan into an ordered checklist
-/tiny-spec-build    # build each task: implement, review, commit
+/tiny-spec-prd       # optional: interview a rough idea into a PRD (PRD.md)
+/tiny-spec-breakdown # optional: carve a PRD + wireframes into stories (BREAKDOWN.md)
+/tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan      # turn the spec into a design and harden the constitution
+/tiny-spec-tasks     # slice the plan into an ordered checklist
+/tiny-spec-build     # build each task: implement, review, commit
+```
+
+Or collapse the three planning steps into one and go straight to building:
+
+```
+/tiny-spec-run       # create → plan → tasks in one pass; stops before build
+/tiny-spec-build     # build each task: implement, review, commit
 ```
 
+`tiny-spec-run` resolves where your ticket stands and invokes whichever of
+`create` / `plan` / `tasks` moves it forward, reconciling anything stale first. It
+**stops before `tiny-spec-build`** — that's where you actually review the work — and
+it writes nothing itself, it only delegates.
+
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
 installed. Each skill is copied (not symlinked) so every install is
 self-contained.
@@ -69,7 +99,7 @@ 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-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+for s in tiny-spec-prd tiny-spec-breakdown tiny-spec-run tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
   cp -R "$s" "$HOME/.claude/skills/$s"
 done
 cp agents/*.md "$HOME/.claude/agents/"
@@ -87,6 +117,33 @@ short interview, `tiny-spec-plan` hardens it with concrete engineering rules, an
 `tiny-spec-build` injects it whole into every task. It holds your style, standards,
 invariants, definition of done, and verification commands.
 
+Because it is project-wide it can also go missing — deleted, or never committed —
+while your specs survive. Re-running `tiny-spec-create` then repairs it: it rebuilds
+the constitution from whatever is already written down and marks completed tasks
+stale, since they were reviewed against a document that wasn't there.
+
+### Designs, if you have them
+
+Drop your exported wireframes in a `design/` directory and `tiny-spec-create` will
+look at them — actually look, they are read as images. From all of them together it
+proposes one coherent **design system** (spacing scale, type scale, color roles) for
+your approval and writes it into the constitution, then describes each screen as a
+`D<n>` entry in `SPEC.md`: its layout, its elements with a selector each, and the
+states it must render — all in those token names.
+
+The point is what happens at build time. Tag a task with `design: D1` and the
+reviewer renders that surface, measures the selectors the entry names, and **fails the
+task** on a value that isn't on your scale, an element that never got built, or a
+state the design calls for and the code doesn't render. It measures numbers rather
+than diffing screenshots, because pixel diffs go flaky and get muted. Tasks without a
+`design:` tag are graded exactly as before.
+
+No Figma token, no plugin, no design SaaS — a view-only Figma works fine, since the
+committed export is what the agents read and the `source:` link keeps the trail back.
+Change an export and its recorded hash stops matching, which marks the spec stale the
+same way editing a requirement does. Skip the whole thing for a CLI or a library; the
+constitution simply has no design section.
+
 `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).
@@ -110,11 +167,14 @@ flowchart TB
 
     CON([constitution.md]) -.-> P & I & R
     MEM([memory.md]) -.-> I & R
+    DES([SPEC.md D-n + design/ export]) -.->|only on a design: task| I & R
 ```
 
 Solid arrows are the flow. Dotted arrows show the persistent context injected into
 a step: the `constitution.md` goes into planning, implementation, and review, while
-`memory.md` is handed to the executor and reviewer.
+`memory.md` is handed to the executor and reviewer. A task tagged `design:` also
+carries its screen's `D<n>` entry into both agents — and the review step then runs
+the `visual:` gate on top of the usual one.
 
 A small `memory.md` carries operational lessons between runs, so the executor and
 reviewer (which start fresh each time) don't relearn the same pitfalls.
@@ -153,7 +213,7 @@ The case for staying small:
   optional by design — add shape where it pays, skip it where it doesn't.
 - **More moving parts is more to maintain.** Orchestrators, ownership contracts,
   checkpoint matrices, and config files are themselves a system you have to learn
-  and keep in sync. Four skills and two agents are not.
+  and keep in sync. A few small skills and two agents are not.
 - **Generated docs can fake rigor.** A folder of polished planning artifacts looks
   like progress, but it isn't proof. The proof is the reviewer running your real
   tests before each commit.
@@ -163,22 +223,26 @@ independent reviewer and stops.
 
 ## Project layout
 
-Each skill is self-contained. It carries its own templates and refers to them by
-relative path, with no absolute paths and no shared parent required at runtime, so
-a skill folder works wherever you drop it.
+Each skill is one self-contained `SKILL.md`, with every document skeleton inline in
+it — no companion template files, no absolute paths, and no shared parent required
+at runtime, so a skill works wherever you drop it. (It also means a run never stops
+to ask permission to read a template out of your Claude config directory.)
 
 tiny-spec creates a `.spec/` directory in your project root, never inside a skill.
 It is namespaced per ticket, with a shared spine at the root:
 
 ```
 .spec/
-  ACTIVE                    the active ticket directory name (resolution pointer)
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
     SPEC.md  PLAN.md  tasks.md  decisions.md
 ```
 
+`PRD.md`, `BREAKDOWN.md`, and `design/` sit at your project root rather than inside
+`.spec/`, because they are yours: the first two are regenerable pre-spec planning
+files, and the design exports are project files no skill ever writes.
+
 `CONTRACTS.md` documents the formats for maintainers. The skills do not read it at
 runtime; each is self-sufficient.
 

{tiny_spec-0.1.0 → tiny_spec-0.3.0}/agents/tiny-spec-build-executor.md

@@ -18,9 +18,12 @@ Everything you need and nothing you don't:
 - the **task id**, **description**, and **acceptance** (the outcome that proves it done);
 - a **`files:` hint** — likely paths to touch (guidance, not a hard boundary);
 - the full **constitution** (`constitution.md`): Style, Engineering standards,
-  Guiding invariants, Glossary, Layout, Definition of Done, Verification commands;
+  Guiding invariants, Glossary, Layout, Definition of Done, Verification commands,
+  and — for projects with a visual surface — the **Design system** token table;
 - the project's **memory** if any (`memory.md`) — operational lessons; honor them
   so you don't re-learn a pitfall a past run already paid for;
+- **if the task carries `design:`** — that screen's `D<n>` entry from `SPEC.md` and
+  the path to its committed export;
 - the specific existing files that are your starting point, named explicitly.
 
 You are **blind to the workflow, not to the codebase.** You don't get the plan,
@@ -41,7 +44,24 @@ violated.
    task genuinely needs a nearby file the hint missed, that's fine (you're
    sequential, no one else is writing). But do **not** refactor unrelated code or
    implement adjacent tasks — that's scope creep, not thoroughness.
-5. You MAY run a **narrow self-check** of your own work (the one test file you
+5. **If the task carries a `design:` reference**, build that surface against the
+   `D<n>` entry: **look at the export image** (`Read` renders it), then implement its
+   `layout:`, every row of its `elements:`, and **every state it names** — empty,
+   loading, error, success. Missing states are the most common way generated UI
+   passes a functional check and is still wrong.
+   - **The `elements:` selectors are a contract, not a hint** — unlike `files:`. The
+     reviewer measures exactly those selectors, so a `[data-testid="signup-email"]`
+     row means your markup carries that attribute verbatim. Rename one and the check
+     silently measures nothing. If a selector is genuinely wrong for this codebase
+     (a component library owns the markup, the id collides), that is a **blocker** —
+     report it so the spec gets fixed. Never quietly substitute your own.
+   - **Reference tokens, never raw values.** `space.4`, `color.text.muted` — not
+     `16px`, not `#6B7280`. A value that isn't on the constitution's scale will fail
+     review, and inventing a token the Design system doesn't define is a blocker,
+     not a judgement call: report it and let the constitution be fixed.
+   - The image is the *intent*; the `D<n>` entry and the token table are the
+     *contract*. Where they disagree, the contract wins and you say so in `DECISIONS`.
+6. You MAY run a **narrow self-check** of your own work (the one test file you
    wrote, a syntax/import check). You do **not** need to run the full gate — the
    independent **reviewer** runs the authoritative Verification commands next.
    Leave the tree in a clean, buildable state for it.

tiny_spec-0.3.0/agents/tiny-spec-build-reviewer.md

@@ -0,0 +1,125 @@
+---
+name: tiny-spec-build-reviewer
+description: Independently reviews a single finished task — runs the project's real gate end-to-end and checks the code against the constitution and the task's acceptance. Blind to how the code was written. Returns PASS/FAIL plus findings. Spawned (one per task) by tiny-spec-build. Does not fix code, plan, spawn agents, or invoke skills.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# tiny-spec-build-reviewer
+
+You independently review **one finished task** from a build. You did
+**not** write this code and you have no memory of how it was written — that
+independence is the whole point. Your final message **is** the structured verdict
+back to `tiny-spec-build`; return data, not pleasantries.
+
+## What you receive (the context contract)
+
+- the **task id**, **description**, and **acceptance** (the outcome that must hold);
+- the full **constitution** (`constitution.md`) — especially **Guiding invariants**,
+  **Definition of Done**, and **Verification commands**, plus the **Design system**
+  token table if the project has one;
+- the project's **memory** if any (`memory.md`) — operational lessons (e.g. the
+  gate needs the package installed first); honor them so you don't false-fail on a
+  known precondition;
+- **if the task carries `design:`** — that screen's `D<n>` entry from `SPEC.md` and
+  the path to its committed export;
+- the list of **changed files** to review.
+
+## How to review
+
+Your job is to answer one question honestly: **does this task actually satisfy its
+acceptance and the constitution — verified, not inferred?**
+
+1. **Read the changed code.** Check it against the constitution: does it honor the
+   **Guiding invariants**, match the **Style** and **Layout**, meet the
+   **Definition of Done**? Note any violation as a finding.
+2. **Run the real gate.** Execute the constitution's **Verification commands**
+   end-to-end (install → lint → test → build → run, as applicable) from a clean
+   state, after the documented setup — not a test-runner shortcut. Capture the
+   real output.
+3. **Exercise the acceptance.** Trigger the task's stated outcome the most
+   black-box way available (CLI > HTTP > public API) with realistic input,
+   including a negative case if the acceptance implies a boundary or rejection.
+   The acceptance is met only if the **observed** effect is the one it names — not
+   an adjacent or merely-plausible behavior. "A unit test exists" or "the code
+   looks right" is **not** evidence.
+4. **Measure the design — only if the task carries `design:`.** Skip this step
+   entirely otherwise; a task without the field is graded exactly as steps 1–3.
+
+   First check the constitution has a `visual:` verification command. If it does
+   **not**, stop and report a **blocker** (`VERDICT: FAIL`, findings naming the
+   missing command). Do not fall back to eyeballing and do not pass the task — a
+   design gate that silently doesn't run is worse than no gate, because the checked
+   box then claims a verification that never happened.
+
+   Otherwise:
+   - Run the `visual:` command against **every selector in the entry's `elements:`
+     list** and read back the **real numbers** — `getComputedStyle()` and
+     `getBoundingClientRect()`. Measure the selectors the entry names; do not
+     substitute ones you think are equivalent, and do not measure a sample.
+   - **A selector that matches nothing is a `FAIL`, never a skip.** Either the code
+     didn't build the element or it named it something else — both are real, and both
+     are invisible if you quietly move on. Report the selector and that it was absent.
+   - Compare each element's numbers to the tokens its row names. Report concrete
+     deltas ("heading is 28px, `type.heading.lg` is 24px"; "padding 19px is not on
+     the `space.*` scale"). **Do not pixel-diff the screenshot** — font antialiasing
+     makes image comparison flaky enough that the check gets ignored, which is
+     exactly how visual gates die.
+   - **Check `layout:`** — the arrangement, max width, and the **order** it names.
+     Use the bounding rectangles: elements listed in order should appear in that
+     order down the page (or across it, for a row). Every token can be correct on an
+     element that is in the wrong place.
+   - **Exercise every state the entry names** — empty, loading, error, success.
+     Drive the UI into each one and observe what changes; **finding the word in the
+     source is not evidence**, and it false-passes routinely (a comment saying the
+     loading state is missing contains "loading"). A surface that renders its happy
+     path and nothing else is a fail, not a nit.
+   - Finally, `Read` the export image as a cross-check for what numbers can't catch
+     (a missing element, wrong order, wrong hierarchy).
+
+## Verdict rules
+
+- **`PASS`** — the gate is green AND you exercised the acceptance end-to-end with
+  real input AND the observed effect matches AND no invariant/DoD violation — AND,
+  on a task carrying `design:`, step 4 ran and found nothing measurable wrong. Only
+  this is a pass.
+- **`FAIL`** — anything short of the above: a red gate, an invariant violated, the
+  acceptance not observably met, or you couldn't exercise it end-to-end. When torn,
+  **fail** — never round up. List concrete, actionable findings so the executor
+  can fix them.
+
+**The design step splits the verdict differently — this is deliberate.** On a task
+carrying `design:`:
+
+- **`FAIL` on what you measured**: a selector from `elements:` that matches nothing,
+  a value off the token scale, a token the Design system doesn't define, a hardcoded
+  color/spacing where a token exists, an order or arrangement that contradicts
+  `layout:`, or a state the `D<n>` entry names that doesn't render. These are
+  objective and an executor can fix them from your numbers.
+- **Flag, don't fail, on taste.** "The hierarchy feels off", "spacing looks cramped
+  but is on-scale" — put it in `FINDINGS` prefixed `flag:` and pass if everything
+  measurable is green. The fix loop is bounded at two attempts; burning it on a
+  subjective disagreement means the task blocks on something no executor can resolve.
+- The "when torn, fail" rule still governs steps 1–3 unchanged. It does **not** apply
+  to a subjective visual impression.
+
+You are **read-only on the source** — you run commands and read files, but you do
+**not** edit code, fix the task, or rewrite docs. If it's wrong, you report it; the
+executor fixes it on the next attempt. (You have edit tools only so you can run
+gates that scratch-write build output — never use them on source.)
+
+Never spawn subagents or invoke skills.
+
+## Report back (your final message)
+
+```
+TASK: <task id>
+VERDICT: PASS | FAIL
+GATE: <the Verification commands you ran + the real result (pass/fail + key output)>
+ACCEPTANCE: <how you exercised it + the observed effect, or why you couldn't>
+DESIGN: <omit unless the task carried `design:`. The D<n> checked, the measurements
+  you read back vs the tokens they should match, and which states you exercised —
+  or "blocker: no `visual:` command in the constitution">
+FINDINGS:
+- <each invariant/DoD/acceptance problem, concrete and actionable> (omit if PASS)
+- flag: <subjective visual note — does not fail the task> (only with a DESIGN section)
+```

tiny_spec-0.3.0/docs/eval/README.md

@@ -0,0 +1,119 @@
+# tiny-spec evaluation
+
+Three complementary evaluations of the tiny-spec suite, plus a shared score history.
+All are **maintainer-only dev tools** — none of this is in `tiny_spec/manifest.json`,
+so nothing here ships to users.
+
+| Eval | Question it answers | How | Drives |
+|------|---------------------|-----|--------|
+| **Static review** — `/eval-suite` | Does the *design* have the right mechanisms? | Reads `CONTRACTS.md`, agents, SKILL.md; scores 0–3 against the rubric. | Dimensions **B, C, D** |
+| **Empirical harness** — `harness/run.sh` | Does the *execution* stage produce working code, and does its own gate tell the truth? | Runs `create → plan → tasks → build` on benchmark tasks and grades the output with held-out tests. | Dimension **A** (auto-derived) |
+| **Planning harness** — `harness/run-planning.sh` | Does the *planning* stage produce a sound, faithful hand-off? | Runs `tiny-spec-prd → tiny-spec-breakdown` on loose ideas; grades the PRD/BREAKDOWN with structural checks + an LLM judge. | `planning-results.jsonl` (standalone) |
+
+The rubric, criteria, weights, and worked rationale live in
+[`../sdd-evaluation-rubric.md`](../sdd-evaluation-rubric.md).
+
+## Files
+
+```
+docs/eval/
+  scores.jsonl              append-only scorecard history (the A–D score over time)
+  results.jsonl             append-only per-run empirical detail (created on first run)
+  planning-results.jsonl    append-only planning-eval detail (created on first run)
+  benchmark/<task>/         execution-stage tasks
+    TICKET.md               the prompt handed to tiny-spec (NO hidden tests)
+    grade/test.py           held-out grader — the suite never sees this
+  planning/<case>/          planning-stage cases
+    IDEA.md                 a loose product idea handed to the planning stage
+  harness/
+    run.sh                  execution: sandbox -> headless build -> held-out grade -> score
+    score.py                metrics + Dimension A thresholds + merge into scores.jsonl
+    run-planning.sh         planning: sandbox -> headless prd+breakdown -> grade -> score
+    grade_planning.py       structural checks + LLM judge -> one result object per case
+    score_planning.py       aggregate -> planning-results.jsonl (does NOT touch scores.jsonl)
+```
+
+## Running the empirical eval
+
+Prereqs: `claude` CLI, `python3`, `git`. The harness vendors the repo's skills+agents
+into each sandbox's local `.claude/`, so you do **not** need tiny-spec globally installed.
+
+```sh
+docs/eval/harness/run.sh                  # all tasks
+docs/eval/harness/run.sh roman duration   # a subset
+CLAUDE_MODEL=claude-sonnet-4-6 docs/eval/harness/run.sh roman   # pick a model
+KEEP_SANDBOX=1 docs/eval/harness/run.sh roman                   # keep sandbox to inspect
+```
+
+Each task runs in a throwaway sandbox: a fresh git repo seeded only with `TICKET.md`
+and the vendored skills. `claude -p` drives `create → plan → tasks → build`
+autonomously; then the held-out grader runs against the produced `solution.py`.
+
+### What gets measured
+
+- **held-out pass rate** — the real correctness signal (truth = the grader).
+- **suite/truth agreement** & **FALSE-PASS rate** — does tiny-spec's *own* verdict (all
+  tasks ticked, no open blocker) match reality? A FALSE-PASS (suite says done, grader
+  fails) is the worst outcome; it directly tests the suite's core claim that "an
+  independent reviewer running the real gate is the safeguard."
+- completion rate, blocker rate.
+
+### How Dimension A is derived (thresholds in `score.py`)
+
+- **A1 measurability** → 3 once a pass-rate is produced.
+- **A3 reproducible harness** → 3 once the harness has run.
+- **A2 gate effectiveness** → 3 if 0 false-PASS & agreement ≥ 90%; 2 if ≤ 20% false-PASS
+  & agreement ≥ 70%; 1 otherwise; 0 if nothing completed.
+- **A4 regression visibility** → 3 once ≥ 2 empirical runs are on record, else 2.
+
+B/C/D are carried over from the latest `/eval-suite` static scorecard; the empirical run
+swaps in the A scores and recomputes the weighted total, appending a new line tagged
+`"scored_by": "eval-output"`.
+
+## Running the planning eval
+
+```sh
+docs/eval/harness/run-planning.sh                 # all planning cases
+docs/eval/harness/run-planning.sh snip            # a subset
+JUDGE_MODEL=claude-sonnet-4-6 docs/eval/harness/run-planning.sh   # pick the judge model
+KEEP_SANDBOX=1 docs/eval/harness/run-planning.sh snip            # keep sandbox to inspect
+```
+
+Each case runs in a throwaway sandbox seeded with `IDEA.md` and the vendored skills.
+`claude -p` drives `tiny-spec-prd → tiny-spec-breakdown` (it must **not** scaffold
+`.spec/` or run any later skill), then `grade_planning.py` scores the produced
+`PRD.md` + `BREAKDOWN.md`.
+
+### What gets measured
+
+- **structural conformance** (deterministic) — PRD has its required sections filled;
+  BREAKDOWN has a Decisions block, ≥1 Feature, Stories with a slug and ≥1 AC; the
+  planning skills left no `.spec/` behind.
+- **hand-off integrity** (LLM judge) — **coverage** (every PRD capability lands in ≥1
+  story, nothing dropped) and **no fabrication** (every story traces to a capability,
+  nothing invented). These are the high-value signals; a case PASSes only if structural
+  conformance holds *and* the judge confirms both.
+- **quality** (LLM judge, reported not gated) — atomicity / user-observable phrasing,
+  cross-cutting concerns placed in Decisions rather than as their own Feature, and
+  whether the PRD faithfully reflects the idea.
+
+Results append to `planning-results.jsonl`. This scorecard is **standalone** — it does
+not feed the A–D `scores.jsonl`, because planning quality and execution correctness are
+separate claims.
+
+## Caveats
+
+- **Cost/time:** each task runs the full multi-agent flow headlessly — minutes and real
+  tokens per task. Start with a subset.
+- **Autonomy:** `--dangerously-skip-permissions` is used so the sandbox run is
+  non-interactive. It runs in a throwaway dir, never your repo.
+- **Small benchmark:** 5 self-contained Python tasks. It measures the suite's loop on
+  small, well-specified work — not large-codebase performance. To approximate the
+  literature (Spec Kit Agents on SWE-bench Lite), add harder tasks under `benchmark/`;
+  the grader contract (`grade/test.py` reading `$SOLUTION_PATH`) is all a new task needs.
+- **Judgment vs measurement:** Dimension A here is *measured*; B/C/D remain design
+  judgment from `/eval-suite`.
+- **Planning eval uses an LLM judge:** coverage/fabrication/atomicity are judged by a
+  model, so verdicts are not bit-reproducible the way held-out tests are. The
+  deterministic structural layer *is* reproducible; the judge adds the semantic signal
+  the structure can't see. Add planning cases by dropping a new `planning/<case>/IDEA.md`.

{tiny_spec-0.1.0 → tiny_spec-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tiny-spec"
-version = "0.1.0"
+version = "0.3.0"
 description = "A tiny, opinionated take on spec-driven development."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -34,6 +34,9 @@ packages = ["tiny_spec"]
 # expects them). Bundle them into the wheel under tiny_spec/_bundle/ so the
 # installer can copy them at runtime, without restructuring the repo.
 [tool.hatch.build.targets.wheel.force-include]
+"tiny-spec-prd" = "tiny_spec/_bundle/tiny-spec-prd"
+"tiny-spec-breakdown" = "tiny_spec/_bundle/tiny-spec-breakdown"
+"tiny-spec-run" = "tiny_spec/_bundle/tiny-spec-run"
 "tiny-spec-create" = "tiny_spec/_bundle/tiny-spec-create"
 "tiny-spec-plan" = "tiny_spec/_bundle/tiny-spec-plan"
 "tiny-spec-tasks" = "tiny_spec/_bundle/tiny-spec-tasks"
@@ -43,6 +46,9 @@ packages = ["tiny_spec"]
 [tool.hatch.build.targets.sdist]
 include = [
   "tiny_spec",
+  "tiny-spec-prd",
+  "tiny-spec-run",
+  "tiny-spec-breakdown",
   "tiny-spec-create",
   "tiny-spec-plan",
   "tiny-spec-tasks",