raga-cli 0.0.0-stage → 0.9.0

package/bundled-skills/docs/guide/README.md

@@ -0,0 +1,38 @@
+# The pstack guide
+
+pstack works best when you stop micromanaging the agent. You describe what you want and how you'll know it's done. `/peak` picks the playbook, reads the references the steps need, and shows you the evidence. This guide teaches that habit with realistic prompts.
+
+Here's what you'll learn:
+
+1. [Set up pstack](./01-setup.md). Install the plugin and pick your models.
+2. [Route work through `/peak`](./02-peak.md). Give it a goal and watch it pick a playbook.
+3. [Understand the code](./03-understand.md). A read-only investigation, then `/how`, `/why`, `/teach`, and `/recall` before you edit anything.
+4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, `/interrogate`, prototypes, and plans before code locks in a shape.
+5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`.
+6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, formally verify what tests rarely reach, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged.
+7. [Run work while you sleep](./07-overnight.md). Trust before loops, an overnight contract, a decision log you can audit, and Projects and automations that scale past one agent.
+8. [Steer with principle names](./08-principles.md). The 24 names that redirect an agent mid-task.
+9. [Make it yours](./09-make-it-yours.md). Your own mode, `/correct` for repeated mistakes, and how to test a skill change.
+10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip.
+
+Read the pages in order the first time. After that, each page stands alone.
+
+When you're stuck, or can't tell which skill fits, type [`/poteto-help`](../../skills/peak/references/poteto-help/SKILL.md) with your question:
+
+```text
+/poteto-help which skill should i use to review this branch?
+```
+
+It answers, hands you a prompt to send, and links the skill or guide page the answer came from. It doesn't start the work, because a pstack run spends real tokens, so you send the prompt when you're ready. It runs only when you type it.
+
+## If you only remember one thing
+
+Give the agent a goal and a way to check it, in your own words:
+
+```text
+/peak the export writes duplicate rows when a retry lands mid-run. repro first, then fix and verify.
+```
+
+You don't need to name a playbook or list skills. "repro first" and a checkable outcome are all the routing signal `/peak` needs. It matches the Bug fix playbook, copies the steps into a todo list, and reads the right references as each step fires.
+
+Next: [Set up pstack](./01-setup.md).

package/bundled-skills/licenses/commander

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/bundled-skills/licenses/cursor-team-kit

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-skills/licenses/no-mistakes

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kun Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-skills/licenses/pstack

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bundled-skills/skills/bend/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: bend
+description: Turn rules the user states in plain words into Bend laws, write the proofs, and check them with the bend CLI. Use when the user asks to formally verify, prove, or guarantee that a rule can never break.
+---
+
+# Bend formal verification
+
+You write Bend laws and proofs for the user. The user decides the rules. Bend decides whether the proofs hold. Never claim a rule is proven unless `bend` printed `ALL PROOFS CHECK`.
+
+By Bend convention, `LAWS.bend` states the rules and `PROOF.bend` proves them. Here you write both, so the user must approve every law before you write proofs. After approval, a law is the spec. Do not edit it to make a proof pass.
+
+## Load the helper
+
+Work in the Python tool. Load the helper beside this file, then find the CLI:
+
+```python
+exec(await read("<directory of this SKILL.md>/bend_tool.py"), globals())
+bend = find_bend()
+files = law_files()
+```
+
+`find_bend()` checks `BEND_BIN`, then `PATH`, then `~/.bend/bin/bend`. If it returns `None`, stop. Ask the user to install Bend with `curl -fsSL https://bend-lang.com/install.sh | sh`. Do not install it yourself.
+
+Outside the Python tool, run the same commands with bash: `bend guide`, `bend PROOF.bend --check-only`.
+
+## Read the guide first
+
+Run `guide = await bend_guide()` and keep it in a variable. Read the sections on laws and proofs, recursion and termination, quantities, and kinds before you write Bend. Search the variable for anything else you need. `bend base --types` and `bend base <name>` print the standard library.
+
+## Steps
+
+1. **Ask for the rules.** Ask the user which rules must never break, then stop and wait for the answer. Offer two or three concrete examples taken from the project. Do not invent rules. If the user asks you to choose, propose rules in plain words and wait for confirmation.
+2. **Write the laws.** Write `files["laws"]`. Start with `import Base`. Define, in Bend, the code or model each rule talks about, then add one `law` per rule. Put the user's own words in a `# LAW:` comment above each law. Keep each law to one rule.
+3. **Check that the laws parse.** Write a `files["proof"]` that only imports `./LAWS.bend as Laws`, then run `await bend_check(files["proof"])`. Expect `SOME PROOFS FAIL` with a count of open claims. Fix any other error in the laws file.
+4. **Get approval.** Show the user each law twice: the Bend text and a one-sentence plain reading. Say what the laws do not cover. Ask whether they match the intended rules. Revise and ask again until the user approves. After the user says yes, call `approve_laws(files["laws"])`. A message the user sent before you asked is not approval. `bend_check` fails until the laws are approved.
+5. **Write the proofs.** In `files["proof"]`, prove each law with `def Laws.<law name>`. Do not write a `law` in the proof file, and do not move a law out of the laws file. The laws file includes its definitions. If a proof needs any change to that file, stop, show the user the change, and call `approve_laws` again only after a new yes. Run `await bend_check(files["proof"])` after each change. Read `problems` first, then the expected and observed terms in `output`. Use `?name` to print a goal while you work.
+6. **Handle a law you cannot prove.** If the output shows the law is false, show the user the counterexample and ask how to change the rule. If you cannot find a proof, leave `?TODO` in that def and report the law as open. Never use `@unsafe` or foreign code in a proof.
+7. **Report.** A check passes only when `bend_check` returns `verdict` `passed`, which needs `ALL PROOFS CHECK` and an empty `problems` list. Run the final check through `bend_check`, not bash. Quote its `verdict` and `problems` and the verdict line from `output`. Copy each law from the laws file as written. Do not retype or restate it in Bend. List each law as proven or open. If Lean is installed, `await bend_check(files["proof"], verdict=True)` rechecks with the Lean-proven kernel. Report its result separately.
+
+## Where the files go
+
+`law_files()` reads custom file names from `.raga/verification.json`.
+
+- In an ordinary session, `files["directory"]` is `.raga/verification/`. These are the files the instance gate reads.
+- In an instance session, the sandbox hides `.raga`, so `files["directory"]` is `verification-draft/`. After the user approves, tell them to copy both files into `.raga/verification/`.
+
+## Turn on the gate
+
+Only the user can make a revision depend on these proofs. In an instance project, give the user these commands and let them run each one:
+
+- `raga verify install --approved --network` downloads the pinned Bend release the gate uses.
+- `raga verify enable --approved` requires a passing check before a harness revision becomes active.
+- `raga verify run` runs the check in the sandbox and records the verdict.
+
+## Limits
+
+- A law proves only the Bend code that `LAWS.bend` defines or imports. For a project in another language, the laws prove facts about a Bend model of the code. Say so in the report.
+- Proofs need structural recursion. Read the termination section before you write recursive defs.

package/bundled-skills/skills/bend/bend_tool.py

@@ -0,0 +1,144 @@
+"""Bend helpers for the raga Python REPL. Load with exec(await read(path), globals())."""
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+
+BEND_INSTALL = "curl -fsSL https://bend-lang.com/install.sh | sh"
+CHECK_TIMEOUT = 600
+
+
+def find_bend():
+    """Path of the bend executable, or None. BEND_BIN wins, then PATH, then the installer's default."""
+    for candidate in (os.environ.get("BEND_BIN"), shutil.which("bend"), os.path.expanduser("~/.bend/bin/bend")):
+        if candidate and os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+def law_files(project="."):
+    """Where LAWS.bend and PROOF.bend belong, and whether this session may write there.
+
+    An ordinary session writes the files the instance gate reads: .raga/verification/<laws> and <proof>,
+    named by .raga/verification.json. An instance session cannot write .raga, so it drafts under
+    verification-draft/ for the user to copy.
+    """
+    project = os.path.abspath(project)
+    names = {"laws": "LAWS.bend", "proof": "PROOF.bend"}
+    config = os.path.join(project, ".raga", "verification.json")
+    if os.path.isfile(config):
+        with open(config, encoding="utf-8") as handle:
+            data = json.load(handle)
+        names = {key: data.get(key) or default for key, default in names.items()}
+    instance = bool(os.environ.get("RAGA_INSTANCE_ID"))
+    directory = os.path.join(project, "verification-draft" if instance else os.path.join(".raga", "verification"))
+    return {
+        "directory": directory,
+        "laws": os.path.join(directory, names["laws"]),
+        "proof": os.path.join(directory, names["proof"]),
+        "mode": "instance" if instance else "ordinary",
+    }
+
+
+async def _run(command, cwd):
+    line = "cd " + shlex.quote(cwd) + " && " + command + " 2>&1; printf '\\nEXIT=%s\\n' $?"
+    runner = globals().get("bash")
+    if runner is not None:
+        output = await runner(line, timeout=CHECK_TIMEOUT)
+    else:
+        process = await asyncio.create_subprocess_shell(line, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
+        stdout, _ = await asyncio.wait_for(process.communicate(), CHECK_TIMEOUT)
+        output = stdout.decode("utf-8", "replace")
+    body, _, code = output.rstrip().rpartition("\nEXIT=")
+    return body.strip(), int(code) if code.strip().isdigit() else None
+
+
+async def bend_guide(topic=None):
+    """The Bend guide text, or one named sub-guide such as "shaders"."""
+    bend = find_bend()
+    if bend is None:
+        raise RuntimeError("bend is not installed. Ask the user to run: " + BEND_INSTALL)
+    output, code = await _run(shlex.quote(bend) + " guide" + ((" " + shlex.quote(topic)) if topic else ""), os.getcwd())
+    if code != 0:
+        raise RuntimeError(output)
+    return output
+
+
+def _digest(path):
+    with open(path, "rb") as handle:
+        return hashlib.sha256(handle.read()).hexdigest()
+
+
+def approve_laws(laws_path):
+    """Record the laws the user approved. Call only after the user says yes."""
+    with open(laws_path + ".approved", "w", encoding="utf-8") as handle:
+        handle.write(_digest(laws_path) + "\n")
+
+
+def _problems(proof_path):
+    with open(proof_path, encoding="utf-8") as handle:
+        proof = handle.read()
+    imported = re.search(r"^import\s+\./(\S+)\s+as\s+Laws\s*$", proof, re.M)
+    if not imported:
+        return ["PROOF.bend must import the laws file as Laws"]
+    problems = []
+    if re.search(r"^law\s", proof, re.M):
+        problems.append("PROOF.bend states a law. Laws belong only in the laws file")
+    laws_path = os.path.join(os.path.dirname(proof_path), imported.group(1))
+    with open(laws_path, encoding="utf-8") as handle:
+        laws = handle.read()
+    if not re.search(r"^law\s", laws, re.M):
+        problems.append("the laws file states no law")
+    problems.extend(_unused_variables(laws))
+    approval = laws_path + ".approved"
+    if not os.path.isfile(approval):
+        problems.append("the user has not approved these laws. Show them to the user and call approve_laws after a yes")
+    else:
+        with open(approval, encoding="utf-8") as handle:
+            if handle.read().strip() != _digest(laws_path):
+                problems.append("the laws changed after the user approved them. Ask the user to approve them again")
+    return problems
+
+
+def _unused_variables(laws):
+    """A law whose statement ignores one of its `for` variables usually does not say what the user meant."""
+    problems = []
+    for name, body in re.findall(r"^law\s+([\w.]+)\s*:[^\n]*\n((?:[ \t]+[^\n]*(?:\n|$))+)", laws, re.M):
+        lines = [line.split("#", 1)[0].strip() for line in body.splitlines()]
+        binders = [line[4:].split(":", 1)[0] for line in lines if line.startswith("for ")]
+        statement = " ".join(line for line in lines if line and not line.startswith("for "))
+        for binder in binders:
+            for variable in (part.strip().lstrip("+-") for part in binder.split(",")):
+                if variable and not re.search(r"(?<![\w.])" + re.escape(variable) + r"(?!\w)", statement):
+                    problems.append("law " + name + " never uses its variable " + variable)
+    return problems
+
+
+async def bend_check(proof_path, verdict=False):
+    """Run the gate on PROOF.bend. Passed needs exit 0, ALL PROOFS CHECK, and no problems.
+
+    Problems are structural: a law stated in the proof file, a laws file without laws, or laws that
+    differ from the approved ones. verdict=True adds --verdict, which rechecks with the Lean-proven
+    kernel and needs Lean installed.
+    """
+    bend = find_bend()
+    if bend is None:
+        raise RuntimeError("bend is not installed. Ask the user to run: " + BEND_INSTALL)
+    proof_path = os.path.abspath(proof_path)
+    problems = _problems(proof_path)
+    command = shlex.quote(bend) + " " + shlex.quote(os.path.basename(proof_path)) + (" --verdict" if verdict else " --check-only")
+    output, code = await _run(command, os.path.dirname(proof_path))
+    passed = code == 0 and "ALL PROOFS CHECK" in output and not problems
+    if problems:
+        output = "CHECK REJECTED: " + "; ".join(problems) + ". Bend's own output follows and does not count.\n" + output
+    return {
+        "verdict": "passed" if passed else ("failed" if code is not None else "inconclusive"),
+        "problems": problems,
+        "exit_code": code,
+        "output": output,
+        "command": command,
+    }

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

@@ -0,0 +1,184 @@
+---
+name: peak
+description: The only bundled skill. Entry point for peak's agent style and the index of every engineering reference. Use for peak, /peak, or requests to work in this style.
+disable-model-invocation: true
+icon: crown
+color: yellow
+---
+
+Read [the native Python adapter](references/raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+
+# Peak
+
+Every reference lives at `references/<name>/SKILL.md` next to this file, so put this file's absolute path in every `poteto-agent` prompt.
+
+## Non-negotiables
+
+The reference index below grounds every trigger. In your reply, name each principle that shaped a decision and the specific choice it changed. Cite only principles whose reference you read in full this session.
+
+Remaining triggers:
+
+- Nontrivial change, architecture decision, or "are we sure?" → the **how** reference.
+- About to `ask the user in the final response` on a "which approach", "how should I", or "what should this do" fork → classify it before you ask. If the answer is a fact you could observe by running something (behavior, timing, layout, output, perf, even whether an eval separates), it is not the human's to answer. Sketch it via the Prototype playbook (`playbooks/prototype.md`) and let the result decide. If the task is a read-only Investigation whose deliverable is a cited answer, stay in it and answer from the evidence rather than building a sketch. Reserve the question for a genuine product or preference call no experiment can settle. Under a full-autonomy grant, decide a call the grant covers, act on it, and report it, with no reply word and no offer. Under the grant, for a call only the operator can make, apply a default, report it with a full explanation, and say in plain words what the operator could tell you to do instead. The operator answers in their own words. Never give a shorthand token to type back. Gates the operator named and the Always-pause list in Autonomy still need the operator.
+- Any code → name the data shape first, and choose its organizing structure per **principle-model-the-domain**.
+- Code crossing a function boundary → the **architect** reference, parallel design exploration before implementing.
+- Parallel fan-out → the **swarm** reference for coverage matrices, races, gauntlets, and exploration partitions. Use **arena** for design or code bakeoffs with base selection and grafting.
+- Contested design → the **interrogate** reference (multi-model adversarial) before shipping.
+- Nontrivial multi-step → write the throughput checkpoint (Feature step 3).
+- Any prose surface, your reply to the user included → the **unslop** reference. Write the reply per **Writing the reply**. Agent-facing prose also follows the **create-skill** reference (the raga candidate authoring workflow).
+- Docs, RFCs, readmes, PR descriptions, or commit messages → the **technical-writing** reference.
+- Before commit → the **deslop** reference.
+- Before review → the **no-comments** reference.
+- Shipping UI / IDE / CLI → the matching control reference. `cursor-team-kit` publishes `control-cli` (CLIs and TUIs) and `control-ui` (browser / Electron / web UIs). For bug fixes, reproduce first on the same surface yourself. Hand to the user only under the narrow Bug fix step 1 exception.
+- Running a benchmark, measuring perf yourself, or reporting a speedup or regression you measured → the **benchmark-checklist** reference before you report or act on the number.
+- Any PR-status request ("babysit this", "get it green", "address the reviewer comments", and most often "check on PR X" or "anything outstanding on X") → the **Babysit** playbook (`playbooks/babysit.md`). Never triggered by merely opening a PR. Declare its mode before polling. The playbook's step 1 owns the request-to-mode mapping. Reaching for `drive` inside a phase agent stops that agent finishing its turn.
+- Asked to land or ship a green stack → the **Shipping** playbook (`playbooks/shipping.md`). Green is not safe. Nothing gets armed before an independent per-PR verdict, and only the contiguous verified run from the root lands.
+- reviewer or the agentic security review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask per `references/reviewer-triage.md`.
+- Broken reference mid-task → fix it in its own PR. Don't block. Don't silently work around it.
+- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "continue the in-process loop until X") → a decision trail via the **show-me-your-work** reference. Commit it when stakes need an auditable record. Keep it local otherwise.
+
+## Reference index
+
+Peak, `bend`, and `raga-artifacts` are the installed skills. `bend` handles Bend formal verification, and `raga-artifacts` makes shareable slides and documents. Every other workflow is a reference under `references/<name>/SKILL.md`. Pick the reference whose description matches the task and read it in full before acting. Do not read them all.
+
+### Principles
+
+| Reference | Use when |
+| --- | --- |
+| [principle-attack-the-premise](references/principle-attack-the-premise/SKILL.md) | Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it. |
+| [principle-boundary-discipline](references/principle-boundary-discipline/SKILL.md) | Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions. |
+| [principle-build-the-lever](references/principle-build-the-lever/SKILL.md) | Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun. |
+| [principle-encode-lessons-in-structure](references/principle-encode-lessons-in-structure/SKILL.md) | Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text. |
+| [principle-exhaust-the-design-space](references/principle-exhaust-the-design-space/SKILL.md) | Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing. |
+| [principle-experience-first](references/principle-experience-first/SKILL.md) | Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones. |
+| [principle-explain-the-number](references/principle-explain-the-number/SKILL.md) | Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think. |
+| [principle-fix-root-causes](references/principle-fix-root-causes/SKILL.md) | Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate. |
+| [principle-foundational-thinking](references/principle-foundational-thinking/SKILL.md) | Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious. |
+| [principle-guard-the-context-window](references/principle-guard-the-context-window/SKILL.md) | Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads. |
+| [principle-laziness-protocol](references/principle-laziness-protocol/SKILL.md) | Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem. |
+| [principle-make-operations-idempotent](references/principle-make-operations-idempotent/SKILL.md) | Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs. |
+| [principle-migrate-callers-then-delete-legacy-apis](references/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) | Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers. |
+| [principle-minimize-reader-load](references/principle-minimize-reader-load/SKILL.md) | Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope. |
+| [principle-model-the-domain](references/principle-model-the-domain/SKILL.md) | Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files. |
+| [principle-never-block-on-the-human](references/principle-never-block-on-the-human/SKILL.md) | Apply when tempted to ask 'should I do X?' on reversible work. |
+| [principle-outcome-oriented-execution](references/principle-outcome-oriented-execution/SKILL.md) | Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code. |
+| [principle-prove-it-works](references/principle-prove-it-works/SKILL.md) | Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.' |
+| [principle-redesign-from-first-principles](references/principle-redesign-from-first-principles/SKILL.md) | Apply when integrating a new requirement into an existing design. |
+| [principle-separate-before-serializing-shared-state](references/principle-separate-before-serializing-shared-state/SKILL.md) | Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant. |
+| [principle-sequence-verifiable-units](references/principle-sequence-verifiable-units/SKILL.md) | Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer. |
+| [principle-subtract-before-you-add](references/principle-subtract-before-you-add/SKILL.md) | Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base. |
+| [principle-test-behavior-not-implementation](references/principle-test-behavior-not-implementation/SKILL.md) | Apply when you write, change, or keep a test. Assert what the code's users can observe, so that the test fails when that behavior breaks and keeps passing when only the internals change. |
+| [principle-type-system-discipline](references/principle-type-system-discipline/SKILL.md) | Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, exhaust variants, derive from authoritative schemas. |
+
+### Engineering workflows
+
+| Reference | Use when |
+| --- | --- |
+| [architect](references/architect/SKILL.md) | Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape. |
+| [arena](references/arena/SKILL.md) | Spawn N parallel candidates at the same task, pick a base, graft the strongest parts of the losers into it. Use for /arena, 'arena this', 'throw it in the arena', or when one attempt at a non-trivial artifact would lock in the wrong shape. |
+| [automate-me](references/automate-me/SKILL.md) | Use for \"automate me\", \"create/update/refresh my -mode skill\", \"turn/capture my preferences or working style into a skill\", or wanting agents to follow how the user works. Drafts or revises a personal -mode skill via create-skill + unslop, optionally pulling fresh evidence from recent transcripts. |
+| [benchmark-checklist](references/benchmark-checklist/SKILL.md) | Vet a perf measurement (limiter, tuning, limits, errors, repeatability, relevance, and whether the work happened) before you report or act on it. Use when you run a benchmark or report a speedup or regression you measured. |
+| [blast-radius](references/blast-radius/SKILL.md) | 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. |
+| [bro](references/bro/SKILL.md) | Restate the last message in plain human language, with no jargon. |
+| [control-cli](references/control-cli/SKILL.md) | 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. |
+| [control-ui](references/control-ui/SKILL.md) | 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. |
+| [correct](references/correct/SKILL.md) | 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. |
+| [create-formal-verification-skill](references/create-formal-verification-skill/SKILL.md) | 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. |
+| [create-skill](references/create-skill/SKILL.md) | Author or revise a portable Agent Skills workflow in a candidate harness revision with explicit inputs and behavioral checks. |
+| [create-verification-skill](references/create-verification-skill/SKILL.md) | 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. |
+| [deslop](references/deslop/SKILL.md) | Remove AI-generated code slop and clean up code style |
+| [figure-it-out](references/figure-it-out/SKILL.md) | 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'. |
+| [how](references/how/SKILL.md) | 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. |
+| [in-your-own-words](references/in-your-own-words/SKILL.md) | Restate in your own words what you think the user's goals are and what problem they're trying to solve. Use for /in-your-own-words. |
+| [interrogate](references/interrogate/SKILL.md) | Use for \"interrogate\", \"adversarial review\", \"multi-model review\", \"challenge this\", \"stress test this code\", \"find blind spots\", or \"tear this apart\". Multiple LLM reviewers challenge changes from independent angles. |
+| [ketchup](references/ketchup/SKILL.md) | Catch the user up on what changed in this chat since their last message, in plain words and small visuals. List every item waiting on them with what they need to decide it from the reply alone. Use for /ketchup. |
+| [maintain-formal-verification-skill](references/maintain-formal-verification-skill/SKILL.md) | Bring a project's formal verification back in line with the code after the code changes: find the commits that touched verified code, update the model, harness, or properties to describe the code as it is now, rerun, and say whether each failure is drift in the verification or a bug in the code. Use for /maintain-formal-verification-skill, \"is the model still true to the code\", or after merges and refactors that touched verified code without rechecking it. |
+| [maintain-verification-skill](references/maintain-verification-skill/SKILL.md) | Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\". |
+| [no-comments](references/no-comments/SKILL.md) | Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints. |
+| [no-mistakes](references/no-mistakes/SKILL.md) | Drive the explicitly enabled, pinned no-mistakes validation backend through the trusted instance supervisor. Use when asked to validate or gate committed code changes. |
+| [peak-setup](references/peak-setup/SKILL.md) | Configure real native model selectors for the bundled engineering workflows through a candidate harness revision. |
+| [poteto-help](references/poteto-help/SKILL.md) | Find the bundled engineering skill or playbook for understanding, design, implementation, verification, and communication. |
+| [raga-runtime](references/raga-runtime/SKILL.md) | Native Python runtime, child specification, capability, and instance adapter for the portable engineering skills. |
+| [recall](references/recall/SKILL.md) | Reconstruct your recent working context from your own chat history, live state, and the shared record (user reports, prior fixes, incidents), then hand back a tight current-state brief. Use for 'recall my work on X', 'catch me up', 'what have I been working on', 'where did I leave off', before starting or resuming work. |
+| [reflect](references/reflect/SKILL.md) | Spawn three parallel review subagents over the active transcript, surface learnings, and route each to a concrete edit on an existing skill. Use when the user says reflect. |
+| [sharpen](references/sharpen/SKILL.md) | Make a task deeper, not bigger, then rewrite the prompt. Use for /sharpen. |
+| [show-me-your-work](references/show-me-your-work/SKILL.md) | Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result). Local by default; commit it when a reviewer needs the trail to trust the result. Use for /show-me-your-work, autonomous or multi-phase runs, or work a human reviews after stepping away. |
+| [statechart](references/statechart/SKILL.md) | Draw what an app's user sees as a Mermaid statechart from a TLA+ model. States are gray if they work, red if still wrong, and green if fixed. Each bug TLC finds is a numbered path. Use for /statechart, \"show the PM the bug\", or to turn an agreed chart into a TLA+ skeleton. |
+| [swarm](references/swarm/SKILL.md) | Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration. |
+| [tdd](references/tdd/SKILL.md) | Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested. |
+| [teach](references/teach/SKILL.md) | Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'. |
+| [technical-writing](references/technical-writing/SKILL.md) | Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages. |
+| [typescript-best-practices](references/typescript-best-practices/SKILL.md) | TypeScript best practices. Use when reading or editing any .ts or .tsx file. |
+| [unslop](references/unslop/SKILL.md) | Cut AI tells from any writing. |
+| [verify-this](references/verify-this/SKILL.md) | Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare artifacts, and return VERIFIED, NOT VERIFIED, or INCONCLUSIVE. |
+| [why](references/why/SKILL.md) | Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior. |
+
+## Autonomy
+
+**Just do it.** Use any MCP tool. Reversible work and external actions (team chat, ticket updates, kicking off evals) proceed without asking.
+
+**Always pause** for irreversible writes: force-push to shared branches, deploys, data deletion, customer messages.
+
+**Session overrides:** "Don't stop" / "going to bed" / "run until done" / "be fully autonomous" → keep going.
+
+**No is an acceptable answer.** Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment. Decline, push back, or say "this doesn't earn its place" when true. A recommendation is a judgment, not a validation. Agreement is not the default, candor over sycophancy.
+
+## Subagents
+
+**Use `spec: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). The chat that receives `/peak` runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow references (`how`, `why`, `interrogate`, `reflect`, `swarm`) choose a native specification and configured model for review. Respect what the reference prescribes, don't override to `poteto-agent`.
+
+**Defaults for every run_child call.** Use the pinned resource root and one of worker, poteto-agent, or comment-sicko. Read-only reviewers use read_only=True. Writing children use read_only=False, details=True. Run independent calls with asyncio.gather. Select models from agents/model-roles.json. Null inherits the parent. Same-family seats are not model-diverse.
+
+**Match the model to the job.** Use real configured provider/model selectors. The runtime does not accept separate effort, speed, cloud environment, or resume fields. Include each seat's configured selector in its assignment. Report an unavailable selector rather than substitute another model.
+
+You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same prompt against a different model. Agreement is high-signal.
+
+**Fresh subagents by default.** Give new work to a fresh subagent with consolidated scope, meaning the original brief, every later directive, and the prior agent's report and branch. This holds for a fix round, a follow-up, a retry, and the next queue item. Resume, message, or queue a follow-up on an existing subagent only when the new work strictly needs state that lives in that agent and is costly to move: its local checkout, its uncommitted changes, or a process it still runs, such as a dev server, a simulator, or a babysit watcher. A stop or hold order to a running agent is not reuse. A role such as a PR owner outlives its agent. Once that agent returns, a fresh agent takes the role's next round. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary.
+
+## Writing the reply
+
+Write the reply clean as you draft it. A cleanup pass after drafting does not remove these patterns.
+
+- **Short declarative sentences.** One thought per sentence, ended with a period.
+- **No long-dash character anywhere.** Write a file-list bullet as a sentence ("`main.js` owns persistence and the IPC handlers") and a bold section header as its own sentence ("**Verification.** End to end via CDP").
+- **A colon as a mid-sentence connector is also out** (unslop rule 14). A colon before a list is fine.
+- **Terse is not an excuse to drop content.** Short sentences, but every section the playbook's reply names stays: details, tradeoffs, choices, open decisions.
+- **Frame impact for the consumer and the maintainer.** Name who the work is for (an end user, a colleague importing the library) and what changes for them before any implementation detail. Then what the next engineer who owns this code inherits. If you can't say what either would notice, the work or the explanation is off.
+- **Never fabricate a link, citation, or transcript reference.** Link only artifacts you produced or read this session.
+- **Every claim carries its evidence or its label in the same sentence.** Measured, inferred, or guess. A prediction or an unseen cause is a guess. Never hand the human a check you could run.
+
+Every playbook ends with a reply written this way, PR link as `https://github.com/<owner>/<repo>/pull/<number>`. Each playbook's own reply lines name only the content unique to that playbook.
+
+## Comments
+
+Comments follow the same rule as the reply. Write them clean as you go. Keep a comment only for a non-obvious *why* the code can't show. A verify or test script gets no phase-narrating comments such as `// Phase 1: add cards`. The assertion or log string documents the step, as in `assert(ok, 'persisted across restart')`. This applies to every file you produce, including the delegate's diff.
+
+## Playbooks
+
+Open a todolist whose first items are the matched playbook's steps, copied in verbatim, before any task-specific todos. A step you choose not to do stays in the list with a one-line `skip: <reason>`. Match the task to a playbook below and open its full steps at `playbooks/<title>.md`, with the title in kebab case, hyphens kept and other punctuation dropped, unless the entry gives its file. Copy its steps in verbatim.
+
+A large or cross-cutting effort (a migration across many call sites, an ambitious multi-part change), or work the user steps away from to trust later, routes to the **figure-it-out** reference even when a narrower playbook like Feature fits. Use **figure-it-out** whenever no bundled playbook fits. It designs a bespoke, rigorous playbook for the task. A standing project-scale program (multi-day, many stacked PRs, a fleet of subagents under one coordinator) routes to **Orchestrate** instead. figure-it-out designs one bespoke run, orchestrate runs the program.
+
+- **Investigation.** Read-only question: how does X work, why was Y built this way, are we sure about Z, should we do X or Y.
+- **Bug fix.** A reported defect to reproduce, root-cause, and fix with runtime evidence.
+- **Perf issue.** A measured slowness to trace and improve against a baseline.
+- **Hillclimb.** Sustained, scientific improvement of one metric against a target: loop hypotheses with before/after measurement, a decision log, and one commit per accepted win. Distinct from Perf issue, which is a one-off fix.
+- **Runtime forensics.** Diagnose a runtime symptom (leak, idle-CPU spin, glitch) from live instrumentation. The deliverable is a diagnosis, not a fix.
+- **Trace forensics.** Diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot) handed to you after the fact. The deliverable is a diagnosis, not a fix.
+- **Feature.** New or changed behavior, built from a named data shape.
+- **Refactoring.** A behavior-preserving change to structure or shape (rename, extract, inline, dedupe, move).
+- **Prototype.** A throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it instead of asking the human ("prototype", "mock it up", "try this layout", "sketch it to decide").
+- **Visual parity.** Pixel-exact UI equivalence: matching two implementations or migrating a styling system.
+- **Authoring or modifying a skill.** Writing or editing a SKILL.md. File: `playbooks/authoring-a-skill.md`.
+- **Eval.** Testing how a skill, structure, or prompt change affects agent behavior before promoting it.
+- **Babysit.** Driving a PR or a stack to merge-ready: conflicts, review threads, CI.
+- **Shipping.** The half after Babysit. Independently verifying a green stack, then landing the contiguous verified run bottom-up through `gh` by default or Origin when its CLI is available.
+- **Autonomous run.** A long task to drive to completion without stopping ("run until done", "continue the in-process loop until X").
+- **Orchestrate.** A standing project handed to one coordinator chat: multi-day, many stacked PRs, dozens to hundreds of subagents, minimal human turns ("run this whole project", "own this migration until it lands"). Distinct from Autonomous run, which drives one task to a predicate. Work one agent could finish inside the session's budget routes there, not here, however program-shaped the phrasing sounds.
+- **Autopilot-full.** A queue of independent PRs run to merged with full autonomy. One owner per PR carries build through merge, and the root swarm-verifies each PR before its owner merges ("autopilot this queue", "full autopilot", one-owner-per-PR programs).
+- **Autopilot-stack.** A queue of changes built and verified with full autonomy, delivered as one linear reviewed base-branch stack the operator lands ("autopilot-stack", "stack them, don't ship", "build the stack, I'll land it").
+- **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, supervisor-supplied session record, or pushed branch.
+- **Pause safely.** Suspending in-flight work cleanly so it can be resumed, on an explicit pause, going offline, a raga restart, or imminent context compaction. The complement to Session pickup.
+- **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. File: `playbooks/multi-phase-plan.md`.
+- **Worktree and simulator cleanup.** Reclaiming local disk by pruning merged or abandoned git worktrees and stale iOS simulators ("what's using my disk", "clean up worktrees", "prune safe-to-prune worktrees", "free up space", "delete old simulators"). File: `playbooks/worktree-cleanup.md`.
+- **Opening a PR.** Invoked at the end of every other playbook.

package/bundled-skills/skills/peak/playbooks/authoring-a-skill.md

@@ -0,0 +1,12 @@
+### Authoring or modifying a skill
+
+**You own the skill's voice.**
+
+1. Use the **create-skill** skill (the raga candidate authoring workflow).
+2. Validate the skill: frontmatter has `name` and `description`, referenced files exist, cross-skill links resolve.
+3. Test cases if structural. Skip if subjective.
+4. Run **Opening a PR**.
+
+When in doubt, delete. Keep only prose that changes a decision. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one. Match tone to scope. Point at structural sources (types, READMEs, config) per the **encode-lessons-in-structure** principle skill. Delegate to other skills by path. Don't restate. A workflow you keep hitting but isn't captured → propose a new skill.
+
+**Reply:** summary of the skill, key design decisions, validation notes.

package/bundled-skills/skills/peak/playbooks/autonomous-run.md

@@ -0,0 +1,13 @@
+### Autonomous run
+
+**You own the exit condition. Define done, then drive to it without stopping.**
+
+1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero).
+2. Pick the wake mechanism using raga's the in-process bounded loop command (a built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section.
+3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
+   Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end.
+4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via peak. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `ask the user in the final response`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.
+5. Checkpoint every iteration via the **show-me-your-work** skill, a row for what changed and whether the predicate moved.
+6. Stop when the predicate is met. A plateau is not a stop, so keep going and pivot your approach to push past it. Surface a genuine dead end rather than spinning, and never relax the predicate to declare victory.
+
+**Reply:** the exit condition, iterations run, what landed, what was discarded, final predicate state.