PyPI - tiny-spec - Versions diffs - 0.4.0__tar.gz → 0.5.0__tar.gz - Mend

tiny-spec 0.4.0tar.gz → 0.5.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tiny-spec
-Version: 0.4.0
+Version: 0.5.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
@@ -44,10 +44,24 @@ Description-Content-Type: text/markdown
 <p align="center">A tiny, opinionated take on spec-driven development.</p>
 <p align="center">
+  <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>
 </p>
+<p align="center">
+  <code>uvx tiny-spec install</code>
+</p>
+<!-- DEMO GIF SLOT — images/demo.gif
+     Record the FAIL -> fix -> PASS loop, then uncomment:
+<p align="center">
+  <img src="images/demo.gif" alt="tiny-spec build loop: the reviewer fails a task, the executor fixes it, the task commits" width="800">
+</p>
+-->
 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
@@ -57,7 +71,9 @@ 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.
-`tiny-spec-run` walks the three planning steps in one command. No config file, no
+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.
 ```
@@ -69,6 +85,10 @@ PLANNING (optional on-ramps)              EXECUTION (the core loop, one story at
   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.
 ```
 The two on-ramps are **optional** and stack. Have nothing written down? Run
@@ -79,6 +99,97 @@ work? Skip both and start at `tiny-spec-create`. Both on-ramps write a regenerab
 file at your project root (not under `.spec/`); `tiny-spec-create` then reads the
 breakdown one story at a time.
+## How small
+Every other kit in this space is bigger. That is the whole pitch, so here is the
+receipt rather than the adjective:
+| | skills / commands | agents | config | artifacts per feature |
+|---|---|---|---|---|
+| **tiny-spec** | **8** (4 core + 4 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.
+<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>
+## 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.
+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.
+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 being **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:
+| | |
+|---|---|
+| held-out pass rate | **100%** (5/5) — the code works, judged by tests it never saw |
+| suite/truth agreement | **100%** — the reviewer's verdict matched the held-out grader every time |
+| **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.
+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.
 ## New to spec-driven development?
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -121,6 +232,17 @@ Or collapse the three planning steps into one and go straight to building:
 **stops before `tiny-spec-build`** — that's where you actually review the work — and
 it writes nothing itself, it only delegates.
+Or hand it a whole list of stories:
+```
+/tiny-spec-loop      # 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).
 **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
@@ -141,7 +263,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-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-loop 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/"
@@ -152,6 +274,13 @@ or install one set at a time.
 </details>
+### See a finished run first
+[`examples/todo-cli/`](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`,
+`tasks.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-create` seeds it from a
@@ -332,19 +461,21 @@ unnoticed.
 3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
    end to end 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 it becomes a blocker.
+   executor with the findings. After two failed attempts the run halts `exhausted`.
 ```mermaid
 flowchart TB
     SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
+    TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
     P --> I[Implement<br/>executor]
     I --> R[Review + run gate<br/>reviewer]
+    I -->|blocker| B
     R -->|pass| C[Commit + tick]
     C --> TASKS
     R -->|fail| I
-    R -->|fail twice| B[Blocker logged to decisions.md]
+    R -->|fail twice| B[Halt — blocked / exhausted<br/>logged to decisions.md]
     CON([constitution.md]) -.-> P & I & R
     MEM([memory.md]) -.-> I & R
@@ -365,42 +496,74 @@ 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.
-## Why it's small
+### Working a whole list — `tiny-spec-loop`
-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.
+`/tiny-spec-loop` takes a list of stories and works them one after another. Per story
+it does the same four moves:
-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.
+```
+cut a branch from main  →  tiny-spec-run  →  tiny-spec-build  →  merge back to main
+```
-The case for staying small:
+Then the next story. Each branch is cut **fresh from main**, so story 3 sees stories 1
+and 2 already merged — which is what makes an ordered list build correctly.
-- **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.
+**The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
+each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
+a list at invocation instead and that wins; but a bare feature name has no acceptance
+criteria, so `tiny-spec-create` will interview you when it reaches it. That's the
+honest trade: a breakdown runs unattended, a pasted list is supervised.
-That's the whole trade: where larger kits add machinery, tiny-spec adds one
-independent reviewer and stops.
+**Every run ends in exactly one of six states, and it says which:**
+| | |
+|---|---|
+| `done` | every story built **and merged** |
+| `blocked` | an upstream document is wrong — go fix the spec or the plan |
+| `exhausted` | a task stayed red past two fix attempts |
+| `paused` | it reached a `pause:` point |
+| `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.
+**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
+just produces a second, more confusing failure downstream.
+**Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
+the build halts *before* running it:
+```
+- [ ] T7 — run the schema migration against the restored snapshot
+  - acceptance: every row in orders has a non-null tenant_id
+  - pause: confirm the snapshot is current before this touches real rows
+```
+`tiny-spec-tasks` 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.
+**What it will not do to your repo.** It runs exactly five git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, and reads. It refuses to start on a dirty
+tree. It **never pushes**, never rebases, never resets, never deletes a branch, and
+never opens a PR. Merges are local, so a bad run is one `git reset` away; publishing
+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.
+**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
+its own homework. It reports and stops; the upstream edit is yours.
 ## Project layout

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/README.md RENAMED Viewed

@@ -7,10 +7,24 @@
 <p align="center">A tiny, opinionated take on spec-driven development.</p>
 <p align="center">
+  <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>
 </p>
+<p align="center">
+  <code>uvx tiny-spec install</code>
+</p>
+<!-- DEMO GIF SLOT — images/demo.gif
+     Record the FAIL -> fix -> PASS loop, then uncomment:
+<p align="center">
+  <img src="images/demo.gif" alt="tiny-spec build loop: the reviewer fails a task, the executor fixes it, the task commits" width="800">
+</p>
+-->
 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
@@ -20,7 +34,9 @@ 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.
-`tiny-spec-run` walks the three planning steps in one command. No config file, no
+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.
 ```
@@ -32,6 +48,10 @@ PLANNING (optional on-ramps)              EXECUTION (the core loop, one story at
   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.
 ```
 The two on-ramps are **optional** and stack. Have nothing written down? Run
@@ -42,6 +62,97 @@ work? Skip both and start at `tiny-spec-create`. Both on-ramps write a regenerab
 file at your project root (not under `.spec/`); `tiny-spec-create` then reads the
 breakdown one story at a time.
+## How small
+Every other kit in this space is bigger. That is the whole pitch, so here is the
+receipt rather than the adjective:
+| | skills / commands | agents | config | artifacts per feature |
+|---|---|---|---|---|
+| **tiny-spec** | **8** (4 core + 4 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.
+<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>
+## 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.
+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.
+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 being **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:
+| | |
+|---|---|
+| held-out pass rate | **100%** (5/5) — the code works, judged by tests it never saw |
+| suite/truth agreement | **100%** — the reviewer's verdict matched the held-out grader every time |
+| **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.
+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.
 ## New to spec-driven development?
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -84,6 +195,17 @@ Or collapse the three planning steps into one and go straight to building:
 **stops before `tiny-spec-build`** — that's where you actually review the work — and
 it writes nothing itself, it only delegates.
+Or hand it a whole list of stories:
+```
+/tiny-spec-loop      # 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).
 **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
@@ -104,7 +226,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-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-loop 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/"
@@ -115,6 +237,13 @@ or install one set at a time.
 </details>
+### See a finished run first
+[`examples/todo-cli/`](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`,
+`tasks.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-create` seeds it from a
@@ -295,19 +424,21 @@ unnoticed.
 3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
    end to end 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 it becomes a blocker.
+   executor with the findings. After two failed attempts the run halts `exhausted`.
 ```mermaid
 flowchart TB
     SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
+    TASKS -->|pause: set| H[Halt — paused<br/>task stays unchecked]
     TASKS --> P[Plan task]
     P --> I[Implement<br/>executor]
     I --> R[Review + run gate<br/>reviewer]
+    I -->|blocker| B
     R -->|pass| C[Commit + tick]
     C --> TASKS
     R -->|fail| I
-    R -->|fail twice| B[Blocker logged to decisions.md]
+    R -->|fail twice| B[Halt — blocked / exhausted<br/>logged to decisions.md]
     CON([constitution.md]) -.-> P & I & R
     MEM([memory.md]) -.-> I & R
@@ -328,42 +459,74 @@ 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.
-## Why it's small
+### Working a whole list — `tiny-spec-loop`
-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.
+`/tiny-spec-loop` takes a list of stories and works them one after another. Per story
+it does the same four moves:
-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.
+```
+cut a branch from main  →  tiny-spec-run  →  tiny-spec-build  →  merge back to main
+```
-The case for staying small:
+Then the next story. Each branch is cut **fresh from main**, so story 3 sees stories 1
+and 2 already merged — which is what makes an ordered list build correctly.
-- **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.
+**The list is `BREAKDOWN.md` by default** — its `- Story:` entries, in file order,
+each already carrying a `slug:` (the branch and directory name) and `AC:` lines. Paste
+a list at invocation instead and that wins; but a bare feature name has no acceptance
+criteria, so `tiny-spec-create` will interview you when it reaches it. That's the
+honest trade: a breakdown runs unattended, a pasted list is supervised.
-That's the whole trade: where larger kits add machinery, tiny-spec adds one
-independent reviewer and stops.
+**Every run ends in exactly one of six states, and it says which:**
+| | |
+|---|---|
+| `done` | every story built **and merged** |
+| `blocked` | an upstream document is wrong — go fix the spec or the plan |
+| `exhausted` | a task stayed red past two fix attempts |
+| `paused` | it reached a `pause:` point |
+| `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.
+**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
+just produces a second, more confusing failure downstream.
+**Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
+the build halts *before* running it:
+```
+- [ ] T7 — run the schema migration against the restored snapshot
+  - acceptance: every row in orders has a non-null tenant_id
+  - pause: confirm the snapshot is current before this touches real rows
+```
+`tiny-spec-tasks` 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.
+**What it will not do to your repo.** It runs exactly five git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, and reads. It refuses to start on a dirty
+tree. It **never pushes**, never rebases, never resets, never deletes a branch, and
+never opens a PR. Merges are local, so a bad run is one `git reset` away; publishing
+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.
+**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
+its own homework. It reports and stops; the upstream edit is yours.
 ## Project layout

tiny_spec-0.5.0/examples/todo-cli/README.md ADDED Viewed

@@ -0,0 +1,69 @@
+# Example: todo CLI
+A **real run** of the tiny-spec suite on one small ticket — not a hand-written ideal.
+Everything in this folder (the `.spec/` artifacts and the code) was produced by
+actually driving `tiny-spec-create → plan → tasks → build` autonomously on
+[`TICKET.md`](TICKET.md), then committed verbatim. Browse it to see exactly what the
+workflow generates before you run it on your own work.
+> Produced on 2026-06-29 with tiny-spec **v0.2.1**, and kept as-run rather than
+> retouched to match the current artifact formats — a doctored example would defeat
+> the point. Later versions add a `## Design` section to `SPEC.md` (unused here: this
+> is a CLI with no design surface) and richer status flags. The shape is the same.
+## What's here
+```
+TICKET.md                     the input — a small "todo CLI" ask
+.spec/
+  constitution.md             the shared spine: style, standards, invariants,
+                              definition of done, and the verification gate
+  todo-cli/
+    SPEC.md                   intent + REQ-1..REQ-9 (what "done" means)
+    PLAN.md                   the design and how each requirement is covered
+    tasks.md                  the ordered checklist, all ticked [x]
+todo.py                       the produced CLI (stdlib only, 117 lines)
+test_todo.py                  the produced end-to-end test (129 lines)
+```
+Read them in flow order: `TICKET.md` → `SPEC.md` → `PLAN.md` → `tasks.md` →
+`todo.py`. The `constitution.md` is the persistent context injected into every task.
+## It passes its own gate
+The committed code clears the gate defined in its own
+[`constitution.md`](.spec/constitution.md) — the same check `tiny-spec-build-reviewer`
+runs. From this directory:
+```sh
+python3 -m pytest test_todo.py        # 8 passed
+```
+And the ticket's example session reproduces exactly:
+```sh
+python3 todo.py add "buy milk"        # -> 1
+python3 todo.py add "write tests"     # -> 2
+python3 todo.py list                  # two open lines
+python3 todo.py done 1
+python3 todo.py list                  # 1 now shows [x]
+```
+> Running these creates a `todos.json` in your working directory — delete it
+> afterward, and don't commit it.
+## How it was generated
+Driven headlessly the same way the eval harness drives its benchmark tasks: a
+hermetic sandbox with the suite vendored into a local `.claude/`, seeded with
+`TICKET.md`, and run via `claude -p` with instructions to complete the flow
+autonomously. See [`docs/eval/harness/run.sh`](../../docs/eval/harness/run.sh) for the
+exact recipe — the `DRIVER` prompt near the top is what was handed to the model.
+This run finished in 55 turns at roughly $3.49 with no blockers; all five tasks
+passed review on the first or second attempt.
+To produce your own equivalent, point that harness recipe at this `TICKET.md`, or
+just run the flow interactively in a scratch directory. Output won't be
+byte-identical — the model is nondeterministic — but it will be an equivalent,
+gate-passing run.

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "tiny-spec"
-version = "0.4.0"
+version = "0.5.0"
 description = "A tiny, opinionated take on spec-driven development."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -37,6 +37,7 @@ packages = ["tiny_spec"]
 "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-loop" = "tiny_spec/_bundle/tiny-spec-loop"
 "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"
@@ -48,6 +49,7 @@ include = [
   "tiny_spec",
   "tiny-spec-prd",
   "tiny-spec-run",
+  "tiny-spec-loop",
   "tiny-spec-breakdown",
   "tiny-spec-create",
   "tiny-spec-plan",

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny-spec-build/SKILL.md RENAMED Viewed

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-build
-description: Build the spec — run the per-task loop plan→implement→review→commit, one task at a time. Implements with a fresh executor, grades with an independent reviewer running the real gate, commits per passed task, keeps a lean memory. Resumes from the checkbox state.
+description: Build the spec — run the per-task loop plan→implement→review→commit, one task at a time. Implements with a fresh executor, grades with an independent reviewer running the real gate, commits per passed task, keeps a lean memory. Halts on a blocker, a spent convergence budget, a task's pause: point, or a genuine fork, and names which. Resumes from the checkbox state.
 ---
 # tiny-spec-build
@@ -42,6 +42,15 @@ alongside this skill (see the suite README).
 For the selected task, run these steps in order. **Do not tick a task until its
 reviewer passes.**
+**Before step 1, check the task's `pause:` field.** If it has one and the user hasn't
+waived it for this run, **halt `paused`** (see **Halting** below): leave the task
+`[ ]`, dispatch nothing, and don't touch `tasks.md`. A pause stops *before* the work so
+the approach gets reviewed while redirecting it is still cheap.
+A pause can be waived or added for the current run only, conversationally — "skip the
+pause on T5", "also stop before T9". Honor it for this run and **never write it back
+into `tasks.md`**: the file records the standing intent, not one run's override.
 ### 1. PLAN (inline, brief)
 Restate the task as a 2–4 step micro-plan against the constitution: which
 **invariants** apply, which files it touches, which **Definition of Done** items
@@ -90,8 +99,12 @@ It fails on what it measured or saw, and merely flags what is taste.
 ### 4. CONVERGE (on FAIL)
 Re-dispatch the **executor** with the reviewer's findings appended to its brief.
-Bound this to **2 fix attempts**. If it still fails after that, stop and treat it
-as a **blocker** (below) — don't keep grinding or hand-fix past the loop silently.
+Bound this to **2 fix attempts**. If it still fails after that, stop and **halt
+`exhausted`** (see **Halting** below) — don't keep grinding or hand-fix past the loop
+silently. `exhausted` is recorded as a blocker, because a task that three attempts
+couldn't turn green is a signal the upstream document is wrong — but name it
+`exhausted`, not `blocked`: the executor never said it couldn't proceed, it just
+never got there.
 ### 5. COMMIT + TICK (on PASS)
 Two commits, in order (keeps code history clean of planning churn), both in
@@ -156,12 +169,62 @@ On first use, create the file with this structure:
 Report the task outcome (built, reviewed, committed). Then:
 - **Interactive default:** continue to the next unchecked task. Pausing for the
   user between tasks is fine and expected.
-- If the user asked to **run it through** ("do it all", "build everything"), keep
-  looping until done or a blocker stops you — committing per passed task as you go.
+- If the user asked to **run it through** ("do it all", "build everything"), or
+  `tiny-spec-loop` invoked you, keep looping until one of the five terminal states
+  below is reached — committing per passed task as you go.
+**The task list is the budget.** The loop ends when the tasks end. There is no turn
+ceiling, no token cap, and no max-tasks knob to set — adding one would put a second,
+weaker stopping rule next to the real one.
 There is **no** separate autonomous mode and **no** checkpoint config: one commit
 per passed task, always, on the current branch. (If the user wants a feature
-branch, create it once up front — that's their call, not a knob here.)
+branch, create it once up front — that's their call, not a knob here.) Running
+through is a caller's instruction, not a mode — every step above is identical either
+way, which is why a loop and a hand-driven build can't drift apart.
+## Halting
+Every build run ends in exactly **one** of five terminal states. Name it out loud in
+the closing report:
+| State | Cause |
+|---|---|
+| `done` | every task `[x]` and the final smoke passed |
+| `blocked` | the executor reported a `BLOCKER`, or the reviewer found a missing `visual:` command |
+| `exhausted` | convergence (step 4) spent its 2 fix attempts and the task is still red |
+| `paused` | a task's `pause:` point was reached |
+| `fork` | a genuine either/or the plan doesn't pin down |
+**Never round up.** Only `done` may report the work as built. A run that ended at
+`blocked`, `exhausted`, `paused`, or `fork` has unbuilt work in it, and a closing
+report that calls it done is worse than the halt itself — it converts a stop the user
+could act on into a false completion they won't check. Say the state, then say what's
+left and which command resolves it.
+**`blocked` and `exhausted`** log **one** entry with `type: blocker` — an upstream doc
+must change; see **Blockers** below. **`fork`** logs `type: halt`:
+```
+## D-NNN — <short title>
+- type: halt
+- state: fork
+- date: <ISO date>
+- affects: REQ-N, T<n>
+- note: <the options, your recommendation, and what the user has to decide>
+```
+Write one entry per halt, not one per cause — a blocker that halts the loop is a single
+event and reads as two records if you log it twice.
+**`done` and `paused` log nothing.** A green tree with every box ticked already says
+`done`. And a `paused` run stopped at a task whose `pause:` line is sitting right there
+in `tasks.md` saying why — an entry would restate what the file already tells you, and
+the log is for things that aren't otherwise visible. Report it, don't record it.
+The task the loop stopped at stays `[ ]`. That is the whole resume mechanism:
+re-running `tiny-spec-build` (or `tiny-spec-loop`) picks up at exactly that task with no
+conversational context needed.
 ## Blockers (never hack around)
@@ -170,16 +233,22 @@ command** for a `design:` task, or when convergence (step 4) exhausts its attemp
 1. Leave the task `[ ]`.
 2. Log it to `.spec/<active>/decisions.md` using the fixed skeleton (`type: blocker`,
-   naming the upstream doc to fix in `note:`, and the affected `REQ-N`/`T<n>` in
-   `affects:`). Create the file if absent:
+   the terminal state in `state:`, the upstream doc to fix named in `note:`, and the
+   affected `REQ-N`/`T<n>` in `affects:`). Create the file if absent:
    ```
    ## D-NNN — <short title>
    - type: blocker
+   - state: blocked
    - date: <ISO date>
    - affects: REQ-N, T<n>
    - note: <what stopped you; which upstream doc must change>
    ```
+   `state:` is `blocked` for an executor blocker or a missing `visual:`, and
+   `exhausted` when convergence ran out. Both route upstream the same way; the
+   distinction is what the user reads to know whether the task was impossible or just
+   never converged.
 3. **Surface and route upstream:** `tiny-spec-plan` (a design gap, a missing `visual:`
    command, or a token the Design system doesn't define) or `tiny-spec-create` (a
    requirement is wrong/impossible), in update mode. Never resolve a missing `visual:`
@@ -190,6 +259,12 @@ command** for a `design:` task, or when convergence (step 4) exhausts its attemp
 A genuine fork the plan doesn't pin down → don't guess: present the options + your
 recommendation, get the user's call, record it in `decisions.md`, then continue.
+**When running through, a fork is a halt** (`type: halt`, `state: fork`) — record the
+options and your recommendation in the `note:` and stop, rather than blocking on an
+answer nobody may be present to give. Ask only when the user is in the conversation
+with you; a question asked into an empty room stalls the run without ending it, and
+the halt is what makes the same fork readable hours later.
 ## Completion
 When every task in `tasks.md` is `[x]`:
@@ -199,10 +274,11 @@ When every task in `tasks.md` is `[x]`:
    setup — install/build, not a test-runner shortcut). There is no separate
    verify skill — this final smoke confirms the requirements actually work end-to-end, not
    just that tasks are ticked.
-2. **Report** — what was built, the commits made (with the branch), and any open
-   `decisions.md` items (blockers, tasks unchecked by a reconcile). If the final
+2. **Report** — the terminal state by name (`done` here, since every task is `[x]`
+   and the smoke passed), what was built, the commits made (with the branch), and any
+   open `decisions.md` items (blockers, tasks unchecked by a reconcile). If the final
    smoke reveals a gap, it's a bug to fix now (new/edited task) or a blocker to
-   route upstream — not a pass.
+   route upstream — **not** a pass, and not `done`.
 3. **Close the ticket (reference-only).** If a ticket is bound, this is where the
    **closing** keyword belongs — on the final / PR commit, not the per-task ones:
    GitHub `Closes #123`, ADO `Fixes AB#123`. Jira/Monday have no closing keyword,

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny-spec-create/SKILL.md RENAMED Viewed

@@ -111,6 +111,21 @@ Only the **project-wide** questions collapse — still confirm this story's bind
 requirements. If there is **no `BREAKDOWN.md`**, or no entry matches, run the **full
 interview** below unchanged.
+**Exception — a loop run.** If the caller says this is a **loop run** and names the
+story's slug (`tiny-spec-loop` does, through `tiny-spec-run`), skip step 6's
+confirmation and write `SPEC.md` straight out. The `AC:` lines *are* the approval: the
+user reviewed them when they wrote or accepted `BREAKDOWN.md`, and re-confirming them
+once per story is asking the same question twice — across a seven-story run it is the
+difference between walking away and being interrupted seven times. Report the captured
+`REQ-N` instead of asking about them.
+This waives **only** that confirmation. Everything that is a genuine question still
+stops the run: a story whose `AC:` lines contradict each other or the Decisions block,
+an `AC:` you cannot turn into a testable `REQ-N`, a missing ticket id the platform
+needs, a design export the story names that isn't on disk. Those are not ceremony —
+they are the human input the loop is supposed to stop for. Never guess past one because
+a loop is running.
 ## Pick the slug (resolve the active dir)
 **Fresh modes only** — in reseed or update mode the active dir already exists and you

tiny_spec-0.5.0/tiny-spec-loop/SKILL.md ADDED Viewed

@@ -0,0 +1,188 @@
+---
+name: tiny-spec-loop
+description: Work a list of stories end to end, one after another — for each story cut a branch from main, plan it, build it, merge it back locally, then move to the next. Reads BREAKDOWN.md by default, or a list pasted at invocation. Halts the WHOLE run on a blocker, a spent convergence budget, a task's pause: point, a genuine fork, a merge conflict, or a red gate after a merge — and names which. Use for "build the backlog", "work through the breakdown", "build these features one after another". NOT for a single story — for that use tiny-spec-run then tiny-spec-build.
+---
+# tiny-spec-loop
+A **router**, not a stage. It owns no artifact, writes nothing, and holds no state
+file. It walks a list of stories and, for each one, drives the existing flow to a
+finished, merged branch — then moves to the next.
+Per story the cycle is always the same four moves:
+```
+cut a branch from main  →  tiny-spec-run  →  tiny-spec-build  →  merge back to main
+```
+**Everything it decides comes from files on disk and from git.** Which stories are
+built, which are merged, which haven't started — all derived, never recorded. That is
+what makes a run abandoned overnight resume correctly tomorrow, and it is why this
+skill needs no run log, pointer, or lock. Do not "optimize" this into stored state.
+**It supplies one thing the flow was missing: a stopping rule.** The task list is the
+goal, the independent reviewer running the real gate is the verification, `memory.md`
+plus a commit per passed task is the memory. This skill adds when to stop, and nothing
+else — no budget, no turn ceiling, no config.
+## Step 0 — the run brief
+The one interactive moment. Everything after it runs without asking unless a stage
+genuinely needs an answer.
+1. **Check the preconditions.** All three, before touching anything:
+   - it is a git repo (`git rev-parse --is-inside-work-tree`);
+   - the working tree is **clean** (`git status --porcelain` prints nothing) — a dirty
+     tree would get swept into the first story's commits;
+   - an integration branch exists — `main`, or `master` if there is no `main`.
+   Any of them failing → say which and stop. Do not offer to stash, commit, or create
+   the branch for the user.
+2. **Resolve the story list** (Step 1) and play it back in order — slug and title —
+   with the state you derived for each (Step 2). This is the user's chance to
+   reorder, drop, or narrow before anything is cut.
+3. **Take the pause policy.** Ask for, or accept, standing technical stop points for
+   this run — *"halt before anything that touches auth"*, *"stop before any schema
+   migration"*. Carry the wording verbatim into every story's `tiny-spec-tasks` stage
+   (Step 3), where it becomes a real `pause:` line on the matching task. Pause points
+   are **technical**, not per-story: there is no way to mark a whole story for review,
+   because the thing worth looking at is a migration or an auth boundary, not a
+   feature heading.
+Step 0 is a **once-per-run** check. Do not re-run it between stories.
+## Step 1 — the story list
+**Default: `BREAKDOWN.md` at the project root**, in file order. Each `- Story:` under
+each `## Feature:` heading is one item; take its **`slug:`** — that names both the
+branch and the `.spec/<slug>/` dir. A `## Feature:` heading is a grouping, not an item:
+it carries no slug, so a Feature with three stories is three branches and three merges.
+**A list pasted at invocation wins** over `BREAKDOWN.md` when the user gives one. Treat
+each line as a story title and derive a kebab-case slug from it. Such a story has **no
+acceptance criteria**, so `tiny-spec-create` will run its full interview when it reaches
+that story — which is correct, not a failure: a one-line feature name is not enough to
+build from, and that interview *is* the human input the run stops for. Say so in Step 0
+so the user knows a pasted list is a supervised run, not a walk-away one.
+If neither exists, stop and say so. Never invent the list.
+## Step 2 — where each story stands (derive, don't record)
+For each story slug, in order, ask git — **in this order**, first match wins:
+1. **`git show <integration>:.spec/<slug>/tasks.md`** succeeds and every task is `[x]`
+   → **built and merged.** Skip it.
+2. Otherwise, if the branch exists (`git rev-parse --verify <slug>`), read
+   **`git show <slug>:.spec/<slug>/tasks.md`**:
+   - succeeds, every task `[x]` → **built, not merged** → resume at the **merge** (4).
+   - succeeds, at least one `[ ]` → **in progress** → resume at the **build** (3).
+   - fails (no task list yet) → **planning incomplete** → resume at the **plan** (2).
+3. Otherwise → **not started.** Run the full cycle.
+Ask **git**, not the working tree. A story that isn't merged yet has no `.spec/<slug>/`
+on the integration branch at all, so "does the directory exist" can't tell "not started"
+apart from "built on a branch you haven't merged" — reading each ref explicitly can.
+Sourcing step 1 from the integration branch is also what survives a deleted branch: once
+a story is merged, its ticked task list is part of `main` whether or not the branch that
+built it still exists.
+## Step 3 — the per-story cycle
+For the first story that isn't already built and merged:
+1. **Branch.** `git switch <slug>` if it already exists; otherwise
+   `git switch -c <slug> <integration>` — cut **fresh from the integration branch** so
+   this story sees every story merged before it. That is what makes an ordered list
+   build correctly: story 3 gets stories 1 and 2 already in its tree.
+2. **Plan.** Invoke **`tiny-spec-run`**, once. It resolves `.spec/<slug>/` from the
+   branch name automatically, so you don't name the ticket dir. Hand it two things:
+   - a **create-stage brief**: *this is a loop run; seed from the `BREAKDOWN.md` story
+     with slug `<slug>` and do not stop to confirm the requirements — its `AC:` lines
+     are already approved.* Omit the seeding clause for a pasted-list story; there is
+     nothing to seed from and the interview is correct.
+   - a **tasks-stage brief**: the pause policy from Step 0, verbatim, so the technical
+     stop points land as `pause:` lines.
+   If `tiny-spec-run` stops anywhere other than **L9** (tasks ready) or **L10** (already
+   built), that is a halt — report and stop the whole run. **Never invoke it twice to
+   push past its own stop:** each of those is a human decision it deliberately declined
+   to make, and running it again declines again.
+3. **Build.** Invoke **`tiny-spec-build`**, once, briefed to run it through. It owns
+   the per-task loop and writes its own halt record. Anything other than `done` halts
+   the whole run — **do not merge a story that didn't finish**, and do not invoke build
+   a second time: it resumes from the checkbox state, so it lands on the very task that
+   just halted and halts there again.
+4. **Merge — only on `done`.** In order:
+   - `git switch <integration>`
+   - `git merge --no-ff <slug>` — the merge commit keeps each story legible in history.
+   - **Conflict** → `git merge --abort`, then halt `conflict` (below).
+   - **Run the constitution's Verification commands on the merged result**, exercised
+     the way a user would. A story that was green alone can still break against work
+     merged before it, and that is exactly what this catches. Red → halt `blocked`.
+   - **Never push.** Merging locally keeps a bad run one `git reset` away; sending it
+     to a remote is the user's call, and this suite makes no network calls.
+5. **Next story.** Return to Step 2. Do not re-run Step 0.
+## Step 4 — report
+Name, in this order:
+1. **The terminal state** — exactly one of `done`, `blocked`, `exhausted`, `paused`,
+   `fork`, `conflict`. Use the word.
+2. **Stories built and merged**, in order, with their merge commits.
+3. **The story it stopped on**, the task within it, and why in one line.
+4. **Stories never started** — say how many are left, by name. A run that stopped at
+   story 2 of 7 must not read like a finished backlog.
+5. **The one command that resolves it** — `tiny-spec-create`/`tiny-spec-plan` in update
+   mode for `blocked`/`exhausted`, `tiny-spec-loop` again for `paused`, the decision
+   the user owes you for a `fork`, or the conflicted paths for a `conflict`.
+**Only `done` — every story merged — may report the work as built.** A run that halted
+has unbuilt stories in it, and a report that rounds `blocked`, `exhausted`, `paused`,
+`fork`, or `conflict` up to done converts a stop the user could act on into a false
+completion they won't check. Say the state, then say what's left.
+### Halting
+A halt stops **the whole run**, not just the current story. Later stories in a list you
+wrote top to bottom usually assume the earlier ones landed, so skipping ahead past a
+failure produces a second, more confusing failure downstream.
+`tiny-spec-build` records its own halts (`blocked`, `exhausted`, `fork`) in the story's
+`decisions.md`. **You record nothing** — the merge-stage halts are already legible
+without a log: a `conflict` leaves the story's branch unmerged and git itself reports
+the conflicted paths, and a red gate after a merge is reported by the gate. A log entry
+restating what git already shows is a second source of truth with extra steps.
+**On a red gate after a merge, leave the merge in place.** Report it, name the story,
+and tell the user that `git reset --hard HEAD~1` on the integration branch undoes it.
+Do not undo it yourself: fixing forward and rolling back are both reasonable, the
+choice is theirs, and discarding a real merge is not a call a router gets to make.
+### Hard rules
+- **Never write, edit, or flip anything.** No `status:`, no checkbox, no
+  `decisions.md` entry, no code, no `BREAKDOWN.md` edit. Delegate or stop.
+- **Never push, force, rebase, reset, or delete a branch.** The only git commands this
+  skill issues are `switch`, `switch -c`, `merge --no-ff`, `merge --abort`, and
+  read-only queries. Everything outward-facing or destructive is the user's.
+- **Never merge a story whose build didn't return `done`.**
+- **At most one `tiny-spec-run` and one `tiny-spec-build` per story.**
+- **Never invoke `tiny-spec-loop`.** Re-entering means re-reading these steps, not
+  calling yourself. Self-invocation compounds context and does not terminate.
+- **Never invoke `tiny-spec-create`, `tiny-spec-plan`, or `tiny-spec-tasks` directly.**
+  That ladder is `tiny-spec-run`'s; walking it here would duplicate it, and two ladders
+  drift. Briefs are passed *through* run, not around it.
+- **Never resolve a halt yourself.** A blocker means an upstream document is wrong,
+  which is the user's call. Routing to `plan`/`create` in update mode automatically
+  would let the loop rewrite the requirement its own task just failed to satisfy — the
+  agent grading its own homework, one level up.
+- **There is no budget to set.** The story list is the budget: the run ends when the
+  stories end. No turn ceiling, no token cap, no max-stories knob.

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny-spec-run/SKILL.md RENAMED Viewed

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-run
-description: Run the spec flow end to end — read each artifact's status flag to work out where the active ticket stands, then invoke tiny-spec-create → tiny-spec-plan → tiny-spec-tasks in order, taking anything marked stale before anything missing. STOPS before tiny-spec-build; it never builds, never commits, and never writes an artifact itself. Use for "run the whole spec flow", "spec this out end to end", or "pick the chain back up after a change". NOT for a single stage — for that, invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-tasks directly.
+description: Run the spec flow end to end — read each artifact's status flag to work out where the active ticket stands, then invoke tiny-spec-create → tiny-spec-plan → tiny-spec-tasks in order, taking anything marked stale before anything missing. STOPS before tiny-spec-build; it never builds, never commits, and never writes an artifact itself. Use for "run the whole spec flow", "spec this out end to end", or "pick the chain back up after a change". NOT for a single stage — for that, invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-tasks directly. NOT for building — for "spec it out and build it", use tiny-spec-loop.
 ---
 # tiny-spec-run
@@ -29,9 +29,11 @@ to resolve. `tiny-spec-create` picks `BREAKDOWN.md` up on its own when it exists
 If the user named a **single stage** ("update the spec", "redo the tasks"), hand off
 to that skill and stop. `run` is for walking the chain, not for wrapping one stage.
-If they asked for the flow **and** the build ("spec this out and build it"), run the
-chain as normal and stop at the end anyway — then tell them `tiny-spec-build` is the
-next command. The stop is not negotiable; see the hard rules.
+If they asked for the flow **and** the build ("spec this out and build it"), that is
+`tiny-spec-loop` — hand off to it and stop. If you are *already* inside a
+`tiny-spec-loop` run (it invoked you), run the chain as normal and stop at the end
+anyway; the loop takes it from there. Either way **you** never enter the build. The
+stop is not negotiable; see the hard rules.
 Step 0 is a **once-per-run** check on the user's opening request. Do not re-run it
 when you return to Step 1 after a stage.
@@ -181,6 +183,13 @@ something new:
   fall back to an existing ticket dir — the user confirmed this is new work.*
   (`tiny-spec-create` honors that phrase by skipping its sole-dir fallback.)
+**Caller briefs — pass them through verbatim.** A caller (today, `tiny-spec-loop`) may
+hand you a brief addressed to a specific stage: *"for the create stage: …"*, *"for the
+tasks stage: …"*. Append it, **word for word**, to the scope you send that stage, and
+send nothing to the others. Do not summarize it, act on it yourself, or let it change
+which rung fires — the ladder is still yours, and a brief is cargo, not an instruction
+to you. A brief for a stage this run never reaches is simply never delivered.
 **A stage's closing "point the user at X" is not a terminus.** Each stage ends by
 naming the next skill ("point the user at `tiny-spec-plan`"). Inside a run that
 sentence is a *report*, not a stop — when a stage finishes, return to Step 1 and keep
@@ -224,5 +233,9 @@ invent a `## Design` section and the condition would still hold on the next pass
 Telling the user once and letting them decide is the version that terminates.
 Then hand off explicitly: **run `tiny-spec-build` when you're ready to build** (it
-starts at the first unchecked task). If you stopped at L4 or on a bound, say exactly
-what stopped you and what the user needs to decide.
+starts at the first unchecked task, reviewing as it goes), or **`tiny-spec-loop`** to
+run it through until the work is built or something stops it. If you stopped at L4 or
+on a bound, say exactly what stopped you and what the user needs to decide.
+(If `tiny-spec-loop` invoked you, this report is what it reads to decide whether to
+build — so say which rung you stopped on either way.)

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny-spec-tasks/SKILL.md RENAMED Viewed

@@ -45,6 +45,7 @@ For each task, write:
   - type: feat            # optional; Conventional Commit type (defaults to feat)
   - req: REQ-n            # optional; the REQ-N this task delivers
   - design: D-n           # optional; the SPEC.md D<n> screen this task builds — arms the visual gate
+  - pause: <why>          # optional; halt the loop before this task so a human looks first
   - files: <comma-separated hint of files it will touch>
 ```
@@ -70,6 +71,32 @@ other. Two rules:
 - Only set it if the constitution has a `visual:` verification command. Without one
   the reviewer cannot render anything and will raise a blocker instead of a verdict.
+**pause** is the other field that changes what happens rather than what gets written —
+but where `design:` changes how a task is **graded**, `pause:` changes whether the loop
+**continues**. Set it and `tiny-spec-build` halts *before* that task, leaving it
+unchecked, so a human reviews the approach while redirecting it is still cheap. The
+value is one line saying what to look at.
+Propose it only on work that is genuinely **irreversible or wide-blast-radius**:
+- a data migration, or anything that writes to real rows;
+- a destructive or bulk file operation;
+- pulling in a new third-party dependency;
+- an auth, permissions, or trust boundary;
+- a public API or schema contract other people's code depends on.
+**When in doubt, leave it out.** A pause the user didn't want is worse than no pause at
+all — it trains them to wave past the ones they did want, which is exactly the reflex
+that makes the mechanism useless the one time it matters. Most task lists should carry
+zero or one.
+**A caller may hand you a standing pause policy** — *"halt before anything that touches
+auth"*, *"stop before any schema migration"* (`tiny-spec-loop` passes one through
+`tiny-spec-run`). Apply it to **this** task list: any task matching the description gets
+a `pause:` naming the policy that put it there, on top of whatever you'd have set
+anyway. A policy that matches nothing here is not an error — say so and move on, rather
+than stretching a task to fit it.
 Cover **every** part of the approach — together the tasks must deliver all
 `REQ-N`. Don't leave a requirement with no task. Likewise, if `SPEC.md` has a
 `## Design` section, every `D<n>` in it needs at least one task carrying that
@@ -91,9 +118,10 @@ updated: <ISO date>
 # Tasks — <project / feature name>
 > Executed top to bottom, one at a time. A checked `[x]` task is implemented AND
-> reviewed. `type:`, `req:`, and `design:` are optional; `files:` is a hint, not an
-> ownership contract. A task with `design:` is also graded against that screen's
-> `D<n>` entry and the constitution's Design system.
+> reviewed. `type:`, `req:`, `design:`, and `pause:` are optional; `files:` is a hint,
+> not an ownership contract. A task with `design:` is also graded against that screen's
+> `D<n>` entry and the constitution's Design system. A task with `pause:` halts the
+> build before it runs, so a human looks first.
 ## Tasks
@@ -112,6 +140,7 @@ updated: <ISO date>
 - [ ] T3 — <…>
   - acceptance: <observable outcome>
+  - pause: <optional; what to check before this runs — irreversible work only>
   - files: <path, path>
 ```
@@ -138,5 +167,7 @@ When `tasks.md` is `status: stale`:
 ## When done
-Report the task count and point the user at `tiny-spec-build` (one task at a time) or
-note they can run it straight through.
+Report the task count — and any `pause:` points you set, with their reason, so the user
+can drop one before it fires. Then point them at `tiny-spec-build` (one task at a time,
+reviewing as it goes) or `tiny-spec-loop` (run it through until it's built or something
+stops it).

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny_spec/__init__.py RENAMED Viewed

@@ -5,4 +5,4 @@ into your Claude Code config directory (``~/.claude/`` by default). It adds no
 runtime behavior to the suite itself.
 """
-__version__ = "0.4.0"
+__version__ = "0.5.0"

{tiny_spec-0.4.0 → tiny_spec-0.5.0}/tiny_spec/manifest.json RENAMED Viewed

@@ -3,6 +3,7 @@
     "tiny-spec-prd",
     "tiny-spec-breakdown",
     "tiny-spec-run",
+    "tiny-spec-loop",
     "tiny-spec-create",
     "tiny-spec-plan",
     "tiny-spec-tasks",