From 8337bc7081ed62c4ac1731366e4d50e973a7bdac Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:05:17 -0700 Subject: [PATCH 1/9] pstack: lead the README with the two-step quickstart --- pstack/.cursor-plugin/plugin.json | 2 +- pstack/README.md | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json index 6606378..2963ea1 100644 --- a/pstack/.cursor-plugin/plugin.json +++ b/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.10.4", + "version": "0.10.5", "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/README.md b/pstack/README.md index 9d07e5e..4f7b887 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -18,6 +18,15 @@ fork it. improve it. make it yours. PRs are welcome! /add-plugin pstack ``` +## get started + +two steps: + +1. run `/setup-pstack` and choose which models you want. +2. use `/poteto-mode` whenever you're doing anything that requires rigor. + +that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. `/setup-pstack` changes any of it. + ## make it yours `poteto-mode` is my style. you may not want exactly that. @@ -74,7 +83,7 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. ## skills -the rest are useful when you want to specifically invoke them: +`/poteto-mode` runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly: | skill | use it when | |---|---| From dbc286a210272ddbe60fdec396cca7239cb2a5cc Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:07:31 -0700 Subject: [PATCH 2/9] Keep version at 0.10.4; README-only change --- pstack/.cursor-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json index 2963ea1..6606378 100644 --- a/pstack/.cursor-plugin/plugin.json +++ b/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.10.5", + "version": "0.10.4", "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" From 24fee049e3abbd617d6402ce4ec657d3016ff22d Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:09:01 -0700 Subject: [PATCH 3/9] README: no version bump, reorder for first-time readers, collapse long blocks make-it-yours and automations move below the reference sections; the sixteen-playbook table and the examples block collapse behind
so the top of the page is install -> get started -> usage. --- pstack/README.md | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 4f7b887..b14d6df 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -27,20 +27,6 @@ two steps: that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. `/setup-pstack` changes any of it. -## make it yours - -`poteto-mode` is my style. you may not want exactly that. - -type `/automate-me`. 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 `/setup-pstack`. 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. - -## 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 cursor at [`FOR_AGENTS.md`](./automations/benny/FOR_AGENTS.md). setup copies the pack into the target repository at `.cursor/automations/benny/`, enables pstack there for shared skills, and keeps user configuration outside the copied pack. - ## usage use `/poteto-mode` 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. @@ -49,6 +35,9 @@ use `/poteto-mode` at the start of a task. it reads your request, picks from a s this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with sixteen playbooks: +
+the sixteen playbooks + | playbook | for | |---|---| | investigation | a read-only question. how does x work, why was y built this way, are we sure. | @@ -68,6 +57,8 @@ this skill is the main shortcut. i use it whenever i need the agent to do rigoro | pause safely | suspend in-flight work cleanly so it can be resumed later. | | multi-phase plan | work that spans phases or stacked PRs. | +
+ when invoked it: 1. opens a todo list. the first item is reading the inline principles index in the skill. @@ -108,6 +99,9 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. mostly i type `/poteto-mode` 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. +
+example invocations + ``` bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro first, then fix and verify. @@ -140,6 +134,8 @@ show-me-your-work: /show-me-your-work keep a decision trail i can review when i' automate-me: /automate-me ``` +
+ ## the `poteto-agent` subagent pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via `subagent_type: "poteto-agent"`. it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts. @@ -170,6 +166,20 @@ install `cursor-team-kit` alongside pstack if you want the full set. cursor 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, `/poteto-mode` covers it, but it's not a default. +## make it yours + +`poteto-mode` is my style. you may not want exactly that. + +type `/automate-me`. 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 `/setup-pstack`. 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. + +## 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 cursor at [`FOR_AGENTS.md`](./automations/benny/FOR_AGENTS.md). setup copies the pack into the target repository at `.cursor/automations/benny/`, enables pstack there for shared skills, and keeps user configuration outside the copied pack. + ## license MIT From 0f17ac1945ecdc22313fb62dea0bdac9d8b2027f Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:11:43 -0700 Subject: [PATCH 4/9] README: collapse the skills table too, keep four examples visible --- pstack/README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/pstack/README.md b/pstack/README.md index b14d6df..99052d4 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -76,6 +76,9 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. `/poteto-mode` runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly: +
+all skills + | skill | use it when | |---|---| | `/poteto-mode` | default entry point for any non-trivial task. | @@ -95,12 +98,23 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. | `/show-me-your-work` | you want a reviewable decision trail. logs decisions to a tsv you can commit. | | `/unslop` | you're cleaning up writing. removes AI tells. | +
+ ### examples mostly i type `/poteto-mode` 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. +``` +bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even + when idle. repro first, then fix and verify. +overnight run: /poteto-mode i'm going to bed. land the stack even if ci flakes. i want + everything merged by morning. +how: /how do we cancel runs? do we have an n+1 when we look up every run to cancel? +interrogate: /interrogate review this pr. +``` +
-example invocations +all the examples ``` bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even From dd465d457d9d9db5dd6e3ff93d6be3af48f94003 Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:15:06 -0700 Subject: [PATCH 5/9] README: link every skill, playbook, and principle to its file; split examples by section --- pstack/README.md | 100 +++++++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 47 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 99052d4..11c927f 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -40,25 +40,33 @@ this skill is the main shortcut. i use it whenever i need the agent to do rigoro | playbook | for | |---|---| -| investigation | a read-only question. how does x work, why was y built this way, are we sure. | -| bug fix | reproduce a defect, root-cause it, and fix with runtime evidence. | -| perf | trace a measured slowness and improve it against a baseline. | -| hillclimb | sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win. | -| runtime forensics | diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation. | -| trace forensics | diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot). | -| feature | new or changed behavior, built from a named data shape. | -| refactoring | a behavior-preserving change to structure or shape. | -| prototype | a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it. | -| visual parity | pixel-exact ui equivalence between two implementations. | -| authoring a skill | writing or editing a SKILL.md. | -| eval | test how a skill or prompt change affects agent behavior, blinded. | -| autonomous run | drive a long task to completion without stopping. | -| session pickup | resume or take over a prior agent's in-flight work. | -| pause safely | suspend in-flight work cleanly so it can be resumed later. | -| multi-phase plan | work that spans phases or stacked PRs. | +| [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. | +| [autonomous run](./skills/poteto-mode/playbooks/autonomous-run.md) | drive a long task to completion without stopping. | +| [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. |
+``` +bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even + when idle. repro first, then fix and verify. +overnight run: /poteto-mode i'm going to bed. land the stack even if ci flakes. i want + everything merged by morning. +``` + + when invoked it: 1. opens a todo list. the first item is reading the inline principles index in the skill. @@ -81,38 +89,36 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. | skill | use it when | |---|---| -| `/poteto-mode` | default entry point for any non-trivial task. | -| `/how` | you want a walkthrough of how a subsystem works. | -| `/why` | 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). | -| `/recall` | 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. | -| `/blast-radius` | 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. | -| `/architect` | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. | -| `/arena` | you want N parallel attempts at the same thing, then to grab the best parts of each. | -| `/interrogate` | you have a diff and want several different models to try to break it, including a strict code-quality lens. | -| `/automate-me` | you want your own `-mode` skill, drafted from how you've actually worked. | -| `/setup-pstack` | you want to pick which models pstack uses per role. detects your models and writes a config rule. | -| `/reflect` | a long task landed and you want the recipe captured as a skill edit. | -| `/tdd` | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. | -| `/typescript-best-practices` | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. | -| `/figure-it-out` | no bundled playbook fits. designs a rigorous, auditable playbook for the task. | -| `/show-me-your-work` | you want a reviewable decision trail. logs decisions to a tsv you can commit. | -| `/unslop` | you're cleaning up writing. removes AI tells. | +| [`/poteto-mode`](./skills/poteto-mode/SKILL.md) | default entry point for any non-trivial task. | +| [`/how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. | +| [`/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). | +| [`/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. | +| [`/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. | +| [`/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. | +| [`/arena`](./skills/arena/SKILL.md) | you want N parallel attempts at the same thing, then to grab the best parts of each. | +| [`/interrogate`](./skills/interrogate/SKILL.md) | you have a diff and want several different models to try to break it, including a strict code-quality lens. | +| [`/automate-me`](./skills/automate-me/SKILL.md) | you want your own `-mode` skill, drafted from how you've actually worked. | +| [`/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. | +| [`/reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. | +| [`/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. | +| [`/typescript-best-practices`](./skills/typescript-best-practices/SKILL.md) | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. | +| [`/figure-it-out`](./skills/figure-it-out/SKILL.md) | no bundled playbook fits. designs a rigorous, auditable playbook for the task. | +| [`/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. | +| [`/unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. |
-### examples - -mostly i type `/poteto-mode` 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. - ``` -bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even - when idle. repro first, then fix and verify. -overnight run: /poteto-mode i'm going to bed. land the stack even if ci flakes. i want - everything merged by morning. how: /how do we cancel runs? do we have an n+1 when we look up every run to cancel? interrogate: /interrogate review this pr. ``` + +### examples + +mostly i type `/poteto-mode` 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 @@ -152,19 +158,19 @@ automate-me: /automate-me ## the `poteto-agent` subagent -pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via `subagent_type: "poteto-agent"`. it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts. +pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md). it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts. -`/poteto-mode` and `subagent_type: "poteto-agent"` route through the same wrapper. +`/poteto-mode` and [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper. ## principles twenty-one 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. -- core: laziness-protocol, foundational-thinking, redesign-from-first-principles, subtract-before-you-add, minimize-reader-load, outcome-oriented-execution, experience-first, exhaust-the-design-space, build-the-lever. -- architecture: model-the-domain, boundary-discipline, type-system-discipline, make-operations-idempotent, migrate-callers-then-delete-legacy-apis, separate-before-serializing-shared-state. -- verification: prove-it-works, fix-root-causes, sequence-verifiable-units. -- delegation: guard-the-context-window, never-block-on-the-human. -- meta: encode-lessons-in-structure. +- core: [laziness-protocol](./skills/principle-laziness-protocol/SKILL.md), [foundational-thinking](./skills/principle-foundational-thinking/SKILL.md), [redesign-from-first-principles](./skills/principle-redesign-from-first-principles/SKILL.md), [subtract-before-you-add](./skills/principle-subtract-before-you-add/SKILL.md), [minimize-reader-load](./skills/principle-minimize-reader-load/SKILL.md), [outcome-oriented-execution](./skills/principle-outcome-oriented-execution/SKILL.md), [experience-first](./skills/principle-experience-first/SKILL.md), [exhaust-the-design-space](./skills/principle-exhaust-the-design-space/SKILL.md), [build-the-lever](./skills/principle-build-the-lever/SKILL.md). +- architecture: [model-the-domain](./skills/principle-model-the-domain/SKILL.md), [boundary-discipline](./skills/principle-boundary-discipline/SKILL.md), [type-system-discipline](./skills/principle-type-system-discipline/SKILL.md), [make-operations-idempotent](./skills/principle-make-operations-idempotent/SKILL.md), [migrate-callers-then-delete-legacy-apis](./skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md), [separate-before-serializing-shared-state](./skills/principle-separate-before-serializing-shared-state/SKILL.md). +- verification: [prove-it-works](./skills/principle-prove-it-works/SKILL.md), [fix-root-causes](./skills/principle-fix-root-causes/SKILL.md), [sequence-verifiable-units](./skills/principle-sequence-verifiable-units/SKILL.md). +- delegation: [guard-the-context-window](./skills/principle-guard-the-context-window/SKILL.md), [never-block-on-the-human](./skills/principle-never-block-on-the-human/SKILL.md). +- meta: [encode-lessons-in-structure](./skills/principle-encode-lessons-in-structure/SKILL.md). ## not shipped here From 358cb75dd44ec9d86efc236334586b0fcc784a5f Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:16:24 -0700 Subject: [PATCH 6/9] README: visible examples are bare copy-paste prompts --- pstack/README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 11c927f..527e10d 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -60,10 +60,11 @@ this skill is the main shortcut. i use it whenever i need the agent to do rigoro
``` -bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even - when idle. repro first, then fix and verify. -overnight run: /poteto-mode i'm going to bed. land the stack even if ci flakes. i want - everything merged by morning. +/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro first, then fix and verify. +``` + +``` +/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by morning. ``` @@ -109,8 +110,11 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. ``` -how: /how do we cancel runs? do we have an n+1 when we look up every run to cancel? -interrogate: /interrogate review this pr. +/how do we cancel runs? do we have an n+1 when we look up every run to cancel? +``` + +``` +/interrogate review this pr. ``` From 5c8fa91bfec748e2580e7825d6c3f056db2bd9bb Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:17:39 -0700 Subject: [PATCH 7/9] README: link every prose skill mention and the playbooks dir --- pstack/README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 527e10d..83e7681 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -22,16 +22,16 @@ fork it. improve it. make it yours. PRs are welcome! two steps: -1. run `/setup-pstack` and choose which models you want. -2. use `/poteto-mode` whenever you're doing anything that requires rigor. +1. run [`/setup-pstack`](./skills/setup-pstack/SKILL.md) and choose which models you want. +2. use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) whenever you're doing anything that requires rigor. -that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. `/setup-pstack` changes any of it. +that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it. ## usage -use `/poteto-mode` 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. +use [`/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. -### just use `/poteto-mode` +### just use [`/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 sixteen playbooks: @@ -71,19 +71,19 @@ this skill is the main shortcut. i use it whenever i need the agent to do rigoro when invoked it: 1. opens a todo list. the first item is reading the inline principles index in the skill. -2. matches your task to a playbook and copies the steps in verbatim. +2. matches your task to a [playbook](./skills/poteto-mode/playbooks/) and copies the steps in verbatim. 3. routes to the other skills as the steps fire. 4. writes unslopped replies framed for the consumer and the maintainer. -the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. +the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/poteto-mode/SKILL.md). -`/poteto-mode` is also a sticky mode: once entered it stays on across turns, applying itself when a playbook matches or the task needs rigor and staying out of the way otherwise. opt out any time by saying so. +[`/poteto-mode`](./skills/poteto-mode/SKILL.md) is also a sticky mode: once entered it stays on across turns, applying itself when a playbook matches or the task needs rigor and staying out of the way otherwise. opt out any time by saying so. -`/poteto-mode` works extremely well with cursor's `/loop` command. you can make cursor work for many hours without sacrificing rigor. +[`/poteto-mode`](./skills/poteto-mode/SKILL.md) works extremely well with cursor's `/loop` command. you can make cursor work for many hours without sacrificing rigor. ## skills -`/poteto-mode` runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly: +[`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly:
all skills @@ -120,7 +120,7 @@ the full rules and playbooks live in `skills/poteto-mode/SKILL.md`. ### examples -mostly i type `/poteto-mode` 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. +mostly i type [`/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.
@@ -164,7 +164,7 @@ automate-me: /automate-me pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md). it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts. -`/poteto-mode` and [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper. +[`/poteto-mode`](./skills/poteto-mode/SKILL.md) and [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper. ## principles @@ -188,15 +188,15 @@ install `cursor-team-kit` alongside pstack if you want the full set. ## why are there no planning skills? -cursor 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, `/poteto-mode` covers it, but it's not a default. +cursor 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, [`/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 `/automate-me`. 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`. +type [`/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 `/setup-pstack`. 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. +models are configurable too. type [`/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. ## automations From cebd664a8911b55a9b24738546a0fbec57a9067b Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:18:30 -0700 Subject: [PATCH 8/9] README: visible example prompts wrap at 100 chars and lead their sections --- pstack/README.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 83e7681..4f533b1 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -35,6 +35,16 @@ use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) at the start of a task. it r this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with sixteen playbooks: +``` +/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro +first, then fix and verify. +``` + +``` +/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by +morning. +``` +
the sixteen playbooks @@ -59,13 +69,6 @@ this skill is the main shortcut. i use it whenever i need the agent to do rigoro
-``` -/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro first, then fix and verify. -``` - -``` -/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by morning. -``` when invoked it: @@ -85,6 +88,14 @@ the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/po [`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly: +``` +/how do we cancel runs? do we have an n+1 when we look up every run to cancel? +``` + +``` +/interrogate review this pr. +``` +
all skills @@ -109,13 +120,6 @@ the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/po
-``` -/how do we cancel runs? do we have an n+1 when we look up every run to cancel? -``` - -``` -/interrogate review this pr. -``` ### examples From a4c98038b7c7585d2924501c35818910be79face Mon Sep 17 00:00:00 2001 From: lauren Date: Sat, 11 Jul 2026 16:20:26 -0700 Subject: [PATCH 9/9] README: principles as a collapsible table --- pstack/README.md | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/pstack/README.md b/pstack/README.md index 4f533b1..434c837 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -174,11 +174,34 @@ pstack also ships a subagent that runs my style end to end. spawn it from a pare twenty-one 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. -- core: [laziness-protocol](./skills/principle-laziness-protocol/SKILL.md), [foundational-thinking](./skills/principle-foundational-thinking/SKILL.md), [redesign-from-first-principles](./skills/principle-redesign-from-first-principles/SKILL.md), [subtract-before-you-add](./skills/principle-subtract-before-you-add/SKILL.md), [minimize-reader-load](./skills/principle-minimize-reader-load/SKILL.md), [outcome-oriented-execution](./skills/principle-outcome-oriented-execution/SKILL.md), [experience-first](./skills/principle-experience-first/SKILL.md), [exhaust-the-design-space](./skills/principle-exhaust-the-design-space/SKILL.md), [build-the-lever](./skills/principle-build-the-lever/SKILL.md). -- architecture: [model-the-domain](./skills/principle-model-the-domain/SKILL.md), [boundary-discipline](./skills/principle-boundary-discipline/SKILL.md), [type-system-discipline](./skills/principle-type-system-discipline/SKILL.md), [make-operations-idempotent](./skills/principle-make-operations-idempotent/SKILL.md), [migrate-callers-then-delete-legacy-apis](./skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md), [separate-before-serializing-shared-state](./skills/principle-separate-before-serializing-shared-state/SKILL.md). -- verification: [prove-it-works](./skills/principle-prove-it-works/SKILL.md), [fix-root-causes](./skills/principle-fix-root-causes/SKILL.md), [sequence-verifiable-units](./skills/principle-sequence-verifiable-units/SKILL.md). -- delegation: [guard-the-context-window](./skills/principle-guard-the-context-window/SKILL.md), [never-block-on-the-human](./skills/principle-never-block-on-the-human/SKILL.md). -- meta: [encode-lessons-in-structure](./skills/principle-encode-lessons-in-structure/SKILL.md). +
+all twenty-one 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. | +| [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, refuse to lie to the compiler, 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 to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes. | +| [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. | +| [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