pstack-opencode 0.0.0-stage → 0.15.36-opencode

package/skills/maintain-formal-verification-skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: maintain-formal-verification-skill
+description: "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."
+disable-model-invocation: true
+---
+
+# Maintain a formal verification skill
+
+A formal check proves a property of what it describes. When the code changes and the verification does not, the check can keep passing while it describes code that no longer exists. That pass is the dangerous case, because it looks like a proof. This skill is the upkeep loop for a verify skill that the `create-formal-verification-skill` skill generated, or for any project-local skill that runs a model checker, prover, or code-level verifier against named code. The project-local skill handles a change that an agent makes while it uses that skill. This skill handles the changes that skipped it: merges, edits made without the skill, and drift that builds up across many commits.
+
+## Outcomes
+
+Give each check one outcome, and say which:
+
+- **in sync**: no change since the last sync alters what the check describes, and the check passes.
+- **updated**: the code changed, the verification now describes the new code, and the check passes.
+- **bug**: the verification describes the current code, and the code breaks the property. This is a finding about the code. It is not drift.
+- **blocked**: the check could not be brought back in line or could not run. Say exactly why.
+
+A check can be both updated and bug: the update makes the verification describe the code again, and then the property fails on it.
+
+## Edit scope
+
+Edit only the verification: models, harnesses, property files, and the verify skill itself. Never edit product code during a run, unless the user asks you to. When a property fails on the current code, do not weaken the property or the model to make it pass. Report the failure.
+
+## Pass
+
+1. **Find the checks.** A verify skill has no fixed name, so find it by what it does: a project skill that runs a model checker, a prover, or another verifier against named code. Read each one you find, or the one the user named. For each check, collect the property, the code it covers, the bounds and assumptions, the command that runs it, and the commit where it was last confirmed to describe the code. If no verify skill exists, stop and point at `/create-formal-verification-skill`. If the skill does not record a sync commit, use the last commit that changed the verification files, and say that you did.
+
+2. **Run it as it is.** Run each check once before you change anything, and record the result. A pass here does not tell you that the code is correct. It tells you that the old description still holds. A failure here can be drift or a bug. Do not decide which until step 5.
+
+3. **Read every change to covered code.** Diff the covered files from the sync commit to the current commit, and read each commit message. Also look for code that moved: a covered function that is renamed, split, or moved to another file is still covered code. Also look for new code that touches the state that a check guards, such as a new function that writes the same fields. For each change, decide which of these it is:
+   - **No effect.** The change does not alter anything the verification describes, such as formatting, comments, or code paths that the verification does not cover. Check this against the model or harness, not against the commit message.
+   - **The verification no longer describes the code.** A step that was one indivisible action is now two, a branch was added or removed, a check moved, a new path reaches the guarded state, or a value now has a different range. The model or harness must change.
+   - **The promise changed on purpose.** The change alters what the code promises, and evidence in the change says that this is intended: the doc comment, the tests, the changelog, or the commit message. The property must change, and you must cite that evidence.
+   - **The promise may be broken.** The code changed, and no evidence says that the promise changed. Treat a failure that follows as a bug candidate.
+
+4. **Update from the code, not from the result.** Change the model or harness so that each changed part again points to code that a reviewer can open, and keep one indivisible step in the code as one step in the verification. Write the update from the code before you rerun, and do not shape it by what makes the check pass. Change a property only for a promise that changed on purpose. Write down the old wording, the new wording, and the evidence. Keep the bounds unless the change makes them wrong. If you must reduce a bound, say so in the report.
+
+5. **Rerun and judge each result.**
+   - **Pass:** the check can now pass on a description that has lost the ability to fail. Break the new code the way the property guards against, such as removing a new check or reordering a new step, and confirm that the check catches it. Then drop the break.
+   - **Fail:** replay the counterexample against the real code, step by step. If a step cannot happen in the code, the verification is wrong. Fix the verification, and say what was wrong. If every step can happen, it is a bug. Name the commit that introduced it, tell the counterexample as a sequence of steps in the code's own words, and state the harm in one sentence. If a cheap test or reproduction against the real code shows the bug, add it to the report as evidence. Do not commit it to the product code.
+
+6. **Update the verify skill.** Update the code that each check covers, the commands, the bounds, the assumptions, and the sync commit. Set the sync commit to the commit that you checked. Do not move the sync commit for a blocked check, and say so in the report. Then follow the verify skill once as the next agent would, so that you know its steps still run.
+
+## Report
+
+Tell the user, for each check:
+
+- the outcome, and the commits that you read;
+- what changed in the verification and why, with a short reason for each change: the code changed shape, or the promise changed on purpose (with the evidence);
+- the rerun result, and the break that you used to show the updated check can still fail;
+- each bug, in plain words: the counterexample as steps in the code's words, the harm, and the commit that introduced it;
+- what the verification still does not cover, including new code that it should cover and does not.
+
+Say outright which failures were drift in the verification and which were bugs in the code. For a check that passed before you updated it and fails after, say that the old pass was on a stale description.
+
+Put the verification updates in a change of their own, separate from any product fix.

package/skills/maintain-verification-skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: maintain-verification-skill
+description: "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\"."
+disable-model-invocation: true
+---
+
+# Maintain a verification skill
+
+A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by the `create-verification-skill` skill (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
+
+## Outcomes
+
+Pick one, and say which:
+
+- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
+- **changed** — one PR ships proven doc, harness, or map corrections.
+- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
+
+## Edit scope
+
+Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
+
+## Pass
+
+0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.opencode/skills/verify-*/`). Several candidates → ask which one with the `question` tool; none → stop and point at `/create-verification-skill` instead of inventing a target.
+
+1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
+
+2. **Source wave.** One `subagent` call per feature file with `agent: "explore"` and `background: true`, launched concurrently. `explore` cannot edit files or load skills, so each brief carries the feature file's absolute path and says "do not edit files". Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Check `git status` after the wave to confirm it. Return shape: feature summary / source entry points / likely drift or none / one recipe.
+
+3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
+
+4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
+
+5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
+
+6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
+
+Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.

package/skills/no-comments/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: no-comments
+description: "Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints."
+disable-model-invocation: true
+---
+
+# No comments
+
+Spawn Comment Sicko. Act on accepted findings.
+
+Defer to Comment Sicko's fresh perspective.
+
+## Scope
+
+Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including the working tree.
+
+## Steps
+
+1. Call `subagent` with `agent: "comment-sicko"`. Pass the scope. Pick each subagent's reasoning level for the job, per the Subagents section of the `poteto-mode` skill. Do not restate its rules.
+2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, load the `how` or `why` skill with the `skill` tool and run it on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail this `no-comments` run.
+3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, load the `architect` skill and run it once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements.
+4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The `principle-fix-root-causes` and `principle-redesign-from-first-principles` skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards.
+5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work.
+6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work.

package/skills/poteto-help/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: poteto-help
+description: Guides users through pstack setup, /poteto-mode, and picking the skill, playbook, or principle for a task. Type /poteto-help with a question.
+disable-model-invocation: true
+---
+
+# Poteto help
+
+Answer the user's question about pstack, hand them a prompt they can send, and link the file the answer came from. For a help question, don't start the work. The user asked how, and a pstack run spends real tokens, so let them send the prompt.
+
+A message that asks for work, such as "use pstack to fix this bug", is not a help question. Read [`poteto-mode`](../poteto-mode/SKILL.md), do the work under it, and mention once that the `poteto-mode` agent keeps it on.
+
+This file maps questions to the skills and guide pages that hold the answers. Those files own the details. Read the file you route to before you quote it, and trust it when it disagrees with this map. The plugin turns the links here into absolute paths in its folder, which the installer links from the user's checkout of this repo, so give the user that absolute path.
+
+## Find out what they need
+
+Infer the need from the message and the conversation. A named situation, such as "which skill reviews a PR?", goes straight to its section. If the need is still unclear, ask one multiple-choice question with these options, then answer only the section they pick:
+
+- Get set up
+- Start a task with `/poteto-mode`
+- Pick a skill for a situation
+- Fix a run that went wrong
+- Make pstack my own
+
+Check the state that changes the answer, and mention it only when it does:
+
+- No `~/.config/opencode/pstack-models.md` means `/setup-pstack` hasn't run for this user, so every role uses its default model.
+- No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works.
+- No formal verification skill in the project means no property is checked past what tests reach. Mention `/create-formal-verification-skill` when the question is about a race, an invariant, or another case tests rarely hit. When one exists and the code it covers changed after the commit it records as last in sync, mention `/maintain-formal-verification-skill` if the question touches that code.
+
+When the models file is missing and it matters, ask whether the user wants to pick a model for each role and a reasoning budget now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices:
+
+- Now: give them `/setup-pstack` to type, and answer their question too.
+- Later: answer their question, and add one line saying every role keeps its default model until they run `/setup-pstack`.
+
+## Get set up
+
+1. From a checkout of this repo, run `npm run install-pstack`. It links `src/` into `~/.config/opencode`, or into one project's `.opencode/` with `npm run install-pstack -- --project <dir>`, and copies nothing. Add the `experimental` settings it recommends: `"todo": true` gives agents `todowrite`, and `"subagent_depth": 2` lets a delegate run skills that spawn their own subagents.
+2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes `~/.config/opencode/pstack-models.md`. The plugin reads that file at the next request, so no restart is needed. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one.
+3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail.
+
+Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md).
+
+If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor.
+
+## Start a task with `/poteto-mode`
+
+`/poteto-mode` matches the task to a playbook, copies the playbook's steps into the todo list, and runs the other skills as the steps need them. A step it skips stays in the list as `skip: <reason>`. A good prompt states the goal and how to tell it's done. It doesn't list skills, because a hand-written sequence tends to drop or reorder steps the playbook would keep. Read [`references/prompting.md`](references/prompting.md) before you help word one.
+
+Either way of starting it keeps the mode on:
+
+- `/poteto-mode` attaches the skill to its message and keeps a `pstack-mode` instruction entry on that session for the rest of the session, whatever agent it runs under.
+- The `poteto-mode` agent attaches the skill to the first message and keeps the same entry until the user switches agents. Press Tab to select it, or start with `opencode --agent poteto-mode`.
+
+The entry keeps the mode in context every turn and through compaction.
+
+Mid-chat, "new task" makes the mode match a fresh playbook. `/poteto-mode` already uses `poteto-agent` for the subagents its playbook steps spawn. To get the same style from a subagent of your own, spawn it with `agent: "poteto-agent"`.
+
+## Pick a skill
+
+The default answer is `/poteto-mode`, which runs most of the others when its steps need them. Name a skill directly when the user wants more or less of something than the playbook gives. Read the skill before you recommend it, and give one example prompt.
+
+| The user wants to | Skill |
+|---|---|
+| Do any non-trivial task with rigor | [`/poteto-mode`](../poteto-mode/SKILL.md) |
+| Check that the agent understood their goal and the problem before it starts | [`/in-your-own-words`](../in-your-own-words/SKILL.md) |
+| Get a prompt rewritten deeper, not bigger, before sending it: what a top professional would add, their raw material and methods, and an outside check. It returns the prompt and doesn't do the task | [`/sharpen`](../sharpen/SKILL.md) |
+| Know how code works now, or where new code should live | [`/how`](../how/SKILL.md) |
+| Know why code is shaped this way, or where a number came from | [`/why`](../why/SKILL.md) |
+| Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) |
+| Catch up on their own recent work on a topic | [`/recall`](../recall/SKILL.md) |
+| Catch up on what changed in this chat since their last message, in plain words and small visuals, with every item waiting on them listed and decidable from the reply alone | [`/ketchup`](../ketchup/SKILL.md) |
+| Catch up like `/ketchup`, in a short subtitled video of slides, with the waiting calls as text under it | [`/ketchup-video`](../ketchup-video/SKILL.md) |
+| Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) |
+| Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) |
+| Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) |
+| Run parallel checks over slices, or race workers, each in its own worktree | [`/swarm`](../swarm/SKILL.md) |
+| Have different models review a diff and try to break it | [`/interrogate`](../interrogate/SKILL.md) |
+| Fix a bug test-first when a cheap local test exists | [`/tdd`](../tdd/SKILL.md) |
+| Apply TypeScript rules to `.ts` or `.tsx` work | [`/typescript-best-practices`](../typescript-best-practices/SKILL.md) |
+| Clean AI-generated slop out of code before a commit | [`/deslop`](../deslop/SKILL.md) |
+| Drive a CLI or TUI, or a browser, Electron, or web UI, to verify a change | [`control-cli`](../control-cli/SKILL.md), [`control-ui`](../control-ui/SKILL.md) |
+| Strip comments before review, using a reviewer that didn't write them | [`/no-comments`](../no-comments/SKILL.md) |
+| Clean AI tells out of prose | [`/unslop`](../unslop/SKILL.md) |
+| Write docs, an RFC, a README, a PR description, or a commit message to a standard | [`/technical-writing`](../technical-writing/SKILL.md) |
+| Hear the last reply again in plain words | [`/bro`](../bro/SKILL.md) |
+| Give agents a scripted way to drive the app and prove behavior | [`/create-verification-skill`](../create-verification-skill/SKILL.md) |
+| Bring a verification skill and its feature map back in line with the app | [`/maintain-verification-skill`](../maintain-verification-skill/SKILL.md) |
+| Formally verify a race, invariant, or other property that tests rarely reach | [`/create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md) |
+| Bring a formal verification back in line after the code it covers changed, and learn whether a failure is drift or a bug | [`/maintain-formal-verification-skill`](../maintain-formal-verification-skill/SKILL.md) |
+| Show a PM or designer what the user sees as a chart checked by a TLA+ model, with the shortest path to each state that breaks a rule | [`/statechart`](../statechart/SKILL.md) |
+| Vet a performance number before reporting or acting on it | [`/benchmark-checklist`](../benchmark-checklist/SKILL.md) |
+| Run a large or cross-cutting change, or one to review after stepping away | [`/figure-it-out`](../figure-it-out/SKILL.md) |
+| Keep a decision log during a run, and review it afterward | [`/show-me-your-work`](../show-me-your-work/SKILL.md) |
+| Pick a model for each role and a reasoning budget | [`/setup-pstack`](../setup-pstack/SKILL.md) |
+| Turn their own working habits into a personal mode skill | [`/automate-me`](../automate-me/SKILL.md) |
+| Turn what a finished task taught into skill edits | [`/reflect`](../reflect/SKILL.md) |
+| Stop agents from repeating the same mistakes in this repo | [`/correct`](../correct/SKILL.md) |
+| Find their way around pstack | `/poteto-help` |
+
+If a skill directory next to this one is missing from the table, read its frontmatter and route by its description. The `principle-*` directories are covered under principles below.
+
+Close calls:
+
+- `/how` explains what the code does. `/why` explains the reasons. `/teach` runs one or both and explains the result plainly.
+- `/arena` gives every worker the same brief and merges the best parts. `/swarm` splits work into slices or a race and returns one report.
+- `/architect` implements right after it settles the design. Add "with checkpoint" to review the design before it writes code.
+- `/interrogate` reviews the diff. `/blast-radius` looks for breakage outside the diff and proves the one fact that makes the change safe.
+- `/recall` rebuilds context across recent chats. `/ketchup` covers only this chat since the user's last message. Resuming one specific chat or branch is the Session pickup playbook.
+- `/figure-it-out` designs one rigorous run. The Orchestrate playbook runs a program that spans days and many PRs. The Autonomous run playbook drives one task to a finish condition.
+
+Not in pstack:
+
+- `/goal` is built into the app. A skill-authoring skill such as `skill-creator` comes from the user's own catalog when they have one.
+- pstack has no `/orchestrate` skill. Orchestrate is a `/poteto-mode` playbook. If the slash menu shows `/orchestrate`, another plugin provides it.
+
+## Playbooks and principles
+
+Playbooks are step lists inside `/poteto-mode`. They load as hidden skills, but they have no slash command. Inside `/poteto-mode`, describing the task picks one, and these phrases name one directly:
+
+- "babysit this pr" or "check on pr 123" runs Babysit. It drives the PR to merge-ready and stops there. It doesn't merge unless the user asks to merge, land, or ship.
+- "land the stack" runs Shipping.
+- "take over this branch" runs Session pickup.
+- "pause safely" runs Pause safely.
+- "full autopilot on this queue" runs Autopilot-full. "autopilot, don't merge" runs Autopilot-stack.
+- "run the eval playbook" runs Eval.
+
+Without `/poteto-mode`, a phrase such as "babysit this pr" can start another installed skill for the same job instead. The Playbooks section of [`poteto-mode`](../poteto-mode/SKILL.md) lists every playbook and when it applies.
+
+pstack has no planning skill. For work that spans phases or stacked PRs, asking `/poteto-mode` for a plan runs the [Multi-phase plan playbook](../poteto-mode/playbooks/multi-phase-plan.md), which writes the plan and doesn't implement it. For a design question, the Prototype playbook or `/architect` settles it in code first.
+
+Principles are one-rule skills that `/poteto-mode` reads and cites in its replies. The user rarely invokes one. They steer with the names instead, as in "apply prove it works. show me the real output." Principles have no slash command, but asking for one by name, such as "load principle-prove-it-works", loads it on demand. The Principles section of [`poteto-mode`](../poteto-mode/SKILL.md) lists them.
+
+## Fix a run that went wrong
+
+| Symptom | Fix |
+|---|---|
+| The mode stopped applying after a few turns | It was started with `/poteto-mode`, which attaches to one message. Switch to the `poteto-mode` agent, or start each task with `/poteto-mode`. |
+| A question got treated as the next step of the last task | Say "new task", or say the turn doesn't need the mode. |
+| A new model choice had no effect | The plugin rereads `~/.config/opencode/pstack-models.md` at each request. Check that the file has the new line and that the value is a model `opencode models` lists. |
+| Runs cost more than expected | See the cost paragraph under Get set up. |
+| A skill didn't load on its own | Only `/setup-pstack` loads from the user's words. The others load when the user types them or when `/poteto-mode` runs them, and it doesn't run every skill. |
+| Parallel agents overwrote each other | Give each agent its own git worktree. |
+| An overnight run moved but finished nothing | `/goal` needs a check that can pass or fail, not a duration. |
+| The reply claims success from a green build | Ask for the real command, flow, stored value, or profile. That's the prove-it-works principle. |
+
+For a run that drifts, [`references/prompting.md`](references/prompting.md) has one-line steers, and [`references/recipes.md`](references/recipes.md) has prompts worth copying.
+
+## Make pstack my own
+
+- [`/automate-me`](../automate-me/SKILL.md) drafts a personal mode skill from the user's own history, to use alongside `/poteto-mode`.
+- [`/reflect`](../reflect/SKILL.md) after a session turns its lessons into skill edits the user approves.
+- `/poteto-mode write a skill for <workflow>` runs the authoring playbook. The eval playbook tests a skill change blind.
+- Fix a misbehaving skill in its own PR, not inside the feature work where it went wrong.
+
+## Reply
+
+Lead with the answer. Give at most one example prompt in a code block, adapted from [`references/recipes.md`](references/recipes.md) when one fits, then the link to that file. Keep it short unless the user asked for the whole map.

package/skills/poteto-help/references/prompting.md

@@ -0,0 +1,51 @@
+# Word the prompt
+
+A prompt states the intent and the check for done. The playbook supplies the steps, so a few plain sentences beat a spec.
+
+## Put in
+
+- The goal. Say what is wrong or what the user wants.
+- The done check. It can pass or fail. "Make it better" and a duration are not checks.
+- The proof to show. Ask for the real command output, a video of the flow, the stored value, or a before and after number.
+- What the user already knows. A symptom, a repro step, a log, or a link saves the agent a search.
+- The real constraints. "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does.
+
+## Leave out
+
+- The how. Say what to achieve, and leave the agent room to find a better way.
+- A list of skills or steps. A hand-written order drops or reorders steps the playbook keeps. Name a skill only to override one choice.
+- The user's theory of the cause, until the agent restates the problem. A stated guess narrows the search.
+
+## Load the context first
+
+- For a noisy report, ask the agent to restate the underlying issue in its own words and in plain English before it does anything else. A misreading shows up before any code exists.
+- In a fresh chat, `/recall` earlier work on the topic. Old chats hold context that the new agent lacks.
+- Before a change to unfamiliar code, ask `/how` for the mechanics and `/why` for the reasons. An agent with no traced model fixes the symptom at the first plausible spot.
+- Ask `/teach` to make the case for a choice, as in "convince me it fixes the cause and not the symptom". A case is easier to check than a summary.
+
+## Design before the plan
+
+- Never take the first design. Ask for prototypes of a few options, with screenshots or videos for UI, and pick from the evidence.
+- Let prototypes answer the open questions. Don't review an abstract plan adversarially, because reviewers invent risks that never happen.
+- For a shared package or API, ask for the README or a tutorial first, then work back to the code. The doc becomes the target the agent checks itself against.
+- Ask for the plan only after the design is settled. Each step of the plan ends in a check.
+
+## Follow up short
+
+- "do it", "continue", and "keep going until done" are whole prompts once the chat holds the task.
+- Start with "new task" when the subject changes. Otherwise the mode treats the message as the next step.
+
+## Before stepping away
+
+- Say "im going to bed" or "im stepping away" so the agent stops asking.
+- Write done as checks every iteration can run, and give `/goal` that predicate.
+- Ask for a fresh worktree off a named base.
+- Pre-answer what the agent would stop for, such as "don't ask me before committing".
+- Ask for a decision log to audit later.
+- Give an exit: "if you're truly stuck after a few hours, stop and write up why".
+
+## Steer in one line
+
+- Restate the goal: "i said the goal is to repro. i did not ask for a fix yet."
+- Name the principle: "apply prove it works. show me the real output, not the build log."
+- A principle name works because the agent already read the rule. Its reply names the decision the rule changed.

package/skills/poteto-help/references/recipes.md

@@ -0,0 +1,51 @@
+# Prompts worth copying
+
+Swap in the real paths, skills, and done checks. Informal wording works.
+
+## Understand
+
+- `/poteto-mode read <thread>. restate the underlying issue in your own words, in plain english.`
+- `/in-your-own-words <long or messy ask>`
+- `/sharpen <the prompt you're about to send>`
+- `/poteto-mode investigate why <symptom>. give me what we know, what data you used, and your best hypotheses. don't change any code yet.`
+- `use /how to understand <subsystem>. then use /why to find out why it broke recently.`
+- `/recall my work on <topic> from last week, then read <issue>.`
+- `/teach me why you implemented it this way and not <other way>. what did you trade off?`
+- `/poteto-mode take over this branch. read the decision log, find what's done, and continue. don't redo finished work.`
+
+## Build
+
+- Bug: `/poteto-mode <symptom>. repro first, then fix and verify.`
+- Bug in an app: `/poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof.`
+- Bug with a cheap test: `/poteto-mode repro <bug> first. if there's a cheap test path, /tdd it. then fix and rerun.`
+- Feature: `/poteto-mode add <behavior>. <current output> stays byte-identical. verify both.`
+- Refactor: `/poteto-mode move <code> into one module, zero behavior change. record the current output first and prove it's unchanged after.`
+- Perf: `/poteto-mode <operation> takes <time> on <fixture>. trace it, fix the measured cause, show me before and after.`
+
+## Design and plan
+
+- `/poteto-mode prototype a few options for <feature>. take screenshots or videos for me to compare.`
+- `/poteto-mode we need <feature>. /architect it first, and answer open questions with prototypes. let me review before proceeding.`
+- `/poteto-mode write a tutorial for how i would use <new package> first. then /teach me why it beats the current one.`
+- `ask /arena for a second opinion on this thread and our approach.`
+- `/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.`
+- `/poteto-mode plan the migration of <library> to <target>. small verifiable PRs. the result must match the original exactly, bugs included.`
+
+## Review and ship
+
+- `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's a real bug or regression.` Read the Dropped list too.
+- `/create-formal-verification-skill prove <property> holds in <module>, even when <steps> interleave or retry.` After merges or refactors in that code: `/maintain-formal-verification-skill`.
+- `/swarm check every package under <dir> against its check script. one worker per package. one report.`
+- `/poteto-mode open the pr. small ordered commits, evidence in the description.`
+- `/poteto-mode babysit this pr. get it green.` For status only: `/poteto-mode check on pr <number>. anything outstanding?`
+- `/poteto-mode land the stack.`
+
+## Away and back
+
+- `/poteto-mode im going to bed. <goal> in a fresh worktree off <base>. done means <checks>. keep a decision log. don't ask me before committing. /goal <checks>. if you're truly stuck after a few hours, stop and write up why.`
+- `/show-me-your-work catch me up on what you did last night.` Read its Attention section first.
+- `/ketchup` catches you up on this chat since your last message and lists every call that waits on you.
+- `/poteto-mode full autopilot on this queue. each item is independent.`
+- `/poteto-mode autopilot these changes, but don't merge. i'll land them.`
+- `/reflect capture what we learned so the next run doesn't repeat it.` Approve only edits that change a future decision.
+- `/bro` restates the last reply in plain words.

package/skills/poteto-mode/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: poteto-mode
+description: poteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work. Use for poteto, /poteto-mode, the poteto-mode agent, or requests to work in this style.
+disable-model-invocation: true
+---
+
+# Poteto mode
+
+Every skill this file names ships with pstack. Load it with the `skill` tool by its ID when its trigger fires. Most pstack skills are hidden from the skill catalog but load by ID, so a missing catalog entry does not mean the skill is absent. Put this file's absolute path in every `poteto-agent` prompt.
+
+## Non-negotiables
+
+The Principles section below grounds every trigger. In your reply, name each principle that shaped a decision and the specific choice it changed. Cite only principles whose leaf skill you loaded this session.
+
+Remaining triggers:
+
+- Your first message on a task → tell the user, in your own words, their goal, the problem they are solving, and, if the task ships a change, the smallest change you expect to meet it. Don't wait for confirmation. If the evidence rules out the change the user asked for, show it and stop. Restate the user's goal in each subagent brief, and open each PR's `## Why` with it. Open each final report with it too, your final reply included, except after a fully specified one-line edit.
+- Nontrivial change, architecture decision, or "are we sure?" → the `how` skill.
+- About to call `question` 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 (load `prototype` with the `skill` tool) 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 `opencode run` no client answers `question`, so ask in plain text. 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` skill, parallel design exploration before implementing.
+- Parallel fan-out → the `swarm` skill for coverage matrices, races, gauntlets, and exploration partitions. Use `arena` for design or code bakeoffs with base selection and grafting.
+- Contested design → the `interrogate` skill (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` skill. Write the reply per **Writing the reply**. Agent-facing prose also follows the `skill-creator` or `writing-for-agents` skill when the catalog lists one.
+- Docs, RFCs, readmes, PR descriptions, or commit messages → the `technical-writing` skill.
+- Before every commit → the `deslop` skill.
+- Before review → the `no-comments` skill.
+- Shipping UI / IDE / CLI → the matching control skill: `control-cli` for CLIs and TUIs, `control-ui` for browser, Electron, and 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` skill before you report or act on the number.
+- Any PR-status request ("babysit this", "get it green", "address the bugbot comments", and most often "check on PR X" or "anything outstanding on X") → the **Babysit** playbook (load `babysit` with the `skill` tool). 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 (load `shipping` with the `skill` tool). Green is not safe. Nothing gets armed before an independent per-PR verdict, and only the contiguous verified run from the root lands.
+- A review bot (Bugbot, a security reviewer) commented on a PR → 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/bugbot-triage.md`.
+- Broken skill 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", "/goal X") → a decision trail via the `show-me-your-work` skill. Commit it when stakes need an auditable record. Keep it local otherwise.
+
+## Principles
+
+Load the leaf skill for any principle you apply. Each entry names when it applies. Each leaf is the `principle-<title>` skill, with the title in kebab case, hyphens kept and other punctuation dropped, unless the entry gives its ID.
+
+**Core**
+
+- **Laziness Protocol.** Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Bias to deletion and the smallest change that solves the problem.
+- **Foundational Thinking.** Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share.
+- **Redesign from First Principles.** Integrating a new requirement into an existing design. Redesign as if it had been foundational from day one.
+- **Attack the Premise.** 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.
+- **Subtract Before You Add.** Sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base.
+- **Minimize Reader Load.** Reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
+- **Outcome-Oriented Execution.** Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture, don't preserve throwaway compatibility states.
+- **Experience First.** Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience.
+- **Exhaust the Design Space.** A novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing.
+- **Build the Lever.** Any non-trivial work. Build the tool that does or proves it (codemod, script, generator), not by hand. The tool is the artifact a reviewer reruns.
+
+**Architecture**
+
+- **Model the Domain.** Writing stateful logic, or code that branches a lot or repeats a shape assumption across files. Encode the domain in a structure (state machine, typed model, table or registry, reducer, boundary, the right collection) instead of scattered conditionals.
+- **Boundary Discipline.** Wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure.
+- **Type System Discipline.** Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
+- **Make Operations Idempotent.** Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state.
+- **Migrate Callers Then Delete Legacy APIs.** Introducing a new internal API while old callers exist. Migrate and delete in one wave.
+- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first.
+
+**Verification**
+
+- **Prove It Works.** After a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles".
+- **Fix Root Causes.** 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.
+- **Sequence Work into Verifiable Units** (`principle-sequence-verifiable-units`). Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs. Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself.
+- **Test Behavior, Not Implementation.** Writing, changing, or keeping a test. Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change.
+- **Explain the Number.** Apply before you measure, and 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.
+
+**Delegation**
+
+- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread.
+- **Never Block on the Human.** Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.
+
+**Meta**
+
+- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text.
+
+## Autonomy
+
+**Just do it.** Use any MCP tool through `execute`. 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 `agent: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). The session running poteto mode (the `poteto-mode` agent, or a message sent with `/poteto-mode`) runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own `agent` for diverse-model review. Respect what the skill prescribes, don't override to `poteto-agent`.
+
+**Defaults for every `subagent` call.** `background: true`, including a follow-up to a running child through its `sessionID`, because a foreground call holds your turn while other reports wait. An agent that has the tools the step needs: `explore` has no `edit` and no `execute`, so a step that edits or needs MCP never runs there. File pointers, not inlined context. An explicit `model` per role. Role models come from the `pstack-models` instruction entry, which `/setup-pstack` writes to `~/.config/opencode/pstack-models.md`. A role with no line uses its default: `grok-4.7#xhigh` for code and `claude-opus-5-5#xhigh` for prose and judgment, from a provider that lists them. If no provider lists the family, omit `model` so the child runs on the parent model, and say so. Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to the `hardest tasks` line, whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to the cheapest code model. Each code playbook's model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`). A line with a comma-separated list is a ladder, cheapest first. Each code delegate starts on the first entry and moves one entry later for each of these it meets, stopping at the last entry. The change spans more than one module or alters an interface other code calls. The brief cannot name the data shape and the check that proves the change. A delegate on the same task already failed review or verification. Name the entry you chose and the conditions it met in your reply. Prose and judgment read `judgment and prose`. A role line of `inherit-parent` or `auto` runs that role on the parent model, so omit `model`.
+
+**Match the effort to the job.** A model value is `<provider>/<model>#<variant>`, and the variant is the reasoning effort, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. Start from the role's line or default. Raise the variant one step, up to `max`, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Verification is the exception and stays on the `swarm workers` model. Change only the variant, and keep the model the role names, so a diverse panel stays diverse. If the model lacks that variant, use its nearest listed variant at or below the target. A role on `auto` or `inherit-parent` stays on the parent model. If a `subagent` call rejects the adjusted value, retry once with the role's line or default unchanged and say so. If that is rejected too, continue with the calling skill's fallback. Never pass a rejected value again, and skip any fallback that is already rejected. When the calling skill has no fallback, or its fallback runs out, use the closest listed model of the same family (`opencode models`), or omit `model` so the subagent runs on the parent model, and say which.
+
+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. Continue an existing child through its `sessionID` 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 continuations silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary.
+
+## Writing the reply
+
+Before you write the final reply, load the `unslop` skill with the `skill` tool. 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 session 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. Load the `unslop` skill with the `skill` tool first, then write it with the 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 todo list with `todowrite` whose first items are the matched playbook's steps, copied in verbatim, before any task-specific todos. Without `todowrite`, keep the list in your reply and update it at each phase. A step you choose not to do stays in the list with a one-line `skip: <reason>`. A task that needs no playbook records `no playbook: <reason>` as its first todo. A step that loads a skill is never skipped or done inline, because the skill is the step. Match the task to a playbook below and load it with the `skill` tool by its ID, the title in kebab case with hyphens kept and other punctuation dropped (Bug fix is `bug-fix`), unless the entry gives its ID. Then copy its steps in verbatim. A loaded playbook opens with "This is the `poteto-mode` <title> playbook." If the skill that loads lacks that line, another skill owns the ID, so read `playbooks/<id>.md` in this skill's folder instead.
+
+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` skill 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.
+- **Review.** A request to review, stress-test, or try to break existing code or a design, without fixing it.
+- **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. ID: `authoring-a-skill`.
+- **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", "/goal X").
+- **Orchestrate.** A standing project handed to one coordinator session: 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.** Autopilot-full without the merge. A queue of PRs built and verified with full autonomy, then handed to the operator to land. A PR stacks only on a PR it builds on ("autopilot-stack", "autopilot, don't merge", "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 prior session, an exported transcript, or a pushed branch.
+- **Pause safely.** Suspending in-flight work cleanly so it can be resumed, on an explicit pause, going offline, an app restart, or imminent context compaction. The complement to Session pickup.
+- **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. ID: `multi-phase-plan`.
+- **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"). ID: `worktree-cleanup`.
+- **Opening a PR.** Invoked at the end of every other playbook.

package/skills/poteto-mode/playbooks/authoring-a-skill.md

@@ -0,0 +1,12 @@
+### Authoring or modifying a skill
+
+**You own the skill's voice.**
+
+1. Use the `skill-creator` or `writing-for-agents` skill when the catalog lists one. Otherwise author it by hand as `<id>/SKILL.md` with `name` and `description` frontmatter.
+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 `principle-encode-lessons-in-structure` skill. Delegate to other skills by path. Don't restate. A workflow you keep hitting but isn't captured → propose a new skill.
+
+**Reply:** Load the `unslop` skill with the `skill` tool, then write summary of the skill, key design decisions, validation notes.

package/skills/poteto-mode/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. An event to watch (CI, a merge, a ref advancing) gets a watcher subagent with `background: true` that returns on the event and wakes you, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking. A heartbeat is a `shell` call with `background: true` running `sleep <seconds>`. You're woken when it exits. Run the iteration, then start the next sleep. Pick each subagent's reasoning level 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 `principle-sequence-verifiable-units` skill, verifying each unit before the next instead of batching checks at the end.
+4. Mid-run discoveries that support the goal are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `question`. 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:** Load the `unslop` skill with the `skill` tool, then write the exit condition, iterations run, what landed, what was discarded, final predicate state.