setup-pstack

Files (1)

• SKILL.md

SKILL.md (first lines)

# Setup pstack

On Pi, read the [platform mapping](../poteto-mode/references/pi-tools.md), including its per-skill notes, before following this skill.

Write the per-role model override sheet at `~/.pi/agent/pstack-models.md` (`$PI_CODING_AGENT_DIR/pstack-models.md` when that variable is set). Each pstack skill names a default model in its Models section; the sheet adapts those defaults to the models you actually have. pstack-pi's `pstack-routing` extension puts the sheet in every session's system prompt, subagents included, so a saved sheet applies from the next message. There is no include line to add.

## Steps

### 1. Detect available models

Run `pi --list-models` in a shell. Each row's `provider` and `model` columns, joined as `provider/model`, form the detected set, and they are what the `Agent` tool's `model` field should receive. Bare family names such as opus match fuzzily across every provider with credentials and can land on an older model or another provider, so the sheet always names full ids. Ask the user to confirm or add any they want available. Never write an id you have not seen listed. The aliases `inherit-parent` and `auto` are always valid. Both run the role on the parent session's model, which the `Agent` call expresses by omitting `model`.

### 2. Load current state

The default role-to-model mapping is the sheet shape in step 6. If the sheet already exists, read it and treat its values as the current choices. Otherwise start from those defaults. A line whose role is not in that shape, such as `how critics`, is from a retired role. Drop it. A value that is a bare family name (opus, fable, sonnet, haiku) or a model id without a provider is from another runtime. Map it to the matching detected `provider/model` id and say so.

### 3. Map and confirm

Show every role with its current model, marking any id not in the detected set as needing a choice. Also list each line step 2 dropped or rewrote. Ask with `ask_user_question` whether to accept as-is or change specific roles, offering the detected ids plus `inherit-parent` and `auto`. For panel roles (arena runners, architect runners, interrogate reviewers) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. `arena cross-judge pool` is also a list, but Arena selects one value from it whose model family differs from the parent's when possible. `swarm workers` is the default model for every worker unless a race or comparison assigns another model per arm.

The panels exist for model diversity, so keep at least two model families in each panel list. The shipped panel is `{{model:opus}}`, `{{model:fable}}`, `{{model:sonnet}}`. A model that answers `pi --list-models` can still fail at request time (a provider without billing, a model the provider does not serve), so before writing, send each chosen id one short request, such as `pi -p --no-session --no-tools --model <id> "Reply ok"`, and drop any that errors.

Then ask for the default reasoning effort, the `default effort` line. It is `session`, which keeps the parent session's thinking level, or one of the levels in [Models](#models). Every role value without a suffix runs at it. Then ask whether any role should run at another level. A role value may carry one after its id, as in `<id> @xhigh`; panel entries take their own, as in `<id> @xhigh, <id> @max`. The level is passed as the `Agent` call's `thinking` field, and Pi clamps it to what the model supports. Leave the suffix off for the default effort.

### 4. Choose whether session routing is on

pstack-pi's `pstack-routing` extension adds the poteto-mode routing instruction to every main session's system prompt. Ask whether to keep it. The default is on. The answer is the `session hook` line: `on` or `off`. With no sheet or no line, routing is on. The extension rereads the sheet on every message, so the change applies without `/reload`.

### 5. Validate

Every real id written must be in the detected set. `inherit-parent` and `auto` always pass. Validate the id without any `@<level>` suffix, and the level against the levels in [Models](#models). The `default effort` value is one of those levels or `session`. If a chosen id or level is not available, stop and ask again.

### 6. Write the override sheet

Write the sheet with the shape below, substituting the confirmed ids. Overwrite the whole file so re-runs stay idempotent.

```markdown
# pstack model configuration

Per-role model overrides for pstack skills. Each pstack SKILL.md names its defaults in a Models section; the values here override those defaults. Delete a line to fall back to the skill default. A value of `inherit-parent` or `auto` runs that role on the parent session's model (the `Agent` call omits `model`); an alias entry in a panel list still counts toward that panel's fan-out. A model may carry a reasoning effort, as in `{{model:opus}} @xhigh` (levels: low, medium, high, xhigh, max), passed as the `Agent` call's `thinking` field, each entry of a panel list on its own. `default effort` sets the level for a value without one; `session` keeps the parent session's level. `session hook: off` stops pstack-pi's pstack-routing extension from adding the poteto-mode routing instruction; any other value, or no line, leaves it on.

feature, refactoring: {{model:opus}}
bug-fix: {{model:fable}}
perf-issue: {{model:fable}}
hillclimb: {{model:fable}}
judgment and prose: {{model:opus}}
strongest judgment: {{model:fable}}
how explorer: {{model:opus}}
how explainer: {{model:opus}}
why investigators: {{model:opus}}
why synthesizer: {{model:opus}}
reflect tooling: {{model:opus}}
reflect judgment, divergent, synthesizer: {{model:opus}}
arena runners: {{model:opus}}, {{model:fable}}, {{model:sonnet}}
arena cross-judge pool: {{model:opus}}, {{model:fable}}, {{model:sonnet}}
swarm workers: {{model:opus}}
architect runners: {{model:opus}}, {{model:fable}}, {{model:sonnet}}
interrogate reviewers: {{model:opus}}, {{model:fable}}, {{model:sonnet}}

default effort: session
session hook: on
```

### 7. Confirm

Tell the user where the sheet was written, that the extension loads it from the next message, and whether routing is on. Re-running this skill updates the sheet.

## Models

The Pi defaults, stamped by pstack-pi's `scripts/sync-pstack.mjs` from upstream `models.json` and the Pi model map in `port.json`.

- Default panel: `{{model:opus}}`, `{{model:fable}}`, `{{model:sonnet}}`
- Reasoning effort levels: `low`, `medium`, `high`, `xhigh`, `max`
- Default reasoning effort: `session`
- Single-role default: `{{model:opus}}`

From proguha/pstack-pi, MIT.

More from proguha/pstack-pi