groundwork-method 0.0.1 → 0.11.0

package/src/hidden-skills/groundwork-bet/instructions.md

@@ -0,0 +1,88 @@
+---
+name: groundwork-bet
+description: >
+  Orchestrates the GroundWork bet lifecycle — Discovery, Design Foundations,
+  Decomposition, Delivery, Validation — moving one scoped slice of the product
+  vision from concept to validated delivery. Routes each phase to its workflow
+  file and tracks progress through the pitch's status frontmatter.
+---
+
+# groundwork-bet
+
+You are the orchestrator of the GroundWork bet lifecycle — Discovery, Design Foundations, Decomposition, Delivery, Validation. A bet is one scoped slice of the product vision, moved from concept to validated delivery through five phases that each produce a specific artifact.
+
+Apply the `groundwork-writer` skill when producing any artifact this lifecycle commits. Declarative, assertive, zero-hedging.
+
+---
+
+## Mental Model
+
+Each phase establishes one thing the next phase depends on:
+
+- **Discovery** establishes the *what* and the *why*. It produces the pitch — the problem, the appetite, the solution sketch, the success signal, and the explicit no-gos. Without it, design has nothing to anchor against.
+- **Design Foundations** establishes the *contract*. It produces the technical design — UI design first (one subsection per in-scope surface), then the headless core beneath it: data flows and business logic, API design, and schema & data design, surface-neutral. Without a locked design, decomposition produces milestones and tests that contradict each other.
+- **Decomposition** establishes *the order of work and the proof*. With the design locked, it authors the full **milestone ladder** — thin, user-visible steps ordered to front-load risk, each carrying a headline Proof-of-work proof that **drives the real product through its real front door** (no stub, double, or scripted stand-in can satisfy it; any fake it leans on needs a real test behind it; this is the success signal made executable) — but slices only the **first milestone**; later rungs are sliced on arrival in Delivery, from what the milestones before them taught. Every milestone names a consumer who observes its outcome at their real surface; the first user-visible milestone lands the design system in the running app; the ladder must sum to a complete, well-rounded experience. Every shape traces to the prose API/data design. No test code is written here. The user reviews proof by proof and approves; the approved prose is committed as the recorded baseline, and changing *what a milestone proves* afterwards is an owner-approved amendment recorded in git history with a reason — steering how slices break down is free. The tests are generated red at Delivery start from this approved prose. Without this Proof of Work, delivery has no proof to satisfy and no sequence to follow.
+- **Delivery** materializes the red board from the approved prose, then drives it green as an orchestration. The agent is the *driver* — it holds the thin spine (the board, the milestone order, the granularity the user chose, the triage judgement) and dispatches a fresh slice-worker subagent per slice (`briefs/slice-worker.md`) so the heavy implementation context stays disposable. It reviews each worker's diff through independent lenses, commits the slice, proves each milestone at the front door (folding in the visual checks and a polish pass, with the experience-auditor lens judging the assembled milestone), and at every milestone boundary runs a postmortem that confirms the milestone honestly proved its intent, re-checks the remaining ladder, and authors the next milestone's slices from what this one taught (introducing a new rung when the ladder is missing one, within appetite) — recording each authored rung as it goes, course-correcting through the Amendment Protocol or Change Navigation when an approved proof or the design is wrong, never editing approved prose around without a recorded amendment. Delivery is offered at three cadences — slice by slice, milestone by milestone (default), or whole bet — which set where the driver pauses; hard stops pause regardless. The suite is the board (`./dev bet status`, derived not stored) and each slice's commit is its record, so progress is visible and resumable. As each slice completes, permanent best-practice tests are rolled out, and a per-slice reconciliation checks that the approved prose has not silently moved. Without the Decomposition contract, every design question becomes a mid-implementation conversation made under coding pressure.
+- **Validation** confirms the delivered bet behaves as designed, captures each touched service's served contract into the canonical `docs/architecture/api/` record, writes the bet's capability-ledger rows (when the project keeps a surface registry), archives the **whole bet** (docs and tests), runs the bet retrospective, and folds what the bet learned back into upstream documents for every subsequent bet.
+
+The lifecycle is sequential because each phase's output is the next phase's input. The order is structural, not procedural — gating design before decomposition is not a rule to follow but the only way the artifacts compose.
+
+Each phase runs in its own workflow file because each demands a different mode. Loading only the current phase's workflow keeps the conversation in one mode at a time; mixing modes produces shallow work in all of them.
+
+---
+
+## Lifecycle Overview
+
+| Phase | Workflow | Status | Output |
+|---|---|---|---|
+| 1. Discovery | `workflows/01-discovery.md` | `discovery` | `docs/bets/<slug>/pitch.md` |
+| 2. Design Foundations | `workflows/02-design.md` | `design` | `docs/bets/<slug>/technical-design/` (`01-ui-design.md`, `02-data-flows.md`, `03-api-design.md`, `04-data-design.md`) |
+| 3. Decomposition | `workflows/03-decomposition.md` | `decomposition` | `docs/bets/<slug>/decomposition/` prose tree — full milestone ladder + first milestone sliced, approved and committed as the recorded baseline |
+| 4. Delivery | `workflows/04-delivery.md` (driver) + `briefs/slice-worker.md` (per-slice subagent) | `delivery` | Red board materialized from the approved prose, then driven green milestone by milestone — slice-workers implement, the driver reviews/commits, and at each milestone boundary a postmortem course-corrects and opens the next milestone (authoring and recording its slices); each slice committed as its record |
+| 5. Validation | `workflows/05-validation.md` | `validation` → `delivered` | Canonical `docs/architecture/api/` captured from running code; retrospective; whole bet archived |
+
+The pitch's frontmatter `status` field tracks where the bet sits in the lifecycle. Status transitions on entry to each phase and is the routing signal that lets a fresh context pick up the bet at the right place.
+
+---
+
+## Operating Contract
+
+Standard assistant behaviour — covering too much ground per turn, rushing to draft before the conversation has earned its conclusions, and treating documents as static after committing them — undermines collaborative design. These are the failure modes this process is built to prevent.
+
+The shared operating contract at `.groundwork/skills/operating-contract.md` (contract v1) defines how to manage conversational pacing, discovery notes, living documents, and phase lifecycles. Read it before taking any other action — the protocols there govern how this entire skill operates.
+
+---
+
+## Activation
+
+Check `docs/bets/` for pitches (`<slug>/pitch.md`) and route on the pitch's `status` frontmatter.
+
+`docs/bets/` accumulates one pitch per bet, so several may exist. When the user names a bet — a slug or an unambiguous description — route on that pitch. Otherwise, a single pitch with an active status (anything other than `delivered`) is the bet to pick up; when more than one is active, list the candidates with their statuses and ask the user which to resume. Delivered pitches are the project's history, never resume candidates.
+
+- **`status: discovery`** — the pitch is committed but the bet has not entered Design Foundations. Read the pitch and proceed to Design Foundations.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/02-design.md`
+
+- **`status: design`** — the MVP handoff just completed; discovery is done. Read the pitch and proceed directly to Design Foundations.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/02-design.md`
+
+- **`status: decomposition`** — design is locked; proceed to Decomposition.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/03-decomposition.md`
+
+- **`status: delivery`** — decomposition is done; proceed to Delivery.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/04-delivery.md`
+
+- **`status: validation`** — delivery is done; proceed to Validation.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/05-validation.md`
+
+- **`status: delivered`** — the bet is complete; validation closed it. Tell the user this bet shipped and ask what they want to bet on next — follow-up work is a new bet with its own slug starting at discovery, never a reopened pitch.
+
+- **No pitch / new feature request** — ask the user what feature or problem they want to work on. Ensure the user provides a slug (e.g., `meeting-recording`) to use as the directory name for this bet. Then load and execute discovery.
+
+  ➡️ Read and follow: `.groundwork/skills/groundwork-bet/workflows/01-discovery.md`
+
+If activating in a fresh context against an existing pitch, briefly summarise the pitch's scope so the user can confirm the right bet was picked up before proceeding.

package/src/hidden-skills/groundwork-bet/templates/bet-progress-test.md

@@ -0,0 +1,115 @@
+# Bet-Progress Test Guidance
+
+*This document explains how to write bet-progress tests — the red proof-of-work suite generated at Delivery start from the bet's approved prose decomposition. It is guidance for the agent materializing the stubs, not a runnable test file. The actual test stubs live under `tests/bets/<bet-slug>/`.*
+
+---
+
+## What bet-progress tests are
+
+Bet-progress tests are **temporary, black-box proof-of-work** materialized from the approved prose before any implementation exists. Each one renders the Proof-of-work prose of a milestone or slice — the proof the user already reviewed and approved in the decomposition tree — into a runnable red stub. At Delivery start the board is materialized for the whole **milestone ladder** plus the **first milestone's slices**; each later milestone's slice stubs are added when Delivery opens that milestone (its slices are authored then). So the board shows progress at milestone granularity before the later rungs are sliced. They assert what the milestone's consumer would observe if the feature were complete. Red means the work is not done. Green means it is proven. Running the suite is the bet's live progress board.
+
+**A milestone test drives the real product through its consumer's front door.** It exercises the shipping build the way the milestone's consumer would, on the real pipeline and real data, and asserts what the consumer observes — in their surface's medium:
+- `graphical-ui` — a browser-driven (or platform-driven) test that navigates to the feature and verifies what the user sees on the running app
+- `cli` — a test that invokes the command and verifies the output, exit code, or side-effect
+- `agentic-protocol` — a test that sends a protocol request and verifies the response structure
+
+The milestone test resolves its consumer's surface through the surfaces fixture (slug → entry point). It is the front-door proof: it runs the whole path end to end, not a back-channel against an internal contract with no consumer in the loop. Proving a backend contract directly is real work, but it belongs to a *slice* test, not a milestone test — the milestone proves the consumer's outcome.
+
+Slice tests prove the vertical capability a slice contributes toward its parent milestone, at that slice's service edge. They are **informed by and bounded by** the parent milestone's front-door proof — a slice test proves a specific capability; the milestone test proves the consumer-visible outcome those capabilities enable. A slice that builds a screen proves the screen renders and behaves through the pattern it implements in full.
+
+---
+
+## The target-state principle
+
+Write every test as if the feature already exists. The test describes the desired reality, not the current state. A test that asserts "endpoint returns 501" is not a bet-progress test — it describes the absence of implementation. Assert the presence of the delivered capability.
+
+---
+
+## System-level only
+
+Bet-progress tests hit the running services from the outside. They:
+- Do not import application code
+- Do not mock services or fake data layers
+- Do not depend on implementation details (database schemas, internal module structure)
+
+If a test requires knowledge of an internal module, it is not a bet-progress test — it belongs in the permanent per-service test suite.
+
+---
+
+## File naming convention
+
+All bet-progress tests live under `tests/bets/<bet-slug>/`. The `<bet-slug>` is the kebab-case slug of the bet (the `docs/bets/<bet-slug>/` directory name).
+
+**Milestone test files:**
+```
+tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>
+```
+Where `<N>` is the milestone number (1, 2, 3...), `<milestone-slug>` is the kebab-case milestone name, and `<ext>` is the project's test language extension (`.py`, `.go`, `.ts`) — discovered from the scaffold, never assumed.
+
+**Slice test files:**
+```
+tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>
+```
+Where `<N>` is the slice number within the milestone, `<service>` is the owning service name (from `docs/architecture/infrastructure.md`), and `<slice-slug>` is the kebab-case slice name.
+
+**Archive path (Phase 5 — after delivery):**
+```
+tests/bets/_archive/<bet-slug>/
+```
+
+---
+
+## Fixtures and service discovery
+
+Bet-progress tests reuse the shared fixtures from `tests/conftest.py`:
+- `cluster` — boots and health-checks all services; provides the running topology
+- `api_client` — an HTTP client configured with the discovered service base URLs; slice tests use this to exercise a service edge directly
+- `pure_state_reset` — truncates all service data stores before each test (autouse)
+- `surfaces` — the mapping from registry slug to that surface's entry point (base URL for a web surface, binary path for a CLI, protocol endpoint for an agentic surface); milestone front-door tests resolve their consumer's surface here
+- `frontend_base_url` — the legacy alias for the single graphical surface's base URL; present when exactly one graphical surface exists, for suites written before the surfaces fixture
+
+Declare the fixtures you need as test-function parameters; pytest resolves them from the parent conftest automatically.
+
+For a front-door test against a `graphical-ui` surface, the `page` fixture (from pytest-playwright) drives a real browser. For `cli` surfaces, use `subprocess` or `pexpect` to invoke the binary directly.
+
+## Capturing screenshots for the visual verification loop
+
+For `graphical-ui` interface tests, capture a screenshot of each key state of the screen under test — default, hover, focus, empty, loading, error — written to `.groundwork/cache/visual/<bet-slug>/<surface>/<state>.png` (create the directory first). These are the states where "renders broken" and "looks unfinished" both live, and the captures are what the delivery agent reads (Tier 2 inspection) and the experience-auditor review judges at milestone close and over the whole bet. Capture after the state is reached and assertions pass — the screenshot records the proven state, it does not replace the assertion. Capture nothing for `cli` and `agentic-protocol` surfaces; their observable output is text, asserted directly.
+
+**What capture sees, and what it does not.** A static screenshot verifies render correctness, coherence, and composition. It does *not* see motion (easing, durations, press physics) or perceived latency — both committed in the design system — so those stay behaviour-tested, asserted on timing and state, never on a frame. Do not treat a captured screen as proof of an animation or a latency budget.
+
+**Declare the routes the bet touched.** The permanent route-driven gates (render-smoke, geometry, visual-regression) sweep the screens listed in `tests/system/routes.json` (a JSON array of paths), defaulting to the app root when absent. When a bet adds or changes a `graphical-ui` route, add it to that manifest so the permanent suite covers it — the same promotion shape as the bet's other best-practice tests.
+
+---
+
+## Placeholder structure for red tests
+
+When the implementation does not exist yet, a test stub must be **explicitly red** — it must fail, not skip. Use the pattern appropriate to the test language:
+
+- Python: `pytest.fail("bet-progress test not yet implemented — <describe target state>")`
+- Go: `t.Fatal("bet-progress test not yet implemented — <describe target state>")`
+- TypeScript: `throw new Error("bet-progress test not yet implemented — <describe target state>")`
+
+Comment the stub with what it will eventually assert, so the Delivery agent knows exactly what to implement. For a milestone stub, name the consumer's front-door outcome:
+```
+# Front door (<consumer> via <surface>): [what the consumer observes when they drive the real product — the action, what they see, on real data]
+```
+For a slice stub, name the capability at its service edge:
+```
+# Slice capability: [the behaviour at this slice's edge the milestone's front-door proof builds on]
+```
+
+---
+
+## What makes a good bet-progress test
+
+A bet-progress test is good when:
+- It asserts a **falsifiable, consumer-visible outcome** — what the consumer observes at their front door, never an internal state
+- It would fail if the feature shipped incomplete
+- For a **milestone headline**, it **drives the real product through the real front door** — the consumer's action runs the shipping build on the real pipeline and real data, so a stub, mock, scripted driver, or hardcoded return cannot turn it green. A milestone proof a double can satisfy proves plumbing, not the milestone (`workflows/03-decomposition.md`). Seeded inputs are fine; faking the work in the middle is not
+- **Any fake it leans on has a real test behind it** — if the proof uses a fixture for work a real stage should do, another test exercises the real producer; a fixture nothing real ever generates is a green light wired to nothing (`docs/principles/foundations/testing.md`)
+- It would pass without any special knowledge of how the feature is implemented internally
+- It is a **headline proof, not a permutation** — it proves the milestone's outcome or the slice's capability, not every input variant or error code
+- A reviewer can read it and confirm it matches the milestone's acceptance criteria and Proof-of-work prose in its `decomposition/NN-<milestone-slug>/index.md`
+
+**Keep the suite lean.** Bet-progress tests render the high-impact proofs the user reviewed and signed as prose — a milestone's consumer-visible outcome and each slice's vertical capability, typically one to three assertions apiece. If an assertion is an edge case, a permutation, or an error variant rather than the headline outcome, it does not belong here; it is part of the slice's permanent best-practice tests, written when the slice is built in Delivery (`workflows/04-delivery.md`, the Slice Loop). A wall of assertions is unreviewable upstream and front-loads coverage the delivery suite is meant to carry.

package/src/hidden-skills/groundwork-bet/templates/change-proposal.md

@@ -0,0 +1,38 @@
+# Change Proposal [N]: [Bet Name]
+
+*Written when mid-delivery reality contradicts the locked design. The proposal is the decision record the user approves before any locked artifact moves — and the audit trail Validation's retrospective reads afterward.*
+
+**Severity:** [minor — contracts and milestones survive; specific tests/design sections need correction | structural — a contract, milestone, or the appetite is wrong]
+
+---
+
+## Discovery
+
+[What implementation revealed, stated as evidence — the failing behaviour, the incompatible dependency, the contract that cannot be satisfied. Quote the error, the doc, or the code that proves it.]
+
+## Impact
+
+| Artifact | Affected section | Why |
+|---|---|---|
+| `pitch.md` | [section or none] | [how the discovery touches it] |
+| `technical-design/` | [section file — `01-ui-design.md` / `02-data-flows.md` / `03-api-design.md` (shapes) / `04-data-design.md`] | |
+| `decomposition/` | [milestone `index.md` / slice file] | |
+| Built artifacts | [test stub(s) under `tests/bets/<slug>/`, the served contract] | |
+
+## Proposed changes
+
+*(One entry per edit. Before/after, not descriptions of edits.)*
+
+### [artifact → section]
+
+**Before:**
+> [current text / spec fragment / assertion]
+
+**After:**
+> [proposed text / spec fragment / assertion]
+
+**Rationale:** [why this is the right correction, in one or two sentences]
+
+## Routing
+
+[Minor: edits applied on approval, mutated docs re-reviewed, affected proofs amended through the Amendment Protocol (edit the slice/milestone prose, commit it beside the decomposition with a reason, then change the code), slice resumed. Structural: bet reverts to Design Foundations with this proposal as input; delivered slices that survive the change are listed here.]

package/src/hidden-skills/groundwork-bet/templates/decomposition/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Decomposition",
+  "pages": ["..."]
+}

package/src/hidden-skills/groundwork-bet/templates/decomposition/milestone-index.md

@@ -0,0 +1,31 @@
+# Milestone [N]: [Milestone Name]
+
+*This is the landing page for one milestone in the decomposition tree. It renders to `docs/bets/<bet-slug>/decomposition/NN-<milestone-slug>/index.md`. It carries the milestone's demonstrable goal, its sequencing rationale, its acceptance criteria (the agreed front-door cases), and the prose proof of work — then links to its slices. The slice files sit beside it in the same folder.*
+
+**Consumer:** [who observes this milestone's outcome at their real surface — a person at a screen, a developer calling an SDK, an operator reading a dashboard, another system calling the API. Name them and what they see. A pure-API product's consumer is the caller and its surface is the API.]
+
+**Demonstrable goal:** [the thin, user-visible state the product reaches when this milestone is complete — what the consumer observes when they drive the real product, in their surface's medium, on real data. For the first user-visible milestone, this includes the design system landing in the running app.]
+
+**Sequencing rationale:** [why this milestone sits where it does — what it proves through the bet's riskiest real path, why the milestones after it build on the state it reaches.]
+
+**Acceptance criteria (agreed front-door cases):**
+- [ ] [specific, falsifiable case the consumer can carry out on the real product — the integrity anchor the user signs at planning]
+- [ ] [specific, falsifiable case]
+
+## Proof of work
+
+*The prose proof the user reviews and approves. This is the milestone's definition of done in plain language — what the consumer observes when they drive the real product, and how the suite proves it through the real front door. No assertion code; the runnable stub is generated from this prose at Delivery start.*
+
+**Proves:** [the consumer-visible outcome this milestone reaches, in one or two sentences. State what the consumer observes on the real product, not how a test is written.]
+
+**How we prove it:** [the shape of the proof in prose — the consumer's action driving the shipping build end to end, on the real pipeline and real data, and the observable condition it passes on. A reader should understand the proof without seeing any code. Seeded inputs are fine; a scripted stand-in for the real work is not. Name any fake the proof leans on and the real test that proves the real producer behind it.]
+
+**Test file:** `tests/bets/<bet-slug>/test_milestone_<N>_<milestone-slug>.<ext>` — generated red at Delivery start; drives the consumer's surface in `01-ui-design.md` over the interfaces in `technical-design/03-api-design.md` (and stores in `04-data-design.md`) the outcome rests on.
+
+## Slices
+
+*The first milestone is sliced now, at decomposition; every later milestone is sliced when Delivery opens it (`workflows/04-delivery.md`), from what the milestones before it taught. Until a milestone is opened, leave the placeholder line below; once it is sliced, replace it with ordered links — each slice a vertical cut through one service that builds toward this milestone's front-door proof.*
+
+> *Slices authored on arrival.*
+
+- [Slice [N.1]: [Slice Name]](./NN-<slice-slug>.md)

package/src/hidden-skills/groundwork-bet/templates/decomposition/slice.md

@@ -0,0 +1,31 @@
+# Slice [N.M] — [service]: [Slice Name]
+
+*One vertical slice of a milestone. Renders to `docs/bets/<bet-slug>/decomposition/NN-<milestone-slug>/NN-<slice-slug>.md`. It states the slice's scope, ties it to the design, and carries the prose proof of work the user approves. The slice is a vertical cut through one service — it can be deployed and verified without any future slice existing — and it builds on the proven state of the slice before it.*
+
+**Owner service:** [service name from `docs/architecture/infrastructure.md`]
+
+**Complexity:** S / M / L
+
+**Prerequisite:** (none, or "Slice [N.K] merged")
+
+## Scope
+
+[One paragraph linking this slice to its milestone — what vertical capability it contributes and how that capability moves the milestone toward its front-door proof.]
+
+**Required Capabilities:**
+- [Falsifiable capability statement tracing to an interface in `technical-design/03-api-design.md` or a store in `technical-design/04-data-design.md`. "The endpoint exists" is not falsifiable; "POST `/api/sessions` returns 201 with a `session_id` field when given a valid request body matching the API design" is.]
+- [Falsifiable capability statement]
+
+## Design
+
+[Where this slice lands in the design. Name the interface it implements in `technical-design/03-api-design.md` or the store it touches in `technical-design/04-data-design.md`, the data flow it realizes in `technical-design/02-data-flows.md`, and — when it builds a screen — the view in `technical-design/01-ui-design.md` it wires and the best-in-class pattern it implements in full. The shapes the slice builds against live in that prose design at design fidelity; this slice does not restate them.]
+
+## Proof of work
+
+*The prose proof the user reviews and approves — this slice's definition of done in plain language. No assertion code; the runnable stub is generated from this prose at Delivery start.*
+
+**Proves:** [the vertical capability this slice contributes, in one plain-language sentence — what it makes true that the milestone depends on.]
+
+**How we prove it:** [the proof case in prose — the request or interaction exercised and the observable condition it passes on. A slice proves the behaviour at its service edge; when it builds a screen, it proves the screen renders and behaves through the pattern it implements in full.]
+
+**Test file:** `tests/bets/<bet-slug>/test_slice_<N>_<service>_<slice-slug>.<ext>` — generated red at Delivery start; traces to [the interface, channel, or schema table in `technical-design/` it rests on].

package/src/hidden-skills/groundwork-bet/templates/pitch.md

@@ -0,0 +1,45 @@
+---
+status: discovery
+surfaces: [<registry-slug>, <registry-slug>]
+---
+
+# Bet: [Feature Name]
+
+*`surfaces:` lists the registry slugs (from `docs/surfaces.md`) this bet delivers to — validation fills the capability ledger from this scope. When the project has no surface registry, omit the key entirely: the bet runs against the single implicit surface, exactly as before the registry existed. A single-surface registry means one entry and nothing more.*
+
+## The Pitch
+*Provide a brief explanation of the problem, the proposed solution, the appetite, and the stakes.*
+
+- **Problem:** What user problem are we solving?
+- **Appetite:** How much is solving this worth — judged by opportunity cost, what else this cycle could hold? State worth, not an effort estimate. (Express in calendar time only when human-coordination time is the real constraint.)
+- **Stakes:** What is at risk if we get this wrong — blast radius (surface touched, who feels it), reversibility (one-way door or iterate-behind-a-flag), and review load (how much a human must hold to vouch for it)? Stakes earns the rigour; it is not effort.
+- **Solution:** At a high level, how will we solve this?
+- **Success Signal:** What observable outcome confirms this bet delivered its intended value?
+
+### Topology
+
+*A `graph` of the services and components this bet touches and how they connect — the picture that frames the solution at a glance. Renders on GitHub and the docs site. Leave the placeholder below at discovery; the design phase fills it in once the actual shape is known (`workflows/02-design.md` updates it as a living document), so a reader of the pitch always sees the system the bet plays in.*
+
+```mermaid
+graph TD
+  A[Surface / caller] --> B[Service this bet touches]
+  B --> C[(Store)]
+  B --> D[Downstream service]
+```
+
+## Rabbit Holes & No-Gos
+*Two distinct lists. Rabbit holes protect the appetite from technical surprise; no-gos protect it from scope creep.*
+
+**Rabbit Holes** — the technical traps or unknowns that could silently eat the appetite. Name where the work could balloon, and the guard or spike that keeps it bounded. Skip only if the bet is genuinely low-risk technically — and say so if it is.
+
+- [ ] Risk: <what could balloon> — Guard: <the spike, cap, or decision that bounds it>
+
+**No-Gos** — the things we are explicitly NOT doing, to prevent scope creep. Include natural extensions users would expect but are excluded — "users will expect X, but we are not doing X because…" — so reviewers do not raise them as gaps.
+
+- [ ] Out of scope item 1 — why it is excluded
+- [ ] Out of scope item 2 — why it is excluded
+
+**Surface no-gos** — when the registry holds surfaces beyond this bet's `surfaces:` scope, name each surface the capability will not reach in this bet, with its disposition: **deferred** (will reach it later — state the intent) or **omitted** (deliberately never — state the rationale). Validation writes these dispositions into the capability ledger; a surface left unstated here becomes an empty ledger cell the bet cannot close with. Skip this list when the registry holds one surface or the project has no registry.
+
+- [ ] Surface `<slug>` — deferred: <what brings the capability there, and roughly when>
+- [ ] Surface `<slug>` — omitted: <why this capability deliberately never ships here>

package/src/hidden-skills/groundwork-bet/templates/technical-design/01-ui-design.md

@@ -0,0 +1,51 @@
+## UI Design
+
+*The user-facing design of each surface this bet delivers to — what the user sees, the states it must cover, and how they interact. One subsection per surface in the pitch's `surfaces:` scope, written in the vocabulary of the surface's interface type (from its design track in `docs/design-system.md`):*
+- *`graphical-ui` — screens, views, regions, states (loading, active, empty, error, degraded), with a wireframe per key view*
+- *`cli` — commands, flags, output format, error messages, exit codes (no wireframe — the output sketch stands in)*
+- *`agentic-protocol` — request/response turns, protocol states, expected response structure (no wireframe)*
+
+*Organize each subsection by view, command, or interaction — not by feature or service. Each subsection is the anchor that surface's milestone interface-tests will assert against.*
+
+*When the project has no surface registry (`docs/surfaces.md` absent), the product has a single implicit surface: write one subsection for it in the project's interface medium and skip all other surface ceremony. A single-surface registry likewise produces exactly one subsection.*
+
+### Surface: [surface-slug]
+
+#### [View / Command / Interaction Name]
+
+**Purpose:** [what this interaction accomplishes for the user]
+
+**Wireframe** *(graphical-ui only):*
+
+*An ASCII sketch of the view's layout — the regions, their arrangement, and the key controls. Low-fidelity on purpose: it fixes structure and hierarchy, not pixels. One sketch per key view; annotate the notable states inline or sketch a second frame when a state changes the layout materially (empty vs populated, error). The ASCII is the source of truth and is always present — a reader and an agent both build the layout from it.*
+
+```
+┌─ [View title] ──────────────────┐
+│ [region / control]      [action]│
+├─────────────────────────────────┤
+│ [primary content area]          │
+│                                  │
+│ [secondary panel or list]       │
+└─────────────────────────────────┘
+```
+
+*Optional — when a real mockup exists:* `![<view> — <state>](./wireframes/<surface>-<view>.png)`. *A linked or embedded design image supplements the ASCII; it never replaces it (an image is not diffable and an agent cannot read layout intent from it).*
+
+**States:**
+
+| State | Trigger | What the user observes |
+|-------|---------|------------------------|
+| [state name] | [what causes this state] | [what the user sees, reads, or receives] |
+| [state name] | [what causes this state] | [what the user sees, reads, or receives] |
+
+**Key interactions:**
+- [user action] → [system response and any state transition]
+- [user action] → [system response]
+
+**Micro-polish spec** *(graphical-ui only — token-traceable, not adjectives):*
+- *Motion:* [the motion profile or `{duration, easing, transform}` per interaction/state transition — `hover`, `press`, `enter`/`exit`, `stagger`]
+- *Atmosphere / material:* [surface treatment token — `surface-glass`/`surface-elevated`/`surface-hero`, or an explicit blur/tint/border/elevation/gradient composition — plus any glow or grain]
+- *Static micro:* [elevation token (`shadow-low/mid/high`), spacing steps, type roles with line-height/tracking, colour roles, optical-alignment and crisp-rendering obligations]
+
+---
+*(Add a view/command/interaction block for each significant interaction this bet introduces on this surface; add a `### Surface:` subsection for each in-scope surface)*

package/src/hidden-skills/groundwork-bet/templates/technical-design/02-data-flows.md

@@ -0,0 +1,36 @@
+## Data Flows & Business Logic
+
+*How the bet actually works: how data moves through the system, the business logic that governs it, and the routing decisions along the way. The service topology this bet plays in lives in the pitch's Solution — this file does not redraw it; it details how data flows across it. This is the most valuable file in the directory for a reader who knows the product but not this bet — it is where timing, ordering, service boundaries, and failure handling become legible.*
+
+*Diagram-heavy by design. Every non-trivial flow carries a `sequenceDiagram` (these render on GitHub and the Fumadocs site) — prose alone cannot make ordering and cross-service timing legible. Skip trivial CRUD; a flow with no non-obvious timing, ordering, routing, or failure mode does not belong here.*
+
+---
+
+### [Flow Name]
+
+**Trigger:** [what initiates this flow — a user action, a scheduled job, an upstream event]
+
+**What persists:** [what is written and where, at the end of this flow]
+
+**Business logic & routing:** [the rules that govern this flow — validation, branching, the routing/decision points (which path a request takes and why), idempotency, and any cross-service or API-to-API calls it makes. State the decisions, not just the path.]
+
+**Key decisions:** [the design choices that shape this flow and why — sync vs async, cache strategy, fallback behaviour, consistency model]
+
+```mermaid
+sequenceDiagram
+  participant Caller
+  participant ServiceA
+  participant ServiceB
+  participant Store
+  Caller->>ServiceA: request
+  ServiceA->>ServiceB: downstream call (API-to-API)
+  ServiceB-->>ServiceA: result
+  ServiceA->>Store: write
+  Store-->>ServiceA: ack
+  ServiceA-->>Caller: response
+```
+
+*Where a flow's logic is a branch or decision rather than a sequence, a `flowchart` is the right diagram — show the routing decision and each path's outcome.*
+
+---
+*(Add a `### [Flow Name]` block with its own diagram for each significant, non-trivial data path or piece of business logic in the bet.)*

package/src/hidden-skills/groundwork-bet/templates/technical-design/03-api-design.md

@@ -0,0 +1,90 @@
+## API Design
+
+*The interfaces the bet introduces or changes — the contract beneath the surfaces, designed surface-neutral. The contract here serves every in-scope surface and presumes none; when only one surface is in scope, the latent agentic surface stands in as the second consumer: would a programmatic caller find this contract complete? The flows that exercise these interfaces live in `02-data-flows.md`; this file carries the interface design.*
+
+*Each entry is a design commitment, and it carries the shapes at design fidelity: the full request shape with field types, the full response shape with field types, the error cases with caller guidance, and the design rationale for non-obvious choices. The prose is the contract — Decomposition writes its prose proofs against these shapes, and Delivery implements against them and generates the real machine-readable contract (OpenAPI/AsyncAPI/proto) from the running code. A field, flow, or error case that is not specified here will not be correctly implemented or tested.*
+
+*Single-app or embedded-core bets:* *the "interface" may be a module's public API or a key component boundary rather than a network endpoint — the contract discipline is identical (purpose, full signature, errors, rationale). For a single app with no cross-service API, focus this file on the key component interfaces the rest of the app depends on; if the bet introduces no meaningful interface boundary, say so in one line rather than padding it.*
+
+#### [Service / Component / Boundary Name]
+
+**`METHOD /path`** *(or the function/method signature for an embedded core)*
+
+**Purpose:** [what this interface does and why it exists as a distinct boundary]
+
+**Request:**
+```
+[full request shape — headers, params, body fields, each with its type, nullability, and allowed values where they matter]
+```
+
+**Response:**
+```
+[full response shape — every field with its type; enums spelled out; cursors and identifiers typed]
+```
+
+**Errors:**
+- `4xx [reason]` — [when this fires and what the caller should do]
+- `5xx [reason]` — [when this fires]
+
+**Design rationale:** [key decisions — why this shape, why this boundary, tradeoffs accepted]
+
+---
+*(Add an entry for each interface introduced or changed by this bet)*
+
+#### Quality standard for an API design entry
+
+*The contract is a commitment, not an outline. Every entry must carry its full shapes with field types — specific enough that a developer implements from it without asking for clarification, and Delivery's generated contract matches it exactly.*
+
+**Shallow (insufficient):**
+
+```markdown
+#### Notification Service
+
+**`GET /api/notifications`**
+- Returns list of notifications for the authenticated user
+- Requires auth token
+
+**`POST /api/notifications/mark-read`**
+- Marks notifications as read
+```
+
+**Deep (required standard):**
+
+```markdown
+#### Notification Service
+
+**`GET /api/notifications`**
+
+**Purpose:** Returns unread notifications for the authenticated user, ordered newest-first.
+Used by the UI on initial load and by the polling fallback when the websocket is unavailable.
+
+**Request:**
+```
+Authorization: Bearer <token>   — required
+?limit: integer                 — max results (default 20, max 100)
+?before_id: uuid                — cursor; returns notifications older than this id
+```
+
+**Response:**
+```
+notifications: Notification[]
+  id: uuid
+  operation_id: uuid            — links to the triggering operation
+  operation_type: enum(export, import, sync)
+  status: enum(in_progress, completed, failed)
+  message: string               — human-readable current state description
+  created_at: timestamp
+  read_at: timestamp | null     — null if unread
+has_more: boolean               — true if older notifications exist past this page
+```
+
+**Errors:**
+- `401 Unauthorized` — missing or expired token; caller should redirect to login
+- `429 Too Many Requests` — polling interval too short; caller must back off to 10s
+
+**Design rationale:** Cursor-based pagination (`before_id`) rather than offset because
+the feed changes frequently — offset pagination skips or duplicates items as new
+notifications arrive between pages.
+```
+
+The shallow version has no purpose, no shapes, no error cases, and no design rationale — it cannot drive a correct first-pass implementation. The deep version gives a developer everything needed to implement the interface correctly, and the field shapes are right here in the design rather than deferred to a separate spec file.

package/src/hidden-skills/groundwork-bet/templates/technical-design/04-data-design.md

@@ -0,0 +1,29 @@
+## Schema & Data Design
+
+*How this bet models and stores its data: the tables, collections, or stores it introduces or changes, the key fields with their types, and the lifecycle states for anything with a state machine. State the intent and the shape — why the data is modelled this way and what the fields are. The prose is the design commitment; Delivery derives the migration from it. Reference `docs/architecture/domain/` for canonical entity definitions rather than duplicating them; note the domain entity path and describe only what this bet adds or changes.*
+
+#### [Entity or Store Name]
+
+**Owned by:** [service that owns this store]
+
+**Purpose:** [what this store holds and why it is modelled as its own table/collection — the design decision, not a restatement of the fields]
+
+**Key fields:**
+| Field | Type | Description |
+|-------|------|-------------|
+| [field] | [type] | [what it represents] |
+
+**Lifecycle states** (if applicable):
+
+| State | Meaning | Transitions to |
+|-------|---------|----------------|
+| [state] | [what this state means] | [next states and triggers] |
+
+**Design rationale:** [non-obvious modelling choices — normalisation vs embedding, why this index, why this key, consistency boundary]
+
+**Domain reference:** `docs/architecture/domain/<entity>.md` — [what this bet adds beyond what is already documented]
+
+**Key fields and constraints** carry their types, nullability, defaults, and the indexes that encode design intent, so Delivery derives the migration straight from this section — the prose is the schema commitment, not a separate DDL file.
+
+---
+*(Add a block for each entity or store introduced or significantly changed by this bet)*