tiny-spec 1.1.0__tar.gz → 1.2.0__tar.gz

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tiny-spec
-Version: 1.1.0
+Version: 1.2.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
@@ -498,15 +498,38 @@ resumes from the checklist state.
 ### Working a whole list
 
 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:
+"spec it out and build it" — and it takes a list of stories and works them in batches.
+Per story it does the same four moves:
 
 ```
 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
-and 2 already merged — which is what makes an ordered list build correctly.
+Each branch is cut **fresh from main**, so a later story sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
+
+**Independent stories build at the same time.** A story can declare what it must follow
+with a `needs:` line in `BREAKDOWN.md`; everything with no unmet `needs:` forms a batch
+and builds **concurrently, one git worktree per story**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: interface
+
+- Story: expose both helpers on a CLI     slug: cli
+  - AC: `textkit slugify "Hi There"` prints "hi-there"
+  - needs: slugify, wordwrap
+```
+
+Omit `needs:` when a story stands alone — that's the common case, and the field is meant
+to be rare. A `needs:` you didn't need costs you parallelism forever; one you missed
+costs a single merge conflict, which the run already catches and halts on. You can also
+just name the set yourself at invocation ("build these three at once"), which overrides
+the graph. A cycle, or a `needs:` naming a story that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a story never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across stories only.
 
 **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
@@ -529,9 +552,13 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 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
-just produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run after that batch.** Its siblings
+were declared independent, so they finish and merge — killing working lanes because one
+failed throws away good work. But the run does not start the next batch: later stories
+usually assume the earlier ones landed, so skipping ahead past a failure just produces a
+second, more confusing failure downstream. With more than one lane you get each story's
+own state, and the run's state is the worst of them — four green lanes and one `blocked`
+is a `blocked` run.
 
 **Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
@@ -547,12 +574,15 @@ destructive file operations, a new dependency, an auth boundary, a public API co
 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.
+**What it will not do to your repo.** It runs exactly seven git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, `worktree add`, `worktree list`, and
+reads. It refuses to start on a dirty tree, or if a worktree path it needs already
+exists. It **never pushes**, never rebases, never resets, never deletes a branch, never
+removes a worktree, 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 — and it hands
+back the `git worktree remove` commands for the lanes instead of running those either,
+since a halted lane's worktree is the tree you need to look at.
 
 **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

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/README.md

@@ -461,15 +461,38 @@ resumes from the checklist state.
 ### Working a whole list
 
 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:
+"spec it out and build it" — and it takes a list of stories and works them in batches.
+Per story it does the same four moves:
 
 ```
 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
-and 2 already merged — which is what makes an ordered list build correctly.
+Each branch is cut **fresh from main**, so a later story sees the earlier ones already
+merged — which is what makes an ordered list build correctly.
+
+**Independent stories build at the same time.** A story can declare what it must follow
+with a `needs:` line in `BREAKDOWN.md`; everything with no unmet `needs:` forms a batch
+and builds **concurrently, one git worktree per story**, three at a time by default.
+The batch merges, then the next one starts.
+
+```
+## Feature: interface
+
+- Story: expose both helpers on a CLI     slug: cli
+  - AC: `textkit slugify "Hi There"` prints "hi-there"
+  - needs: slugify, wordwrap
+```
+
+Omit `needs:` when a story stands alone — that's the common case, and the field is meant
+to be rare. A `needs:` you didn't need costs you parallelism forever; one you missed
+costs a single merge conflict, which the run already catches and halts on. You can also
+just name the set yourself at invocation ("build these three at once"), which overrides
+the graph. A cycle, or a `needs:` naming a story that isn't there, stops the run rather
+than being guessed past.
+
+**Tasks *inside* a story never run in parallel.** They share files and each one assumes
+the last landed, so they stay strictly sequential. Parallelism is across stories only.
 
 **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
@@ -492,9 +515,13 @@ honest trade: a breakdown runs unattended, a pasted list is supervised.
 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
-just produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run after that batch.** Its siblings
+were declared independent, so they finish and merge — killing working lanes because one
+failed throws away good work. But the run does not start the next batch: later stories
+usually assume the earlier ones landed, so skipping ahead past a failure just produces a
+second, more confusing failure downstream. With more than one lane you get each story's
+own state, and the run's state is the worst of them — four green lanes and one `blocked`
+is a `blocked` run.
 
 **Pause points are technical, not per-story.** Any task can carry a `pause:` line, and
 the build halts *before* running it:
@@ -510,12 +537,15 @@ destructive file operations, a new dependency, an auth boundary, a public API co
 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.
+**What it will not do to your repo.** It runs exactly seven git commands — `switch`,
+`switch -c`, `merge --no-ff`, `merge --abort`, `worktree add`, `worktree list`, and
+reads. It refuses to start on a dirty tree, or if a worktree path it needs already
+exists. It **never pushes**, never rebases, never resets, never deletes a branch, never
+removes a worktree, 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 — and it hands
+back the `git worktree remove` commands for the lanes instead of running those either,
+since a halted lane's worktree is the tree you need to look at.
 
 **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

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/agents/tiny-spec-build-executor.md

@@ -15,6 +15,12 @@ pleasantries.
 
 Everything you need and nothing you don't:
 
+- **the working directory** to operate in. Every path you read, write, or run a command
+  against resolves against it. It may be a **git worktree** rather than the main checkout
+  — a build can run several stories at once, each in its own worktree. **Never read or
+  write outside the directory you were given**, and never `cd` to a sibling worktree to
+  "check something": another story is being built there right now, and what you find will
+  be wrong by the time you act on it;
 - the **task id**, **description**, and **acceptance** (the outcome that proves it done);
 - a **`files:` hint** — likely paths to touch (guidance, not a hard boundary);
 - the full **constitution** (`constitution.md`): Style, Engineering standards,

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/agents/tiny-spec-build-reviewer.md

@@ -13,6 +13,11 @@ back to `tiny-spec-build`; return data, not pleasantries.
 
 ## What you receive (the context contract)
 
+- **the working directory** to operate in — every path and every gate command resolves
+  against it. It may be a **git worktree** rather than the main checkout, since a build
+  can run several stories at once. **Never read, write, or run a gate outside the
+  directory you were given**: a sibling worktree holds a different story mid-build, and
+  measuring it would make your verdict meaningless;
 - the **task id**, **description**, and **acceptance** (the outcome that must hold);
 - the full **constitution** (`constitution.md`) — especially **Guiding invariants**,
   **Definition of Done**, and **Verification commands**, plus the **Design system**
@@ -54,6 +59,18 @@ acceptance and the constitution — verified, not inferred?**
    task on evidence you found insufficient is not** — that is the one thing this whole
    role exists to prevent. Never narrow a `full` gate to `scoped`.
 
+   **A Verification command that cannot run in this environment is a `FAIL` and a
+   blocker — never a `PASS`.** If a documented command is red for a reason the task's
+   code cannot fix (the interpreter is too old, a tool isn't installed, the command was
+   never runnable as written), say exactly that in `GATE:`, return `FAIL`, and name the
+   **constitution** as the upstream document to fix. Proving the task green *somewhere
+   else* — a fresh venv, a container, an install you fixed by hand — is **not** a pass:
+   you verified a different environment than the one the gate names, and the next task
+   will hit the identical red. Diagnosing the cause and demonstrating the task's own code
+   is sound is genuinely useful; put it in `FINDINGS` so the fix is cheap. It does not
+   change the verdict. A constitution whose gate cannot run is the single most dangerous
+   file in the project, because every later task inherits the same false signal.
+
    Say which scope you actually ran in `GATE:`, including that you escalated and why.
 3. **Exercise the acceptance.** Trigger the task's stated outcome the most
    black-box way available (CLI > HTTP > public API) with realistic input,
@@ -78,25 +95,23 @@ acceptance and the constitution — verified, not inferred?**
    - **A selector that matches nothing is a `FAIL`, never a skip.** Either the code
      didn't build the element or it named it something else — both are real, and both
      are invisible if you quietly move on. Report the selector and that it was absent.
-   - Compare each element's numbers to the tokens its row names. Report concrete
-     deltas ("heading is 28px, `type.heading.lg` is 24px"; "padding 19px is not on
-     the `space.*` scale"). **Do not pixel-diff the screenshot** — font antialiasing
-     makes image comparison flaky enough that the check gets ignored, which is
-     exactly how visual gates die.
-   - **Check `layout:`** — the arrangement, max width, and the **order** it names.
-     Use the bounding rectangles: elements listed in order should appear in that
-     order down the page (or across it, for a row). Every token can be correct on an
-     element that is in the wrong place.
-   - **Exercise every state the entry names** — empty, loading, error, success.
-     Drive the UI into each one and observe what changes; **finding the word in the
-     source is not evidence**, and it false-passes routinely (a comment saying the
-     loading state is missing contains "loading"). A surface that renders its happy
-     path and nothing else is a fail, not a nit.
-   - Finally, **judge the render against the export.** Everything above proves the
-     numbers are right. None of it can see an element that is present, on-token, and
-     invisible — so now look. `Read` each `SCREENSHOT <state> <path>` the `visual:`
-     command printed, `Read` the `D<n>`'s `export:` image, and grade **every state you
-     have a screenshot for**, not just the happy path, on four lines:
+   - Compare each element's numbers to the tokens its row names, reporting concrete
+     deltas ("heading is 28px, `type.heading.lg` is 24px"; "padding 19px is not on the
+     `space.*` scale"). **Do not pixel-diff the screenshot** — font antialiasing makes
+     image comparison flaky enough that the check gets ignored, which is how visual
+     gates die.
+   - **Check `layout:`** — the arrangement, max width, and the **order** it names, from
+     the bounding rectangles. Every token can be correct on an element in the wrong place.
+   - **Exercise every state the entry names** — empty, loading, error, success. Drive the
+     UI into each one and observe what changes; **finding the word in the source is not
+     evidence**, and it false-passes routinely (a comment saying the loading state is
+     missing contains "loading"). A surface that renders its happy path and nothing else
+     is a fail, not a nit.
+   - Finally, **judge the render against the export.** Everything above proves the numbers
+     are right; none of it can see an element that is present, on-token, and invisible —
+     so now look. `Read` each `SCREENSHOT <state> <path>` the `visual:` command printed
+     and the `D<n>`'s `export:` image, and grade **every state you have a screenshot
+     for**, not just the happy path, on four lines:
 
      1. **Presence** — is every `elements:` row actually *visible* in the render? At
         `opacity: 0`, zero height, clipped out of view, hidden behind a sibling, or the
@@ -104,24 +119,21 @@ acceptance and the constitution — verified, not inferred?**
         not there. **FAIL** — this is why the step exists.
      2. **Legibility & occlusion** — text clipped, truncated mid-word, overlapping
         another element, or on a background it can't be read against. **FAIL.**
-     3. **Correspondence** — does the render show the same screen as the export: the
-        same regions, in the reading order `layout:` names? A whole region missing is a
-        **FAIL**; a stylistic difference is a **flag**.
+     3. **Correspondence** — the same regions as the export, in the reading order
+        `layout:` names? A whole region missing is a **FAIL**; a stylistic difference is
+        a **flag**.
      4. **Hierarchy & polish** — emphasis, balance, crowding, alignment. **Always a
         flag**, never a fail.
 
-     Three rules bound it:
-
-     - **The numbers beat your eye on anything they already measured.** Padding that is
-       on the `space.*` scale but looks cramped is a `flag:`. A color that is exactly
-       its token but looks washed out is a `flag:`. You may fail only on what
-       measurement *cannot* see. Contradicting your own numbers sends the executor a
-       task it cannot fix, and the loop is bounded at two attempts.
-     - **This is still not a pixel diff.** The export is usually a wireframe — judge
-       structure and legibility, never visual identity.
-     - **Cite what you saw.** Name the state whose screenshot the finding came from and
-       what was in it ("state `error`: caption present in DOM but renders at opacity 0").
-       An uncited visual claim reads as an opinion and gets ignored.
+     Three rules bound it. **The numbers beat your eye on anything they already
+     measured** — on-scale padding that looks cramped, or an exact token that looks
+     washed out, is a `flag:`; you may fail only on what measurement *cannot* see, since
+     contradicting your own numbers sends the executor a task it cannot fix and the loop
+     is bounded at two attempts. **This is still not a pixel diff** — the export is
+     usually a wireframe, so judge structure and legibility, never visual identity. And
+     **cite what you saw**, naming the state the finding came from ("state `error`:
+     caption present in DOM but renders at opacity 0") — an uncited visual claim reads as
+     an opinion and gets ignored.
 
      **If the command printed no `SCREENSHOT` line**, do not run this sub-step and do
      not eyeball a substitute. Grade on steps 1–3 above, write `judge: not run — visual:

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tiny-spec"
-version = "1.1.0"
+version = "1.2.0"
 description = "A tiny, opinionated take on spec-driven development."
 readme = "README.md"
 requires-python = ">=3.9"

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/tiny-spec-build/SKILL.md

@@ -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. 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.
+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. Can be handed several lanes (one worktree + slug per independent story) and runs them concurrently, one task at a time within each. 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
@@ -19,16 +19,14 @@ alongside this skill (see the suite README).
 
 ## Inputs
 
-1. **Resolve the active ticket dir** from the current git branch: the `.spec/<slug>/`
-   whose slug matches the branch name (one branch per ticket). If none matches, use
-   the sole ticket dir if there's exactly one; else ask which. Call it `<active>`.
-   **Two cases pre-empt that order — ask instead of applying it:** more than one dir
-   matches the branch (there is no defined tie-break, and inventing one here would
-   silently disagree with every other skill), or ticket dirs exist while you are on
-   `main`/`master` with no name match (the usual cause is a forgotten `git switch`, and
-   the sole-dir fallback would otherwise swallow it). Detached HEAD or no git repo is a
-   **degraded** case, not an ask case — branch match is simply unavailable, so fall
-   through to sole-dir and ask as written.
+1. **Resolve the active ticket dir** (call it `<active>`), in order: the `.spec/<slug>/`
+   whose slug matches the current git branch (one branch per ticket); else the sole
+   ticket dir if exactly one exists; else ask. **Ask instead** when more than one dir
+   matches the branch, or when ticket dirs exist while you are on `main`/`master` with no
+   name match — neither has a safe tie-break. Detached HEAD or no git repo is
+   **degraded**, not an ask: fall through to sole-dir and ask as written.
+   In **multi-lane mode** (below) this step does not run: each lane is handed its
+   worktree and slug explicitly.
 2. Read `.spec/constitution.md` (**the shared constitution**), `.spec/memory.md` if
    it exists (**shared**), and `.spec/<active>/tasks.md`. The constitution + memory
    get injected **whole** into every executor and reviewer. Also note the `ticket`
@@ -37,6 +35,52 @@ alongside this skill (see the suite README).
    `tiny-spec-plan` to reconcile first.
 4. Pick the **first unchecked `[ ]`** task. If all are `[x]`, jump to **Completion**.
 
+## Multi-lane mode (optional — several stories at once)
+
+A caller may hand you **lanes** instead of a single active dir: one or more
+`(worktree path, slug)` pairs, each an independent story in its own git worktree.
+`tiny-spec-run` does this for a batch of stories whose `needs:` say they don't depend on
+each other. **With one lane, or none, everything below is inert and this skill behaves
+exactly as it always has** — that is the common case and it must not drift.
+
+Given lanes, run them **in rounds**:
+
+1. For every live lane, pick its first `[ ]` task and build the executor brief exactly as
+   step 2 describes — resolved against **that lane's worktree**, not the main checkout.
+2. **Dispatch every lane's executor in one message**, so they run concurrently.
+3. **Dispatch every lane's reviewer in one message**, once the executors are back.
+4. Commit and tick per passing lane, in that lane's worktree.
+
+Then start the next round with whichever lanes are still live. A fast lane waits at the
+round boundary for a slow one; that barrier is deliberate, and much simpler to follow than
+letting lanes free-run.
+
+**Within a lane nothing changes.** Tasks still run one at a time, top to bottom, with the
+same convergence bound, the same gate scope rules, and the same halting states. There is
+no parallelism *inside* a story and no `owns:` contract — tasks in one story share files
+and assume their predecessors landed, which is exactly why they stay sequential.
+
+**A halt stops that lane only.** The other lanes run to completion; you report each lane's
+terminal state separately. The stories were declared independent, so killing working lanes
+because one failed throws away finished work for nothing.
+
+**Every dispatched agent is told its working directory**, and that all paths resolve
+against it. An executor or reviewer must never read or write another lane's worktree.
+
+### `memory.md` in multi-lane mode
+
+`.spec/memory.md` is **shared at the `.spec/` root**, and step 6 below writes to it. Two
+lanes appending to their own copy in their own worktree would conflict on *every* parallel
+batch — a guaranteed merge failure that has nothing to do with the code.
+
+So: **in multi-lane mode, lanes do not write `memory.md` at all.** Collect each lane's
+distilled lessons as it goes, and write them **once, in the main checkout on the
+integration branch, after the batch has merged** — pruning superseded entries there, as
+step 6 describes. Single-lane runs are unaffected and write it in place as before.
+
+The other artifacts are safe and need no special handling: `tasks.md` and `decisions.md`
+are per-story, and `constitution.md` is read-only for the whole build.
+
 ## The per-task loop
 
 For the selected task, run these steps in order. **Do not tick a task until its
@@ -60,6 +104,9 @@ it short and concrete.
 ### 2. IMPLEMENT (dispatch `tiny-spec-build-executor`)
 Spawn one **`tiny-spec-build-executor`** with a fresh, self-contained prompt:
 
+- **the working directory** it must operate in — this lane's worktree, or the project
+  root in a single-lane run. Every path resolves against it, and it must never read or
+  write another lane's worktree;
 - the task id, description, and **acceptance**;
 - the `files:` hint;
 - the **whole** `.spec/constitution.md`;
@@ -69,10 +116,15 @@ Spawn one **`tiny-spec-build-executor`** with a fresh, self-contained prompt:
   design instead of guessing at it;
 - only the specific existing files the task starts from, named explicitly (so it
   edits with the real current contents, not blind);
-- the **previous passed task's `CHANGES` list**, if there is one, labelled as what the
-  last task left behind. Every executor starts cold and re-derives the codebase; naming
-  the files that just moved is the cheapest way to cut that, and you already have the
-  list in hand. Paths only — not the previous task's description, findings, or report.
+- the **accumulated `CHANGES` paths from every passed task in this story so far**,
+  labelled as the ground this story has already moved. Every executor starts cold and
+  re-derives the codebase from scratch — that re-derivation is the **largest single cost
+  in the loop**, far larger than the prompt text around it — and naming the files this
+  story has already touched is the cheapest way to cut it. You already have the lists in
+  hand. **Paths only**, deduplicated, most-recently-touched first — never the earlier
+  tasks' descriptions, findings, or reports. (The reviewer does *not* get this list: it
+  is scoped to the task's own changed files on purpose, and widening it would dilute the
+  independence that makes its verdict worth anything.)
 
 Do **not** pass the plan, sibling tasks, or other chatter. It returns a structured
 report (`STATUS`, `CHANGES`, `DECISIONS`, `BLOCKER`). A `STATUS: blocked` →
@@ -81,6 +133,8 @@ report (`STATUS`, `CHANGES`, `DECISIONS`, `BLOCKER`). A `STATUS: blocked` →
 ### 3. REVIEW (dispatch `tiny-spec-build-reviewer` — independent)
 Spawn one **`tiny-spec-build-reviewer`**, **blind to step 2**, with:
 
+- **the working directory** it must operate in — this lane's worktree, or the project
+  root in a single-lane run. It runs the gate there and touches no other lane;
 - the task id, description, and **acceptance**;
 - the **whole** `.spec/constitution.md`;
 - the list of changed files (from the executor's `CHANGES`) to read;
@@ -169,6 +223,9 @@ entry to the **shared** `.spec/memory.md` (the root — lessons are project-wide
 pruning any entry the new one supersedes. Skip code-style rules (→ shared
 `constitution.md`) and one-off history (→ the ticket's `decisions.md`). Keep it lean.
 
+**In multi-lane mode, do not write the file here.** Hold the entry and write it once
+after the batch merges — see **Multi-lane mode** above for why.
+
 On first use, create the file with this structure:
 
 ```markdown
@@ -212,7 +269,8 @@ 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:
+the closing report — **per lane**, when there is more than one; a lane's halt never
+rounds up into another lane's `done`, and the run's own state is the worst of them:
 
 | State | Cause |
 |---|---|

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/tiny-spec-plan/SKILL.md

@@ -18,19 +18,15 @@ sets `tasks.md`'s `status:`.
 
 Artifacts live under `.spec/`: the **shared** constitution at the root
 (`.spec/constitution.md`), the per-ticket `SPEC.md`/`PLAN.md`/`tasks.md` under
-`.spec/<slug>/`. **Resolve the active ticket dir** from the current git branch: the
-`.spec/<slug>/` whose slug matches the branch name (one branch per ticket). If none
-matches, use the sole ticket dir if there's exactly one; else ask which. Both skeletons
-are inline below — write them from there, no file to read. Requires
-`.spec/<active>/SPEC.md`.
-
-**Two cases pre-empt that order — ask instead of applying it:** more than one dir
-matches the branch (there is no defined tie-break, and inventing one here would
-silently disagree with every other skill), or ticket dirs exist while you are on
-`main`/`master` with no name match (the usual cause is a forgotten `git switch`, and
-the sole-dir fallback would otherwise swallow it). Detached HEAD or no git repo is a
-**degraded** case, not an ask case — branch match is simply unavailable, so fall
-through to sole-dir and ask as written.
+`.spec/<slug>/`. Both skeletons are inline below — write them from there, no file to
+read. Requires `.spec/<active>/SPEC.md`.
+
+**Resolve the active ticket dir**, in order: the `.spec/<slug>/` whose slug matches the
+current git branch (one branch per ticket); else the sole ticket dir if exactly one
+exists; else ask. **Ask instead** when more than one dir matches the branch, or when
+ticket dirs exist while you are on `main`/`master` with no name match — neither has a
+safe tie-break. Detached HEAD or no git repo is **degraded**, not an ask: branch match is
+simply unavailable, so fall through to sole-dir and ask as written.
 
 ## Step 1 — harden the constitution (`constitution.md`)
 
@@ -175,10 +171,19 @@ task it belongs to:
 - a task that only adds tests for the task before it (the constitution's **Definition of
   Done** already requires the tests to ship with the code);
 - one task per file, or one task per function;
-- a "wire it up" / "integrate the pieces" task trailing the pieces it wires.
+- a "wire it up" / "integrate the pieces" task trailing the pieces it wires;
+- a **leading pure-scaffold task** — a skeleton, a dispatch stub, a module that imports
+  cleanly and does nothing. Fold it into the first task that gives it behavior;
+- a **trailing end-to-end verification task**. `tiny-spec-build`'s Completion step already
+  runs the whole gate against the whole project from a clean state, exercised the way a
+  user would. A task that re-does it buys nothing and costs the full per-task overhead.
+
+The shipped `examples/todo-cli` task list predates these two smells and shows both: its
+`T1` is a pure scaffold and its `T5` is an end-to-end verification pass. Today `T1` folds
+into `T2` and `T5` doesn't exist. Read that list for `T4`'s sizing, not for its edges.
 
 **Count is a smell, not a cap.** A story sized the way `tiny-spec-scope` describes
-usually lands in **3–6 tasks**. If you are past about eight, re-read the list: you have
+usually lands in **2–4 tasks**. If you are past about six, re-read the list: you have
 either sliced below the commit line, or the story itself was too big and should have been
 split upstream. Check the list against that; do **not** enforce a number, and never drop
 or merge coverage just to hit one.

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/tiny-spec-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-run
-description: The one router — read each artifact's status flag to work out where work stands, then invoke the skill that moves it forward. Two stop points, chosen once at the start: by default it walks tiny-spec-adopt/create → design → plan and STOPS before tiny-spec-build; asked to build ("spec it out and build it") or handed a story list, it drives each story branch → plan → build → merge until the list ends or something halts it. Use for "run the spec flow", "pick the chain back up", "build the backlog", "work through the breakdown". NOT for a single stage — for that invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-design directly.
+description: The one router — read each artifact's status flag to work out where work stands, then invoke the skill that moves it forward. Two stop points, chosen once at the start: by default it walks tiny-spec-adopt/create → design → plan and STOPS before tiny-spec-build; asked to build ("spec it out and build it") or handed a story list, it drives each story branch → plan → build → merge until the list ends or something halts it. Independent stories — grouped by their BREAKDOWN.md needs: field, or named by the user — build concurrently, one git worktree per lane, merging batch by batch. Use for "run the spec flow", "pick the chain back up", "build the backlog", "work through the breakdown". NOT for a single stage — for that invoke tiny-spec-create, tiny-spec-plan, or tiny-spec-design directly.
 ---
 
 # tiny-spec-run
@@ -53,8 +53,8 @@ return to Step 2 after a stage, or between stories.
    the branch for the user.
 
 2. **Resolve the story list** (below) and play it back in order — slug and title — with
-   the state you derived for each. This is the user's chance to reorder, drop, or narrow
-   before anything is cut.
+   the state you derived for each, **grouped into the batches you will run**. This is the
+   user's chance to reorder, drop, narrow, or correct a dependency 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
@@ -63,6 +63,17 @@ return to Step 2 after a stage, or between stories.
    **technical**, not per-story: the thing worth looking at is a migration or an auth
    boundary, not a feature heading.
 
+4. **Fix the lane count.** Default **3**; take a number from the user if they gave one.
+   This is a concurrency limit on the machine, not a budget — the story list is still the
+   budget, and a batch wider than the lane count simply runs in successive fills. **One
+   lane must stay available**: any phrasing asking for one story at a time ("one at a
+   time", "no parallelism", "serially") sets it to 1, which collapses Step 4 to the
+   sequential behavior — no worktrees, no batching.
+
+   Then check one more precondition, once you know the slugs in the first batch: **no
+   target worktree path already exists.** Name the collisions and stop; do not reuse or
+   remove a directory you found.
+
 ## Step 1 — resolve the scope
 
 ### Stop-before-build: the active ticket dir
@@ -126,7 +137,26 @@ on the integration branch at all, so "does the directory exist" can't tell "not
 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.
+built it still exists. **This survives parallelism unchanged** — a worktree is just a
+branch, so a story built in a worktree but not yet merged lands on rule 2 exactly as one
+built in place.
+
+**Group the remaining stories into batches.** Level 0 is every unbuilt story whose
+`needs:` are empty or already built-and-merged; level 1 is every story whose `needs:` are
+all in level 0; and so on. Batches run **in order**; the stories inside one batch run
+**concurrently**, capped at the lane count.
+
+- **A parallel set the user named at invocation overrides the graph** for this run —
+  "build these three at once", or a pasted list they called independent. Explicit beats
+  derived, the same way a pasted story list already wins over `BREAKDOWN.md`. Say that you
+  are overriding, and name what the graph would have done.
+- **A cycle in `needs:` is a stop.** Print the cycle and stop. Never break it by picking
+  an order — `tiny-spec-scope` says two stories that need each other are really one, and
+  choosing for the user hides a carve that needs fixing.
+- **A `needs:` naming a slug that isn't in the list is a stop**, not a shrug. It is either
+  a typo or a story someone dropped, and both want a human.
+- **A batch of one is the sequential behavior** — Step 4 collapses to exactly what it did
+  before lanes existed. This is the common case for a single ticket and must not change.
 
 ## Step 2 — the ladder
 
@@ -146,67 +176,62 @@ re-evaluate against the new state on disk.
 | — | **no rung matched** | **stop** — report the exact state you found and ask; never improvise a stage |
 
 **Upstream beats downstream — that is what the table order encodes.** Always fix the
-earliest artifact in the chain that needs attention, whether it's stale *or* missing.
-Deriving a task list from a design you already know is wrong wastes the run, and then
-the reconcile has to uncheck completed work all over again.
+earliest artifact in the chain that needs attention, stale *or* missing. Deriving a task
+list from a design you already know is wrong wastes the run, and the reconcile then has
+to uncheck completed work all over again.
 
 **L0/L1 carry the greenfield/brownfield fork.** "Does this repo already contain source?"
-means: is there real code here beyond config and docs? If yes, the constitution should
-be *derived from that code* (`tiny-spec-adopt`) rather than interviewed out of the user
-— an interviewed constitution on an existing codebase is how you get a gate that names
-commands the project doesn't have. If the user is starting from an idea with no code
-yet, `tiny-spec-scope` is theirs to run first; it is not in the ladder (see below).
-
-**L1 is a reseed, not a fresh start.** The constitution is project-wide, so it can go
-missing while a perfectly good `SPEC.md` sits next to it. Invoke the chosen skill in
-**reseed/refresh mode** — say so explicitly, and add: *do not re-interview from scratch,
-do not create a ticket dir, and do not touch `SPEC.md`.* If the constitution still
-doesn't exist afterwards, stop and tell the user; do not loop.
-
-**L1 outranks L2** — a constitution gets reseeded even when the ticket dir or `SPEC.md`
-is also missing. The next pass then lands on L2 and creates the spec properly — and
-because that's a *different rung*, the same-skill bound below does not fire.
-
-**L3 is a stop, not a stage.** Nothing in the suite ever *sets* `SPEC.md` to stale — it
-is the root of the chain. A stale SPEC means someone hand-edited it, so surface it and
-offer `tiny-spec-create` in update mode rather than assuming intent. If the user says go
-ahead **in the same turn**, invoke it and carry on down the ladder — the stop is there
-to get a human decision, not to force a second command. (Update mode *clears* the flag
-on its way out, so this rung resolves rather than repeating.)
-
-**L4 is the one thing `run` checks that isn't a `status:` flag** — and it is
-deliberately *not* a validator. For each `D<n>` in the active `SPEC.md`, run
-`shasum -a 256 <export>` and compare with the `sha256:` the entry declares. You are
-checking whether an anchor still points at what it says it points at, not inferring
-whether two documents agree. A design that moved under a finished spec is otherwise
-completely invisible — no status flips, and the build reviews against a screen that no
-longer exists.
+means: real code beyond config and docs. If yes, the constitution must be *derived from
+that code* (`tiny-spec-adopt`) rather than interviewed out of the user — an interviewed
+constitution on an existing codebase is how you get a gate that names commands the
+project doesn't have. Starting from an idea with no code yet, `tiny-spec-scope` is the
+user's to run first; it is not in the ladder (see below).
+
+**L1 is a reseed, not a fresh start**, and it **outranks L2**. The constitution is
+project-wide, so it can go missing while a perfectly good `SPEC.md` sits next to it.
+Invoke the chosen skill in **reseed/refresh mode** — say so explicitly, and add: *do not
+re-interview from scratch, do not create a ticket dir, and do not touch `SPEC.md`.* If the
+constitution still doesn't exist afterwards, stop and tell the user; do not loop. The next
+pass lands on L2 and creates the spec properly — a *different rung*, so the same-skill
+bound below does not fire.
+
+**L3 is a stop, not a stage.** Nothing in the suite ever *sets* `SPEC.md` to stale — it is
+the root of the chain — so a stale SPEC means someone hand-edited it. Surface it and offer
+`tiny-spec-create` in update mode rather than assuming intent. A go-ahead **in the same
+turn** is enough to invoke it and carry on down the ladder; the stop exists to get a human
+decision, not to force a second command. (Update mode *clears* the flag on its way out, so
+this rung resolves rather than repeating.)
+
+**L4 is the one thing `run` checks that isn't a `status:` flag**, and it is deliberately
+*not* a validator: for each `D<n>` in the active `SPEC.md`, run `shasum -a 256 <export>`
+and compare with the `sha256:` the entry declares. You are checking whether an anchor
+still points at what it says it points at, not inferring whether two documents agree. A
+design that moved under a finished spec is otherwise completely invisible — no status
+flips, and the build reviews against a screen that no longer exists.
 
 - **Mismatch** → `tiny-spec-design` in re-anchor mode.
 - **Missing file** → **stop and tell the user**, naming the entry and the path. Don't
-  route it: a deleted export can mean a rename, a move, or a design that was withdrawn,
-  and each wants a different answer. Never quietly drop the entry.
+  route it: a deleted export can mean a rename, a move, or a withdrawn design, and each
+  wants a different answer. Never quietly drop the entry.
 - No `## Design` section, or every hash matches → the rung doesn't fire; fall through.
 
 **Any `status:` that isn't exactly `current`** — `stale`, missing, unreadable, or an
 unrecognized value like `draft` — counts as **stale**, on `SPEC.md`, `PLAN.md`, and
-`tasks.md` alike. Say so out loud. For `PLAN.md`/`tasks.md` that means reconciling
-(update mode preserves existing ids, so it's the non-destructive way to be wrong); for
-`SPEC.md` it means L3 — stop and ask.
+`tasks.md` alike. Say so out loud. `PLAN.md`/`tasks.md` → reconcile (update mode preserves
+existing ids, the non-destructive way to be wrong); `SPEC.md` → L3, stop and ask.
 
-**A `tasks.md` with no tasks at all is not "built"** — that's why L6 and L7 both require
-at least one task, and why an empty checklist matches neither. It means the
-`tiny-spec-plan` run produced nothing, so L5 catches it. If it comes back empty a second
-time, stop and tell the user — the plan has nothing derivable in it.
+**A `tasks.md` with no tasks at all is not "built"** — L6 and L7 both require at least one
+task, so an empty checklist matches neither and L5 catches it. Empty a second time → stop
+and tell the user; the plan has nothing derivable in it.
 
 `run` trusts the `status:` flags. It does **not** second-guess hand edits, diff
-timestamps, or validate the chain — there is no validator in this suite by design. (L4
-is not an exception: a hash is a value the spec itself declares about a file it names,
-so checking it is reading state, not judging consistency. Do not use it as a precedent
-for adding cross-document checks.) That means it inherits each stage's propagation: if
-`tiny-spec-plan` update mode doesn't flip `tasks.md`, `run` will walk right past it.
-That trust is the price of having no validator; when a run's result looks wrong, suspect
-the stage's propagation before the ladder.
+timestamps, or validate the chain — there is no validator in this suite by design. (L4 is
+not an exception: a hash is a value the spec itself declares about a file it names, so
+checking it is reading state, not judging consistency. Not a precedent for adding
+cross-document checks.) So it inherits each stage's propagation: if `tiny-spec-plan`
+update mode doesn't flip `tasks.md`, `run` walks right past it. That trust is the price of
+having no validator; when a run's result looks wrong, suspect the stage's propagation
+before the ladder.
 
 **`tiny-spec-scope` is not in the ladder.** It is a pre-spec on-ramp that writes
 `BREAKDOWN.md` at the project root, carries no `status:` frontmatter, and is the user's
@@ -253,39 +278,60 @@ to enter `tiny-spec-build` in a stop-before-build run.**
 ## Step 4 — build-through only: build and merge
 
 Reached only when Step 0 fixed the stop point at build-through and the ladder is at L6
-(or L7 with an unmerged branch). 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. **Ladder.** Walk Steps 1–3 for this story until it reaches L6. If it stops anywhere
-   else, that is a halt — report and stop the whole run. **Never walk the ladder 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:
+(or L7 with an unmerged branch). Work **one batch at a time**, in batch order. For every
+story in the current batch that isn't already built and merged:
+
+1. **Lane.** Give each story its own **git worktree**, so lanes cannot collide on the
+   filesystem: `git worktree add ../<repo>-<slug> -b <slug> <integration>`, or
+   `git worktree add ../<repo>-<slug> <slug>` when the branch already exists. Cut **fresh
+   from the integration branch** so the story sees every story merged before it — that is
+   what makes an ordered backlog build correctly, and it is why batches merge before the
+   next one starts.
+
+   With a single lane you may stay in the main checkout and `git switch` as before; a
+   worktree is only required when a batch has more than one story.
+
+2. **Ladder.** Walk Steps 1–3 for each story, in its own worktree, until it reaches L6.
+   A story that stops anywhere else does **not** enter the build — its lane is halted;
+   see the halt rule below. **Never walk the ladder 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 for the whole batch**, briefed to run
+   through, and hand it every live lane as a `(worktree path, slug)` pair. It owns the
+   per-task loop, runs the lanes concurrently, and writes each story's halt record.
+   Do not invoke it a second time for a lane that halted: it resumes from the checkbox
+   state, so it lands on the very task that just halted and halts there again.
+
+4. **Merge — only the lanes that returned `done`, one at a time, in batch order.**
+   For each, in the main checkout:
    - `git switch <integration>`
    - `git merge --no-ff <slug>` — the merge commit keeps each story legible in history.
-   - **Conflict** → `git merge --abort`, then halt `conflict`.
-   - **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`.
+   - **Conflict** → `git merge --abort`, halt that story `conflict`, and carry on with
+     the rest of the batch. Report every conflicted story at the end.
+   - **Run the constitution's Verification commands on the merged result**, exercised the
+     way a user would. Red → halt `blocked`. **This check is load-bearing under
+     parallelism and is never skipped:** every lane gated against a tree that did not
+     contain its siblings, so the merged result is the first time they meet.
    - **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 1. Do not re-run Step 0.
+5. **Next batch.** If **every** lane in this batch merged cleanly, return to Step 1 for
+   the next batch. Do not re-run Step 0. **If any lane halted, stop the run here** — a
+   later batch may well depend on the story that failed, and working out which stories
+   are still safe is exactly the machinery this suite refuses to grow. Report and let the
+   user decide.
+
+6. **Leave the worktrees.** Do **not** run `git worktree remove`. Cleanup is the user's,
+   for the same reason branch deletion is — a halted lane's worktree holds the tree they
+   need to look at. List every path you created in the closing report, with the
+   `git worktree remove` commands, and let them run it.
 
-**A halt stops the whole run**, not just the current story. Later stories in a list
-written top to bottom usually assume the earlier ones landed, so skipping ahead past a
-failure produces a second, more confusing failure downstream.
+**A halt stops the lane it happened in, and ends the run at the end of that batch.**
+Within a batch the other lanes run to completion: the stories were declared independent,
+so stopping the ones that are working buys nothing and throws away finished work. Across
+batches the old rule stands unchanged — later stories usually assume earlier ones landed,
+so never skip ahead past a failure.
 
 `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
@@ -309,11 +355,15 @@ L3 or on a bound, say exactly what stopped you and what the user needs to decide
 **Build-through.** 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.
+   `fork`, `conflict`. Use the word. With more than one lane, report **each story's own
+   state**, and give the run's state as the **worst** of them: four green lanes and one
+   `blocked` is a `blocked` run, never a `done` one with a footnote.
+2. **Stories built and merged**, in batch order, with their merge commits.
+3. **The story or stories it stopped on**, the task within each, and why in one line.
 4. **Stories never started** — say how many are left, by name.
-5. **The one command that resolves it** — `tiny-spec-create`/`tiny-spec-plan` in update
+5. **Worktrees left on disk**, with the `git worktree remove` command for each. You do
+   not run them.
+6. **The one command that resolves it** — `tiny-spec-create`/`tiny-spec-plan` in update
    mode for `blocked`/`exhausted`, this skill again for `paused`, the decision the user
    owes you for a `fork`, or the conflicted paths for a `conflict`.
 
@@ -338,9 +388,11 @@ ticket that legitimately has no visual surface.
 - **Never write, edit, or flip anything.** No `status:`, no checkbox, no `decisions.md`
   entry, no code, no `BREAKDOWN.md` edit. Delegate or stop. A router that regenerates
   documents is a second source of truth.
-- **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 push, force, rebase, reset, delete a branch, or remove a worktree.** The only
+  git commands this skill issues are `switch`, `switch -c`, `merge --no-ff`,
+  `merge --abort`, `worktree add`, `worktree list`, and read-only queries. Everything
+  outward-facing or destructive stays the user's — `worktree remove` included, which is
+  why Step 4 hands those commands over instead of running them.
 - **Never merge a story whose build didn't return `done`.**
 - **Never invoke `tiny-spec-run`.** Re-entering means re-reading these steps, not
   calling yourself. Self-invocation compounds context and does not terminate.

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/tiny-spec-scope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-scope
-description: The greenfield on-ramp — turn a rough idea, or an existing PRD, into BREAKDOWN.md at the project root - a flat list of Features → user Stories, each with draft acceptance criteria and a slug, plus a shared Decisions block. The one skill that works from a blank page. Does not scaffold .spec/ or touch the constitution — tiny-spec-create reads BREAKDOWN.md in seeded mode and does that. For an existing codebase use tiny-spec-adopt instead. The suite works without either.
+description: The greenfield on-ramp — turn a rough idea, or an existing PRD, into BREAKDOWN.md at the project root - a flat list of Features → user Stories, each with draft acceptance criteria, a slug, and an optional needs: naming the stories it must follow, plus a shared Decisions block. The one skill that works from a blank page. Does not scaffold .spec/ or touch the constitution — tiny-spec-create reads BREAKDOWN.md in seeded mode and does that. For an existing codebase use tiny-spec-adopt instead. The suite works without either.
 ---
 
 # tiny-spec-scope
@@ -135,6 +135,7 @@ Write `BREAKDOWN.md` at the **project root** (the user's cwd) with the structure
 - Story: <one user-observable capability>     slug: <ado-__ | kebab>
   - AC: <a single user-observable, testable outcome — becomes REQ-1 in this story's SPEC.md>
   - AC: <another — keep each atomic; no "and" hiding two capabilities>
+  - needs: <slug, slug>   <!-- optional; stories this one must be built after. Omit when independent. -->
   - design: <path(s) to the wireframe(s) covering this story — omit if it has no visual surface>
 - Story: <one user-observable capability>     slug: <ado-__ | kebab>
   - AC: <…>
@@ -171,6 +172,24 @@ story it belongs to, so `tiny-spec-design` knows which files to open for that sp
 instead of re-deriving the mapping from filenames. A wireframe covering several stories
 is listed on each of them.
 
+**`needs:` is what lets stories build in parallel — so keep it honest and keep it rare.**
+It names the stories this one must be built *after*. `tiny-spec-run` uses it to group the
+backlog into batches: stories with no unmet `needs:` build concurrently, each in its own
+git worktree, and the next batch starts once they merge. Three rules:
+
+- **Name a story only for a real code dependency** — this story reads or edits files that
+  one writes, or builds on a schema, API, or type it introduces. A shared theme, a shared
+  `## Feature:` heading, or "it feels like it comes second" is **not** a dependency.
+- **When unsure, omit it.** The two errors are not symmetric. A `needs:` you didn't need
+  costs parallelism on every future run of this backlog, silently and forever. A `needs:`
+  you missed costs one merge conflict, which `tiny-spec-run` already detects and halts on.
+- **Never point across a cycle.** If two stories each need the other, they are one story —
+  merge them, or split the shared part out into a third that both need.
+
+A `## Feature:` heading carries no `needs:` — it is a grouping, not a work item. Most
+backlogs need the field on a minority of stories; a `needs:` on nearly every story means
+the carve is really a sequence, and you should say so rather than encode it here.
+
 **Slugs** mirror `tiny-spec-create`: derive from the platform key when bound — ADO
 `AB#77`→`ado-77`, GitHub `#42`→`gh-42`, Monday item→`monday-<id>`, Jira `PROJ-123`
 verbatim; **ad-hoc** → a short kebab-case slug (`email-login`). The tracker id is

{tiny_spec-1.1.0 → tiny_spec-1.2.0}/tiny_spec/__init__.py

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