@johanesimm/fundamentum 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# Fundamentum — Documentation-First Project Initialization Skills
+
+> A Claude Code skill suite that builds a complete, fully-decided
+> documentation set for a software project — **before any code is
+> written** for a greenfield build, or **retro-fitted onto an existing
+> codebase** — then plans the implementation.
+
+------------------------------------------------------------------------
+
+## Quick start
+
+```bash
+npx @johanesimm/fundamentum
+```
+
+That's it — the installer asks whether to install **globally** (every
+project) or into the **current project**, copies the skills into the
+right `.claude/skills/` folder, and you're done. Restart Claude Code,
+then say *"Initialize this project documentation-first"* to kick off
+`blueprint`. Full walkthrough in [Installation](#installation) below.
+
+------------------------------------------------------------------------
+
+## What it does
+
+You start with an idea. The skills interview you — they never invent
+product facts — and produce, in order:
+
+```
+docs/
+├── foundation/    00–08  vision, principles, glossary, domain model,
+│                         org model, IA, user journeys, AI strategy,
+│                         MVP roadmap
+├── architecture/  09.x   solution architecture, ADRs, module/data/
+│                         permission/state boundaries, stack decision
+├── prd/           10–16  Master PRD (cross-cutting requirements,
+│                         permission & notification matrices, metric
+│                         formulas, event catalog) + one fully-decided
+│                         Feature PRD per module — zero open questions
+├── engineering/   20–25  ERD, database schema (validated against a
+│                         real database), REST API with guard-code
+│                         registry, frontend & backend specs,
+│                         deployment + dev-environment guide
+└── planning/             priority-ordered dev phases with checkbox
+                          deliverables and verifiable exit criteria
+```
+
+…plus the four state files (README, PROJECT_STATE, ROADMAP, CHANGELOG) and, at the end, an
+agent-context file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, … — whichever your coding tool reads)
+so any future session can implement the project without re-deriving anything.
+
+## The method (what makes it different)
+
+1. **Grill first** — every phase starts by interviewing the user;
+   gaps found in earlier docs become questions, never assumptions.
+2. **Fully-decided rule** — Feature PRDs and engineering specs ship
+   with no "Open Questions"/"TBD"; the Master PRD's deferred registry
+   is the single sanctioned backlog for future questions.
+3. **Validate, don't just write** — any schema runs against a throwaway
+   database instance; requirement references are machine-checked across
+   every document.
+4. **Bookkeeping discipline** — PROJECT_STATE/CHANGELOG/ROADMAP are
+   updated after every major document, so any session can resume.
+5. **Stack-agnostic** — the method fits any project type (web app,
+   service, CLI, library, mobile, data pipeline). The suite's
+   containerized-web-app conventions (Docker, Node/Express + Postgres,
+   React) are offered as a **recommended default profile** each skill
+   lets you confirm, adapt, or replace — never a hard requirement.
+   Stack-specific docs (frontend spec, DDL, deployment) are produced
+   only when they apply.
+
+## Skill inventory
+
+Three skills — two orchestrators (new vs existing project) plus the
+standalone agent-context (primer) generator:
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `blueprint` | **Greenfield orchestrator** — scaffolds `docs/` and drives all five phases (foundation → architecture → prd → engineering → planning), deciding everything by interview | Starting a brand-new project documentation-first, or asking for any single phase |
+| `excavate` | **Brownfield orchestrator** — surveys the real code + DB, then drives a reduced pipeline (foundation → prd → data/API → planning) that documents what's already built and plans the gap | Documenting / reverse-engineering an existing codebase |
+| `primer` | Standalone: generate the house-style agent-context file for any project — asks which agentic tool the user uses and writes the right file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / …) | Anytime; also each pipeline's final step |
+
+The phases are **not** separate skills — each orchestrator bundles them
+as instruction files under its own `phases/`, read one at a time:
+
+```
+blueprint/  (greenfield)              excavate/  (existing codebase)
+├── SKILL.md   scaffold + drive       ├── SKILL.md   survey code, then drive
+└── phases/                           └── phases/
+    ├── foundation.md   00–08             ├── foundation.md   00–08  (derived + intent)
+    ├── architecture.md 09.x              ├── prd.md          10–16  (as-built PRDs)
+    ├── prd.md          10–16             ├── engineering.md  20–22  (introspected
+    ├── engineering.md  20–25             │                          ERD/schema/API)
+    └── planning.md     dev phases        └── planning.md     remaining-work plan
+```
+
+The existing-project pipeline deliberately **skips architecture (09.x)
+and the backend/frontend build-specs + deploy guide (23–25)** — for a
+codebase that already exists, the code is the authority for those. Its
+method flips too: **code is the source of truth**, and the user is
+interviewed only for product intent the code can't reveal (vision,
+non-goals, rationale, canonical names).
+
+In both, the pipeline order is enforced by each phase file's stated
+prerequisites and "Done when" gate, not by hidden state — so you can
+jump straight to one phase, provided its inputs already exist.
+
+## Installation
+
+### The `npx` installer (recommended)
+
+**Prerequisites:** [Node.js](https://nodejs.org) 18+ (gives you `npx`)
+and [Claude Code](https://claude.com/claude-code).
+
+**Step 1 — run the installer.** No global install needed; `npx` fetches
+and runs it on the fly:
+
+```bash
+npx @johanesimm/fundamentum
+```
+
+**Step 2 — choose where the skills go.** You'll be asked:
+
+```
+Fundamentum — installing: blueprint, excavate, primer
+
+Where should these skills go?
+  1) Global   ~/.claude/skills      (available in every project)
+  2) Project  ./.claude/skills      (this repo only)
+Choose [1/2]:
+```
+
+- **Global** → the skills work in *every* project on your machine.
+- **Project** → installed only into the repo you're currently in
+  (`./.claude/skills/`); commit them to share with your team.
+
+**Step 3 — done.** It copies the folders and confirms:
+
+```
+  ✓ blueprint → ~/.claude/skills/blueprint
+  ✓ excavate  → ~/.claude/skills/excavate
+  ✓ primer    → ~/.claude/skills/primer
+
+Done. Installed 3 skill(s) into the global directory.
+Restart Claude Code (or start a new session) to pick them up.
+```
+
+**Step 4 — use them.** Restart Claude Code, then just ask:
+
+| Say this | Runs |
+|---|---|
+| "Initialize this new project documentation-first" | `blueprint` |
+| "Document this existing codebase" | `excavate` |
+| "Generate the agent-context file for this project" | `primer` |
+
+### More installer options
+
+```bash
+npx @johanesimm/fundamentum add primer   # install just one skill (space-separate for several)
+npx @johanesimm/fundamentum --global     # skip the prompt: install for every project
+npx @johanesimm/fundamentum --project    # skip the prompt: install into ./.claude/skills
+npx @johanesimm/fundamentum --force      # overwrite existing skills without asking
+npx @johanesimm/fundamentum list         # show which skills are bundled
+npx @johanesimm/fundamentum --help       # full usage
+```
+
+### Run without npm (from source)
+
+```bash
+npx github:<owner>/fundamentum           # straight from GitHub, no publish needed
+node bin/cli.mjs --project               # from a local checkout of this repo
+```
+
+### Manual copy (no Node at all)
+
+Copy the skill folders (`blueprint/`, `excavate/`, `primer/`) into
+`~/.claude/skills/` (global) or `<repo>/.claude/skills/` (project).
+
+### Fork & publish your own
+
+It's a plain npm package. Set a unique `name` in `package.json` (a
+scoped `@you/fundamentum` is always free), then `npm publish` (scoped
+packages need `--access public`, already set here via `publishConfig`).
+Whatever you name it becomes the `npx <name>` command; `files` in
+`package.json` ships only the CLI + skill folders + README.

package/bin/cli.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// Fundamentum skill installer — copies the bundled skills into a Claude Code
+// skills directory (global ~/.claude/skills or project ./.claude/skills).
+// Zero dependencies: uses only the Node standard library.
+
+import { readdir, cp, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import process from 'node:process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(HERE, '..'); // package root — where the skill folders live
+
+const HELP = `fundamentum — install documentation-first Claude Code skills
+
+Usage:
+  npx fundamentum [add] [skills...] [options]
+  npx fundamentum list
+
+Arguments:
+  skills...            Names of skills to install (default: all bundled skills)
+
+Options:
+  -g, --global        Install into ~/.claude/skills (every project)
+  -p, --project       Install into ./.claude/skills (this repo only)
+  -f, --force         Overwrite an existing skill without asking
+  -h, --help          Show this help
+
+With no --global/--project flag, you'll be asked which one.
+
+Examples:
+  npx fundamentum                 # install all skills, ask scope
+  npx fundamentum add primer -g   # install just 'primer' globally
+  npx fundamentum --project       # install all into this repo
+`;
+
+/** Discover bundled skills = top-level dirs that contain a SKILL.md. */
+async function discoverSkills() {
+  const entries = await readdir(ROOT, { withFileTypes: true });
+  const skills = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (e.name.startsWith('.') || e.name === 'bin' || e.name === 'node_modules') continue;
+    if (existsSync(join(ROOT, e.name, 'SKILL.md'))) skills.push(e.name);
+  }
+  return skills.sort();
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  // optional leading verb
+  if (['add', 'install', 'i'].includes(args[0])) args.shift();
+  const flags = new Set();
+  const names = [];
+  for (const a of args) {
+    if (a === '-h' || a === '--help') flags.add('help');
+    else if (a === '-g' || a === '--global') flags.add('global');
+    else if (a === '-p' || a === '--project') flags.add('project');
+    else if (a === '-f' || a === '--force') flags.add('force');
+    else if (a.startsWith('-')) throw new Error(`Unknown option: ${a}`);
+    else names.push(a);
+  }
+  return { flags, names, verb: argv[0] };
+}
+
+async function main() {
+  const { flags, names, verb } = parseArgs(process.argv.slice(2));
+
+  if (flags.has('help')) {
+    process.stdout.write(HELP);
+    return;
+  }
+
+  const available = await discoverSkills();
+  if (available.length === 0) throw new Error(`No skills found in ${ROOT}`);
+
+  if (verb === 'list') {
+    process.stdout.write(`Bundled skills:\n${available.map((s) => `  - ${s}`).join('\n')}\n`);
+    return;
+  }
+
+  // Which skills?
+  let selected = available;
+  if (names.length) {
+    const unknown = names.filter((n) => !available.includes(n));
+    if (unknown.length) {
+      throw new Error(
+        `Unknown skill(s): ${unknown.join(', ')}\nAvailable: ${available.join(', ')}`,
+      );
+    }
+    selected = names;
+  }
+
+  // Interactive prompts share one readline instance.
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+  try {
+    // Scope: global vs project.
+    let scope;
+    if (flags.has('global')) scope = 'global';
+    else if (flags.has('project')) scope = 'project';
+    else if (rl) {
+      process.stdout.write(
+        `\nFundamentum — installing: ${selected.join(', ')}\n\n` +
+          `Where should these skills go?\n` +
+          `  1) Global   ${join(homedir(), '.claude', 'skills')}   (available in every project)\n` +
+          `  2) Project  ${join(process.cwd(), '.claude', 'skills')}   (this repo only)\n`,
+      );
+      const ans = (await rl.question('Choose [1/2]: ')).trim();
+      scope = ans === '2' || ans.toLowerCase().startsWith('p') ? 'project' : ans === '1' || ans.toLowerCase().startsWith('g') ? 'global' : null;
+      if (!scope) throw new Error('No scope chosen. Aborting.');
+    } else {
+      throw new Error('Non-interactive shell: pass --global or --project.');
+    }
+
+    const targetBase =
+      scope === 'global'
+        ? join(homedir(), '.claude', 'skills')
+        : join(process.cwd(), '.claude', 'skills');
+
+    await mkdir(targetBase, { recursive: true });
+
+    const force = flags.has('force');
+    const installed = [];
+    for (const name of selected) {
+      const src = join(ROOT, name);
+      const dest = join(targetBase, name);
+
+      if (existsSync(dest) && !force) {
+        if (rl) {
+          const ans = (await rl.question(`  ${dest} exists. Overwrite? [y/N]: `)).trim().toLowerCase();
+          if (ans !== 'y' && ans !== 'yes') {
+            process.stdout.write(`  skipped ${name}\n`);
+            continue;
+          }
+        } else {
+          process.stdout.write(`  skipped ${name} (exists; use --force)\n`);
+          continue;
+        }
+      }
+
+      await cp(src, dest, { recursive: true, force: true });
+      installed.push(name);
+      process.stdout.write(`  ✓ ${name} → ${dest}\n`);
+    }
+
+    if (installed.length) {
+      process.stdout.write(
+        `\nDone. Installed ${installed.length} skill(s) into the ${scope} directory.\n` +
+          `Restart Claude Code (or start a new session) to pick them up.\n`,
+      );
+    } else {
+      process.stdout.write(`\nNothing installed.\n`);
+    }
+  } finally {
+    rl?.close();
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`Error: ${err.message}\n`);
+  process.exit(1);
+});

package/blueprint/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: blueprint
+description: Bootstrap AND drive the documented-initialization pipeline for a NEW / greenfield project — creates the docs/ scaffold (README, PROJECT_STATE, ROADMAP, CHANGELOG) and runs all five documentation phases in order (foundation → architecture → prd → engineering → planning), each defined in its own bundled phase file under phases/. Use when the user wants to start a project "documentation-first", asks to "initialize project docs", or asks for any single phase (vision/glossary/domain, architecture/ADRs, Master/Feature PRDs, engineering specs/schema/API, or the dev plan). Self-contained entry point for the whole docs pipeline.
+---
+
+# Documented Project Initialization (orchestrator)
+
+You are bootstrapping a project that will be **fully documented before
+any code is written**, using this pipeline:
+
+```
+foundation (00-08) → architecture (09.x) → PRDs (10-16)
+→ engineering (20-25) → planning (dev phases)
+```
+
+Each phase is a bundled instruction file in `phases/`; this skill sets
+up the scaffold, then you **read the relevant `phases/*.md` file and
+follow it** for that phase. **Never write code during this pipeline.**
+Never skip a phase: each consumes the previous one. If the user asks
+for just one phase, jump straight to that phase file — but first
+confirm its prerequisite docs exist (each file states what it needs).
+
+## Step 1 — Interview (always first)
+
+Ask (AskUserQuestion, batched): project name and one-sentence purpose;
+what it explicitly is NOT; target users; whether any docs already
+exist; and how far they want to go now (full pipeline vs one phase).
+Do not proceed on assumptions.
+
+## Step 2 — Scaffold `./docs/`
+
+Create these four state files (small, from the answers):
+
+-   `docs/README.md` — documentation index listing the five phases
+    with status markers (✅ / 🚧 Next / ⏳ Planned)
+-   `docs/PROJECT_STATE.md` — sections: Project, Current Phase,
+    Current Milestone, Completed, Next Tasks, Locked Decisions
+    (empty), Conversation Resume Prompt
+-   `docs/ROADMAP.md` — phase table + upcoming deliverables +
+    "Repository Rule: always update PROJECT_STATE.md and CHANGELOG.md
+    after completing a major document"
+-   `docs/CHANGELOG.md` — `## v0.1` with the scaffold entry + policy
+    line ("Record all significant product, architecture, and
+    documentation decisions here")
+
+Create empty dirs: `docs/foundation`, `docs/architecture`, `docs/prd`,
+`docs/engineering`, `docs/planning`.
+
+## Step 3 — Drive the phases
+
+Work through these in order, one at a time, finishing each before the
+next. For each, **read the phase file and follow it to completion**:
+
+| Order | Phase file | Produces |
+|---|---|---|
+| 1 | `phases/foundation.md` | foundation/00–08 |
+| 2 | `phases/architecture.md` | architecture/09 + 09.5 ADRs + 09.A–J |
+| 3 | `phases/prd.md` | prd/10-Master-PRD + Feature PRDs 11+ |
+| 4 | `phases/engineering.md` | engineering/20–25 |
+| 5 | `phases/planning.md` | planning/ overview + phase files |
+
+Each phase file ends with a "Done when" gate and a pointer to the next
+file — do not advance until the gate passes.
+
+## House conventions (every phase skill enforces these; you enforce
+them too when reviewing output)
+
+1.  **Grill first**: every phase starts with an interview; nothing is
+    invented. Recommended defaults are offered, the user decides.
+2.  **Doc format**: header blockquote (`Document ID`, `Status: Draft
+    vX.Y`, `Depends On`), a Documentation Roadmap status table,
+    `---` separators between sections.
+3.  **Numbering**: 00–08 foundation, 09.x architecture, 10 Master PRD,
+    11+ Feature PRDs, 20+ engineering. IDs never reused.
+4.  **Single source of truth**: reference authoritative docs, never
+    duplicate them; the glossary owns terminology; changes to a locked
+    decision require a superseding decision recorded in CHANGELOG.
+5.  **Fully-decided rule** (PRDs onward): no "Open Questions" /
+    "Pending" / "TBD" sections in Feature PRDs or engineering specs —
+    every question is resolved with the user before the document is
+    finished. The Master PRD's deferred-registry chapter is the ONLY
+    place unresolved future questions may live.
+6.  **Bookkeeping after every major document**: update
+    PROJECT_STATE.md (current milestone), CHANGELOG.md (what + why),
+    README.md and ROADMAP.md status markers.
+7.  **Validate before declaring done**: grep for unresolved language,
+    check ID uniqueness and dangling references, check banned-term
+    consistency. Executable artifacts (SQL) get run, not just written.
+
+## Exit
+
+When all five phases are complete, generate the project's agent-context
+(primer) file with the `primer` skill — it asks which agentic coding
+tool the user uses and writes the correctly-named file (`CLAUDE.md`,
+`AGENTS.md`, `GEMINI.md`, …) or skips if they use none, reusing
+everything above as interview input. Then hand over to implementation.

package/blueprint/phases/architecture.md

@@ -0,0 +1,78 @@
+# Phase 2 — Solution Architecture (docs/architecture/09.x)
+
+> Extension of `blueprint`. Read and follow this file when the
+> orchestrator reaches the architecture phase. Requires the foundation
+> docs (00–08) to exist; interviews the user on every technology and
+> boundary choice.
+
+Translate the foundation (00–08) into locked technical decisions.
+**Read the foundation docs first** — architecture serves the domain
+model and journeys, not the other way around. Every choice is either
+proposed-with-rationale and confirmed by the user, or given by the
+user directly. The recommendations below are a common default for a
+**web application**; first establish what KIND of system this is (web
+app, service/API, CLI, library, mobile, data pipeline, …) and only
+offer the recommendations that fit — never assume a web stack.
+
+## Interview (before writing)
+
+Round 1 — shape: overall structure (for a web/service product recommend
+a modular monolith; but a CLI, library, or pipeline has its own shape —
+match the project type); interface style (REST with a versioned prefix
+is a good web default; others use gRPC, GraphQL, a CLI surface, a public
+library API, message consumers — pick what fits); event needs; async/
+background work if any. Round 2 — stack, offered per tier only when it
+applies and always replaceable: *frontend* (default React + Vite +
+Tailwind + shadcn/ui + TanStack Query + Zustand + RHF + Zod — only if it
+has a UI); *backend/core* (default Node/Express + PostgreSQL + JWT/
+refresh + Argon2id + RBAC — or whatever language/runtime/datastore the
+project actually uses: Python, Go, Rust, Java, …); anything the user's
+org mandates. Round 3 — boundaries: which modules own which data; AI
+isolation requirements; permission/trust philosophy.
+
+## Documents to produce
+
+| Doc | Content |
+|---|---|
+| **09-Solution-Architecture** | The umbrella: context, chosen shape, module list, data-flow overview, security boundaries, integration points, and a closing "Transition" section authorizing the Master PRD |
+| **09.5-Architecture-Decision-Records** | ADR-001…N — one per significant choice: context, decision, consequences, alternatives rejected. Governance rule: future changes must reference/supersede an ADR |
+| **09.A-Frontend-Architecture** | Stack, feature-based structure, rendering/build decisions |
+| **09.B-Backend-Architecture** | Stack, process model (api + worker), auth mechanics |
+| **09.C-Module-Boundaries** | The definitive module list — this becomes the Feature-PRD structure AND the code layout; choose carefully |
+| **09.D-Service-Boundaries** | What runs where (processes, jobs) |
+| **09.E-Event-Architecture** | Core business events + consumers (Timeline/Analytics/AI/Notifications pattern) |
+| **09.F-Data-Ownership** | Entity → owning module table; no entity has two owners |
+| **09.G-API-Boundaries** | API prefix, versioning, external surface |
+| **09.H-Permission-Boundaries** | Role → capability summary (coarse; the PRD refines to resource level) |
+| **09.I-State-Management** | Frontend state rules (e.g. "server state in query cache only, never in the client store" — make one locked rule like this) |
+| **09.J-Technology-Stack-Decision** | Final stack table, one line of rationale each |
+
+Produce only the docs that fit the project type — several are
+web-specific. A headless service or CLI omits **09.A** (frontend) and
+**09.I** (frontend state); a single-process tool may fold **09.D** into
+09.B; a project with no eventing skips **09.E**; a library exposing a
+public API documents its surface in **09.G** rather than an HTTP prefix.
+Keep the umbrella (09), ADRs (09.5), module boundaries (09.C), data
+ownership (09.F), and the stack decision (09.J) in every case; note any
+intentionally-omitted doc in 09 so the omission is explicit.
+
+Short docs are fine — several of these are half a page. Precision
+beats length.
+
+## Rules
+
+-   Every decision traces to a foundation need (cite the doc); if the
+    user requests something the foundation doesn't justify, ask.
+-   Locked decisions go into PROJECT_STATE.md's "Locked Decisions"
+    list.
+-   House format (metadata header, status table, separators);
+    bookkeeping after each doc (PROJECT_STATE, CHANGELOG, ROADMAP,
+    README).
+
+## Done when
+
+09 + 09.5 + 09.C + 09.F + 09.J exist plus every other boundary doc that
+applies to this project type (any omitted one is noted in 09); module
+list (09.C) and data ownership (09.F) are mutually consistent; ADRs
+cover every stack row in 09.J; PROJECT_STATE points at the Master PRD
+(`phases/prd.md`).

package/blueprint/phases/engineering.md

@@ -0,0 +1,146 @@
+# Phase 4 — Engineering Specifications (docs/engineering/20–25)
+
+> Extension of `blueprint`. Read and follow this file when the
+> orchestrator reaches the engineering phase. Derives mechanically from
+> the PRDs; asks the user only for genuine engineering choices;
+> validates executable artifacts.
+
+Requires fully-decided PRDs. These documents **derive** from the PRDs
+— if you hit an undecided product question, STOP and send it back
+through the PRD process (Master PRD amendment) before continuing.
+Interview the user only for genuine engineering-level choices (e.g.
+email transport mechanism, deployment target) — present options with a
+recommendation.
+
+**Adapt the doc set to the project type (this catalogue is the
+web-app-with-relational-DB default).** Produce only the specs that
+apply, and translate each to the project's real stack:
+
+-   **20-ERD / 21-Database-Schema** — only if the project has a managed
+    datastore. Relational → ERD + DDL as below; a document/KV store →
+    document the collections, keys, and invariants in the store's own
+    terms; no persistent store (CLI, stateless service, library) → skip
+    both.
+-   **22-REST-API** — retitle to the actual interface: **22-API** for
+    gRPC/GraphQL, **22-CLI-Interface** for a command-line tool,
+    **22-Public-API** for a library's exported surface. Keep the intent
+    (every operation, its inputs, its errors, its requirement refs).
+-   **23-Frontend-Specification** — only if it has a UI; otherwise skip.
+-   **24-Backend-Specification** — retitle to **24-Core-Specification**
+    for a non-HTTP service, CLI, or library; keep the module/layering,
+    guard-placement, and verification content, drop web-only pieces
+    (request pipeline, outbox) that don't apply.
+-   **25-Deployment-Guide** — match the real delivery model: container
+    topology (below), a serverless deploy, a published package
+    (registry + versioning + release process), or an app-store build.
+
+Renumber nothing — keep 20–25 for the slots that exist, and note any
+skipped doc in 20 (or the umbrella) so the omission is explicit. The
+per-doc detail below is the default profile; carry its *intent* into
+whatever stack the project chose.
+
+Every requirement ID cited in these specs must exist in the PRDs —
+run the cross-check grep after each document:
+
+```
+comm -13 <(cat docs/prd/*.md | grep -oE '<ID-REGEX>' | sort -u) \
+         <(grep -oE '<ID-REGEX>' <spec>.md | sort -u)
+```
+
+## 20-ERD
+
+Relational model: engineering conventions table (PK strategy, naming,
+timestamps, enum policy, deletion policy = lifecycle statuses not
+soft-deletes, immutability strategy, week/time identification); entity
+overview by owning module (mirror 09.F exactly); mermaid `erDiagram`;
+entity notes for **non-obvious choices only**, each justified by a
+requirement ID; a "referential-integrity rules enforced in schema"
+table (PRD rule → mechanism) and an explicit list of what is
+service-layer instead (state machines, cross-module guards,
+permissions).
+
+## 21-Database-Schema
+
+Complete DDL implementing 20, ordered to run top-to-bottom: enum
+types (from the controlled vocabularies — cite requirement IDs in
+comments), tables per module with CHECK constraints for every PRD
+invariant, partial indexes for hot paths, immutability triggers
+(append-only tables + column-level guards for content-immutable
+rows), worker-infrastructure tables (outbox, job ledger, email queue)
+if 24 needs them.
+
+**MANDATORY when there is a schema: validate it against a real
+instance** of the chosen engine (a throwaway Docker container or
+equivalent): for SQL, extract the DDL, run with `ON_ERROR_STOP`, count
+tables, smoke-test 2–3 key guards (an immutability trigger, a CHECK
+constraint), tear down; for a non-SQL store, apply the schema/validators
+to a throwaway instance and assert a couple of the invariants. A schema
+doc that hasn't been executed against a real engine is not done.
+Re-validate after every later amendment.
+
+## 22-REST-API
+
+Conventions first: base path/versioning (09.G), auth, response/error
+envelope, HTTP-status table (including 409 = business-guard
+violation), pagination. Then per-module endpoint tables (method, path,
+roles, behavior with requirement refs). Rules: **state transitions are
+POST actions, never PATCH status**; a **guard-code registry** section
+mapping every 409 `code` → PRD rule → endpoints; cross-cutting
+behavior section (transactional event emission, AI isolation, async
+202 pattern, performance budgets).
+
+## 23-Frontend-Specification
+
+Stack (from 09.A); feature-folder structure mirroring 09.C with a
+no-cross-feature-internals rule; **route × role matrix** (every route,
+R/RW/— per role, role landing redirects); state-management rules
+(restate the 09.I locked rule operationally: query keys, invalidation,
+optimistic-update policy — never optimistic on guarded actions); API
+layer + **guard-code → UI mapping** (409s become actionable dialogs);
+screens per feature with requirement anchors; cross-cutting UI rules
+(action-first, three-click, read-only rendering, accessibility of
+status colors, AI labeling, performance budgets); verification plan
+(route-permission tests, guard-dialog tests, glossary lint in CI).
+
+## 24-Backend-Specification
+
+Process model (api + worker from one codebase); module layout with
+lint-enforced layering (controllers → services → repositories;
+cross-module via exported interfaces only); request pipeline
+(authenticate → status gate → authorize from a single policy table
+transcribing the master permission matrix); **transactional outbox**
+(business write + activity + outbox in one transaction; at-least-once
+idempotent consumers); guard placement table (which service owns which
+guard, row-locked inside the mutation transaction); notification
+matrix engine; **scheduled-jobs table** (job, schedule in org
+timezone, behavior, all idempotent via the job ledger); external
+integration flows in full (e.g. email: connection, send pipeline,
+retry/backoff, failure handling — never leave an integration as a
+one-liner); AI pipeline + isolation (restricted DB role) if
+applicable; security parameters; verification plan.
+
+## 25-Deployment-Guide
+
+Topology (recommend Docker Compose single host for a modular-monolith
+MVP; images orchestrator-agnostic); image table (multi-stage, non-root,
+SHA-versioned, never `latest`); environment-variable table (secrets
+only — runtime org config belongs in the database); migrations
+(one-shot container, forward-only, boot-time version check);
+least-privilege DB roles; backup/PITR/restore-drill policy sized to
+what the PRDs declare precious; TLS/proxy/runtime policies;
+health/monitoring/alerts table; deploy + rollback procedure; first-
+install bootstrap (including the seed-admin exception); **Development
+Guide section**: docker-compose.dev with hot reload (watcher backend,
+HMR frontend, bind mounts), dev provider substitutions through the
+same interfaces (mail catcher, AI stub), committed dev env file, seed
+command, manual job triggering, and dev/prod parity rules (no guard
+bypasses).
+
+## Bookkeeping & done
+
+After each doc: cross-check grep, PROJECT_STATE, CHANGELOG (record
+engineering decisions like transport choices individually), ROADMAP/
+README markers. Done when every applicable spec in the 20–25 range
+exists (skipped ones noted), any schema has passed live validation
+against a real engine, all reference greps are clean, and PROJECT_STATE
+points at planning (`phases/planning.md`).