@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/ask-matt/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: ask-matt
+description: "Ask which skill or flow fits your situation. A router over the skills in this repo."
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+> **Homage + Router.** Adopted from Matt Pocock's `ask-matt` (MIT, github.com/mattpocock/skills @ `7a83a3a`) — the name stays as a nod to upstream, the content is adapted to *this* repo's skill set (the plan→execute→land→learn line plus our gates, cross-model review, and land/learn skills). Provenance: `docs/agents/provenance.md`. Folder↔upstream-name note: `/diagnose` = upstream `diagnosing-bugs`, `/write-a-skill` = upstream `writing-great-skills` (renamed upstream, local names kept).
+
+You don't remember every skill, so ask.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**; on-ramps and gates merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## The main flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+0. **Size unclear? `/scale-check` first.** A new undertaking without a clear
+   size — a new app, a big cross-cutting change, a genuine "where do I even
+   start?" — runs `/scale-check` before anything else: a short plain-language
+   dialog that routes it to a Program, a Feature, a Direct-Slice, or a Bug,
+   and hands back a paste-ready start prompt for the chosen route. **Rule: a
+   new build without a clear size runs `scale-check` first** — never guess
+   the altitude and jump straight into step 1. Skip this step outright when
+   the size is already obvious (a one-line fix, a known bug) — go straight to
+   the entry that fits.
+<!-- mirror-xform:start codex-escalation -->
+1. **`/grill-with-docs`** — sharpen the idea by relentless interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.)
+<!-- mirror-xform:end -->
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions): `/handoff` out → fresh session → **`/prototype`** to answer with throwaway code → `/handoff` back what you learned.
+3. **Gate — does a slice hinge on an unknown?** Clear it *before* building (see Gate-before-build): a binary fact → **`/verify-spike`**; a bounded "which option" trade-off → **`/decision-gate`**.
+4. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split into independently-grabbable issues / a wave anchor). Clear context between issues: fresh session per issue, kick off **`/implement`** with the PRD + the single issue.
+   - **No** → **`/implement`** right here, same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out with **`/code-review`** (the two-axis Standards×Spec review; project layer at `docs/agents/code-review.md`, seeded by `/setup-workflow`) before committing. Reach for **`/tdd`** on its own to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own to review any branch/PR against a fixed point.
+5. **Land** → **`/wrapup`** (see Land). **Learn** → **`/retro`** (see Learn).
+
+### Context hygiene
+
+Keep steps 1–4 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so grilling, PRD, and issues build on the same thinking. Each `/implement` then starts fresh from the issue. If a session gets large before `/to-issues`, don't push on degraded — `/handoff` and continue fresh.
+
+## Depth Ladder
+
+Prefer the smallest depth that produces a clear next action.
+
+- **Program:** the size is genuinely unclear — a new app, a big cross-cutting
+  undertaking, several independently-shippable stages. Run `/scale-check`
+  first (it owns the altitude criteria catalog — this router only names it);
+  two or more criteria tripped routes to a program grill → `/to-prd` →
+  `/to-waves`.
+- **Deep:** `/grill-with-docs` followed by `/to-prd` and `/to-issues` when
+  terminology, contracts, rollout order, or ownership are still uncertain.
+- **Medium:** `/to-issues` for a ready artefact that needs slicing.
+- **Light:** direct `/tdd` for a small, well-understood change.
+- **Gate:** insert `/verify-spike` or `/decision-gate` before any depth level
+  when a slice hinges on an unresolved fact or trade-off.
+
+## Gate-before-build
+
+When `/to-issues` cuts a slice that hinges on an unknown, it tags the slice instead of guessing. The gate is its own slice, sequenced *before* the build slice it blocks.
+
+- **`/verify-spike`** — a single yes/no fact against the real lib/runtime/DB/platform, answered by a throwaway read-only harness with output-proof.
+- **`/decision-gate`** — a bounded trade-off ("which option") or a targeted research gap: options × criteria table + reasoned pick, sunk to an ADR/issue.
+<!-- mirror-xform:start codex-escalation -->
+- **`/grill-with-docs` / `/grill-me`** — for genuinely hard-to-reverse calls, escalate to the relentless-interview grill.
+<!-- mirror-xform:end -->
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. Moves issues through triage and produces agent-ready issues that `/implement` later picks up. Only for issues **you didn't create** — `/to-issues` output is already agent-ready, don't triage it.
+- **Something's broken** → **`/diagnose`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression between two known-good states. Refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the finding is that there's no good seam.
+- **A huge, foggy effort too big for one agent session** — a greenfield build or a sprawling feature where the way from here to the destination isn't yet visible, and it's still **pre-spec** (before any grill or PRD) → **`/wayfinder`** (user-invoked). It charts a **shared map** of investigation slices on the tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog lifts and the route is clear, then merges onto the main flow at **`/to-prd`** (or, if the effort turned out small enough, straight to **`/implement`**). Where `/grill-with-docs` sharpens an idea you can hold in one session, wayfinder is for the one you can't. Once an undertaking has already resolved into several independently-shippable waves, `/scale-check` → `/to-waves` stays the primary route.
+- **A backlog to cluster** → **`/board-to-waves`**. Groups an existing board into themed waves when you need to *find* the next wave rather than start fresh.
+- **A whole wave to LAND** → **`/orchestrate-wave`**. When a wave anchor (file-disjoint slices, specs already locked) is ready to build, verify and land end-to-end — often AFK: it dispatches an implementer per slice in its own worktree, integrates serially, verifies centrally, and lands the wave. The execute-and-land node of the wave ladder (`scale-check` → `to-waves`/`board-to-waves` → `orchestrate-wave`). A single slice just goes to `/tdd`.
+
+## Cross-model review (Codex)
+
+An independent second model catches what one model rationalises. Read-only, bounded.
+
+<!-- mirror-xform:start codex-escalation -->
+- **`/grill-me` / `/grill-with-docs`** — the relentless interview that locks a plan before any code; reach for these on genuinely hard-to-reverse calls.
+<!-- mirror-xform:end -->
+- **`/codex-review`** (Claude Code only) — standalone: you already have a plan, just want the cross-model stress-test.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run in spare moments to keep the codebase good for agents. Surfaces **deepening opportunities**; picking one _generates an idea_ for the main flow at `/grill-with-docs`.
+- **`/zoom-out`** — step back from the diff to the structure when a change is fighting the codebase; recon that becomes a planned slice or guides a refactor in place.
+- **`/security-audit`** — a whole-app, application-layer security audit run as an independent two-model pass (two models audit the same code separately, then the remediation plan is hardened before any fix). Run before a release or after the attack surface changes (new endpoint, new input source, auth change, dependency bump). Infra hardening (ports/TLS/SSH/backups) is audited separately.
+
+## Vocabulary underneath
+
+Model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them when the **words**, not the process, are the problem.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word, record a hard-to-reverse decision as an ADR. The active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary. (ADR conventions: `docs/adr/README.md`.)
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*. `/tdd` and `/improve-codebase-architecture` both speak it.
+- **`/write-a-skill`** (Claude Code only) — reference for writing and editing skills well (invocation, information hierarchy, progressive disclosure, leading words, pruning, failure modes). *This router is itself an instance of its "router skill" pattern.*
+
+## Land
+
+- **`/wrapup`** — the land-and-clean closeout: make the branch landable, enforce the PR-body contract, merge, reconcile the board, sweep merged branches, surface what's still open. Does not replace live verification — verify the user outcome first.
+- **`/local-ci`** — the pre-PR gate: run the repo's local CI (fast static guards + the full gate) before opening a PR. When your host can't enforce a required status check at merge (a Free-plan private repo has no branch protection), the gate has to be local — this is it.
+- The **pre-commit / pre-push gate** fires automatically (installed once via `/git-guardrails-claude-code` / `/setup-pre-commit`, both Claude Code only), blocking a broken commit/push.
+
+## Learn
+
+- **`/retro`** — in-session post-mortem that proposes concrete changes to rules, skills, or hooks, each with per-patch approval.
+- **`/audit-skills`** — the anti-drift audit: check the repo's own skills against code/doc reality and fix the rot (dead paths, stale line numbers, broken cross-refs). Run it periodically or when a SessionStart drift-hint flags a skill whose declared source moved.
+- **`/write-a-skill`** (Claude Code only) — turn a move you keep repeating into a reusable skill (see Vocabulary).
+
+## Crossing sessions
+
+- **`/handoff`** — compacts the conversation into a markdown file when a thread is full or you need to branch (e.g. into a `/prototype` session). You don't continue in place — open a new session and reference that file. `/handoff` forks; `/compact` continues.
+- **`/compact`** (built-in) — stay in the same conversation, letting earlier turns be summarized. Use at intentional breaks between phases, not mid-phase.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless — saves nothing locally.
+- **`/prototype`** — a small throwaway program that answers one design question (does this state model feel right; what should this UI look like). Keep the answer, delete the code.
+- **`/research`** — delegate reading/docs legwork to a **background agent**: it investigates a question against **primary sources** and leaves a cited Markdown note in the repo. Keep working while it reads. Model-invoked (also triggerable by name); the note it produces is something to carry *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/resolving-merge-conflicts`** — a disciplined loop for an in-progress merge/rebase conflict: understand each side's intent, preserve both where possible, always resolve (never `--abort`).
+- **`/git-worktree-recover`** — reflog recovery for a branch mix-up: a commit landed on the wrong branch, the branch switched unexpectedly, or work looks lost. Finds the misplaced commit, moves it to the right branch, and sets up a clean worktree.
+- **`/spec-self-critique`** — red-team your own spec before committing to build it.
+
+## Precondition
+
+- **`/setup-workflow`** — run before your first engineering flow to configure the issue tracker, triage labels, board profile, and doc layout the other skills assume.
+
+## Repo-specific skills
+
+This repo also carries **project-private domain/tooling skills** (data layer, migrations, forecast/risk logic, brand, blast-radius census, …) that don't ship in the kit. For those, see the **project-skill table in `CLAUDE.md`** — they're model-invoked and fire on their own triggers.

package/.agents/skills/ask-matt/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/ask-matt` @ 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/.agents/skills/audit-skills/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: audit-skills
+disable-model-invocation: true
+description: "Audit the project's own skills for drift from code/doc reality and fix it — the anti-drift learn step. Run at retro, periodically, or when a drift-hint warns a skill's declared source moved since its last touch. Fans out one read-only research subagent per skill, re-verifies each reported drift before editing (the auditor produces false positives), and fixes by content type. Triggers: audit the skills, skill drift, stale skill, skill points at a dead path or renamed symbol."
+---
+
+# audit-skills — Skill freshness audit (anti-drift)
+
+A reusable recipe for checking the project's own skills against code/doc reality
+and keeping them fresh. Skills rot in every repo: a refactor moves a file, a
+symbol is renamed, a line number shifts — and the SKILL.md that named it now
+lies. This is the **learn** step of the plan → execute → land → learn line: the
+skills the other steps rely on drift, and nothing fixes them unless a recipe does.
+
+## When to run
+
+- At `/retro` (a periodic hygiene point).
+- When the SessionStart drift-hint hook (`.claude/hooks/skill-drift-hint.py`)
+  warns that a declared source moved in git since the skill's last touch.
+- Ad-hoc, when a skill you just reached for points at a dead path or a renamed
+  symbol.
+
+Not for: rewriting a domain skill's content on demand (that is the skill itself),
+or auditing application code (a code review or a diagnosis does that).
+
+## Standing guards (run without this audit)
+
+Two automatic nets catch the most common drift classes before an audit — this
+recipe complements them, it does not replace them:
+
+1. **A skill-sync test** — for any un-guessable enumeration a skill documents (a
+   status→bucket map, a design-token list), a test parses the value out of the
+   SKILL.md and asserts equality with the code constant. Drift breaks the build.
+   Your project layer names the concrete tests.
+2. **The drift-hint hook** (`.claude/hooks/skill-drift-hint.py`) + a per-skill
+   `SOURCES.txt`: at SessionStart it flags any skill whose declared source file
+   is newer in git than its SKILL.md.
+
+**Core insight:** test-covered values do NOT drift silently — only un-tested
+prose refs (paths, line numbers, cross-refs, memory keys) rot. So: test-cover the
+high-value un-guessable enumerations (guard 1); audit everything else
+periodically (this recipe).
+
+## The SOURCES.txt convention
+
+Each drift-prone skill declares its code/doc anchors in a co-located
+`SOURCES.txt` next to its `SKILL.md`:
+
+- one repo-relative source path per line;
+- `#` comments and blank lines are ignored;
+- the drift-hint hook compares each source's last-commit time against the
+  SKILL.md's — a source committed *after* the skill means the skill may be stale;
+- committing (touching) the SKILL.md resets the signal — that is how you
+  acknowledge that you re-checked it.
+
+When a confirmed fix introduces a new source file or replaces an old one, update
+that skill's `SOURCES.txt` in the same change — otherwise the hook keeps pointing
+at dead anchors, or misses the new source.
+
+## Recipe
+
+### 1. Enumerate the skills — three audit classes
+
+Do NOT hardcode a skill list (it rots on every new skill; a newly added skill
+stays blind). Derive it from the skill manifest (`.claude/skills/skill-manifest.json`)
+plus the `SOURCES.txt` files. Sort every skill into one of three classes:
+
+1. **Code-drift — subagent-audited, drift-hook-netted.** Every skill with a
+   `SOURCES.txt`. The hook already watches these; run a full step-2 subagent
+   audit over each file/symbol/line claim.
+   ```bash
+   ls .claude/skills/*/SOURCES.txt   # → the drift-netted skills
+   ```
+2. **Project-layer drift — against docs, not code.** Published/genericized skills
+   carry their project crust in a project-layer doc, not in code. Lighter check:
+   do the inline pointers still resolve to existing project-layer files, and do
+   the cited field/status names still match the profile.
+3. **Script-coupled, un-netted — checked by hand every audit.** Skills coupled to
+   scripts or hooks with no `SOURCES.txt` and no hook net. No hook warns, so
+   re-check them manually each audit.
+
+Your project layer assigns each concrete skill to a class — a completeness gate
+catches the next new skill that would otherwise stay invisible.
+
+### 2. Audit in parallel — one subagent per skill
+
+Run **one read-only research subagent per skill** — several in parallel in a
+SINGLE message (they are independent and read-only, so they don't contend for the
+git index). Per subagent prompt:
+
+- name the repo root, insist **read-only**, "propose no fixes";
+- list **each concrete SKILL.md claim** separately: file path, symbol name, line
+  number, code example, cross-ref, memory key;
+- ask for a verdict table back — `TRUE / FALSE / PARTIAL` + the CURRENT real
+  path/symbol/signature — in compact `file:line` form (far fewer tokens than
+  inline reads).
+
+### 3. Re-verify before every edit — mandatory
+
+**The auditor produces false positives.** Treat every reported drift as a
+hypothesis, not a fact: re-verify it at the edit itself (`grep` / read the file)
+before changing anything. Never take the auditor's list blind — and an empty
+`grep` result is not proof either, so anchor the search frame (path from the repo
+root, grep the import line, try a second pattern variant). On low-confidence
+findings, re-audit the whole skill rather than trusting the list. This
+false-positive discipline is the single most important rule of the recipe.
+
+### 4. Fix only what's confirmed — by content type
+
+- **Line number** → reference the symbol (function / constant); keep a line only
+  when unavoidable.
+- **Dead path** → the correct path, OR a pointer to the single source of truth.
+- **Cross-ref** → a stable name (verify the target still exists first).
+- **Stale "must still fix" state-claim** → move it into a "historical" block
+  (keep the lesson, don't present it as current) or delete it.
+- **Real code finding** (the skill is right, the code drifted) → a **separate
+  issue**, NOT fixed inside the docs change.
+- **Test-covered values** → leave untouched (guard 1 already secures them).
+
+### 5. Catch up the SOURCES.txt
+
+If a confirmed fix introduced a new source file or replaced an old one, update
+the affected skill's `SOURCES.txt` in the same change (see the convention above).
+
+### 5b. Sync any second surface
+
+If your skills are published to more than one surface (for example a Codex mirror
+alongside the Claude source), sync the mirror in the **same** change — otherwise
+the second surface rots silently. Mirror the body, but preserve each surface's
+own frontmatter: a mirror's `description` may be deliberately condensed, so never
+blind-copy the whole file over it. A `SOURCES.txt` is a plain anchor list and can
+be mirrored verbatim. Your project layer names the surfaces and the exact
+transform.
+
+## Done
+
+- **Enumeration completeness:** every skill from the manifest is assigned to one
+  of the three §1 classes — this catches the next new skill that would otherwise
+  stay invisible to the audit.
+- Every reported drift is either fixed (with re-verify proof) or dismissed as a
+  false positive (with proof the skill was right).
+- Real code findings filed as their own issues, not folded into the docs change.
+- Any second surface synced (body-parity; each surface's frontmatter preserved).
+- The skill-sync guard and the drift-hint smoke test pass.
+- A pure docs / test / hook change needs no application live-verify.

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

@@ -0,0 +1,135 @@
+---
+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/.agents/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/.agents/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/.agents/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.