@jiroamato/pstack 0.0.0-stage → 0.16.0

package/pstack/README.md

@@ -0,0 +1,307 @@
+# pstack
+
+> this is a port of [poteto's pstack](https://github.com/cursor/plugins/tree/main/pstack) from cursor to claude code and codex, maintained by [jiroamato](https://github.com/jiroamato). the skills, playbooks, and principles are poteto's, kept as close to upstream as the harnesses allow. the [`pstack-harness`](./skills/pstack-harness/SKILL.md) adapter, the manifests, the agent definitions, and `/setup-pstack` are the port's. upstream version: 0.15.15.
+
+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.
+
+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. 
+
+**pstack is my answer.** these are the same skills i use everyday to ship high quality code at Cursor. this turns your agent harness 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.
+
+**use the models your harness gives you.** every frontier model has its strengths and weaknesses. many of the skills run multi-model panels to take advantage of each model's unique strengths. on claude code the panels mix opus and sonnet. on codex they mix gpt-6-astra and gpt-6-luna. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.
+
+fork it. improve it. make it yours. PRs are welcome! 
+
+## install
+
+pstack installs as a plugin on claude code and on codex, or copies into a skills directory with npx. same skills, same playbooks, same principles.
+
+the quick way, from a shell:
+
+```bash
+npx @jiroamato/pstack
+```
+
+it asks which agent and whether to install into this project or your home directory, then copies the skills and agents there. re-run it to update, `npx @jiroamato/pstack uninstall` to remove. skills keep their bare names, so type `/poteto-mode` on claude code.
+
+or as a plugin, which the tool updates for you. claude code, from a shell:
+
+```bash
+claude plugin marketplace add jiroamato/pstack
+claude plugin install pstack@pstack-plugins
+```
+
+codex, from a shell:
+
+```bash
+codex plugin marketplace add jiroamato/pstack
+codex plugin add pstack
+```
+
+start a new session afterwards. on claude code the plugin's skills are namespaced, so type `/pstack:poteto-mode` (plain `/poteto-mode` after an npx install). on codex type `$poteto-mode`. this readme writes `/poteto-mode` for both.
+
+## get started
+
+two steps:
+
+1. run [`/setup-pstack`](./skills/setup-pstack/SKILL.md), pick a reasoning budget, and choose which models you want.
+2. use [`/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 [`/poteto-help`](./skills/poteto-help/SKILL.md).
+
+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: code delegates (feature, refactoring, bug fix, perf, hillclimb) go to the code tier (sonnet on claude code, gpt-6-luna on codex), while the hardest changes, prose, and judgment go to the judgment tier (opus on claude code, gpt-6-astra on codex). the default panel is one of each. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.
+
+## usage
+
+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`](./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:
+
+```
+/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.
+```
+
+<details>
+<summary>the twenty-three playbooks</summary>
+
+| 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 and a root swarm verdict on each round, from the code-ready head on. |
+| [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. |
+
+</details>
+
+
+
+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 [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, follow the harness **keep the mode on** row in [`pstack-harness`](./skills/pstack-harness/SKILL.md). on claude code, start the session as the agent with `claude --agent pstack:poteto-agent`, or add one line to your `CLAUDE.md`: "Apply the pstack:poteto-mode skill to any non-trivial task." on codex, add the same line with `$poteto-mode` to `AGENTS.md`. it then applies itself when a playbook matches or the task needs rigor, and stays out of the way otherwise. say so to opt out.
+
+[`/poteto-mode`](./skills/poteto-mode/SKILL.md) works extremely well with claude code's `/loop` command. on codex, the autonomous run playbook polls or spawns a monitor agent instead (the harness **loop** row). either way you can make the agent work for many hours without sacrificing rigor.
+
+## skills
+
+[`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `deslop`, `control-cli`, `control-ui`, `unslop`, `no-comments`, `technical-writing`, `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.
+```
+
+<details>
+<summary>all skills</summary>
+
+| skill | use it when |
+|---|---|
+| [`/poteto-mode`](./skills/poteto-mode/SKILL.md) | default entry point for any non-trivial task. |
+| [`/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 `/poteto-help`. |
+| [`/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. |
+| [`/swarm`](./skills/swarm/SKILL.md) | you want N parallel workers across different slices or races, then one aggregated report. |
+| [`/interrogate`](./skills/interrogate/SKILL.md) | you have a diff and want 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. |
+| [`/make-bot-ui`](./skills/make-bot-ui/SKILL.md) | you want a page or dashboard whose buttons wake a bot: a claude code session over a channel, claude code with the reply on telegram, or a chatgpt dot through slack. covers the secret handoff and tailscale. |
+| [`pstack-harness`](./skills/pstack-harness/SKILL.md) | the port's adapter. maps every cursor primitive the skills name (subagents, models, transcripts, loops, custom modes) onto claude code and codex. the skills read it. you rarely invoke it. |
+| [`/setup-pstack`](./skills/setup-pstack/SKILL.md) | you want to pick which models pstack uses per role. detects your models and writes `~/.pstack/models.md`. on codex it also installs the two pstack agents. |
+| [`/reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. |
+| [`/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. |
+| [`/kiss`](./skills/kiss/SKILL.md) | you want to know how agent-friendly a repo is. assesses it against the principles behind dune (one writer per value, discovery over registries, forbidden imports fail mechanically), writes `.kiss/assessment.md` with what to improve, in what order, and what to leave alone, then lands the findings one pr at a time through `correct` and the refactoring playbook. |
+| [`/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. |
+| [`/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. |
+| [`/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. |
+| [`/no-comments`](./skills/no-comments/SKILL.md) | strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints. |
+| [`/deslop`](./skills/deslop/SKILL.md) | clean AI-generated code slop out of the branch and working diff before commit. preserves behavior and the surrounding code style. |
+| [`/control-cli`](./skills/control-cli/SKILL.md) | drive and profile a real CLI or TUI, verify prompts and keyboard flows, and capture terminal evidence with an available local driver. |
+| [`/control-ui`](./skills/control-ui/SKILL.md) | drive a web, IDE, or Electron UI, assert the result, and capture screenshots, snapshots, or profiles with an available browser driver. |
+| [`/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. |
+| [`/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. |
+| [`/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. |
+| [`/unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. |
+| [`/bro`](./skills/bro/SKILL.md) | you want the last message restated in plain human language, no jargon. |
+| [`/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. |
+
+</details>
+
+
+
+### examples
+
+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.
+
+
+<details>
+<summary>all the examples</summary>
+
+```
+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.
+perf:              /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:           /poteto-mode build a small feature behind a feature flag. verify it really works.
+prototype:         /poteto-mode build two prototypes of the markdown renderer so we can compare.
+                   spawn an agent for each.
+multi-phase:       /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:     /poteto-mode i'm going to bed. land the stack even if ci flakes. i want
+                   everything merged by morning.
+babysit:           /poteto-mode check on pr 123. anything outstanding?
+visual parity:     /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:     /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:               /how do we cancel runs? do we have an n+1 when we look up every run to cancel?
+why:               /why is this feature flag not on yet?
+architect:         design this instrumentation to be high signal with no false positives. /architect
+                   this first.
+arena:             /arena take my prompt to the arena verbatim. i want to compare their proposals
+                   with yours.
+swarm:             /swarm check every package under packages/ against its check.sh. one worker per
+                   package. one report.
+interrogate:       /interrogate review this pr.
+tdd:               /tdd implement
+unslop:            can we unslop and tighten the new changes?
+reflect:           /reflect that took too long. capture what we learned so the next run doesn't
+                   repeat it.
+correct:           /correct
+show-me-your-work: /show-me-your-work keep a decision trail i can review when i'm back.
+automate-me:       /automate-me
+help:              /poteto-help which skill should i use to review this branch?
+```
+
+</details>
+
+## the `poteto-agent` and Comment Sicko subagents
+
+pstack also ships a subagent that runs my style end to end. spawn it from a parent agent as [`pstack:poteto-agent`](./agents/poteto-agent.md) on claude code, or as `poteto-agent` on codex once [`/setup-pstack`](./skills/setup-pstack/SKILL.md) has installed [`codex/agents/poteto-agent.toml`](./codex/agents/poteto-agent.toml) into `~/.codex/agents/`. it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `general-purpose` skips that read and drifts.
+
+[`/poteto-mode`](./skills/poteto-mode/SKILL.md) and [`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 `pstack:comment-sicko` on claude code and `comment-sicko` on codex. usually invoke it through [`/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.
+
+<details>
+<summary>all twenty-four principles</summary>
+
+| 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. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing 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, 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. |
+| [test-behavior-not-implementation](./skills/principle-test-behavior-not-implementation/SKILL.md) | verification | Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test. |
+| [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. |
+
+</details>
+
+## bundled from cursor-team-kit
+
+[`/deslop`](./skills/deslop/SKILL.md), [`/control-cli`](./skills/control-cli/SKILL.md), and [`/control-ui`](./skills/control-ui/SKILL.md) are adapted from [cursor-team-kit](https://github.com/cursor/plugins/tree/main/cursor-team-kit) and included in this plugin. no separate team-kit installation is needed. on claude code, invoke `/pstack:deslop`, `/pstack:control-cli`, or `/pstack:control-ui`; on codex, use `$deslop`, `$control-cli`, or `$control-ui`.
+
+`poteto-mode` and the relevant standalone skills explicitly load them: `deslop` for kept code, `control-ui` for web/IDE/Electron, and `control-cli` for CLI/TUI. there is no separate `control` skill. a project's `verify-<app>` skill supplies app-specific commands, selectors, and feature coverage alongside the bundled driver. the drivers use terminal and browser tools already available in the session; installing pstack does not install those tools.
+
+## kiss
+
+[`/kiss`](./skills/kiss/SKILL.md) is the port's own addition, not from upstream. it is an assessment skill built on the principles behind dune, the framework lauren tan built so agents could ship thousands of prs a month to grok bot: a correct open-file edit should preserve the whole app's invariants. `assess` reads a repo and writes `.kiss/assessment.md`: the repo's shape as a noun table, what is already right, what to improve in the order it will be landed, and what to leave alone and why. `apply` lands the findings one pr at a time, gate first.
+
+kiss adds no machinery of its own. it links the pstack skills as siblings: `how` and `why` while assessing, `correct` for a repeated mistake class, the refactoring and opening a pr playbooks for each change, `create-verification-skill` for a repo with no scripted way to prove itself. its ladder is numbered the way `correct` numbers its levels, so a finding and a fix name the same number. on claude code, invoke `/pstack:kiss`; on codex, `$kiss`.
+
+## harness differences
+
+a few things upstream `poteto-mode` leaned on were cursor-only. the [`pstack-harness`](./skills/pstack-harness/SKILL.md) skill says what the port does instead:
+
+- `/create-skill` becomes `skill-creator`, which both harnesses ship (the **skill-creator** row).
+- `/loop` is a claude code built-in. codex gets a polling loop or a monitor agent (the **loop** row).
+- `/make-bot-ui` lost its cursor grok bot webhook. it now wakes a claude code session over a channel, claude code with the reply on telegram, or a chatgpt dot through slack (the **channels** row).
+- `environment: "cloud"` subagents have no counterpart and were dropped. parallel workers isolate in git worktrees instead (the **isolation** row).
+
+## why are there no planning skills?
+
+claude code 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`](./skills/automate-me/SKILL.md). it mines your recent transcripts, drafts a `<your-name>-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`](./skills/setup-pstack/SKILL.md). it detects the models you have access to and writes `~/.pstack/models.md`, a small file mapping each role (code, judgment, the review panels) to a model, with one section per harness. every skill reads it and falls back to sensible defaults when the file is absent, so you override only what you want.
+
+when a default changes, a file written before the change still pins the old default. delete those role lines, or delete the file, then run `/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. the pack was written for cursor automations. the port keeps its instructions and points the trigger wiring at claude code scheduled tasks or codex automations, so expect to adapt the trigger step to your setup.
+
+to set it up, point your agent at [`FOR_AGENTS.md`](./automations/benny/FOR_AGENTS.md). setup copies the pack into the target repository at `.pstack/automations/benny/`, enables pstack there for shared skills, and keeps user configuration outside the copied pack.
+
+## license
+
+MIT. the pstack skills are copyright Lauren Tan (poteto), from [cursor/plugins](https://github.com/cursor/plugins). the three team-kit skills are copyright Cursor. the port keeps both licenses; see [NOTICE](./NOTICE) and [LICENSE-cursor-team-kit](./LICENSE-cursor-team-kit).

package/pstack/agents/comment-sicko.md

@@ -0,0 +1,34 @@
+---
+name: comment-sicko
+description: Comment Sicko. A deranged comment-hater that savors deletion and condemns workaround code. Read-only. Spawn it from the no-comments skill with the scope (files or a diff). Reports deletions and MUST KILL flags, never edits code.
+model: inherit
+tools: Read, Glob, Grep, Bash
+---
+
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/pstack/agents/poteto-agent.md

@@ -0,0 +1,10 @@
+---
+name: poteto-agent
+description: Routing target for the poteto-mode skill and any request for poteto's style. Spawn a fresh poteto-agent for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the poteto-mode skill's SKILL.md in full before any work, including its inline Principles index. Substituting general-purpose skips that read and drifts.
+model: inherit
+background: true
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. It lives at `${CLAUDE_PLUGIN_ROOT}/skills/poteto-mode/SKILL.md`. Navigate to a leaf `principle-*` skill whenever you apply that principle. Read `${CLAUDE_PLUGIN_ROOT}/skills/pstack-harness/SKILL.md` before your first spawn, model choice, or structured question.

package/pstack/automations/benny/FOR_AGENTS.md

@@ -0,0 +1,92 @@
+# benny automation intent
+
+## what i want to automate
+
+i want two automations (claude code scheduled tasks, or codex automations) that work together in one slack issue channel.
+
+### automation 1: triage issue reports
+
+- trigger: when someone posts a new top-level report in my configured source slack channel, i want this automation to start on that report and keep its original thread coordinates.
+- behavior: i want it to read the thread and attachments, classify the report as a bug or performance issue, feature request, question or feedback, or reroute, and trace the likely owning layer before routing.
+- tracker: i want it to search my configured tracker for duplicates, update a confident duplicate, and create a ticket only for a clear net-new bug.
+- tools: i want slack thread read and reply access, my configured tracker integration, and my optional routing map.
+- outcome: i want exactly one reply in the source thread with a short verdict and `[benny:bug]`, `[benny:performance]`, or `[benny:other]`. a bug or performance marker may include the tracker url.
+- boundary: i never want this automation to post a root message in the source channel.
+
+### automation 2: reproduce and fix confirmed bugs
+
+- trigger: i want this automation to start from the same new top-level report, or another supported trigger chosen during setup, then wait for the trusted triage marker in the original thread.
+- gates: i want it to stop when someone clearly owns the fix. if an existing pull request or merged commit may fix the report, i want verification instead of a competing change.
+- behavior: i want it to use my configured control adapter and feature map, reproduce the exact symptom twice through the real ui, and capture screenshots, video, and a read-only state cross-check.
+- fix: i want it to verify existing pull requests without authoring over them. after a confirmed repro, it may attempt one bounded root-cause fix, use tdd when the test is cheap, smoke the blast radius, and open a draft pull request only when before-and-after proof passes.
+- tools: i want slack thread read and reply access, repository and history access, draft pull request creation, my configured tracker, and my control adapter.
+- outcome: i want evidence and a verified result in the source or optional operations threads, plus an optional draft pull request. updates should be concise.
+- boundary: i never want this automation to post a root message in the source channel.
+
+### shared rules
+
+- i want the source channel and root thread coordinates to stay immutable for the whole run.
+- i treat utility and debug bots as evidence, not delegation or fix ownership.
+- i allow subagents to help, but they cannot post to slack or receive slack credentials.
+- i want this entire pack committed at `.pstack/automations/benny/` in the target repository. its `SKILL.md` files are direct automation instructions, not registered plugin skills.
+- i want pstack enabled for the target repository (claude code: committed `.claude/settings.json`; codex: a user-scope install) only for shared dependencies such as `how`, `why`, `tdd`, `unslop`, and the required principle skills.
+- i want each live automation prompt to read its committed operational file directly. i do not want plugin cache paths, copied excerpts, or slash-skill discovery.
+- i keep user-owned configuration, feature maps, routing maps, and secrets outside `.pstack/automations/benny/` so pack refreshes cannot overwrite them.
+- i want both automations to fail closed when channel coordinates, tracker access, the control adapter, or the feature map are missing or uncertain.
+- i want draft pull requests only. do not merge or deploy.
+
+### my configuration
+
+- source slack channel: `<channel>`
+- optional operations channel: `<channel or none>`
+- repository and default branch: `<repo>`, `<branch>`
+- tracker: `<type, team, project, labels, intake status>`
+- routing map: `<path or none>`
+- triage identity: `<slack identity>`
+- app-specific verification skill/adapter: `<configured skill using pstack control-ui for web/IDE/Electron>`
+- feature map: `<committed same-repo path outside the copied pack, or behavior to paraphrase>`
+- models: `<triage, reproduce, code, media review>`
+- status emoji strings: `<seen, reproducing, reproduced, blocked, fixing, failed, pull request opened>`
+- budgets: `<polling, verdict wait, follow-up, repro, rejection, fix>`
+- optional bot token capability: `<none, file download, or editable operations status>`
+
+start from [`configuration.example.yaml`](./templates/configuration.example.yaml) and [`feature-map.example.md`](./skills/reproduce-and-fix-issues/references/feature-map.example.md). copy and fill them outside this pack, for example under `.pstack/benny/`. keep secret values in a secret manager or environment.
+
+## for the agent
+
+the human enters setup by pointing their agent at this file. do not look for or invoke a discovered benny slash skill.
+
+1. ask which repository will run the automations.
+2. treat the directory containing this `FOR_AGENTS.md` as the source pack.
+3. merge the entire source pack into `<target-repository>/.pstack/automations/benny/`.
+4. preserve every destination-only file. never delete unrelated files or overwrite user-owned configuration, feature maps, or routing maps.
+5. when an existing destination file at a source-managed path differs, review the diff and merge without discarding local edits. if ownership is ambiguous, stop and ask before replacing it.
+6. verify that the copied `FOR_AGENTS.md` and `skills/setup-benny/SKILL.md` exist in the target repository.
+7. read and follow `.pstack/automations/benny/skills/setup-benny/SKILL.md` directly from the target repository.
+
+on claude code, i want you to merge this into the target repository's `.claude/settings.json`:
+
+```json
+{
+	"extraKnownMarketplaces": {
+		"pstack-plugins": {
+			"source": { "source": "github", "repo": "jiroamato/pstack" }
+		}
+	},
+	"enabledPlugins": { "pstack@pstack-plugins": true }
+}
+```
+
+preserve every unrelated setting and plugin. on codex, plugins are user-scoped, so install pstack for the user who runs the automations with `codex plugin marketplace add jiroamato/pstack` and `codex plugin add pstack`.
+
+i want verification from a fresh agent rooted in the target repository. confirm that pstack's `how`, `why`, `tdd`, `unslop`, and the principle skills used by benny resolve in project scope. on claude code, do not count skills loaded from the current session or a user-scoped install. on codex, confirm the automation's user has pstack installed.
+
+if project-scoped plugins are unavailable or any shared dependency does not resolve, stop and explain what failed. do not add `.pstack/automations/benny/skills/` to a plugin manifest or expect its files to appear in the slash-skill list.
+
+tell me that the pstack settings (`.claude/settings.json` on claude code), `.pstack/automations/benny/`, and any referenced secret-free configuration must be committed before either automation is enabled. do not create or update an automation until i explicitly ask.
+
+for first-time creation, use your harness's automation creator (the `schedule` skill on claude code, the automations editor in the codex app) once for triage and once for repro and fix. complete the draft review, approval, readiness check, and editor handoff for the first automation before starting the second.
+
+paraphrase this intent and the finished configuration into each draft. the triage prompt must read and follow `.pstack/automations/benny/skills/triage-issue-reports/SKILL.md`. the repro prompt must read and follow `.pstack/automations/benny/skills/reproduce-and-fix-issues/SKILL.md`. use these repo-relative paths only after the automation creator confirms they are committed in the repository where the automation will run.
+
+for existing automations, do not use the automation creator to inspect or update them. validate the configuration, then use the concise field checklist in the copied setup file so i can edit each automation directly in its editor. do not create duplicates.

package/pstack/automations/benny/README.md

@@ -0,0 +1,28 @@
+# benny
+
+benny gives you two automations (claude code scheduled tasks, or codex automations) for slack issue reports. one triages each report. the other reproduces confirmed bugs and may prepare a small draft fix.
+
+the files in this directory are dormant setup and automation sources. they do not appear as slash skills.
+
+## set it up
+
+1. point your agent at [`FOR_AGENTS.md`](./FOR_AGENTS.md) and name the target repository.
+2. let setup merge this whole directory into the target at `.pstack/automations/benny/`. it must preserve destination-only files and review conflicts instead of overwriting local edits.
+3. let setup enable pstack for the target repository for shared dependencies. on claude code that is `.claude/settings.json`:
+
+```json
+{
+	"extraKnownMarketplaces": {
+		"pstack-plugins": {
+			"source": { "source": "github", "repo": "jiroamato/pstack" }
+		}
+	},
+	"enabledPlugins": { "pstack@pstack-plugins": true }
+}
+```
+
+   on codex, install pstack for the user who runs the automations (`codex plugin marketplace add jiroamato/pstack`, then `codex plugin add pstack`).
+
+4. keep user-owned configuration outside the copied pack, for example in `.pstack/benny/`. adapt [`configuration.example.yaml`](./templates/configuration.example.yaml) and [`feature-map.example.md`](./skills/reproduce-and-fix-issues/references/feature-map.example.md).
+5. commit the pstack settings (`.claude/settings.json` on claude code), `.pstack/automations/benny/`, and any secret-free configuration before enabling either automation.
+6. review each new automation draft or update existing automations in their editors. then send a harmless test report and verify every source-channel post stays in the original thread.