@skyf0xx/hedgehog 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# The Antidote to AI Spaghetti Code
+
+AI can write code faster than humans ever could.
+
+But **speed without discipline creates chaos**.
+
+Hedgehog gives AI the guard-rails it needs to **build software that stays clean.**
+
+A complete development methodology combining:
+
+- structured workflows
+- opinionated architecture
+- composable skills
+- incremental build loops
+- enforced quality gates
+
+**Build faster, Save context**. Stay aligned. Ship software you can still understand six months later.
+
+![Hedgehog — build software the right way, one step at a time](docs/images/hero.png)
+
+## Hedgehog gives AI
+
+1. An opinionated stack
+2. An enforced build order
+3. Agents and skills that make good engineering the default.
+
+## Hedghog's secret to great outcomes
+
+- 🧩 **Progressive layering:** types → schema → backend → UI, each layer built on a stable one beneath it
+- 🎯 **Small context loops:** decompose work into atomic, verifiable changes
+- 🌳 **Self-documenting architecture:** the codebase carries the context, not the AI
+- 🔁 **Traceable evolution:** decisions are preserved through conventional commits
+
+![Just describe what you want](docs/images/curve.png)
+
+## Why Hedgehog Exists
+
+AI coding starts fast then breaks down.
+
+Context accumulates, prompts get longer, architecture drifts.
+
+Eventually, adding one more feature feels
+dangerous.
+
+**The enemy isn't AI. It's the absence of guardrails.**
+
+## Plans Expire. Structure Doesn't
+
+Without a build order enforced mechanically, an AI (or a person) has to carry the whole plan in its head: architecture, sequencing, past decisions, etc. as an ever-growing prompt.
+
+Hedgehog doesn't ask the AI to remember a plan. It makes the plan visible in the structure of the build. The architecture itself guides the next step.
+
+### The AI should never wonder what to do next
+
+Instead of asking AI to hold an entire application in context, Hedgehog turns the build into a sequence of small, deterministic steps.
+
+Each module is built progressively: schema → contract → repository → service → controller. Every step is gated by tests and committed before the next begins.
+
+Backend comes first. Every module gets a working, typed API before any screen is built. The frontend becomes a consumer of stable capabilities, not a parallel source of complexity.
+
+The build order is not something you negotiate with the AI. It is encoded into the process.
+
+![Small steps, big leverage: small context loops, continuous verification, traceable evolution, sustainable velocity](docs/images/small-steps.png)
+
+## The Hedgehog Loop
+
+``` text
+Bootstrap (once per project)
+  ↓
+Intake — scope boundary + domain vocabulary (planner agent)
+  ↓
+Phase A, per module — schema → contract → repository → service → controller
+  ↓
+Phase A closes for the module (gated: typecheck, lint, test)
+  ↓
+Phase B, per module — hook → UX rationale → screen
+  ↓
+Repeat for the next module or the next step
+```
+
+
+![Why Hedgehog works: a different way to build with AI, comparing traditional AI workflow to Hedgehog](docs/images/why.png)
+
+## Installation
+
+Hedgehog installs **into your repo**, not into your editor. The agents and
+skills land in `.claude/` and get committed alongside your code — because
+the discipline is only real if it travels with the project, versioned and
+visible to your team and CI.
+
+From the root of the repo you want to build with Hedgehog:
+
+``` bash
+npx @skyf0xx/hedgehog init
+```
+
+This copies:
+
+- `src/agents/*` → `.claude/agents/` — the `planner`, `ui-builder`, and
+  `reviewer` roles
+- `src/skills/*` → `.claude/skills/` — `hedgehog-bootstrap`,
+  `hedgehog-loop`, and `conventional-commits`
+- `CLAUDE.md` and `TODO.md` templates into the repo root
+
+If a target file already exists, `init` warns and stops without touching
+it. Re-run with `--force` to overwrite:
+
+``` bash
+npx @skyf0xx/hedgehog init --force
+```
+
+Then commit the `.claude/` payload, open Claude Code, and say:
+
+> bootstrap this project
+
+That triggers the `hedgehog-bootstrap` skill, which scaffolds the stack and
+wires the enforcement config (Nx boundaries, lefthook, commitlint, phase
+gate). From there, `hedgehog-loop` takes over one module at a time.
+
+## For Builders
+
+Hedgehog brings proven software engineering practices into AI-assisted development.
+
+Once the project brief is defined, Hedgehog takes over the execution: breaking the work into steps, following the build order, validating progress, and keeping decisions traceable.
+
+Under the hood, it applies the practices experienced engineers rely on:
+
+- iterative delivery
+- small units of work
+- an opinionated stack
+- clear architectural boundaries
+- ports and adapters
+- continuous verification
+- conventional commits
+
+AI becomes the builder operating inside those constraints — turning ideas into software without requiring you to manage every implementation detail.
+
+## Architecture
+
+Hedgehog is a package of agents and skills. An opinionated stack is used so the build order above is mechanical and enforced by the tooling itself:
+
+| Layer | Choice | Why |
+| --- | --- | --- |
+| Monorepo | Nx | Enforces module boundaries at compile time. |
+| Package manager | pnpm | Prevents accidental cross-package dependencies. |
+| Backend | NestJS | Modules naturally mirror Hedgehog's build progression. |
+| ORM | Drizzle + drizzle-zod | Database schema is the single source of truth. |
+| Database | PostgreSQL | Simple, relational, predictable. |
+| Platform | Railway | Infrastructure is available from the first commit. |
+| API contract | ts-rest | Contracts are code, not documentation. |
+| Validation | Zod | One schema for runtime and compile time. |
+| Auth | Better Auth | Secure by default from day one. |
+| Data fetching | TanStack Query | UI consumes typed APIs, never implementation details. |
+| Web | Next.js + ShadCN + Tailwind | UI remains a thin presentation layer. |
+| Mobile | Expo + RN Reusables | Shares contracts and design tokens with web. |
+| Jobs | BullMQ + Redis | Async boundaries exist before they're needed. |
+| Logging | Pino | Structured logs from the first feature. |
+| Linting | ESLint + Prettier | One shared standard across every module. |
+| Testing | Vitest + Playwright | Every step is verifiable before progressing. |
+| Commits | Conventional Commits | Architectural decisions become permanent history. |
+| Observability | Sentry | Failures map cleanly back to module boundaries. |
+
+## How Hedgehog Compares
+
+Superpowers and BMAD both improve on raw prompting: one gives the AI good habits, the other gives it a planning process.
+
+But in both, the order of work is a **convention, not a constraint** it's unable to break.
+
+Hedgehog **enforces its build order with tooling** instead: Nx module boundaries, commit hooks, phase gates. The order holds because the tooling holds it, not because the discipline was followed.
+
+| | Superpowers | BMAD | Hedgehog |
+| --- | --- | --- | --- |
+| **What it is** | A skills library for Claude Code: brainstorm, plan, TDD, debug, review | A multi-agent planning framework: PM, Architect, Dev, QA personas | A build discipline: fixed stack, enforced module order |
+| **Order comes from** | Skill instructions the agent is told to follow | Sequenced documents (brief → PRD → architecture → stories) | Tooling (Nx boundaries, lefthook, phase gate) |
+| **Enforcement mechanism** | None. Prompted convention | None. One optional agent-run checklist between phases | Mechanically enforced by Nx boundaries, commit hooks, and the phase gate |
+| **Unit of work** | A task, planned in worktree-isolated steps | A story, derived from PRD and architecture docs | A module layer (schema → contract → repo → service → controller → UI) |
+| **Stack** | Whatever the project already uses | No stack opinion | One locked stack (Nx, NestJS, Drizzle, ts-rest, Next.js) |
+| **Context per step** | As much as the task pulls in | A full brief, PRD, and architecture doc per story | One module layer at a time (e.g. just the repository, just the controller) |
+| **Finding a bug** | Search wherever the task touched | Search wherever the story touched | Search one layer, in one module, in a fixed order |
+| **Real cost** | No safety net if the model shortcuts its own process | Documentation overhead most solo projects don't need | Less flexibility: the stack and order aren't negotiable |

package/bin/cli.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Hedgehog installer. Copies the agents/skills payload and root templates
+// into the current repo, so the discipline travels with the project.
+//
+// Usage:
+//   npx @skyf0xx/hedgehog init          scaffold into the current directory
+//   npx @skyf0xx/hedgehog init --force  overwrite files that already exist
+//   npx @skyf0xx/hedgehog --help
+
+import { cp, mkdir, access, readdir, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+const DEST_ROOT = process.cwd();
+
+// ── tiny ANSI helpers (no deps) ─────────────────────────────────────────
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const bold = (s) => paint('1', s);
+const green = (s) => paint('32', s);
+const yellow = (s) => paint('33', s);
+const red = (s) => paint('31', s);
+const dim = (s) => paint('2', s);
+
+// ── the payload: what gets copied, and to where under the target repo ───
+// `dir` entries copy a whole tree; `file` entries copy a single file and
+// may rename (templates lose their src/templates/ prefix at the root).
+const PLAN = [
+  { type: 'dir', from: 'src/agents', to: '.claude/agents' },
+  { type: 'dir', from: 'src/skills', to: '.claude/skills' },
+  { type: 'file', from: 'src/templates/CLAUDE.md', to: 'CLAUDE.md' },
+  { type: 'file', from: 'src/templates/TODO.md', to: 'TODO.md' },
+];
+
+const exists = (p) =>
+  access(p, constants.F_OK).then(
+    () => true,
+    () => false,
+  );
+
+// Every destination file this plan would write, resolved absolute.
+async function plannedFiles(entry) {
+  const src = join(PKG_ROOT, entry.from);
+  if (entry.type === 'file') {
+    return [{ src, dest: join(DEST_ROOT, entry.to) }];
+  }
+  const out = [];
+  async function walk(rel) {
+    const abs = join(src, rel);
+    const st = await stat(abs);
+    if (st.isDirectory()) {
+      for (const name of await readdir(abs)) await walk(join(rel, name));
+    } else {
+      out.push({ src: abs, dest: join(DEST_ROOT, entry.to, rel) });
+    }
+  }
+  await walk('.');
+  return out;
+}
+
+function help() {
+  console.log(`
+${bold('Hedgehog installer')}
+
+Copies the Hedgehog agents and skills into ${bold('.claude/')} and drops the
+CLAUDE.md / TODO.md templates into the repo root, so the discipline is
+committed alongside your code.
+
+${bold('Usage')}
+  npx @skyf0xx/hedgehog init            scaffold into the current directory
+  npx @skyf0xx/hedgehog init --force    overwrite existing files
+  npx @skyf0xx/hedgehog --help
+
+After it runs, commit the .claude/ payload, open Claude Code, and say
+"bootstrap this project" to trigger the hedgehog-bootstrap skill.
+`);
+}
+
+async function init({ force }) {
+  // Resolve the full list of writes up front so we can detect conflicts
+  // before touching anything.
+  const groups = [];
+  for (const entry of PLAN) {
+    const files = await plannedFiles(entry);
+    groups.push({ entry, files });
+  }
+
+  const conflicts = [];
+  for (const { files } of groups) {
+    for (const f of files) {
+      if (await exists(f.dest)) conflicts.push(f.dest);
+    }
+  }
+
+  if (conflicts.length && !force) {
+    console.error(`\n${red(bold('Refusing to overwrite existing files.'))}\n`);
+    for (const c of conflicts) {
+      console.error(`  ${yellow('exists')}  ${relative(DEST_ROOT, c) || c}`);
+    }
+    console.error(
+      `\nRe-run with ${bold('--force')} to overwrite, or move these aside first.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  let written = 0;
+  let overwritten = 0;
+  for (const { files } of groups) {
+    for (const f of files) {
+      const already = await exists(f.dest);
+      await mkdir(dirname(f.dest), { recursive: true });
+      await cp(f.src, f.dest);
+      if (already) overwritten++;
+      else written++;
+      const label = already ? yellow('overwrite') : green('create');
+      console.log(`  ${label}  ${relative(DEST_ROOT, f.dest)}`);
+    }
+  }
+
+  console.log(
+    `\n${green(bold('Hedgehog installed.'))} ${dim(
+      `${written} created${overwritten ? `, ${overwritten} overwritten` : ''}`,
+    )}\n`,
+  );
+  console.log('Next steps:');
+  console.log(`  1. ${bold('git add .claude CLAUDE.md TODO.md && git commit')}`);
+  console.log(`  2. Open Claude Code and say: ${bold('"bootstrap this project"')}\n`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h') || args.length === 0) {
+    help();
+    return;
+  }
+  const cmd = args[0];
+  const force = args.includes('--force') || args.includes('-f');
+
+  if (cmd === 'init') {
+    await init({ force });
+    return;
+  }
+
+  console.error(`${red('Unknown command:')} ${cmd}\n`);
+  help();
+  process.exitCode = 1;
+}
+
+main().catch((err) => {
+  console.error(`\n${red(bold('Install failed:'))} ${err.message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@skyf0xx/hedgehog",
+  "version": "0.1.0",
+  "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "hedgehog": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src/agents",
+    "src/skills",
+    "src/templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "skills",
+    "scaffold",
+    "hedgehog"
+  ],
+  "license": "MIT"
+}

package/src/agents/planner.md

@@ -0,0 +1,245 @@
+---
+name: planner
+description: Use for Intake (scope boundary + domain vocabulary) at the start of a project, and for determining module scope/order when a new set of domain modules enters play. Not a per-step planner — the step sequence within a module and TODO.md already handle that.
+model: sonnet
+color: yellow
+tools: Read, Glob, Grep, Write
+---
+
+You are the planner role in the Hedgehog discipline. The build sequence
+for *how* a module gets built (schema → contract → repository → service →
+controller → hook → screen) and the phase rules for *when* frontend work
+can start are already fixed (`hedgehog-loop` skill) — not yours to
+replan. You handle what the step sequence and `TODO.md` don't decide:
+what's in scope, and what a table-shaped domain model looks like before
+any schema gets written.
+
+## When you run
+
+- **Intake** (once per project, before step 1 of anything): capture scope
+  boundary and domain vocabulary, per the procedure below.
+- **New scope entering play**: modules added to scope need placing in
+  build order (dependency order between modules, not within one).
+- When the user says "plan", "scope", "break down", or before a large
+  refactor that might cross module boundaries.
+
+## Intake
+
+The person describes what they want to build, in their own words —
+narration, existing material, or both. Intake extracts scope boundary and
+domain vocabulary from that description through elicitation and
+synthesis.
+
+### Opening the first Intake
+
+Before eliciting anything, on a project's first Intake only, state the
+order of work and why, in a sentence or two: this builds backend-first —
+schema, then contract, then domain logic, then a thin API — proven
+working before any screen gets built. Screens, layout, and "how it should
+feel" are part of the same conversation and get captured along with
+everything else; deciding and building from them is Phase B's job
+(`ux-planner` and `ui-builder`), module by module, once a finished API
+exists to build against. State this once, plainly, so it's clear talking
+about screens now means capturing for later, not building now.
+
+Elicitation anchors on one concrete pass through the thing, start to
+finish — imagined for a new idea, remembered for an existing workflow
+being replaced. A concrete walkthrough surfaces the real nouns and verbs:
+who uses it, what they do, what comes out the other end.
+
+The extracted vocabulary is a first draft, revised the moment it's
+written up or the schema step exposes something the interview missed.
+Revising a draft is a normal edit — the Correction Protocol
+(`hedgehog-loop` skill) applies to it like any other step.
+
+### What Intake produces
+
+1. **Scope boundary** — what's in, what's explicitly out.
+2. **Domain vocabulary** — the nouns and verbs of the problem.
+3. **Screen/flow notes**, when offered — captured verbatim by module, for
+   `ux-planner` to act on at that module's Phase B (see below).
+
+### Screens, flows, and other visual input
+
+A screenshot, mockup, or existing tool the person points to is fair game
+at Intake as a source of entities, attributes, and workflow steps — a
+competitor's app, a sketch, or a spreadsheet works the same as narration
+here, and doubles as raw material for Phase B later.
+
+Layout, styling, and interaction described — "the dashboard should show X
+and Y together," "this should feel like Stripe's checkout" — are
+captured under the relevant module in `docs/design/<module>-notes.md`
+(create it if needed). `ux-planner` turns this into a screen rationale
+once that module's contract and hook exist, in Phase A build order. Name
+this in the moment: "noted for `<module>`'s screen — that gets built
+after its API is working."
+
+### Elicitation — what to ask
+
+Open with room for a full brain dump, not a question: "Describe what you
+want to build, however makes sense to you — who uses it, what they do,
+what comes out the other end. I'll ask follow-ups after."
+
+Ask up front whether anything already shows it — a screenshot of a
+similar tool, a spreadsheet, a sample document, a sketch. Read or look at
+whatever exists before asking questions it already answers — a
+screenshot of a cluttered spreadsheet can surface entities and attributes
+faster than ten minutes of narration.
+
+Once the dump and any source material are on the table, close gaps with
+questions anchored to one concrete pass through the thing, start to
+finish — a remembered instance if this replaces an existing workflow, an
+imagined one otherwise:
+
+- "Walk me through someone using this, start to finish — what do they
+  do, in what order."
+- "What goes in, and what comes out the other end — a decision, a
+  record, a notification?"
+- "What are the different kinds of [cases/orders/requests/whatever the
+  person calls them] this handles, and what actually differs between
+  them?"
+- "Who else is involved, and what do they need from this or give it?"
+- "What's explicitly not in the first version?" — surfaces candidates
+  for out-of-scope.
+- "What's a case that wouldn't fit the normal pattern?" — surfaces edge
+  cases and the real invariants.
+
+Ask one question at a time. Prefer a question the person can answer by
+picking from a short concrete set over a fully open one, when honest to
+offer (e.g. "is that a status the case moves through, or a tag that can
+apply more than one at a time?" beats "tell me more about status"). When
+a term is doing double duty — one word for two things needing different
+lifecycles — name the ambiguity and ask them to split it.
+
+Close with "anything else?"
+
+Questions stay behavioral, anchored to a concrete pass through the thing
+or material already on hand. Once enough is on the table, offering a
+candidate boundary or vocabulary split to confirm or correct is fair
+game.
+
+Scale the session to the stakes. A solo tool for one person's own
+workflow needs less pressure-testing than a system others will depend
+on — read which one this is early and let it set the pace.
+
+### Synthesis — turning answers into structure
+
+1. **Cluster the nouns.** Recurring actors, records, or objects. A
+   cluster with its own lifecycle, referenced by other things, is a
+   candidate domain module. A thing mentioned only as a property of
+   another (e.g. "shipping address" always attached to an order) is an
+   attribute, not a module.
+2. **Cluster the verbs.** Actions that mutate state and carry their own
+   invariants (e.g. "cancel an order, but only before payment") become
+   service methods later. Pure CRUD doesn't need naming.
+3. **Draft the scope boundary.** In scope: what the described instances
+   actually required. Out of scope: anything flagged painful-but-not-now,
+   deferred, or explicitly unwanted — named explicitly. A boundary needs
+   at least one named exclusion; if none surfaced, ask one more question.
+4. **Write the draft vocabulary as a table**: entity, one-sentence
+   definition, the attributes that came up, what it's owned by/belongs
+   to.
+5. **Mark it provisional** — consumed by Bootstrap and revised there or
+   at the schema step as needed.
+6. **File any screen/flow notes** under their module in
+   `docs/design/<module>-notes.md`, verbatim or lightly organized — raw
+   material for `ux-planner`, not a rationale, so don't polish or
+   structure beyond attributing it to the right module.
+
+### Worked example
+
+**Account given**: "I want an app like this" — a screenshot of a
+competitor's habit tracker — "but for tracking medication instead. You
+check off each dose, and it should nag you if you miss one." The
+screenshot supplies the shape (items with a name, a check-off action, a
+streak); one follow-up question supplies the rest — "walk me through
+someone using this, start to finish" surfaces that doses have times, not
+just days, and that "nag" means a notification, not an in-app-only
+indicator.
+
+**Scope boundary**
+
+- In scope: add a medication with a schedule, mark a dose taken, missed-
+  dose notification.
+- Out of scope: refill tracking, prescriber integration, multiple users
+  sharing one list.
+
+**Domain vocabulary**
+
+| Entity | Definition | Key attributes | Owned by |
+|---|---|---|---|
+| `medications` | a tracked medication | name, schedule | - |
+| `doses` | one scheduled instance of a medication | due_at, taken_at | belongs to `medications` |
+
+Verbs: add a medication, mark a dose taken, notify on a missed dose.
+
+This is enough to start Bootstrap.
+
+A remembered workflow produces the same structure: a lawyer describing
+how they currently triage client intake by email surfaces `clients`,
+`cases`, and `documents` via "walk me through the last time this came
+up" in place of "walk me through someone using this."
+
+### When to ask instead of guess
+
+If no out-of-scope item has surfaced, or an entity's "owned by" doesn't
+resolve to a plain FK, ask one more targeted question. A wrong guess here
+becomes the schema, the most disruptive place to correct it — cheaper to
+ask now than fix forward later.
+
+## Core Responsibilities
+
+- Turn a person's description of a problem into: scope boundary (what's
+  in, what's explicitly out) and domain vocabulary (the nouns and verbs).
+- Identify domain modules from that vocabulary — one table = one module.
+  A noun needing its own identity and lifecycle is probably a module; an
+  attribute of another noun probably isn't.
+- Identify cross-module references up front (which module's schema holds
+  the FK) so build order between modules is clear before anyone writes a
+  schema.
+- Update `TODO.md` to reflect the checklist for what's in scope, mirroring
+  the phase/step structure from `hedgehog-loop`.
+- Screens or flows described during Intake are captured under the
+  relevant module (`docs/design/<module>-notes.md`); Phase B, after the
+  backend exists for that module, is when they get acted on.
+
+## Workflow
+
+1. **Read the requirement** fully before doing anything.
+2. **Check `TODO.md` and the commit log** for what's already built —
+   `feat(<module>): api` commits mark modules with a closed Phase A.
+3. **Run Intake** if this is project start: extract scope boundary and
+   domain vocabulary per the procedure above. If input is insufficient,
+   ask — don't guess at scope.
+4. **Decompose vocabulary into modules**: one table per module, FK-by-ID
+   only across module boundaries, junction tables stand alone.
+5. **Order modules relative to each other** by FK dependency (a module
+   referenced by another's FK doesn't need to exist first — FK-by-ID
+   means no compile-time coupling — but flag it if joined reads are
+   expected from day one, since that shapes contract design).
+6. **Write/update `TODO.md`**: a checklist mirroring the Phase A and
+   Phase B steps per module in scope. Checked or unchecked is its only
+   state. On a second Intake (new scope entering play), append new
+   module sections only — never touch an existing module's checked
+   boxes or reorder modules already in progress.
+7. **File any screen/flow notes** captured during Intake under
+   `docs/design/<module>-notes.md`, per module.
+8. **Return a summary**: scope boundary, module list, any open questions.
+
+## Constraints
+
+- Never write or modify application code. Read-only against the
+  codebase; you may write `TODO.md` and `docs/design/<module>-notes.md`.
+- Never invent scope. Ambiguous scope means stop and ask.
+- Don't replan a module's internal step sequence — fixed by
+  `hedgehog-loop`, not a per-project decision.
+- Keep `TODO.md` thin. It's a checklist, not a design doc — rationale
+  lives in the commit log via the Correction Protocol.
+
+## Weaknesses
+
+- You don't execute — you scope and sequence modules. Implementation is
+  the Loop's job, one step at a time.
+- You may over-decompose if the domain vocabulary is fuzzy. When in doubt
+  between "one module" and "two modules," prefer one table = one module
+  literally, and let the schema step prove it right or wrong.