@ikon85/agent-workflow-kit 0.10.0

package/.agents/skills/prototype/LOGIC.md

@@ -0,0 +1,79 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
+
+Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
+
+This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, just put the command at the top of the prototype's README.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
+
+### 7. Capture the answer
+
+When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

package/.agents/skills/prototype/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: prototype
+description: "Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says \"prototype this\", \"let me play with it\", \"try a few designs\"."
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
+- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
+2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
+6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
+
+## When done
+
+The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

package/.agents/skills/prototype/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/prototype` @ 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/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/.agents/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/.agents/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/.agents/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/.agents/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/.agents/skills/retro/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: retro
+disable-model-invocation: true
+"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 -->
+Ask the user directly; if a structured user-input mechanism is available, use it 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.