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
9 changes: 8 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -249,14 +249,21 @@ jobs:
if (!indexedPrinciples.has(p)) fail(`skills/${p} is not indexed in skills/poteto-mode/SKILL.md`);
}

const diskPlaybooks = new Set(readdirSync("skills/poteto-mode/playbooks").filter((f) => f.endsWith(".md")));
const indexedPlaybooks = new Set();
for (const line of playbooksSection.split(/\r?\n/)) {
const m = line.match(/^- \*\*([^*]+?)\.\*\*(?:.*?File: `playbooks\/([^`]+)`)?/);
if (m) {
indexedPlaybooks.add(m[2] ?? `${toKebab(m[1])}.md`);
continue;
}
const trimmed = line.trim().replace(/\.$/, "");
if (!trimmed.includes(", ") || trimmed.includes("`")) continue;
const names = trimmed.split(",").map((part) => `${toKebab(part.trim())}.md`);
if (names.length > 1 && names.every((name) => diskPlaybooks.has(name))) {
for (const name of names) indexedPlaybooks.add(name);
}
}
const diskPlaybooks = new Set(readdirSync("skills/poteto-mode/playbooks").filter((f) => f.endsWith(".md")));
for (const pb of indexedPlaybooks) {
if (!diskPlaybooks.has(pb)) fail(`skills/poteto-mode/SKILL.md references missing playbook "playbooks/${pb}"`);
}
Expand Down
11 changes: 5 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Grok Build port of [pstack](https://github.com/cursor/plugins/tree/bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7/pstack) (`0.15.42`) by [Lauren Tan (poteto)](https://x.com/poteto).
Grok Build port of [pstack](https://github.com/cursor/plugins/tree/2f87c854fe3e2fcda44ca86b46ede35aad3c46b7/pstack) (`0.15.43`) by [Lauren Tan (poteto)](https://x.com/poteto).

# pstack

Expand Down Expand Up @@ -37,7 +37,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 every role defaults to `grok-4.6` at `xhigh`. the default panel is `grok-4.6 xhigh` / `grok-4.5 high`. [`/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 every role defaults to `grok-4.6` at `xhigh`, and no role runs above `xhigh`. the default panel is `grok-4.6 xhigh` / `grok-4.5 high`. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.

## usage

Expand All @@ -47,7 +47,7 @@ type `/poteto-mode` and the task in one message.

### 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 @@ -60,7 +60,7 @@ morning.
```

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

| playbook | for |
|---|---|
Expand All @@ -79,7 +79,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 Expand Up @@ -269,7 +268,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 a small always-applied rule mapping each role (code, judgment, the review panels) to a model. every skill reads it and falls back to sensible defaults when the rule is absent, so you override only what you want.

when a default changes, a rule written before the change still pins the old default until you run `/setup-pstack` again. that run drops retired roles it recognizes, such as `how explorer` and `why investigators`, and keeps any other role whose model differs from the default, including every `grok-*` slug. to drop a pin it does not recognize, delete that role's line or the file first.
when a default changes, a rule written before the change still pins the old default until you run `/setup-pstack` again. that run drops retired roles it recognizes, such as `how explorer`, `why investigators`, `hardest tasks`, `architect runners`, `reflect tooling`, and `reflect judgment, divergent, synthesizer`, and keeps any other role whose model differs from the default, including every `grok-*` slug. to drop a pin it does not recognize, delete that role's line or the file first.

## automations

Expand Down
1 change: 1 addition & 0 deletions agents/poteto-agent.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
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. Omitting `subagent_type` skips that read and drifts. Do not call `spawn_subagent`. Only the parent chat can spawn.
model: grok-4.6
---

# Poteto subagent
Expand Down
6 changes: 3 additions & 3 deletions docs/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,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 `~/.grok/rules/pstack-models.md`, a small rule every pstack skill reads.

The defaults are the same as the `large` budget. Most roles run at `xhigh` reasoning. A panel's second entry runs at `high`. `unlimited` raises each entry one level, up to `max`. If the model does not offer that effort, it stays at its highest offered effort at or below the target. `medium` lowers each entry one level and `small` lowers it two, and both spend fewer tokens. Effort is a separate field, written after the model id (`grok-4.6 xhigh`). If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent.
The defaults are the same as the `large` budget. Every role runs on `grok-4.6` at `xhigh`. The default panel is `grok-4.6 xhigh` / `grok-4.5 high`. No role runs above `xhigh`. `medium` lowers each entry one level and `small` lowers it two, and both spend fewer tokens. Effort is a separate field, written after the model id (`grok-4.6 xhigh`). If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent.

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 drops retired roles it recognizes, such as `how explorer` and `why investigators`, tells you which, and keeps your other choices, including every `grok-*` slug. To drop a pin it does not recognize, delete that role's line or the file first.
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 drops retired roles it recognizes, such as `how explorer`, `why investigators`, `hardest tasks`, `architect runners`, `reflect tooling`, and `reflect judgment, divergent, synthesizer`, tells you which, and keeps your other choices, including every `grok-*` slug. To drop a pin it does not recognize, delete that role's line or the file first.

You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. 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 Expand Up @@ -62,7 +62,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. Type `/poteto-mode` at the start of each task. The skill has `disable-model-invocation: true`, so it stays off until you invoke it. There is no custom mode to pin.

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` is bundled in this plugin. If it is missing, 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` is bundled in this plugin. If it is missing, 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