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 .qoder-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pstack",
"displayName": "pstack",
"version": "0.15.42",
"version": "0.15.43",
"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"
Expand Down
14 changes: 10 additions & 4 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Qoder compatibility

pstack 0.15.42 runs on Qoder. The core poteto-mode workflow is compatible. This file records what is verified, what needs setup, and what is out of scope.
pstack 0.15.43 runs on Qoder. The core poteto-mode workflow is compatible. This file records what is verified, what needs setup, and what is out of scope.

## Verified compatible

- The manifest `.qoder-plugin/plugin.json` and `marketplace.json` use the Qoder plugin format.
- Both agents, `poteto-agent` and `comment-sicko`, register and appear in the Agent tool list.
- The plugin ships 61 skills. Four are model-invocable: `control-cli`, `control-ui`, `deslop`, and `setup-pstack`. The other 57 set `disable-model-invocation: true`, so Qoder hides them from model invocation but keeps them slash-invocable and file-routable.
- The skills use Qoder tool names such as `Agent`, `TaskCreate`, and `Skill`. No Cursor tool name or `cursor-agent` CLI reference remains.
- The default models `Fast` and `Ultimate` are valid names in `qodercli --list-models`. Code, prose, and judgment default to `Ultimate xhigh`. The hardest tasks default to `Ultimate max`. Reflect tooling and swarm workers default to `Ultimate high`. Review panels default to `Ultimate high` and `Fast high`.
- The default models `Fast` and `Ultimate` are valid names in `qodercli --list-models`. Code, prose, and judgment default to `Ultimate xhigh`. Trivial mechanical edits and swarm workers default to `Ultimate high`. Review panels default to `Ultimate high` and `Fast high`. No role runs above `xhigh`.
- Every `subagent_type` reference points to a registered agent.

## Bugbot detection
Expand All @@ -19,8 +19,14 @@ Qoder's exact bugbot login and marker are unverified. Detection covers any host

## Model setup

Run `/setup-pstack` to write `~/.qoder/rules/pstack-models.md` and the model-pinning profiles under `~/.qoder/agents/`. The rule carries a `# defaults: 2` line. A rule without that line is from an older setup. On the next run, old default values take the new defaults: a `Fast` value at any effort in `feature, refactoring`, `bug-fix`, `perf-issue`, `hillclimb`, `reflect tooling`, or `swarm workers`; an `Ultimate` value in `hardest tasks`; and a panel list that is exactly one `Ultimate` entry and one `Fast` entry. Every other value stays as the user's choice. A line whose role is not in the current shape, including the retired roles `how explorer`, `how explainer`, `why investigators`, and `why synthesizer`, is dropped. Until you run setup, roles use the documented auto fallback: `Explore` for read-only work and `poteto-agent` for write work. The fallback works. The pinned-model path stays inactive until setup runs.
Run `/setup-pstack` to write `~/.qoder/rules/pstack-models.md` and the model-pinning profiles under `~/.qoder/agents/`. The rule carries a `# defaults: 3` line and a `# budget` line. Budgets are `large` (`xhigh`), `medium` (`high`), and `small` (`medium`). No role runs above `xhigh`.

A rule without the `# defaults: 3` line is from an older setup. On the next run, a line whose role is not in the current shape is dropped. That includes the retired roles `hardest tasks`, `architect runners`, `reflect tooling`, `reflect judgment, divergent, synthesizer`, `how explorer`, `why investigators`, and `why synthesizer`. A `# budget: unlimited` line becomes `large`, because no role runs above `xhigh`. An `arena cross-judge pool` that is exactly one `Ultimate` entry and one `Fast` entry takes the current default list. If the rule also has no `# defaults: 2` line, a `Fast` value at any effort in `feature, refactoring`, `bug-fix`, `perf-issue`, `hillclimb`, or `swarm workers` takes that role's default, and a panel list that is exactly one `Ultimate` entry and one `Fast` entry takes that role's default list. In any other list from that older rule, each `Fast` entry becomes `Ultimate high`. Every other value stays as the user's choice. Until you run setup, roles use the documented auto fallback: `Explore` for read-only work and `poteto-agent` for write work. The fallback works. The pinned-model path stays inactive until setup runs.

## Transcript layout

Qoder writes transcripts at `~/.qoder/projects/<slug>/<session-id>.jsonl`. Subagent transcripts sit under `~/.qoder/projects/<slug>/<session-id>/subagents/`. `<slug>` is qodercli 1.1.89 `Vf(cwd)`, the same function `join(configDir, "projects", Vf(cwd), sessionId + ".jsonl")` uses. The dash step runs on UTF-16 code units, the same units `charCodeAt` reads, so a non-BMP character becomes two dashes. Every code unit that is not an ASCII letter or digit becomes `-`, so `/home/me/my_proj` is `-home-me-my-proj`. When the dashed form is longer than 200 characters, the slug is the first 200 characters, a `-`, and the base-36 form of `Math.abs(t)`. Hash the original path, not the dashed string. `t` starts at `5381`. Each UTF-16 code unit updates it with `t = 33 * t ^ charCodeAt(i)`, and `^` is signed 32-bit. `Math.abs(-2147483648)` is `2147483648`.

## Out of scope

The benny Slack automations are not a compatibility target. Qoder has no surface that creates a Slack-triggered automation, so the pack stays dormant and unsupported. `automations/benny/FOR_AGENTS.md` records this limit.
The benny Slack automations are not a compatibility target. Qoder has no surface that creates a Slack-triggered automation, so the pack stays dormant and unsupported. `automations/benny/FOR_AGENTS.md` records this limit.
11 changes: 5 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# pstack

Qoder port of [pstack](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack) (`0.15.42`) by [Lauren Tan (poteto)](https://x.com/poteto).
Qoder port of [pstack](https://github.com/cursor/plugins/tree/2f87c854fe3e2fcda44ca86b46ede35aad3c46b7/pstack) (`0.15.43`) by [Lauren Tan (poteto)](https://x.com/poteto).

See the [upstream pstack README](https://github.com/cursor/plugins/blob/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack/README.md) and the [guide](./docs/guide/README.md) for usage and documentation.
See the [upstream pstack README](https://github.com/cursor/plugins/blob/2f87c854fe3e2fcda44ca86b46ede35aad3c46b7/pstack/README.md) and the [guide](./docs/guide/README.md) for usage and documentation.

i'm [poteto](https://x.com/poteto). i'm not a president or ceo, but i've worked with millions of lines of code at Meta, Netflix, and Cursor. i'm also on the react core team where i help build and maintain react compiler.

Expand Down Expand Up @@ -48,7 +48,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 the ultimate tier, while the hardest changes go to ultimate at max effort. the default panel is ultimate / fast. [`/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 ultimate at xhigh, and no role runs above xhigh. the default panel is ultimate / fast. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.

## usage

Expand All @@ -58,7 +58,7 @@ pick `/poteto-mode` from the `/` menu before you type your task, so qoder 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 @@ -71,7 +71,7 @@ morning.
```

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

| playbook | for |
|---|---|
Expand All @@ -90,7 +90,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
1 change: 0 additions & 1 deletion agents/comment-sicko.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
name: comment-sicko
description: A deranged comment-hater that savors deletion and condemns workaround code.
disallowedTools: [Edit, Write, NotebookEdit]
---

# Comment Sicko
Expand Down
2 changes: 2 additions & 0 deletions agents/poteto-agent.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
name: poteto-agent
description: Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run. Use for delegates, not as the runner for `/poteto-mode` itself. 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.
background: true
model: Ultimate
effort: xhigh
---

# Poteto subagent
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 @@ -25,7 +25,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 `~/.qoder/rules/pstack-models.md`, a small rule every pstack skill reads, plus the model-pinning agent profiles the roles spawn.

The defaults are the same as the `large` budget. Most roles run at `xhigh` reasoning. The hardest changes run at `max`, and the review panels and swarm workers run at `high`. `unlimited` raises each role one level, up to `max`. `medium` lowers each role 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 Ultimate at `xhigh` reasoning, and the review panels and swarm workers run at `high`. No role runs above `xhigh`. The default panel is Ultimate and Fast. `medium` lowers each role 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 file first.

Expand Down Expand Up @@ -60,7 +60,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. `/poteto-mode` attaches the skill to one message, and it fades as the chat moves on, 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`](../../skills/deslop/SKILL.md) on the diff before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies.
The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs [`/deslop`](../../skills/deslop/SKILL.md) on the diff before each commit, and poteto-mode applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies.

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

Expand Down
Loading
Loading