@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/prototype/UI.md

@@ -0,0 +1,112 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
+
+For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
+
+Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
+
+### 5. Hand it over
+
+Surface the URL (and the `?variant=` keys). The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
+
+- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
+- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
+
+Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/.claude/skills/research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
+---
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

package/.claude/skills/research/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/research` @ 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/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort` as an escape from resolving — the only exception is a merge/rebase started by mistake, in which case abort cleanly and start over.
+
+4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/.claude/skills/resolving-merge-conflicts/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/resolving-merge-conflicts` @ 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/retro/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: retro
+disable-model-invocation: false
+description: Use when the user explicitly asks for a retro after a session with PR-activity. Analyzes session friction and proposes concrete config mutations (Memory/Skill/CLAUDE.md/Hook) with per-patch approval. No file is written — findings live in the mutated config.
+---
+
+# Retro — In-Session Deep-Dive
+
+Trigger: user types `/retro` (optionally with a PR/Issue number, e.g. `/retro 274`).
+
+## What this skill does
+
+A retro is a session-contained vehicle for surfacing friction and turning it into concrete config improvements. The retro itself is NOT a persistent artifact — the artifact is the **change** to Memory, Skill, CLAUDE.md, or a Hook. If nothing should change, nothing is persisted.
+
+## Symmetry Principle (mandatory)
+
+**Retro input = user friction + agent friction. Both equally weighted.**
+
+The user describes their pains in plain language. The executing agent contributes its own session pains from the tool-call trace in parallel. **Both** go through the analysis pipeline. The agent analyzes (root cause + config component) and proposes measures. The user votes per patch.
+
+The retro is never just "agent asks user about friction". That would be the wrong entry point — the user often only sees symptoms, while the agent sees the real tool-call failures, memory stalls, hook misses, and skill conflicts in the trace.
+
+## Why this exists
+
+Two purposes:
+
+1. **Feature-level learning** — capture friction while it is fresh so the same trap is not stepped into next session.
+2. **Config-health surveillance** — accumulate evidence that a CLAUDE.md rule, Skill, Memory note, or Hook is outdated, missing, or actively in the way. Each retro is the trigger source for incremental config cleanup.
+
+The previous file-based workflow (`pr-retro-stub.py` hook + filled retro files in `.claude/retros/` + batch-PR) was removed because filed retros are read by no one — only the config mutations matter.
+
+## Process
+
+### 1. Detect PR context
+
+Two signals:
+
+- **Branch-Pattern:** Run `git branch --show-current`. If it matches `feat/<N>-…` / `fix/<N>-…` / `chore/<N>-…` / `docs/<N>-…`, the issue number is `<N>`.
+- **Skill-Argument:** if the user typed `/retro <num>`, that number wins over the branch.
+
+If neither yields a number, ask the user:
+
+> "No PR context detected — run the retro anyway? If yes, give me the issue/PR number or say 'none'."
+
+User may skip (silent exit), give a number, or say "none" (proceed without a PR/issue anchor).
+
+### 2a. User friction probe (one question, outcome language)
+
+Ask exactly:
+
+> "Was there friction in the session? If yes, in 1-2 sentences: what was it?"
+
+A plain-language description is expected ("worktree setup is annoying", "LSP is acting up"). It is the **agent's job** to derive the technical root cause + config component from it — the agent should NEVER ask the user for that.
+
+### 2b. Agent friction self-probe (mandatory, parallel to 2a)
+
+The executing agent scans the session itself for friction. Mandatory checklist:
+
+- Which tool calls failed or had to be retried? (permission denials, edit-before-read errors, bash-pipe aborts)
+- Which memories turned out to be stale on inspection? (content contradicts today's code)
+- Which pre-commit/hook checks needed workarounds?
+- Which skill steps contradicted CLAUDE.md? (e.g. a plugin skill says npm install, CLAUDE.md says pnpm)
+- Which bash calls ran with CWD drift / sequential permission approval / missing absolute path?
+- Which `<system-reminder>` spam patterns recurred?
+
+Mark own findings explicitly as **"<Agent>-Finding: …"** in the output, on equal footing with user findings. Examples: **"Codex-Finding: …"** on Codex, **"Claude-Finding: …"** on Claude.
+
+### 2c. Memory sweep probe (mandatory if threshold breached — only if a memory directory exists)
+
+First check existence — consumers without Claude auto-memory (e.g. a pure Codex install) have no memory directory. Derive the path portably (project slug = absolute main-tree path with `/`→`-`; worktree-safe via the git common dir, fallback `pwd`):
+
+```bash
+PROJ_ROOT=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | xargs -r dirname)
+MEMDIR="$HOME/.claude/projects/$(printf '%s' "${PROJ_ROOT:-$(pwd)}" | tr '/' '-')/memory"
+test -d "$MEMDIR" && echo present || echo absent
+```
+
+Directory missing → one sentence in the output: "Memory sweep probe: no memory directory (no Claude auto-memory) — skipped." No patch proposal, step counts as satisfied. Otherwise continue:
+
+Count empirically — active memory set + index size:
+
+```bash
+ls -1 "$MEMDIR/"*.md | grep -v '/MEMORY\.md$' | wc -l
+wc -l "$MEMDIR/MEMORY.md"
+```
+
+Threshold trigger (either is enough):
+- Active memory set ≥ 65 files (sweep trigger above the CLAUDE.md target "active set <35" — fires only on real bloat, not a healthy-but-full set; tuned across retros)
+- MEMORY.md > 120 lines
+
+If the trigger is breached:
+- One sentence in the output: "Memory sweep probe: N active memory files, X lines MEMORY.md — over the token-hygiene target (<35 files)."
+- Include a config patch proposal in step 3:
+  "Patch X — memory set over <35. Identify + delete stale/completed memories (prune-on-touch). Check content before every deletion; move deleted memory files to `archive/` (instead of hard-deleting) so recovery stays possible. **Affects:** memory · **Weight:** low (hygiene, isolated)."
+  Like every step-4 patch, this one also carries the `Affects / Weight` line (3b/step 4).
+
+If 0 triggers:
+- One-liner in the output: "Memory sweep ok (N files / X lines)."
+- No patch proposal.
+
+**Skip allowance:** only when the memory directory is missing (see above) — otherwise none, the sweep probe runs on every retro.
+
+**Why here (mandatory step, not just memory):** memory is passive (only fires if the agent thinks of it); `/retro` runs routinely after PR activity and is the natural enforcement vehicle. The entry must happen BEFORE the symmetric analysis so it can flow into the process as a patch proposal if needed.
+
+**Threshold tuning:** sweep trigger = ≥65 files / >120 lines MEMORY.md (target stays "active set <35", trigger sits with headroom above it so healthy-full sets don't fire on every retro); threshold tuned upward across retros — raise further on the next empty-handed hit.
+
+### 3. Symmetric analysis (agent, on its own)
+
+For **every** friction point (user-reported AND self-found), the agent analyzes:
+
+- **Root cause:** which tool call / memory / hook / skill was concretely involved?
+- **Config component:** which mutation would prevent it next time? (memory / skill / CLAUDE.md / hook / helper script / issue / nothing)
+- **Repeatable or one-off?** One-off incidents → no patch needed.
+
+If the user's description in step 2a is ambiguous, the agent may ask **ONE** clarifying outcome question — e.g. "where was it most annoying — during setup, mid-work, or during cleanup?". Never multiple-choice with memory names, hook paths, or config classes.
+
+### 3b. Determine target + weight (threshold ladder)
+
+Before formulating a patch in step 4, place **every** friction point on the threshold ladder. **Weight** = how durable/far-reaching the rule is (drives the visible patch line in step 4 + the user's approval depth). **Target** = where the patch physically goes.
+
+| Weight | Target (tier) | When |
+|---|---|---|
+| **high** | CLAUDE.md / hard rule (or durable hook) | durable + cross-cutting + **incident-backed**; applies **across all phases** (even without a spec — during build, git, deploy) |
+| **medium** | `spec-self-critique` (project check) | recurring **spec-structural** defect, **catchable from the spec before building** |
+| **low** | Memory | isolated infra/domain gotcha (a fact to recall, not a pattern) |
+| **minimal** | Inline note / "nothing" | one-off, no pattern, no durable config artifact |
+
+**Domain/glossary gap** (the defect sits in the **grill input**, not the spec structure — a term was fuzzy/missing before a spec even existed) → target `CONTEXT.md` / `docs/adr/`, **weight medium**. This way learning findings reach the **plan START** (what `grill-with-docs` reads) for the first time, not just the spec gate. Boundary to `spec-self-critique` (also medium): that one holds a **structural** spec defect; this one a **substantive** domain/term gap.
+
+**Borderline high vs medium — two-stage test (CLAUDE.md vs `spec-self-critique`):**
+1. **Phase reach first:** "Would looking at the SPEC *before* building have prevented the friction?" → **Yes** = spec quality hole → `spec-self-critique` (medium). → **No, applies always/cross-phase** → CLAUDE.md candidate.
+2. **Incident gate for the high tier:** CLAUDE.md / hard rule **only** if durable + cross-cutting + **went wrong for real at least once** (incident-backed). A pure one-off observation without recurrence → downgrade to memory/inline, **not** a hard rule.
+
+**Borderline medium vs low:** when in doubt, **medium** wins (an active spec gate beats passive memory recall) — a spec-structural finding mis-routed to `low`/memory sits in passive recall and **never** fires again at the next spec, while a medium finding in the `spec-self-critique` layer fires guaranteed.
+
+**Tier says roughly where, class says which file.** For a **skill** target, the class routing in step 4 ("class first") decides **which** file — e.g. a "medium → `spec-self-critique`" patch (published class) lands in the **project layer** `docs/agents/skills/spec-self-critique.md`, not the scaffolding.
+
+**A GitHub issue is NOT a weight tier.** A real follow-up = work to track → `python3 scripts/board-sync.py create` (step-4 table), **orthogonal** to the ladder; its "weight" follows the follow-up scope. The ladder classifies **config patches**, not "turn it into a ticket".
+
+**Target missing in the project — separate two cases cleanly:**
+- **(a) Tier skill missing entirely** (e.g. a foreign project without `spec-self-critique`): no durable spec-time gate exists. **Memory is NOT a substitute** — passive recall doesn't catch a recurring spec defect before building. Report honestly: *"this project has no durable target for this tier"* + propose a `/setup-workflow` follow-up. **No fake guard via memory.**
+- **(b) Skill exists, project-layer file missing** (`docs/agents/skills/<skill>.md`): **create / append** — that is the normal retro-sink behavior that `spec-self-critique` step 0 expects anyway. **No** downgrade.
+
+### 4. Patch proposals (concrete recommendation, no multiple-choice with tech refs)
+
+**Generalization check FIRST (mandatory, before formulating) — class, not symptom.** Before cutting a patch, abstract one level up: *"What is this incident an EXAMPLE of?"* The patch covers the **class / principle** (every scenario where the same mechanism bites) — the concrete incident is only the **example**, not the scope. Symptom-tight patches (exactly-this-one-trigger) miss the next variant of the same class, forcing the user to steer again. **BUT class ≠ speculation:** only include **verified** members of the class (verify-first), structure it **extensibly** instead of stuffing in unproven patterns — too broad (unverified) is the same mistake as too narrow, just inverted. (retro: an over-narrow symptom patch was widened to the correct class, while an unverified pattern was deliberately left out.)
+
+For every friction point: the agent formulates **one concrete recommendation** with a short rationale in plain language. Format:
+
+> **Patch X — [one line: what].**
+> **Why:** [one line, why it removes the friction].
+> **What changes:** [one line, visible effect].
+> **Affects:** [target in plain language] · **Weight:** [high / medium / low / minimal] — [short rationale from the ladder (3b)].
+
+**Every patch carries the `Affects / Weight` line** (from 3b) — including the memory-sweep patch from step 2c (Affects: memory · Weight: low). The weight drives approval depth: "high / CLAUDE.md" = durable always-on rule, worth more scrutiny; "minimal / inline" = throwaway. Wording in plain language (no tech jargon in the user-facing view).
+
+Optionally present the diff/script/edit as a code block (for visual review), but NOT as a multiple-choice option with tech vocabulary.
+
+Possible mutation targets (internal for Claude, do NOT list in user-facing output):
+
+| Mutation type | Where |
+|---|---|
+| New/changed memory note | `~/.claude/projects/<project>/memory/<slug>.md` (plus update the `MEMORY.md` index) |
+| CLAUDE.md rule adjustment | `CLAUDE.md` (Hard Rules section) |
+| Skill improvement (generic/portable) | `.claude/skills/<skill>/SKILL.md` |
+| Project-specific skill lore (`generic`/`vendored` skill) | `docs/agents/skills/<skill>.md` (project layer) |
+| New/changed hook | `.claude/hooks/<name>.py` + test |
+| New helper script | `scripts/<name>.sh` (+ tracked `.claude/settings.json` allowlist —: `.local.json` doesn't propagate to worktrees) |
+| New GitHub issue | `python3 scripts/board-sync.py create` |
+| "Do nothing" | one-off incident, no recurrence risk |
+
+**Skill patch routing (class first).** If a patch targets a skill, FIRST read `.claude/skills/skill-manifest.json` **best-effort**. Published classes (`generic`/`vendored`): **project-specific** lore → `docs/agents/skills/<skill>.md` (project layer), **generic/portable** improvement → `.claude/skills/<skill>/SKILL.md`. `project-private`: the skill dir is fine. **Manifest missing** (foreign install) → safe default: lore goes to `docs/agents/skills/<skill>.md`, NEVER into a published skill dir. (Keeps published skills self-contained; e.g. `spec-self-critique` is `generic` → its project-specific checks belong in the project layer, not the scaffolding.)
+
+### 5. Per-patch approval (yes / no / modify)
+
+Per patch:
+
+> "Patch X — [what line]. Apply? (Yes / No / Modify)"
+
+<!-- mirror-xform:start codex-user-input-mechanism -->
+Use `AskUserQuestion` with ≤3 options. Option labels in plain language, **never memory slugs or hook paths in the labels**. On "Modify", ask in plain language what should be different.
+<!-- mirror-xform:end -->
+
+### 6. Implementation
+
+For each approved patch, execute the mutation immediately (Edit / Write / Bash). Do NOT batch — apply one at a time so the user can interrupt.
+
+### 7. Exit
+
+The retro is **opt-in** (user triggers `/retro`); it is **offered before PR creation**, never enforced. If done, it happens before the PR (not after merge). After all patches:
+
+1. Summarize in 2-3 sentences what changed + what was deferred.
+2. Fold a **`## Retro / Meta-Findings` section into the PR body** — into the PR still to be created, or via `gh pr edit` if already open: the honest friction analysis (user **and** agent findings) + the applied patches.
+3. Repo file patches (CLAUDE.md/hook/skill/script) get **committed as part of the slice PR**; memory patches are filesystem-only (not in the PR).
+
+Never create a file in `.claude/retros/`.
+
+## What NOT to do
+
+- **Do NOT create files in `.claude/retros/`.** The directory is historical archive only.
+- **Repo file patches belong in the slice PR** (the retro runs BEFORE PR creation) — commit them + add findings as a meta section in the PR body. Only memory/filesystem patches stay uncommitted.
+- **Do NOT skip the friction probe.** If you don't ask explicitly, you may silently invent friction that wasn't there.
+- **Do NOT propose patches without user approval.** Every config mutation gets explicit yes/no.
+
+## Format conventions
+
+- German prose for user-facing questions and summaries (project convention).
+- Correct umlauts (ä, ö, ü, ß — never ae/oe/ue/ss in prose).
+- File links as `[name](path)`, clickable in <maintainer>'s VS Code.

package/.claude/skills/scale-check/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: scale-check
+disable-model-invocation: true
+description: "Route an undertaking to the right altitude before any planning starts — a short plain-language dialog (3–6 questions) deciding between a Program, a Feature, a single Direct-Slice, or a Bug, then hand back a paste-ready start prompt for the chosen route. Use at the very start of a new build when the size is unclear (a new app, a big cross-cutting feature, or a where-do-I-start question). Owns the altitude criteria catalog; when in doubt it routes to Feature. NOT for slicing a chosen plan (to-issues) and NOT for clustering an existing backlog (board-to-waves)."
+---
+
+# scale-check — Route an undertaking to its altitude
+
+Answers one question in plain language: **"how big is this, and where do I start?"**
+The output is a **verdict** (Program / Feature / Direct-Slice / Bug), the **route**
+that fits it, and a **paste-ready start prompt** for that route. No requirements
+interview, no code, no board writes — this is a routing dialog, not a planning
+skill.
+
+This skill is the **single owner of the altitude criteria catalog** below. Other
+skills only *reference* it — a backlog-grooming pass escalates a candidate that
+trips the program criteria, and the skill router names it as the first step for a
+new build without a clear size. Keep the catalog here and cite it from there;
+never fork a second copy.
+
+## When to reach for it
+
+- A new undertaking whose size is genuinely unclear — greenfield app, "a bunch of
+  related work", a feature that might be bigger than one feature.
+- Someone asks "where do I start?" / "is this a program?" / "do I need a PRD?".
+- **Not** when the size is already obvious: a one-line fix goes straight to a
+  Direct-Slice, a known bug straight to a diagnosis — you can skip the dialog and
+  hand back that route directly.
+
+## The dialog — 3 to 6 plain-language questions
+
+Ask **one question at a time**, in plain language (no PM jargon), and recommend an
+answer where the person hesitates. Stop early once the verdict is unambiguous (two
+program criteria already tripped, or an obvious single-slice/bug). Each answer maps
+to the criteria catalog below.
+
+1. **Is this fixing something that used to work, or building something new?**
+   → "fixing" ends the dialog: **Bug** route.
+2. **In one sentence, what should exist at the end that doesn't today?**
+   (Frames the whole thing in outcome language — everything below hangs off this.)
+3. **Does it arrive in one go, or in several stages you'd ship and learn from
+   separately** (a first usable version, then expansions)?
+4. **Is it one clear area of the app, or several parts that each stand on their
+   own** (a whole new app counts as "several")?
+5. **Realistically, is this a handful of focused changes, or many separate work
+   sessions stretching over a longer horizon — and does its shape need big
+   structural calls locked before day one** (data model, phasing, cross-area
+   sequencing) **that would be expensive to revisit mid-build?**
+6. **Are there distinct acceptance stages** — e.g. a pilot that has to pass before
+   a wider rollout — **that gate what comes after them, and would progress only
+   make sense as a rollup across many waves rather than one issue's status?**
+
+Questions 3–6 are the four program-signal probes, each reaching two of the six
+altitude criteria (3→C1, 4→C2, 5→C3+C5, 6→C4+C6); question 1 catches bugs,
+question 2 anchors the outcome. You rarely need all six.
+
+## Altitude criteria (the single source of truth)
+
+Count how many of these the undertaking trips. **Two or more → Program route.**
+Fewer than two → it is a Feature (or smaller). **When it is borderline or you are
+unsure, route to Feature, never Program** — an emergent wave can always be promoted
+later, but program scaffolding you never needed is pure waste, and the Feature
+route can grow into a program the moment a second criterion clearly trips.
+
+- **C1 — Staged delivery.** It ships in several successive stages (a first usable
+  version, then expansions), not a single release.
+- **C2 — Multiple subsystems.** It spans several parts that each stand on their own,
+  or is a whole new app (greenfield), not one feature area.
+- **C3 — Long horizon.** It realistically needs many separate build sessions/waves,
+  not a handful of slices.
+- **C4 — Acceptance gates.** It has distinct acceptance stages (pilot → rollout,
+  phase gates) that gate later work.
+- **C5 — Upfront structure decisions.** Its shape needs structure-bearing decisions
+  locked before the first build day (data model, phasing, cross-area sequencing) —
+  decisions that would be expensive to revisit mid-build.
+- **C6 — Program-level overview.** Progress only makes sense as a rollup across many
+  waves, not as one issue's status.
+
+A single criterion is a strong Feature that may grow; **two or more is the program
+threshold**. The threshold is deliberately low and the tie always breaks to Feature.
+
+## Verdicts, routes, and start prompts
+
+Report the verdict, which criteria tripped (for a Program) or why it stayed below
+threshold, and the matching paste-ready start prompt. All four routes are existing
+skills — this skill only picks the entry point.
+
+### Program (≥2 criteria)
+
+A multi-wave undertaking: grill it once into a Program-PRD with a wave plan, then
+unfold that plan onto the board after a chat preview gate.
+
+```
+New program: <one-sentence outcome from Q2>.
+Tripped altitude criteria: <e.g. C1 staged delivery, C2 multiple subsystems, C4 gates>.
+1. Run a program grill with `grill-with-docs` — lock scope → phases → waves and any
+   structure-bearing decisions (escalate a single bounded choice to `decision-gate`).
+2. `to-prd` — it auto-detects the program mode from the Wellenplan chapter and writes
+   a Program-PRD (native anchor over the waves).
+3. `to-waves` — unfold the wave plan into named wave stubs + slice leaves after the
+   chat preview gate (nothing is written to the board until you approve it).
+```
+
+### Feature (0–1 criteria, or any doubt)
+
+One coherent feature — the standard single-wave line, unchanged.
+
+```
+New feature: <one-sentence outcome from Q2>.
+`grill-with-docs` (sharpen the terms + decisions) → `to-prd` (publish the Draft-PRD)
+→ `to-issues` (slice it into independently buildable tracer-bullet slices).
+```
+
+### Direct-Slice (a single, well-understood change)
+
+One behavior, already clear enough to build — no PRD, no slicing.
+
+```
+Small change: <one-sentence behavior>.
+`tdd` — one behavior at a time, red → green → refactor. No PRD, no decomposition.
+```
+
+### Bug (something that used to work)
+
+```
+Bug: <what's broken — expected vs. actual>.
+`diagnose` — reproduce, minimize, hypothesize, instrument, fix, regression-test.
+```
+
+## Output shape
+
+```
+scale-check: verdict=<Program | Feature | Direct-Slice | Bug>
+  criteria tripped=<C1,C2,… | none | n/a (bug/direct)>
+  route=<program grill → to-prd → to-waves | grill-with-docs → to-prd → to-issues | tdd | diagnose>
+  start-prompt: <the paste-ready block above, filled in>
+```
+
+Make the doubt-default visible: if it landed on Feature only because it was
+borderline, say so — "one criterion tripped (C2); routed to Feature by the
+tie-breaks-to-Feature rule — promote a wave later if a second one clearly appears."

package/.claude/skills/security-audit/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: security-audit
+description: Run the whole application's security audit as an independent two-model pass — two AI models audit the same code separately — then harden the remediation plan before any fix lands. Use when the user wants a security audit / security review of the entire app ("audit the app for vulnerabilities", "is the app secure", "security check before release"), before a release, or after the attack surface changes (new endpoint, new input source, auth change, dependency bump). NOT for reviewing a single diff/PR (that is a code review) and NOT for infrastructure hardening (firewall/ports/TLS/SSH/backups — audited separately from the application layer).
+---
+
+# security-audit — application-layer security audit (two-model run)
+
+Application-layer security audit of the whole repo. This skill is the **run
+procedure**; the checklist itself lives in a **runbook you own per project**. The
+generic runbook structure ships as a template you copy and fill:
+**`docs/agents/security-audit-runbook-template.md`** — copy it into your project
+(for example `docs/security/audit-runbook.md`), replace each `<placeholder>` with
+your actual stack, and keep it as the checklist single source of truth. Read your
+filled runbook first.
+
+**Scope guard:** code + config only. Infrastructure (firewall, exposed ports,
+TLS, SSH, backups) is audited **separately** — an exposed database port beats any
+code fix. Keep the two audits apart.
+
+## Workflow — two-model run
+
+Run in a **fresh session** (token hygiene). Anchor the campaign to a single
+tracking issue (an umbrella / cluster issue); open a new one per fresh audit.
+
+1. **Model-A pass (read-only).** Work the runbook's audit prompt → a findings
+   table with exact `file:line`, a severity, and a confirmed/suspected tag on
+   every finding. Cite real evidence — never claim a vulnerability you did not
+   locate in the code; prefer a flagged false positive over a silent omission.
+   Write it to a scratch file.
+2. **Model-B pass (read-only, independent).** Hand a *second* model the **same**
+   prompt in its own read-only sandbox. A second model refutes the first model's
+   false positives and catches what it missed — that independence is the whole
+   point. Generic operational gotchas when the second model is Codex:
+   - **Fresh session — never resume an existing one** during a parallel run:
+     context bleeds across sessions and you get hallucinated, off-topic verdicts.
+   - **Do not pipe the `--json` event stream through `grep`** (it can hang) —
+     write the raw json to a file and parse the thread id separately.
+   - The sandbox sees only tracked files; if you run it inside a git worktree,
+     copy any hook config into the worktree, or it fails closed to deny-all.
+3. **Consolidate.** Merge both passes into one report (the runbook's findings
+   template). Where the two models **disagree**, the finding goes onto a "needs
+   human verification" list — it is **never silently dropped**. Each finding keeps
+   its confirmed/suspected tag together with its evidence.
+4. **Harden the remediation plan.** Draft a remediation plan (which gaps, what
+   fix, what order, what blast radius), then grill **the plan** with a plan-review
+   pass: a relentless interview on scope and priority plus an adversarial
+   second-model review of the plan until it is approved. The audit produced the
+   *what*; the grill hardens the *how*. A human signs off before any code is
+   touched. (Your project layer names the concrete plan-review skill.)
+5. **Fix by slices.** Each confirmed gap → its own issue → a worktree → a
+   test-first fix → live-verify → a PR linked under the tracking anchor. Tick the
+   anchor's checklist on merge. Gaps discovered mid-fix → filed as their own
+   issue, linked under the same anchor.
+
+## Why two models + a grill
+
+Security findings are the textbook "plausible-but-wrong" case — one model's miss
+or false positive is expensive to catch later. An independent second model is
+cheap adversarial verification; grilling the plan stops over- or under-fixing
+before any code is touched.
+
+## Project layer
+
+Your project's runbook (copied from the template above) carries the stack-coupled
+checklist — the concrete framework, ORM, auth library, and deploy platform, and
+the exact commands to run. The standing tracking anchor and any category / board
+wiring live there too, not in this generic skeleton.