@pknx/waterfall-cli 0.1.0

package/prompts/global/before-changing-spec.md

@@ -0,0 +1,62 @@
+# Before changing spec artifacts — review the actual delta
+
+## Important: cross-references in spec **content** (compact ids)
+
+In **prose inside** **`CR-*`**, **`RQ-*`**, **`UC-*`**, **`STORY-*`**, **`TST-*`**, **`HOR-*`**, **`BUG-*`**, and **`SYS-*`** bodies:
+
+- **Never** refer to another artifact by **file path** (no `` `technical/...` ``, no `` `requirements/...` `` in running text).
+- **Always** use the **typed id** only: **`CR-001`**, **`RQ-002`**, **`UC-003`**, **`STORY-004`**, **`TST-005`**, **`SYS-006`**, **`HOR-007`**, **`BUG-008`** (and stable **`TC-*`** ids inside a UC).
+
+**Why:** paths churn with refactors and bloat the spec; ids stay stable and grep-friendly. **Git** and **diff** commands are for **your** review process — they are not how readers should cite dependencies in markdown.
+
+**Horizontals (`HOR-*`):** **`## Aggregated definitions`** must hold **substance** (models, contracts, rules), not catalogs of paths. At **most one** optional **traceability** line per logical topic may cite a single **`STORY-<NNN>`** (id only) if needed — do not dump path lists into horizontal body text.
+
+**No “upstream” graph in markdown:** Do **not** add **`**Upstream:**`** identity fields or **`### Upstream`** under **`## Links and dependencies`**. Trace parents with **typed fields** (**`CR:`**, **`UC:`**) or prose ids, and use **`### Downstream references`** for children only — see **`prompts/items/*-document-structure.md`**.
+
+**`### Downstream references` and similar lists:** List children as **typed ids only** (e.g. `- RQ-002`, `- STORY-014`, `- TST-003`). Do **not** use markdown links whose targets are repository paths — paths churn and duplicate what the id already names. Readers and search jump on **`RQ-002`** / **`STORY-014`**; optional tooling may resolve ids without embedding paths in spec text.
+
+**`*Source:*` lines (e.g. in `TST-*`):** Cite **`UC-<NNN>`** and the matching **`TC-<NNN>-<seq>`** by **id only** (e.g. `*Source: UC-004 / TC-004-01*`), never a path to **`UC-<NNN>.md`**.
+
+## Operator hints and prompt **structure** (not spec body text)
+
+- **Operator hint** — text the **Waterfall CLI** injects before a workflow (including blocks like **CR branch — changed paths** or **`waterfall horizontal update`** path lists) is **steering context** for that run. **Interpret** it (what to read, what changed, what to reconcile). Do **not** paste it **verbatim** into **`## Summary`**, **`## Purpose`**, titles, **identity** blocks, or other artifact sections unless you are deliberately keeping a single polished sentence as the canonical description.
+- **Create-command scaffolds** — **`waterfall cr start`**, **`sys start`**, and **`horizontal create`** write **`## Draft steering (CLI)`** (raw operator text) plus italic placeholders in canonical sections. Treat that block as **scratch input**: **rephrase** into structured content per the relevant **`prompts/items/*-document-structure.md`** (or **`horizontal-structure.md`** for **HOR**), then **remove** **Draft steering** when done. Canonical sections must **not** stay a 1:1 copy of the steering text.
+- **`SYS-*` / `HOR-*` — `## Purpose`:** write scope in **plain language** without **CR-***, **SYS-*** (siblings), **STORY-***, **RQ-***, **UC-***, **HOR-*** (peers), or **TST-***. Traceability uses **`### Downstream references`** and (for horizontals) **`## Aggregated definitions`** when appropriate — not the Purpose paragraph.
+- **CLI wire: read order** — When the primary workflow is attached as a **file** segment in **system** (reference delivery), read that workflow from disk **first**, then use the **user** text segments (operator hint, then any separate **CR branch — paths changed** block) as steering. When the workflow is inlined under **user** (embed delivery), read **user** top to bottom: operator hint and scope segments, then the workflow body.
+- **Prompts are not filler** — files under **`prompts/global/`**, **`prompts/items/`**, and **`prompts/commands/`** define **shape, rules, and process**. They are **not** meant to be copied into **`CR-*`**, **`RQ-*`**, **`UC-*`**, **`STORY-*`**, **`TST-*`**, **`HOR-*`**, or **`SYS-*`** bodies as boilerplate or “Purpose” text. Write **substance** for the product; cite **typed ids** where traceability is needed.
+
+---
+
+## Rule
+
+**Before** you edit **`UC-*`**, **`RQ-*`**, **`CR-*`**, **`TST-*`**, or **`STORY-*`** files, inspect the current repository state so your change matches what is already there, not an assumed older version.
+
+## Baseline: always **`develop`**
+
+For **`waterfall-spec`**, **Git diff review is always anchored to `develop`** — the integration branch defined in **[`CURSOR.md`](../CURSOR.md)**. Do **not** use **`main`**, a generic **`HEAD`-only** review, or another default as the comparison line unless the team has **explicitly** documented an exception.
+
+1. **`git fetch origin develop`** (when you use a remote named **`origin`**) so local **`develop`** matches the shared line where possible.
+2. **Working tree vs `develop`** — **`git diff develop`** (optionally **`git diff develop -- <path>…`**) — everything that differs from the tip of **`develop`** to your **current files** (includes **staged** and **unstaged** changes on top of whatever branch you are on).
+3. **Commits on your branch vs `develop`** — **`git diff develop...HEAD`** (optionally with **`-- <path>…`**) — changes **reachable from `HEAD`** since the **merge base** with **`develop`** (useful on **`feature/…`** branches without mixing in unstaged noise).
+4. **Single file** — same refs: e.g. **`git diff develop -- requirements/…/UC-002.md`** or **`git diff develop...HEAD -- path/to/file`**.
+5. **History** — **`git log -p develop..HEAD -- path/to/file`** (or **`develop...HEAD`** with three dots for symmetric difference) when you need prior commits on the branch without contradicting **`develop`**.
+
+**If you are on `develop` with only local (uncommitted) edits:** **`git diff`** and **`git diff --staged`** still show your pending delta vs the last commit; after **`git fetch`**, **`git log HEAD..origin/develop`** (or **`git diff HEAD origin/develop`**) checks whether **`develop`** moved upstream before you edit.
+
+## Workflow prompts: one action, one artifact set
+
+Each edge guide under **`prompts/`** (**CR → RQ**, **RQ → UC**, **UC → STORY**, **UC → TEST**, **TEST → STORY**) includes **Scope of edits (strict)** — **only** the **target types** for that transition may be modified in that run. **Do not** mix layers (e.g. no **`UC`** body edits inside **CR → RQ**). If multiple layers need updates, **finish** one prompt’s scope, commit or hand off, then run the next prompt.
+
+## Why
+
+- Avoids blind overwrites of links or markdown sections someone else refined.
+- Makes **incremental** updates (new testcase, tightened scope) easier to phrase consistently.
+- Surfaces **merge residue** or **duplicate** sections before you add more text.
+- Keeps review **comparable** with the same integration line the team merges to (**`develop`**).
+
+## When applying prompts from an agent
+
+Instruct the agent to **read the file from disk** and to show or run **`git diff`** **against `develop`** (per Baseline above) **before** proposing edits — especially for **`UC`** / **`RQ`** / **`TST`** where tables and ids must stay aligned.
+
+This complements (does not replace) **`CURSOR.md`** Git branch rules: still work on **`feature/CR-<NNN>`** (or **`feature/<short-slug>`** for non-CR work) as required; **diff** is for **awareness of content** relative to **`develop`**, not a substitute for branching.
+

package/prompts/global/content-requirements-vs-use-cases.md

@@ -0,0 +1,116 @@
+# Content rules — RQ (requirement theme) vs UC (use case)
+
+These rules describe **what to write** at each layer. Process steps live in the edge-specific prompt files.
+
+---
+
+## Requirement (`RQ-*` / `RQ-<NNN>.md` under the RQ folder)
+
+**Purpose:** State the **general** intent of a **functionality area** — the “why” and “what kind of capability” — **without** prescribing a single user click-path.
+
+**Include:**
+
+- **General purpose** — what capability the theme delivers, in **broad terms** (product language, not UI steps).
+- **Scope** — what **is** in the RQ: themes, sub-areas, major boundaries.
+- **Constraints** — policy, non-goals, dependencies on other RQs or CRs, quality bars (e.g. security posture, “local-only”, “OIDC only”) when they apply to the **whole theme**.
+- **Out of scope** — explicit exclusions so UCs do not sprawl.
+- **Links** — optional owning **CR-<NNN>** in identity or **Summary** (typed id); **`### Downstream references`** for UCs and related summaries as the graph grows. Do **not** maintain an **`### Upstream`** subsection.
+
+**Avoid:**
+
+- Step-by-step “user does X then Y” unless that is the **only** way to express a constraint (rare at RQ level).
+- Duplicating full testcase tables (those belong in **`UC-<NNN>.md`**).
+
+---
+
+## Use case (`UC-<NNN>.md`)
+
+**Purpose:** Describe **one specific, actionable** slice of behavior: a **flow** actors can perform or a **system behaviour** you can verify — **and** how acceptance is proven.
+
+**Behaviour sections (same file) must include:**
+
+- **Actors** and **goal** tied to a **concrete** outcome.
+- **Main flow** (numbered or structured) — **actions** and **system responses** someone could **execute** or **test** (login, start stack, open page, …).
+- **Preconditions / postconditions** that make the flow **testable**.
+- **Exceptions** — error paths with expected handling.
+- **Context** sections as needed (still inside this file — see [`uc-document-structure.md`](../items/uc-document-structure.md)).
+
+**Acceptance sections (same file)** — use stable headings **`## TC-<NNN>-<seq> — …`**:
+
+- **Acceptance tests** — each testcase id (e.g. **TC-002-01**) with objective, preconditions, **steps**, and **expected outcome** so **completion of the UC** can be judged objectively.
+- Coverage aligned to the **main flow** and **critical exceptions**; add or change cases when the UC changes.
+
+**Avoid:**
+
+- Vague goals (“good UX”) without observable criteria — tie them to **`TC-*`** sections or measurable checks.
+
+---
+
+## Relationship
+
+| Layer | Question it answers |
+|-------|---------------------|
+| **RQ** | What **area** of the product are we building, under what **constraints** and **scope**? |
+| **UC** | What **specific** flow or behaviour must work, and **how do we know** it is done (**`TC-*`** ids in **`UC-<NNN>.md`**)? |
+
+If an idea is still “fuzzy,” keep it in **RQ** or **CR** until it can be written as an **actionable** UC plus **`TC-*`** acceptance.
+
+---
+
+## Granularity: breaking an **RQ** into **multiple UCs**
+
+One **RQ** theme should usually become **several** UCs, not one oversized document.
+
+**Prefer a separate `UC-*` for each:**
+
+- **Separable user- or system-visible outcome** (e.g. “search catalog” vs “add line item to cart” vs “submit order”) — not one UC titled “everything checkout.”
+- **Distinct actor or channel** when behaviour or rules differ materially (guest vs authenticated, API vs web).
+- **Independent test surface** — if acceptance would be a huge single **`TC-*`** list, split so each UC has a tight, reviewable testcase set.
+- **Different failure / policy envelope** (e.g. payment retry vs inventory reservation).
+
+**Anti-patterns:**
+
+- A single UC that lists ten unrelated flows in one **main flow** — split into multiple UCs and link them under the same **RQ** `### Downstream references`.
+- Copy-pasting **RQ** prose into **UC** without actionable steps — the UC must be executable/testable.
+
+Cross-references between UCs use **ids only** (`UC-002`, `UC-003`), not paths — see **[`before-changing-spec.md`](before-changing-spec.md)**.
+
+---
+
+## Granularity: multiple RQ themes from one CR
+
+A **CR** often spans **several product themes**. Prefer **several RQs** over one umbrella RQ that tries to cover everything in the change.
+
+**Prefer a separate `RQ-*` for each:**
+
+- **Separable product or customer-facing theme** (e.g. catalog search vs cart/checkout vs account orders) — not one RQ titled “bookstore” that lists every subsystem in one file.
+- **Different constraint or policy envelope** (e.g. guest vs authenticated commerce rules, public vs admin-only capabilities).
+- **Independent downstream planning** — if different teams or phases could ship different themes, split RQs so **RQ → UC** can run per theme without dragging unrelated scope into every UC pass.
+
+**Anti-patterns:**
+
+- One **RQ** whose **Scope** reads like a CR dump of every file you might touch — refine into themes or defer explicit “phase 2” RQs with a short note on the **CR**.
+- Skipping **RQ** split because “it is all one feature” when acceptance and ownership clearly diverge (still one **CR**, multiple **RQ** children).
+
+Link every **RQ** from the source **CR** `### Downstream references` (**typed ids only**).
+
+---
+
+## Granularity: multiple STORY items from one UC
+
+**UC → STORY** is where work becomes **implementation-sized**. One **UC** usually becomes **several** stories, not one “implement the whole UC” mega-story.
+
+**Prefer a separate `STORY-*` for each:**
+
+- **Separable delivery slice** — API endpoint group, persistence layer, storefront page flow, background job, migration, or infra — that you could review, estimate, or ship in a meaningful chunk.
+- **Different SYS ownership** when the same UC touches multiple subsystems (each SYS gets its own stories where possible).
+- **Different risk or sequencing** — foundation (schema, auth hook) before UI; read path before write path when the UC describes both.
+- **Bounded acceptance** — if one story would need ten unrelated acceptance bullets, split so each **STORY** traces to a **subset** of **TC-*** ids or UC sections.
+
+**Anti-patterns:**
+
+- One **STORY** whose **Goal** restates the entire UC title with no narrowing — decompose into vertical slices with explicit **out of scope** on each story for the remainder.
+- Folding **unrelated** UC changes into a single story because “we are already editing that SYS” — split by concern; link both under the UC `### Downstream references`.
+
+See **[`story-document-structure.md`](../items/story-document-structure.md)** and the **UC → STORY** command prompt for process steps.
+

package/prompts/global/cursor-overview.md

@@ -0,0 +1,31 @@
+# CURSOR.md overview — spec “law” pointer
+
+Authoritative source in the spec tree: `waterfall-spec/CURSOR.md`.
+
+## Role of `CURSOR.md`
+
+`CURSOR.md` is the normative document for:
+
+- **Directory layout** of `waterfall-spec` (where CR, RQ, UC, SYS, STORY, TST live),
+- **Naming conventions** (id formats, folder names, `_STORY-*` closure rule),
+- **Branching rules** (work on `feature/...`, no direct `develop` edits),
+- **Graph discipline** (how artifacts reference each other),
+- **Immutability constraints** for closed artifacts.
+
+All prompt files and CLI behavior must stay consistent with `CURSOR.md`. If there is ever a conflict, `CURSOR.md` wins.
+
+**File names (CLI + `prompts/items/*`):** each primary artifact lives in a **typed folder** with a matching **`ITEM-<NNN>.md`** file — e.g. **`changerequests/CR-001-slug/CR-001.md`**, **`requirements/RQ-002-slug/RQ-002.md`**, **`technical/SYS-003-slug/SYS-003.md`**, **`technical/horizontals/HOR-004-slug/HOR-004.md`**.
+
+## When to read `CURSOR.md`
+
+Agents and operators should consult `CURSOR.md` when:
+
+- introducing new artifacts (CR/RQ/UC/STORY/TST),
+- changing directory structure or file naming,
+- changing downstream references between artifacts,
+- interpreting rules around closed stories/tests.
+
+Prompt files under `prompts/commands/` and structure guides under `prompts/items/` assume the rules from `CURSOR.md` as their baseline.
+
+**CLI operator hints** and **prompts/** wording: see **[`before-changing-spec.md`](./before-changing-spec.md)** — hints are steering only (not verbatim Summary/Purpose); structure guides are not copied into artifact bodies as filler.
+

package/prompts/global/git-usage.md

@@ -0,0 +1,46 @@
+# Git usage for `waterfall-spec` (from CLI)
+
+This prompt summarizes how to use Git safely when editing **`waterfall-spec`** while you are operating via the **`waterfall` CLI**. The **authoritative** rules still live in **`CURSOR.md`** inside `waterfall-spec`; if anything here disagrees, **`CURSOR.md` wins**.
+
+## 1. Diff discipline — always compare against `develop`
+
+Before you edit **`CR-*`**, **`RQ-*`**, **`UC-*`**, **`STORY-*`**, or **`TST-*`**:
+
+- Review the **actual delta** on disk anchored to **`develop`**.
+- Recommended commands (see **`before-changing-spec.md`** in this same `global/` folder for full details):
+  - `git fetch origin develop`
+  - `git diff develop` (or `git diff develop -- <path>…`)
+  - `git diff develop...HEAD` for branch-range changes
+  - `git log -p develop..HEAD -- <path>` when you need history
+
+**Do not** rely on intuition about “what probably changed”; always inspect the real diff first.
+
+## 2. One transition, one artifact set
+
+Lifecycle prompts and CLI commands follow **strict scopes**:
+
+- **CR → RQ**
+- **RQ → UC**
+- **UC → STORY**
+- **UC → TEST**
+- **TEST → STORY**
+
+In each run, only the **target types** for that edge may be changed (plus `number.json` where required). If multiple layers need updates, **finish one edge, commit or hand off, then run the next**. Do not mix CR, RQ, UC, STORY, TST edits into a single unstructured commit driven by one prompt.
+
+## 3. Branching rules (summary — see `CURSOR.md` for full law)
+
+- **No working commits on `develop`**: author spec changes on a non‑`develop` branch, then integrate via merge.
+- **CR‑scoped work**:
+  - Use branches named **`feature/CR-<NNN>`** or **`feature/CR-<NNN>-<slug>`**.
+  - Keep all commits for that CR on its `feature/CR-<NNN>…` branch until integration.
+  - Do **not** use `cr-<NNN>-...` or `CR-<NNN>-...` without the `feature/` prefix.
+- **Non‑CR cleanup / maintenance work**:
+  - Use short-lived branches like **`feature/<short-slug>`**.
+  - Do not use **`chore/*`** branch names.
+
+For the complete set of Git rules (including recovery guidance), read **`CURSOR.md` → “Git workflow (this repository)”** in the `waterfall-spec` repository.
+
+## Spec body text vs git paths
+
+**Git** commands (`git diff develop`, path-scoped diffs) are for **operators and agents** to **inspect** the tree. **Inside** markdown artifacts (**`CR`**, **`RQ`**, **`UC`**, **`STORY`**, **`HOR`**, etc.), **cross-references must use typed ids** (`STORY-001`, `UC-002`) — **not** repository paths. See **[`before-changing-spec.md`](before-changing-spec.md)**.
+

package/prompts/global/horizontal-structure.md

@@ -0,0 +1,75 @@
+# Horizontal artifacts (**HOR-***) — structure and patterns
+
+**Horizontals** live under **`technical/horizontals/HOR-<NNN>-<slug>/HOR-<NNN>.md`**. They are **cross-cutting** views: one document that **aggregates** a concern (schemas, APIs, **technical stack**, security rules, etc.) **across many anchored items** (today: **story**).
+
+CLI: **`waterfall horizontal create …`**, **`waterfall horizontal update HOR-NNN`**. Both run only on a **change-request branch** **`feature/CR-<NNN>-…`** (same rule as **`sys start`** and lifecycle prompts), not on **`develop`**.
+
+**Scaffold from `horizontal create`:** the file may ship **`## Draft steering (CLI)`** (raw operator purpose text) and an italic placeholder under **Purpose**. **Synthesize** a tight **Purpose** and later fill **`## Aggregated definitions`** from story substance (especially after **`horizontal update`**) — **not** by leaving **Purpose** as a verbatim copy of steering. **`## Purpose`** should **not** cite **CR-***, **SYS-***, **STORY-***, etc. — plain-language scope only; ids live in **Aggregated definitions** when needed for traceability. Remove **Draft steering** when the doc stands on its own.
+
+**Reference rule:** In **`HOR-<NNN>.md`**, **`## Aggregated definitions`** is **substance** (models, contracts, invariants in prose or tables). Do **not** fill it with file paths, directory trees, or bullet lists of paths. Cite sources by **typed id** only (**`STORY-012`**, **`UC-003`**) — **at most one** such id per logical subsection when traceability is needed; prefer **zero** if the definition is self-contained. See **[`before-changing-spec.md`](before-changing-spec.md)**.
+
+**Git signal:** **`waterfall horizontal update`** prints **`develop...HEAD`** path lists in the **operator hint** only. Use them to find what to read; **fold** facts into **`## Aggregated definitions`** — the horizontal markdown file itself should not accumulate raw git listings.
+
+## When to use a horizontal
+
+- Several **STORY** artifacts (or future anchors) each mention the **same concern** (e.g. persistence, REST shapes).
+- You want a **single place** to reconcile naming, types, and invariants **in words and tables**, not a second copy of every story path.
+- The horizontal **does not replace** stories; it **summarizes** the agreed cross-cutting truth.
+
+## `## Aggregated definitions` — what “good” looks like
+
+- **Database / `database-model`:** follow **Database model — required shape** under **`database-model`** below (full table inventory, datatypes, Mermaid ER) — not “see `technical/...`”.
+- **API / `api-model`:** resources, methods, request/response field summaries, errors, versioning — written out.
+- **Technical stack / `technical-stack`:** follow **Technical stack — required shape** under **`technical-stack`** below (languages, frameworks, libraries, tooling — one reconciled inventory).
+- **Bad:** paragraphs that are mostly `` `path/to/file` `` bullets; **good:** compact definitions with **optional** single **`STORY-<NNN>`** pointer only where one story owns an edge case.
+
+## Common horizontal kinds (examples)
+
+### `database-model`
+
+- **Collects:** every persisted **table** (or equivalent store) in scope, **all columns** with **datatypes**, keys, nullability / defaults where normative, relationships, migration notes, and **persistence** rules — as **written definitions** inside **`## Aggregated definitions`**.
+- **Process:** After **`horizontal update`**, use the **hint** path list, then **merge facts** into **## Aggregated definitions**.
+
+#### Database model (`database-model`) — required shape
+
+Inside **`## Aggregated definitions`**, a **`database-model`** horizontal **must** include:
+
+1. **Entity-relationship diagram** — one fenced **`mermaid`** block using **`erDiagram`**. **Every** in-scope table appears as an entity; **every** foreign-key (or equivalent) relationship appears with correct cardinality. Entity blocks **must list all attributes** with types (same logical names and types as the per-table tables below — no orphan columns in prose only).
+2. **Per-table definitions** — for **each** table, a subsection headed with the **table name** containing a **markdown table** with at least **Field** and **Type** columns for **every** column; add **Null**, **Default**, and **Notes** columns when the team needs them. No hand-wavy “see stories”; the horizontal is the **inventory of record** for the datamodel.
+
+Optional short prose before or after is fine for narrative (e.g. engine, schema name); it does not replace the diagram or column tables.
+
+- **Quality bar:** Stories stay detailed; the horizontal stays **one reconciled summary** that is **machine-checkable** (complete column list + ER).
+
+### `api-model`
+
+- **Collects:** resource paths, methods, request/response shapes, error conventions, versioning — as **contract text**, not link farms.
+- **Process:** Same — **`horizontal update`** supplies the path list in the hint; you **author** the consolidated contract in **## Aggregated definitions**.
+
+### `technical-stack`
+
+- **Collects:** the **single inventory of record** for **technologies** the system actually uses: languages and runtimes, application frameworks, major **libraries** and SDKs, databases and clients, message brokers, HTTP/gRPC stacks, front-end UI kits, test runners, build tools, linters, container base images, CI actions — whatever **STORY** artifacts commit to for this product or CR.
+- **Process:** After **`horizontal update`**, use the **hint** path list, read relevant **STORY** **`## Technology`** / **`## Data and validation`** sections, and **deduplicate** into **`## Aggregated definitions`**.
+
+#### Technical stack (`technical-stack`) — required shape
+
+Inside **`## Aggregated definitions`**, a **`technical-stack`** horizontal **must** include:
+
+1. **Grouped inventory** — one **`###`** subsection per **category** your team uses (adapt names as needed), for example: **Languages & runtimes**, **Backend frameworks & servers**, **Frontend & UI**, **Data stores & clients**, **Messaging & integration**, **Auth & security libraries**, **Testing**, **Build, packaging & CI**, **Observability & ops tooling**. Empty categories may be omitted or marked *not used*.
+2. **Tables, not prose-only lists** — under each category, a **markdown table** with at least **Component** (product or library name) and **Role** (what it does in *this* system). Add **Version** (or version policy, e.g. “LTS Node 20”) and **Notes** when stories specify them. **Every** technology that remains in active use across in-scope stories should appear **once** in the right group (no duplicates across groups unless intentionally distinct deployments).
+
+Optional one-line **narrative** (e.g. “Primary backend is Node; storefront is Next.js”) is fine above the tables; it does not replace the inventory.
+
+- **Quality bar:** A new engineer can answer “what do we run and import?” from this file alone; stories stay the **source of detail**, the horizontal is the **reconciled catalog**.
+
+### Other slugs
+
+Use a **short kebab-case** name (`security-model`, `event-model`, …). Describe in **## Purpose** what is in scope and what is out of scope.
+
+## Anchor item type
+
+Today the CLI supports **`story`** only: path filters in **`horizontal update`** look for **`STORY-*`** / **`_STORY-*`** segments in paths changed vs **`develop`**. More anchors may be added later.
+
+## Related prompts
+
+- **`prompts/commands/horizontal-update.md`** — agent pass after **`horizontal update`** to refresh **aggregated** content (not path indexes).

package/prompts/global/workflows-index.md

@@ -0,0 +1,59 @@
+# Workflows index — prompt families (CR ↔ RQ ↔ UC ↔ STORY ↔ TEST, with SYS as manual structure)
+
+Authoritative source in the spec tree: `waterfall-spec/prompts/workflows.md`.
+
+## Purpose
+
+Give operators and agents a single place to see:
+
+- which lifecycle *edges* exist (CR→RQ, RQ→UC, UC→STORY, UC→TEST, TEST→STORY),
+- which prompt file backs each edge,
+- which CLI commands should be used against those prompts.
+
+`SYS-*` artifacts are part of technical structure, but SYS creation is manual and not a dedicated lifecycle edge command.
+
+**HOR-*** (horizontals) aggregate cross-cutting definitions across anchored items (e.g. **story**) — kinds include **`database-model`**, **`api-model`**, **`technical-stack`**, and others in **`horizontal-structure.md`**.
+
+## Edges and prompts
+
+- **CR → RQ** — `prompts/commands/cr-to-rq.md`
+- **RQ → UC** — `prompts/commands/rq-to-uc.md`
+- **UC → STORY** — `prompts/commands/uc-to-story.md`
+- **UC → TEST** — `prompts/commands/uc-to-test.md`
+- **TEST → STORY** — `prompts/commands/test-to-story.md`
+
+Each of these prompt files includes:
+
+- a **Scope of edits (strict)** section, and
+- a **CLI orchestration** section (for the corresponding `... all` command).
+
+## CLI-oriented workflows
+
+For any command that invokes an agent from a **change-request branch** (`feature/CR-<NNN>-…`), the wire payload uses **two `user` text segments**: first the operator’s own hint, then a separate **“CR branch — paths changed vs develop”** block from `git diff develop...HEAD --name-only`, so agents see the CR’s touched paths without running git themselves. That second block is **operational context** only — **interpret** it; do **not** paste it verbatim into **`## Summary`**, **`## Purpose`**, or titles. **Spec markdown** must still cite dependencies by **typed id** (`RQ-001`, `STORY-003`), not paths (**[`before-changing-spec.md`](before-changing-spec.md)**).
+
+Entry points and their backing prompts:
+
+- `waterfall cr start` → `prompts/commands/cr-start.md`
+- `waterfall sys start` → `prompts/commands/sys-start.md`
+- `waterfall horizontal create …` → mechanical scaffold + **`Draft steering (CLI)`**; patterns in **`horizontal-structure.md`**; refinement checklist **`horizontal-create.md`**
+- `waterfall horizontal update HOR-NNN` → `prompts/commands/horizontal-update.md` (after CLI adds git path lists to the operator hint)
+- `waterfall cr to rq` → `prompts/commands/cr-to-rq.md`
+- `waterfall rq to uc` → `prompts/commands/rq-to-uc.md`
+- `waterfall uc to story` → `prompts/commands/uc-to-story.md`
+- `waterfall uc to test` → `prompts/commands/uc-to-test.md`
+- `waterfall test to story` → `prompts/commands/test-to-story.md`
+- `waterfall story close STORY-NNN` → `prompts/commands/story-close.md`
+- `waterfall story close all` → `prompts/commands/story-close-all.md`
+- `waterfall cr finish` → `prompts/commands/cr-finish.md`
+
+For the `... all` commands, see the **CLI orchestration** section inside the relevant edge prompt.
+
+## CLI wire: prompt delivery (**embed** vs **reference**)
+
+The Waterfall CLI may send the primary command workflow in one of two shapes:
+
+- **Embed (default)** — the workflow markdown body is inlined as a **user** text segment (after operator hint and any CR branch path list). Read **user** top to bottom.
+- **Reference** — the primary workflow is **not** duplicated under **user**; it appears only as a **file** segment in **system** (absolute path under the CLI install). Open that file and follow it; **user** carries hint and scope only.
+
+**Reference mode — paths and links:** Resolve relative links in each markdown file from **that file’s directory**. Global and command prompts live under the CLI install, **outside** the spec workspace; your environment must allow reading those absolute paths. For the Cursor CLI backend, use **sandbox disabled** so those prompt files are readable.
+

package/prompts/items/bug-document-structure.md

@@ -0,0 +1,23 @@
+# BUG document structure
+
+Canonical path: `technical/SYS-<NNN>-<slug>/BUG-<NNN>-<slug>/BUG-<NNN>.md`
+
+## Identity block
+
+1. Title heading like `# BUG-<NNN> — <short defect title>`
+2. One line each:
+   - `**Id:** BUG-<NNN>`
+   - `**SYS:** SYS-<NNN>` (parent subsystem)
+   - `**Status:** <draft|open|in progress|closed|…>`
+
+## Summary
+
+The **Summary** section is the defect narrative: what breaks, how to reproduce, expected vs actual behavior, scope/severity, and links to related **STORY-***, **UC-***, or **TC-*** by **typed id only** (no file paths — see **[`before-changing-spec.md`](../global/before-changing-spec.md)**).
+
+Optional subsections (when useful):
+
+- `### Reproduction`
+- `### Expected vs actual`
+- `### Related work items`
+
+Do **not** leave long-term **Draft steering (CLI)** blocks in finished specs; they are operator scratch input from `waterfall bug start`.

package/prompts/items/cr-document-structure.md

@@ -0,0 +1,45 @@
+# CR document structure — required sections & fields
+
+This guide defines the canonical *markdown shape* of a change request:
+`changerequests/CR-<NNN>-<slug>/CR-<NNN>.md`
+
+## Rule
+
+A CR markdown file is a single human-readable artifact whose identity and lifecycle state are clearly extractable near the top, with the rest of the proposal describing the change.
+
+## Required identity block
+
+Your CR markdown should start with:
+
+1. A title heading like `# CR-<NNN> — <human description>`
+2. Identity fields (present verbatim, one per line):
+   - `**Id:** CR-<NNN>`
+   - `**Status:** draft` (or the current lifecycle status)
+
+   Do **not** add an **Upstream** field or **`### Upstream`** subsection — use **`### Downstream references`** only under **`## Links and dependencies`**. Optional peer or product context belongs in **`## Summary`** as prose citing **typed ids** (`CR-001`), not a separate “upstream” graph.
+
+## Required sections
+
+The following sections should exist (names may vary slightly in subsections, but the anchors/meaning should be stable):
+
+1. `## Summary`
+   - Short, high-signal description of what the CR introduces at the conceptual level.
+2. A “proposal” section (commonly `## Proposed change`)
+   - Break the proposal into subsections (`### ...`) as needed.
+
+3. `## Links and dependencies` (commonly)
+   - Include a `### Downstream references` subsection listing produced artifact **ids** (for CR, usually **`RQ-*`** — see **[`before-changing-spec.md`](../global/before-changing-spec.md)**).
+
+## Allowed and disallowed content (structure guidance)
+
+1. Allowed: detailed proposal and rationale, organized into subsections.
+2. Allowed: links to related typed artifacts by **id** in prose or in **`### Downstream references`** only (no **`### Upstream`**).
+3. Allowed: out-of-scope bullet lists.
+4. Disallowed: mixing in full step-by-step lifecycle edits for later artifact layers. Keep those for the transition prompts.
+
+## Downstream references (required)
+
+Under `## Links and dependencies`, keep a `### Downstream references` list with **one bullet per produced artifact id** (e.g. `- RQ-001`). Prefer **typed ids only** — no path-based markdown links (**[`before-changing-spec.md`](../global/before-changing-spec.md)**).
+
+For CRs, this is where new **`RQ-*`** entries are appended during CR → RQ transitions.
+

package/prompts/items/rq-theme-document-structure.md

@@ -0,0 +1,36 @@
+# RQ theme document structure — required sections & fields
+
+This guide defines the canonical markdown shape of an RQ *theme*:
+`requirements/RQ-<NNN>-<slug>/RQ-<NNN>.md`
+
+## Rule
+
+An RQ theme is the general-purpose “what/why/scope” layer for an RQ. It must be readable and navigable on its own, and link **forward** via **`### Downstream references`** only (no upstream sections).
+
+## Required header identity block
+
+Your `RQ-<NNN>.md` should start with:
+
+1. A title heading like `# RQ-<NNN> — <human description>`
+2. Identity fields (present verbatim, one per line):
+   - `**Id:** RQ-<NNN>`
+   - `**Status:** <...>` (e.g. draft/active)
+   - Optional: `**CR:** CR-<NNN>` — the **change request** this theme belongs to (**typed id only**, not “upstream” wording)
+
+## Required sections
+
+1. `## Summary`
+   - A concise explanation of what the RQ delivers at a thematic level.
+2. `## Links and dependencies`
+   - Must include:
+     - `### Downstream references` list — **one bullet per child id** (**`UC-*`**, **`STORY-*`**, etc.); ids only, no path-based links (**[`before-changing-spec.md`](../global/before-changing-spec.md)**)
+     - `### Other dependencies` if there are non-spec inputs (frameworks, infra, etc.)
+   - Do **not** add **`### Upstream`** — owning **CR** is optional in the identity block or **Summary**, by **id** only.
+3. Optional but common `## In scope` / `## Out of scope`
+   - Explicit inclusions/exclusions that prevent RQ drift.
+
+## Structural constraints
+
+1. No step-by-step user flows: the *flow* narrative lives in UC; the theme stays general and constraint-oriented.
+2. Keep `### Downstream references` current whenever this RQ produces new child artifacts.
+

package/prompts/items/story-document-structure.md

@@ -0,0 +1,49 @@
+# STORY document structure — required sections & fields
+
+This guide defines the canonical markdown shape of a STORY:
+`technical/SYS-<NNN>-<...>/STORY-<NNN>-<slug>/STORY-<NNN>.md`
+
+## Rule
+
+STORY markdown must be a standalone implementation contract for a meaningful slice of work, with its identity, **UC** traceability (**typed id**), and acceptance criteria clearly extractable from the top sections.
+
+**Horizontals:** Where **`HOR-*`** artifacts define the cross-cutting **data model**, **API model**, or **technical stack** for the CR, this STORY **must respect** their **`## Aggregated definitions`** — align entities, fields, types, public contracts, and **named technologies** (frameworks, libraries, runtimes). **Extend** those concepts **only** when this slice needs something **not** already captured; call out extensions in prose (and **`HOR-<NNN>`** by id if helpful). See **[`horizontal-structure.md`](../global/horizontal-structure.md)**.
+
+## Required identity block
+
+Your `STORY-<NNN>.md` should start with:
+
+1. A title heading like `# STORY-<NNN> — <human description>`
+2. Identity fields (present verbatim, one per line):
+   - `**Id:** STORY-<NNN>`
+   - `**SYS:** SYS-<NNN>` (owning technical subsystem)
+   - `**Status:** <draft|closed>` (or the current lifecycle status)
+   - `**UC:** UC-<NNN>` — primary use case this story implements (**typed id only**; do **not** use **`**Upstream:**`**)
+3. Optional: `**Closed:** YYYY-MM-DD — ...` when status is closed
+
+## Required sections
+
+1. `## Goal`
+   - What this STORY implements/updates, in one coherent statement.
+2. `## Data and validation`
+   - **Concrete** structures: entities, fields, types or schema notes; **validity** and invariants; error/edge behaviour for this slice. No hand-waving — enough detail to implement and review. Stay **consistent** with applicable **`HOR-*`** definitions; document any **necessary** extension beyond the horizontal.
+3. `## Technology`
+   - **Named** stack for this slice: runtime, frameworks, APIs/protocols, storage class, major libraries — what implementers actually use. Stay **consistent** with **`technical-stack`** **`HOR-*`** when one exists; document any **necessary** new or differing choice.
+4. `## Acceptance criteria`
+   - Observable criteria that prove completion for this slice; trace to **`UC-<NNN>`** / **`TC-*`** by **id only** (see **[`before-changing-spec.md`](../global/before-changing-spec.md)** — no file paths in prose).
+5. `## Out of scope` (recommended)
+   - What the next STORY should pick up; keeps scope boundaries clean.
+6. Implementation notes (optional)
+   - E.g. `## Implementation notes` for wiring, env flags, or follow-ups — still use **typed ids** for cross-refs, not paths.
+
+## Structural constraints
+
+1. Don’t rewrite full UC behaviour or testcase tables inside STORY — summarize only what this slice implements; point to **`UC-<NNN>`** / **`TC-*`** by id.
+2. When closing a story, the *folder* must be renamed to `_STORY-.../` while the inner filename remains `STORY-<NNN>.md`.
+
+## Downstream references (required)
+
+Inside `## Links and dependencies`, include a `### Downstream references` subsection.
+
+List directly produced follow-up artifacts (**`TST-*`**, follow-up **`STORY-*`** / **`BUG-*`**) as **typed id bullets only**, one-way from this story — **[`before-changing-spec.md`](../global/before-changing-spec.md)**.
+

package/prompts/items/sys-document-structure.md

@@ -0,0 +1,36 @@
+# SYS document structure — required sections & fields
+
+This guide defines the canonical markdown shape of a subsystem:
+`technical/SYS-<NNN>-<slug>/SYS-<NNN>.md`
+
+## Rule
+
+A SYS document defines one technical boundary that groups implementation stories. It should describe **purpose** and a maintained **`### Downstream references`** list of produced stories. Do **not** use **`### Upstream`**.
+
+SYS creation is a manual maintenance action, not a lifecycle chain step. The lifecycle command `uc -> story` can target one or many existing SYS documents, but it does not create SYS entities.
+
+## Required identity block
+
+Your `SYS-<NNN>.md` should start with:
+
+1. A title heading like `# SYS-<NNN> — <human description>`
+2. Identity fields (present verbatim, one per line):
+   - `**Id:** SYS-<NNN>`
+   - `**Status:** <draft|active|closed>`
+
+## Required sections
+
+1. `## Links and dependencies`
+   - Include:
+     - `### Downstream references` — **`STORY-*`** ids produced under this SYS (ids only; **[`before-changing-spec.md`](../global/before-changing-spec.md)**)
+   - Traceability to **CR** / **RQ** / **UC** / other **SYS** belongs here (or in **`## Implementation notes`** if you add it) using **typed ids** — **not** inside **`## Purpose`**.
+2. `## Purpose`
+   - One clear paragraph for subsystem scope and intent in **plain product and technical language**.
+   - **Do not** cite **CR-***, **RQ-***, **UC-***, **SYS-*** (other than this file’s own identity in the title block), **STORY-***, **HOR-***, or **TST-*** in **`## Purpose`** — describe boundaries without artifact ids; readers infer links from **`### Downstream references`** and folder placement.
+
+## Structural constraints
+
+1. Keep SYS focused on technical ownership and boundaries, not detailed acceptance logic.
+2. Put implementation detail in `STORY-<NNN>.md` files under this SYS.
+3. Keep `### Downstream references` current as stories are added/closed/moved.
+