@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/board-to-waves/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: board-to-waves
+disable-model-invocation: false
+description: >-
+  Use when sweeping/grooming the GitHub backlog board to cluster open issues
+  into thematic waves (Wellen) — "lass uns das Board durchgehen", "was ist
+  offen und passt zusammen", "clustern wir den Backlog", "welche Wellen stecken
+  da drin" — or to spot candidate waves before planning. Reads all open issues,
+  groups them by the Gate+Booster+Splitter heuristic, estimates size/risk +
+  grill-needed per candidate, and after the user confirms creates
+  cluster/Wave-less candidate STUB issues with a To-Do checklist. STOPS at
+  stubs: no PRD, no slicing, no sub-issue links, no promotion (downstream:
+  to-prd matures the stub, to-issues slices + promotes). NOT for
+  maturing/slicing ONE already-chosen candidate (to-prd/to-issues), NOT for
+  per-issue triage labelling (triage), NOT for code comprehension (zoom-out) —
+  this is board-WIDE thematic affinity grouping, not per-issue and not
+  code-reading.
+---
+
+# board-to-waves
+
+**Survey the board → cluster open issues by theme → anchor stub issues.** Systematizes how Welle F came about: first look at what's open and what fits together, then form thematic waves. Result lands durably as an anchor issue on the board (GitHub = SSOT), not as a chat list.
+
+## Pipeline Position
+
+```
+board-to-waves   Board → candidate STUB issues (cluster/wave-less, size + grill-needed flag)   ← HERE
+                         ↓ (<maintainer> picks waves)
+[optional]       dedicated grill-with-docs session — only if the flag fires
+                         ↓
+to-prd           matures the stub into a Draft PRD (Mode B)
+                         ↓
+to-issues        slices + promotes (sets type:cluster + Wave at ≥2 slices)
+```
+
+**Stops at stubs.** No slice plan, no PRD, no sub-issue link, no promotion. Whether/when a stub becomes a real wave = separate step (`to-prd → to-issues`), <maintainer>'s call.
+
+**S4 exit — no stub at all.** A candidate that trips the `scale-check` altitude criteria (Splitter S4 below) skips the stub step entirely — it is reported as an escalation, pointing at `scale-check` (→ a program grill → `to-prd` program mode → `to-waves`), never at `to-prd`/`to-issues` directly. Still <maintainer>'s call, still no board write here.
+
+Model: **strongest available reasoning model for board-wide judgment calls** (survey/plan/brainstorm — cross-board judgment, <maintainer>'s table).
+
+## Wave Numbering & Registry
+
+**Format:** `Welle <N> — <Thema>` (hybrid: number orders, topic gives context). **The wave number is only assigned at `to-issues` promotion** — the board-to-waves candidate stub is cluster/wave-less and carries **no** `Welle <N> —` prefix in the title yet (`to-issues` sets it on promote).
+**Carrier = Wave field (number)** on the **anchor** (mandatory — source of truth + board sort key, set at promotion). NOT the title string, NOT the `wave:*` label (both deprecated for waves). Member/sub-issues get the Wave field + native parent link at `to-issues` promotion (not yet at clustering time): the parent link carries the assignment semantically, the Wave field makes it board-filterable — without the Wave field an assigned issue wrongly shows up in the "wave-less" view (`is:open no:wave -label:"type:cluster"`).
+**N = monotonic auto-increment ID:** `max(assigned wave numbers) + 1`. Ascending, never reused, never letters, never retroactively resorted (like issue numbers). Gaps are fine. `to-issues` pulls the next free number at promotion via the shared board-sync helper (`scripts/board-sync.py` `next-wave`) — board-to-waves itself assigns **no** wave.
+
+**Registry = board-native, no doc file:** view filter `type:cluster`, sort `Wave` ascending, columns Status + sub-issues progress. The anchor issues + Wave field **are** the registry. Active wave = `type:cluster` + the in-progress-role status. Wave field ≠ `Cluster (G-number)` field (roadmap G-cluster, orthogonal). No milestones (progress comes from the sub-issue rollup).
+
+## Clustering Heuristic — Gate + Booster + Splitter
+
+**🚦 Gate (mandatory — without it, no wave, just a pile):** shared **through-line / outcome**. The issues must serve *one* product outcome (e.g. "market/partner readiness" = Welle F).
+
+**➕ Boosters (the more that fire, the clearer a wave):**
+| # | Criterion | Board signal |
+|---|---|---|
+| B1 | Code proximity / change coupling | same files/paths in issue bodies; historically co-changed (`git log`) |
+| B2 | Type homogeneity | same `type:*` / `dimension:*` labels |
+| B3 | Dependency chain | **native blocked-by edges** (`python3 scripts/board-sync.py deps <#>` — the blocking SSOT); secondary: `blocked` label, "blocked by" / mutual body refs (the body section is only the machine mirror) |
+| B4 | Shared verify surface | same page/surface live-testable |
+
+**✂️ Splitters (separate DESPITE affinity):**
+- **S1 Too big** — > ~7 slices / not shippable in a manageable sequence → split into two waves.
+- **S2 Foreign parent** — issue already hangs under another wave (GitHub 1-parent; `to-issues` link check is the final word).
+- **S3 "Same type alone" ≠ wave** — type is a booster, never a gate. Otherwise "all refactors" becomes a junk drawer.
+- **S4 Programm-Verdacht** — the candidate trips the `scale-check` altitude criteria (`.claude/skills/scale-check/SKILL.md` § "Altitude criteria (the single source of truth)" — referenced here, **never** re-forked; e.g. staged delivery + several subsystems that each stand on their own) → **escalate to the Program route instead of creating a candidate stub**: report it in the candidate list (§3/§5) pointing at `scale-check` (grill once into a Program-PRD with a Wellenplan, then `to-waves` unfolds it), not `to-prd`/`to-issues`. The bottom-up Wave-stamping rule above is unaffected — an escalated candidate is still just a proposal, not yet a committed wave, exactly like any other candidate.
+
+**Rule:** issue → candidate X if **Gate(X) satisfied AND ≥1 booster fires** and no splitter applies. Otherwise: own candidate or leftover bucket "unclustered / standalone issue".
+
+**Sequencing WITHIN a wave** (belongs to `to-issues`, noted here only): WSJF-lite — visible+low-risk → logic/backend → cleanup; dependencies force order.
+
+> References: Atlassian/Mountain Goat (epics/themes), CodeScene/Tornhill (change coupling), SAFe (WSJF), ProductPlan/Asana (affinity/batching).
+
+## Size + `grill-needed` (per candidate)
+
+- **Size + risk** as a rough effort estimate (no fixed time commitment): rough slice count, backend yes/no, model mix, risk level (race/cache/forecast/migration → high).
+- **`grill-needed` flag** — fires when: many slices OR fuzzy (members are `type:idea`/`type:research`, undecided) OR cross-subsystem OR open product decisions. = low decision maturity.
+  - **"this session"** when manageable, **"own session"** when too big/fuzzy to do on the side. Recommendation goes into the stub, **<maintainer>'s call**.
+
+## Procedure
+
+### 1. Read the board
+```bash
+gh issue list --repo <owner>/<repo> --state open --limit 500 \
+  --json number,title,labels,body
+```
+`--limit 500` (item/issue-list caps **silently**, `docs/agents/board-sync.md`). Already-parented issues get recognized later at link time — title/labels/body suffice here.
+
+### 2. Cluster
+Apply the heuristic. Per candidate, capture: topic (gate outcome), members (#…), firing boosters, splitter checks, size+risk, `grill-needed`+when. Issues that reach no gate+booster → leftover bucket, **do not** force-cluster.
+
+### 3. Propose candidates (<maintainer> chooses)
+Concise list, per candidate **which criteria fired** visible (rationale):
+```
+Candidate A "<Outcome>": #a #b #c
+  Gate=<Outcome> · B1 all frontend · B2 all type:refactor
+  Size ~4 slices, risk low · grill-needed: no
+Candidate B "<Outcome>": #x #y …
+  … · grill-needed: yes (own session — cross-subsystem)
+Candidate C "<Outcome>": #p #q #r #s …
+  … · trips scale-check C1+C2 → Programm-Verdacht (S4) — escalate to `scale-check`, no stub here
+Rest (unclustered): #m #n …
+```
+**<maintainer> confirms** which become real waves. Only confirmed → step 4 (an S4-flagged candidate is routed to `scale-check` instead, not step 4).
+
+### 4. Create candidate stubs (per confirmed candidate)
+Body from `docs/agents/wave-anchor-template.md` **stage 1** (header + cluster origin + to-do checklist; slice table empty). Body **always** via `--body-file` (`gotchas_gh_body_file`).
+
+**All board write mechanics (create stub, attach to board, stamp status) go through the shared board-sync helper** `scripts/board-sync.py` — no bare `gh issue create`/`gh project item-*` in this prose (enforced by lint; board constants live in `docs/agents/board-sync.md`).
+
+**Idempotency — stub marker + search-before-create (mandatory, BEFORE `create`).** Re-runs of board-to-waves must **not** produce duplicate stubs (a duplicate stub would confuse Mode-B identity in `to-prd`). Mirrors the `to-prd` pattern:
+- **Stable stub marker** `<!-- wave-stub-source: <topic-slug> -->` as the **first body line** of every stub. `<topic-slug>` = kebab-case slug of the gate outcome; set on the **first** run, **never** changed after (identity ≠ content — the slug stays findable even if members/size change later).
+- **search-before-create** per candidate **before** the `create`. **No** reliance on GitHub search (doesn't index HTML comments) — bounded, local:
+  ```bash
+  gh issue list --repo <owner>/<repo> --state open --limit 500 --json number,body,labels
+  # locally filter on `wave-stub-source: <topic-slug>` → 1 match ⇒ skip + report (stub exists); >1 ⇒ STOP + report; 0 ⇒ create
+  ```
+
+**Create the candidate stub (cluster/wave-less)** — issue **without** `type:cluster` and **without** `--wave` (exactly one `type:*` + one `priority:*`; title **without** a `Welle <N>` prefix, since the wave number is only assigned at promotion), **with `--wave-stub`** (a searchable "awaiting planning" filter — the HTML marker above is only locally greppable, GitHub doesn't index it), attach to the board, triaged-role status (clustered, not yet planned). `to-prd` then matures the stub (Mode B) into a Draft PRD, `to-issues` promotes it to an anchor (sets `type:cluster` + Wave then, **strips `wave-stub`** — the stub leaves the planning list):
+```bash
+python3 scripts/board-sync.py create \
+  --title "<Outcome/Thema>" \
+  --body-file <stub.md> \
+  --label "type:feature" --label "priority:medium" \
+  --wave-stub \
+  --status-role triaged
+```
+Outputs `#<STUB_NUM> <URL>`. `--dry-run` shows the `gh` calls without writing. (Fuzzy/undecided candidate → `type:research` instead of `type:feature`.)
+
+**Search open stubs** (= "what still needs planning"): `gh issue list --label wave-stub --state open` or board filter `is:open label:wave-stub`. At `to-issues` promotion (wave) **or** atomic publish (`add --bucket`), `wave-stub` is stripped automatically — no manual edit.
+
+**Member issues:** list in the stub body (#…). **No** wave stamp and **no** native parent link yet at clustering time — `to-issues` sets both at promotion. That members show up in the "wave-less" view (`is:open no:wave`) until then is **correct**: a candidate isn't a committed wave yet.
+
+### 5. Output
+```
+Clustered: <N> wave candidates, <M> confirmed → cluster/wave-less stubs created.
+  Candidate <X> #<STUB_NUM> — #a #b #c · ~4 slices · grill: no
+  Candidate <Y> #<…>       — #x #y   · ~8 slices · grill: own session
+Escalated (Programm-Verdacht, S4): #<p> #<q> … — routed to `scale-check`, no stub created
+Rest (unclustered): #m #n …
+Next step (<maintainer>'s call, separate): grill → to-prd (matures the stub) → to-issues (slices + promotes) per chosen candidate; an escalated candidate instead starts at `scale-check`.
+```
+
+## Notes
+- **Stops at stubs.** Never write the PRD, slice, link, promote, or call `to-prd`/`to-issues` yourself.
+- Boundary: `triage` = per-issue state machine; `zoom-out` = code comprehension; `board-to-waves` = board-wide thematic affinity. Different altitudes.
+- A leftover bucket is OK and intentional — not every issue belongs in a wave. Force-clustering dilutes the gate.
+- Size/risk are a rough estimate, not a commitment. <maintainer> can override the stub's "when to grill" recommendation at any time.

package/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: code-review
+description: Review a diff, branch, or PR against two separate axes — Standards (this repo's own conventions plus a Fowler-smell baseline) and Spec (does the diff faithfully implement the originating issue/PRD) — reported side by side, never merged or re-ranked. Runs a three-dot merge-base preflight before either axis starts. Use when asked to review a diff/branch/PR, or when a review needs to answer both "does this follow our standards" and "does this match the spec" without one masking the other. NOT for a pre-code plan review (that reviews a plan before any code exists), NOT for root-causing a known bug (`diagnose`), and NOT a pure reuse/simplification/efficiency pass (narrower, no bug-hunting).
+---
+
+# Code Review
+
+A code-review compares one diff against **two independent axes** — Standards and Spec — and reports them **separately**. A diff can pass one axis and fail the other: code that satisfies every convention but builds the wrong thing is a Standards-pass/Spec-fail; code that nails the issue but breaks conventions is a Spec-pass/Standards-fail. Merge or re-rank the two and one axis silently masks the other — that is the exact failure mode this method exists to prevent.
+
+## When this and not another skill
+
+| You are reviewing… | Use |
+|---|---|
+| "Review this diff/branch/PR against our standards AND the spec." | **code-review** |
+| "Review this plan before any code is written." (adversarial pre-code review) | a plan-review / adversarial-review skill |
+| "Why is this broken / slow?" (root-cause of a known defect) | `diagnose` |
+| "Clean this up — reuse, simplify, cut waste." (no bug-hunting) | a dedicated simplification pass |
+
+## Preflight (fail-fast, before either axis starts)
+
+1. **Fixed point** — whatever the requester names: a SHA, branch, tag, `main`, `HEAD~N`. Missing → ask; do not guess.
+2. **Three-dot diff against the merge-base** — `git diff <fixed-point>...HEAD` (three dots, not two — two dots diffs tip-to-tip and pulls in unrelated upstream changes), plus the commit list: `git log <fixed-point>..HEAD --oneline`.
+3. **Validate before working** — `git rev-parse <fixed-point>` must resolve, and the diff must be non-empty. A bad ref or an empty diff fails **here**, not silently inside a parallel sub-agent.
+
+## Axis 1 — Standards
+
+**Sources.** This repo's own documented conventions: a root convention file (`CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md` — whichever this repo uses), any per-package convention files in a monorepo, a `docs/conventions/` folder. If `docs/agents/code-review.md` exists (this skill's project layer, seeded by `/setup-workflow`), read it first — it names exactly which sources count here and how this method relates to any other review tooling already running in this environment. Absent that file, gather the sources yourself from the repo root before reviewing.
+
+**Plus a Fowler-smell baseline** (*Refactoring*, ch. 3) — applies even when the repo documents nothing. Each smell is a **judgment call** (flag as "possible X"), never a hard violation:
+
+- **Mysterious Name** — a name that does not say what it does/holds → rename; a dishonest name hides a murky design.
+- **Duplicated Code** — the same logic shape in ≥2 hunks/files → extract, have both call it.
+- **Feature Envy** — a function reaches into another module's data more than its own → move it to the data it envies.
+- **Data Clumps** — the same fields always travel together → bundle them into one type.
+- **Primitive Obsession** — a primitive/string standing in for a domain concept → give it its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurring across the diff → polymorphism or a shared map.
+- **Shotgun Surgery** — one logical change forces edits scattered across many files → consolidate into one module.
+- **Divergent Change** — one module edited for many unrelated reasons → split it, one reason per module.
+- **Speculative Generality** — an abstraction/hook built for a need the spec does not have → delete it, inline until real demand exists.
+- **Message Chains** — a long `a.b().c().d()` → hide it behind one method on the first object.
+- **Middle Man** — a class/function that only delegates onward → cut it out, call directly.
+- **Refused Bequest** — a subclass ignoring most of what it inherits → drop inheritance, use composition.
+
+**Two binding rules:** (1) **A documented repo standard overrides the baseline** — if the repo's own conventions explicitly sanction something the baseline would flag, suppress the flag. (2) **Skip what tooling already enforces** — a type checker, linter, or CI guard catches that class of issue mechanically; the review does not re-derive it.
+
+## Axis 2 — Spec
+
+**Source.** The originating issue/PRD, resolved through this project's issue-tracker workflow (`docs/agents/issue-tracker.md`, seeded by `/setup-workflow`) — pull the issue reference from the commit messages or the PR description. No issue reference → ask the requester for the spec path. No spec exists at all → report this axis as "no spec available" and skip it; never invent requirements to check against.
+
+**Taxonomy**, each finding cited against a specific spec line:
+- (a) **Missing/partial** — requirements the spec asks for that are absent or only half-built.
+- (b) **Scope creep** — behavior in the diff the spec never asked for.
+- (c) **Looks-right-but-wrong** — requirements that appear implemented but diverge from what the spec actually says on inspection.
+
+## Execution
+
+- Run both axes as **parallel sub-agents** — separate context each, so neither poisons the other's read. Give the Standards sub-agent the Standards sources **plus** the full Fowler baseline in its prompt; it has no other way to see the baseline.
+- Report **side by side**, under `## Standards` and `## Spec` headers, verbatim or lightly cleaned — never merge or re-rank the two into one combined verdict.
+- Cap each sub-agent's report under 400 words — findings, not padding.
+- Close with a findings count **per axis** and the single worst issue **per axis** — never a cross-axis "winner"; picking one would be exactly the re-ranking this method exists to prevent.
+
+## Relationship to adjacent review tooling
+
+This skill governs one thing: a diff/branch/PR review split into Standards vs. Spec. It is not the only review-shaped tool an environment may have — a pre-code plan-review loop, a security-specific audit, a pure reuse/simplification pass, or a dedicated reviewer subagent can all coexist with it; each stays its own axis, not a replacement for this one. If this repo has seeded `docs/agents/code-review.md`, it names the concrete adjacent tools and how they relate; absent that, treat any other review tool you find as complementary unless it explicitly says otherwise.

package/.claude/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# 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.
+
+## 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.

package/.claude/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# 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**.
+
+## 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. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent 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
+
+### 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.

package/.claude/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+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, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its 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
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/.claude/skills/codebase-design/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/codebase-design` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.claude/skills/codex-build/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: codex-build
+description: Hand a frozen spec (PLAN.md or any locked plan) to OpenAI Codex to IMPLEMENT inside a bounded workspace-write sandbox, while Claude stays the spec-writer and reviewer — the exact role-flip of /codex-review. Codex builds from the spec against a declared allowed-write set, Claude reads the full diff like a contributor PR, runs the proof test, and iterates fixes via the SAME Codex session up to MAX_FIX_ROUNDS before taking over. Human approves the diff before any commit. Use when the user says "/codex-build", "have codex build this", "codex implement the plan", "hand the plan to codex", "delegate the build to codex", or right after a plan survives /grill-me-codex, /grill-with-docs-codex, or /codex-review and they choose Codex for implementation (Act 3). Also for standalone delegation — refactors, mechanical migrations, bug fixes with a known repro, test/coverage writing — anything that reads as a work order. NOT for tiny edits (~<20 lines — delegation overhead loses), NOT for design work (if writing the spec forces decisions, that's /grill-me-codex first), NOT for reviewing existing code (/codex:review), and NOT for anything needing Claude-session tools (MCP, secrets, browser).
+---
+
+# Codex-Build — Codex Types, Claude Verifies
+
+> **Local adaptation note:** adapted from Chase AI's `codex-build` (which itself adapts Peter Steinberger's `codex-first` pattern). Upstream runs Codex with `--yolo` / full access; this fork deliberately does NOT — Codex writes inside a **workspace-write sandbox** against a **declared allowed-write set**, never `danger-full-access`, and the approval policy is never weakened. See `THIRD-PARTY-NOTICES.md`.
+
+The role-flip of `/codex-review`: there, Claude builds the plan and Codex critiques read-only. Here, **Codex is the builder with bounded write access; Claude is the spec-writer and reviewer.** Codex implements a frozen spec end-to-end; Claude judges the diff like a contributor PR, demands proof, and iterates fixes in the same Codex session. The human enters at exactly two points: kickoff and diff sign-off.
+
+**Spec quality decides success.** Codex starts with zero session context — everything it needs must be in the prompt. A plan that survived `/grill-me-codex` or `/codex-review` already is a frozen spec; that's the ideal input.
+
+## Prerequisites (verify once, fast)
+
+- `codex --version` ≥ 0.130 (older CLIs error on the default `gpt-5.5` model).
+- Codex authenticated (prior `codex login`; ChatGPT account is fine). On auth/model error, surface it — don't silently retry.
+- Do NOT pin `-m` or model config (e.g. `model_reasoning_effort`) unless the user asks. Pinning `gpt-5.x-codex` variants 400s on ChatGPT-account auth; config defaults come from `~/.codex/config.toml`.
+- **Echo the active model at kickoff** so the user can confirm: read the `model` line from `~/.codex/config.toml` (absent = "CLI default"); state it with the resolved tunables. If the user objects, stop before launching the build.
+- **Codex has a native image-generation tool** in `codex exec` sessions (ChatGPT-account backed, no API key; upstream-verified 2026-07-08). Specs may therefore include "generate these image assets yourself" steps: name exact file paths, dimensions, and style in the prompt contract.
+- Run from the target working directory's root (both `exec` and `resume` then need no `-C`; `resume` doesn't support `-C` anyway).
+
+## Tunables (read from args, else default)
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `SPEC_FILE` | `PLAN.md` | The frozen spec Codex implements. |
+| `MAX_FIX_ROUNDS` | `2` | Fix iterations via resume before Claude takes over and finishes directly. |
+| `LOG_FILE` | `PLAN-REVIEW-LOG.md` | Append-only build transcript. If it exists (Act 1/2 ran), append `## Act 3 — Build`; else create it. |
+| `PROOF_CMD` | from spec | Exact test/verify command Codex must run as proof. If the spec lacks one, ask the user ONE question to get it before launching. |
+
+Echo resolved values before starting.
+
+## Step 0 — Gates (before any Codex launch)
+
+1. **Spec gate.** `SPEC_FILE` must exist and read as a work order (goal, concrete steps, bounds). No spec → offer `/grill-me-codex` (interview first) or `/codex-review` (have a plan, want it stress-tested) instead. If the user insists on building from a rough idea, write the spec WITH them first — that's design, and design stays with Claude.
+2. **Clean-tree gate.** `git status -sb`. Dirty working tree → STOP and ask the user to commit or stash first. Non-negotiable: Codex writes files, and a dirty tree means its diff can't be isolated or cleanly reverted.
+3. **Isolation gate.** Run on a dedicated feature branch — in worktree-based repos, in the slice's worktree, never the main tree. Codex's diff must be revertable without touching parallel work.
+4. **Allowed-write set.** Derive from the spec the explicit set of files/directories Codex may create or modify (the spec's "Key paths" / file list). This goes into the prompt contract AND is enforced after every round (Step 3). Can't derive one → the spec is not a work order yet; sharpen it first.
+5. Confirm scope in one line, then go. No round-by-round approvals; the human gate is at the end.
+
+## Step 1 — The build prompt (contract, via temp file)
+
+Never inline-quote the prompt — write it to a temp file. Fill this contract completely; when chained from a grill/review skill, derive it from the plan's sections:
+
+```bash
+CODEX_TMP="/tmp/codex-$(pwd | sha1sum | cut -c1-8)"; mkdir -p "$CODEX_TMP"   # run-unique per worktree cwd: stable across exec+resume turns, collision-free under parallel sessions
+P="$CODEX_TMP/build-prompt.txt"
+cat >"$P" <<'EOF'
+GOAL: <one paragraph — what done looks like>
+SPEC: Read <SPEC_FILE> at the repo root. It is a frozen, already-reviewed spec.
+  Implement it exactly. If a step is impossible as written, implement the
+  closest faithful version and report the deviation — do not redesign.
+KEY PATHS: <files/dirs Codex will touch or must read first>
+ALLOWED WRITES: <the explicit allowed-write set from Step 0.4 — Codex must not
+  create or modify anything outside it; if the spec seems to require it,
+  report instead of writing>
+CONSTRAINTS: <"don't touch X", style rules, deps that must not change>
+NON-GOALS: <explicitly out of scope — from the plan's Out of scope section>
+PROOF: Run `<PROOF_CMD>` and include its full output in your report.
+OUTPUT: End with a report — files changed (one line each: path + what/why),
+  proof output, and any deviations from the spec with reasons.
+EOF
+```
+
+## Step 2 — Launch Codex (fresh session, capture `thread_id`)
+
+```bash
+codex exec -s workspace-write --json -o "$CODEX_TMP/build.txt" - <"$P" 2>/dev/null | grep '"type":"thread.started"'
+```
+
+- **`-s workspace-write`, never `--yolo` / `--dangerously-bypass-approvals-and-sandbox`, and never weaken the approval policy.** The sandbox bounds Codex to the working directory; the allowed-write gate (Step 3) bounds it further to the declared set. If the build genuinely needs something outside the sandbox (network installs, system config), that step is Claude's, not Codex's — split it out of the spec.
+- Prompt goes via stdin (`- <"$P"`) — this both avoids quoting bugs AND sidesteps the non-TTY stdin hang (`codex exec` blocks forever waiting on stdin EOF under Claude Code's Bash tool; feeding the file gives immediate EOF).
+- Parse `thread_id` from the `{"type":"thread.started","thread_id":"..."}` line → `THREAD_ID`. Codex's final report lands in `$CODEX_TMP/build.txt` — read that file; don't parse the JSONL stream for content.
+- `2>/dev/null` suppresses cosmetic MCP/auth stderr noise. Confirm success by the report file + a `thread.started` line; neither → failed run (auth/model) — stop and tell the user.
+- **Timing:** foreground with `timeout: 600000` on the Bash tool call (default 2-min tool timeout kills real builds). If the spec is clearly >10 min of work (multi-file feature, migration, anything with image generation), launch with `run_in_background: true` instead and read the `-o` file when it exits. Don't kill a quiet background run early — Codex builds are legitimately slow.
+- **Heads-up on completion (required):** when a background Codex run finishes, the FIRST line of your next message to the user must be a loud standalone banner — `🔔 CODEX FINISHED — <what> (exit ok/fail) — verifying now` — BEFORE any verification output. The user is not watching tool calls; never let a completed build slide silently into the verify phase.
+
+## Step 3 — Verify (Claude, always, never delegated)
+
+Codex's report is advisory. Verify yourself:
+
+1. **Allowed-write gate:** `git status --porcelain=v1` — every changed AND untracked path must be inside the allowed-write set from Step 0.4. Any path outside it is a finding: surface it to the user before anything else, and don't fold it silently into the diff review.
+2. Read the FULL diff (`git diff`). Judge it like a contributor PR: correctness, spec fidelity, style match with surrounding code, nothing touched outside scope.
+3. Run `PROOF_CMD` yourself (or the focused tests for the changed area). Codex's pasted output doesn't count as proof.
+4. Append to `LOG_FILE` under `## Act 3 — Build`: `### Round <n> — Codex build` + its report summary + `### Claude's verdict` + what passed/failed review.
+
+## Step 4 — Fix loop (same session, bounded)
+
+Problems found → resume the SAME session (Codex keeps its context; cheaper and better than a fresh run). Write the fix list to a second temp file (`$CODEX_TMP/fix-prompt.txt`), same contract discipline: exact problem, exact file, proof expected, same allowed-write set.
+
+```bash
+# resume has no -s and no -C: run from the repo dir and force the sandbox via
+# config override, or Codex inherits config.toml's sandbox_mode (possibly
+# read-only — can't write; possibly danger-full-access — must never run).
+codex exec resume "$THREAD_ID" -c sandbox_mode="workspace-write" --json \
+  -o "$CODEX_TMP/build.txt" - <"$CODEX_TMP/fix-prompt.txt" 2>/dev/null >/dev/null
+```
+
+Re-verify (Step 3, including the allowed-write gate) after each round. After `MAX_FIX_ROUNDS` failed rounds: STOP delegating — Claude takes over and finishes the remaining fixes directly. Log the takeover. Ping-ponging trivia through delegation burns more than it saves.
+
+## Step 5 — Human gate (diff sign-off)
+
+Present: 3-bullet summary of what was built, files-changed list, proof-test output (pass/fail, verbatim tail), rounds used, any spec deviations. Ask: *"Codex built it, proof passes, diff reviewed. Commit?"*
+
+- Commit ONLY on yes — and Claude writes the commit, never Codex.
+- Rejected → ask what's wrong, route back to Step 4 (or take over directly if fix rounds are spent).
+
+## Hard rules
+
+- Clean tree before launch. Always. No exceptions.
+- **Sandbox is bounded every round:** `-s workspace-write` on exec, `-c sandbox_mode="workspace-write"` on every resume. Never `--yolo`, never `danger-full-access`, never a weakened approval policy — if the task can't be done inside those bounds, it isn't a Codex delegation.
+- The allowed-write gate runs after EVERY round — out-of-set writes are findings, not noise.
+- Claude never skips the diff read. Codex claims are advisory until Claude has read the diff and run the proof.
+- Fix loop terminates at `MAX_FIX_ROUNDS` — then Claude takes over. No unbounded delegation ping-pong.
+- Commits, pushes, releases, GitHub mutations: Claude-side only, after the human gate. Codex never commits.
+- `LOG_FILE` is the deliverable — with Acts 1/2 it tells the whole story: grilled → reviewed → built → verified.
+
+## What NOT to do
+
+- Don't build without a spec — that's designing by delegation, and it fails. Route to `/grill-me-codex` or `/codex-review` first.
+- Don't use for ~<20-line single-obvious-change edits — just make the edit.
+- Don't pin `-codex` model variants on ChatGPT-account auth — 400s.
+- Don't resume with `--last` — capture and use the explicit `THREAD_ID` (parallel sessions make `--last` grab the wrong thread). And ECHO the id into the command visibly before running: `resume` with a missing/garbage id can silently fall back to the most recent session instead of erroring (observed upstream 2026-07-08) — a wrong-target resume looks exactly like a successful one.
+- Don't parse the JSONL stream for the report — read the `-o` file.
+- Don't let Codex commit, and don't auto-commit yourself — human gate first.

package/.claude/skills/codex-build/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,35 @@
+# Third-Party Notices
+
+## codex-build (the Codex build-and-verify loop)
+
+This skill (Codex implements a frozen spec, Claude verifies the diff and proof) is
+adapted from **codex-build** by **Chase AI**, from https://github.com/chaseai-yt/grill-me-codex,
+used under the MIT License. Chase's skill itself adapts Peter Steinberger's
+`codex-first` pattern (agent-scripts). Our copy has diverged from that template:
+the upstream `--yolo` / full-access sandbox is replaced by a bounded
+workspace-write sandbox with a declared allowed-write set enforced after every
+round.
+
+```
+MIT License
+
+Copyright (c) 2026 Chase AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```