Skip to content
Open
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.3",
"version": "0.11.4",
"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/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 (defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`).
Use your configured architect runners (defaults `claude-opus-4-8-thinking-high`, `gpt-5.5-high-fast`, `grok-4.5-fast-high`).

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

Expand Down
2 changes: 1 addition & 1 deletion 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. Default runners are your configured arena list (defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`). 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. Default runners are your configured arena list (defaults `claude-opus-4-8-thinking-high`, `gpt-5.5-high-fast`, `grok-4.5-fast-high`). 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 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`: your configured how-explorer model (default `grok-4.5-fast-xhigh`)
- `model`: your configured how-explorer model (default `grok-4.5-fast-high`)
- `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`: your configured how-explainer model (default `claude-opus-4-8-thinking-xhigh`)
- `model`: your configured how-explainer model (default `claude-opus-4-8-thinking-high`)
- `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`: your configured how-explainer model (default `claude-opus-4-8-thinking-xhigh`)
- `model`: your configured how-explainer model (default `claude-opus-4-8-thinking-high`)
- `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 model in your configured how-critics list (defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`), all in a single message.
After the explanation is complete, spawn one architectural critic per model in your configured how-critics list (defaults `claude-opus-4-8-thinking-high`, `gpt-5.5-high-fast`, `grok-4.5-fast-high`), all in a single message.

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 model in your configured interrogate list (defaults `claude-opus-4-8-thinking-xhigh`, `gpt-5.5-high-fast`, `grok-4.5-fast-xhigh`), all in a single message.
Launch one reviewer per model in your configured interrogate list (defaults `claude-opus-4-8-thinking-high`, `gpt-5.5-high-fast`, `grok-4.5-fast-high`), all in a single message.

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, explicit model per role (configurable via `/setup-pstack`; defaults `grok-4.5-fast-xhigh` for code, `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, explicit model per role (configurable via `/setup-pstack`; defaults `grok-4.5-fast-high` for code, `claude-opus-4-8-thinking-high` 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.

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/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
- **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize.
- **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants.
- **Smallest safe decomposition.** If one worker is best, name why.
4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally.
4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.5-fast-high`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally.
5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it.
6. Rebase into small, ordered commits; stack follow-ups.
Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next.
Expand Down
2 changes: 1 addition & 1 deletion pstack/skills/poteto-mode/playbooks/refactoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ A refactor that smuggles in a behavior change loses its safety net. If the clean
2. Name the structure the code is missing per **principle-model-the-domain**: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection.
3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move.
4. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted, not left to ride.
5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself.
5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `grok-4.5-fast-high`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself.
6. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary.
7. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it.
8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a 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-high` for code, `claude-opus-4-8-thinking-high` for judgment).

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

Expand Down
8 changes: 4 additions & 4 deletions pstack/skills/reflect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,15 @@ One message, three `Task` calls, `subagent_type: generalPurpose`, explicit `mode

| Lens | `model` | Prompt template |
|---|---|---|
| Judgment | your configured reflect-judgment model (default `claude-opus-4-8-thinking-xhigh`) | `references/judgment-reviewer.md` |
| Tooling | your configured reflect-tooling model (default `grok-4.5-fast-xhigh`) | `references/tooling-reviewer.md` |
| Divergent | your configured reflect-judgment model (default `claude-opus-4-8-thinking-xhigh`) | `references/divergent-reviewer.md` |
| Judgment | your configured reflect-judgment model (default `claude-opus-4-8-thinking-high`) | `references/judgment-reviewer.md` |
| Tooling | your configured reflect-tooling model (default `grok-4.5-fast-high`) | `references/tooling-reviewer.md` |
| Divergent | your configured reflect-judgment model (default `claude-opus-4-8-thinking-high`) | `references/divergent-reviewer.md` |

Pass each template verbatim, substituting the transcript path or digest where marked. Reviewers return findings in the `Task` response body.

### 3. Synthesize

One `Task` call, `subagent_type: generalPurpose`, using your configured reflect-judgment model (default `claude-opus-4-8-thinking-xhigh`), agent mode (`readonly: false`). The synthesizer's quality check includes spot-verifying citations, which can require MCP access; readonly strips MCPs. Use `references/synthesizer.md` verbatim, with each reviewer's full output inlined where marked. The synthesizer returns a structured Accepted / Rejected / Backlog list.
One `Task` call, `subagent_type: generalPurpose`, using your configured reflect-judgment model (default `claude-opus-4-8-thinking-high`), agent mode (`readonly: false`). The synthesizer's quality check includes spot-verifying citations, which can require MCP access; readonly strips MCPs. Use `references/synthesizer.md` verbatim, with each reviewer's full output inlined where marked. The synthesizer returns a structured Accepted / Rejected / Backlog list.

### 4. Structural enforcement check

Expand Down
26 changes: 13 additions & 13 deletions pstack/skills/setup-pstack/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,23 +35,23 @@ description: pstack per-role model choices (overrides skill defaults)
alwaysApply: true
---
# pstack model configuration. One line per role. Delete a line to fall back to the skill default.
feature, refactoring: grok-4.5-fast-xhigh
feature, refactoring: grok-4.5-fast-high
bug-fix: gpt-5.5-high-fast
perf-issue: gpt-5.5-high-fast
hillclimb: gpt-5.5-high-fast
judgment and prose: claude-opus-4-8-thinking-xhigh
judgment and prose: claude-opus-4-8-thinking-high
hardest tasks: claude-fable-5-thinking-max
how explorer: grok-4.5-fast-xhigh
how explainer: claude-opus-4-8-thinking-xhigh
how critics: claude-opus-4-8-thinking-xhigh, gpt-5.5-high-fast, grok-4.5-fast-xhigh
why investigators: grok-4.5-fast-xhigh
why synthesizer: claude-opus-4-8-thinking-xhigh
reflect tooling: grok-4.5-fast-xhigh
reflect judgment, divergent, synthesizer: claude-opus-4-8-thinking-xhigh
arena runners: claude-opus-4-8-thinking-xhigh, gpt-5.5-high-fast, grok-4.5-fast-xhigh
arena cross-judge pool: claude-opus-4-8-thinking-xhigh, gpt-5.5-high-fast, grok-4.5-fast-xhigh
architect runners: claude-opus-4-8-thinking-xhigh, gpt-5.5-high-fast, grok-4.5-fast-xhigh
interrogate reviewers: claude-opus-4-8-thinking-xhigh, gpt-5.5-high-fast, grok-4.5-fast-xhigh
how explorer: grok-4.5-fast-high
how explainer: claude-opus-4-8-thinking-high
how critics: claude-opus-4-8-thinking-high, gpt-5.5-high-fast, grok-4.5-fast-high
why investigators: grok-4.5-fast-high
why synthesizer: claude-opus-4-8-thinking-high
reflect tooling: grok-4.5-fast-high
reflect judgment, divergent, synthesizer: claude-opus-4-8-thinking-high
arena runners: claude-opus-4-8-thinking-high, gpt-5.5-high-fast, grok-4.5-fast-high
arena cross-judge pool: claude-opus-4-8-thinking-high, gpt-5.5-high-fast, grok-4.5-fast-high
architect runners: claude-opus-4-8-thinking-high, gpt-5.5-high-fast, grok-4.5-fast-high
interrogate reviewers: claude-opus-4-8-thinking-high, gpt-5.5-high-fast, grok-4.5-fast-high
```

### 6. Confirm
Expand Down
Loading