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 pstack/.cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pstack",
"displayName": "pstack",
"version": "0.11.5",
"version": "0.11.6",
"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
2 changes: 1 addition & 1 deletion pstack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ two steps:
1. run [`/setup-pstack`](./skills/setup-pstack/SKILL.md) and choose which models you want.
2. use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) whenever you're doing anything that requires rigor.

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: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.
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: precisely-specified code goes to sol, fast mechanical code goes to grok, and prose and judgment go to fable. the default panel is fable / sol / grok. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.

## usage

Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst

Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt. Each candidate produces a design package shaped per `references/rationale-template.md`: the caller's usage written first, then the type sketch, function signatures, module map, and prose rationale derived from it.

Use your configured `architect runners`. The routed **how** and **arena** skills resolve model values per `~/.cursor/rules/pstack-models.mdc`, including omitting Task `model` for `inherit-parent`/`auto`. If the role line is absent, use defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`.
Use your configured `architect runners`. The routed **how** and **arena** skills resolve model values per `~/.cursor/rules/pstack-models.mdc`, including omitting Task `model` for `inherit-parent`/`auto`. If the role line is absent, use defaults `claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.5-fast-xhigh`.

This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.

Expand Down
4 changes: 2 additions & 2 deletions pstack/skills/arena/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The N candidates will receive the same prompt, so the prompt is the contract. Ge

1. State the artifact each candidate is producing.
2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. Concrete: `Adds a --dry-run flag that skips writes`. Vague: `code is correct`. The rubric is the picker's tool in Phase D; candidates only see the task.
3. Pick the runners. Resolve each entry in your configured `arena runners` list per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, use defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`. If every entry is `inherit-parent`/`auto`, keep the same fan-out count and omit `model` for every runner. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
3. Pick the runners. Resolve each entry in your configured `arena runners` list per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, use defaults `claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.5-fast-xhigh`. If every entry is `inherit-parent`/`auto`, keep the same fan-out count and omit `model` for every runner. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
4. Assign output paths. Each candidate writes to its own location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`). N candidates writing to the same path is shared mutable state and fails the the **separate-before-serializing-shared-state** principle skill test.

## Phase B: Fan out
Expand All @@ -38,7 +38,7 @@ If a candidate fails to produce output, proceed with N-1 and note the dropout in

## Phase C: Cross-judge

After all Phase B candidates complete, choose one value from the configured `arena cross-judge pool` in `~/.cursor/rules/pstack-models.mdc`. If the role line is absent, choose from defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`. Prefer a model family different from the parent's when possible. Pass a selected real slug as Task `model`. For selected `inherit-parent`/`auto`, omit `model`. A pool containing only `inherit-parent`/`auto` cannot provide a different family; still spawn the judge with `model` omitted.
After all Phase B candidates complete, choose one value from the configured `arena cross-judge pool` in `~/.cursor/rules/pstack-models.mdc`. If the role line is absent, choose from defaults `claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.5-fast-xhigh`. Prefer a model family different from the parent's when possible. Pass a selected real slug as Task `model`. For selected `inherit-parent`/`auto`, omit `model`. A pool containing only `inherit-parent`/`auto` cannot provide a different family; still spawn the judge with `model` omitted.

Spawn one readonly judge subagent with the resolved value. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Spawning while candidates are still writing means the judge sees partial or empty outputs and reports them as dropouts.

Expand Down
8 changes: 4 additions & 4 deletions pstack/skills/how/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ The right decomposition depends on the question. Use your judgment. Narrow quest
Spawn all explorers in a single message:

- `subagent_type`: `generalPurpose`
- `model`: resolve the configured `how explorer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `grok-4.5-fast-xhigh`.
- `model`: resolve the configured `how explorer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `gpt-5.6-sol-max`.
- `readonly`: `true`

Each explorer gets the same base prompt from `references/explorer-prompt.md` plus a specific exploration angle naming its slice. Each explorer should:
Expand All @@ -64,7 +64,7 @@ Then proceed to Step 3.
Spawn a single Task subagent that explores and explains in one pass:

- `subagent_type`: `generalPurpose`
- `model`: resolve the configured `how explainer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `claude-opus-4-8-thinking-xhigh`.
- `model`: resolve the configured `how explainer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `claude-fable-5-thinking-max`.
- `readonly`: `true`

The agent does its own exploration (Glob, Grep, Read) and writes the explanation directly. Read `references/explainer-prompt.md` for the communication style and output format. Same structure, just no explorer findings as input.
Expand All @@ -76,7 +76,7 @@ Proceed to Step 4.
Once all explorers return, spawn a single Task subagent to synthesize their findings into one coherent explanation:

- `subagent_type`: `generalPurpose`
- `model`: resolve the configured `how explainer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `claude-opus-4-8-thinking-xhigh`.
- `model`: resolve the configured `how explainer` role per `~/.cursor/rules/pstack-models.mdc`. Pass a real slug as `model`. Omit `model` for `inherit-parent`/`auto`. If the role line is absent, default to `claude-fable-5-thinking-max`.
- `readonly`: `true`

The explainer gets all explorers' findings and writes the human-facing explanation (output format below). Read `references/explainer-prompt.md` for the full prompt template. The explainer reconciles overlapping findings, resolves contradictions, and weaves the slices into a unified picture.
Expand Down Expand Up @@ -109,7 +109,7 @@ Run the full explain flow above (Steps 1-4). You must understand the architectur

### Step 2. Spawn Critics

After the explanation is complete, spawn one architectural critic per entry in your configured `how critics` list, all in a single message. If the role line is absent, use defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`.
After the explanation is complete, spawn one architectural critic per entry in your configured `how critics` list, all in a single message. If the role line is absent, use defaults `claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.5-fast-xhigh`.

For each critic:
- `subagent_type`: `generalPurpose`
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/interrogate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Write one clear paragraph. Reviewers challenge whether the work achieves the int

## Step 3, Spawn Reviewers

Launch one reviewer per entry in your configured `interrogate reviewers` list, all in a single message. If the role line is absent, use defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`.
Launch one reviewer per entry in your configured `interrogate reviewers` list, all in a single message. If the role line is absent, use defaults `claude-fable-5-thinking-max`, `gpt-5.6-sol-max`, `grok-4.5-fast-xhigh`.

For each reviewer:
- `subagent_type`: `generalPurpose`
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Read the leaf skill in full for any principle you apply. Each entry names when i

**Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `poteto-agent` route through the same wrapper. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`) set their own `subagent_type` for diverse-model review; respect what the skill prescribes, don't override to `poteto-agent`.

**Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, and a per-role model from the `/setup-pstack` rule. Pass a real slug as `model`. For `inherit-parent`/`auto`, omit `model` so the subagent inherits the parent chat model. If a role line is absent, default to `grok-4.5-fast-xhigh` for code and `claude-opus-4-8-thinking-xhigh` for prose and judgment. Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`claude-fable-5-thinking-max`) when the task needs judgment or the intent is vague, and to your strongest instruction-following model when the work is a precisely specified sequence of steps to execute to the letter; trivial mechanical edits go to your fast code model. Per-role lines in the `/setup-pstack` rule override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `architect`, `interrogate`, `reflect`); a role with no line keeps its default.
**Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, and a per-role model from the `/setup-pstack` rule. Pass a real slug as `model`. For `inherit-parent`/`auto`, omit `model` so the subagent inherits the parent chat model. If a role line is absent, default to `grok-4.5-fast-xhigh` for code and `claude-fable-5-thinking-max` for prose and judgment. Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`claude-fable-5-thinking-max`) when the task needs judgment or the intent is vague, and to your strongest instruction-following model (`gpt-5.6-sol-max`) when the work is a precisely specified sequence of steps to execute to the letter; trivial mechanical edits go to your fast code model. Per-role lines in the `/setup-pstack` rule override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `architect`, `interrogate`, `reflect`); a role with no line keeps its default.

You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. A second opinion is the same prompt against a different model. Agreement is high-signal.

Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/playbooks/bug-fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspender

1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed.
2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with Cursor's `/loop` command. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out; a design grounded on a plausible-but-unconfirmed cause can be unanimously wrong while the real cause sits one subsystem over.
3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `gpt-5.5-high-fast`) with a specific scope; review the diff.
3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `gpt-5.6-sol-max`) with a specific scope; review the diff.
4. Verify on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence.
5. Stage the commits so the failing repro lands before the fix in git history; the diff tells the story. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear.
This is the canonical **sequence-verifiable-units** principle skill, the failing test first and the fix on top.
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/playbooks/hillclimb.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Core discipline: one change, one measurement, keep or revert. Never stack untest
3. Open the decision log via the **show-me-your-work** skill. A `decision.tsv`, one row per attempt: id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. This is the run's memory. Read it before each attempt so the search accumulates instead of circling. Keep it out of the tree (gitignored) so it survives reverts.
4. Ground each hypothesis in the architecture model from step 1, so it names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something".
5. Loop, one hypothesis per iteration:
- Hand the change to a subagent using your configured hillclimb model (default `gpt-5.5-high-fast`) with a tight scope; supervise and review the diff rather than typing it (the **guard-the-context-window** principle skill). When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree so they can't collide (the **separate-before-serializing-shared-state** principle skill).
- Hand the change to a subagent using your configured hillclimb model (default `gpt-5.6-sol-max`) with a tight scope; supervise and review the diff rather than typing it (the **guard-the-context-window** principle skill). When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree so they can't collide (the **separate-before-serializing-shared-state** principle skill).
- Measure before and after with the frozen harness, and run the regression gate.
- Accept only when the metric moves past noise and the gate stays green. Otherwise revert the change in full; a tweak that "might help" does not ride along.
- One commit per accepted fix, staging only the files you changed (`git add <files>`, never `-A`). Log the row either way, kept or reverted.
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/playbooks/perf-issue.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
- **Redundancy.** The wait hangs on one slow instance or attempt. Duplicate the work (replicas, hedged requests, speculative execution) and take the fastest result. This trades extra load for lower tail latency, so the trace has to show the wait dominates and the system has headroom; duplication without that tradeoff only adds load.
- **Lazy evaluation.** Cost lands on results that are never used or not needed yet (eager init on the boot path, rendering offscreen items). Defer the work until first use.
- **Scheduling.** The work must happen, but not during the interactive moment. Move it to where nobody is waiting: idle callbacks, a background warmup after boot, precompute before the user arrives, cleanup after the frame commits. Distinct from Lazy (later-when-needed): Scheduling often runs the work *earlier* than the hot moment, or in its shadow. The win is perceived latency, so measure the interactive path, not total work done.
3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (default `gpt-5.5-high-fast`); review the diff. Capture a post-fix trace.
3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (default `gpt-5.6-sol-max`); review the diff. Capture a post-fix trace.
Apply the **sequence-verifiable-units** principle skill, verifying each attempt before trying the next.
4. Parse and compare the artifacts (JSON to sqlite, diff). "Inconclusive" or wrong-surface is not a pass; flag it.
5. Cite the measurement in the PR.
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/references/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Resolve what is in scope vs explicitly out, technical or platform constraints, p
Delegate codebase exploration (the **guard-the-context-window** principle skill).

- Prefer `subagent_type: "poteto-agent"`. `generalPurpose` is the fallback. Never use the built-in `plan` subagent_type; it ignores this skill.
- Pass `model:` explicitly per the configured roles (defaults `grok-4.5-fast-xhigh` for code, `claude-opus-4-8-thinking-xhigh` for judgment).
- Pass `model:` explicitly per the configured roles (defaults `grok-4.5-fast-xhigh` for code, `claude-fable-5-thinking-max` for judgment).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plan exploration still defaults grok

Low Severity · Logic Bug

This PR moves parallel codebase exploration to gpt-5.6-sol-max via the how explorer role and the /setup-pstack template, but plan.md still tells multi-phase planning to pass grok-4.5-fast-xhigh for code explorers. Planning and how flows can spawn different models for the same exploration work.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 50393b3. Configure here.


Each explorer returns file pointers, conventions, dependencies, test infrastructure, and entry points. No inlined dumps.

Expand Down
Loading
Loading