@korallis/k-pi 0.1.0

package/dist/kpi/kstack/generated/skills/architect/references/runner-prompt.md

@@ -0,0 +1,20 @@
+# Architect runner prompt
+
+The orchestrator passes this file through to every parallel candidate runner during Phase B and fills in the variable inputs around it: the task, the Phase A grounding artifacts, the isolated working directory, and the path to write outputs. The working directory is a git branch when available, otherwise a per-runner subdirectory under the sketch dir; what matters is independence between candidates.
+
+You are producing one candidate design in architect's parallel exploration. Read the **architect** skill in full first; that's the workflow you're inside. Output a candidate design package: type sketch, function signatures, module map, and prose rationale shaped per [`rationale-template.md`](rationale-template.md).
+
+Apply the following discipline. The orchestrator compares candidates on these axes to pick a base.
+
+- Caller's usage first. Write the README-style usage and two or three real call sites before the types, then derive the type sketch from them. The usage is the spec; the two must agree, so reconcile the sketch to the usage, not the reverse.
+- Data structures first. Get the core types right and the code becomes obvious. Trace each dominant access pattern through the proposed structure; if the answer is "we'll add a map / index / cache later," the structure is wrong.
+- Interface depth. Compare the capability hidden behind the public surface relative to the size of that surface. Prefer a simple interface that pulls complexity into the callee, even when the implementation becomes less simple. Do not put transport or wire types on the public surface; parse into domain types behind the interface.
+- Shared state: if two actors might both write, ask "what happens?" If the answer isn't "nothing," default to per-actor state with a merge at the read boundary, per the **separate-before-serializing-shared-state** principle skill.
+- Make boundaries visible. `not implemented` errors for bodies, `// TODO` pseudocode for tricky logic, doc comments stating intent and invariants. A reader should trace data from input to output by reading types and signatures alone.
+- Encode invariants in types: hard-to-misuse types > runtime checks > prose comments, per the **encode-lessons-in-structure** principle skill.
+- Validate at boundaries, trust types inside, per the **boundary-discipline** principle skill. Business logic as pure functions; the shell stays thin.
+- Single source of truth per invariant. Derive instead of sync.
+- Idempotent state transitions where applicable, per the **make-operations-idempotent** principle skill. Ask what happens if the operation runs twice or crashes halfway.
+- Short call chains. If tracing the flow needs more than three files, flatten the hierarchy, per the **laziness-protocol** and **minimize-reader-load** principle skills.
+
+You are one of several runners, each on a different model. Produce the best design your model can make; don't hedge against the others. Differences between candidates are the signal used to pick a base and graft. Converging on a safe-looking middle defeats the exploration.

package/dist/kpi/kstack/generated/skills/arena/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: arena
+description: Run at most two local K-π candidates against one frozen brief and graft the stronger result. Use for /arena, a bake-off, comparing two approaches, or picking between competing implementations.
+disable-model-invocation: true
+---
+
+# Arena
+
+Two attempts at the same brief, judged on their contract files.
+
+1. **Freeze the brief.** Both workers receive the same text. A brief that changes
+   between workers compares two different questions.
+2. **Pick the runners.** Take them from the `arena runners` list in
+   `~/.kpi/agent/kstack/models.json`. Prefer two different families so the
+   comparison is not one family reviewing its own habits. Only models the live
+   registry returned are eligible.
+3. **Spawn at most two.** `spawn_background` with role `arena`, one worker per
+   runner. Two is the cap every K-π fan-out obeys, and only one worker may hold
+   the writer slot, so the second either reviews or waits.
+4. **Steer with `communicate`.** Follow-up constraints go to the worker, not to a
+   shared scratch file.
+5. **Judge the candidates.** Read each worker's `candidate.json` against the
+   frozen acceptance criteria. Never read a worker transcript.
+6. **Graft the smallest proven result.** Take the winning candidate, or the
+   smallest combination that satisfies the criteria, and hand it to the shipping
+   gate. Never merge an origin branch and never push.
+
+Every worker writes inside the current checkout on the job branch. There is no
+second checkout, no remote runner, and no sleeper waiting for one to wake.

package/dist/kpi/kstack/generated/skills/blast-radius/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: blast-radius
+description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust."
+disable-model-invocation: true
+---
+
+# Blast radius
+
+Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet.
+
+Companion to `how` and `why`. `how` tells you what the code does. `why` tells you why it's shaped that way. Blast radius tells you what it breaks somewhere else.
+
+Listing the callers is not the job. The agent can grep those in a second. The job is the breakage grep won't show you.
+
+## Don't trust your own writeup
+
+A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it's true, and that is the trap you are walking into. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code. Words are where you start, not what you ship.
+
+### How sure are you
+
+For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.
+
+1. You said so. Worthless on its own.
+2. You pointed at the line. A real `file:line`, or the library's own source.
+3. You showed the bad case can't happen. You walked the failure step by step and it doesn't reach.
+4. You ran it. A script or test that calls the real code and fails loud if you're wrong.
+5. You reproduced it in the running app.
+
+Any safety fact you can't get to step 4, say so out loud. Don't write it up as settled. Step 4 is usually one small script that imports the same library the app ships and calls the exact function you're worried about.
+
+## Steps
+
+1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use `why` step 2 to pull the PR and commits.
+2. Find the one fact it's safe because of. Most changes that look scary are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most of the scary cases die at once. Spend your time here, not on a long list of maybes.
+3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
+4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed; list the ones you checked and cleared separately. Same rules as `why`. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API.
+5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened. If you can't prove it cheaply, mark it unproven. Don't round up.
+6. For a big or wide change, run it as an `arena`. Ask several models the same question and merge the answers. Different models catch different real bugs.
+
+## What to hand back
+
+- **What it does.** What changed, including the part that isn't obvious.
+- **The one fact it's safe because of.** State it, say which step you got it to, and show the proof. If you couldn't prove it, write unproven.
+- **Risks.** Only the real ones. Each names how it breaks, the `file:line`, how likely and how bad, and how to check. Paste the proof for the ones that matter.
+- **Cleared.** What you checked and why it's fine.
+- **Before you merge.** The cheapest test or repro that catches the real bug, including the script you wrote.
+
+Write it through `unslop`, cite real code, and strip anything private before it goes anywhere public.
+
+**Reply:** the writeup above, with the one safety fact either proven or marked unproven.

package/dist/kpi/kstack/generated/skills/bro/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bro
+description: Restate the last message in plain human language, with no jargon.
+disable-model-invocation: true
+---
+
+Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another.

package/dist/kpi/kstack/generated/skills/create-verification-skill/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: create-verification-skill
+description: "Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /create-verification-skill, \"make a control skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
+disable-model-invocation: true
+---
+
+# Create a verification skill
+
+Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (`.kpi/skills/verify-<app>/`) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
+
+## 1. Interview the repo, not the user
+
+Answer these from the codebase and only ask the user what you cannot observe:
+
+- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
+- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
+- **Drive:** how can an agent interact with it programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
+- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
+- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.
+
+If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
+
+## 2. Generate the skill
+
+Write `.kpi/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
+
+- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
+- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
+- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
+- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
+- **Cleanup:** how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
+- **Helpers:** any script the skill ships is executable and its invocation is shown in the skill body. A helper the reader has to reverse-engineer is not a helper.
+
+## 3. Seed the feature map
+
+Create `.kpi/skills/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
+
+## 4. Prove the generated skill before handing it over
+
+Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
+
+## 5. Offer the maintenance loop
+
+Point the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.

package/dist/kpi/kstack/generated/skills/create-verification-skill/references/feature-map-example/README.md

@@ -0,0 +1,47 @@
+# Notes verification map
+
+This directory is the maintained source for verifying the user-facing behavior of Notes. Read the index before driving the app, then use the matching feature file as the recipe.
+
+## Baseline preconditions
+
+- Launch Notes at `http://127.0.0.1:4173` with a disposable data directory.
+- Set `NOTES_DATA_DIR=/tmp/notes-verify-$RUN_ID` so concurrent runs do not share state.
+- Seed notes titled `Quarterly plan` and `Grocery list`.
+- Put `control-notes` and the `notes` CLI on `PATH`.
+- Run `control-notes doctor` and require the expected URL, data directory, and build revision.
+- Never drive an instance that was not started by this verification run.
+
+## Driving conventions
+
+- Start every recipe from the baseline state unless its preconditions say otherwise.
+- Prefer ARIA roles and accessible names over CSS selectors or DOM position.
+- Treat every command as literal. Keep quoted names and flags unchanged.
+- Run browser actions through `control-notes browser`.
+- Run terminal actions through `control-notes cli -- <command>`.
+- Restore seeded data after a mutation. Do not remove proof artifacts during cleanup.
+
+## Proof and skip reporting
+
+- Capture the user action and the resulting state, not only the final screen.
+- UI proof includes an ARIA snapshot and a screenshot with the app identity visible.
+- CLI proof includes the command, stdout, stderr, and exit code.
+- Mutation proof includes a read-only second view of the stored value.
+- Record the feature ID and entry point used with every artifact.
+- Report an unreachable path with the attempted command and the unmet precondition.
+- Do not report a skipped entry point as verified through a different path.
+
+## Feature entry contract
+
+Each feature file starts with an H1 title and one paragraph describing the user-visible behavior. It then uses exactly four H2 sections in this order.
+
+1. `Sub-features` lists short IDs with one line for each behavior.
+2. `How to get to it (user POV)` lists every user entry point.
+3. `Driving it with <harness>` starts with `Preconditions:` and uses labeled bullets that pair each user action with an exact command and observable result.
+4. `Gotchas` lists traps that can waste or invalidate a verification run.
+
+Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof.
+
+## Features
+
+- [Create a note](./create-note.md) covers browser and CLI creation, cancellation, persistence, and cleanup.
+- [Search notes](./search.md) covers toolbar, keyboard, and CLI search with matching, empty, and clear states.

package/dist/kpi/kstack/generated/skills/create-verification-skill/references/feature-map-example/create-note.md

@@ -0,0 +1,39 @@
+# Create a note
+
+Create note lets a user save a titled note from the browser or CLI, cancel an unfinished draft, and confirm the saved note from a second user-facing view.
+
+## Sub-features
+
+- `create-open` opens a blank editor from each browser entry point.
+- `create-save` persists a title and body.
+- `create-cancel` discards an unfinished browser draft.
+- `create-cli` creates the same note shape from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `New note` button in the browser toolbar.
+- Press `n` in the browser while focus is outside an editable field.
+- Run `notes create --title <title> --body <body>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- No note is titled `Release checklist`.
+- `control-notes doctor` reports the expected URL and disposable data directory.
+
+- **Open editor.** Choose `New note`. Run `control-notes browser click --role button --name "New note"`. A form named `Note editor` appears with focus in the `Title` textbox.
+- **Enter content.** Type the title and body. Run `control-notes browser fill --role textbox --name "Title" --value "Release checklist"` and `control-notes browser fill --role textbox --name "Body" --value "Tag and publish"`. The `Save note` button becomes enabled.
+- **Save note.** Choose `Save note`. Run `control-notes browser click --role button --name "Save note"`. A status named `Note saved` appears and the heading reads `Release checklist`.
+- **Confirm persistence.** Return to the note list and reopen the note. Run `control-notes browser click --role link --name "All notes"` and `control-notes browser click --role link --name "Release checklist"`. The editor shows both saved values.
+- **Cancel draft.** Open a new note, enter `Discard me`, and choose `Cancel`. Run `control-notes browser click --role button --name "New note"`, `control-notes browser fill --role textbox --name "Title" --value "Discard me"`, and `control-notes browser click --role button --name "Cancel"`. The note list returns and has no `Discard me` link.
+- **CLI entry.** Create a second note. Run `control-notes cli -- notes create --title "CLI note" --body "Created from terminal" --format json`. Exit code `0` and stdout contain the new note ID and title.
+- **Proof.** Reopen both saved notes from `All notes`. Run `control-notes browser snapshot --aria --path artifacts/create-note/list.aria.txt` and `control-notes browser screenshot --path artifacts/create-note/list.png`. The artifacts show `Release checklist` and `CLI note`.
+
+## Gotchas
+
+- Pressing `n` while a textbox has focus types the character instead of opening a new editor.
+- Titles are trimmed on save. Assert the rendered title, not the draft input value.
+- A save status alone is insufficient proof. Reopen the note from the list.
+- Remove `Release checklist` and `CLI note` during fixture cleanup, but retain their proof artifacts.

package/dist/kpi/kstack/generated/skills/create-verification-skill/references/feature-map-example/search.md

@@ -0,0 +1,45 @@
+# Search notes
+
+Search lets a user find notes by title or body text, inspect a matching note, and distinguish no matches from an unavailable search.
+
+## Sub-features
+
+- `search-open` opens search from each supported browser entry point.
+- `search-match` returns title and body matches without changing note data.
+- `search-open-result` opens a result in the note editor.
+- `search-empty` shows a complete empty state for a query with no matches.
+- `search-clear` removes the query and restores the recent-notes view.
+- `search-cli` returns the same matching notes from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `Search` button in the browser toolbar.
+- Press `/` in the browser while focus is outside an editable field.
+- Run `notes search <query>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- The disposable data directory contains `Quarterly plan` with body text `Draft budget`.
+- `control-notes doctor` reports the expected URL and data directory.
+
+- **Toolbar entry.** Choose the `Search` button. Run `control-notes browser click --role button --name "Search"`. A dialog named `Search notes` appears with focus in its searchbox.
+- **Keyboard entry.** Close the dialog, focus the page, and press `/`. Run `control-notes browser press --key "/"`. The same dialog appears and the page does not insert a slash.
+- **Title match.** Type `quarterly`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "quarterly"`. The `Search results` list contains `Quarterly plan` and does not contain `Grocery list`.
+- **Body match.** Replace the query with `budget`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "budget"`. The result `Quarterly plan` remains visible with a body-match excerpt.
+- **Open result.** Choose `Quarterly plan`. Run `control-notes browser click --role link --name "Quarterly plan"`. The dialog closes and the editor heading reads `Quarterly plan`.
+- **Empty state.** Reopen search and enter `volcano`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "volcano"`. A status named `No matching notes` appears after search completes.
+- **Clear query.** Choose `Clear search`. Run `control-notes browser click --role button --name "Clear search"`. The searchbox is empty and the `Recent notes` region replaces the result list.
+- **CLI match.** Search from the terminal. Run `control-notes cli -- notes search "quarterly" --format json`. Exit code `0` and stdout contain one object whose title is `Quarterly plan`.
+- **CLI miss.** Search for an absent value. Run `control-notes cli -- notes search "volcano" --format json`. Exit code `0` and stdout are `[]`.
+- **Proof.** Capture the populated result state. Run `control-notes browser snapshot --aria --path artifacts/search/results.aria.txt` and `control-notes browser screenshot --path artifacts/search/results.png`. Both artifacts identify Notes, the query, and `Quarterly plan`.
+
+## Gotchas
+
+- Pressing `/` while the editor or searchbox has focus inserts text instead of opening search.
+- Results update after a short debounce. Wait for the results list or empty status, not a fixed sleep.
+- Archived notes are excluded unless the user enables `Include archived`.
+- The CLI defaults to human-readable output. Use `--format json` for stable assertions.
+- Opening a result changes browser state. Reopen search before proving another query.

package/dist/kpi/kstack/generated/skills/figure-it-out/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: figure-it-out
+description: "Design an auditable playbook when no narrower one fits: a large migration, an ambitious multi-part change, or work a human reviews after stepping away. Scales rigor to the task, runs a hypothesis loop, and logs decisions via show-me-your-work. Use for /figure-it-out, 'figure it out', a large migration, or when no narrower playbook applies."
+disable-model-invocation: true
+---
+
+# Figure it out
+
+When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away. Bias toward more rigor. The cost of building the wrong thing dwarfs the cost of being careful.
+
+Don't reinvent a playbook you already have. A focused single-unit task that matches Bug fix, Perf, Feature, Visual parity, Eval, or Multi-phase plan routes there. But a large or cross-cutting version of one (a migration across many call sites, an ambitious multi-part change), or work the user reviews after stepping away, belongs here even though a single-unit version would be a Feature. The rigor and the audit trail are the point.
+
+## Start
+
+Open a todolist whose first item is to read the Principles section of the **k-mode** skill. Then add the phases below as todos.
+
+## Phase A: Frame
+
+Ground first, then commit. Don't start the run until you can state:
+
+- The definition of done as a falsifiable predicate (the **prove-it-works** principle skill). "Done well" has to be checkable.
+- Scope, quantified: rough units and effort, plus the blockers grounding surfaced. Raise them before spending hours, not after fifty doomed commits.
+- The rigor level, biased high. One-way doors and high blast radius get more; reversible low-stakes steps get less. Rigor is gates and artifacts, not "try harder".
+
+Present the framing and tradeoffs before committing to a long run. Reversible work proceeds (the **never-block-on-the-human** principle skill), but a multi-hour run earns one checkpoint.
+
+## Phase B: Design the workflow
+
+Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first so option value stays high. Scaffold and verification come before features (the **foundational-thinking** principle skill).
+
+- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
+- For one-way-door design decisions, run the **architect** skill (it runs **arena**) with diverse, isolated, opinionated candidates and a read-only judge on a different model family. Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
+- Decide what fans out. Parallelize only across genuine seams, and give each worker its own branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan.
+- Write the designed phase list down. That list is what the human reviews.
+
+Then put the design into motion. Add its steps to the todolist as concrete items, after the Phase C entry and before Phase D. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
+
+## Phase C: Run the loop
+
+Each unit is an experiment: state the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't.
+Apply the **sequence-verifiable-units** principle skill, verifying each unit before starting the next instead of batching checks at the end.
+
+- Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system. A blank screenshot passes a lazy gate.
+- Pair delegated work with a judge and audit the delegates' artifacts yourself before trusting them. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
+- A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Inconclusive is not a pass. Don't hide a negative.
+
+## Phase D: Keep the audit trail
+
+Log the run via the **show-me-your-work** skill, one canonical TSV with a row per decision and per unit, evidence as links. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR; commit it when confidence has to be shown. Prefer evidence produced by committed scripts so a reviewer can re-run it. The trail plus the diff is what lets the human come back and trust the work.
+
+## Phase E: Verify and hand back
+
+Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script, so the win can't silently regress (the **encode-lessons-in-structure** principle skill).
+
+**Reply:** the playbook you designed, the rigor level and why, the decision-trail path, what's verified against the predicate, and what's still open.

package/dist/kpi/kstack/generated/skills/how/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: how
+description: "Use for \"how does X work\", code walkthroughs before changing something, and placement / ownership / layering questions (\"where should this live\", \"which package owns this\", \"is this the right layer\"). Explains subsystem architecture, runtime flow, onboarding mental models. Can critique architecture. Use why for motivation."
+disable-model-invocation: true
+---
+
+# How
+
+Explore the codebase to answer "how does X work?" questions. Produce clear architectural explanations at the level of a senior engineer onboarding onto a subsystem. Enough to build a working mental model, not annotated source code.
+
+Two modes:
+
+1. **Explain** (default). Explore the codebase and produce a clear explanation
+2. **Critique.** Explain first, then spawn multiple models to independently identify architectural issues
+
+## Explain Mode
+
+### Step 1. Understand the Question and Assess Complexity
+
+Parse what the user is asking about:
+
+- "How does the rate limiter work?", a subsystem
+- "How do we handle billing for on-demand usage?", a feature flow
+- "How is the auth service structured?", an architectural overview
+- "Walk me through what happens when a user submits a form", a runtime trace
+
+Identify the scope. If ambiguous, state your best-guess interpretation before exploring. Don't ask. Let the user redirect if you're off.
+
+**Assess complexity to decide the approach:**
+
+- **Simple** (a single module, a small utility, a narrow question like "how does function X work"): skip explorer agents; the explainer explores and explains in a single pass. Go to Step 2b.
+- **Complex** (a subsystem spanning multiple files/services, a cross-cutting feature, a full architectural overview): spawn parallel explorer agents first, then hand off to the explainer. Go to Step 2a.
+
+When in doubt, lean simple. You can always spawn explorers if the explainer hits a wall.
+
+### Step 2a. Explore (complex questions only)
+
+Decompose the question into 2-4 parallel exploration angles, each a distinct slice of the subsystem so explorers don't duplicate work. Example split for "how does the rate limiter work?":
+
+- Explorer 1: data model and state management
+- Explorer 2: request path and enforcement
+- Explorer 3: configuration and metrics infrastructure
+
+The right decomposition depends on the question. Use your judgment. Narrow questions: 2 explorers is fine. Broad subsystems: up to 4.
+
+Spawn all explorers in a single message:
+
+- `role`: `generalPurpose`
+- `model`: your configured how-explorer model (roles resolved from `~/.kpi/agent/kstack/models.json`, set by `/setup-kstack`)
+- `readonly`: `true`
+
+Each explorer gets the same base prompt from `references/explorer-prompt.md` plus a specific exploration angle naming its slice. Each explorer should:
+- Start broad: Glob for relevant directories, Grep for key types/interfaces/class names
+- Follow the thread: from an entry point, trace the call chain (callers, callees, data flow, type definitions)
+- Read the actual code, don't guess from file names
+- Stop when it can describe the full path from input to output (or trigger to effect) without hand-waving any step
+- Note things that are surprising, non-obvious, or that a newcomer would get wrong
+
+Each explorer returns structured findings: components found, flow traced, files read, anything non-obvious. Overlap between explorers is fine; the explainer reconciles.
+
+Then proceed to Step 3.
+
+### Step 2b. Direct Explain (simple questions)
+
+Spawn a single background K-π worker that explores and explains in one pass:
+
+- `role`: `generalPurpose`
+- `model`: your configured how-explainer model (roles resolved from `~/.kpi/agent/kstack/models.json`, set by `/setup-kstack`)
+- `readonly`: `true`
+
+The agent does its own exploration (Glob, Grep, Read) and writes the explanation directly. Read `references/explainer-prompt.md` for the communication style and output format. Same structure, just no explorer findings as input.
+
+Proceed to Step 4.
+
+### Step 3. Synthesize (complex questions only)
+
+Once all explorers return, spawn a single background K-π worker to synthesize their findings into one coherent explanation:
+
+- `role`: `generalPurpose`
+- `model`: your configured how-explainer model (roles resolved from `~/.kpi/agent/kstack/models.json`, set by `/setup-kstack`)
+- `readonly`: `true`
+
+The explainer gets all explorers' findings and writes the human-facing explanation (output format below). Read `references/explainer-prompt.md` for the full prompt template. The explainer reconciles overlapping findings, resolves contradictions, and weaves the slices into a unified picture.
+
+### Step 4. Present
+
+Present the explainer's output to the user. You may lightly edit for clarity or add context from the conversation, but don't substantially rewrite. The explainer's communication is the product.
+
+### Output Format
+
+Follow this structure, adapted to the question. Not every section is needed for every question.
+
+**Overview.** 1-2 paragraphs. What it is, what it does, why it exists. Enough to decide whether to keep reading.
+
+**Key Concepts.** The important types, services, or abstractions. Brief definition of each. Not exhaustive, just the ones needed to understand the rest.
+
+**How It Works.** The core of the explanation. Walk through the flow: what triggers it, what happens step by step, where data goes, the decision points. Prose, not pseudocode. Reference specific files and functions so the reader can go look, but don't dump code blocks unless a snippet is genuinely necessary.
+
+**Where Things Live.** A brief map of the relevant files/directories. Not every file, just the ones needed to start working in this area.
+
+**Gotchas.** Non-obvious or surprising things that would trip someone up. Historical context that explains why something looks weird. Known sharp edges.
+
+## Critique Mode
+
+Triggered when the user asks for architectural issues, problems, or improvements, not just understanding.
+
+### Step 1. Explain First
+
+Run the full explain flow above (Steps 1-4). You must understand the architecture before critiquing it.
+
+### Step 2. Spawn Critics
+
+After the explanation is complete, spawn one architectural critic per model in your configured how-critics list (roles resolved from `~/.kpi/agent/kstack/models.json`, set by `/setup-kstack`), all in a single message.
+
+For each critic:
+- `role`: `generalPurpose`
+- `model`: one model from the configured how-critics list. These are minimum reasoning levels. The lead should escalate any model when the architecture warrants deeper analysis.
+- `readonly`: `true`
+
+Read `references/critic-prompt.md` for the prompt template. Each critic gets:
+1. The explanation from Step 1 (so they don't re-explore)
+2. The relevant file paths (so they can read the actual code)
+3. The architectural critique rubric from `references/critique-rubric.md`
+
+### Step 3. Lead Judgment
+
+Same framework as the interrogate skill. You're a pragmatic lead, not an aggregator.
+
+Categorize findings:
+- **Act on.** Architectural problems worth fixing now
+- **Consider.** Real concerns, but the cost/benefit is unclear
+- **Noted.** Valid observations, low priority
+- **Dismissed.** Wrong, missing context, or style preference
+
+Present the explanation first (from Step 1), then the critique verdict below it. The explanation should stand on its own; someone who just wants to understand the system shouldn't wade through critique.

package/dist/kpi/kstack/generated/skills/how/references/critic-prompt.md

@@ -0,0 +1,59 @@
+# Critic Prompt Template
+
+Build each critic background K-π worker's prompt from this template. Fill in the placeholders.
+
+---
+
+You are reviewing the architecture of a codebase subsystem. An explanation of how it works has already been written. Read it to orient yourself, then read the actual code to form your own judgment.
+
+## Architectural Explanation
+
+{EXPLANATION}
+
+## Relevant Files
+
+{FILE_PATHS}
+
+## Critique Rubric
+
+{CRITIQUE_RUBRIC_CONTENTS}
+
+## Instructions
+
+Read the files listed above. Use the explanation as a map, but form your own opinions from the code itself. The explanation might miss things or frame them charitably.
+
+Find architectural problems, not line-level bugs or style issues. Ask whether this subsystem is built well for what it needs to do and how it will need to evolve.
+
+For each finding:
+
+1. **Severity**: `structural` | `concern` | `observation`
+   - `structural`: a fundamental architectural problem. Wrong abstraction boundary, broken data model, coupling that will block future work
+   - `concern`: a real issue that makes the system harder to work with or reason about, but not fundamentally broken
+   - `observation`: worth noting. A tradeoff that might not age well, a pattern inconsistent with the rest of the codebase, technical debt
+2. **Finding**: the architectural issue. Be specific. Name the components, the boundary, the coupling.
+3. **Evidence**: concrete code that demonstrates the problem. Don't just assert that "this is too coupled". Show the dependency chain.
+4. **Impact**: what the issue costs. Harder to test? Harder to change? Performance cliff at scale? Be concrete about the consequence.
+
+## What to Avoid
+
+- Line-level code review (not your job here)
+- Suggesting rewrites without demonstrating a problem with the current approach
+- "This could use more abstraction" without showing what the abstraction would actually solve
+- Flagging intentional tradeoffs with clear benefits as issues
+
+If the architecture is sound, say so. An empty critique is a valid outcome.
+
+## Output
+
+```
+## Findings
+
+### 1. [Severity] Short title
+**Components**: Which parts of the system are involved
+**Finding**: What's wrong architecturally
+**Evidence**: Concrete code references
+**Impact**: What this costs in practice
+
+### 2. [Severity] Short title
+...
+```

package/dist/kpi/kstack/generated/skills/how/references/critique-rubric.md

@@ -0,0 +1,58 @@
+# Architectural Critique Rubric
+
+Review through whichever of these lenses are relevant. Not every lens applies to every subsystem.
+
+## Abstraction Fit
+
+Are the abstractions pulling their weight?
+
+- Does each abstraction represent a real concept, or is it an indirection layer "in case we need it"?
+- Are the boundaries in the right place? Do they separate things that change independently?
+- Is there accidental coupling where components share implementation details they shouldn't need to know about?
+- Is business logic entangled with framework wiring, or cleanly separated?
+
+Over-abstraction is as much a problem as under-abstraction. A flat, simple design is fine when the domain is simple.
+
+## Data Model
+
+Do the data structures fit the actual usage patterns?
+
+- Are the data models designed for how data is actually accessed, or for how it was conceptually modeled?
+- Are there impedance mismatches, places where code constantly reshapes data because the model doesn't match the access pattern?
+- Are types honest? Do they represent what data actually looks like at runtime, or claim more structure than exists?
+
+## Boundary Discipline
+
+Are system boundaries clean and well-placed?
+
+- Is validation concentrated at entry points, or scattered through internal code?
+- Are errors handled at boundaries and propagated cleanly, or caught and re-thrown at every layer?
+- Does data cross boundaries in well-typed shapes, or as bags of optional fields?
+- Could this subsystem be tested in isolation, or does it require the entire system to be running?
+
+## Evolution Readiness
+
+How well will this architecture handle likely changes?
+
+- If the most probable next requirement landed tomorrow, how much would change? "One file" or "everything"?
+- Are there hardcoded assumptions that would need to be relaxed?
+- Is the design bolted-on (integrated as an afterthought) or integrated (looks like it was always part of the plan)?
+- Are legacy paths preserved for compatibility that no one depends on?
+
+Don't penalize for not handling hypothetical changes. Focus on changes plausible given the codebase's trajectory.
+
+## Complexity vs. Value
+
+Is the complexity budget spent wisely?
+
+- Is complexity concentrated in the parts that need it (core logic, tricky invariants) or in accidental places (boilerplate, unnecessary indirection, configuration)?
+- Are there simpler ways to achieve the same behavior?
+- Does every component earn its existence, or are there vestigial pieces from an earlier design?
+
+## Consistency
+
+Does this subsystem follow the patterns established elsewhere in the codebase?
+
+- Are similar problems solved the same way here as elsewhere, or does this area invent its own patterns?
+- If the patterns differ, is there a good reason, or did it just evolve independently?
+- Inconsistency isn't automatically bad. But unexplained inconsistency is a maintenance burden.