interface:
  display_name: "Codebase Design"
  short_description: "Shared vocabulary for designing deep modules and clean seams"
  default_prompt: "Use $codebase-design to design or improve this module's interface."

# Deepening

How to deepen a cluster of shallow modules safely, given its dependencies.
Assumes the vocabulary in [../SKILL.md](../SKILL.md) — **module**, **interface**,
**seam**, **adapter**.

## Dependency categories

When assessing a candidate for deepening, classify its dependencies. The
category determines how the deepened module is tested across its seam.

### 1. In-process

Pure computation, in-memory state, no I/O. Always deepenable — merge the
modules and test through the new interface directly. No adapter needed.

### 2. Local-substitutable

Dependencies that have local test stand-ins (PGLite for Postgres, in-memory
filesystem). Deepenable if the stand-in exists. The deepened module is tested
with the stand-in running in the test suite. The seam is internal; no port at
the module's external interface.

### 3. Remote but owned (Ports & Adapters)

Your own services across a network boundary (microservices, internal APIs).
Define a **port** (interface) at the seam. The deep module owns the logic; the
transport is injected as an **adapter**. Tests use an in-memory adapter.
Production uses an HTTP/gRPC/queue adapter.

Recommendation shape: *"Define a port at the seam, implement an HTTP adapter
for production and an in-memory adapter for testing, so the logic sits in one
deep module even though it's deployed across a network."*

### 4. True external (Mock)

Third-party services (Stripe, Twilio, etc.) you don't control. The deepened
module takes the external dependency as an injected port; tests provide a mock
adapter.

## Seam discipline

- **One adapter means a hypothetical seam. Two adapters means a real one.**
  Don't introduce a port unless at least two adapters are justified (typically
  production + test). A single-adapter seam is just indirection.
- **Internal seams vs external seams.** A deep module can have internal seams
  (private to its implementation, used by its own tests) as well as the
  external seam at its interface. Don't expose internal seams through the
  interface just because tests use them.
- **Hexagonal direction.** The core offers its interface to callers and declares
  the capability it requires from the outside; locate both interface decisions on
  the core side of the seam. Adapters depend toward the core, while core code must
  not import infrastructure, framework, storage, clock, or protocol details.
  Adapters translate those external details and do not duplicate business rules;
  composition selects adapters. Keep a one-adapter case local, and let a simple
  module expose its handler directly.

## Testing strategy: replace, don't layer

- Old unit tests on shallow modules become waste once tests at the deepened
  module's interface exist — delete them.
- Write new tests at the deepened module's interface. The **interface is the
  test surface**.
- Tests assert on observable outcomes through the interface, not internal
  state.
- Tests should survive internal refactors — they describe behaviour, not
  implementation. If a test has to change when the implementation changes,
  it's testing past the interface.

# Design It Twice

When the user wants to explore alternative interfaces for a chosen deepening
candidate, use this parallel sub-agent pattern. Based on "Design It Twice"
(Ousterhout) — your first idea is unlikely to be the best.

Uses the vocabulary in [../SKILL.md](../SKILL.md) — **module**, **interface**,
**seam**, **adapter**, **leverage**.

Offerable in two places: standalone, or mid-interview as a grounding step —
when `scope`'s interview mode (`skills/workflows/scope/references/interview.md`) hits an
interface-shape frontier question, this can run right there, the same way
that file's `ground it` escape hatch grounds a question before re-asking it.

## Process

### 1. Frame the problem space

Before spawning sub-agents, write a user-facing explanation of the problem
space for the chosen candidate:

- The constraints any new interface would need to satisfy
- The dependencies it would rely on, and which category they fall into (see
  [DEEPENING.md](DEEPENING.md))
- A rough illustrative code sketch to ground the constraints — not a proposal,
  just a way to make the constraints concrete

Show this to the user, then immediately proceed to Step 2. The user reads and
thinks while the sub-agents work in parallel.

### 2. Dispatch parallel design alternatives

The coordinator supplies the selected adapter, explicit design-agent model, and
explicit design-agent effort. Pass model and effort unchanged to every design
worker. This procedure does not select an adapter, model, or effort, apply a
routing table or headroom policy, or add defaults.

Dispatch only through `skills/drivers/orchestrate/scripts/codex-worker.py` or
`skills/drivers/orchestrate/scripts/claude-worker.py`, using the selected
adapter's read-only surface. Never use the built-in Agent tool, Workflow tool,
or background-agent machinery.

Create one coordinator-owned `<session-scratch>/design-it-twice/` directory.
For alternative `<n>`, write its complete independent technical brief to
`design-<n>.prompt.md`; use `design-<n>.json` as that worker's state file; and
capture its launcher stdout and stderr in `design-<n>.stdout` and
`design-<n>.stderr`. The coordinator passes the contents of
`design-<n>.prompt.md` as the adapter's positional prompt text. State files
carry lifecycle metadata only; successful design output comes from each
launcher's stdout `final_message`.

Start alternatives 1, 2, and 3 through the selected adapter before waiting on
any launcher, retaining each launcher PID and joining each individually. Each
worker receives its separate technical brief and one different constraint:

- Alternative 1: "Minimize the interface — aim for 1–3 entry points max.
  Maximise leverage per entry point."
- Alternative 2: "Maximise flexibility — support many use cases and extension."
- Alternative 3: "Optimise for the most common caller — make the default case
  trivial."
- Alternative 4, when applicable: "Design around ports & adapters for
  cross-seam dependencies."

Include both [../SKILL.md](../SKILL.md) vocabulary and CONTEXT.md vocabulary
in every brief. Each worker must not modify, patch, or stash.

Each worker outputs:

1. Interface (types, methods, params — plus invariants, ordering, error modes)
2. Usage example showing how callers use it
3. What the implementation hides behind the seam
4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
5. Trade-offs — where leverage is high, where it's thin

On one nonzero completion, use the selected adapter's `resume` surface once
against that alternative's same state file. If it still does not produce a
successful `final_message`, mark that alternative unavailable. With two or more
successful alternatives, present and compare the available designs, naming every
unavailable alternative. With zero or one successful alternative, report that
the design-it-twice pass did not produce enough alternatives and return to the
interface-shape frontier; do not recommend a design.

### 3. Present and compare

Present designs sequentially so the user can absorb each one, then compare
them in prose. Contrast by **depth** (leverage at the interface), **locality**
(where change concentrates), and **seam placement**.

After comparing, give your own recommendation: which design you think is
strongest and why. If elements from different designs would combine well,
propose a hybrid. Be opinionated — the user wants a strong read, not a menu.