raga-cli 0.0.0-stage → 0.9.0

package/bundled-skills/skills/peak/references/control-cli/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: control-cli
+description: Build or adapt a local harness to drive, inspect, and profile an interactive CLI or TUI without external services. Use for CLI UX checks, startup regressions, memory leaks, hangs, prompt flows, or terminal demos.
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Control CLI
+
+Use a repeatable local harness to exercise an interactive CLI instead of poking at it manually. First reuse the repo's own test/demo harness if it exists; otherwise assemble a temporary harness from standard local tools.
+
+## What It Is Used For
+
+- Reproducing CLI/TUI bugs with deterministic input.
+- Verifying keyboard flows, prompts, interrupts, resize behavior, and terminal layout.
+- Capturing before/after transcripts for bug fixes.
+- Profiling startup time, slow operations, hangs, or memory growth.
+- Recording a short terminal demo when output is easier to show than explain.
+
+## Harness Loop
+
+1. Identify the command under test and the smallest reproducible workspace.
+2. Discover existing local harnesses: package scripts, e2e tests, demo recorders, expect scripts, or PTY helpers.
+3. If no harness exists, launch the CLI in an isolated terminal session with deterministic env vars.
+4. Capture the current screen before interacting.
+5. Send one action at a time: text, Enter, arrows, Escape, Ctrl-C, resize.
+6. Wait for a concrete screen pattern or prompt before the next action.
+7. Save the transcript and any profile artifacts.
+8. Kill the session cleanly.
+
+## Harness Options
+
+- Repo-native harness: prefer checked-in scripts because they know the app's startup, env, and prompts.
+- `tmux`: managed sessions, `capture-pane`, `send-keys`, attach/detach.
+- PTY probe: use a short Python, Node, or Expect script when tmux is unavailable.
+- Runtime inspector: use Node or Bun inspector for CPU profiles, heap snapshots, and live evaluation.
+- Terminal recorder: use repo-local demo tools or asciinema-compatible tools when the user asks for a demo.
+
+## Minimal tmux Harness
+
+```bash
+SESSION="cli-harness-$(date +%s)"
+tmux new-session -d -s "$SESSION" -- <command-under-test>
+tmux capture-pane -pt "$SESSION"
+tmux send-keys -t "$SESSION" "help" Enter
+tmux capture-pane -pt "$SESSION"
+tmux kill-session -t "$SESSION"
+```
+
+For Node CLIs:
+
+```bash
+NODE_OPTIONS="--inspect=127.0.0.1:0" tmux new-session -d -s "$SESSION" -- <node-cli-command>
+```
+
+Read the terminal output to find the inspector URL, then use Chrome DevTools-compatible tooling if profiling is needed.
+
+## Minimal PTY Harness
+
+Use a PTY script when you need deterministic waits in a repo that does not have tmux or a demo harness. Keep it temporary unless the user asks to add a reusable test.
+
+```python
+import os
+import pty
+import select
+import subprocess
+import time
+
+master_fd, slave_fd = pty.openpty()
+proc = subprocess.Popen(
+    ["<command>", "<arg>"],
+    stdin=slave_fd,
+    stdout=slave_fd,
+    stderr=slave_fd,
+    close_fds=True,
+)
+os.close(slave_fd)
+
+deadline = time.time() + 30
+buffer = b""
+while time.time() < deadline:
+    ready, _, _ = select.select([master_fd], [], [], 0.25)
+    if not ready:
+        continue
+    chunk = os.read(master_fd, 4096)
+    buffer += chunk
+    if b"<ready text>" in buffer:
+        os.write(master_fd, b"help\n")
+        break
+
+print(buffer.decode(errors="replace"))
+proc.terminate()
+os.close(master_fd)
+```
+
+If the CLI needs richer terminal control, use `pty.fork()` or an existing PTY library.
+
+## Profiling Recipes
+
+- Startup regression: capture baseline and treatment startup timings under the same machine, env, and command.
+- Slow operation: start a CPU profile, perform the operation, stop the profile, and compare top self-time functions.
+- Memory leak: force GC if available, take a heap snapshot, perform the operation repeatedly, force GC again, and take another snapshot.
+- Hang: capture the screen, active handles/resources, and a stack/CPU sample before interrupting.
+
+## Guardrails
+
+- Prefer deterministic waits over sleeps. If you must sleep, explain why.
+- Do not send credentials or destructive commands into a controlled session.
+- Keep the harness in `/tmp` unless the repo already has a testing/demo harness.
+- Do not hard-code paths from another repository. Adapt commands to the current repo's scripts and runtime.
+- Clean up tmux sessions, temp dirs, inspector processes, and demo artifacts unless the user asks to keep them.

package/bundled-skills/skills/peak/references/control-ui/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: control-ui
+description: Build or adapt a local browser/CDP harness to drive and inspect a web, IDE, or Electron UI. Use for local UI verification, screenshots, accessibility snapshots, perf profiles, visual diffs, or reproducing UI bugs.
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Control UI
+
+Use local browser automation to verify UI behavior with evidence. First reuse the repo's own Playwright, browser, or Electron harness if it exists; otherwise assemble a temporary local harness around the app's dev server or Chromium debug port.
+
+## What It Is Used For
+
+- Reproducing UI bugs that depend on real browser focus, keyboard input, scrolling, resizing, or rendering.
+- Verifying visual or accessibility changes with screenshots and snapshots.
+- Checking local web, IDE, or Electron behavior before shipping.
+- Capturing console logs, network logs, CPU profiles, traces, or heap snapshots.
+- Creating before/after evidence for `verify-this`.
+
+## Setup Pattern
+
+1. Start the app locally using the repo's documented dev command.
+2. Discover existing local harnesses: Playwright tests, Cypress specs, Storybook, browser scripts, Electron launch scripts, or snapshot tools.
+3. For a web app, connect to the local URL with the existing browser tooling.
+4. For Electron/Chromium, enable a remote debugging port when supported.
+5. Select the correct page by stable app markers, not by tab order alone.
+6. Prefer accessibility roles, labels, and stable `data-*` selectors over coordinates.
+
+## Generic Web Harness
+
+Use the repo's installed browser tooling when possible. If the repo already has Playwright, a minimal one-off probe looks like:
+
+```javascript
+import { chromium } from "playwright";
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+await page.goto("http://127.0.0.1:<port>");
+await page.getByRole("button", { name: /submit/i }).click();
+await page.screenshot({ path: "/tmp/ui-harness-after.png", fullPage: true });
+await browser.close();
+```
+
+Do not add Playwright as a project dependency just for this probe unless the user asks. Prefer existing dev dependencies or external browser tools already available in the environment.
+
+## Generic CDP Harness
+
+For Electron or a Chromium app launched with `--remote-debugging-port=<port>`, connect over CDP:
+
+```javascript
+import { chromium } from "playwright";
+
+const browser = await chromium.connectOverCDP("http://127.0.0.1:<debug-port>");
+const pages = browser.contexts().flatMap((context) => context.pages());
+let page;
+for (const candidate of pages) {
+  if (await candidate.locator("<app-root-selector>").count()) {
+    page = candidate;
+    break;
+  }
+}
+
+if (!page) {
+  console.log(await Promise.all(pages.map(async (p) => ({
+    title: await p.title(),
+    url: p.url(),
+  }))));
+  throw new Error("No matching app page found");
+}
+
+await page.screenshot({ path: "/tmp/ui-harness-cdp.png", fullPage: true });
+await browser.close();
+```
+
+Replace `<app-root-selector>` with a stable marker from the current repo, such as a root app node, landmark, or product-specific `data-*` attribute.
+
+## Interaction Loop
+
+1. Capture a page snapshot or screenshot before acting.
+2. Choose a target from the latest page structure.
+3. Perform exactly one structural action: click, type, keypress, drag, scroll, navigate, or resize.
+4. Capture a fresh snapshot/screenshot.
+5. Verify the expected state change.
+6. Save artifacts for before/after comparisons when the user asked for proof.
+
+## CDP Capabilities
+
+Use raw CDP only when higher-level browser APIs are insufficient:
+
+- Performance: CPU profiles, traces, paint flashing, FPS meter, layout shift inspection.
+- Memory: heap snapshots and forced GC for leak investigations.
+- Network: request blocking, throttling, cache disablement, request/response logs.
+- Rendering: viewport changes, color scheme emulation, reduced motion, accessibility checks.
+- Debugging: console streaming, exception capture, DOM snapshots.
+
+## Page Selection
+
+When multiple app windows/tabs share a debug port:
+
+- Prefer a positive marker for the surface under test, such as an app root selector.
+- Use a negative marker to avoid the wrong surface when necessary.
+- If no page matches, list available page titles and URLs instead of guessing.
+
+## Guardrails
+
+- Do not rely on stale element references after navigation or structural changes.
+- Avoid coordinate clicks unless a fresh screenshot was captured immediately before the click.
+- Keep test data local and disposable.
+- Do not store screenshots or heap snapshots from privacy-sensitive workspaces unless the user explicitly agrees.
+- Do not hard-code selectors, ports, or script paths from another repository. Discover the current repo's local app markers.
+- Clean up dev servers, debug sessions, and temp profiles when done.

package/bundled-skills/skills/peak/references/correct/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: correct
+description: "Find the mistakes agents keep repeating in this repo and make each one impossible. Try architecture first, then types, then a lint whose error names the fix, then a test, and write docs last. Prove each check fails on a real past mistake. Repeat this each time the operator corrects you. Use for /correct."
+disable-model-invocation: true
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Correct
+
+The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them.
+
+Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo.
+
+## Find the mistake classes
+
+First, read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Group the mistakes into classes. A class counts once it has happened twice.
+
+## Fix each class at the highest level that works
+
+1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy.
+2. **Enforce it with types so the bad state can't be written.** If bad code still compiles, add a lint or CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more.
+3. **Test the behavior.** Fix or delete any test that still passes when the behavior it checks breaks, or that fails when only the internals change.
+4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them.
+
+## Fix and prove
+
+Then fix the most frequent classes now, one commit each. Prove each new check fails on a real past mistake. Run the same command locally and in CI. Exceptions go on the offending line with a reason, an expiry date, and a human's approval.
+
+## Keep the rule table
+
+Last, keep a table in the agent instruction file that pairs each rule with what enforces it. When the operator corrects you, fix the mistake and add the rule. If the rule was already there and nothing enforces it, that's a repeat, so fix it at the highest level in the same change. Drop a rule once its mistake can't happen.
+
+**Reply:** each class with its evidence, the level you picked, and why a higher level didn't work.

package/bundled-skills/skills/peak/references/create-formal-verification-skill/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: create-formal-verification-skill
+description: "Generate a project-local skill that formally verifies the code where a bug costs the most and tests reach the least, in any language, with whichever verification tool fits. Use for /create-formal-verification-skill, \"model-check this race\", \"prove this invariant\", or when concurrency, retries, state machines, parsers, or unsafe code need more than tests."
+disable-model-invocation: true
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Create a formal verification skill
+
+A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language.
+
+## Choose the target from the code
+
+Answer from the codebase, and ask the user only what you cannot observe. If the user named an area or a bug, start there.
+
+A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify.
+
+## Let the question choose the tool
+
+Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. Whether events can happen in a bad order usually suits a model checker over a small model of the design, and TLA+ is the default for that in any language. Whether the code itself behaves for every input, as with memory safety, overflow, or a data-structure invariant, usually suits a verifier that runs on the code. If no verifier runs on this language, say so, and test the real code with generated inputs, not a hand model of the function. A property that must hold at every size, where a bound is not enough, can need a proof. Prefer a tool that the repo's developers can install and run, and tell the user why you chose it.
+
+## What makes it good
+
+- **True to the code.** Every part of the model or proof points to code that a reviewer can open. What the verification treats as one indivisible step is one indivisible step in the code. Names come from this repo.
+- **Able to fail.** A check that you have never seen fail proves nothing. Show each property failing on a broken variant of the code it guards, such as a removed check or a reordered step.
+- **Findings stay findings.** When the current code breaks the property, report it with the counterexample in the code's terms. Do not weaken the property or the model until it passes, and do not change product code unless the user asks.
+- **Honest about scope.** Say what is verified, under which bounds and assumptions, and what is left out. A pass covers the model or the bound, not the whole system.
+- **Readable without the tool.** State the property and the harm in one plain sentence each. Tell a counterexample as a short sequence of steps in the code's words.
+- **Cheap to rerun.** One command, a reproducible tool version, and a run short enough that the next agent will use it on every relevant change.
+- **Kept in step with the code.** Record which files and functions each check covers, and the commit at which you last confirmed that the verification describes them. When the covered code changes after that commit, the next agent can see that the verification needs another look.
+
+## Generate the verify skill
+
+Write a project-local skill with frontmatter that names the area and says when to use it. Without frontmatter, the skill never registers. From the skill alone, the next agent must be able to tell whether a change touches the verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Put the coverage record and the sync commit in the skill, and tell the next agent to move the sync commit forward only after it confirms that the verification describes the code at the new commit. Use this repo's real commands, paths, and nouns, and leave no placeholders.
+
+## Prove it before you hand off
+
+Follow the generated skill once, as the next agent would, on a scratch change that breaks the property in the real code. It must catch the break. Then drop the scratch change and confirm that the check is back where it started: passing, or failing only on the findings you will report. A verify skill that was never run is a draft. If the skill misses the break or a step does not run, fix the skill or the verification, not the scratch change.
+
+## Hand off
+
+Tell the user what you verified, which tool you used and why, the bounds, what the check found in plain words, how to run it, and what it does not cover. Suggest a second target only if you found a close one. Point the user at `/maintain-formal-verification-skill` for bringing the verification back in line after changes that did not recheck it.

package/bundled-skills/skills/peak/references/create-skill/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: create-skill
+description: Author or revise a portable Agent Skills workflow in a candidate harness revision with explicit inputs and behavioral checks.
+---
+
+# Author a candidate skill
+
+Define the trigger, input data, observable result, dependencies, side effects, approval boundaries, and failure behavior. Read nearby skills before choosing a shape. Use the native adapter at [raga-runtime](../raga-runtime/SKILL.md).
+
+Request a candidate with `candidate = await instance.candidate_create()`. Read an existing resource with `await instance.candidate_read(candidate['id'], path)`. Write the proposed text with `await instance.candidate_write(candidate['id'], path, content)`. Never edit an accepted revision or a global skill installation. Use `skills/peak/references/<name>/SKILL.md`, with a lowercase hyphenated name and a description in YAML frontmatter. Keep helpers beside the reference. Resolve relative paths from that directory. Add the new reference to the index in `skills/peak/SKILL.md`.
+
+Exercise success, input variation, failure, and ambiguous cases with real input. Executable Python helpers must pass fresh sandboxed interpreter probes without session globals. Record dependencies and external effects. A source-text assertion does not prove behavior. An unsupported capability reports its setup prerequisites.
+
+Commit through `await instance.candidate_commit(candidate['id'], message)` and hand the candidate ID and evidence to the user. Promotion belongs to the trusted supervisor and explicit user approval. Host extension activation requires separate review. A skill cannot grant itself network or publication authority.

package/bundled-skills/skills/peak/references/create-verification-skill/SKILL.md

@@ -0,0 +1,46 @@
+---
+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
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# 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 (`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 `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 prompt). Launch must reach a usable state from an empty data dir, including any migrations and seed data. Ready means usable, not just that a process answers. A database health check can pass while its init scripts are still running. 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 `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`. If the seed data lacks a precondition that a journey needs, the journey reports a failure and the reason goes in that feature's `Gotchas`. Never weaken the journey to make it pass. 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. If you proved it in a stand-in for the real target (a container in place of a fresh VM, a local stack in place of a remote one), list every setup step the stand-in did that the target will not. Those steps stay unverified until a run on the real target covers them.
+
+## 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/bundled-skills/skills/peak/references/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/bundled-skills/skills/peak/references/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/bundled-skills/skills/peak/references/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/bundled-skills/skills/peak/references/deslop/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: deslop
+description: Remove AI-generated code slop and clean up code style
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Remove AI code slop
+
+Check the diff against main and remove AI-generated slop introduced in the branch.
+
+## Focus Areas
+
+- Extra comments that are unnecessary or inconsistent with local style
+- Defensive checks or try/catch blocks that are abnormal for trusted code paths
+- Casts to `any` used only to bypass type issues
+- Deeply nested code that should be simplified with early returns
+- Other patterns inconsistent with the file and surrounding codebase
+
+## Guardrails
+
+- Keep behavior unchanged unless fixing a clear bug.
+- Prefer minimal, focused edits over broad rewrites.
+- Keep the final summary concise (1-3 sentences).

package/bundled-skills/skills/peak/references/figure-it-out/SKILL.md

@@ -0,0 +1,54 @@
+---
+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. Use for /figure-it-out or 'figure it out'."
+disable-model-invocation: true
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# 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.
+
+## Start
+
+Open a todolist whose first item is to read the Principles section of the **peak** 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).
+- Scope, quantified: rough units and effort, plus the blockers grounding surfaced.
+- 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. 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**). 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 seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **peak** skill.
+- Write the designed phase list down. That list is what the human reviews.
+
+Then execute the design. Add its steps to the todolist as concrete items between the Phase C and Phase D entries. 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.
+- Pair delegated work with a judge. 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. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. 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 (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/bundled-skills/skills/peak/references/how/SKILL.md

@@ -0,0 +1,38 @@
+---
+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. Use why for motivation."
+disable-model-invocation: true
+---
+
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# How
+
+Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
+
+Every spawn is a native raga child with `spec: worker` and `read_only=True`. Explorers use the `how explorer` line in the `model-roles.json` rule (default `None`), and every explainer uses the `how explainer` line (default `None`). Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If a configured model is rejected, report the unavailable selector and stop that seat. Do not silently substitute another model. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **peak** skill.
+
+## 1. Assess complexity
+
+If the scope is ambiguous, state your interpretation and explore. The user can redirect.
+
+- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from `references/explainer-prompt.md` without the explorer-findings section. Go to step 4.
+- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2.
+
+When in doubt, take the simple path.
+
+## 2. Explore (complex only)
+
+Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Spawn all explorers in a single message, each with `references/explorer-prompt.md` and its angle filled in.
+
+## 3. Synthesize (complex only)
+
+Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in.
+
+## 4. Present
+
+Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
+
+## Output format
+
+The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.