specpipe 1.0.0

package/templates/skills/sp-scaffold/references/ARCHITECTURE.md.tmpl

@@ -0,0 +1,228 @@
+# Architecture — <System Name>
+
+<!--
+WHAT THIS FILE IS: the source of truth for the system's *shape* — its boundaries,
+invariants, and the few decisions that are expensive to reverse. It is a map, not an
+atlas: bird's-eye view + named entities, NOT API docs and NOT how-it-works walkthroughs.
+It stays current as the system grows (matklad's ARCHITECTURE.md discipline).
+
+WHERE OTHER THINGS LIVE (do not duplicate them here):
+- WHY each major choice was made → §12 ADRs (or docs/adr/ if they grow).
+- Per-feature behaviour contract (Given/When/Then) → docs/specs/<feature>/<feature>.md
+- Discovery / alternatives / scale rationale → docs/explore/<feature>.md (if used)
+
+FILL RULE: replace every <placeholder>. Delete any section that genuinely does not apply
+to this app-type (e.g. §10 for a system with no async work) — but say so in §2 non-goals
+rather than leaving an empty heading. Keep prose tight; this is a map, not a novel.
+-->
+
+> Handoff-grade design doc. Source of truth for the system *shape*. Deep rationale lives in `docs/explore/`; the behaviour contract in `docs/specs/`.
+
+## 1. Overview & primary quality goal
+
+<!-- 2-3 sentences: what the system does, for whom. Then name the ONE quality goal that
+dominates design (correctness-under-concurrency / latency / data-integrity / security /
+availability). Everything else is secondary — say so. This goal justifies the hard calls below. -->
+
+<one-paragraph what + who>
+
+**Primary quality goal:** *<the one property that dominates>* — <why it dominates, in one sentence>.
+
+## 2. Scope & non-goals
+
+**In scope:** <bullet or sentence list of what ships>
+
+**Non-goals (deliberate):**
+- <thing not built> — <one-line why deferred / out of brief>
+
+## 3. System context (C4 L1)
+
+<!-- Who/what is OUTSIDE the system and how they talk to it. One box = this system;
+the rest are users + external parties. Keep external dependencies as external boxes so
+they stay swappable. -->
+
+```mermaid
+flowchart LR
+  user([<actor>])
+  sys[<This system>]
+  ext[[<External party / 3rd-party service>]]
+  user --> sys
+  sys --> ext
+```
+
+## 4. Container / component view (C4 L2)
+
+<!-- The deployable/runnable units inside the system (frontend, API, worker, DB, cache,
+queue) and the data/control flow between them. A "container" is a runnable unit or a
+datastore — NOT a Docker container specifically. State the ONE boundary rule that must
+never be crossed (e.g. "DB is the single source of truth; cache is transport only"). -->
+
+```mermaid
+flowchart TB
+  subgraph A[<unit>]
+    a[<component>]
+  end
+  store[(<datastore>)]
+  a --> store
+```
+
+**Boundary rule (non-negotiable):** <the one architectural boundary that must hold — what owns truth, what is allowed to talk to what>.
+
+**Codemap — organizing principle + where things live**
+
+<!-- matklad's codemap: LEAD WITH THE PRINCIPLE (stable), then an illustrative tree.
+The PRINCIPLE is language-agnostic; the NAMES and the physical MECHANISM (folders vs
+packages vs targets vs crates) vary by stack — adapt them, never copy one stack's tree
+blindly. Keep this bird's-eye. sp-build reads THIS to decide where new code/tests go. -->
+
+**Two layers under ONE root, as siblings — the split IS the architecture; the names are the project's.**
+
+- **Core layer — reusable foundation, feature-independent.** The wrapper/plumbing every feature reuses: entrypoint/bootstrap, config & env, IO/filesystem/request plumbing, DI, error handling, logging, shared utils + base types. Changes shape rarely; nothing business-specific lives here.
+- **Feature layer — business logic + the scaling axis.** One self-contained unit per capability; grow the app by ADDING a feature, never by editing core. This is the vertical slice a story builds.
+
+Both live under the **same root, discoverable as siblings.** Do NOT scatter them into disconnected top-level trees, and do NOT bury the real code several levels deep inside a wrapper dir. (Anti-pattern seen in the wild: a `core/` package sitting next to a separate `app/` tree with the actual code at `core/Sources/<Pkg>/...` — that is two disconnected trees, not core+feature siblings.) The *mechanism* maps the two layers onto whatever the stack's unit of modularity is:
+
+- **JS/TS:** `core/` + `features/` (or `modules/`) directories at root.
+- **Swift/SPM:** one `Package.swift` at root; a `Core` target + per-feature targets under `Sources/`; the app/GUI target in the **same** package (or an Xcode project at root that depends on it) — never a buried `core/` sub-package beside a disconnected `app/` tree.
+- **Go:** a `core`/`internal` package + per-feature packages. **Rust:** a core crate/module + feature modules. **C#/Java:** a Core project + feature projects in one solution.
+
+Architecture layers (domain / use-case / infrastructure — Clean Architecture) are ORTHOGONAL and optional: they live *inside* core and *inside* each feature; they are NOT the top-level split.
+
+```
+<root>/                  # illustrative (JS names) — map to your stack's mechanism
+├── core/                # reusable foundation: bootstrap, config, IO plumbing, DI, errors, shared utils
+├── features/            # one unit per capability (the scale axis) — add here, don't edit core
+│   └── <capability>/    # its own logic + types (tests per the test-layout rule below)
+└── <tests/integration>  # cross-feature / real-dependency tests
+```
+
+**Test layout — one rule per tier, decided once and enforced.** The structure leaks when the convention is implicit. Unit tests live as close to the code as the language idiomatically allows; each higher tier moves one step outward into its own dir + own runner:
+
+- **Unit / component → co-located.** JS/TS: sibling `foo.ts` → `foo.test.ts` (flat sibling, not `__tests__/`). Go: `foo_test.go` same package. Rust: `#[cfg(test)] mod tests` inline. Mocked deps; logic decidable without external state.
+- **Integration → a separate dir INSIDE the package** (`tests/integration/`, or tag `*.int.test.ts` if sharing a dir). Real deps, NOT mocked, its own task.
+- **e2e → a separate top-level dir / package** with its own runner + config — never in the unit runner's `include`. Monorepo: its own package (`e2e/`).
+- **Naming: ONE suffix repo-wide** — `.test.*` for unit + integration; reserve a distinct tag for e2e (`.e2e.test.*` / `.e2e-spec.*`) so runners select disjoint sets by glob. NEVER mix `.spec` and `.test`.
+- **Monorepo:** package-private tests in each package; cross-package e2e its own package; shared fixtures/config in one `test-utils`/`test-config` package, not duplicated.
+- **Ecosystem escape hatch (general rule: tests go where the language idiomatically puts them — don't impose the JS `__tests__/` / `.test.` shape on other stacks):** Python → src-layout (`src/pkg/` + top-level `tests/` mirror, `test_*.py`, `conftest.py`); Java/Maven → `src/test` mirror; **Swift/SPM → `Tests/<Target>Tests/` mirror (`swift test`), not co-located siblings**; Go/Rust → the language rule above IS the layout (inline / `tests/` for Rust integration). When unsure, follow what the stack's official scaffolder/test runner expects.
+
+**The split rule (correctness, not bookkeeping):** which tier a test belongs to is decided by *what its correctness depends on*. A test whose correctness IS the integration — SQL-level guarantees (conditional updates, unique constraints, locking); cross-surface data flow where one surface writes and another reads (test the seam, incl. write-twice / out-of-order); idempotency / exactly-once across endpoints; transactions — MUST be a real-dependency test. Mocking the thing under test there yields a vacuous test that passes while the real behaviour is broken.
+
+## 5. Data model
+
+<!-- Entities, key fields, and the structural guarantees the storage layer enforces
+(unique indexes, constraints, FKs). Note WHICH field is the guard for any contended state.
+Schema/migration detail belongs here, never in a spec's acceptance scenarios. -->
+
+| Entity | Key fields | Notes |
+|---|---|---|
+| `<entity>` | `<fields>` | <invariants this entity carries> |
+
+**Structural guarantees (enforced by the store, not just app code):**
+- <unique index / constraint / FK and the invariant it protects>
+
+## 6. Core flows & state machines
+
+<!-- The 1-3 flows that carry the primary quality goal. Use a state diagram for any entity
+with a lifecycle, a sequence diagram for any multi-actor flow (request → queue → worker → store).
+Call out the guarded write: a state change that is allowed ONLY when a guard condition held. -->
+
+```mermaid
+stateDiagram-v2
+  [*] --> <state>
+  <state> --> <state>: <transition + guard>
+```
+
+<short prose for each core flow; name the guarded transitions>
+
+## 7. Invariants & correctness *(non-negotiable)*
+
+<!-- THE most important section (matklad). List the properties that must ALWAYS hold,
+across EVERY code path that could violate them — not just the path where they were first
+conceived. Express as absences where possible ("never two confirmed reservations per seat",
+"money never moves without a traceable record", "a request retried twice causes one effect").
+
+CONVERGENCE WITH SPECS: each invariant here SHOULD become an `INV-NNN` in the feature spec,
+with an `applies-to:` list naming every endpoint/surface that can break it — so the build
+tests it at every surface, not only the obvious one. An invariant tested at one surface and
+not another is the classic cross-surface bug (e.g. idempotency enforced on the webhook but
+not on the separate intent-creation endpoint). State the mechanism that enforces each one. -->
+
+- **INV-1 · <name>:** <the property> — enforced by <mechanism>; applies to <surfaces>.
+- **INV-2 · <name>:** <…>
+
+## 8. API / interface contracts
+
+<!-- The system's boundary surface: HTTP endpoints, CLI commands, library exports, or events.
+One row per surface. Note auth requirement and error outcomes. For a producer/consumer split
+(separate FE/BE), this table is the contract both sides build against — pin the seam here. -->
+
+<envelope/format note if any>
+
+| Surface | Auth | Request | Success | Errors |
+|---|---|---|---|---|
+| `<method · path / command / export>` | <auth> | `<in>` | `<out>` | `<errors>` |
+
+## 9. Auth & security
+
+<!-- Authn (who you are) AND authz (what you may touch — ownership, not just session).
+Session model, secret handling, CSRF/replay/injection guards relevant to this system.
+Omit subsections that don't apply; never omit authz if the system has protected actions. -->
+
+- **AuthN:** <mechanism, session model, lifetime, revocability>
+- **AuthZ:** <ownership rule — a valid session is necessary but not sufficient>
+- **Secrets/config:** <how secrets are supplied; never in the client; .env.example provided>
+- **Boundary guards:** <CSRF / replay / rate-limit / input validation as applicable>
+
+## 10. Async / background processing
+
+<!-- DELETE this section if the system has no async/queue/scheduled work. Otherwise:
+ingest → queue → worker → store, with dedup/idempotency, retry/backoff/DLQ, and the
+recovery path for "the event never arrived" (reconciliation / inbox drain). -->
+
+- **Receive / enqueue:** <verify, dedup at the edge, fast-ack>
+- **Process (worker):** <dedup again, transactional apply, guarded write>
+- **Failure & recovery:** <retry/backoff/DLQ; reconciliation for missing events; bounded so it never loops forever>
+
+## 11. Cross-cutting concerns
+
+<!-- Conventions applied everywhere: response/error format, validation, IDs, logging,
+error hygiene (never leak internals to clients). Short bullets. -->
+
+- <response/error envelope · validation · ID scheme · logging · error hygiene>
+
+## 12. Decisions (lightweight ADRs)
+
+<!-- One ADR per significant, expensive-to-reverse choice (stack, storage, auth transport,
+sync vs async). Format: Context → Decision → Consequence. These are immutable once made;
+to change one, supersede it with a new ADR. If ADRs grow past ~6, move to docs/adr/NNNN-*.md
+(see adr/NNNN-template.md). The tech-stack rationale lives HERE, not in §1. -->
+
+**ADR-1 · <decision>.** *Context:* <forces>. *Decision:* <what was chosen over what>. *Consequence:* <what this commits us to>.
+
+## 13. Run & deploy
+
+<!-- The shortest path from clone to running. Commands, env setup, what seeds/migrations
+run on start, ports, dev credentials. The step-by-step runbook can live in README; this is
+the deploy-shape summary. -->
+
+```bash
+<clone → configure env → run>
+```
+
+## 14. Scale path & known risks
+
+<!-- What you'd do when it grows (documented, NOT built — so reviewers see you know the
+ceiling) + the honest risk list + accepted risks (by decision) + known gaps (config
+defaults that aren't decided requirements). -->
+
+**Scale path (documented, not built):** <levers for when this grows>
+
+**Known risks:** <highest-likelihood/impact risks + mitigation>
+
+**Accepted risks (by decision):** <risk + why acceptable here>
+
+**Known gaps:** <config defaults or unresolved questions>
+
+---
+<!-- Keep this file synced with the specs it describes; note the last sync below. -->
+> Synced with `docs/specs/<feature>/<feature>.md` on <YYYY-MM-DD>.

package/templates/skills/sp-scaffold/references/DESIGN.md.tmpl

@@ -0,0 +1,113 @@
+# Design: <Feature Name>
+
+<!--
+WHAT THIS IS: a per-feature, forward-looking technical proposal — how to build a change
+that doesn't exist yet, why this way, what was rejected. It is time-bound: once the feature
+ships, this becomes a historical record of intent and is expected to go stale.
+
+HOW IT DIFFERS FROM ITS NEIGHBOURS (don't duplicate):
+- ARCHITECTURE.md = the LIVING system map (always current, no argument, no expiry).
+- ADR = ONE immutable decision (this doc may SPAWN ADRs for its irreversible choices).
+- docs/specs/<feature>/<feature>.md = the BEHAVIOUR contract (Given/When/Then acceptance
+  scenarios). THIS doc is the technical "how/why"; the spec is the testable "what". They are
+  companions — keep behaviour assertions in the spec, design reasoning here.
+
+PIPELINE: explore → DESIGN.md (this) proposes & justifies → spawns ADRs for hard calls →
+sp-plan turns the agreed behaviour into the spec → after build, durable consequences fold
+into ARCHITECTURE.md. Not every feature needs a DESIGN.md — write one when the technical
+design is non-trivial or contested. A simple feature can go straight to the spec.
+
+FILL RULE: replace every <placeholder>. Keep the CORE sections; delete optional subsections
+that don't apply rather than leaving them empty. A "mini" design can collapse to
+Summary + Goals & Non-Goals + Proposed Design + Alternatives.
+-->
+
+## Metadata   <!-- CORE -->
+
+- **Author(s):** <name>
+- **Status:** Draft | In Review | Approved | Implemented | Superseded
+- **Created / Updated:** <YYYY-MM-DD> / <YYYY-MM-DD>
+- **Reviewers:** <names>
+- **Related:** <ARCHITECTURE.md §N · ADR-NNNN · docs/specs/<feature> · ticket>
+
+## Summary   <!-- CORE -->
+
+<!-- One self-contained paragraph a reader can grasp without the rest. What changes, and why now. -->
+
+<one paragraph>
+
+## Context & Background   <!-- CORE -->
+
+<!-- The problem, the current state, the constraints. Why this is worth doing. Link to the
+explore doc / ticket for deep rationale rather than repeating it. -->
+
+<the situation that motivates this design>
+
+## Goals & Non-Goals   <!-- CORE -->
+
+**Goals:**
+- <what success looks like — measurable where possible>
+
+**Non-Goals:**
+- <explicitly out of scope, so the design isn't judged against it>
+
+## Proposed Design   <!-- CORE -->
+
+<!-- The heart of the doc. Lead with an overview, then only the subsections that carry weight
+for THIS feature. Show the seam: where this feature touches existing surfaces. -->
+
+**Overview:** <the approach in a few sentences>
+
+<!-- OPTIONAL subsections — keep the ones that matter: -->
+- **System-context / data flow:** <diagram or prose — where this sits, what it talks to>
+- **APIs / interfaces:** <new or changed endpoints/commands/exports + their contract>
+- **Data model / storage:** <new entities, fields, migrations, indexes>
+- **Key logic:** <pseudo-code ONLY for genuinely novel algorithms — not routine CRUD>
+- **Degree of constraint:** <how prescriptive this design is — what's fixed vs left to the implementer>
+
+## Alternatives Considered   <!-- CORE -->
+
+<!-- The real candidates, including "do nothing". For each: what it was and why it lost.
+This is what separates a design doc from a spec — the reasoning, not just the chosen path. -->
+
+- **<alternative>:** <what it was> — rejected because <reason>.
+- **Do nothing:** <consequence of not building this>.
+
+## Trade-offs & Risks   <!-- CORE -->
+
+<!-- What this design costs, what could go wrong, what you're accepting. Be honest. -->
+
+- <trade-off accepted / risk + mitigation>
+
+## Cross-cutting Concerns   <!-- CORE — fill the ones that apply -->
+
+<!-- Address each relevant axis. "N/A — <reason>" is a valid answer; an empty one is not.
+TESTING ties to the build: name the invariants this feature must uphold (they should become
+INV-NNN in the spec, tested at EVERY surface that can break them — not just the obvious one),
+plus the negative/abuse cases (replay/double-submit, concurrent, terminal-state). -->
+
+- **Security & Privacy:** <authz, secrets, data exposure — or N/A + reason>
+- **Observability:** <logging, metrics, how you'll know it broke — or N/A + reason>
+- **Testing:** <invariants to hold across all surfaces; negative/abuse cases; integration seam>
+- **Rollout / Migration / Flags:** <how it ships safely; reversibility — or N/A + reason>
+- **Dependencies:** <new libs/services; are they maintained/justified — or N/A>
+- **Performance / Scale:** <hot paths, expected load, the ceiling — or N/A + reason>
+
+## Open Questions   <!-- CORE -->
+
+<!-- Unresolved decisions. Each should be answerable; an unanswered one blocks "Approved".
+These map cleanly to GAP-NNN when this becomes a spec. -->
+
+- <question needing an answer before / during build>
+
+## Timeline / Milestones
+
+<!-- OPTIONAL. Phased delivery if the feature is large enough to stage. -->
+
+## Revisions
+
+<!-- OPTIONAL. Material changes after first review, dated — so reviewers see what moved. -->
+
+| Date | Change |
+|---|---|
+| <YYYY-MM-DD> | <what changed and why> |

package/templates/skills/sp-scaffold/references/adr/NNNN-template.md

@@ -0,0 +1,92 @@
+# ADR-NNNN: <short noun-phrase title>
+
+<!--
+WHAT THIS IS: one architecture decision, captured immutably. An ADR is NOT a design doc
+(that's DESIGN.md, per-feature, forward-looking) and NOT the system map (that's
+ARCHITECTURE.md, living). It freezes ONE expensive-to-reverse choice — stack, storage,
+auth transport, sync vs async, a boundary rule — with the forces that drove it.
+
+WHEN TO WRITE ONE: a choice you'd want a future maintainer to understand the *why* of,
+and that you can't cheaply undo. Trivial/reversible choices don't need an ADR.
+
+IMMUTABILITY: once Status = accepted, never edit the Decision/Context. To change your mind,
+write a NEW ADR and set this one's Status to "superseded by ADR-MMMM".
+
+LOCATION & NAMING: docs/adr/NNNN-kebab-title.md, zero-padded sequential (0001, 0002…).
+ADR-0001 is conventionally the meta-decision "Record architecture decisions". While the
+project has ≤~6 decisions they may live inline in ARCHITECTURE.md §12 instead of here;
+spill into docs/adr/ once they outgrow that.
+
+TINY-DECISION SHORTCUT (Y-statement): for a small call, the whole ADR can be one line —
+"In the context of <use case>, facing <concern>, we decided for <option> and neglected
+<alternatives>, to achieve <benefit>, accepting that <trade-off>." Use the full form below
+when the decision deserves the room.
+
+FILL RULE: replace every <placeholder>. Keep the CORE four sections always; the others are
+optional — delete a heading rather than leave it empty.
+-->
+
+- **Status:** proposed | accepted | deprecated | superseded by ADR-NNNN   <!-- CORE -->
+- **Date:** <YYYY-MM-DD>
+- **Deciders:** <names / roles>
+
+## Context and Problem Statement   <!-- CORE -->
+
+<!-- The forces at play — technical, product, team, time. Value-neutral: describe the
+tension, don't argue the answer yet. End with the question being decided. -->
+
+<what's pushing on this decision, and the question it raises>
+
+## Decision Drivers
+
+<!-- OPTIONAL. The criteria that actually matter for choosing — bullet them so the
+Decision below is auditable against them. -->
+
+- <driver / constraint>
+
+## Considered Options
+
+<!-- OPTIONAL but recommended for non-obvious calls. List the real candidates, including
+"do nothing". One line each here; details go in Pros and Cons below. -->
+
+- <option A>
+- <option B>
+- <option C — e.g. do nothing>
+
+## Decision   <!-- CORE -->
+
+<!-- Active voice, full sentence: "We will …". State what was chosen AND what was rejected. -->
+
+We will <chosen option>, over <rejected options>, because <the driver that broke the tie>.
+
+## Consequences   <!-- CORE -->
+
+<!-- ALL of them — positive, negative, and neutral. What does this commit the system to?
+What new work / risk / constraint does it create? Negatives in the same list, not hidden. -->
+
+- **Positive:** <benefit gained>
+- **Negative:** <cost / new constraint / risk accepted>
+- **Neutral:** <follow-on work, things now true>
+
+## Pros and Cons of the Options
+
+<!-- OPTIONAL. Only when the trade-off is close enough that a reader will second-guess it.
+Per option: a few good/bad points. Skip for a clear-cut decision. -->
+
+### <option A>
+- Good: <…>
+- Bad: <…>
+
+## Confirmation
+
+<!-- OPTIONAL. How do we verify the decision is actually being followed in the code/build?
+(a test, a lint rule, an architecture check, a review checklist item). -->
+
+<how compliance is checked>
+
+## More Information / Links
+
+<!-- OPTIONAL. The DESIGN.md this came from, related ADRs, the ARCHITECTURE.md section it
+affects, tickets, external references. -->
+
+- <links>

package/templates/skills/sp-scaffold/references/stack-profiles/react.md

@@ -0,0 +1,36 @@
+# Stack Profile — React (web frontend / full-stack FE)
+
+<!--
+A dated, research-VERIFIABLE starting suggestion — NOT a hard rule and NOT skill logic.
+sp-scaffold MAY offer this as a default the user confirms; the Bootstrap Brief always wins,
+and currency MUST be re-checked at scaffold time (versions and "best practice" move).
+Override freely. Absence of a profile is fine — research the stack instead.
+
+This file is the TEMPLATE for adding more profiles (laravel.md, fastapi.md, go-cli.md …):
+keep them short, dated, opinion-as-data, with the "verify + don't over-install" cautions.
+
+THIS IS A KIT-BUNDLED SEED. It is OVERWRITTEN on `devkit upgrade`. Do NOT hand-edit it as your
+personal store — instead COPY it to `~/.claude/stack-profiles/<stack>.md` (your global defaults,
+survives upgrades) or `./.claude/stack-profiles/<stack>.md` (this project). Lookup precedence:
+project > user/global > this bundled seed; and the Bootstrap Brief overrides all of them.
+-->
+
+**Current as of:** 2026-06 — VERIFY each choice's currency with a web search at scaffold time before trusting it.
+
+## Conventions (the patterns the example module demonstrates)
+
+- **Server state / data layer:** TanStack Query (React Query) — never keep server state in a client store.
+- **Client state:** Zustand — only for genuine client-only state.
+- **Validation:** Zod — schemas shared between forms and API boundaries.
+- **Forms:** React Hook Form + Zod resolver.
+- **UI kit:** shadcn/ui + Tailwind (or the team's kit).
+- **Structure:** feature-based — `features/<name>/{components,hooks,services,types}`; `core/` for the request client + providers.
+- **Tests:** per the ARCHITECTURE §4 test rule — unit co-located sibling (`.test.tsx`, one suffix repo-wide), e2e as its own package.
+
+## Why these
+
+Widely adopted, composable, typed end-to-end. The scaffold's ONE example module wires a single slice through all of them — one query (React Query) → input validated by Zod → render — so every sp-build story copies an established pattern instead of improvising (this is what keeps cross-feature seams consistent).
+
+## Caution
+
+**Do NOT pre-install what the skeleton doesn't exercise.** The walking skeleton demonstrates the pattern with ONE thin slice; it does not scaffold empty stores/forms/components for features that don't exist yet. Pre-built infrastructure with no consumer is orphan code.