diff --git a/README.md b/README.md index a18fabd..52d4171 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,279 @@ -# devin-pstack +# pstack -Devin (`devin`) port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) (`0.15.29`) by [Lauren Tan (poteto)](https://x.com/poteto). +Devin (`devin`) port of [pstack](https://github.com/cursor/plugins/tree/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack) (`0.15.29`) by [Lauren Tan (poteto)](https://x.com/poteto). -See the [upstream pstack README](https://github.com/cursor/plugins/blob/main/pstack/README.md) and the [guide](./docs/guide/README.md) for usage and documentation. +i'm [poteto](https://x.com/poteto). i'm not a president or ceo, but i've worked with millions of lines of code at Meta, Netflix, and Cursor. i'm also on the react core team where i help build and maintain react compiler. -## Install +there's a growing sense that ai writes too much slop code. i agree. i don't want to ship like a team of twenty slop artists. throughput without quality is not a goal i aspire to. if you want to go fast, go deep first. -Install the plugin with the Devin CLI: +**pstack is my answer.** these are the same skills i use every day to ship high quality code at Cursor. this turns cursor into a real engineering team. the goal is not to maximize loc, in fact it's the opposite. pstack helps you write less, but higher quality code. + +**pstack gives you fearless parallelism.** when you can go deep on one agent and trust it to write good, verifiable code, you can truly parallelize with confidence. start multiple agents up with `poteto-mode` and trust that they'll apply rigorous engineering principles to their work. + +**cursor gives you the best of all worlds.** every frontier model has its strengths and weaknesses. use any model with pstack. in fact, many of my skills use multi-model workflows to take advantage of each model's unique strengths. + +fork it. improve it. make it yours. PRs are welcome! + +## install ```bash devin plugins install pstack-ports/devin-pstack +devin plugins list ``` -Verify the installation: +## get started -```bash -devin plugins list +two steps: + +1. run [`/pstack:setup-pstack`](./skills/setup-pstack/SKILL.md), pick a reasoning budget, and choose which models you want. +2. use [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) whenever you're doing anything that requires rigor. + +new here? the [pstack guide](./docs/guide/README.md) walks you through a first real task, from setup and prompting through verification and overnight runs. stuck, or unsure which skill fits? ask [`/pstack:poteto-help`](./skills/poteto-help/SKILL.md). + +that's it. the other skills are situational, and the mode skill uses them for you as needed. out of the box the mode splits work by model strength: code delegates (feature, refactoring, bug fix, perf, hillclimb) go to grok, while the hardest changes, prose, and judgment go to opus 5.5. the default panel is opus 5.5 / grok. [`/pstack:setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it. + +## usage + +use [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) at the start of a task. it reads your request, picks from a set of playbooks, and runs the other skills as the steps need them. + +pick `/pstack:poteto-mode` from the `/` menu before you type your task, so devin attaches the skill to the message. + +### just use [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) + +this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with twenty-three playbooks: + +``` +/pstack:poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro +first, then fix and verify. +``` + +``` +/pstack:poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by +morning. +``` + +
+the twenty-three playbooks + +| playbook | for | +|---|---| +| [investigation](./skills/poteto-mode/playbooks/investigation.md) | a read-only question. how does x work, why was y built this way, are we sure. | +| [bug fix](./skills/poteto-mode/playbooks/bug-fix.md) | reproduce a defect, root-cause it, and fix with runtime evidence. | +| [perf](./skills/poteto-mode/playbooks/perf-issue.md) | trace a measured slowness and improve it against a baseline. | +| [hillclimb](./skills/poteto-mode/playbooks/hillclimb.md) | sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win. | +| [runtime forensics](./skills/poteto-mode/playbooks/runtime-forensics.md) | diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation. | +| [trace forensics](./skills/poteto-mode/playbooks/trace-forensics.md) | diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot). | +| [feature](./skills/poteto-mode/playbooks/feature.md) | new or changed behavior, built from a named data shape. | +| [refactoring](./skills/poteto-mode/playbooks/refactoring.md) | a behavior-preserving change to structure or shape. | +| [prototype](./skills/poteto-mode/playbooks/prototype.md) | a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it. | +| [visual parity](./skills/poteto-mode/playbooks/visual-parity.md) | pixel-exact ui equivalence between two implementations. | +| [authoring a skill](./skills/poteto-mode/playbooks/authoring-a-skill.md) | writing or editing a SKILL.md. | +| [eval](./skills/poteto-mode/playbooks/eval.md) | test how a skill or prompt change affects agent behavior, blinded. | +| [babysit](./skills/poteto-mode/playbooks/babysit.md) | drive a pr or a stack to merge-ready: conflicts, review threads, ci. | +| [shipping](./skills/poteto-mode/playbooks/shipping.md) | independently verify a green stack, then land the contiguous verified run bottom-up through github by default or origin when available. | +| [autonomous run](./skills/poteto-mode/playbooks/autonomous-run.md) | drive a long task to completion without stopping. | +| [orchestrate](./skills/poteto-mode/playbooks/orchestrate.md) | a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents. | +| [autopilot-full](./skills/poteto-mode/playbooks/autopilot-full.md) | run independent prs to merged with one owner per pr. a swarm verifies each code-ready head, and every later change to the patch gets a fresh check. | +| [autopilot-stack](./skills/poteto-mode/playbooks/autopilot-stack.md) | build and verify one linear base-branch stack for the operator to review and land. | +| [session pickup](./skills/poteto-mode/playbooks/session-pickup.md) | resume or take over a prior agent's in-flight work. | +| [pause safely](./skills/poteto-mode/playbooks/pause-safely.md) | suspend in-flight work cleanly so it can be resumed later. | +| [multi-phase plan](./skills/poteto-mode/playbooks/multi-phase-plan.md) | work that spans phases or stacked PRs. | +| [worktree cleanup](./skills/poteto-mode/playbooks/worktree-cleanup.md) | reclaim disk by pruning merged or abandoned worktrees and stale ios simulators, safety-gated. | +| [opening a pr](./skills/poteto-mode/playbooks/opening-a-pr.md) | open a ready pr from small ordered commits with a conventional commits title and a briefing-style body. invoked at the end of every other playbook. | + +
+ + + +when invoked it: + +1. matches your task to a [playbook](./skills/poteto-mode/playbooks/) and opens a todo list whose first items are its steps, copied in verbatim. +2. routes to the other skills as the steps fire. +3. writes unslopped replies framed for the consumer and the maintainer. + +the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/poteto-mode/SKILL.md). + +to keep [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, pin it in `AGENTS.md` ("default to the poteto-mode skill's style for non-trivial tasks") or start each task's message with it. a typed `/pstack:poteto-mode` attaches the skill to one message, and it fades as the chat moves on. + +[`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) works extremely well with devin's `/loop` command. you can make devin work for many hours without sacrificing rigor. + +## skills + +[`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `no-comments`, `technical-writing`, `tdd`, and the principles). the table below is for when you want one directly: + +``` +/pstack:how do we cancel runs? do we have an n+1 when we look up every run to cancel? +``` + +``` +/pstack:interrogate review this pr. ``` -Then run `/pstack:setup-pstack` once to pick a reasoning budget and per-role models, and use `/pstack:poteto-mode` for anything that needs rigor. +
+all skills + +| skill | use it when | +|---|---| +| [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) | default entry point for any non-trivial task. | +| [`/pstack:poteto-help`](./skills/poteto-help/SKILL.md) | you're new to pstack, or unsure which skill, playbook, or principle fits. finds out what you're trying to do, answers that part, and hands you a prompt to type. runs only when you type `/pstack:poteto-help`. | +| [`/pstack:in-your-own-words`](./skills/in-your-own-words/SKILL.md) | you want the agent to play back your goal and the problem before it starts. runs only when you type `/pstack:in-your-own-words`. | +| [`/pstack:sharpen`](./skills/sharpen/SKILL.md) | you want a prompt made deeper, not bigger, before you send it: what a top professional would do that you didn't ask for, the raw material they'd start from, their methods and tools, and an outside check that the result is right. hands back the rewritten prompt and leaves your choices open. doesn't do the task. runs only when you type `/pstack:sharpen`. | +| [`/pstack:how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. | +| [`/pstack:why`](./skills/why/SKILL.md) | you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse). | +| [`/pstack:recall`](./skills/recall/SKILL.md) | you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief. | +| [`/pstack:ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long. | +| [`/pstack:blast-radius`](./skills/blast-radius/SKILL.md) | you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted. | +| [`/pstack:architect`](./skills/architect/SKILL.md) | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. | +| [`/pstack:arena`](./skills/arena/SKILL.md) | you want N parallel attempts at the same thing, then to grab the best parts of each. | +| [`/pstack:swarm`](./skills/swarm/SKILL.md) | you want N parallel workers across different slices or races, then one aggregated report. | +| [`/pstack:interrogate`](./skills/interrogate/SKILL.md) | you have a diff and want different models to try to break it, including a strict code-quality lens. | +| [`/pstack:automate-me`](./skills/automate-me/SKILL.md) | you want your own `-mode` skill, drafted from how you've actually worked. | +| [`/pstack:make-bot-ui`](./skills/make-bot-ui/SKILL.md) | you want a page or dashboard whose buttons wake a Devin session over the Devin Cloud API or a webhook, including the sender-key handoff and Tailscale. | +| [`/pstack:setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models and writes a config rule. | +| [`/pstack:reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. | +| [`/pstack:correct`](./skills/correct/SKILL.md) | you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it. | +| [`/pstack:teach`](./skills/teach/SKILL.md) | you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram. | +| [`/pstack:tdd`](./skills/tdd/SKILL.md) | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. | +| [`/pstack:benchmark-checklist`](./skills/benchmark-checklist/SKILL.md) | you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it. | +| [`/pstack:no-comments`](./skills/no-comments/SKILL.md) | strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints. | +| [`/pstack:typescript-best-practices`](./skills/typescript-best-practices/SKILL.md) | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. | +| [`/pstack:figure-it-out`](./skills/figure-it-out/SKILL.md) | no bundled playbook fits. designs a rigorous, auditable playbook for the task. | +| [`/pstack:show-me-your-work`](./skills/show-me-your-work/SKILL.md) | you want a reviewable decision trail. logs decisions to a tsv you can commit. | +| [`/pstack:create-verification-skill`](./skills/create-verification-skill/SKILL.md) | your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform. | +| [`/pstack:maintain-verification-skill`](./skills/maintain-verification-skill/SKILL.md) | your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections. | +| [`/pstack:create-formal-verification-skill`](./skills/create-formal-verification-skill/SKILL.md) | tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change. | +| [`/pstack:maintain-formal-verification-skill`](./skills/maintain-formal-verification-skill/SKILL.md) | code your formal verification covers has changed since it was last checked. updates the model, harness, or properties to match the code, reruns, and says whether each failure is drift in the verification or a bug in the code. | +| [`/pstack:unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. | +| [`/pstack:bro`](./skills/bro/SKILL.md) | you want the last message restated in plain human language, no jargon. | +| [`/pstack:technical-writing`](./skills/technical-writing/SKILL.md) | layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages. | + +
+ + + +### examples + +mostly i type [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) at the start of a task and let it route to a playbook. the other skills fire as the steps need them. a few i reach for directly. + + +
+all the examples + +``` +bug fix: /pstack:poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even + when idle. repro first, then fix and verify. +perf: /pstack:poteto-mode a big list takes a second or two to load even though we virtualize. + run a cpu trace and tell me why. +feature: /pstack:poteto-mode build a small feature behind a feature flag. verify it really works. +prototype: /pstack:poteto-mode build two prototypes of the markdown renderer so we can compare. + spawn an agent for each. +multi-phase: /pstack:poteto-mode open source these skills as a plugin. nothing internal leaks, work + in a temp dir, show me the dependency graph first. +overnight run: /pstack:poteto-mode i'm going to bed. land the stack even if ci flakes. i want + everything merged by morning. +babysit: /pstack:poteto-mode check on pr 123. anything outstanding? +visual parity: /pstack:poteto-mode the row spacing is too tall when this flag is on. the second image + is correct. repro and fix until it matches. +figure it out: /pstack:poteto-mode i'm stepping away. migrate every caller from the synchronous store + to the new async one, keeping behavior identical. i want to trust it was done + right when i'm back. +how: /pstack:how do we cancel runs? do we have an n+1 when we look up every run to cancel? +why: /pstack:why is this feature flag not on yet? +architect: design this instrumentation to be high signal with no false positives. /pstack:architect + this first. +arena: /pstack:arena take my prompt to the arena verbatim. i want to compare their proposals + with yours. +swarm: /pstack:swarm check every package under packages/ against its check.sh. one worker per + package. one report. +interrogate: /pstack:interrogate review this pr. +tdd: /pstack:tdd implement +unslop: can we unslop and tighten the new changes? +reflect: /pstack:reflect that took too long. capture what we learned so the next run doesn't + repeat it. +correct: /pstack:correct +show-me-your-work: /pstack:show-me-your-work keep a decision trail i can review when i'm back. +automate-me: /pstack:automate-me +help: /pstack:poteto-help which skill should i use to review this branch? +``` + +
+ +## the `poteto-agent` and Comment Sicko subagents + +[`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) runs in the chat that receives it. that chat owns the playbook, the todo list, and every subagent spawn. + +pstack also ships [`profile: "pstack:poteto-agent"`](./agents/poteto-agent.md) as the wrapper for delegates spawned during a run. it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `subagent_general` skips that read and drifts. do not spawn `poteto-agent` to run the playbook itself. + +[`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) and [`profile: "pstack:poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper. + +pstack also ships [Comment Sicko](./agents/comment-sicko.md), a read-only comment reviewer available as `profile: "pstack:comment-sicko"`. usually invoke it through [`/pstack:no-comments`](./skills/no-comments/SKILL.md), not directly. + +## principles + +twenty-four short skills, one principle each. `poteto-mode` indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each. + +
+all twenty-four principles + +| principle | group | rule | +|---|---|---| +| [laziness-protocol](./skills/principle-laziness-protocol/SKILL.md) | core | Bias toward deletion and the smallest change that solves the problem. | +| [foundational-thinking](./skills/principle-foundational-thinking/SKILL.md) | core | Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious. | +| [redesign-from-first-principles](./skills/principle-redesign-from-first-principles/SKILL.md) | core | Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on. | +| [attack-the-premise](./skills/principle-attack-the-premise/SKILL.md) | core | Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it. | +| [subtract-before-you-add](./skills/principle-subtract-before-you-add/SKILL.md) | core | Remove dead weight, redundant validators, and stub references first, then build on the simpler base. | +| [minimize-reader-load](./skills/principle-minimize-reader-load/SKILL.md) | core | Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope. | +| [outcome-oriented-execution](./skills/principle-outcome-oriented-execution/SKILL.md) | core | Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code. | +| [experience-first](./skills/principle-experience-first/SKILL.md) | core | Choose user delight over implementation convenience; ship fewer polished features over more rough ones. | +| [exhaust-the-design-space](./skills/principle-exhaust-the-design-space/SKILL.md) | core | Build 2-3 competing prototypes and compare side by side before committing. | +| [build-the-lever](./skills/principle-build-the-lever/SKILL.md) | core | Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun. | +| [model-the-domain](./skills/principle-model-the-domain/SKILL.md) | architecture | Encode the domain in a structure instead of scattered conditionals. | +| [boundary-discipline](./skills/principle-boundary-discipline/SKILL.md) | architecture | Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions. | +| [type-system-discipline](./skills/principle-type-system-discipline/SKILL.md) | architecture | Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, exhaust variants, derive from authoritative schemas. | +| [make-operations-idempotent](./skills/principle-make-operations-idempotent/SKILL.md) | architecture | Converge to the same end state regardless of partial prior runs. | +| [migrate-callers-then-delete-legacy-apis](./skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) | architecture | Migrate callers and delete the old API in the same wave instead of preserving compatibility layers. | +| [separate-before-serializing-shared-state](./skills/principle-separate-before-serializing-shared-state/SKILL.md) | architecture | Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant. | +| [prove-it-works](./skills/principle-prove-it-works/SKILL.md) | verification | Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'. | +| [fix-root-causes](./skills/principle-fix-root-causes/SKILL.md) | verification | 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-verifiable-units](./skills/principle-sequence-verifiable-units/SKILL.md) | verification | Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer. | +| [test-behavior-not-implementation](./skills/principle-test-behavior-not-implementation/SKILL.md) | verification | Apply when you write, change, or keep 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](./skills/principle-explain-the-number/SKILL.md) | verification | Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think. | +| [guard-the-context-window](./skills/principle-guard-the-context-window/SKILL.md) | delegation | Route bulk to subagents; keep summaries in the main thread, not raw payloads. | +| [never-block-on-the-human](./skills/principle-never-block-on-the-human/SKILL.md) | delegation | Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions. | +| [encode-lessons-in-structure](./skills/principle-encode-lessons-in-structure/SKILL.md) | meta | Encode the rule as a lint, metadata flag, runtime check, or script instead of more text. | + +
+ +## not shipped here + +a few things `poteto-mode` references but doesn't bundle: + +- `/deslop` and the `deslop` skill ship in the `cursor-team-kit` plugin. +- `control-cli` (for CLIs and TUIs) and `control-ui` (for browser, Electron, web) ship in `cursor-team-kit` too. +- `/create-skill` is a cursor built-in. cursor also ships a built-in `/autopilot` that watches a pr. inside `poteto-mode`, pr-status requests go to the [babysit playbook](./skills/poteto-mode/playbooks/babysit.md) instead. + +install `cursor-team-kit` alongside pstack if you want the full set. + +## why are there no planning skills? + +devin already has a great plan mode which works great with pstack. but personally, i don't believe in planning. the best spec is code. if you do want to make a plan, [`/pstack:poteto-mode`](./skills/poteto-mode/SKILL.md) covers it, but it's not a default. + +## make it yours + +`poteto-mode` is my style. you may not want exactly that. + +type [`/pstack:automate-me`](./skills/automate-me/SKILL.md). it mines your recent transcripts, drafts a `-mode` skill from how you've actually worked, and routes through pstack underneath. you keep pstack as the base and end up with your own routing skill alongside `poteto-mode`. + +models are configurable too. type [`/pstack:setup-pstack`](./skills/setup-pstack/SKILL.md). it detects the models you have access to and writes a small always-applied rule mapping each role (code, judgment, the review panels) to a model. every skill reads it and falls back to sensible defaults when the rule is absent, so you override only what you want. + +when a default changes, a rule written before the change still pins the old default. delete those role lines, or delete the file, then run `/pstack:setup-pstack` again. a rerun keeps any role whose model differs from the default. + +## automations + +pstack also ships a dormant [benny automation pack](./automations/benny/). benny triages slack issue reports, then reproduces and fixes confirmed bugs with real ui evidence. its files are not registered as slash skills. + +to set it up, point devin at [`FOR_AGENTS.md`](./automations/benny/FOR_AGENTS.md). setup copies the pack into the target repository at `.devin/automations/benny/`, enables pstack there for shared skills, and keeps user configuration outside the copied pack. + +## license + +MIT diff --git a/docs/guide/05-build-and-clean.md b/docs/guide/05-build-and-clean.md index 6053b80..5ef1dda 100644 --- a/docs/guide/05-build-and-clean.md +++ b/docs/guide/05-build-and-clean.md @@ -56,7 +56,7 @@ In context, that's enough. [`/pstack:tdd`](../../skills/tdd/SKILL.md) writes the ## Clean before you commit -The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs a slop-strip pass on the diff before each commit and applies [`/pstack:unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `deslop` ships in Cursor's `cursor-team-kit` plugin, not in this port. Ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits. +The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs a slop-strip pass on the diff before each commit and applies [`/pstack:unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in the `cursor-team-kit` plugin, not in pstack. If you don't have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits. For prose, `/pstack:unslop` takes a target and any extra rules you have: @@ -76,7 +76,7 @@ Comments need their own pass, and not from the agent that wrote them. An author [`/pstack:no-comments`](../../skills/no-comments/SKILL.md) spawns [Comment Sicko](../../agents/comment-sicko.md), a read-only reviewer with a short keep list: license headers, doc comments on a public API, links that explain what code can't, behavior forced by an external dependency you can't reshape. Everything else goes. A surprise in your own code gets no such pass. The comment comes back as a refactor flag, and `/pstack:no-comments` fixes the flags it accepts at the root cause. When a comment claims a constraint, "do not remove", the skill offers to encode the claim as a type, test, or lint. Either way, the comment comes out. -The division of labor is worth keeping straight. `/pstack:deslop` cleans slop out of the code, `/pstack:unslop` cleans it out of prose, and `/pstack:no-comments` hands the comments to a reviewer who didn't write them. +The division of labor is worth keeping straight. `/deslop` cleans slop out of the code, `/pstack:unslop` cleans it out of prose, and `/pstack:no-comments` hands the comments to a reviewer who didn't write them. **Pitfall:** cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say `deslop it` before you commit, not after review calls it out. diff --git a/docs/guide/10-recipes-and-pitfalls.md b/docs/guide/10-recipes-and-pitfalls.md index d0c9fc6..5b9c24e 100644 --- a/docs/guide/10-recipes-and-pitfalls.md +++ b/docs/guide/10-recipes-and-pitfalls.md @@ -171,7 +171,7 @@ That's the whole prompt. [`/pstack:bro`](../../skills/bro/SKILL.md) restates the - **Correcting the same mistake by hand.** A correction in chat helps one run. `/pstack:correct` fixes the repo so no later run repeats it. - **Using `/pstack:arena` for coverage.** `/pstack:arena` repeats one design or code brief, then picks a base and grafts the best parts. `/pstack:swarm` partitions slices or declared race arms and aggregates one report. - **Accepting every review comment.** Bots and humans both file real catches and noise in one list. `/pstack:interrogate` sorts findings into act-on and dismissed buckets with reasons, and you can override either way. -- **Treating `auto` as a model slug.** `auto` and `inherit-parent` mean "omit the model field so the subagent inherits the parent chat model." [Setup](./01-setup.md) covers the roles. +- **Treating `auto` as a model slug.** `auto` and `inherit-parent` mean "spawn the role's subagents with `subagent_general` or `subagent_explore`, so they follow the parent chat model." [Setup](./01-setup.md) covers the roles. - **Putting a Fusion model in a role.** A `fusion-*` slug names a lead and sidekick pair for the main chat, so pstack rejects it and falls back to the role's default. Pick the lead's or the sidekick's own slug, like `claude-opus-5-5-max` or `swe-2-high`. - **Reporting success off a green build.** A build proves it compiles. Ask for the real command, flow, stored value, or profile, and expect the evidence in the reply. - **Writing a `SKILL.md` freehand.** Route it through the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md) so validation and review happen. diff --git a/skills/automate-me/SKILL.md b/skills/automate-me/SKILL.md index d660b2e..353b6ce 100644 --- a/skills/automate-me/SKILL.md +++ b/skills/automate-me/SKILL.md @@ -26,7 +26,7 @@ Update mode changes the rest of the flow: ### 1. Mine their history -Locate the active workspace's transcripts before fanning out. `devin list` names this directory's sessions; their data lives under `~/Library/Application Support/Devin/` on macOS (`%APPDATA%\devin` on Windows). Use only this workspace's sessions. Don't sweep unrelated projects' sessions. That crosses workspace boundaries and reads private chats. +Locate the active workspace's transcripts before fanning out. `devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. Use only this workspace's sessions. Don't sweep unrelated projects' sessions. That crosses workspace boundaries and reads private chats. Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting: @@ -93,12 +93,12 @@ Work in a worktree off main. Commit and open a PR. Don't push to main directly. ## Evaluation -A `-mode` skill is subjective output. A `create-skill`-style test/iterate benchmark loop isn't useful here. Vibe-check with the user: does it read like them? Did it miss anything? Then ship. +A `-mode` skill is subjective output. An authoring-playbook-style test/iterate benchmark loop isn't useful here. Vibe-check with the user: does it read like them? Did it miss anything? Then ship. Run a description-optimization loop only if the skill's trigger accuracy turns out to be a problem in practice. ## When not to use -- User wants a task-specific skill (not working conventions): `create-skill` alone, no mining required. +- User wants a task-specific skill (not working conventions): run the Authoring or modifying a skill playbook (`skills/poteto-mode/playbooks/authoring-a-skill.md`) alone, no mining required. - User wants to capture one narrow workflow (e.g. "how I write commit messages"). That's a regular skill, not a mode skill. diff --git a/skills/poteto-help/SKILL.md b/skills/poteto-help/SKILL.md index 9926526..d2eb9f5 100644 --- a/skills/poteto-help/SKILL.md +++ b/skills/poteto-help/SKILL.md @@ -107,9 +107,9 @@ Close calls: Not in pstack: -- `deslop`, `control-cli`, and `control-ui` ship in Cursor's `cursor-team-kit` plugin and are not part of this port. Ask for the same outcome in plain words. +- `/deslop`, `control-cli`, and `control-ui` ship in the `cursor-team-kit` plugin. - `/loop` is a Devin built-in. -- pstack has no `/pstack:orchestrate` skill. Orchestrate is a `/pstack:poteto-mode` playbook. +- pstack has no `/orchestrate` skill. Orchestrate is a `/pstack:poteto-mode` playbook. If the slash menu shows `/orchestrate`, another plugin provides it. ## Playbooks and principles diff --git a/skills/poteto-mode/playbooks/eval.md b/skills/poteto-mode/playbooks/eval.md index b5070c8..a3b76db 100644 --- a/skills/poteto-mode/playbooks/eval.md +++ b/skills/poteto-mode/playbooks/eval.md @@ -19,7 +19,7 @@ 3. **Author one organic prompt.** What a user would type. No leakage of what's being measured. 4. **Spawn N parallel candidates** on different models per the **arena** skill's Phase B. Each works in its own sanitized dir. Same prompt to each. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. 5. **Spawn one blinded judge** on a different model family per the **arena** skill's Phase C. Judge sees outputs by sanitized label and the rubric, never a model name. -6. **Verify the chain from transcripts, not self-report.** Read each candidate's local transcript in Devin's session store (`devin list` names this directory's sessions; data lives under `~/Library/Application Support/Devin/` on macOS, `%APPDATA%\devin` on Windows). Do not read unrelated projects' sessions. Look at which files each candidate actually opened. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims. +6. **Verify the chain from transcripts, not self-report.** Read each candidate's local transcript in Devin's session store. `devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. Do not read unrelated projects' sessions. Look at which files each candidate actually opened. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims. 7. **Read every candidate output yourself** end to end. Compare to the judge's verdict. Disagreement means a model is biased or the rubric is ambiguous. Synthesize. **Reply:** variant under test, rubric, per-candidate notes, judge's verdict, your synthesis, and a recommendation for whether to promote the variant. diff --git a/skills/poteto-mode/playbooks/session-pickup.md b/skills/poteto-mode/playbooks/session-pickup.md index ef649f6..e7ef62c 100644 --- a/skills/poteto-mode/playbooks/session-pickup.md +++ b/skills/poteto-mode/playbooks/session-pickup.md @@ -2,7 +2,7 @@ **You own the resume point. Read the prior trail, don't redo it.** -1. Locate the prior trail. A local transcript in Devin's session store (`devin list` names this directory's sessions; data lives under `~/Library/Application Support/Devin/` on macOS, `%APPDATA%\devin` on Windows — do not read unrelated projects' sessions), a cloud-session URL, or a pushed branch. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. +1. Locate the prior trail. A local transcript in Devin's session store, a cloud-session URL, or a pushed branch. `devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. Do not read unrelated projects' sessions. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. 2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions made. The prior trail is authoritative input. Resist the bias to re-derive it. 3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass means you're treating the trail as untrustworthy when it's authoritative. 4. Route the remaining work to the matching playbook and pick the verdict: continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here. The routed playbook owns the rest. diff --git a/skills/poteto-mode/scripts/worktree-audit.sh b/skills/poteto-mode/scripts/worktree-audit.sh index 1f180e0..e01f2b3 100755 --- a/skills/poteto-mode/scripts/worktree-audit.sh +++ b/skills/poteto-mode/scripts/worktree-audit.sh @@ -61,9 +61,9 @@ elif raw=$(gh pr list --author "@me" --state all --limit 1000 \ fi [ -s "$prs" ] || echo "[]" > "$prs" -# Devin session store: per-session data under the app's user dir. -transcripts="$HOME/Library/Application Support/Devin/User" -[ "$(uname)" = "Darwin" ] || transcripts="$HOME/.config/devin" +# CLI session store: ~/.local/share/devin/cli/sessions.db +# ($XDG_DATA_HOME or DEVIN_SESSIONS_DIR when set). No per-OS branch. +transcripts="${DEVIN_SESSIONS_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/devin/cli}" now=$(date +%s) echo "# base: $base" diff --git a/skills/recall/SKILL.md b/skills/recall/SKILL.md index a914209..7901cc1 100644 --- a/skills/recall/SKILL.md +++ b/skills/recall/SKILL.md @@ -12,7 +12,7 @@ Keep it tight and on-topic. Read only what the in-scope threads need, then stop. Your context lives in two records. Your own chat history holds what you did and decided. The shared record holds everything that happened around the same code under other names: the symptoms users keep reporting, the fixes that shipped and got reverted, the errors still firing in prod. That second record is what the **why** skill searches, across source control, the issue tracker, chat and issue channels, long-form docs, and error tracking. A feature with a long bug tail keeps most of its story there, so don't reconstruct it from your transcripts alone. -Transcripts live in Devin's session store: `devin list` names the sessions for the current directory, and session data lives under `~/Library/Application Support/Devin/` on macOS (`%APPDATA%\devin` on Windows) — per-session message stores under `User/`, ordered by real modification time. +`devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. 1. Classify, then route. One specific prior chat to resume is the `session-pickup` playbook, not this. Turning habits into a durable skill is `automate-me`. A human-readable summary of your work is a different task. Recall loads working context across recent chats before you act. If the user already gave you a full state capsule (paths, branch, the change), use it and skip the mining. 2. Lock the scope before searching. Pin the window ("recent" is a real range, default the last 7 days), the topic if named, and the workspace (default the active one. Never read another project's transcripts without being asked). State the scope back. Never quietly turn "all" into "recent N". diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index b42c515..bb45793 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -12,12 +12,10 @@ Invoke when the user says "reflect" or "/pstack:reflect". Skip when the conversa ## 1. Locate the active transcript -Before fanning out, find this conversation's transcript in Devin's session store. `devin list --format json` names the sessions for the current directory and gives each one's `id`. The CLI stores transcripts at `~/.local/share/devin/cli/transcripts/.json` (Devin Desktop stores its own under `~/Library/Application Support/Devin/` on macOS, `%APPDATA%\devin` on Windows). Do not read another project's sessions — that crosses workspace boundaries and reads private chats from unrelated projects. +Before fanning out, find this conversation's transcript in Devin's session store. `devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. Do not read another project's sessions — that crosses workspace boundaries and reads private chats from unrelated projects. ```bash devin list --format json | jq -r '.[].id' -ls -t "$HOME/.local/share/devin/cli/transcripts"/*.json 2>/dev/null | head -10 -ls -t "$HOME/Library/Application Support/Devin"/User/**/*.jsonl "$HOME/Library/Application Support/Devin"/User/acp-messages/*.db 2>/dev/null | head -10 ``` Prefer the CLI transcript whose `id` matches this session. Otherwise order candidates by real modification time and take the one whose opening user prompt matches this conversation. If none matches or the store is unreadable, pass a tight digest of the session instead. diff --git a/skills/show-me-your-work/SKILL.md b/skills/show-me-your-work/SKILL.md index e8a18e6..a471f94 100644 --- a/skills/show-me-your-work/SKILL.md +++ b/skills/show-me-your-work/SKILL.md @@ -54,7 +54,7 @@ Commit it only when the work is ambitious enough that a reviewer needs the trail ## Audit the log against the transcript -At the end of the run, before handing back, check the log told the truth. Read this run's transcript in Devin's session store: `devin list` names this directory's sessions and `~/Library/Application Support/Devin/` on macOS (`%APPDATA%\devin` on Windows) holds the per-session data. Don't read unrelated projects' sessions. That reads private chats. Walk this run's rows against what actually happened. Each stretch of them begins at one of this run's `start` rows, or at the first row if this run created the log, and ends at the next `start` row of another run: +At the end of the run, before handing back, check the log told the truth. Read this run's transcript in Devin's session store. `devin list --format json` names this directory's sessions. The CLI stores them in `~/.local/share/devin/cli/sessions.db` (`$XDG_DATA_HOME` or `DEVIN_SESSIONS_DIR` when set; `%APPDATA%\devin\cli\` on Windows). Don't read other directories' sessions. Don't read unrelated projects' sessions. That reads private chats. Walk this run's rows against what actually happened. Each stretch of them begins at one of this run's `start` rows, or at the first row if this run created the log, and ends at the next `start` row of another run: - Check that every row maps to a real decision or action. - Check that each row's evidence resolves and shows what the row claims. diff --git a/skills/typescript-best-practices/SKILL.md b/skills/typescript-best-practices/SKILL.md index 211a691..5611965 100644 --- a/skills/typescript-best-practices/SKILL.md +++ b/skills/typescript-best-practices/SKILL.md @@ -1,7 +1,7 @@ --- name: typescript-best-practices description: TypeScript best practices. Use when reading or editing any .ts or .tsx file. -triggers: [user, model] +triggers: [user] --- # TypeScript best practices