diff --git a/README.md b/README.md index 1ffdccb..d976095 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,8 @@ One orchestrator skill (`poteto-mode`) routes tasks to playbooks. Supporting ski | `pstack:setup-pstack` | Configure the delegate model and reasoning budget. | | `pstack:automate-me`, `pstack:recall`, `pstack:reflect`, `pstack:show-me-your-work`, `pstack:why` | Personalization, history, reflection, evidence, and intent. | | `pstack:benchmark-checklist`, `pstack:blast-radius`, `pstack:bro`, `pstack:create-verification-skill`, `pstack:figure-it-out`, `pstack:maintain-verification-skill`, `pstack:no-comments`, `pstack:tdd`, `pstack:teach`, `pstack:technical-writing`, `pstack:typescript-best-practices` | Focused engineering workflows. | +| `pstack:ketchup`, `pstack:in-your-own-words`, `pstack:sharpen` | Catch up on what changed in a chat, restate the goal before starting, aim a task higher. | +| `pstack:arena`, `pstack:correct`, `pstack:create-formal-verification-skill`, `pstack:poteto-help` | Parallel candidates with a cross-judge, repeated-mistake enforcement, formal verification, and the help map. | | `principle-*` (20 skills) | Engineering principles used by the orchestrator. | diff --git a/plugin.yaml b/plugin.yaml index 3982021..dc93df6 100644 --- a/plugin.yaml +++ b/plugin.yaml @@ -1,4 +1,4 @@ name: pstack -version: "0.2.0" +version: "0.3.0" description: "Poteto's engineering rigor stack. Playbooks, principles, multi-model review." author: poteto (adapted by Madeleine) diff --git a/skills/arena/SKILL.md b/skills/arena/SKILL.md new file mode 100644 index 0000000..d452005 --- /dev/null +++ b/skills/arena/SKILL.md @@ -0,0 +1,107 @@ +--- +name: arena +description: "Run N parallel candidates, cross-judge, graft, verify." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [engineering, workflow, delegation] + related_skills: [swarm, poteto-mode] +--- + +# Arena + +Spawn N candidates at the same task, cross-judge them, pick one base, graft the strongest parts of the losers into it, verify the result. Use when one attempt at a non-trivial artifact would lock in the wrong shape. + +Open a todo list with one entry per phase (Frame, Fan out, Cross-judge, Pick, Graft, Verify) before launching anything. + +## Phase A: Frame + +Every candidate gets the same prompt, so the prompt is the contract. + +1. State the artifact each candidate is producing. +2. Derive the rubric. 3-6 concrete gradeable criteria for what success looks like on this task. The rubric is the picker's tool in Phase D. Candidates only see the task, never the rubric. +3. Pick the runners (see Runners below). +4. Give each candidate its own output location: `/tmp/arena-/candidate-/`. If the artifact is a change to an existing repo, candidates must not edit the same working tree. Either they write a patch into their own directory, or they return the full artifact in their result, per `pstack:principle-separate-before-serializing-shared-state`. + +### Runners + +Hermes resolves the delegate model from `delegation.model` and `delegation.provider`. There is no per-task model field, so one `delegate_task` call runs every task in it on the same model. Get family diversity by pinning the delegation model per batch and calling `delegate_task` once per family. + +Default: two candidates on different model families, using the two strongest models available in the profile as configured in `pstack:setup-pstack`. Example slugs only, not requirements: `anthropic/claude-sonnet-4.5` and `openai/gpt-5.1`. Use whatever `hermes model` reports for this profile. + +Record the current pin before touching anything: + +```bash +hermes config get delegation +``` + +Then, per family: + +```bash +hermes config set delegation.model +hermes config set delegation.provider # only when the slug needs a provider other than the parent's +``` + +The loader invalidates its config cache on file change, so the next `delegate_task` call in the same session reads the new pin. Restore the recorded values in Phase F. + +- `inherit-parent` means clear the pin: `hermes config unset delegation.model` and `hermes config unset delegation.provider`. That batch then runs on the parent chat model. +- If the runtime rejects a configured slug, run that seat on its family default and say so in the synthesis note. Never invent a slug you have not confirmed. +- `inherit-parent` in the candidate set is legal. It just means the seats are not independent by model family, so say that in the note. +- Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. +- Reasoning effort is global for delegates (`delegation.reasoning_effort`), set in `pstack:setup-pstack`. There is no per-seat reasoning level. Set the budget before the arena opens, generous enough for the hardest seat in it. +- If N exceeds `delegation.max_concurrent_children`, the tool refuses the call. Split into more batches, one per family per chunk. + +## Phase B: Fan out + +One `delegate_task` call per model family, `tasks=[...]` containing every candidate for that family. Run foreground (the default) so the call blocks and returns all results. + +Each task brief is self-contained and carries: + +- **Goal**: produce the artifact at its own output path. +- **Grounding**: the path to shared context every candidate needs, and nothing more, per `pstack:principle-guard-the-context-window`. +- **Output path**: its own `/tmp/arena-/candidate-/` directory. +- **Rationale**: a short note naming the alternatives it considered and what it rejected, and why. + +If a candidate produces no output, proceed with N-1 and note the dropout. + +## Phase C: Cross-judge + +Pick a judge from a model family different from the parent and from the candidate families. Same mechanism as Phase A: pin `delegation.model` to the judge slug, and restore the pin after. + +The judge is read-only. Hermes has no tool-level read-only flag for delegates, so read-only is enforced by the brief: it gets the rubric and the candidate paths by label, is told to read candidates and write nothing, and returns per-criterion scores, a recommended base, and rationale in its final message. Do not let it write files into the candidate directories. + +Spawn it only after every Phase B candidate finished. It runs in parallel with your own Phase D reading. Never spawn it while candidates are still writing. + +## Phase D: Pick a base + +Read every candidate end to end before picking. Score each against the rubric criterion by criterion, not on holistic feel, then compare with the cross-judge. + +Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding. + +Pick the base a future maintainer can extend most easily without breaking invariants. When two feel tied, prefer the cleaner boundary or smaller API, per `pstack:principle-laziness-protocol`. + +## Phase E: Graft + +Walk each losing candidate once more for what is worth porting into the base. Usually one or two things per candidate, not most of it. Fold each graft in by hand, per `pstack:principle-redesign-from-first-principles`, so the result stays coherent under one mental model. Do not paste mechanically. + +If the candidates converge on one shape, that is strong agreement. Note it and ship the consensus shape, no graft needed. If they wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. + +## Phase F: Verify + +Verify the synthesized artifact like any other output, per `pstack:principle-prove-it-works`. Run it, test it, read the diff. If verification finds a problem the arena missed, either Phase A was wrong (reframe and re-run) or a candidate caught it and you skipped the graft (go back to Phase E). Do not paper over it. + +Restore the delegation pin you recorded in Phase A, then run `hermes config get delegation` and confirm the values read back. Leaving a foreign model pinned silently reroutes every later delegate in the session. + +## Outputs + +One synthesized artifact, plus a short `arena-synthesis.md` beside it naming: + +- the base and why it won +- the cross-judge's verdict, and any disagreement with your pick +- each graft with its source candidate +- what was rejected and why +- any convergence or dropouts +- the verification result and the evidence for it diff --git a/skills/correct/SKILL.md b/skills/correct/SKILL.md new file mode 100644 index 0000000..6a09999 --- /dev/null +++ b/skills/correct/SKILL.md @@ -0,0 +1,43 @@ +--- +name: correct +description: "Turn repeated agent mistakes into enforced repo rules." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [engineering, workflow, process] + related_skills: [] +--- + +# Correct + +The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them. + +Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo. + +## When to Use + +When the operator has corrected the same thing more than once, after a revert or a review comment that names a recurring slip. Reach for `pstack:correct` instead of fixing the one instance and moving on. + +## Find the mistake classes + +Read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Use `terminal` for git history and `search_files` for the workaround comments and instruction files. Group the mistakes into classes. A class counts once it has happened twice. + +## Fix each class at the highest level that works + +1. **Eliminate it with architecture.** Give each piece of state one owner and each task one supported way. Hide internals so the wrong import fails. Replace hand-synced lists with one source of truth. Delete old ways and dead code an agent would copy. +2. **Enforce it with types so the bad state can't be written.** If bad code still compiles, add a lint or CI check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more. +3. **Test the behavior.** Fix or delete any test that still passes when the behavior it checks breaks, or that fails when only the internals change. +4. **Write docs or agent rules last, only for judgment calls.** Nothing fails when an agent skips them. + +## Fix and prove + +Fix the most frequent classes now, one commit each. Prove each new check fails on a real past mistake: check out the old code, or reconstruct the bad variant, and watch the check fail before it passes on the fix. Run the same command locally and in CI. Exceptions go on the offending line with a reason, an expiry date, and a human's approval. + +## Keep the rule table + +Keep a table in the agent instruction file (AGENTS.md or the repo's equivalent) that pairs each rule with what enforces it. When the operator corrects you, fix the mistake and add the rule. If the rule was already there and nothing enforces it, that's a repeat, so fix it at the highest level in the same change. Drop a rule once its mistake can't happen. + +**Reply:** each class with its evidence, the level you picked, and why a higher level didn't work. diff --git a/skills/create-formal-verification-skill/SKILL.md b/skills/create-formal-verification-skill/SKILL.md new file mode 100644 index 0000000..dff4672 --- /dev/null +++ b/skills/create-formal-verification-skill/SKILL.md @@ -0,0 +1,60 @@ +--- +name: create-formal-verification-skill +description: "Prove one invariant where tests reach the least." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [engineering, verification, formal-methods] + related_skills: [create-verification-skill] +--- + +# Create a formal verification skill + +A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language. + +## When to Use + +When concurrency, retries, state machines, parsers, or unsafe code need more than tests. Use it on `pstack:create-formal-verification-skill` requests such as "model-check this race" or "prove this invariant". + +## Choose the target from the code + +Answer from the codebase, and ask the user only what you cannot observe. Read with `search_files` and `read_file` before asking anything. If the user named an area or a bug, start there. + +A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify. + +## Let the question choose the tool + +Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. + +- Whether events can happen in a bad order usually suits a model checker over a small model of the design. +- Whether the code itself behaves for every input, as with memory safety, overflow, or a data-structure invariant, usually suits a verifier that runs on the code. +- A property that must hold at every size, where a bound is not enough, can need a proof. + +For concurrent and distributed designs, TLA+ is often the most useful place to start. Prefer a tool that the repo's developers can install and run, and tell the user why you chose it. + +## What makes it good + +- **True to the code.** Every part of the model or proof points to code that a reviewer can open. What the verification treats as one indivisible step is one indivisible step in the code. Names come from this repo. +- **Able to fail.** A check that you have never seen fail proves nothing. Show each property failing on a broken variant of the code it guards, such as a removed check or a reordered step. +- **Findings stay findings.** When the current code breaks the property, report it with the counterexample in the code's terms. Do not weaken the property or the model until it passes, and do not change product code unless the user asks. +- **Honest about scope.** Say what is verified, under which bounds and assumptions, and what is left out. A pass covers the model or the bound, not the whole system. +- **Readable without the tool.** State the property and the harm in one plain sentence each. Tell a counterexample as a short sequence of steps in the code's words. +- **Cheap to rerun.** One command, a reproducible tool version, and a run short enough that the next agent will use it on every relevant change. +- **Kept in step with the code.** When verified code changes, something tells the next agent that the verification needs another look. + +## Generate the verify skill + +Write a project-local skill at `/.hermes/skills/verify-/SKILL.md` with frontmatter that names the area and says when to use it. Without frontmatter the skill never registers, so give it `name` and `description` at minimum. + +From the skill alone, the next agent must be able to tell whether a change touches the verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Use this repo's real commands, paths, and nouns, and leave no placeholders. + +## Prove it before you hand off + +Follow the generated skill once, as the next agent would, on a scratch change that breaks the property in the real code. It must catch the break. Then drop the scratch change and confirm that the check is back where it started: passing, or failing only on the findings you will report. A verify skill that was never run is a draft. If the skill misses the break or a step does not run, fix the skill or the verification, not the scratch change. + +## Hand off + +Tell the user what you verified, which tool you used and why, the bounds, what the check found in plain words, how to run it, and what it does not cover. Suggest a second target only if you found a close one. Point at `pstack:create-verification-skill` when the gap is behavioral coverage rather than a provable property. diff --git a/skills/in-your-own-words/SKILL.md b/skills/in-your-own-words/SKILL.md new file mode 100644 index 0000000..a119405 --- /dev/null +++ b/skills/in-your-own-words/SKILL.md @@ -0,0 +1,14 @@ +--- +name: in-your-own-words +description: "Restate the user's goals and problem in your own words." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [communication, workflow] + related_skills: [pstack:bro] +--- + +Restate in your own words what you think the user's goals are and what problem they're trying to solve. diff --git a/skills/ketchup/SKILL.md b/skills/ketchup/SKILL.md new file mode 100644 index 0000000..7a68027 --- /dev/null +++ b/skills/ketchup/SKILL.md @@ -0,0 +1,50 @@ +--- +name: ketchup +description: "Catch up on what changed since the user's last message." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [communication, workflow] + related_skills: [pstack:bro, pstack:unslop] +--- + +# Ketchup + +Catch the user up on what changed in this chat since the last message they wrote before `pstack:ketchup`, and help them understand each change, not only where it stands. Then lay out every call waiting on them so they can make it from your reply alone. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it. + +Use `pstack:bro`'s voice, not its task: plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out. + +## Gather what changed + +Keep this turn read-only. Make visuals only from what you already have: do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from `delegate_task` subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched, using `terminal` with `gh`, and `session_search` when the record sits in an earlier session. Check each number you will show against the facts it comes from, and say so when you correct one. + +An action item is a call or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one line and no visual. + +One call can cover many items, such as each PR in a set awaiting merge. For each item, collect its link, what it changes for users, the evidence behind your pick, its risk, and your pick. Write "unknown" for a fact the call needs that you do not know. Leave out a link you do not have. + +## Write the reply + +Spend words on the calls, not on the story. Keep what happened under 100 words, not counting pictures, and shorter when less happened. Leave out work that changed nothing for the user. Give each item about 30 words. The reply grows with the number of items: two items need well under 150 words in all, not counting pictures, and thirty need far more. Never cut items or shrink them to stay under a word count: no count in place of a list, and no link in place of an item. A link can add depth, but the reply alone must be enough to decide. + +Open with one short sentence that names what waits on the user, or says nothing does. The action items give the detail. If nothing happened and nothing waits on the user, say so and stop. + +Then show what happened, pictures first. Embed inline the screenshots and videos the work produced, then any diagram that explains a change. Then sum up in one short bullet per thing the user asked for: what came of it, and whether it is done, still running, failed, or not checked. Write each line the way you would say it out loud: "Search was slow from a missing index", not "Search review: done" or "Slow search: missing index". Name any bug found and fixed on the way. Each line must stay true when read alone. Never mark something done that still waits on the user, and leave out anything the action items say. Under the summary, give at most three short lines that change what the user knows or must do. Then name in one line any work left that you can do yourself. + +Then list the action items. Ask the call the user owns, such as merge, approve, or pick, and give your pick. A step you would take first goes in your pick. So does anything that must happen first, and anything that cannot be undone. Give the number or link of each PR, issue, or agent a call is about, also in a call between options. + +Fit the shape to the call. A call about one item is one bullet: the call, your pick, what it changes for users, the evidence behind your pick, and its risk, with the item named once. When items share a call, write the call and your pick once, then give each item its own bullet, riskiest first: its link and name, what it changes for users, the evidence behind your pick, and its risk. Name an item's pick only where it differs from the call's. Give each item's risk even when it is low, such as "Low risk: only the colors change." Say what waiting costs only when it is more than a delay, such as a deadline or lost data. + +For a call between options, give every option the work weighed, each with what it gets the user and what it costs, and the current state when there is one. Those costs are the call's risk, so add no separate risk line. When the screenshots above show the options, write each option's gain and cost under its screenshot. + +## Visuals + +A visual is a picture: a screenshot, a video, a Mermaid diagram, a chart, or a generated image. A Markdown table is not a visual, even with before and after columns. + +When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list, a list of action items, or boxes with nothing connecting them. Never give a fact twice, in text or across visuals. + +Keep each visual small enough to read at a glance: at most six boxes, with at most eight words in each. Write labels as plain words a person would say, not tags like "Tests: pass". A fact that needs a sentence belongs in the text, or nowhere. + +Embed screenshots and videos inline when the change is visible, not only as links. If a visible change has none, mark its summary line "No screenshot yet," and say there what changed on screen. Draw diagrams and charts from facts you have: a Mermaid diagram for how things connect and a chart for numbers. Never invent a number, and never draw or generate a picture of a screen you did not capture. Link only artifacts that exist. diff --git a/skills/poteto-help/SKILL.md b/skills/poteto-help/SKILL.md new file mode 100644 index 0000000..0935a3e --- /dev/null +++ b/skills/poteto-help/SKILL.md @@ -0,0 +1,172 @@ +--- +name: poteto-help +description: "Answer questions about pstack skills, setup, and fixes." +version: 0.1.0 +author: poteto (Hermes adaptation) +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [help, workflow, reference] + related_skills: [poteto-mode] +--- + +# 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. Load `pstack:poteto-mode`, do the work under it, and mention once that `pstack:poteto-help` maps the rest of the system. + +This skill 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. Paths below are relative to this plugin, which lives at `~/.hermes/plugins/pstack/`. Give the user the path, not a URL, because the plugin is installed locally. + +In this fork every skill is a Hermes skill. Invoke it as `/pstack:` in the CLI or TUI, or ask for the `pstack:` skill by name and the agent loads it. There is no bare `/how` command. + +## 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 `pstack: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: + +- Empty `delegation.model` and `delegation.reasoning_effort` in `hermes config get delegation` means `pstack:setup-pstack` hasn't run, so every delegate runs on the parent chat's model and budget. +- No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `pstack:create-verification-skill` when the question is about proving a change works. + +When the delegation settings are unset and it matters, ask whether the user wants to pick a model and a reasoning budget for delegates now. It matters when the user is new, the question is about setup or cost, or the answer depends on which model runs. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices: + +- Now: give them `/pstack:setup-pstack` to run, and answer their question too. +- Later: answer their question, and add one line saying delegates keep inheriting the parent model until they run `/pstack:setup-pstack`. + +## Get set up + +1. Install the plugin by symlinking it into the profile plugins directory, then register its skills for slash commands: + + ```bash + ln -s /path/to/pstack ~/.hermes/profiles//plugins/pstack + hermes config set skills.external_dirs '["plugins/pstack/skills"]' + ``` + +2. Run `/pstack:setup-pstack`. It asks for a reasoning budget, picks the delegate model, and writes `delegation.reasoning_effort`, `delegation.model`, and `delegation.provider`. The settings apply to new sessions. +3. Start a real task with `/pstack:poteto-mode`, a goal, and a check that can pass or fail. + +Installing changes nothing until the user invokes a skill. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [recipes](references/recipes.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 `/pstack:setup-pstack` and pick a smaller budget or a cheaper delegate model. Leaving `delegation.model` unset makes every delegate inherit the parent chat model, which saves tokens when the chat runs on a cheap model. A shorter panel list runs fewer subagents, one for each entry. Save `pstack:poteto-mode` for work that needs rigor. + +The skills use the plain Agent Skills format, so other tools can read them. This fork runs on Hermes tools: `delegate_task` for subagents, `cronjob` for scheduled runs, `session_search` for history. Work that assumed a fleet of background workers maps onto those. + +## Start a task with `pstack:poteto-mode` + +`pstack: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: `. 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 [recipes](references/recipes.md) before you help word one. [Guide page 2](../../docs/guide/02-poteto-mode.md) has examples. + +How long it stays on: + +- Typing `/pstack:poteto-mode` attaches the skill to the turn you send. The agent keeps using it while the task runs and drops it when the subject changes. +- For work that spans many turns, say so in the same message: "stay in poteto-mode until this lands". That keeps the orchestrator loaded across the session. +- There is no Custom Mode in Hermes. To make it the default for a project, put the instruction in the project's `AGENTS.md`, which Hermes loads every session. + +Mid-chat, "new task" makes the mode match a fresh playbook. `pstack:poteto-mode` already runs its playbook steps as `delegate_task` subagents. To get the same style from a subagent of your own, say in the delegate prompt that it runs under the `pstack:poteto-mode` skill. + +## Pick a skill + +The default answer is `pstack: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 | [`pstack:poteto-mode`](../poteto-mode/SKILL.md) | +| Check that the agent understood their goal and the problem before it starts | [`pstack:in-your-own-words`](../in-your-own-words/SKILL.md) | +| Aim a task higher before starting: more expert, more outcome-focused, not overspecified | [`pstack:sharpen`](../sharpen/SKILL.md) | +| Know how code works now, or where new code should live | [`pstack:how`](../how/SKILL.md) | +| Know why code is shaped this way, or where a number came from | [`pstack:why`](../why/SKILL.md) | +| Understand a change or subsystem, explained plainly | [`pstack:teach`](../teach/SKILL.md) | +| Catch up on their own recent work on a topic | [`pstack:recall`](../recall/SKILL.md) | +| Catch up on what changed in this chat since their last message, in plain words and small visuals | [`pstack:ketchup`](../ketchup/SKILL.md) | +| Know what a small diff could break outside itself | [`pstack:blast-radius`](../blast-radius/SKILL.md) | +| Settle types and module shape before code that crosses a function boundary | [`pstack:architect`](../architect/SKILL.md) | +| Get several attempts at one brief, merged into the best one | [`pstack:arena`](../arena/SKILL.md) | +| Run parallel checks over slices, or race workers | [`pstack:swarm`](../swarm/SKILL.md) | +| Have different reviewers read a diff and try to break it | [`pstack:interrogate`](../interrogate/SKILL.md) | +| Fix a bug test-first when a cheap local test exists | [`pstack:tdd`](../tdd/SKILL.md) | +| Apply TypeScript rules to `.ts` or `.tsx` work | [`pstack:typescript-best-practices`](../typescript-best-practices/SKILL.md) | +| Strip comments before review, using a reviewer that didn't write them | [`pstack:no-comments`](../no-comments/SKILL.md) | +| Clean AI tells out of prose | [`pstack:unslop`](../unslop/SKILL.md) | +| Clean AI code slop out of a diff | [`pstack:deslop`](../deslop/SKILL.md) | +| Make a repeated agent mistake impossible to repeat | [`pstack:correct`](../correct/SKILL.md) | +| Write docs, an RFC, a README, a PR description, or a commit message to a standard | [`pstack:technical-writing`](../technical-writing/SKILL.md) | +| Hear the last reply again in plain words | [`pstack:bro`](../bro/SKILL.md) | +| Give agents a scripted way to drive the app and prove behavior | [`pstack:create-verification-skill`](../create-verification-skill/SKILL.md) | +| Keep a verification skill and its feature map current | [`pstack:maintain-verification-skill`](../maintain-verification-skill/SKILL.md) | +| Formally verify a race, invariant, or other property that tests rarely reach | [`pstack:create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md) | +| Vet a performance number before reporting or acting on it | [`pstack:benchmark-checklist`](../benchmark-checklist/SKILL.md) | +| Run a large or cross-cutting change, or one to review after stepping away | [`pstack:figure-it-out`](../figure-it-out/SKILL.md) | +| Keep a decision log during a run, and review it afterward | [`pstack:show-me-your-work`](../show-me-your-work/SKILL.md) | +| Pick the delegate model and a reasoning budget | [`pstack:setup-pstack`](../setup-pstack/SKILL.md) | +| Turn their own working habits into a personal mode skill | [`pstack:automate-me`](../automate-me/SKILL.md) | +| Turn what a finished task taught into skill edits | [`pstack:reflect`](../reflect/SKILL.md) | +| Find their way around pstack | `pstack:poteto-help` | + +If a skill directory next to this one is missing from the table, which happens when the fork grows, read its frontmatter and route by its description. The `principle-*` directories are covered under principles below. + +Close calls: + +- `pstack:how` explains what the code does. `pstack:why` explains the reasons. `pstack:teach` runs one or both and explains the result plainly. +- `pstack:architect` settles the design, then implements. Add "with checkpoint" to review the design before it writes code. +- `pstack:interrogate` reviews the diff. `pstack:blast-radius` looks for breakage outside the diff and proves the one fact that makes the change safe. +- `pstack:recall` rebuilds context across past sessions. Resuming one specific session is the Session pickup playbook. +- `pstack: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. +- `pstack:unslop` fixes prose. `pstack:deslop` fixes code. + +Not in pstack: + +- pstack has no planning skill of its own. Ask `pstack:poteto-mode` for a plan, or load the standalone `plan` skill if the profile installs one. +- There is no `/loop`. A repeating run is a `cronjob`, or the autonomous run playbook with a falsifiable finish condition. +- pstack has no `/orchestrate` skill. Orchestrate is a `pstack:poteto-mode` playbook. + +## Playbooks and principles + +Playbooks are step lists inside `pstack:poteto-mode`, not skills, so they have no slash command. Load one with `skill_view(name='pstack:poteto-mode', file_path='playbooks/.md')`. Inside `pstack: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. "stack them, don't ship" runs Autopilot-stack. +- "run the eval playbook" runs Eval. + +Without `pstack:poteto-mode`, a phrase such as "babysit this pr" doesn't route anywhere. Say which playbook you want, or load the orchestrator first. The Playbooks section of [`poteto-mode`](../poteto-mode/SKILL.md) lists every playbook and when it applies. [Guide page 6](../../docs/guide/06-verify-and-ship.md) covers opening, babysitting, and landing a PR. + +For work that spans phases or stacked PRs, ask `pstack:poteto-mode` for a plan. It writes the plan and doesn't implement it. For a design question, the Prototype playbook or `pstack:architect` settles it in code first. + +Principles are one-rule skills that `pstack: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." Any `principle-*` skill still loads on demand when the user names it. [Guide page 8](../../docs/guide/08-principles.md) lists them. + +## Fix a run that went wrong + +| Symptom | Fix | +|---|---| +| The mode stopped applying after a few turns | It was attached to one turn. Ask for `pstack:poteto-mode` again, or say "stay in poteto-mode until this lands". | +| 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 | `pstack:setup-pstack` writes Hermes config, which loads at session start. Start a new session. | +| Runs cost more than expected | See the cost paragraph under Get set up. | +| A skill didn't load on its own | Skills load when you type `/pstack:` or the orchestrator loads them, and it doesn't load every skill. Ask for the skill by name. | +| Parallel agents overwrote each other | Subagents share the workspace. Partition by file, give each one its own scope, and have the orchestrator merge. | +| An overnight run moved but finished nothing | Give it a check that can pass or fail, not a duration. See [guide page 7](../../docs/guide/07-overnight.md). | +| 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, [recipes](references/recipes.md) has one-line steers. [Guide page 10](../../docs/guide/10-recipes-and-pitfalls.md) has more pitfalls and the recipes worth copying. + +## Make pstack my own + +- [`pstack:automate-me`](../automate-me/SKILL.md) drafts a personal mode skill from the user's own history, to use alongside `pstack:poteto-mode`. +- [`pstack:reflect`](../reflect/SKILL.md) after a session turns its lessons into skill edits the user approves. +- `pstack:poteto-mode write a skill for ` runs the authoring playbook. The eval playbook tests a skill change blind. +- Fix a misbehaving skill in its own change, not inside the feature work where it went wrong. + +[Guide page 9](../../docs/guide/09-make-it-yours.md) covers each of these. + +## Reply + +Lead with the answer. Give at most one example prompt in a code block, adapted from [recipes](references/recipes.md) when one fits, then the link to that file. Keep it short unless the user asked for the whole map. diff --git a/skills/poteto-help/references/recipes.md b/skills/poteto-help/references/recipes.md new file mode 100644 index 0000000..83fb95e --- /dev/null +++ b/skills/poteto-help/references/recipes.md @@ -0,0 +1,57 @@ +# Prompts worth copying + +Swap in the real paths, skills, and done checks. Informal wording works. Every `pstack:` here is a Hermes skill: type `/pstack:` in the CLI or TUI. + +## Understand + +- `/pstack:poteto-mode read . restate the underlying issue in your own words, in plain english.` +- `/pstack:poteto-mode investigate why . give me what we know, what data you used, and your best hypotheses. don't change any code yet.` +- `use /pstack:how to understand . then use /pstack:why to find out why it broke recently.` +- `/pstack:recall my work on from last week, then read .` +- `/pstack:teach me why you implemented it this way and not . what did you trade off?` +- `/pstack:poteto-mode take over this branch. read the decision log, find what's done, and continue. don't redo finished work.` + +## Build + +- Bug: `/pstack:poteto-mode . repro first, then fix and verify.` +- Bug in an app: `/pstack:poteto-mode repro this with the project's verify skill. if it repros on main, fix it and show me the run as proof.` +- Bug with a cheap test: `/pstack:poteto-mode repro first. if there's a cheap test path, /pstack:tdd it. then fix and rerun.` +- Feature: `/pstack:poteto-mode add . stays byte-identical. verify both.` +- Refactor: `/pstack:poteto-mode move into one module, zero behavior change. record the current output first and prove it's unchanged after.` +- Perf: `/pstack:poteto-mode takes