@pknx/waterfall-cli 0.1.0

package/prompts/commands/cr-to-rq.md

@@ -0,0 +1,62 @@
+# Process: CR → RQ
+
+## Purpose
+
+Promote **raw intent** in a **`CR-*`** into a structured **requirement theme** **`RQ-*`** so use cases can hang under a coherent scope.
+
+## Scope of edits (strict)
+
+**Only** touch artifacts of these types in this action (plus **`number.json`** counter updates this workflow requires):
+
+| In scope | Typical paths |
+|----------|----------------|
+| **`CR-*`** | `changerequests/CR-<NNN>-<slug>/CR-<NNN>.md` — append the new RQ id under `### Downstream references`. |
+| **`RQ-*`** | `requirements/RQ-*-…/RQ-<NNN>.md` (create or update). |
+
+**Out of scope (do not edit here):** **`UC-*`**, **`SYS-*`**, **`STORY-*`**, **`BUG-*`**, **`TST-*`**, and **`RQ`** content that belongs under **use cases** (flows, testcase tables). Use **RQ → UC** and later prompts instead.
+
+If you discover missing **UC** / **STORY** / **test** work, **stop** after **`CR → RQ`** and run the matching prompt in a **separate** change.
+
+## Preconditions
+
+- **`changerequests/CR-<NNN>-<slug>/CR-<NNN>.md`** exists.
+- Scope is clear enough to name at least one RQ theme; when the CR bundles **several separable themes**, plan **multiple RQs** in this pass (or explicit deferrals on the CR), not one kitchen-sink RQ.
+
+## Granular RQ breakdown (required mindset)
+
+- **One RQ = one coherent requirement theme** at the “what area / what constraints” level. If the CR mixes **catalog**, **cart/checkout**, **account**, **admin**, etc., create **multiple** **`RQ-*`** folders — do **not** fold the whole CR into a single mega-RQ whose scope is every path in the diff.
+- **Split by customer- or policy-visible boundaries** when themes have different non-goals, actors, or quality bars; keep each **`RQ-<NNN>.md`** readable on its own.
+- **Phrase scope** so **RQ → UC** can later produce **several granular UCs** per theme — see **[`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)** (sections **Granularity: multiple RQ themes from one CR** and **Granularity: breaking an RQ into multiple UCs**).
+
+## Rules
+
+1. **Every new `RQ-*` must be added to the source CR markdown** under `### Downstream references` (one-way linking).
+2. **`RQ-*`** gets **`RQ-<NNN>.md`** (summary + links) inside **`requirements/RQ-<NNN>-<slug>/`**.
+3. Do **not** skip **`CR`** for net-new product intent — record or extend a **`CR-*`** first unless **`CURSOR.md`** allows a different entry (e.g. **BUG**).
+
+## Content (RQ `RQ-<NNN>.md`)
+
+Follow **[`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)** — the RQ theme file carries **general** purpose, **scope**, **constraints**, **in/out of scope**, and links. Avoid step-by-step user flows here (those belong in **UCs**). Where the theme covers multiple separable capabilities, phrase **scope** so **RQ → UC** can produce **several granular UCs** (not one kitchen-sink UC) — see the same doc, *Granularity: breaking an RQ into multiple UCs*. If the **CR** already mixes unrelated themes, **split RQs first** (see **Granularity: multiple RQ themes from one CR** in the same doc).
+
+When editing the source **CR**, follow **[`cr-document-structure.md`](../items/cr-document-structure.md)**. When authoring **`RQ-<NNN>.md`**, follow **[`rq-theme-document-structure.md`](../items/rq-theme-document-structure.md)**.
+
+## Steps
+
+1. Allocate **`next.RQ`** from **`number.json`** → e.g. **`RQ-002`**.
+2. Create **`requirements/RQ-002-<slug>/`** with **`RQ-002.md`** (per content rules above).
+3. In the source **`CR-<NNN>.md`**, append the produced RQ under `### Downstream references`.
+4. Increment **`next.RQ`** in **`number.json`** in the **same** commit.
+5. If **`CR`** proposed multiple themes, create **multiple RQs** or explicitly defer follow-on RQs in **`CR`** revision notes.
+
+## Done when
+
+- `CR -> RQ` traceability is visible in markdown via `### Downstream references` in the source CR.
+
+## CLI orchestration
+
+When this prompt is executed as part of a batch command (for example `waterfall cr all`), the CLI will run multiple prompts in separate agent invocations.
+
+1. Treat the operator-provided `hint` as global steering for the batch, but do not widen this step beyond its **Scope of edits (strict)**.
+2. If this step has **nothing to do** for the current artifact(s), make no changes and let the CLI proceed.
+3. Commit boundary: stop after this step's artifacts are internally consistent (`CR`/`RQ`/`number.json` for this step). The next lifecycle step prompt will be invoked separately.
+

package/prompts/commands/horizontal-create.md

@@ -0,0 +1,27 @@
+# Process: refine horizontal scaffold (`waterfall horizontal create` — phase 2)
+
+## Purpose
+
+After the CLI **mechanically** creates **`technical/horizontals/HOR-<NNN>-<slug>/HOR-<NNN>.md`** (identity block, italic **Purpose** placeholder, empty **`## Aggregated definitions`**, **`## Draft steering (CLI)`**), this prompt runs with **`--execute-agent`** (or dry-run) so **Purpose** becomes **meaningful synthesized prose** aligned with **[`horizontal-structure.md`](../global/horizontal-structure.md)** — not a verbatim copy of steering.
+
+## When this prompt runs (agent refinement)
+
+The scaffold file **already exists** and is **committed**. **Git diff vs `develop`** shows recent paths.
+
+**Your task:** edit **only** that **`HOR-<NNN>.md`**:
+
+- Replace the **Purpose** placeholder with a short, product-readable paragraph on what this horizontal reconciles (schemas, APIs, stack, …) — **synthesize** from **Draft steering** and the operator hint (`[horizontal create · anchor=… · name=…]` prefix in the wire payload). **Do not** name **CR-***, **SYS-***, **STORY-***, **RQ-***, **UC-***, **HOR-*** (other), or **TST-*** in **Purpose** — describe the concern in plain language; **typed ids** belong in **`## Aggregated definitions`** only when traceability is needed (sparingly, per **[`before-changing-spec.md`](../global/before-changing-spec.md)**), not in the Purpose paragraph.
+- **Remove** **`## Draft steering (CLI)`** when **Purpose** is satisfactory.
+- **`## Aggregated definitions`:** usually stays **empty** until **`waterfall horizontal update`** fills it from **STORY** substance; you may add a **one-line** intent bullet only if it helps the next update pass — **no** path dumps.
+
+**Out of scope for this pass:** **`number.json`**, other files, lifecycle edges (**UC → STORY**, etc.).
+
+## Mechanical phase (CLI only — before this prompt)
+
+The CLI creates the folder, file, bumps **`next.HOR`**, commits. See **[`horizontal-structure.md`](../global/horizontal-structure.md)** for folder shape.
+
+## Rules (content)
+
+1. **Purpose** must be **synthesized**, not a 1:1 paste of **Draft steering**.
+2. **Purpose** must stay **id-free** (no **CR-001**, **SYS-002**, **STORY-014**, …). **`## Aggregated definitions`** may use **typed ids** sparingly for traceability when you add substance later — see **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+3. Full **Aggregated definitions** content is the job of **`horizontal update`** + **`horizontal-update.md`**, not this pass.

package/prompts/commands/horizontal-update.md

@@ -0,0 +1,39 @@
+# Process: refresh a horizontal after **`waterfall horizontal update`**
+
+## Purpose
+
+**`waterfall horizontal update HOR-<NNN>`** computes **`git diff develop...HEAD --name-only`**, filters paths for this horizontal’s **anchor** (e.g. **story**), and injects the result into the **operator hint** for this run — **not** into **`HOR-<NNN>.md`**. The spec file stays a **model document**; raw path lists live only in chat / CI logs (and may overlap with the CLI’s **CR branch — changed paths** block).
+
+Your job is to **turn that hint into real content** in **`## Aggregated definitions`**: definitions, tables, and rules — **never** a dump of repository paths.
+
+## Scope of edits (strict)
+
+| In scope | Action |
+|----------|--------|
+| **`HOR-<NNN>.md`** | Rewrite or extend **## Aggregated definitions** with **substantive** consolidated model/contract text. |
+
+**Out of scope:** creating new **STORY**/**UC**/**RQ** files, changing **CR** scope, editing **`CURSOR.md`** / **`schemas/`** unless this CR explicitly owns that.
+
+## Reference rule (critical)
+
+- In **`## Aggregated definitions`**, **never** cite other artifacts by **file path**.
+- Use **typed ids** only (**`STORY-004`**, **`UC-002`**) when traceability is unavoidable — **not more than one** id reference per logical subsection; prefer **none** if the text stands alone.
+
+See **[`horizontal-structure.md`](../global/horizontal-structure.md)** and **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+
+## Steps
+
+1. Read **`prompts/global/horizontal-structure.md`** for the horizontal **kind** (e.g. `database-model`, `api-model`, `technical-stack`).
+2. Use the **operator hint** (matching paths + full diff list) to choose which **stories** (or other anchors) to open; extract **facts** (fields, endpoints, constraints).
+3. Update **## Aggregated definitions** with deduplicated **content**; resolve conflicts explicitly in prose.
+4. If this artifact is a **`database-model`** horizontal (**`Horizontal name:`** / slug **`database-model`** in the file): satisfy **Database model — required shape** in **`horizontal-structure.md`** — **Mermaid `erDiagram`** covering **all** tables and relationships, plus **one markdown table per table** listing **every field** and **datatype** (and optional Null/Default/Notes).
+5. If this artifact is a **`technical-stack`** horizontal (**`Horizontal name:`** / slug **`technical-stack`**): satisfy **Technical stack — required shape** in **`horizontal-structure.md`** — grouped **`###`** sections with **markdown tables** listing **all** in-use technologies (component, role; version and notes when known).
+6. Optionally add **one** compact traceability line per subsection (**`STORY-<NNN>`** only) if required — never path dumps.
+7. Save and commit your **content** edits if the horizontal document changed.
+
+## Done when
+
+- **## Aggregated definitions** reads like a **real** consolidated spec for that concern, not an index of paths.
+- For **`database-model`**: ER diagram + per-table field/type tables are **complete** for every table in scope.
+- For **`technical-stack`**: every technology committed by in-scope stories appears in the grouped inventory tables **once**, with no silent contradictions across stories.
+- No stale **aggregated** text that contradicts the current stories on the branch.

package/prompts/commands/rq-to-uc.md

@@ -0,0 +1,62 @@
+# Process: RQ → UC
+
+## Purpose
+
+Break an **`RQ-*`** into **use cases** **`UC-*`** with **actionable** behavior and **acceptance tests** in **one** markdown file (**`UC-<NNN>.md`**).
+
+## Scope of edits (strict)
+
+**Only** touch artifacts of these types in this action (plus **`number.json`** counter updates this workflow requires):
+
+| In scope | Typical paths |
+|----------|----------------|
+| **`RQ-*`** | `requirements/RQ-*-…/RQ-<NNN>.md` — append new UC id under `### Downstream references`; keep **`RQ`** general. |
+| **`UC-*`** | New or updated `requirements/RQ-*-…/UC-<NNN>-<slug>/UC-<NNN>.md` (behaviour + **`## TC-…`** sections). |
+
+**Out of scope (do not edit here):** **`CR-*`** (except read-only context), **`SYS-*`**, **`STORY-*`**, **`BUG-*`**, **`TST-*`**. Do **not** promote **`CR`** into **`STORY`** or **tests** in this pass.
+
+If scope needs a **new** **`CR`** or **another** **`RQ`**, finish this **`RQ → UC`** slice first, then run **CR → RQ** / another edge prompt **separately**.
+
+## Preconditions
+
+- **`RQ-*`** folder exists with **`RQ-<NNN>.md`**.
+- You can name actors, goal, and boundaries for at least one UC.
+- You have read **[`before-changing-spec.md`](../global/before-changing-spec.md)** and reviewed **`git diff`** for the RQ/UC paths you will touch.
+
+## Granular UC breakdown (required mindset)
+
+- **One UC = one coherent capability slice** a tester could exercise end-to-end (or a clear system behaviour with bounded pre/postconditions). If the RQ theme covers multiple such slices, create **multiple** **`UC-*`** folders — do **not** fold the whole theme into a single mega-UC.
+- **Split by feature boundaries:** e.g. browse/search, cart mutation, checkout submission, order history — each gets its own UC when they are independently describable and testable.
+- **Each new UC** gets its own **`## TC-<NNN>-<seq>`** set sized for that slice — avoid one UC carrying dozens of unrelated testcases.
+- Link all produced UCs from **`RQ-<NNN>.md`** `### Downstream references`; cross-link UCs with **ids only** (`UC-003`), never file paths — **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+
+See **[`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)** → **Granularity: breaking an RQ into multiple UCs** (and, when the **RQ** still bundles unrelated themes, **Granularity: multiple RQ themes from one CR** upstream on the **CR**).
+
+## Rules
+
+1. **Separation of concerns:** **`RQ`** stays **general** (theme, scope, constraints); each **`UC`** is **specific** and **testable** — see **[`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)**.
+2. **RQ theme shape:** preserve the theme required header + section structure described in **[`rq-theme-document-structure.md`](../items/rq-theme-document-structure.md)** when updating **`RQ-<NNN>.md`**.
+3. **UC document model:** follow **[`uc-document-structure.md`](../items/uc-document-structure.md)** — **no separate “description” file**; all narrative sections live in **`UC-<NNN>.md`**.
+4. In **`UC-<NNN>.md`**, add **`## TC-<NNN>-<seq> — …`** acceptance sections — **`TC-*`** must be sufficient to judge **UC completion**.
+5. Keep one-way linking lightweight: append the new UC in the source **`RQ-<NNN>.md`** under `### Downstream references`.
+6. Use **`number.json` `next.UC`**, create artifacts, increment in the **same** commit.
+
+## Steps
+
+1. Allocate **`next.UC`** → **`UC-<NNN>`** with kebab **`UC-<NNN>-<slug>/`** under the owning **`RQ`**.
+2. Write **`UC-<NNN>.md`** with **actionable** main flow, pre/postconditions, exceptions, any **context** sections, **and** stable **`## TC-<NNN>-<seq> — …`** acceptance blocks that **prove** the UC’s goal and critical paths.
+3. Create **`UC-<NNN>.md`** and update **`RQ-<NNN>.md`** by appending this UC under `### Downstream references`.
+4. Increment **`next.UC`**.
+
+## Done when
+
+- **`UC`** folder is linked from **`RQ`** and ready for **`SYS` / `STORY` / `TST`** work.
+
+## CLI orchestration
+
+When this prompt is executed as part of a batch command (for example `waterfall cr all`, `waterfall rq all`, or `waterfall uc all`), the CLI will run multiple prompts in separate agent invocations.
+
+1. Treat the operator-provided `hint` as global steering for the batch, but do not widen this step beyond its **Scope of edits (strict)**.
+2. If this step has **nothing to do** for the current artifact(s), make no changes and let the CLI proceed.
+3. Commit boundary: stop after this step's artifacts are internally consistent (`RQ`/`UC`/`number.json` for this step). The next lifecycle step prompt will be invoked separately.
+

package/prompts/commands/story-close-all.md

@@ -0,0 +1,34 @@
+# Orchestration: close all eligible STORIES (`waterfall story close all`)
+
+## Purpose
+
+Run **[`story-close.md`](story-close.md)** once per **eligible** **STORY**, in a batch, without closing stories that are not ready.
+
+## Scope of edits (strict)
+
+This file does **not** widen **`story-close.md`** scope. Each closure is one application of **`story-close.md`** (prefer one commit per STORY for auditability).
+
+## Preconditions
+
+- Human-approved **ordered list** of **STORY-<NNN>** ids to close.
+- Branch **`feature/…`** from **`develop`**; **[`before-changing-spec.md`](../global/before-changing-spec.md)** reviewed.
+
+## Eligibility (all must hold for each id)
+
+1. Implementation for that STORY is merged to **`waterfall-app`** **`develop`** (or agreed integration branch).
+2. Verification (tests per STORY/TST policy) is green.
+3. Folder is still **`STORY-*`**, not already **`_STORY-*`**.
+4. No remaining open work tracked under the same STORY id (otherwise split to a new STORY first).
+
+If any item is unclear, stop and run **`story close STORY-<NNN>`** only after confirmation.
+
+## Invocation order
+
+1. For each approved id in order, execute **[`story-close.md`](story-close.md)** for that STORY only.
+2. Commit after each STORY (recommended) or one reviewed batch per team policy.
+3. Do not use this pass to change UC **`TC-*`** or RQ prose beyond link fixes allowed inside **`story-close.md`**.
+
+## Done when
+
+- Every approved STORY on the list is **`_STORY-*`** with a consistent graph; no ineligible STORY was closed.
+

package/prompts/commands/story-close.md

@@ -0,0 +1,44 @@
+# Process: close one STORY (`waterfall story close STORY-NNN`)
+
+## Purpose
+
+Close a **delivered** **STORY** per **[`CURSOR.md`](CURSOR.md)** (Closed STORY): rename folder to **`_STORY-NNN-slug/`**, set **Status: closed** in **`STORY-NNN.md`**, and fix markdown links/references. **Convention:** **NNN** is the **three-digit zero-padded** story number (e.g. `014`); **slug** matches the existing folder slug. Usually **implementation** is merged on **`waterfall-app`** **`develop`** first; then spec closure (see companion app `prompts/spec-lock-and-merge.md` §0.5).
+
+## Scope of edits (strict)
+
+Only what this **one** story needs for closure and path consistency:
+
+| Area | Action |
+|------|--------|
+| Story folder | Rename `technical/SYS-…/module/STORY-NNN-slug/` → `_STORY-NNN-slug/` (underscore on **folder** only). |
+| Story markdown | **`STORY-NNN.md`:** **Status:** `closed`, **Closed:** date + note. |
+| Story markdown | Ensure `## Links and dependencies` / `### Downstream references` stay valid after rename. |
+| Peers | Fix markdown links/references that still point at the old **`STORY-…`** path (module, UC, TST, other STORY links). |
+
+**Out of scope:** CR, RQ, UC behaviour or **`TC-*`** sections (except link-only path fixes), new STORY ids, **`next.STORY`** bumps for new work. **Never** add new scope inside **`_STORY-*`** after close — use a new **STORY** per **`CURSOR.md`**.
+
+## Preconditions
+
+- Implementation merged per team rules.
+- Work on **`feature/…`**, not direct **`develop`** commits for spec tree edits.
+- **[`before-changing-spec.md`](../global/before-changing-spec.md)** — diff vs **`develop`**.
+
+## Rules
+
+1. Inner filename stays **`STORY-NNN.md`** (not `_STORY-NNN.md`).
+2. Preserve numeric id.
+3. Search for stale path references after rename.
+
+## Steps
+
+1. Locate **`technical/SYS-*-…/<module>/STORY-NNN-slug/`**.
+2. Rename to **`_STORY-NNN-slug/`**.
+3. Update **`STORY-NNN.md`** (status, **Closed:**).
+4. Fix links/references in the story markdown.
+5. Fix all markdown links/references in peers.
+6. Commit on **`feature/…`**; merge per **`CURSOR.md`**.
+
+## Done when
+
+- Folder is **`_STORY-…`**, story is closed, graph and links are consistent.
+

package/prompts/commands/sync-bugs-refine-imports.md

@@ -0,0 +1,33 @@
+# Process: refine BUG(s) imported from remote sync (`waterfall sync bugs`)
+
+## Purpose
+
+After **remote-leading** sync materializes new `BUG-NNN.md` files, the CLI invokes this prompt (dry-run logs the plan; **`--execute-agent`** runs your backend) so imported scaffolds get the same treatment as **`waterfall bug start`**: real **Summary** prose per **[`bug-document-structure.md`](../items/bug-document-structure.md)**, not placeholders.
+
+## When this prompt runs
+
+The CLI has **already**:
+
+- Created `technical/SYS-…/BUG-NNN-…/BUG-NNN.md` with **Id / SYS / Status** and a **Summary** section containing **Draft steering (remote import)** (remote title + quoted tracker comments).
+- Applied remote comments to **`BUG-NNN.comments.json`** where applicable.
+- Listed spec-relative paths in the operator hint.
+
+## Your task
+
+For **each** path in the hint:
+
+1. Open that `BUG-NNN.md`.
+2. **Synthesize** a proper **Summary** from **Draft steering (remote import)** — same quality bar as **[`bug-start.md`](bug-start.md)** (repro, expected vs actual, links to related items by **typed id** only).
+3. **Remove** the entire **Draft steering (remote import)** section when done.
+4. Keep **Id**, **SYS**, **Status** unchanged unless you find a clear error (e.g. wrong subsystem — rare if sync inferred SYS correctly).
+
+**Out of scope:** `number.json`, inventing tracker comments, moving folders unless the steering clearly implies the wrong SYS and you can fix it safely.
+
+## Rules
+
+- **SYS** on the file should match the folder under `technical/SYS-…/`; do not retarget bugs casually.
+- Typed references only (**STORY-***, **UC-***, …); no file paths in finished prose — **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+
+## Done when
+
+Every listed `BUG-NNN.md` reads like a real defect note and **Draft steering (remote import)** is gone.

package/prompts/commands/sys-start.md

@@ -0,0 +1,63 @@
+# Process: start a new SYS (`waterfall sys start`)
+
+## Purpose
+
+Create a new technical subsystem folder under `technical/` with a minimal **`SYS-<NNN>.md`** scaffold, and advance `number.json` `next.SYS`.
+
+The **Waterfall CLI** runs **mechanical** scaffold + commit first, then invokes this prompt with **`--execute-agent`** (or dry-run) so **Purpose** is **synthesized** prose per **`sys-document-structure`**, not an italic placeholder.
+
+## When this prompt runs (agent refinement — phase 2)
+
+The CLI has **already** created **`technical/SYS-<NNN>-<slug>/SYS-<NNN>.md`** (placeholder **Purpose** + **`## Draft steering (CLI)`**), bumped **`number.json`**, and **committed**.
+
+**Your task:** edit **only** that **`SYS-<NNN>.md`**:
+
+- Replace the **Purpose** placeholder with subsystem **purpose and boundaries** per **[`sys-document-structure.md`](../items/sys-document-structure.md)** — **synthesize** from **Draft steering**; **no verbatim paste** as the only Purpose.
+- In **`## Purpose`**, **do not** mention **CR-***, **RQ-***, **UC-***, other **SYS-***, **STORY-***, **HOR-***, or **TST-*** — write scope in ordinary language (what this boundary owns and what is out of scope). Put **typed ids** only under **`### Downstream references`** (or notes), not in the Purpose paragraph.
+- **Remove** **`## Draft steering (CLI)`** when done.
+- Keep **Id**, **Status**, **`## Links and dependencies`** unchanged except as needed for prose consistency.
+
+**Out of scope for this agent pass:** **`number.json`**, other artifacts, story folders.
+
+## Scope of edits — mechanical phase only (CLI / human)
+
+Only touch:
+
+- New folder: `technical/SYS-<NNN>-<slug>/`
+- New file: `technical/SYS-<NNN>-<slug>/SYS-<NNN>.md`
+- `number.json` (`next.SYS` increment in same change)
+
+Out of scope: CR/RQ/UC/STORY/TST content edits, story creation, and restructuring existing SYS folders.
+
+## Rules
+
+1. Use `next.SYS` as the numeric source of truth (three-digit, zero-padded).
+2. Keep slug kebab-case and short.
+3. `SYS-<NNN>.md` must include:
+   - identity fields (`Id`, `Status`)
+   - `## Links and dependencies` with **`### Downstream references`** only (no **`### Upstream`** — see **[`sys-document-structure.md`](../items/sys-document-structure.md)**)
+   - `## Purpose`
+4. SYS creation is manual structure setup, not lifecycle chain execution.
+
+### Operator steering vs canonical SYS prose
+
+The CLI **`waterfall sys start`** scaffold may include **`## Draft steering (CLI)`** and an italic placeholder under **Purpose**.
+
+- **Synthesize** subsystem purpose and boundaries from that steering into real **Purpose** prose per **[`sys-document-structure.md`](../items/sys-document-structure.md)** — **not** a 1:1 paste of the steering block.
+- **Purpose** stays **free of typed ids** (**CR-***, **SYS-***, **STORY-***, …); traceability uses **`### Downstream references`**.
+- **Remove** **`## Draft steering (CLI)`** when **Purpose** is complete.
+
+## Steps
+
+1. Read `number.json` `next.SYS`.
+2. Create `technical/SYS-<NNN>-<slug>/`.
+3. Create `SYS-<NNN>.md` using `items/sys-document-structure.md`.
+4. Increment `next.SYS` in `number.json`.
+5. Commit scaffold change on the current feature branch.
+
+## Done when
+
+- New SYS folder exists with `SYS-<NNN>.md`.
+- `number.json` `next.SYS` is incremented.
+- No unrelated artifact types were edited.
+

package/prompts/commands/test-to-story.md

@@ -0,0 +1,64 @@
+# Process: TEST → STORY
+
+## Purpose
+
+When a **`TST-*`** or **`TC-*`** requires **implementation work** (harness, fixtures, automation, app changes to make a test runnable), capture that work as **`STORY-*`** items — **stories implement what the test needs**, not only product features.
+
+Examples: add integration test target, mock server, CI job, **`local-environment`** change, Playwright setup, API endpoint needed **only** for verification.
+
+## Scope of edits (strict)
+
+**Only** touch artifacts of these types in this action (plus **`number.json`** counter updates this workflow requires):
+
+| In scope | Typical paths |
+|----------|----------------|
+| **`TST-*`** | **`TST-<NNN>.md`** — append new **`STORY-*`** / **`BUG-*`** under `### Downstream references` plus status notes if needed. |
+| **`STORY-*`** | Under **`technical/SYS-*-…/<module>/`** when new work is **test-driven**. |
+| **`BUG-*`** | Under **`technical/SYS-*-…/<module>/`** when the gap is a **defect / regression** (per **`CURSOR.md`**) rather than greenfield test enablement. |
+| **`UC-*`** | Optional markdown links update only when needed; do not change **`UC-<NNN>.md`** behaviour or `TC-*` sections here. |
+
+**Out of scope (do not edit here):** **`CR-*`**, **`RQ-*`** / **`RQ` `RQ-<NNN>.md`**, wholesale rewrites of **`UC-<NNN>.md`** **`TC-*`** sections (that is **UC → TEST**). Do **not** use this pass to “also” implement product **STORY** scope unrelated to the cited **`TST`** / **`TC`**.
+
+## Preconditions
+
+- A **`TST-*`** and/or **`UC-<NNN>.md`** (**`TC-*`** sections) defines expected results.
+- You have identified **engineering work** that is **driven by the test** (not already covered by an existing **STORY**).
+
+## Content rules (STORY from tests)
+
+Each **STORY** created from **TEST** should:
+
+- **Respect `HOR-*`** horizontals the same way as **UC → STORY** — **`## Data and validation`** / API / **`## Technology`** notes must **align** with **`## Aggregated definitions`** in relevant **`database-model`**, **`api-model`**, and **`technical-stack`** files; **extend** only when the test or harness **requires** something not modeled there, and say so explicitly (**[`horizontal-structure.md`](../global/horizontal-structure.md)**).
+
+- State clearly that it **implements or enables** a **test** or **test level** (cite **`TST-*`** and **`TC-*`** ids).
+- Split **test infrastructure** from **product behaviour** when both are needed — separate STORIES if separable (e.g. “add health endpoint for probe” vs “add E2E suite wiring”).
+- **Acceptance criteria** should be observable: e.g. “`npm run test:integration` covers TC-002-01–03”, “CI runs TST-001 on PR”.
+- Ensure any new/updated `STORY-<NNN>.md` matches the required shape in **[`story-document-structure.md`](../items/story-document-structure.md)**.
+
+## Rules (graph + BUG)
+
+1. **Regressions / wrong behaviour** in product code → prefer **`BUG-*`** linking **`TST`**, **`STORY`**, **`UC`** as **`CURSOR.md`** describes.
+2. **New work** (automation, tooling, test-only endpoints with guardrails) -> **new `STORY-*`**; do not expand closed **`_STORY-*`**.
+3. One-way linking model: append produced **`STORY`** / **`BUG`** links under source **`TST-<NNN>.md`** -> `### Downstream references`.
+4. Trivial doc-only tweaks to **TST** may skip a STORY; anything touching **implementation repos** or **CI** should usually have a **STORY**.
+
+## Steps
+
+1. **Diff** **`TST-*`** / **`UC-<NNN>.md`** — see **[`before-changing-spec.md`](../global/before-changing-spec.md)** — and list **what must be built** to execute or automate the tests.
+2. For each **non-trivial** work item, create **`STORY-*`** (or **`BUG-*`**) with test-driven goal and acceptance criteria.
+3. Update or create the produced **`STORY-*`** / **`BUG-*`** markdown.
+4. In source **`TST-<NNN>.md`**, append new entries under `### Downstream references`; update status notes if tracked.
+5. Allocate ids from **`number.json`** in the same commit.
+
+## Done when
+
+- Every **test-execution gap** that needs code or infra has a **traceable STORY or BUG**, and **`TST → STORY|BUG`** edges are consistent.
+
+## CLI orchestration
+
+When this prompt is executed as part of a batch command (for example `waterfall cr all`, `waterfall rq all`, `waterfall uc all`, or `waterfall test all`), the CLI will run multiple prompts in separate agent invocations.
+
+1. Treat the operator-provided `hint` as global steering for the batch, but do not widen this step beyond its **Scope of edits (strict)**.
+2. If this step has **nothing to do** for the current artifact(s), make no changes and let the CLI proceed.
+3. Commit boundary: stop after this step's artifacts are internally consistent (`TST`/`STORY`/`BUG`/`number.json` for this step). The batch will not continue in this same invocation.
+

package/prompts/commands/uc-to-story.md

@@ -0,0 +1,85 @@
+# Process: UC → STORY
+
+## Purpose
+
+Turn **`UC-*`** intent into implementable **`STORY-*`** items under one or more existing **`technical/SYS-*`** subsystems. A single UC should be split into small, actionable stories, and those stories may land in different SYS areas.
+
+## Scope of edits (strict)
+
+**Only** touch artifacts of these types in this action (plus **`number.json`** counter updates this workflow requires):
+
+| In scope | Typical paths |
+|----------|----------------|
+| **`UC-*`** | In **`UC-<NNN>.md`**, append produced stories under `### Downstream references`. Do not rewrite behaviour/testcase content here. |
+| **`STORY-*`** | New or updated `technical/SYS-*-…/STORY-<NNN>-<slug>/STORY-<NNN>.md` (or equivalent folder pattern already used in the target SYS). |
+
+**Out of scope (do not edit here):** **`CR-*`**, **`RQ-*`** (theme / **`RQ-<NNN>.md`**), **`UC-<NNN>.md`** **acceptance (`TC-*`) sections** or wholesale rewrites of behaviour/testcases, **`TST-*`**, **`BUG-*`** (unless **`CURSOR.md`** mandates a parallel **BUG** for a defect — still prefer a **separate** BUG prompt). If the **UC prose** or **acceptance** is wrong, fix it under **RQ → UC** or **UC → TEST** in another change, **not** inside **UC → STORY**.
+
+## Preconditions
+
+- **`UC-<NNN>.md`** (behaviour + **`TC-*`** acceptance) exists and is stable enough to scope engineering work.
+- Target **`SYS-*`** areas are identified.
+- You have reviewed **[`before-changing-spec.md`](../global/before-changing-spec.md)** (e.g. **`git diff`** on the UC) so new stories align with **current** wording.
+- Applicable **`HOR-*`** horizontals for this change (e.g. **`database-model`**, **`api-model`**, **`technical-stack`**) are **read**; see **[`horizontal-structure.md`](../global/horizontal-structure.md)**. Stories **must respect** their **`## Aggregated definitions`** — names, types, tables, API contracts, and **named stack choices** stay **consistent** with the horizontal. **Extend** those concepts **only** when the **UC** truly needs something not yet modeled; then state the extension **explicitly** in the STORY and treat a **horizontal** refresh as the normal follow-up when the extension is durable.
+- SYS creation is manual and out of lifecycle orchestration: this prompt selects from existing SYS only.
+
+## Granular STORY breakdown (required mindset)
+
+- **One STORY = one shippable engineering slice** (clear goal, bounded acceptance, explicit **out of scope** for the rest of the UC). If the UC implies **search**, **cart**, **checkout**, **persistence**, **API**, **UI** work, create **multiple** **`STORY-*`** items — do **not** collapse the whole UC into a single vague story.
+- **Split by vertical slice or layer** when each part has different **TC-*** coverage, different **SYS** homes, or different sequencing (e.g. schema + API before storefront flow).
+- **Each STORY** must still satisfy **[`story-document-structure.md`](../items/story-document-structure.md)** (**`## Data and validation`**, **`## Technology`**, etc.) for **its** slice only; do not use one story as a dump of every open question for the UC.
+- Link every produced story from **`UC-<NNN>.md`** `### Downstream references`; cite **UC** / **TC-*** by **id only** — **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+
+See **[`content-requirements-vs-use-cases.md`](../global/content-requirements-vs-use-cases.md)** → **Granularity: multiple STORY items from one UC**.
+
+## Content rules (STORY body)
+
+Each **STORY** should:
+
+- **Honor horizontals:** **`## Data and validation`** and **`## Technology`** (and any API/persistence prose) must **not** contradict relevant **`HOR-*`** definitions — including **`technical-stack`** (frameworks, libraries, runtimes). Prefer **reusing** consolidated model, contract, and stack text **by meaning** (cite **`HOR-<NNN>`** by id if you need a single traceability line). Only **add** new fields, resources, types, or **stack components** when the UC slice **requires** them and the horizontal does not yet cover them — then document the delta clearly.
+- Map to **part of the UC** you can deliver independently (API slice, UI slice, infra, docs in implementation repo, etc.) — **not** one giant “do everything” unless the UC is truly atomic.
+- State **goal** and **acceptance criteria** that **trace** to **UC** sections and/or **`TC-*`** ids where helpful — cite **`UC-<NNN>`** and **`TC-*`** by **id only**, never by file path (**[`before-changing-spec.md`](../global/before-changing-spec.md)**).
+- List **out of scope** so the next STORY can pick up the remainder without overlap.
+- Prefer **several small STORIES** over one vague one when the UC change is large (phasing, vertical slices).
+- Split by subsystem ownership when needed: one UC may produce stories in multiple SYS folders.
+- Ensure `STORY-<NNN>.md` matches the required shape in **[`story-document-structure.md`](../items/story-document-structure.md)**.
+
+### Concrete engineering detail (required depth)
+
+Stories must be **implementation-ready**, not vague intent:
+
+- **`## Data and validation` (required):** name **entities / fields / types** (or equivalent schema shapes), **validity rules** (ranges, required fields, uniqueness, state transitions), and what “invalid” means for this slice.
+- **`## Technology` (required):** name **concrete** stack choices for this slice — languages, frameworks, protocols, storage type (e.g. relational table vs document vs cache), integration style (REST/gRPC/events) — at the level the team needs to start work without guessing.
+- Tie those sections to **UC** / **`TC-*`** by **id** so traceability stays compact.
+
+If information is still unknown, state **explicit assumptions** or **open decisions** in the STORY rather than leaving generic placeholders.
+
+## Rules (graph + process)
+
+1. One-way linking model: when a story is created, append it in source **`UC-<NNN>.md`** under `### Downstream references`.
+2. Keep traceability in markdown only through `### Downstream references` in the source UC.
+3. Use **`number.json` `next.STORY`**; **closed** stories get **`_STORY-*`** folder prefix only — never edit closed stories for new scope (**`CURSOR.md`**).
+4. **Implementation** happens outside **`waterfall-spec`**; the STORY describes what lands in which SYS-owned technical area.
+5. SYS entities are not created by this lifecycle edge; if a new SYS is needed, create it manually first.
+
+## Steps
+
+1. **Diff / read** the UC — see **[`before-changing-spec.md`](../global/before-changing-spec.md)** — and list **concrete deltas** (new flows, changed preconditions, new exceptions).
+2. **Decompose** those deltas into **ordered or parallel** STORIES (each shippable, each with clear acceptance), grouped by target SYS ownership.
+3. Allocate each **`STORY-<NNN>`** under the appropriate existing **`technical/SYS-…/`** path.
+4. Write **`STORY-<NNN>.md`**: goal, acceptance criteria (linked to UC / TC where useful), out-of-scope, and links section.
+5. In source **`UC-<NNN>.md`**, append each produced story under `### Downstream references`.
+6. Increment **`next.STORY`** per new STORY in the **same** commit batch as appropriate.
+
+## Done when
+
+- Every planned UC change has at least one STORY (or explicit deferral), stories are split into actionable chunks, and `UC -> STORY` traceability is present under `### Downstream references` in the UC.
+
+## CLI orchestration
+
+When this prompt is executed as part of a batch command (for example `waterfall cr all`, `waterfall rq all`, or `waterfall uc all`), the CLI will run multiple prompts in separate agent invocations.
+
+1. Treat the operator-provided `hint` as global steering for the batch, but do not widen this step beyond its **Scope of edits (strict)**.
+2. If this step has **nothing to do** for the current artifact(s), make no changes and let the CLI proceed.
+3. Commit boundary: stop after this step's artifacts are internally consistent (`UC`/`STORY`/`number.json` for this step). The next lifecycle step prompt will be invoked separately.
+

package/prompts/commands/uc-to-test.md

@@ -0,0 +1,58 @@
+# Process: UC → TEST
+
+## Purpose
+
+**Create or adapt** verification so that **all changes** to a **`UC-*`** are **covered** by **`TC-*`** acceptance sections in **`UC-<NNN>.md`** and, where used, **`TST-*`** (manual and/or automated).
+
+## Scope of edits (strict)
+
+**Only** touch artifacts of these types in this action (plus **`number.json`** counter updates this workflow requires):
+
+| In scope | Typical paths |
+|----------|----------------|
+| **`UC-*`** | **`UC-<NNN>.md`** — update `## TC-...` acceptance blocks and append produced tests under `### Downstream references`. |
+| **`TST-*`** | `tests/TST-<NNN>-<slug>/TST-<NNN>.md`. |
+
+**Out of scope (do not edit here):** **`UC-<NNN>.md`** behaviour narrative (**actors** through **main flow**, **exceptions**, **non-functional** sections, etc.) unless a **separate** **RQ → UC** (or explicit UC authoring pass) already changed it — **UC → TEST** does not redefine product behaviour. **`CR-*`**, **`RQ-*`**, **`SYS-*`**, **`STORY-*`**, **`BUG-*`**.
+
+## Preconditions
+
+- **`UC-<NNN>.md`** contains (or will contain) **`TC-*`** sections aligned to the use case.
+- You know whether verification is **manual-only**, **automated in an implementation repo**, or both.
+- You have run **`git diff`** (or equivalent) on **`UC-<NNN>.md`** — see **[`before-changing-spec.md`](../global/before-changing-spec.md)** — so you see **every** delta that needs test coverage.
+
+## Content rules
+
+1. **Every new or changed** main-flow step, precondition, postcondition, or **exception** in the **behaviour** part of **`UC-<NNN>.md`** should map to **at least one** **`TC-*`** (new or updated steps/expected outcome), unless explicitly marked non-testable (rare — then document why next to the **`TC-*`** or in a short note in the same file).
+2. **Regressions:** if behaviour is **removed** or **replaced**, **retire or rewrite** the affected **`TC-*`** blocks so no stale acceptance remains.
+3. **`TST-*`** (if present) must **mirror** the **`TC-*`** set you intend to run as a **formal spec** — add or adjust **TST** sections when **TCs** change; cite testcase ids in **TST** tables.
+4. **Automation** (implementation repo) should still trace to **`TC-*`** / **TST** in prose or CI docs — no “mystery tests” with no UC id.
+
+## Rules (graph + ids)
+
+1. **Source of testcase ids:** **`UC-<NNN>.md`** (`**## TC-…**` headings) — **`TST-*`** cites those ids; do not invent parallel numbering in **`TST-*`** without mapping.
+2. One-way linking model: append new `TST-*` links in the source **`UC-<NNN>.md`** under `### Downstream references`.
+3. **`number.json` `next.TST`** for new **`TST-*`** folders under **`tests/`**.
+
+## Steps
+
+When creating/updating **`TST-<NNN>.md`**, follow **[`tst-document-structure.md`](../items/tst-document-structure.md)** so identity, `Links and dependencies`, `Objective`, `Environment and data`, and `TC-*` table sections remain consistent.
+
+1. From the **UC diff**, list **coverage gaps** (missing **TC-**, outdated expected outcomes, new branches).
+2. **Update `UC-<NNN>.md`** — edit **`TC-*`** sections first until the delta is fully covered.
+3. **Update or create `TST-*`** so it reflects the same scope (new sections, environment notes, manual vs automated).
+4. In **`UC-<NNN>.md`**, append each produced test spec under `### Downstream references`.
+5. Increment **`next.TST`** when adding a new **`TST-*`**.
+
+## Done when
+
+- **No UC change** is left without a matching **`TC-*`** update (or explicit documented exception), and every **`TST-*`** row traces to a **`TC-*`** where applicable.
+
+## CLI orchestration
+
+When this prompt is executed as part of a batch command (for example `waterfall cr all`, `waterfall rq all`, or `waterfall uc all`), the CLI will run multiple prompts in separate agent invocations.
+
+1. Treat the operator-provided `hint` as global steering for the batch, but do not widen this step beyond its **Scope of edits (strict)**.
+2. If this step has **nothing to do** for the current artifact(s), make no changes and let the CLI proceed.
+3. Commit boundary: stop after this step's artifacts are internally consistent (`UC`/`TST`/`number.json` for this step). The next lifecycle step prompt will be invoked separately.
+