adjohn/pstack/setup-pstack

Setup pstack

Write ~/.claude/pstack-models.md, an always-loaded override file that sets pstack's model per role, imported into every session from ~/.claude/CLAUDE.md. The skills read it and fall back to their inline defaults when a line is absent, so this is an override layer, not a requirement.

Steps

1. Detect available models

Start from the documented model aliases as candidates: haiku, sonnet, opus, and fable. Full model IDs also work when the user's account exposes them. There is no in-session API that lists the user's entitled models, so where availability is uncertain (fable, full model IDs), either test-spawn a one-line background subagent per candidate and treat a slug-rejection error as unavailable, or ask the user which models their account has. If you cannot confirm any, ask the user to paste the slugs they have access to. Never write a real slug you have not confirmed is available. The aliases inherit-parent and auto are always valid even though they are not detected slugs.

2. Load current state

The default role-to-model mapping is the file shape shown in step 5 below. If ~/.claude/pstack-models.md already exists, read it and treat its # budget line and its role values as the current choices. Otherwise start from those defaults. A line whose role is not in step 5, such as how critics, is from a retired role. Drop it.

3. Budget, map, and confirm

(a) Ask for a budget. Prefer AskUserQuestion over free text. Offer these four options with these exact labels, and name the current budget when the file records one.

• unlimited (model default, max per session)
• large (xhigh reasoning)
• medium (high reasoning)
• small (medium reasoning)

(b) Apply it. Claude Code model tiers carry no effort token, so the budget is one session-wide effort level, and it is every role's starting level: poteto-mode steps a spawn's effort up or down from it for the job. large, medium, and small set effortLevel in ~/.claude/settings.json to xhigh, high, or medium. Read the JSON, set that one key, write it back, and leave every other key as it was. unlimited removes the key, so each model runs at its own default. max cannot be persisted, so on unlimited tell the user that /effort max or CLAUDE_CODE_EFFORT_LEVEL=max reaches it per session. A saved per-model level under modelSettings outranks effortLevel, so name any such entry you find and ask before touching it. Role models do not change with the budget. Build the working table from the skill defaults, and on a re-run keep any role you changed by tier, list, or alias (inherit-parent, auto).

(c) Show the roles and confirm. Show every role with its model, marking any real slug not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected models plus inherit-parent and auto (both mean: this role runs on the parent chat model, which is how users on the default model setting stay on it) as the options. Prefer AskUserQuestion over free text. 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 runs one judge. It tries only values on a tier other than the parent's, in list order, so order it by preference. An inherit-parent or auto value never judges. swarm workers is the default model for every worker unless a race or comparison assigns another model per arm.

4. Validate

Every real slug written must be in the detected set; inherit-parent and auto always pass. If a chosen real slug is not available, stop and ask again. An override file pointing at a model the user cannot use breaks every delegation that reads it.

5. Write the override file

Write ~/.claude/pstack-models.md with a # budget line with the chosen label and its target effort, and one line per role, using the same labels poteto-mode uses. Overwrite the whole file so re-runs stay idempotent. Shape:

# pstack model configuration. One line per role. Delete a line to fall back to the skill default.
# `inherit-parent` or `auto` as a value: the role runs on the parent chat model (omit the Agent `model`). Alias entries in a panel list still count toward its fan-out.
# budget: unlimited (model default, max per session)
feature, refactoring: haiku
bug-fix: haiku
perf-issue: haiku
hillclimb: haiku
judgment and prose: opus
hardest tasks: opus
how explorer: haiku
how explainer: opus
why investigators: haiku
why synthesizer: opus
reflect tooling: haiku
reflect judgment, divergent, synthesizer: opus
arena runners: opus, haiku
arena cross-judge pool: opus, haiku
swarm workers: haiku
architect runners: opus, haiku
interrogate reviewers: opus, haiku

Then make it always loaded: read ~/.claude/CLAUDE.md (create it if it does not exist) and add the line @~/.claude/pstack-models.md if it is not already present. That memory import pulls the file into every session. Adding the line is idempotent: skip it when it is already there, and never duplicate it.

6. Confirm

Tell the user the override file was written, that ~/.claude/CLAUDE.md imports it, what effortLevel now holds in ~/.claude/settings.json, and that it applies to new sessions. Re-running this skill updates it.

7. Offer a verification skill (optional)

Check whether the project has a way to drive the real app for proof (a verify-* skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke /create-verification-skill (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing.

8. Offer a formal verification skill (optional)

Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke /create-formal-verification-skill (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing.