infinity-harness 2.0.0

package/harness/docs/phases/simplify.md

@@ -0,0 +1,45 @@
+# SIMPLIFY Phase
+
+## Overview
+Reduce code complexity without changing behavior. Remove dead code, consolidate
+duplicates, flatten deep nesting, and ensure tests still pass after changes.
+
+## When to Use
+- VERIFY phase complete (optional phase — only if enabled in config)
+- Code works but has accumulated complexity during build
+
+## Craft Skills (read before working)
+- `harness/skills/codebase-design.md` — deepen modules: more behavior behind smaller interfaces
+- `harness/skills/code-review.md` — the smell baseline (what to hunt for)
+
+## Process
+1. Read `harness/progress.md` and `AGENTS.md`
+2. Run `the infinity_brief tool` to see the current step
+3. For each feature:
+   a. Review code for: code smells, deep nesting, DRY violations, dead code
+   b. Simplify: consolidate duplicate logic, flatten conditionals, remove unused
+   c. Run `npm test` to ensure tests still pass after simplification
+   d. Run `the infinity_validate tool --feature <id> --task <id>` per task
+4. When all features simplified → run `the infinity_validate tool` (full phase)
+5. If PASS → `the infinity_advance tool` to advance to REVIEW
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "It works, don't touch it" | Working code with high complexity is a liability |
+| "Simplification risks breaking things" | Tests catch breakage — that's what they're for |
+| "I'll clean up later" | Later never comes — simplify now while context is fresh |
+
+## Red Flags
+- Tests fail after simplification — you changed behavior, not just structure
+- Simplification removed more than 20% of code — may have removed needed logic
+- No tests to verify behavior preserved — add tests before simplifying
+
+## Verification
+- [ ] Code smells reduced (subjective — use judgment)
+- [ ] No new dead code introduced
+- [ ] Tests still pass: `npm test`
+- [ ] `the infinity_validate tool` passes
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Simplifier → Evaluator for REVIEW)

package/harness/docs/phases/verify.md

@@ -0,0 +1,46 @@
+# VERIFY Phase
+
+## Overview
+Independently verify that built features meet acceptance criteria. The Evaluator
+role runs tests, checks coverage, and validates behavior against the PRD.
+
+## When to Use
+- BUILD phase complete (all features pass)
+- Need to verify quality before review
+
+## Craft Skills (read before working)
+- `harness/skills/diagnosing-bugs.md` — build a feedback loop BEFORE hypothesizing about any failure
+- `harness/skills/tdd.md` — regression tests for anything you fix
+
+## Process
+1. Read `harness/progress.md`, `AGENTS.md`, and `specs/prd.md`
+2. Run `the infinity_brief tool` to see the current verification step
+3. For each feature:
+   a. Run the test suite: `npm test`
+   b. Check coverage: `{{coverageCmd}}` (if coverage gate enabled)
+   c. Verify behavior matches acceptance criteria from PRD
+   d. Run `the infinity_validate tool --feature <id> --task <id>` per task
+4. If any task fails → fix and re-validate (retry)
+5. When all features verified → run `the infinity_validate tool` (full phase)
+6. If PASS → `the infinity_advance tool` to advance to SIMPLIFY or REVIEW
+
+## Rationalizations to Avoid
+| Excuse | Rebuttal |
+|--------|----------|
+| "Build already validated, no need to re-verify" | Build validates implementation; VERIFY validates behavior |
+| "Coverage is high enough" | Check against configured threshold, not gut feeling |
+| "Edge cases are unlikely" | Unlikely ≠ impossible — test them |
+
+## Red Flags
+- Tests pass but behavior doesn't match PRD acceptance criteria
+- Coverage below configured threshold
+- Missing tests for error/edge cases
+
+## Verification
+- [ ] All tests pass: `npm test`
+- [ ] Coverage meets threshold (if gate enabled)
+- [ ] Behavior matches PRD acceptance criteria
+- [ ] `the infinity_validate tool` passes
+
+## Handoff
+On gate pass: `the infinity_advance tool` (Evaluator → Simplifier for SIMPLIFY, or Evaluator for REVIEW)

package/harness/model-router.json

@@ -0,0 +1,28 @@
+{
+  "$comment": "Optional per-task model routing. Disabled by default: every empty string means 'use whatever model pi is configured with'. Set enabled:true and fill in model ids to route cheap tasks to a small model and hard ones to a large one. Read fresh on every resolution, so edits take effect without restarting the session.",
+  "version": 1,
+  "enabled": false,
+  "default": "",
+  "byDifficulty": {
+    "easy": "",
+    "moderate": "",
+    "difficult": ""
+  },
+  "master": "",
+  "byPhase": {},
+  "byRole": {},
+  "byFeature": {},
+  "bySprint": {},
+  "byTask": {},
+  "consultation": {
+    "enabled": true,
+    "maxPerTask": 1,
+    "oneStepOnly": true,
+    "requireExhaustion": true
+  },
+  "budgets": {
+    "maxReworksPerRun": 3,
+    "maxReplansPerRun": 2,
+    "maxReviewBounces": 2
+  }
+}

package/harness/skills/README.md

@@ -0,0 +1,60 @@
+# Craft Skills
+
+How to do the work WELL — the engineering discipline behind each pipeline
+phase. The phase docs (`harness/docs/phases/`) say *what* to produce; these
+skills say *how* an expert produces it.
+
+`the infinity_brief tool` matches skills to your current task and points you at
+the right ones. Read the referenced skill BEFORE working — it is short and
+it will change what you do. Find skills yourself:
+`infinity-harness capability match "<your task>"`.
+
+## Process skills (phase-mapped)
+
+| Skill | Use during | One-liner |
+|-------|-----------|-----------|
+| `grilling.md` | DEFINE | Stress-test the spec with relentless questions |
+| `domain-modeling.md` | DEFINE | Pin down domain terms before writing code |
+| `research.md` | DEFINE, anytime | Answer questions from primary sources only |
+| `planning-tasks.md` | PLAN | Break specs into tracer-bullet vertical slices |
+| `codebase-design.md` | PLAN, SIMPLIFY | Design deep modules behind small interfaces |
+| `tdd.md` | BUILD | Red → green loop; tests worth keeping |
+| `prototype.md` | BUILD | Throwaway code that answers a design question |
+| `diagnosing-bugs.md` | VERIFY, anytime | Build a feedback loop before hypothesizing |
+| `code-review.md` | REVIEW | Two-axis review: standards + spec |
+| `resolving-merge-conflicts.md` | anytime | Resolve conflicts by original intent |
+
+## Domain skills (task-matched by tags)
+
+`databases` · `http-apis` · `auth-security` · `frontend-ui` ·
+`testing-infra` · `concurrency-async` · `performance` ·
+`error-handling-logging` · `config-and-secrets` · `cli-design`
+
+## Frontier playbook (how a strong model operates)
+
+| Skill | Delivery surface |
+|-------|-----------------|
+| `self-review.md` | Its pass runs before EVERY validate (briefs remind you) |
+| `stuck-protocol.md` | Referenced when retries fail — stop thrashing, escalate cleanly |
+| `context-hygiene.md` | Externalize discoveries the moment they happen |
+| `scope-discipline.md` | The contract is the boundary; park everything else |
+
+## The capability ladder (meta-skills)
+
+| Skill | Purpose |
+|-------|---------|
+| `capability-acquisition.md` | HAVE → ACQUIRE → CREATE → KEEP, for skills/MCP/tools |
+| `writing-skills.md` | How to author a skill worth keeping |
+| `building-mcp-servers.md` | Scaffold, fill handlers, self-test, register |
+| `building-tools.md` | Project tool standards + registration |
+
+Growing the library IS part of the job: acquired and created capabilities
+are registered (`infinity-harness capability add ...`) so the next task starts
+ahead. Export your accumulated skills across projects:
+`infinity-harness capability export`.
+
+## Attribution
+
+Skills marked "Adapted from mattpocock/skills" derive from
+[Matt Pocock's skills repository](https://github.com/mattpocock/skills)
+(MIT License, © 2026 Matt Pocock), adapted for the infinity-harness pipeline.

package/harness/skills/auth-security.md

@@ -0,0 +1,56 @@
+---
+name: auth-security
+description: Authentication, authorization, secrets, and the injection/XSS/CSRF baseline
+tags: [auth, authentication, authorization, security, login, password, token, jwt, session, oauth, secret, csrf, xss, injection, permission]
+when: task touches login, sessions, tokens, permissions, user input, or secrets
+phases: [plan, build, verify]
+provenance: { origin: built-in }
+---
+
+# Auth & Security
+
+## Rules
+
+- **Never roll your own crypto or password hashing.** Passwords: argon2id
+  or bcrypt via the platform's vetted library. Compare with constant-time
+  functions. No MD5/SHA for passwords, ever.
+- **AuthN ≠ AuthZ.** Authentication says who you are; EVERY endpoint still
+  checks what you may do — on the server, against the resource ("is this
+  order YOURS?"), not just the route. Client-side checks are UI hints only.
+- **Sessions:** httpOnly + Secure + SameSite cookies; regenerate the ID on
+  login; server-side revocation on logout/password change.
+- **JWTs (if you must):** short-lived access (≤15 min) + rotating refresh;
+  verify `alg` (reject `none`), `exp`, `aud`, `iss`; keys from env/KMS.
+  If you need instant revocation, you wanted sessions.
+- **Secrets live in the environment** (or a secrets manager) — never in
+  code, configs, logs, error messages, or git history. `.env` is
+  gitignored; ship `.env.example` with dummy values.
+- **All user input is hostile:** parameterized SQL (see `databases.md`);
+  context-aware output encoding (frameworks' default escaping — don't
+  bypass with innerHTML/dangerouslySetInnerHTML); path traversal checks on
+  any filename input; allowlists over blocklists.
+- **CSRF:** any cookie-authenticated state change needs SameSite plus a
+  CSRF token (or requires a custom header). Token-in-header APIs are
+  exempt; cookie APIs are not.
+- **Rate-limit auth endpoints** (login, reset, signup) and return uniform
+  errors — "invalid credentials", never "no such user" (enumeration).
+- **Fail closed.** Auth error / lookup failure / config missing → deny.
+
+## Anti-patterns
+
+- **Logging tokens/passwords** — scrub auth headers and bodies at the
+  logger, once, centrally.
+- **Role checks sprinkled inline** (`if user.role == "admin"`) → one
+  authorization function/policy layer, called everywhere, testable alone.
+- **Long-lived static API keys in client code** — anything shipped to a
+  browser/app is public.
+- **Home-grown password reset** — tokens must be single-use, expiring,
+  hashed at rest, invalidated on use AND on password change.
+
+## Checklist
+
+- [ ] Every state-changing endpoint has an explicit server-side authZ check
+- [ ] Secrets only via env; repo greps clean of keys (`git log -p` too)
+- [ ] Auth failures uniform + rate-limited; nothing enumerable
+- [ ] Tests include the NEGATIVE cases: wrong user, expired token, missing role
+- [ ] Dependency audit run (npm audit / pip-audit) with highs resolved

package/harness/skills/building-mcp-servers.md

@@ -0,0 +1,70 @@
+---
+name: building-mcp-servers
+description: When and how to build a project MCP server — scaffold, handlers, self-test, register
+tags: [meta, mcp, server, protocol, stdio, integration, build]
+when: a needed external-system integration has no existing MCP server
+phases: []
+provenance: { origin: built-in }
+---
+
+# Building MCP Servers
+
+## Build vs. script — decide first
+
+- Capability is **reused across sessions/tasks** and benefits from being a
+  native agent tool → build an MCP server.
+- **One-off or shell-shaped** action → a tool script is cheaper
+  (`building-tools.md`). Don't build a server to wrap one command.
+
+## Process
+
+1. **Scaffold** (a WORKING server — protocol plumbing done):
+
+   ```
+   infinity-harness capability create mcp <name>
+   → harness/mcp/<name>/server.mjs + self-test.mjs
+   ```
+
+2. **Define tools.** Edit the `TOOLS` object in `server.mjs`. Per tool:
+   - `description` written FOR the consuming model — say when to call it
+     and what comes back
+   - `inputSchema` — JSON Schema; mark required params
+   - `handler(args)` — async, returns a string
+   Keep it zero-dep if possible; if you need a client library, add it to
+   the project and pin the version.
+
+3. **Self-test until green:**
+
+   ```
+   node harness/mcp/<name>/self-test.mjs
+   ```
+
+   It runs initialize → tools/list → tools/call. Extend it with one call
+   per real tool you added.
+
+4. **Register** (adds it to the index AND every MCP client config):
+
+   ```
+   infinity-harness capability add mcp <name> --command node \
+     --args harness/mcp/<name>/server.mjs \
+     --tags db,postgres --description "Query the dev database" --trust curated
+   ```
+
+## Rules
+
+- **stdout is the protocol.** Never `console.log` in a handler — one stray
+  line corrupts the JSON-RPC stream. Log to stderr if you must.
+- **Secrets via environment** (`process.env.X`), never hardcoded, never in
+  client configs.
+- **Handlers fail soft:** return an error message string, don't throw the
+  server down.
+- **Errors are content.** A tool that errors should return actionable text
+  ("connection refused on :5432 — is the dev DB running?").
+
+## Checklist
+
+- [ ] Self-test green, one case per tool
+- [ ] No stdout pollution (run self-test — parse errors reveal it)
+- [ ] Secrets via env; version pins for any deps
+- [ ] Registered with tags + description (matcher-visible)
+- [ ] `infinity-harness capability doctor --type mcp` passes

package/harness/skills/building-tools.md

@@ -0,0 +1,60 @@
+---
+name: building-tools
+description: Project tool standards — idempotent, self-documenting, non-interactive executables
+tags: [meta, tool, script, cli, automation, executable]
+when: a repeatable action deserves a registered executable instead of ad-hoc shell
+phases: []
+provenance: { origin: built-in }
+---
+
+# Building Tools
+
+A tool is a registered executable under `harness/tools/` that future
+sessions (and other agents) can find and run. Build one when you catch
+yourself doing the same multi-step shell dance twice.
+
+## Process
+
+1. `infinity-harness capability create tool <name>` → stub at
+   `harness/tools/<name>.sh` (any language works — .mjs, .py; the stub is
+   bash).
+2. Implement to the standards below.
+3. Register:
+
+   ```
+   infinity-harness capability add tool harness/tools/<name>.sh \
+     --run "bash harness/tools/<name>.sh" \
+     --tags db,fixtures --description "Reset local db to fixtures"
+   ```
+
+## Standards (the registration bar)
+
+- **Idempotent** — running it twice is safe and converges to the same state.
+- **`--help` works** — prints usage + purpose, exits 0. (`capability
+  doctor` checks exactly this.)
+- **`--json` where output is consumed** — machine-readable when another
+  tool or agent reads the result.
+- **Exit codes:** 0 success · 1 operation failed · 2 usage error.
+- **Never interactive** — no prompts, no confirmations; flags only. An
+  unattended agent runs this at 3am.
+- **Fail loud and specific** — errors name the thing that's wrong and the
+  likely fix, on stderr.
+- **Self-contained** — resolve paths relative to the project root, not the
+  caller's cwd.
+
+## Anti-patterns
+
+- **The snowflake** — works only on the author's machine (hardcoded paths,
+  undeclared deps). Fix: check prerequisites at startup, fail with install
+  instructions.
+- **The chatterbox** — pages of output hiding the result. Fix: one summary
+  line by default, `--verbose` for the rest.
+- **The mutation surprise** — destructive with no dry-run. Fix: anything
+  destructive gets `--dry-run` and defaults to showing what it would do.
+
+## Checklist
+
+- [ ] Idempotent (ran it twice to prove it)
+- [ ] `--help` exit 0; exit codes correct
+- [ ] Registered with ≥2 tags + description
+- [ ] `infinity-harness capability doctor --type tool` passes

package/harness/skills/capability-acquisition.md

@@ -0,0 +1,72 @@
+---
+name: capability-acquisition
+description: The capability ladder — HAVE, ACQUIRE, CREATE, KEEP — for skills, MCP servers, and tools
+tags: [meta, capability, acquire, search, skill, mcp, tool, ladder, library]
+when: a task needs knowledge, system access, or an executable the project lacks
+phases: []
+provenance: { origin: built-in }
+---
+
+# Capability Acquisition — The Ladder
+
+Your task needs something the library lacks. Resolve it with the ladder —
+and register what you find so the NEXT task starts at Tier 0.
+
+## Step 1 — Decide the capability TYPE
+
+- Need **knowledge or method** (how to do X well) → a **skill**
+- Need to **interact with an external system** (DB, API, browser, tracker) → an **MCP server**
+- Need a **repeatable executable action** (reset fixtures, run a codemod) → a **tool**
+- Need a **fact** (does API X support Y?) → follow `research.md` — findings
+  saved under `docs/research/` with frontmatter become matchable facts
+
+## Step 2 — ACQUIRE: search the sources
+
+```
+the capability index "<2-4 keywords>" --type skill|mcp|tool
+```
+
+This queries the machine-queryable registries directly (npm, MCP registry,
+GitHub, crates, …). Browse-only sources are listed after — use them only
+if you have web access.
+
+**Choosing among hits** (in order): trust tier (official > curated >
+community) → actively maintained → widely used → known author →
+permissive license (MIT/Apache/BSD) → small and composable. NEVER adopt a
+framework that wants to own your whole process — the harness owns the
+process.
+
+**Adapt, don't adopt.** Whatever you take: trim it to the useful core,
+re-point references to harness surfaces (DOMAIN.md, feature-list,
+learn/decision), add an attribution line (source + license), then register:
+
+```
+infinity-harness capability add skill <path> --from <url>
+infinity-harness capability add mcp <name> --command npx --args -y,<pkg>@<exact-version> \
+  --tags ... --description "..." --trust curated
+infinity-harness capability add tool <file> --run "..." --tags ... --description "..."
+```
+
+**MCP security (hard rules):** pin exact versions (`pkg@1.2.3`, never
+`@latest`); community-tier servers need `--force` after you review their
+source; secrets go through env indirection, never into configs.
+
+## Step 3 — CREATE: nothing usable exists
+
+```
+infinity-harness capability create skill|tool|mcp <name>
+```
+
+- skill → fill the stub per `writing-skills.md`
+- tool → implement per `building-tools.md`
+- mcp → the scaffold is a WORKING server; fill in handlers per
+  `building-mcp-servers.md`, verify with its self-test, then register
+
+## Step 4 — Budget and fallback (never block the pipeline)
+
+Acquisition fits ONE working session. If the search didn't conclude, or you
+have no network:
+
+1. Record the gap: `harness/lessons-decisions.md "capability gap: <what was needed>"`
+2. Proceed with general best practices — a missing skill is not a blocked task
+3. The gap resurfaces via `infinity-harness capability gaps` for a later pass

package/harness/skills/cli-design.md

@@ -0,0 +1,55 @@
+---
+name: cli-design
+description: Command-line tool design — argument conventions, output contracts, exit codes, composability
+tags: [cli, command, terminal, flags, arguments, stdout, stdin, shell, script, tool]
+when: task builds or extends a command-line interface
+phases: [plan, build]
+provenance: { origin: built-in }
+---
+
+# CLI Design
+
+## Rules
+
+- **stdout is the product; stderr is the commentary.** Results (the thing
+  a pipe consumes) go to stdout; progress, warnings, and errors go to
+  stderr. Mixing them breaks every script that consumes you.
+- **Exit codes are the API:** 0 success · 1 operation failed · 2 usage
+  error. Scripts branch on these; a CLI that exits 0 on failure is lying
+  to automation.
+- **`--help` on everything**, including subcommands: one-line purpose,
+  usage line, every flag with its default. Help exits 0; unknown flags
+  exit 2 naming the flag and suggesting help.
+- **Machine mode:** `--json` emits one parseable object/line to stdout
+  with a stable shape — additive changes only; renames are breaking
+  changes. (Agents and scripts are your biggest users.)
+- **Non-interactive by default.** Prompts hang cron jobs and agents. Take
+  input via flags/stdin; destructive actions get `--dry-run` (show, don't
+  do) and require `--force` instead of asking "are you sure?".
+- **Follow the grain:** `tool <noun> <verb>` or `tool <verb>` —
+  consistently; flags kebab-case with `--long` forms; `-` means stdin/
+  stdout where files are expected; respect `NO_COLOR` and non-TTY (no
+  spinners into pipes).
+- **Errors say what + why + what next:** `✗ config not found:
+  harness/config.json — run: infinity-harness init`. Never a bare stack trace
+  for an expected failure.
+- **Fast startup matters.** A CLI invoked in loops pays its startup cost
+  ×N — lazy-load heavy imports per subcommand.
+
+## Anti-patterns
+
+- **Chatty stdout** — banner + tips drowning the result → result only;
+  decorations to stderr or behind `--verbose`.
+- **Boolean flags taking values** (`--force true`) → presence = true.
+- **Positional soup** (`tool a b c d`) — 3+ positionals nobody remembers →
+  named flags for all but the primary argument.
+- **Config file required to run at all** → flags work standalone; config
+  file provides defaults, flags override.
+
+## Checklist
+
+- [ ] Piping stdout to a file captures exactly the result, nothing else
+- [ ] Exit codes verified: success=0, failure=1, bad usage=2
+- [ ] `--json` output parses and has a documented shape
+- [ ] Runs unattended: zero prompts anywhere
+- [ ] Every destructive path has --dry-run and needs --force

package/harness/skills/code-review.md

@@ -0,0 +1,57 @@
+---
+name: code-review
+description: Two-axis review (spec fidelity + standards/smells) with the Fowler smell baseline
+tags: [review, quality, smell, refactor, standards, spec, diff, audit]
+when: reviewing a diff, a branch, or the whole delivery before shipping
+phases: [review, simplify]
+provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
+---
+
+# Code Review — Two Axes
+
+> Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT © Matt Pocock).
+> Use during: REVIEW (whole-delivery review) and when reviewing any diff.
+
+Review the diff since a fixed point along two independent axes. Never merge
+them — a change can pass one and fail the other, and one axis must not mask
+the other.
+
+- **Spec axis** — does the code faithfully implement what was asked?
+- **Standards axis** — does the code follow this repo's conventions and
+  avoid the smell baseline below?
+
+## Process
+
+1. **Pin the fixed point.** `git diff <fixed-point>...HEAD` (three-dot) and
+   `git log <fixed-point>..HEAD --oneline`. In the harness pipeline the fixed
+   point is usually the phase-start or sprint-start commit/tag
+   (`infinity-harness rollback list` shows checkpoints).
+2. **Spec review.** The spec sources are `specs/prd.md`, the sprint contract
+   (`harness/sprint-contract.md`), and the feature list's acceptance
+   criteria. Report: (a) requirements missing or partial; (b) behaviour
+   nobody asked for (scope creep); (c) requirements that look implemented
+   but wrong. Quote the spec line for each finding.
+3. **Standards review.** Sources: the repo's documented conventions
+   (CONTRIBUTING, lint config, `harness/docs/CONSTRAINTS.md`) plus the smell
+   baseline below. Documented repo standards override the baseline; skip
+   anything tooling already enforces. Smells are judgement calls — label
+   them, don't treat them as violations.
+4. **Report both axes separately**, then fix what's real. Fill in
+   `harness/evaluator-rubric.md` with evidence, not vibes.
+
+## Smell baseline (Fowler, Refactoring ch. 3)
+
+Each reads *what it is* → *how to fix*:
+
+- **Mysterious Name** — name doesn't reveal what it does/holds → rename; if no honest name comes, the design is murky.
+- **Duplicated Code** — same logic shape in more than one place → extract the shared shape.
+- **Feature Envy** — a method reaches into another object's data more than its own → move it onto the data it envies.
+- **Data Clumps** — the same few fields/params keep travelling together → bundle into one type.
+- **Primitive Obsession** — a primitive standing in for a domain concept → give the concept its own type.
+- **Repeated Switches** — same switch/if-cascade recurs → polymorphism or one shared map.
+- **Shotgun Surgery** — one logical change forces scattered edits everywhere → gather into one module.
+- **Divergent Change** — one module edited for several unrelated reasons → split it.
+- **Speculative Generality** — abstraction for needs the spec doesn't have → delete it.
+- **Message Chains** — long `a.b().c().d()` navigation → hide the walk behind one method.
+- **Middle Man** — a thing that mostly delegates onward → cut it.
+- **Refused Bequest** — an implementer ignoring most of what it inherits → composition over inheritance.

package/harness/skills/codebase-design.md

@@ -0,0 +1,70 @@
+---
+name: codebase-design
+description: Deep modules — small interfaces hiding lots of behavior, seams, testability
+tags: [design, architecture, module, interface, seam, refactor, coupling, abstraction, api]
+when: designing module boundaries, planning features, refactoring for clarity
+phases: [plan, simplify]
+provenance: { origin: "mattpocock/skills", license: MIT, adapted: true }
+---
+
+# Codebase Design — Deep Modules
+
+> Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT © Matt Pocock).
+> Use during: PLAN (shaping features into modules) and SIMPLIFY (finding deepening opportunities).
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed
+at a clean seam, testable through that interface.
+
+## Vocabulary (use these terms exactly)
+
+- **Module** — anything with an interface and an implementation: a function,
+  class, package, or tier-spanning slice. (Avoid: unit, component, service.)
+- **Interface** — everything a caller must know to use the module correctly:
+  the signature, plus invariants, ordering constraints, error modes, config,
+  performance characteristics. (Avoid: API — too narrow.)
+- **Seam** — a place where you can alter behaviour without editing in that
+  place; where a module's interface lives. (Avoid: boundary.)
+- **Adapter** — a concrete thing that satisfies an interface at a seam.
+- **Depth** — leverage at the interface: how much behaviour a caller (or
+  test) can exercise per unit of interface they must learn.
+
+## Deep vs shallow
+
+```
+Deep (aim for this):          Shallow (avoid):
+┌───────────────┐             ┌───────────────────────────────┐
+│ Small interface│            │        Large interface        │
+├───────────────┤             ├───────────────────────────────┤
+│               │             │      Thin implementation      │
+│  Deep impl    │             └───────────────────────────────┘
+│               │
+└───────────────┘
+```
+
+When designing an interface, ask: Can I reduce the number of methods? Can I
+simplify the parameters? Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep
+  module can be internally composed of small parts — they just aren't part
+  of the interface.
+- **The deletion test.** Imagine deleting the module. If complexity
+  vanishes, it was a pass-through. If complexity reappears across N callers,
+  it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same
+  seam. If you want to test *past* the interface, the module is probably
+  the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.**
+  Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+1. **Accept dependencies, don't create them.**
+   `processOrder(order, paymentGateway)` — testable.
+   `processOrder(order)` that news up `StripeGateway()` inside — not.
+2. **Return results, don't produce side effects.**
+   `calculateDiscount(cart): Discount` — testable.
+   `applyDiscount(cart): void` that mutates — harder.
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params
+   = simpler test setup.