Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .factory-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pstack",
"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.",
"version": "0.15.36",
"version": "0.15.42",
"author": {
"name": "Lauren Tan"
},
Expand Down
6 changes: 3 additions & 3 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ These are the platform behaviors that drive every rule below. Recheck them when

| Cursor | Droid |
| :-- | :-- |
| Per-spawn model and reasoning level on Task | Seat droids. `poteto-agent` is the code seat (`grok-4.7`, `xhigh`). `poteto-judgment` is the judgment seat (`claude-opus-5-5`, `xhigh`). Each has a read-only twin with `tools: read-only` |
| Per-spawn model and reasoning level on Task | Seat droids. `poteto-agent` is the code seat (`claude-opus-5-5`, `xhigh`). `poteto-judgment` is the judgment seat (`claude-fable-5-2`, `max`). Each has a read-only twin with `tools: read-only` |
| `readonly: true` | `tools: read-only`, only on a droid that never writes |
| `readonly: false` | Omit `tools`. A droid that edits files, such as `comment-sicko`, must not be read-only |
| `is_background: true` | Drop it. Every Task runs in the background |
Expand All @@ -47,10 +47,10 @@ These are the platform behaviors that drive every rule below. Recheck them when
| Cursor | Droid |
| :-- | :-- |
| `run_in_background: true` on a spawn | Drop the field. Spawn parallel work in one message |
| A subagent that spawns its own subagents (sub-coordinators, a subagent that runs `/how` or `/no-comments`) | Every spawn stays in the chat that runs the playbook. A skill that a delegate may run needs an in-subagent path that does the work inline. `no-comments` reads `droids/comment-sicko.md` and runs the pass itself. `show-me-your-work` leaves its cross-model review to the parent. `comment-sicko` traces a claim itself instead of running `/how` or `/why`. The orchestrate sub-coordinator is dropped |
| A subagent that spawns its own subagents (sub-coordinators, a subagent that runs `/how` or `/no-comments`) | Every spawn stays in the chat that runs the playbook. A skill that a delegate may run needs an in-subagent path that does the work inline. `no-comments` reads `droids/comment-sicko.md` and runs the pass itself. `show-me-your-work` leaves its cross-model review to the parent. `comment-sicko` traces a claim itself instead of running `/how`, and it may run `/why` inline because that skill does not spawn. The orchestrate sub-coordinator is dropped |
| Cloud agents | Background subagents, each in its own git worktree |

Skills that spawn subagents, and so must run in the main chat: `how`, `why`, `teach`, `recall`, `arena`, `architect`, `swarm`, `interrogate`, `reflect`. `no-comments` and `show-me-your-work` also spawn, and each has an in-subagent path.
Skills that spawn subagents, and so must run in the main chat: `how`, `teach`, `recall`, `arena`, `architect`, `swarm`, `interrogate`, `reflect`. `no-comments` and `show-me-your-work` also spawn, and each has an in-subagent path. `why` does not spawn.

### Skills

Expand Down
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# pstack

Droid port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) (`0.15.36`) by [Lauren Tan (poteto)](https://x.com/poteto).
Droid port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) (`0.15.42`) by [Lauren Tan (poteto)](https://x.com/poteto).

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.

Expand Down Expand Up @@ -42,7 +42,7 @@ two steps:

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, 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. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.
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), prose, and judgment go to opus 5.5, while the hardest changes go to fable 5.2. the default panel is fable 5.2 / opus 5.5. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.

## usage

Expand Down Expand Up @@ -111,7 +111,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, start e

## 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`, `unslop`, `no-comments`, `technical-writing`, `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 (`why`, `architect`, `arena`, `swarm`, `interrogate`, `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?
Expand All @@ -129,9 +129,9 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, start e
| [`/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`. |
| [`/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 `/in-your-own-words`. |
| [`/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 `/sharpen`. |
| [`/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, which asks the agent to prototype any choice an experiment can settle and leaves product and preference choices to you. doesn't do the task. runs only when you type `/sharpen`. |
| [`/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). |
| [`/why`](./skills/why/SKILL.md) | you want to know why something was built this way. answers from the record, not the code: the commits and pr discussions that introduced it and each later change, and other sources when that trail is thin. cites what the authors wrote, marks its own inferences, and says what the record does not answer. |
| [`/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. |
| [`/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. |
| [`/ketchup-video`](./skills/ketchup-video/SKILL.md) | you want the `/ketchup` catch-up as a short subtitled video of slides, with the calls waiting on you as text under it. |
Expand Down Expand Up @@ -278,7 +278,7 @@ type [`/automate-me`](./skills/automate-me/SKILL.md). it mines your recent trans

models are configurable too. type [`/setup-pstack`](./skills/setup-pstack/SKILL.md). it detects the models you have access to and writes the pstack-models section into `~/.factory/AGENTS.md`, mapping each role (code, judgment, the review panels) to a model. every skill reads it and falls back to sensible defaults when the section 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 section, then run `/setup-pstack` again. a rerun keeps any role whose model differs from the default.
when a default changes, a rule written before the change still pins the old default until you run `/setup-pstack` again. that run replaces the old defaults it recognizes and keeps any other role whose model differs from the default. to drop a pin it does not recognize, delete that role's line or the section first.

## automations

Expand Down
4 changes: 2 additions & 2 deletions automations/benny/FOR_AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ i want two automations that work together in one slack issue channel.
- 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 `.factory/automations/benny/` in the target repository. its `SKILL.md` files are direct automation instructions, not registered plugin skills.
- i want pstack enabled in the target repository with `droid plugin install pstack@droid-pstack --scope project` only for shared dependencies such as `how`, `why`, `tdd`, `unslop`, and the required principle skills.
- i want pstack enabled in the target repository with `droid plugin install pstack@droid-pstack --scope project` only for shared dependencies such as `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 `.factory/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.
Expand Down Expand Up @@ -72,7 +72,7 @@ droid plugin install pstack@droid-pstack --scope project

this preserves every unrelated setting and plugin.

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. do not count skills loaded from the current session or a user-scoped install.
i want verification from a fresh agent rooted in the target repository. confirm that pstack's `why`, `tdd`, `unslop`, and the principle skills used by benny resolve in project scope. do not count skills loaded from the current session or a user-scoped install.

if project-scoped plugins are unavailable or any shared dependency does not resolve, stop and explain what failed. do not add `.factory/automations/benny/skills/` to a plugin manifest or expect its files to appear in the slash-skill list.

Expand Down
2 changes: 1 addition & 1 deletion automations/benny/skills/reproduce-and-fix-issues/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ Collect:

Inspect screenshots and video. Use read-only parallel workers for code history, test ideas, blast-radius mapping, and media review when useful. Each worker gets a narrow question and the Slack-write prohibition.

Use pstack's `how` skill to trace the action through the repository. Use `why` for regression history and defensive code. Form competing cause hypotheses and identify evidence that would separate them.
Trace the action through the repository. Use pstack's `why` skill for regression history and defensive code. Form competing cause hypotheses and identify evidence that would separate them.

## 7. Reproduce

Expand Down
1 change: 0 additions & 1 deletion automations/benny/skills/setup-benny/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,6 @@ This preserves every unrelated setting and plugin entry.

Reload the target project or start a fresh agent rooted there. Verify that these shared pstack skills resolve from project scope:

- `how`
- `why`
- `tdd`
- `unslop`
Expand Down
2 changes: 1 addition & 1 deletion automations/benny/skills/triage-issue-reports/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Use evidence already in the thread before asking the reporter for more.

## 3. Trace cause before routing

Do a bounded source and history pass before choosing an owner or destination. Use pstack's `how` skill to trace the path from the reported action to the observed result. Use `why` when the report looks like a regression or touches defensive code.
Do a bounded source and history pass before choosing an owner or destination. Trace the path from the reported action to the observed result. Use pstack's `why` skill when the report looks like a regression or touches defensive code.

1. Identify the likely code path from the reported action to the observed result.
2. Check whether the visible symptom belongs to that code path or a dependency below it.
Expand Down
4 changes: 2 additions & 2 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,9 +21,9 @@ Run:

[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes the pstack-models section into `~/.factory/AGENTS.md`, a small rule every pstack skill reads.

The defaults run at `xhigh` effort, the same as the `large` budget. `unlimited` lifts each model to its highest effort, up to `max`. Opus goes to `max`. Grok tops out at `xhigh`, so it stays there. `medium` and `small` lower the effort and spend fewer tokens.
The defaults are the same as the `large` budget. The code seat runs at `xhigh` effort and the judgment seat runs at `max`. `unlimited` raises each seat one level, up to `max`. `medium` lowers each seat one level and `small` lowers it two, and both spend fewer tokens.

You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default, so delete those role lines, or delete the section, then run `/setup-pstack` again.
You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default until you run `/setup-pstack` again. That run replaces the old defaults it recognizes, tells you which, and keeps your other choices. To drop a pin it does not recognize, delete that role's line or the section first.

You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and that role spawns the built-in `worker` droid, which inherits the parent chat model. Both values mean the same thing, and neither is a model ID. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm.

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/02-poteto-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ When you're unsure whether a prompt is aimed right, run [`/sharpen`](../../skill
/sharpen write a migration guide for the v2 config format.
```

The agent says what a top professional would do that you didn't ask for, the rawest material they would start from, the methods and tools they would use, and what other than you or the agent would show the result is right. Then it rewrites your prompt to ask for exactly that, deeper but not bigger, and leaves your choices open. It doesn't do the task. Read the rewrite, then send it, for example with `/poteto-mode`.
The agent says what a top professional would do that you didn't ask for, the rawest material they would start from, the methods and tools they would use, and what other than you or the agent would show the result is right. Then it rewrites your prompt to ask for exactly that, deeper but not bigger. The rewrite asks the agent to prototype any choice an experiment can settle and to recommend an option from what it observed, and it leaves product and preference choices to you. It doesn't do the task. Read the rewrite, then send it, for example with `/poteto-mode`.

## Follow up short

Expand Down Expand Up @@ -132,7 +132,7 @@ When you step away, say what done means and go:

Work you'll review later routes through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.

**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
**Pitfall:** don't enumerate skills in your prompt ("use /architect, then /arena, then /interrogate..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.

Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.

Expand Down
Loading
Loading