tiny-spec 0.5.0__tar.gz → 1.0.1__tar.gz

{tiny_spec-0.5.0 → tiny_spec-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiny-spec
-Version: 0.5.0
+Version: 1.0.1
 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
@@ -68,36 +68,40 @@ 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 **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.
-Two optional routers sit over the top: `tiny-spec-run` walks the three planning steps
-in one command, and `tiny-spec-loop` works a whole list of stories — branch, plan,
-build, merge, next — until they're built or something stops it. No config file, no
-build step.
+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
+stories through to merged code. No config file, no build step.
 
 ```
-                                           ┌───────────────── 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
-                                           ▲                                                 ▲
-                                           └──────────────── tiny-spec-loop ─────────────────┘
-                                             optional: per story — branch, run, build, merge,
-                                             then the next story. Halts on a wall.
+   GREENFIELD                        BROWNFIELD
+   starting from an idea             starting from a codebase
+   tiny-spec-scope                   tiny-spec-adopt
+   idea → Features → Stories         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.md            → review → commit
+
+   tiny-spec-run      one router. Walks the chain and stops before build —
+                      or, asked to, builds each story and merges it.
+   tiny-spec-design   optional. Wireframes → tokens + gradeable screens.
 ```
 
-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.
+**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
+Features → Stories 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`.
+
+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
 
@@ -106,57 +110,41 @@ receipt rather than the adjective:
 
 | | skills / commands | agents | config | artifacts per feature |
 |---|---|---|---|---|
-| **tiny-spec** | **8** (4 core + 4 optional) | **2** | **none** | **`SPEC` `PLAN` `tasks`** |
+| **tiny-spec** | **7** (3 core + 1 router + 3 optional) | **2** | **none** | **`SPEC` `PLAN` `tasks`** |
 | [GitHub Spec Kit](https://github.com/github/spec-kit) | 10 | — | `specify init` | `spec` `plan` `tasks` `checklist` `constitution` `research` `data-model` `contracts/` `quickstart` |
 | [OpenSpec](https://github.com/Fission-AI/OpenSpec) | 12 | — | `.openspec.yaml` | `proposal` `design` `tasks` `specs/` |
 | [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) | 58 | 5 personas | 35 × `customize.toml` | `PRD` `architecture` `epics` `stories` `UX` `brief` `sprint-plan` |
 
-The whole of tiny-spec is **2,079 lines** of markdown across 8 skills and 2 agents.
-There is no config file, no build step, no orchestrator, and no CLI to initialize a
-project — the skills are the product.
+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.
 
-<sub>Counts taken from each project's own repository on 2026-08-03 by listing its
-command/skill/agent directories and templates, not from its marketing copy. Spec Kit:
-`templates/commands/` (10 files) and the artifact set named in `templates/plan-template.md`.
-OpenSpec: `skills/` (12 directories). BMAD: `SKILL.md` files on `main` (58), agent
-personas in `src/bmm-skills/agents/` (analyst, architect, dev, pm, ux-designer), and
-`customize.toml` files (35). These projects are all substantially more popular than
-tiny-spec — Spec Kit ~125k stars, OpenSpec ~64k, BMAD ~51k — and being smaller is a
-bet, not a proof of quality. Re-run the counts yourself before believing them.</sub>
+<sub>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.</sub>
 
 ## 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.
-
-A green unit test suite is not the same as working software, so the reviewer
-exercises acceptance criteria end to end and a final smoke test confirms the whole
-spec. That independent review is the safeguard — not the volume of planning
-artifacts. One task, one commit, an external reviewer. Nothing gets added unless
-it earns its place.
+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.** Generating large `spec.md`,
-  `plan.md`, `research.md`, and `data-model.md` files costs tokens to write, then
-  costs context to carry. 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.** Bigger kits
-  assume you're bootstrapping a project from a blank page. Day to day, you pick up
-  a ticket and change part of a system that already exists. tiny-spec binds to a
-  ticket, works one at a time, and references your task platform instead of
-  re-describing the world.
-- **Rigid pipelines fight the user.** Mandatory phases and required sections
-  impose ceremony on work that doesn't need it. tiny-spec's extra structure is
-  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. 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.
+- **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.
@@ -166,10 +154,10 @@ independent reviewer and stops.
 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 being **false-PASS rate**, how
-often the gate blesses code that is actually broken.
+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, v0.4.0 (`7810074`), 2026-08-03:
+Most recent run — 5 benchmark tasks on v1.0.0:
 
 | | |
 |---|---|
@@ -178,27 +166,24 @@ Most recent run — 5 benchmark tasks, v0.4.0 (`7810074`), 2026-08-03:
 | **false-PASS rate** | **0%** — it never called broken code done |
 | blocker rate | 0% |
 
-The same run a month earlier on `f973c85` scored identically, which is the more
-interesting result: the loop is at least stable across versions rather than tuned to a
-single commit.
+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`](docs/eval/README.md) for the method and
-[`docs/sdd-evaluation-rubric.md`](docs/sdd-evaluation-rubric.md) for the scoring rubric
-this repo grades itself against. **Read both skeptically: it is my benchmark, of my own
-tool, scored by me.** The rubric says so itself — *"treat the tiny-spec column as
-self-assessment to pressure-test, not gospel."* The tasks are small and self-contained,
-so the harness measures the loop on well-specified work, not large-codebase performance.
-The harness is in the repo precisely so you don't have to take my word for it.
+[`docs/sdd-evaluation-rubric.md`](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 — and it implements against that. The payoff: the
-agent stops guessing. It knows what "done" looks like, you can review the plan
-before a single line is written, and the result is checked against the spec
-rather than vibes. tiny-spec is one small take on that idea.
+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
 
@@ -212,41 +197,41 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/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-scope     # starting from an idea: interview it into stories (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      # turn the spec into a design and harden the constitution
-/tiny-spec-tasks     # slice the plan into an ordered checklist
+/tiny-spec-plan      # design it, harden the constitution, slice the task list
 /tiny-spec-build     # build each task: implement, review, commit
 ```
 
-Or collapse the three planning steps into one and go straight to building:
+Run one of the two front doors once per project, then `create → plan → build` per
+ticket. Or let the router drive:
 
 ```
-/tiny-spec-run       # create → plan → tasks in one pass; stops before build
+/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 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.
+`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.
 
-Or hand it a whole list of stories:
+Ask it to build and it goes all the way instead:
 
 ```
-/tiny-spec-loop      # per story: branch → plan → build → merge → next
+/tiny-spec-run build the backlog     # per story: branch → plan → build → merge → next
 ```
 
-`tiny-spec-loop` reads your `BREAKDOWN.md` (or a list you paste) and works the stories
-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](#working-a-whole-list--tiny-spec-loop).
+It reads your `BREAKDOWN.md` (or a list you paste) and works the stories 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](#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?** There is no design flag to pass. Commit your exports to
-`design/` before the run and `tiny-spec-create` — whether you invoke it directly or
-reach it through `tiny-spec-run` — reads what's there and asks which screens this
-ticket covers. [Designs, if you have them](#designs-if-you-have-them) walks through it.
+**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](#designs-if-you-have-them) walks through it.
 
 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
@@ -263,7 +248,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-prd tiny-spec-breakdown tiny-spec-run tiny-spec-loop tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+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/"
@@ -283,14 +268,22 @@ The tests pass; you can clone it and run the gate yourself.
 
 ## How it works
 
-The constitution (`constitution.md`) is the spine. `tiny-spec-create` seeds it from a
-short interview, `tiny-spec-plan` hardens it with concrete engineering rules, and
-`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
+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 `tiny-spec-build` injects it whole into
+every task. 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
@@ -302,11 +295,11 @@ 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-create` reads every file in `design/` at your project root —
-directly, or when `tiny-spec-run` reaches it — and asks which screens this ticket
-covers; you can also just hand it paths during the interview. Change an export later and
-re-running `create` (or `run`) re-hashes it, marking the spec stale exactly like editing
-a requirement.
+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.
@@ -318,7 +311,7 @@ your-project/
     dashboard.png
 ```
 
-**2. `tiny-spec-create` looks at them and proposes a design system.** Actually looks —
+**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
@@ -387,13 +380,12 @@ FINDINGS:
 
 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
+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** — on-scale-but-cramped is never a
-fail — which keeps the two halves from contradicting each other. Measurable or visible
-violations fail; taste comes back as `flag:` notes so a bounded fix loop can't thrash. A
-task with no `design:` tag is graded exactly as before.
+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.
 
 <details>
 <summary>The <code>visual:</code> command (you write this once)</summary>
@@ -437,14 +429,12 @@ 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` is what the layout-order check
-reads, and `opacity`/`visibility` are worth printing because they turn the cheapest kind
-of invisible element into a numeric failure. The `SCREENSHOT` line is what the reviewer
-reads back to look at the render and catch the rest — occlusion, clipping, truncation,
-same-color-on-same-color — none of which any single property reports. 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.
+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.
 
 </details>
 
@@ -496,13 +486,14 @@ and logs a blocker instead of hacking around it. You fix the gap upstream in
 `tiny-spec-plan` or `tiny-spec-create`, then resume. Work runs one ticket at a time and
 resumes from the checklist state.
 
-### Working a whole list — `tiny-spec-loop`
+### Working a whole list
 
-`/tiny-spec-loop` takes a list of stories and works them one after another. Per story
-it does the same four moves:
+Ask `/tiny-spec-run` to build — "build the backlog", "work through the breakdown",
+"spec it out and build it" — and it takes a list of stories and works them one after
+another. Per story it does the same four moves:
 
 ```
-cut a branch from main  →  tiny-spec-run  →  tiny-spec-build  →  merge back to main
+cut a branch from main  →  walk the chain  →  tiny-spec-build  →  merge back to main
 ```
 
 Then the next story. Each branch is cut **fresh from main**, so story 3 sees stories 1
@@ -525,10 +516,9 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 | `fork` | a real either/or the plan doesn't answer |
 | `conflict` | a story's branch wouldn't merge cleanly |
 
-**Only `done` means the work is built** — and in a story loop that means *all* of them.
-A run that stopped at story 2 of 7 reporting "done" is the single thing autonomous loops
-get wrong most often, so the state is always named, along with what got merged and how
-many stories are still untouched.
+**Only `done` means the work is built** — and in a story run, that means *all* of them.
+Stopping at story 2 of 7 and reporting "done" is what autonomous loops get wrong most
+often, so the state is always named alongside what merged and what's still untouched.
 
 **A halt stops the whole run, not just that story.** Later stories in a list you wrote
 top to bottom usually assume the earlier ones landed, so skipping ahead past a failure
@@ -543,7 +533,7 @@ the build halts *before* running it:
   - pause: confirm the snapshot is current before this touches real rows
 ```
 
-`tiny-spec-tasks` proposes these for genuinely irreversible work — migrations,
+`tiny-spec-plan` proposes these for genuinely irreversible work — migrations,
 destructive file operations, a new dependency, an auth boundary, a public API contract.
 You can also give the run a standing policy up front ("halt before anything that touches
 auth") and it gets applied as each story's tasks are sliced.
@@ -555,22 +545,26 @@ never opens a PR. Merges are local, so a bad run is one `git reset` away; publis
 stays yours. If the gate goes red after a merge it leaves the merge alone and tells you
 the undo command rather than running it.
 
-**Walk away and come back.** Nothing is written down to track progress — it's derived:
-a story whose ticked `tasks.md` is on `main` is done, a `.spec/<slug>/` with an unchecked
-task is in progress, no directory means not started. So re-running `/tiny-spec-loop`
-tomorrow in a fresh session picks up exactly where it stopped. No run-state file, no
-lock, and no budget to configure: the story list *is* the budget.
+**Walk away and come back.** Progress isn't written down, it's derived: a story whose
+ticked `tasks.md` is on `main` is done, a `.spec/<slug>/` with an unchecked task is in
+progress, no directory means not started. Ask again tomorrow in a fresh session and it
+picks up where it stopped. No run-state file, no lock, no budget to configure — the
+story list *is* the budget.
 
 **It never fixes a blocker for you.** A blocker means one of your documents is wrong,
-and a loop allowed to rewrite the requirement its own task just failed would be grading
+and a run allowed to rewrite the requirement its own task just failed would be grading
 its own homework. It reports and stops; the upstream edit is yours.
 
+**And it never decides to build on its own.** Whether a run stops before the build or
+goes all the way is fixed from your opening request and never revised. Build is your
+review gate, so promoting itself into it is the one thing a router doesn't get to do.
+
 ## Project layout
 
 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.)
+it — no companion template files, no absolute paths, no shared parent required at
+runtime. A skill works wherever you drop it, and 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:
@@ -583,12 +577,12 @@ It is namespaced per ticket, with a shared spine at the root:
     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.
+`BREAKDOWN.md` and `design/` sit at your project root rather than inside `.spec/`,
+because they are yours: the breakdown is a regenerable pre-spec planning file, 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.
+Every format lives inline in the skill that writes it — there is no separate contract
+document to keep in sync, and no skill reads anything but its own `SKILL.md` at runtime.
 
 ## Integrations