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
4 changes: 2 additions & 2 deletions UPSTREAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@ pvstack tracks Lauren Tan's pstack directly from Cursor's plugin repository.

- Repository: https://github.com/cursor/plugins
- Path: `pstack/`
- Commit: `ae5650febf4320793844c12c4adaa937f417f8da`
- Upstream version: 0.15.36
- Commit: `bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7`
- Upstream version: 0.15.42

Update with `node tools/sync-upstream.mjs --ref main`, review the diff, then commit.
`node tools/sync-upstream.mjs --check` fails when the tree has drifted from this pin.
Expand Down
15 changes: 1 addition & 14 deletions plugins/pvstack/.upstream-files.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,6 @@
"skills/create-verification-skill/references/feature-map-example/search.md",
"skills/figure-it-out/SKILL.md",
"skills/how/SKILL.md",
"skills/how/references/explainer-prompt.md",
"skills/how/references/explorer-prompt.md",
"skills/in-your-own-words/SKILL.md",
"skills/interrogate/SKILL.md",
"skills/ketchup-video/SKILL.md",
Expand Down Expand Up @@ -500,6 +498,7 @@
"skills/statechart/scripts/test/corpus/UserNoDeadlock/verdict-2.exit",
"skills/statechart/scripts/test/corpus/UserNoDeadlock/verdict-2.out",
"skills/statechart/scripts/test/differential.test.ts",
"skills/statechart/scripts/test/drawn.ts",
"skills/statechart/scripts/test/grid/Grid.cfg",
"skills/statechart/scripts/test/grid/Grid.tla",
"skills/statechart/scripts/test/grid/sany.out",
Expand All @@ -521,18 +520,6 @@
"skills/typescript-best-practices/references/patterns.md",
"skills/unslop/SKILL.md",
"skills/why/SKILL.md",
"skills/why/references/epistemics.md",
"skills/why/references/investigator-prompt.md",
"skills/why/references/source-playbook.md",
"skills/why/references/sources/code-archaeology.md",
"skills/why/references/sources/databricks.md",
"skills/why/references/sources/datadog.md",
"skills/why/references/sources/incident-postmortem.md",
"skills/why/references/sources/linear.md",
"skills/why/references/sources/notion.md",
"skills/why/references/sources/sentry.md",
"skills/why/references/sources/slack.md",
"skills/why/references/synthesizer-prompt.md",
"skills/poteto-delegate/SKILL.md",
"droids/comment-sicko.md",
"droids/poteto-agent.md",
Expand Down
4 changes: 2 additions & 2 deletions plugins/pvstack/docs/upstream/guide/01-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ Run:

[`/setup-pvstack`](../../skills/setup-pvstack/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 `~/.factory/pvstack-models.md`, a small rule every pstack skill reads.

The defaults run at `xhigh` reasoning, the same as the `large` budget. `unlimited` lifts each model to its highest tier, up to `max`. Opus goes to `max`. Grok tops out at `xhigh`, so it stays there. `medium` and `small` lower the reasoning and spend fewer tokens.
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`. Gemini tops out at `high`, so it stays there. `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-pvstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pvstack` again.
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-pvstack` 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-pvstack` 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.

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
4 changes: 2 additions & 2 deletions plugins/pvstack/docs/upstream/guide/02-poteto-mode.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ When you're unsure whether a prompt is aimed right, run [`/sharpen`](../../skill
/sharpen write a migration guide for the v2 config format.
```

The agent says what a top professional would do that you didn't ask for, the rawest material they would start from, the methods and tools they would use, and what other than you or the agent would show the result is right. Then it rewrites your prompt to ask for exactly that, deeper but not bigger, and leaves your choices open. It doesn't do the task. Read the rewrite, then send it, for example with `/poteto-mode`.
The agent says what a top professional would do that you didn't ask for, the rawest material they would start from, the methods and tools they would use, and what other than you or the agent would show the result is right. Then it rewrites your prompt to ask for exactly that, deeper but not bigger. The rewrite asks the agent to prototype any choice an experiment can settle and to recommend an option from what it observed, and it leaves product and preference choices to you. It doesn't do the task. Read the rewrite, then send it, for example with `/poteto-mode`.

## Follow up short

Expand Down Expand Up @@ -132,7 +132,7 @@ When you step away, say what done means and go:

Work you'll review later routes through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.

**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
**Pitfall:** don't enumerate skills in your prompt ("use /architect, then /arena, then /interrogate..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.

Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.

Expand Down
6 changes: 3 additions & 3 deletions plugins/pvstack/docs/upstream/guide/03-understand.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,23 +14,23 @@ When the cause is unclear, ask for findings, not a fix:
/poteto-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet.
```

"don't change any code yet" routes this to the [Investigation playbook](../../skills/poteto-mode/playbooks/investigation.md). It runs `/how`, adds `/why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.
"don't change any code yet" routes this to the [Investigation playbook](../../skills/poteto-mode/playbooks/investigation.md). It traces the code, adds `/why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.

## Trace behavior with `/how`

```text
/how do we dedupe notifications? is there an n+1 when we look up subscribers?
```

Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains.
Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. It starts one read-only subagent that explores the code and writes the explanation.

## Dig up history with `/why`

```text
/why was the retry limit set to five? does the reason still hold?
```

[`/why`](../../skills/why/SKILL.md) starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.
[`/why`](../../skills/why/SKILL.md) answers from the record, not the code. It reads the commits and PR discussions that introduced the code and each later change, and looks at other sources when that trail is thin. The answer cites what the authors wrote, marks the agent's own inferences as inferences, and says what the record does not answer, because "nobody wrote down why" is itself an answer.

The two compose naturally. `do why first then how` is a good prompt when you suspect the history explains the mess.

Expand Down
4 changes: 2 additions & 2 deletions plugins/pvstack/docs/upstream/guide/04-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ 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, running `/how` over the code the design touches and `/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) 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.

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

Expand All @@ -28,7 +28,7 @@ The design isn't sacred once code starts. If implementation shows the same worka
/arena take my prompt to the arena verbatim. i want to compare their proposals with yours.
```

[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge from a different model family scores every candidate against a rubric. When no model from another family can run, the coordinator skips the judge and picks the base itself. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result.
[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge from a different model vendor scores every candidate against a rubric. When no model from another vendor can run, the coordinator skips the judge and picks the base itself. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result.

```mermaid
flowchart LR
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,7 @@ To watch the catch-up instead, run [`/ketchup-video`](../../skills/ketchup-video

## The pitfalls

- **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
- **Enumerating skills in the prompt.** "use /architect then /arena then /interrogate" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
- **A vague finish condition.** "make it better" gives `/loop` nothing to check. Give a command or artifact that can pass or fail.
- **Leading with your theory of the cause.** The agent searches wherever you pointed. Ask it to restate the problem first, then share your hunch.
- **Taking the first design.** One attempt locks in the first shape the model thought of. Ask for prototypes or `/architect` and pick from evidence.
Expand Down
4 changes: 2 additions & 2 deletions plugins/pvstack/docs/upstream/harness/claude-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ pstack skills use Cursor names. In Claude Code, read this file once per session,
| Cursor | Claude Code |
| --- | --- |
| `claude-<family>-<version>-<effort>[-fast]`, such as `claude-opus-5-5-xhigh` | `model: "opus"` and `effort: "xhigh"`. `model` takes only `opus`, `sonnet`, `haiku`, `fable`. Drop `-fast`. |
| A `grok-*`, `gpt-*`, or other non-Claude slug | Omit `model` so the agent runs on the session model, and say so. |
| A `gemini-*` or other non-Claude slug | Omit `model` so the agent runs on the session model, and say so. |
| `auto` or `inherit-parent` | Omit `model`. |
| The `pvstack-models.md` rule, `~/.factory/pvstack-models.md` | `~/.claude/rules/pstack-models.md`. Claude Code loads it into every new session, so its role lines are already in context. If they are not, read the file. If the file or the role's line is missing, use the skill's default slug. |
| A role value `<model> <effort>`, such as `opus high` | `model: "opus"` and `effort: "high"`. |
Expand All @@ -42,7 +42,7 @@ pstack skills use Cursor names. In Claude Code, read this file once per session,
Claude Code loads every `.md` file in `~/.claude/rules/` into each new session, so `setup-pvstack` writes its rule there. Follow its steps with these changes:

- Detect. The detected models are the `model` values that the `Agent` tool schema lists, each with an effort from its `effort` values. Write a real model as `<model> <effort>`, such as `opus xhigh`. The effort is the last token, so the budget step works as written.
- Defaults. Map each default slug with the rows above: `claude-opus-5-5-xhigh` is `opus xhigh`, and `grok-4.7-xhigh-fast` is `inherit-parent`.
- Defaults. Map each default slug with the rows above: `claude-opus-5-5-xhigh` is `opus xhigh`, `claude-opus-5-5-high-fast` is `opus high`, `claude-fable-5-2-max` is `fable max`, and `gemini-4-carbon-high` is `inherit-parent`.
- Write. Write `~/.claude/rules/pstack-models.md` with no frontmatter, then the comment lines, the `# budget` line, and one line per role from step 5. Overwrite the whole file. Never put the role lines in `CLAUDE.md` or `AGENTS.md`.

## Paths
Expand Down
2 changes: 1 addition & 1 deletion plugins/pvstack/droids/comment-sicko.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ That list is my only leash. When I am not sure a keep clause applies, the commen

`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.

`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I trace the named symbol or call, run `/why` from the **why** skill on it, or both. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.

A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.

Expand Down
6 changes: 3 additions & 3 deletions plugins/pvstack/skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,15 @@ Open a todolist with one entry per phase before starting.

## Phase A: Ground the problem

Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
Build a real mental model of every system the new code touches. Trace the relevant subsystems. Naming a file isn't grounding. Write an architectural explanation of each. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.

Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.

## Phase B: Sketch

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.

Take the runners from the `architect runners` line in the `pvstack-models.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.
Take the runners from the `architect runners` line in the `pvstack-models.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `claude-fable-5-2-high`, `claude-opus-5-5-high-fast`, and `gemini-4-carbon-high`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A.

Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.

Expand Down Expand Up @@ -72,7 +72,7 @@ Use judgment. A few edge cases don't condemn an architecture. Some problems are

When you scrap:

1. Re-run the **how** skill over what's been built.
1. Trace what's been built.
2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.
3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows.
4. Return to Phase B and re-run arena.
Expand Down
Loading
Loading