@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/local-ci/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: local-ci
+description: Run the repo's local CI gate before opening a PR — the stand-in for GitHub required status checks when your plan or repo visibility can't enforce them (a Free-plan private repo has no branch protection). Use before every PR, when a guard/test red is suspected on a branch, or when wiring/repairing the pre-push guard backstop. Triggers — "local ci", "run local ci", "pre-PR check", "why is main red", "did a guard land red".
+---
+
+# Local CI
+
+A guard only protects if it runs on a **gate**. When your host can't enforce a
+required status check at merge — **GitHub Free + Private has no branch protection
+and no rulesets** ([GitHub Docs: protected
+branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches))
+— the gate has to be **local**. This skill is that gate.
+
+> Fault class: *Detection without Enforcement.* A guard that runs only in a
+> manual, opt-in step is not a gate — the drift it catches still merges. Fix the
+> gate class, not the one field that slipped through.
+
+The exact commands, guard names, hook wiring and the project's own incident lore
+live in the **project layer** for this skill (its `docs/agents/skills/local-ci.md`,
+seeded as an empty stub by `/setup-workflow` and filled per project). This
+skeleton names the two profiles generically; run the two your project layer names.
+
+## When
+
+- **Before opening ANY PR** → run the full local gate. Red → fix it, or defer a
+  *single* failure ONLY with an explicit written reason in the PR body (never
+  silently — a skipped gate framed as done is a fake quality gate).
+- A guard/test red is suspected on a branch ("why is main red").
+- Wiring or repairing the pre-push backstop / adding a new guard.
+
+## The two profiles
+
+Two commands, one fast and one full — your project layer names the exact
+invocations:
+
+- **Fast static guards** — no DB, ~seconds. Run automatically at **pre-push** so a
+  red drift guard cannot leave the machine.
+- **Full gate** — typecheck + lint + the test suites a CI job would run, ~a minute.
+  Too slow for a hook → the **agent's named pre-PR step**, explicit not automatic.
+
+## Enforcement model
+
+- **pre-push** runs the fast guards automatically → a red drift guard cannot be
+  pushed. Keep any emergency escape hatch explicit and logged — never a silent one.
+- **pre-commit** gates typecheck + lint, and should block a committed focused-test
+  marker (`.only` / `fit` / `fdescribe`) so a focused test can't silently gut a
+  file's coverage (green-but-empty).
+- The **full gate** is the agent's named pre-PR step: the full suite is too slow
+  for a hook, so it is explicit, not automatic. Run it; report the result honestly.
+
+## Contention — stop the dev server before the full gate
+
+The full gate runs several test runners at once. A dev server running in parallel
+oversubscribes the cores → **boot-contention false reds**: hook/boot timeouts in
+*unrelated* tests that are green in isolation. Symptom = "Hook timed out" in tests
+that pass on their own.
+
+- Stop the dev server before the full gate. Verify a suspicious red as a false red
+  by running that one test in isolation — green in isolation = contention, not a
+  real red.
+- Kill the dev server by **PID-via-port, not a process-name match**. A name match
+  (`vite`) also hits the test runner (`vitest`), and matching your own command line
+  kills the running command. Resolve the PID from the listening port instead.
+
+## On a red
+
+1. Read the failing test's message — a good guard prints the exact drift
+   (`file:line`, the offending token, the missing allowlist key).
+2. Fix the source. If a guard legitimately can't be satisfied yet, add its
+   **documented allowlist entry with a reason** — never widen a guard silently
+   (that re-opens the blind spot the guard exists to close).
+3. Iterate on the single file, then the full gate for sign-off.
+
+## Adding a new guard
+
+Prefer a **glob-discovered** guard config so a new fast static guard joins the
+pre-push set automatically — no hand-maintained list. Name it to match the include
+glob and keep it **DB-free** (pre-push must stay ~seconds); DB-bound tests belong
+to the full gate, not the fast pre-push set.
+
+## Baseline-green first
+
+If your success criterion is "gate green" and you do NOT know the base's green
+status — you are **hardening the gate itself**, or building against a `main` that a
+rename/schema cascade is landing on piecemeal — run the relevant gate part ONCE on
+the **unmodified base** before your first edit. It separates pre-existing breakage
+from your work; otherwise foreign reds surface one at a time as you build (an abort
++ scope question each).
+
+## When the host CAN enforce
+
+If the repo moves to a plan/visibility with required checks: add a CI workflow
+running the full gate on PR and make it a **required status check** — then the gate
+is machine-enforced at merge, not just local. Until then, local is the gate.

package/.claude/skills/orchestrate-wave/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: orchestrate-wave
+description: >-
+  Use when the user hands you a whole WAVE / cluster of pre-planned, file-disjoint
+  slices and wants you to ORCHESTRATE building, verifying AND landing it end-to-end —
+  often AFK / "ultracode". Triggers: "orchestriere Welle #N" (or any wording that
+  delegates wave-landing responsibility to you), "ultracode diese Welle / diesen
+  Cluster", or a wave-anchor issue (a cluster/umbrella issue with file-disjoint
+  sub-issues whose specs are already locked) handed over to land. NOT for a single
+  slice (just `tdd` it), NOT for finding/clustering a wave (that's `board-to-waves`),
+  NOT for planning specs (that's `grill-with-docs`/`to-issues`).
+---
+
+# Orchestrate Wave
+
+You are the orchestrator. The user gives you a wave anchor (a cluster/umbrella
+issue with file-disjoint sub-issues whose specs/decisions are already locked) and
+says "land it". You decide inline-vs-delegate; you are responsible for it landing
+correctly, AFK. Subagents BUILD; **you** integrate + verify + land.
+
+The anchor, its sub-issues and the locked plan doc contain the verbatim contracts
+you must NOT paraphrase.
+
+> **Phase 0 probes a project layer.** Concrete tooling — exact test/verify
+> commands, a DB/tunnel setup, a headless login recipe, brand checks, deploy
+> lockstep — is project-specific and lives in a **project layer** this skill reads
+> at runtime, not in this skeleton. The skeleton names the layer's sections
+> (`§Setup`, `§Builder Commands`, `§Builder Hard Rules`, `§Integration Suites`,
+> `§Verify Recipe`, `§Headless Login`, `§Landing`) and falls back to generic
+> instructions when the layer is absent. See **Phase 0**.
+
+## Standing rules (all phases)
+
+- **AFK heartbeat.** A wave run may take time but must never look stuck: during any
+  long-running gate (dispatch wait, integration suite, full verify, browser/E2E,
+  migration) send a short status update at least every ~30 s and on every phase
+  change — current gate, last green milestone, next step, visible blocker/risk. A
+  still-running tool session is stated as such; never wait silently for the final
+  result.
+- **Degrade by subtraction, never by improvisation.** The defined failure paths:
+  - **Slice stays red after escalation** (2-strikes rule, see Routing): pull the
+    slice — do not merge it (or revert its merge), pull every dependent that
+    consumes its artifacts (Phase-1 graph), land the remaining green subset, create
+    a tracking issue, leave its anchor row open, report the pull prominently.
+  - **Schema wave degraded:** if a pulled slice owns a migration/schema that a
+    remaining slice reads, the ONE-lockstep-window premise no longer holds → STOP,
+    land nothing schema-dependent, report.
+  - **Plan-level error** (integration/verify reveals a wrong LOCKED decision, not a
+    slice bug): STOP the wave. No improvised redesign AFK — keep worktrees intact,
+    report findings + options.
+- **Routing = one axis: how expensive is a wrong result to catch?** Mechanically
+  caught (test/screenshot/lint) → default tier at medium/low effort; plausible-but-
+  wrong / subtle logic / architecture → top tier at high effort + main-thread
+  re-verify; review/verify verdicts never below high. Concrete tier→model mapping
+  lives in your dispatch/model doctrine, if present — no model names here.
+  Escalate a repeatedly-failing slice one tier/effort up on the 2-strikes rule (2×
+  same problem despite concrete feedback, or structurally wrong approach — NOT the
+  first red test). The same axis sets how hard you re-verify. Borderline → default
+  tier + re-verify beats blanket top tier.
+
+## Phase 0 — Setup
+
+1. **Read everything**: the anchor body, every sub-issue body (each has a Handoff
+   block: scope, blast-radius, live-verify, PR line), and the locked plan /
+   plan-review doc in the planning worktree (file-exact).
+2. **Probe the project layer.** Read the project layer doc for this skill (the
+   consumer's `docs/agents/skills/orchestrate-wave.md` or the path your project
+   uses). If its `§`-sections carry **filled** content, follow the project recipe
+   wherever a phase below points at a `§`-section. If the file is only a
+   `setup-workflow` sentinel stub (empty headings, no real content) or absent,
+   treat the layer as **ABSENT** → use the generic fallback in each phase and warn
+   **once** that `/setup-workflow` plus project maintenance fill the layer (the
+   commands/tunnel/login can't be guessed). Never treat an empty heading as a
+   verify recipe.
+3. **Wave worktree**: reuse the planning worktree (never re-create; the handoff
+   points there). Bring its branch to current `main`:
+   `git -C <wave> merge --ff-only origin/main` (if your repo guards destructive
+   git, ff-merge is the safe path — not `reset --hard`). Install dependencies with
+   your package manager after (the lockfile may have moved). A gitignored plan doc
+   survives the merge.
+4. **Run project setup steps (`§Setup`)** the later verify needs — e.g. a DB
+   tunnel or service the live-verify depends on. Absent layer → start whatever your
+   live-verify environment requires before Phase 4.
+
+**Done when:** anchor + every sub-issue + plan read · project layer probed
+(filled → project recipe; stub/absent → generic + one-time warning) · wave branch
+ff'd to `origin/main` + deps installed · project setup steps running.
+
+## Phase 1 — Disjointness recon (the load-bearing step)
+
+Zero merge conflicts later depends entirely on getting this right.
+
+- Delegate to a read-only investigator agent: for EACH slice the exact file path of
+  every named component + resolve ambiguous targets, then a **FILE → SLICES** table
+  listing every file that appears in ≥2 slices.
+- Build the **overlap graph**. Identify the **conflict hub** (the slice whose new
+  artifacts other slices reuse). **Build the hub first**, merge it, THEN the
+  dependents stop conflicting.
+- Cut into **waves of fully file-disjoint slices**. Edited-by-≥2 = serialize across
+  waves; only-shared-via-import = safe. A new primitive edited by one slice but
+  *consumed* by others is NOT a conflict.
+- **Native blocking edges are the frontier authority.** Read the anchor's
+  buildable frontier from the tracker's native issue dependencies:
+  `python3 scripts/board-sync.py frontier <anchor#>` → `FREI` / `BLOCKED by #…` /
+  `done` per sub-issue. A body `## Blocked by` section is only the machine-written
+  MIRROR of those edges (on conflict the API wins) — never derive build order from
+  body text or table order alone. The frontier must AGREE with your Phase-1
+  dependency order; a contradiction is a plan finding to reconcile before dispatch,
+  not a detail.
+- **Reconcile contradictory sub-issue ACs against the plan BEFORE dispatch — the
+  plan is authority.** `to-issues` cuts slices independently, so a shared
+  append-only file (a query-key registry, a barrel, a shared types module) is often
+  claimed by *every* slice, with duplicate/clashing adds. **The hub slice OWNS the
+  shared-mutable file: it pre-adds ALL the wave's keys/types/helpers; dependents
+  CONSUME only and never touch it.** Embed verbatim in each dependent's contract:
+  "X already exists in `<file>` — do NOT add it, consume only." (Real case: all 14
+  sub-issues claimed the same registry adds + 4 contradictions — hub expanded to
+  own all 20 keys, batch merged conflict-free.)
+
+**Done when:** FILE→SLICES table exists · every ≥2-slice file has exactly ONE
+owning slice · disjoint waves cut in dependency order · every dependent contract
+carries its verbatim consume-only lines.
+
+## Phase 2 — Dispatch one wave in parallel (isolated worktree per implementer)
+
+Phase 2+3 repeat **per disjoint wave** from Phase 1 — the conflict-hub wave first.
+Within ONE wave, all slices dispatch at once. **Dispatch only `FREI` slices** —
+re-read the native frontier (`frontier <anchor#>`) before each wave; a
+gate-before-build edge clears only when its blocker actually lands (never
+"unblock" by editing body text — remove the edge via `dep-remove` if the plan
+genuinely changed). Two per-slice calls first: **(a)
+inline vs delegate** — a tiny mechanical bit (a rename, a 1-2-line tweak) you do
+yourself — and **(b) tier + effort** (Standing rules → Routing). For each
+delegated slice:
+
+- **One worktree per agent** off the wave-branch HEAD, own index so parallel agents
+  never share a git index. Use your project's worktree-setup command (`§Setup`),
+  else plain `git worktree add <path> -b feat/<anchor>-<slug>`.
+- **Build the prompt from [`references/builder-contract.md`](references/builder-contract.md)**
+  — fill the slots with the slice's VERBATIM What+AC, plan decision, recon
+  file:line map and consume-only lines; never paraphrase (paraphrase drift has
+  produced real contract errors). The template is the SSOT for the builder's hard
+  rules, test/typecheck commands, workflow order and report format.
+- **Capture reusable names** from the hub agent's report (the new component/helper
+  paths) and embed them into the dependent slices' contracts.
+
+**Done when:** every dispatched slice reported back with commit SHA + green
+package tests + green fast gate (`§Builder Commands`) — or a STOP item you resolved
+(answered / re-dispatched) before integration.
+
+## Phase 3 — Serial integration
+
+In the wave worktree: `git merge --no-ff <slice-branch>` per slice (disjoint →
+conflict-free). After EACH wave, on the integrated branch:
+
+- Typecheck both packages + the **FULL suite** — catches sibling/consumer test
+  breaks the agent ownership didn't cover (hardcoded count/tab asserts). Exact
+  commands = `§Integration Suites` (absent layer → your project's full test +
+  typecheck for every package the wave touched).
+- **Run EVERY test framework the wave's files belong to**, not just the primary
+  one: a kit/tooling/scripts wave may also have a separate unit-test runner and a
+  separate script-test runner the main suite does NOT cover (real case: a
+  second-framework red rode 3 integrations before surfacing). `§Integration Suites`
+  names each framework for this project.
+
+**Done when:** every framework green on the integrated branch — before dispatching
+the next wave.
+
+## Phase 4 — Central verify (YOURS, serial — the user explicitly wants this)
+
+Live-verify asserts USER OUTCOME (a DB-/UI value compared), not a tech metric.
+A single browser + single dev DB ⇒ verify is serial and yours. **A subagent's
+"PASS" is a hypothesis, not a gate** — implementers repeatedly mis-report green
+(real case: "gate PASS" while a size gate was red; files declared missing that
+existed). Never merge on the subagent's word.
+
+- **Re-run your project's full CI/verify gate CENTRALLY yourself** (`§Verify
+  Recipe`). On an integrated verify/coordinator branch (no per-slice issue number)
+  a branch-name-derived guard can BLOCK with no matching baseline — a branch-naming
+  artifact, not a coverage gap (each slice branch carried its own); `§Verify
+  Recipe` names the skip/override for that. Absent layer → run your project's
+  verification command or a project-provided verification skill (e.g. the kit's
+  **`/local-ci`** gate), if one exists; if the project has neither, run its full
+  test + typecheck and assert each slice's AC as a user-visible outcome by hand.
+- **Schema-/reader-changing waves** additionally run the COMBINED integration suite
+  against the refreshed snapshot before merge (`§Verify Recipe`) — per-slice-
+  isolated runs miss cross-slice seed/reader breaks.
+- **ONE dev server / one shared dev DB only.** ⚠ A second backend against a shared
+  dev DB can reaper-kill a live job (`§Verify Recipe` names the project's gotcha).
+  Stop the first dev server before starting another worktree's, or verify in the
+  same worktree.
+- **Headless login into the session-MCP profile** (AFK, no password in the
+  transcript). First navigate the MCP browser to the app root: no `/login`
+  redirect = already authenticated → skip the login (an authed profile makes a
+  login script time out on the e-mail field — looks like a selector bug, is not).
+  Otherwise: full recipe, profile-resolution lore + script = `§Headless Login`.
+- **Per surface**: browser snapshot + screenshot; assert each slice's AC visibly
+  gone/fixed + no regression. Run the project's design/brand checks (tokens, no
+  hardcoded values, formatters, chart-axis rules — `§Verify Recipe`) +
+  cross-surface consistency.
+- **Standardisation wave → CROSS-CONSUMER uniformity assert, NOT just per-slice
+  ACs.** If the wave unifies a shared pattern across ≥2 consumers, per-slice-green
+  is NOT enough — measure the standardised property on ALL N consumers and assert
+  they are EQUAL (e.g. `table.left - card.left` identical across every table;
+  export column-set identical), not just "present on each". Divergence only shows
+  in the cross-consumer diff. The shared component must OWN the standardised
+  property; this verify proves it actually does.
+- **DB-compare** the outcome value against the SQL source of truth. Watch
+  type-coercion traps your project layer flags (`§Verify Recipe`) — e.g. a `date`
+  column that shifts a day through a naive ISO round-trip.
+- **Console-clean** where required: read the browser console at warning level → 0
+  errors / 0 warnings.
+- **Gap the agents missed?** 1-file mechanical → fix inline; else **freshly
+  re-dispatch** a new agent into the existing slice worktree/branch with the prior
+  findings embedded — a continuation is NOT available in the parallel-wave flow;
+  stopped/background agents are re-dispatched, not resumed.
+
+**Done when — count it, don't remember it:** own central gate green (+ combined
+integration where schema/reader) · **N/N slice ACs** visually asserted with
+screenshot · cross-consumer equality measured (standardisation wave) · brand/design
+checks pass · console 0/0 · DB outcome value compared.
+
+## Phase 5 — Land
+
+- **One PR** for the whole wave (one merge for the user) OR per-slice — your call;
+  one PR with per-slice commits is usually kindest AFK.
+- **Schema-/migration waves: land as ONE combined PR — NOT incremental
+  auto-merge.** If merges to the main branch auto-deploy, per-slice merges race a
+  manually-gated prod migration → prod errors ×N slices. One combined PR = ONE
+  deploy = ONE prod-migration lockstep window. Incremental merge only for
+  byte-neutral waves (no new schema the deployed code reads). Project specifics
+  (deploy trigger, migration command, done-signal) = `§Landing`.
+- **`Closes #N` needs the keyword before EACH issue, one per line** — `Closes #a,
+  #b` only closes the first. Anchor → `Part of #<anchor>`, never `closes`
+  (premature close).
+- **Anchor tracker: `python3 scripts/board-sync.py anchor-sync <anchor#>`** — first
+  `--dry-run`, review the diff, then write; gate symbol + stable cells of freshly
+  appended rows by hand. Mandatory at EVERY slice event: PR-create AND merge.
+- **Stacked follow-up PRs** that build on the unmerged wave: base on the **wave
+  branch** (not main) — the platform auto-retargets them when the wave PR merges.
+  Note the merge order in the body.
+- New issues via `scripts/board-sync.py` (never bare `gh issue create`); write
+  multi-paragraph PR/issue bodies via `--body-file` (an inline body with backticks
+  can crash the shell).
+
+**Done when:** PR(s) open with correct `Closes`/`Part of` lines · anchor-sync
+written · merge order documented.
+
+## Phase 6 — Cleanup + close
+
+- Stop the dev server(s) you started, by port (`lsof -ti:<port> | xargs kill` —
+  your own processes, targeted by the worktree's assigned ports, never blind).
+  Remove temp verify scripts (a login helper, DB-check scripts).
+- **Before removing any slice worktree, read its `ANNAHMEN.md`** (an assumptions
+  log, gitignored at worktree-root) and propagate each build-time assumption marker
+  to the sibling issue it carries. A hand-driven multi-PR / migration landing does
+  NOT run `wrapup`'s assumption-propagation step — this is the only place it
+  happens; `worktree remove` deletes the log.
+- **Post-merge:** run `anchor-sync` again; verify every leaf issue actually closed
+  (the same checks `wrapup` runs, by hand when landing outside `wrapup`). The
+  anchor closes manually — a parent is not auto-closed on sub-issue completion.
+- A skill edited during the wave → run `codex-adapter-sync` (lives in
+  `.agents/skills/`) in the SAME PR — the mirror-presence-parity lint is a
+  pre-PR gate and blocks a dual-surface skill PR without its mirror.
+- Leave slice worktrees for the user to inspect, or note they're
+  post-merge-removable.
+
+**Done when:** no orphan process · ANNAHMEN propagated · anchor reconciled + leaf
+closes verified · final report lists landed/pulled slices as **X of Y**.

package/.claude/skills/orchestrate-wave/references/builder-contract.md

@@ -0,0 +1,67 @@
+# Builder Contract — template (fill slots, embed VERBATIM)
+
+SSOT for every delegated slice prompt in `orchestrate-wave` Phase 2. The
+orchestrator copies the block below and fills the `{{SLOTS}}` with verbatim
+material from the locked plan/issue — never paraphrased (paraphrase drift has
+produced real contract errors). Tier + effort per SKILL.md §Standing rules →
+Routing.
+
+The **Hard rules** and **Commands** sections below carry generic defaults so the
+template is never shipped with an unresolved project slot. When a project layer
+is present (`orchestrate-wave` Phase 0 probe → `§Builder Hard Rules` /
+`§Builder Commands`), the orchestrator REPLACES the generic lines with the
+project's exact rules and commands before dispatch — the builder must see exact
+commands, not "your project's tests".
+
+```text
+You are the implementer for slice #{{ISSUE}} of wave #{{ANCHOR}}.
+Worktree: {{WORKTREE_PATH}} (branch {{BRANCH}}) — work ONLY here.
+
+## Scope (verbatim from issue/plan — do not reinterpret)
+{{WHAT_AND_AC_VERBATIM}}
+
+## Plan decisions that bind you
+{{PLAN_DECISIONS_VERBATIM}}
+
+## File map (recon)
+{{FILE_LINE_MAP}}
+{{CONSUME_ONLY_LINES}}
+
+## Hard rules
+- Follow this project's UI/content conventions (from the project layer
+  §Builder Hard Rules — e.g. UI-text language, design tokens, formatters).
+  Absent a project layer: match the surrounding code's conventions exactly.
+- Size gates (recommended default): no new file >300 lines, no function >50
+  lines — unless the project sets its own limit.
+- If your slice adds a guard/helper/auth-check: WIRE it into its consumer + add a
+  negative test — an unwired helper is dead code.
+- STOP + report on any contract ambiguity — do NOT guess (this discipline has
+  caught real contract errors).
+- Do NOT run a browser/E2E or a dev server — the orchestrator verifies centrally.
+
+## Commands (exact — deviations produce false reds)
+Run, for EVERY package you edit: your package's unit tests for the files you
+touched, a typecheck, and the project's fast pre-PR gate. State the EXACT
+commands here from the project layer §Builder Commands. Absent a project layer,
+use: run your package tests + typecheck + fast gate, and name the exact
+invocation for each in this prompt so the builder cannot guess a wrong one.
+
+## Workflow order (non-negotiable)
+1. Implement (red→green test-first where the slice has logic).
+2. Commit your ONE commit on the slice branch FIRST — before any longer verify
+   (verify-then-forget-to-commit leaves the orchestrator hand-committing your
+   worktree). Do NOT push. Do NOT `--no-verify` (pre-commit hooks must pass).
+3. Run the commands above. Never end your turn with a background command still
+   running.
+
+## Report back (concise)
+Files touched · decisions taken · test results (exact output) · commit SHA ·
+STOP items · what the orchestrator should visually verify.
+```
+
+Orchestrator notes:
+
+- `{{CONSUME_ONLY_LINES}}` come from the Phase-1 reconciliation, e.g.
+  "X already exists in `<file>` — do NOT add it, consume only."
+- For dependent slices, fill hub artifact paths from the hub agent's report
+  (Phase 2 "capture reusable names"), not from the plan's guesses.

package/.claude/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/.claude/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/.claude/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.
+```