Cursor plugin specification and official plugins
TypeScript
feat(pstack): add prompting references to /poteto-help (#507)
lauren807c031086fc
diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.jsonindex 0604e033..1fe039fc 100644--- a/pstack/.cursor-plugin/plugin.json+++ b/pstack/.cursor-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "pstack","displayName": "pstack",- "version": "0.15.11",+ "version": "0.15.12","description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.","author": {"name": "Lauren Tan"diff --git a/pstack/skills/poteto-help/SKILL.md b/pstack/skills/poteto-help/SKILL.mdindex 38ef479a..f1f10bbf 100644--- a/pstack/skills/poteto-help/SKILL.md+++ b/pstack/skills/poteto-help/SKILL.md@@ -33,7 +33,7 @@ Check the state that changes the answer, and mention it only when it does:2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats.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. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them.+Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. 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 [`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 Auto or a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor.@@ -41,7 +41,7 @@ pstack is built for Cursor. Its skills use the Agent Skills format, so other too## 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. [Guide page 2](../../docs/guide/02-poteto-mode.md) has examples.+`/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. [Guide page 2](../../docs/guide/02-poteto-mode.md) has examples.Whether `/poteto-mode` stays on depends on how the user starts it:@@ -132,7 +132,7 @@ Principles are one-rule skills that `/poteto-mode` reads and cites in its replie| An overnight run moved but finished nothing | `/loop` needs 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. |-[Guide page 10](../../docs/guide/10-recipes-and-pitfalls.md) has more pitfalls and the recipes worth copying.+For a run that drifts, [`references/prompting.md`](references/prompting.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@@ -145,4 +145,4 @@ Principles are one-rule skills that `/poteto-mode` reads and cites in its replie## Reply-Lead with the answer. Give at most one example prompt in a code block, then the link to that file. Keep it short unless the user asked for the whole map.+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.diff --git a/pstack/skills/poteto-help/references/prompting.md b/pstack/skills/poteto-help/references/prompting.mdnew file mode 100644index 00000000..6b72b2e6--- /dev/null+++ b/pstack/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 `/loop` 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.diff --git a/pstack/skills/poteto-help/references/recipes.md b/pstack/skills/poteto-help/references/recipes.mdnew file mode 100644index 00000000..73118e2a--- /dev/null+++ b/pstack/skills/poteto-help/references/recipes.md@@ -0,0 +1,47 @@+# 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.`+- `/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 dismissals too.+- `/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. /loop until done. 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.+- `/poteto-mode full autopilot on this queue. each item is independent.`+- `/poteto-mode autopilot these changes but stack them, don't ship. i'll land the stack.`+- `/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.