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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tiny-spec
-Version: 0.1.0
+Version: 0.2.1
 Summary: A tiny, opinionated take on spec-driven development.
 Project-URL: Homepage, https://github.com/GrayMa77er/tiny-spec
 Project-URL: Source, https://github.com/GrayMa77er/tiny-spec
@@ -54,15 +54,23 @@ builds the work one task at a time. Every task is implemented by one agent and
 graded by an independent reviewer that runs the real tests before anything is
 committed.
 
-It is four skills and two agents. No orchestrator, no config file, no build step.
+It is four skills and two agents — plus an optional Phase-0 on-ramp,
+`tiny-spec-breakdown`, for carving a PRD into stories. No orchestrator, no config
+file, no build step.
 
 ```
-tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
-   intent               design             tasks            per-task loop
-   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
-                        constitution
+tiny-spec-breakdown  ⇢   tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
+   (optional)               intent               design             tasks            per-task loop
+   PRD → stories            SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
+   BREAKDOWN.md                                  constitution
 ```
 
+`tiny-spec-breakdown` is optional: skip it and start at `tiny-spec-create` for a
+single known piece of work; reach for it when a PRD needs carving into many stories.
+It reads a PRD plus wireframes/notes and writes a `BREAKDOWN.md` at your project root
+— a flat list of Features → Stories with draft acceptance criteria — which
+`tiny-spec-create` then reads one story at a time.
+
 ## New to spec-driven development?
 
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -85,10 +93,11 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
-/tiny-spec-plan     # turn the spec into a design and harden the constitution
-/tiny-spec-tasks    # slice the plan into an ordered checklist
-/tiny-spec-build    # build each task: implement, review, commit
+/tiny-spec-breakdown # optional: carve a PRD + wireframes into stories (BREAKDOWN.md)
+/tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan      # turn the spec into a design and harden the constitution
+/tiny-spec-tasks     # slice the plan into an ordered checklist
+/tiny-spec-build     # build each task: implement, review, commit
 ```
 
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
@@ -106,7 +115,7 @@ git clone https://github.com/GrayMa77er/tiny-spec.git
 cd tiny-spec
 
 mkdir -p "$HOME/.claude/skills" "$HOME/.claude/agents"
-for s in tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+for s in tiny-spec-breakdown 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/"
@@ -209,7 +218,6 @@ It is namespaced per ticket, with a shared spine at the root:
 
 ```
 .spec/
-  ACTIVE                    the active ticket directory name (resolution pointer)
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)

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

@@ -17,15 +17,23 @@ builds the work one task at a time. Every task is implemented by one agent and
 graded by an independent reviewer that runs the real tests before anything is
 committed.
 
-It is four skills and two agents. No orchestrator, no config file, no build step.
+It is four skills and two agents — plus an optional Phase-0 on-ramp,
+`tiny-spec-breakdown`, for carving a PRD into stories. No orchestrator, no config
+file, no build step.
 
 ```
-tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
-   intent               design             tasks            per-task loop
-   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
-                        constitution
+tiny-spec-breakdown  ⇢   tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
+   (optional)               intent               design             tasks            per-task loop
+   PRD → stories            SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
+   BREAKDOWN.md                                  constitution
 ```
 
+`tiny-spec-breakdown` is optional: skip it and start at `tiny-spec-create` for a
+single known piece of work; reach for it when a PRD needs carving into many stories.
+It reads a PRD plus wireframes/notes and writes a `BREAKDOWN.md` at your project root
+— a flat list of Features → Stories with draft acceptance criteria — which
+`tiny-spec-create` then reads one story at a time.
+
 ## New to spec-driven development?
 
 Spec-driven development (SDD) means writing down *what* you want and *why* before
@@ -48,10 +56,11 @@ uvx tiny-spec install
 Restart Claude Code so it picks up the new skills, then run the flow in your project:
 
 ```
-/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
-/tiny-spec-plan     # turn the spec into a design and harden the constitution
-/tiny-spec-tasks    # slice the plan into an ordered checklist
-/tiny-spec-build    # build each task: implement, review, commit
+/tiny-spec-breakdown # optional: carve a PRD + wireframes into stories (BREAKDOWN.md)
+/tiny-spec-create    # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan      # turn the spec into a design and harden the constitution
+/tiny-spec-tasks     # slice the plan into an ordered checklist
+/tiny-spec-build     # build each task: implement, review, commit
 ```
 
 Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
@@ -69,7 +78,7 @@ git clone https://github.com/GrayMa77er/tiny-spec.git
 cd tiny-spec
 
 mkdir -p "$HOME/.claude/skills" "$HOME/.claude/agents"
-for s in tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+for s in tiny-spec-breakdown 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/"
@@ -172,7 +181,6 @@ It is namespaced per ticket, with a shared spine at the root:
 
 ```
 .spec/
-  ACTIVE                    the active ticket directory name (resolution pointer)
   constitution.md           project-wide, shared across tickets
   memory.md                 operational lessons, shared across tickets
   <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)

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

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

tiny_spec-0.2.1/tiny-spec-breakdown/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: tiny-spec-breakdown
+description: Optional Phase-0 on-ramp — read a PRD plus wireframes/notes, interview briefly, and decompose the work into a flat list of Features → user Stories (each with draft acceptance criteria and a slug) plus a shared Decisions block, written to BREAKDOWN.md at the project root. Does not scaffold .spec/ or touch the constitution — tiny-spec-create reads BREAKDOWN.md in seeded mode and does that. The suite works without it.
+---
+
+# tiny-spec-breakdown
+
+Turns a body of source material — a PRD, wireframes, loose notes — into the set of
+**user stories** to spec, *before* any one of them is picked up. It is the moment
+**before** `tiny-spec-create`: that skill takes **one story → one spec**; this one
+decides what the stories *are*.
+
+This is an **optional** front door. The suite works fine without it — start at
+`tiny-spec-create` for a single known piece of work. Reach for `breakdown` only when
+you have a multi-story PRD to carve.
+
+**It writes exactly one file: `BREAKDOWN.md` at the project root.** It does **not**
+scaffold `.spec/`, does **not** create or edit `constitution.md`, and does **not**
+run `tiny-spec-create` or loop over stories. It produces the worksheet and stops —
+you create the work items in your tracker from it, then run the normal flow per
+story. Keeping the carve out of `.spec/` is deliberate: `.spec/` is per-spec build
+state; the breakdown is pre-spec planning the tracker owns.
+
+## Inputs
+
+Take one or more file paths from the user (a PRD is the usual anchor; wireframes,
+design notes, an API sketch are common companions). **Read them all.** If two
+sources disagree, ask which wins and note it — don't silently pick.
+
+## Interview — short, five groups
+
+Keep it lean (earned ceremony). Ask only what you can't infer from the inputs; skip
+a group the material already answers.
+
+1. **Inputs & boundary.** Which files are in scope, and what's the boundary of *this*
+   breakdown — the whole product, one epic, or an MVP slice? *(Hint: anchors against
+   boiling the ocean; you can re-run later for the next slice.)*
+2. **Platform & hierarchy.** Where will these live — `ado | jira | github | monday`,
+   or **ad-hoc** (no tracker)? Which levels does the team actually use? *(Hint: ADO
+   default is Epic › Feature › Story › Task, but many teams skip Feature — don't
+   invent levels they won't track. Ad-hoc → kebab slugs, no parent ids, no `Refs:`
+   footer downstream.)*
+3. **Structure & granularity.** How should features be grouped — by user journey, by
+   screen/surface, by domain/module, or by persona? And how big is a story? *(Hint:
+   wireframes push toward screen-based, a PRD usually reads journey-based — pick one
+   lens. A story = one buildable spec = one tight plan→build loop; if it can't be
+   built and verified in one pass, split it as a vertical slice, not a layer.)*
+4. **Tech & cross-cutting** (→ the Decisions block). Stack / framework, where code
+   lives, and any cross-cutting non-functionals (auth, i18n, a11y, perf)? *(Hint:
+   stack + code-location seed the constitution later; cross-cutting concerns become
+   constitution invariants or shared requirements — **not** their own feature.)*
+5. **Confirm the carve.** Play back the proposed Features and the stories under each
+   before writing. Adjust on feedback.
+
+## Write `BREAKDOWN.md`
+
+Copy this skill's `templates/BREAKDOWN.template.md` to `BREAKDOWN.md` at the
+**project root** (the user's cwd) and fill it in:
+
+- the **`## Decisions`** block — stack, code location, platform, structure lens,
+  scope, cross-cutting concerns;
+- one **`## Feature:`** heading per feature (a grouping only — it never becomes a
+  folder), with the tracker-parent id left blank for the user to fill after creating
+  it;
+- under each feature, the **stories** — each a single user-observable capability,
+  with a proposed **slug** and its **draft acceptance criteria** (`AC:` lines).
+
+**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 unknown until the user creates the item, so leave the parent-id
+placeholder and use a provisional slug where needed.
+
+**Acceptance criteria are draft `REQ-N`.** Write each as one **user-observable,
+testable** outcome with no implementation detail — and keep it **atomic**: if a line
+hides two capabilities behind an "and", split it. `tiny-spec-create` promotes these
+into `REQ-N`, so atomic ACs here save a re-split later.
+
+## When done
+
+Print the carve — the features and the stories under each — and a **suggested first
+spec** (which story to pick up first). Then **stop**. Tell the user the next steps,
+which you do **not** perform:
+
+1. Create the Features and Stories in their tracker from `BREAKDOWN.md`, capturing
+   the ids.
+2. Run `tiny-spec-create` per story — with `BREAKDOWN.md` present it reads each
+   story's entry instead of re-interviewing (seeded mode), and on first run seeds the
+   constitution from the Decisions block.
+
+Do **not** scaffold `.spec/`, write a constitution, or invoke `tiny-spec-create`
+yourself — `breakdown` ends here.

tiny_spec-0.2.1/tiny-spec-breakdown/templates/BREAKDOWN.template.md

@@ -0,0 +1,37 @@
+# Breakdown — <product / epic name>
+
+<!-- A pre-spec worksheet. It lives at the PROJECT ROOT (not under .spec/) and is
+     NOT a tracked .spec/ artifact. tiny-spec-create reads it in seeded mode: each
+     Story below becomes one .spec/<slug>/SPEC.md (its AC lines → REQ-N), and on a
+     story's first create the Decisions block seeds the shared constitution.md.
+     Regenerable — edit freely; the tracker (ADO/Jira/…) stays the source of truth. -->
+
+## Decisions
+
+<!-- Project-wide framing. tiny-spec-create folds these into constitution.md on a
+     story's first run: Stack + Code-lives → Style and Layout; verification hints →
+     Verification commands; Cross-cutting → Guiding invariants. Keep each to a line. -->
+
+- Stack: <language / framework / runtime>
+- Code lives: <where the code is — repo path, dirs of note>
+- Platform: <ado | jira | github | monday | ad-hoc>   <!-- ad-hoc → kebab slugs, no parent ids, no Refs footer -->
+- Structure lens: <by journey | by screen | by domain | by persona — how features are grouped below>
+- Scope: <whole product | epic | MVP slice — the boundary of this breakdown>
+- Cross-cutting: <non-functionals spanning stories — auth, i18n, a11y, perf. These become constitution invariants or shared REQ, NOT their own feature.>
+
+## Feature: <feature name>           (tracker parent: <fill after creating, e.g. AB#120>)
+
+- 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>
+- Story: <one user-observable capability>     slug: <ado-__ | kebab>
+  - AC: <…>
+
+## Feature: <feature name>           (tracker parent: <…>)
+
+- Story: <one user-observable capability>     slug: <ado-__ | kebab>
+  - AC: <…>
+
+## Suggested first spec
+
+<story title> (slug: <…>) — run tiny-spec-create on this first.

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/tiny-spec-build/SKILL.md

@@ -19,8 +19,9 @@ alongside this skill (see the suite README).
 
 ## Inputs
 
-1. **Resolve the active ticket dir** from `.spec/ACTIVE` (if absent and exactly one
-   ticket dir exists, use it; if several exist, ask which). Call it `<active>`.
+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>`.
 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`

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/tiny-spec-create/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tiny-spec-create
-description: Start or update a spec — capture intent and requirements into .spec/<slug>/SPEC.md, optionally bound to a ticket (or ad-hoc). On first run, scaffolds .spec/ and seeds the shared constitution (constitution.md) from a short interview. Re-run to update an existing spec in place.
+description: Start or update a spec — capture intent and requirements into .spec/<slug>/SPEC.md, optionally bound to a ticket (or ad-hoc). On first run, scaffolds .spec/ and seeds the shared constitution (constitution.md) from a short interview. If a BREAKDOWN.md (from tiny-spec-breakdown) is present, seeds the spec from a chosen story instead of a full interview. Re-run to update an existing spec in place.
 ---
 
 # tiny-spec-create
@@ -16,6 +16,31 @@ directory. Two are **project-wide** and shared at the `.spec/` root
 `tasks.md`, `decisions.md`) live under `.spec/<slug>/`. Templates ship in this
 skill's own `templates/` folder (alongside this file); read them from there.
 
+## Seeded mode (`BREAKDOWN.md` present)
+
+Before interviewing, check for **`BREAKDOWN.md`** at the project root (written by the
+optional `tiny-spec-breakdown` skill). If it exists and the user is creating one of
+its stories, **seed from it instead of running the full interview** — confirm, don't
+re-ask:
+
+1. **Pick the story.** Ask which story (or infer from the user's request); match it
+   to its `## Feature:` → `Story:` entry by slug or title.
+2. **Slug + binding.** Use the story's **slug** for `.spec/<slug>/`. Take the ticket
+   provider from the Decisions **Platform** and the **id** from the story's tracker
+   parent or the user (ask for the id if the placeholder is still blank; omit the
+   `ticket:` block entirely if the platform is ad-hoc).
+3. **Requirements.** Promote the story's **`AC:` lines into `REQ-N`** — verbatim where
+   already atomic; split any that hide two capabilities behind an "and".
+4. **Constitution (first run only).** Seed `constitution.md` from the **`## Decisions`**
+   block instead of interviewing stack/layout: Stack + Code-lives → **Style** and
+   **Layout**; any verification hints → **Verification commands**; cross-cutting
+   concerns → **Guiding invariants**. If `constitution.md` already exists, reuse it.
+5. Confirm the captured `REQ-N` with the user, then write `SPEC.md` as below.
+
+Only the **project-wide** questions collapse — still confirm this story's binding and
+requirements. If there is **no `BREAKDOWN.md`**, or no entry matches, run the **full
+interview** below unchanged.
+
 ## Pick the slug (resolve the active dir)
 
 Each spec lives in its own directory `.spec/<slug>/`. At the start of the interview,
@@ -31,14 +56,20 @@ establish the slug. There are two paths — both are first-class:
   footer (everything else — namespacing, the constitution, the build loop — is
   identical). You can bind a ticket later by adding the block to `SPEC.md`.
 
-Create `.spec/<slug>/` and write the slug as the single line of `.spec/ACTIVE` (the
-pointer every downstream skill reads to find the active spec).
+Create `.spec/<slug>/`.
+
+**One branch per ticket — how the active ticket is resolved.** Work for a ticket
+lives on a branch named after the slug (e.g. `PROJ-123` or
+`feature/PROJ-123-dark-mode`); downstream skills resolve the active ticket from the
+branch name, so several tickets can be in flight on separate branches at once. If the
+user isn't already on such a branch, create one (e.g. `git switch -c <slug>`) so the
+new spec resolves by branch match.
 
 ## First run — scaffold
 
 If `.spec/` does not exist:
 
-1. Create `.spec/` and the active ticket dir `.spec/<slug>/`, and write `.spec/ACTIVE`.
+1. Create `.spec/` and the active ticket dir `.spec/<slug>/` (on the ticket branch — see above).
 2. **Short interview** (keep it short — earned ceremony):
    - the ticket binding (above);
    - the intent in one paragraph;
@@ -71,7 +102,8 @@ that hides two capabilities, split it.
 ## Update mode (re-run on an existing spec)
 
 When the active ticket's `SPEC.md` already exists and the user wants a change to
-requirements (resolve the active dir from `.spec/ACTIVE`):
+requirements (resolve the active dir by branch match — see the resolution order
+downstream skills use):
 
 1. Edit `.spec/<active>/SPEC.md` in place — add/alter/remove `REQ-N`, preserving
    existing ids where the requirement still exists.
@@ -92,9 +124,9 @@ Tell the user which downstream docs went stale and to re-run `tiny-spec-plan` to
 reconcile.
 
 > **New spec?** To start a different piece of work (a new ticket or an ad-hoc
-> change), re-run this skill — it creates a new `.spec/<slug>/` and repoints
-> `.spec/ACTIVE`. The shared `constitution.md` and `memory.md` carry over; the
-> previous spec's artifacts stay untouched on disk.
+> change), re-run this skill on a new branch — it creates a new `.spec/<slug>/` that
+> resolves by branch match. The shared `constitution.md` and `memory.md` carry over;
+> the previous spec's artifacts stay untouched on disk.
 
 ## When done
 

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/tiny-spec-plan/SKILL.md

@@ -11,8 +11,9 @@ reviewed against.
 
 Artifacts live under `.spec/`: the **shared** constitution at the root
 (`.spec/constitution.md`), the per-ticket `SPEC.md`/`PLAN.md` under
-`.spec/<ticket-id>/`. **Resolve the active ticket dir** from `.spec/ACTIVE` (if it's
-absent and exactly one ticket dir exists, use it; if several exist, ask which). The
+`.spec/<ticket-id>/`. **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. The
 template ships in this skill's own `templates/` folder (alongside this file).
 Requires `.spec/<active>/SPEC.md`.
 

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/tiny-spec-tasks/SKILL.md

@@ -10,8 +10,9 @@ tasks. No waves, no parallelism, no `owns:` contracts — tasks run one at a tim
 top to bottom.
 
 Artifacts live under `.spec/`; `PLAN.md` and `tasks.md` are per-ticket. **Resolve
-the active ticket dir** from `.spec/ACTIVE` (if absent and exactly one ticket dir
-exists, use it; if several exist, ask which). The template ships in this skill's own
+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. The template ships in this skill's own
 `templates/` folder (alongside this file). Requires `.spec/<active>/PLAN.md`.
 
 ## Slice the plan into tasks

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/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__ = "0.1.0"
+__version__ = "0.2.1"

{tiny_spec-0.1.0 → tiny_spec-0.2.1}/tiny_spec/manifest.json

@@ -1,5 +1,6 @@
 {
   "skills": [
+    "tiny-spec-breakdown",
     "tiny-spec-create",
     "tiny-spec-plan",
     "tiny-spec-tasks",