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.42",
"version": "0.15.43",
"author": {
"name": "Lauren Tan"
},
Expand Down
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,14 @@ jobs:
const m = line.match(/^- \*\*([^*]+?)\.\*\*(?:.*?File: `playbooks\/([^`]+)`)?/);
if (m) {
indexedPlaybooks.add(m[2] ?? `${toKebab(m[1])}.md`);
continue;
}
// 0.15.43 lists the playbooks as one comma-separated sentence.
if (/,/.test(line) && /\.$/.test(line.trim()) && !line.includes("**")) {
for (const name of line.replace(/\.\s*$/, "").split(",")) {
const trimmed = name.trim();
if (trimmed) indexedPlaybooks.add(`${toKebab(trimmed)}.md`);
}
}
}
const diskPlaybooks = new Set(readdirSync("skills/poteto-mode/playbooks").filter((f) => f.endsWith(".md")));
Expand Down
8 changes: 4 additions & 4 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 (`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` |
| Per-spawn model and reasoning level on Task | Seat droids. `poteto-agent` is the code seat (`claude-opus-5-5`, `xhigh`) for code, prose, and judgment. `poteto-judgment` is the Fable seat (`claude-fable-5-2`, `xhigh`), used when the user names Fable 5.2, after two failed Opus 5.5 xhigh runs, or on a panel. No seat runs above `xhigh`. 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`, and it may run `/why` inline because that skill does not spawn. The orchestrate sub-coordinator is dropped |
| A subagent that spawns its own subagents (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. `architect` sketches both shapes itself when a subagent runs it, because `arena` spawns |
| Cloud agents | Background subagents, each in its own git worktree |

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 that spawn subagents, and so must run in the main chat: `how`, `teach`, `recall`, `arena`, `architect`, `swarm`, `interrogate`. `no-comments` and `show-me-your-work` also spawn, and each has an in-subagent path. `why` and `reflect` do not spawn. `architect` stays on this list because a large or contested design runs `arena`.

### Skills

Expand All @@ -60,7 +60,7 @@ Skills that spawn subagents, and so must run in the main chat: `how`, `teach`, `
| `paths: [...]` glob activation | Drop `paths`. Remove `disable-model-invocation` and let the description route the skill (`typescript-best-practices`) |
| `icon`, `color` | Kept for parity with upstream. Droid ignores them |
| A skill loaded by the model by name | Skills with `disable-model-invocation: true` are read by path. `poteto-mode` reads `../<name>/SKILL.md`. Seat droids find `poteto-mode` in `~/.factory/plugins/` |
| cursor-team-kit `deslop`, `control-cli`, `control-ui` | Bundled in `skills/` |
| `deslop`, `control-cli`, `control-ui` | Bundled in `skills/` |
| Cursor `create-skill` skill | The `authoring-a-skill` playbook. Droid's `/create-skill` is a user pane, not a skill an agent can call |

### Paths
Expand Down
9 changes: 4 additions & 5 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.42`) by [Lauren Tan (poteto)](https://x.com/poteto).
Droid port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) (`0.15.43`) 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), 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.
that's it. the other skills are situational, and the mode skill uses them for you as needed. out of the box, code delegates (feature, refactoring, bug fix, perf, hillclimb), prose, and judgment go to opus 5.5 at xhigh, and no role runs above xhigh. outside a review panel, fable 5.2 runs only when you name it or after two opus 5.5 runs of the same brief fail. the default panel is fable 5.2 / opus 5.5. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.

## usage

Expand All @@ -52,7 +52,7 @@ pick `/poteto-mode` from the `/` menu before you type your task, so droid attach

### 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:
this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with twenty-two playbooks:

```
/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro
Expand All @@ -65,7 +65,7 @@ morning.
```

<details>
<summary>the twenty-three playbooks</summary>
<summary>the twenty-two playbooks</summary>

| playbook | for |
|---|---|
Expand All @@ -84,7 +84,6 @@ morning.
| [babysit](./skills/poteto-mode/playbooks/babysit.md) | drive a pr or a stack to merge-ready: conflicts, review threads, ci. |
| [shipping](./skills/poteto-mode/playbooks/shipping.md) | independently verify a green stack, then land the contiguous verified run bottom-up through github by default or origin when available. |
| [autonomous run](./skills/poteto-mode/playbooks/autonomous-run.md) | drive a long task to completion without stopping. |
| [orchestrate](./skills/poteto-mode/playbooks/orchestrate.md) | a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents. |
| [autopilot-full](./skills/poteto-mode/playbooks/autopilot-full.md) | run independent prs to merged with one owner per pr. a swarm verifies each code-ready head, and every later change to the patch gets a fresh check. |
| [autopilot-stack](./skills/poteto-mode/playbooks/autopilot-stack.md) | autopilot-full without the merge. build and verify prs for the operator to review and land, stacking a pr only on a pr it builds on. |
| [session pickup](./skills/poteto-mode/playbooks/session-pickup.md) | resume or take over a prior agent's in-flight work. |
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,7 +21,7 @@ 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 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.
The defaults are the same as the `large` budget. Code, prose, and judgment run on the code seat, Opus 5.5 at `xhigh`. The judgment seat is Fable 5.2 at `xhigh`, and no seat runs above `xhigh`. Outside a review panel, Fable 5.2 runs only when you name it for a task or after two Opus 5.5 runs of the same brief fail their check. Review panels and swarm workers share those seats, so they run at the seat's `xhigh` rather than a separate `high`. `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 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.

Expand Down Expand Up @@ -56,7 +56,7 @@ Pick something real but small, and describe it the way you'd describe it to a co
/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
```

Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/poteto-mode` skips a step, the step stays in the list with `skip: <reason>`, so you can see what it chose not to do.
Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt.

From here you can type normal follow-ups. Droid attaches a skill to the message that names it, so start each new task with `/poteto-mode`.

Expand Down
6 changes: 3 additions & 3 deletions docs/guide/02-poteto-mode.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Route work through `/poteto-mode`

`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-three playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need.
`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-two playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need.

![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates, under a /poteto-mode departure board listing BUG FIX, FEATURE, and INVESTIGATION.](./images/router.jpg)

Expand All @@ -25,7 +25,7 @@ flowchart TD
J --> K
```

The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, opening a PR, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, opening a PR, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.

## Say the goal, not the ceremony

Expand All @@ -35,7 +35,7 @@ You don't write a spec. You say what's wrong or what you want, plus anything you
/poteto-mode users get two notifications after a retry. repro first, then fix and verify.
```

That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps. A skipped step stays visible with `skip: <reason>`.
That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps.

## What goes in a prompt

Expand Down
14 changes: 4 additions & 10 deletions docs/guide/04-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,9 @@ The two most common design mistakes are taking the agent's first design and poli
/architect design the import pipeline before writing any code. i care most about how callers use it.
```

[`/architect`](../../skills/architect/SKILL.md) grounds itself first, tracing the code the design touches and running `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.
[`/architect`](../../skills/architect/SKILL.md) traces every system the change touches first. Then it sketches two different shapes, each with types, signatures, and module boundaries, and picks the one where each piece of state has one owner, each task has one way to do it, and callers need to know least. For a large or contested design, it runs `/arena` instead of sketching alone. If you want to see the design before any code, say so in the prompt.

By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so:

```text
/architect with checkpoint. stop and show me before implementing.
```

The design isn't sacred once code starts. If implementation shows the same workaround in unrelated places, or types that only compile with `any` or forced casts, `/architect` treats that as proof the design is wrong. It scraps the sketch and starts over instead of patching around it.
The design isn't sacred once code starts. If the same workaround keeps coming back, `/architect` redesigns instead of patching around it.

## Fan out attempts with `/arena`

Expand Down Expand Up @@ -106,7 +100,7 @@ pstack has no planning skill, on purpose. When you do want a written plan, ask f
/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.
```

The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and it names which execution playbook should run it next.
The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and execution starts only when you say go.

For a migration, state the bar in the prompt:

Expand All @@ -121,7 +115,7 @@ For a migration, state the bar in the prompt:
You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder:

- A small, finished change you're unsure about needs `/interrogate` alone.
- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it.
- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it when the design is large or contested.
- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly.
- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`.
- An open question you could answer by running something, like a layout, a timing, or an approach, gets a prototype, not a debate.
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/05-build-and-clean.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ In context, that's enough. [`/tdd`](../../skills/tdd/SKILL.md) writes the smalle

## Clean before you commit

The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs `/deslop` on the diff before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in this plugin. If you don't have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs `/deslop` on the diff before each commit, and poteto-mode applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in this plugin. If you don't have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.

For prose, `/unslop` takes a target and any extra rules you have:

Expand Down
4 changes: 2 additions & 2 deletions docs/guide/06-verify-and-ship.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,7 @@ A counterexample in model terms convinces you. The PM or designer who owns the b
/poteto-mode open the pr. small ordered commits, evidence in the description.
```

The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Five narrow PRs beat one fat one, and stacked follow-ups beat a growing branch.
The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small landable commits, cleans the diff, writes a one-minute briefing as the body, and opens the PR ready. Stacked follow-ups beat a growing branch.

## Drive the PR to merge-ready with Babysit

Expand All @@ -141,7 +141,7 @@ An open PR starts collecting blockers immediately. Checks fail, reviewers commen
/poteto-mode babysit this pr. get it green.
```

Babysit watches the PR, with a bundled watcher on GitHub or the Origin CLI when it's available, and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop:
Babysit watches the PR, with a bundled watcher on GitHub or the Origin CLI when it's available, and takes blockers in order: conflicts, then review threads, then CI. It never rebases or force-pushes. A conflict or a stale base comes back to you with the branch that needs the rebase. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop:

```text
/poteto-mode check on pr 123. anything outstanding?
Expand Down
Loading
Loading