setup-pstack skill

Setup pstack

For a routing-only request, establish the parent in step 1, then go directly to Codex startup routing.

Configure one portable model sheet for the current parent harness. Read provider-dispatch.md before probing or writing anything. Its model matrix, descriptor grammar, sheet grammar, and route table are the contract. Choose one requested effort per assigned provider/model pair and, when the operator wants it, an explicit ordered primary -> fallback attempt chain per seat plus, when the operator accepts it, one # fallback policy line declaring which terminal outcomes may advance the chain (usage-exhausted is the only authorized outcome when the line is absent). An optional # continuation: {"on":["permission","handoff"],"max":2} line is a separate same-route execution policy; preserve a loaded line or its absence unless the operator explicitly chooses a change. Do not add a second configuration file or an unapproved substitution; a saved chain is the only authorized provider fallback. The installed helper skills/poteto-mode/scripts/model-policy/pstack-model-policy validates the rendered sheet (validate --sheet <file> --parent <claude|codex>) before it is written.

Claude Code writes ~/.claude/pstack-models.md and loads it from ~/.claude/CLAUDE.md with:

@~/.claude/pstack-models.md

Codex writes ~/.codex/pstack-models.md. Codex has no @ include, so mirror the sheet's exact bytes inside one bounded block in ~/.codex/AGENTS.md and retain the sheet as the editable source of truth:

<!-- pstack:models:begin -->
<exact contents of ~/.codex/pstack-models.md>
<!-- pstack:models:end -->

Steps

1. Establish the parent

Use the harness and tool surface running this skill: Claude Code or Codex. Environment markers may corroborate that top-level answer, but do not launch a child and ask it to detect where it came from. Record the parent because the same descriptor takes a different route in each harness.

2. Load current state

Read the current parent-specific sheet when it exists. Before validating the loaded descriptors, normalize only the rolling-alias predecessors that earlier pstack releases generated. A provider-qualified Claude model is migratable when its model component starts with claude-fable-, claude-opus-, or claude-sonnet- and the remaining revision contains only digits and hyphens. Replace that component in memory with fable, opus, or sonnet, preserving the provider, effort, role, and lane order. Record each original and normalized descriptor for the confirmation in step 8. This migration is valid loaded state and does not require a separate operator choice.

Read the sheet's # budget line as the recorded budget choice; a missing or unreadable line means no recorded budget. Read each # access: <JSON> line as a per-provider access fact (funding, capacity, apiSpend, provenance, and optional display-only plan/note/observedAt). Preserve those facts verbatim unless the operator updates them. Funding, capacity, plan, notes, and observation times are advisory evidence, never credentials or durable entitlement. apiSpend is different: it is the binding saved authorization passed to every policy-enabled external attempt until the operator changes it. One # access record per provider is the maximum. Provider observations alone do not authorize dispatch: selected funding and API-spend choices require operator confirmation and provenance: "user". Retain provider-reported plan details as optional evidence, then mark the access record user-confirmed when the operator accepts those binding choices. Treat the normalized values as current role-to-family assignments. Overlay those rows on the complete first-run role map in step 8. Materialize any missing documented role row from that map on the next successful write. A duplicate or unknown role row is inconsistent state; report it and resolve it before probing. A bare host-native slug from an older sheet is also invalid because it does not say which provider owns it. A versioned Claude ID outside the three migration families is not an alias or an inconsistency: it stays an exact model ID subject to the same provider rules as any other descriptor. If the sheet is missing, use the complete first-run role map and the model matrix's Default effort cells for rows marked First-run active. Fable, Sonnet, Astra, Luna, and Terra are opt-in: offer them as named role replacements without adding them to the three-family first-run panel. First-run active only seeds defaults; derive assigned families from the final role map on every run.

Optional Cursor roles

Cursor lanes are opt-in and separate from the three baseline families below. Preserve existing cursor:<slug>@default assignments and collect any named Cursor role additions before probing; do not add Cursor to the default panel. Discover exact slugs with cursor-agent models; require default effort and reject Cursor's auto model selector. In step 6, each distinct selected Cursor slug gets one external read-only runner probe from the current parent, alongside the other assigned pairs. cursor-agent status --format json must confirm stored OAuth authentication. When CURSOR_API_KEY is supplied, the runner instead checks CLI availability and defers authentication to execution; only a successful model result establishes availability. The CLI must be available as cursor-agent; never substitute an unrelated agent binary.

A selected Cursor lane that fails its probe requires explicit repair or reassignment through step 4 before saving, without changing the active sheet. An unassigned Cursor provider requires neither installation nor probing. Model parsing and final role validation must accept these discovered, probed optional descriptors alongside the model matrix families and aliases. Store them directly in the same role map with @default; do not ask a separate reasoning-effort question or create another source of truth.

Optional Antigravity roles

Antigravity lanes are opt-in and separate from the default panel. Preserve loaded antigravity:<exact-agy-slug>@default assignments and accept named additions only after agy models lists the exact slug. Do not use auto, infer a slug for a hosted Claude model, or pass a separate effort flag: reasoning is part of the listed slug. Record an explicit user-confirmed # access fact with apiSpend: "deny" or "approved" before probing; the runner rejects an omitted choice even for an older sheet. Probe each selected slug from the current parent through the external read-only runner. A model listing alone does not prove authentication or execution. An unassigned Antigravity provider needs no installation or probe.

Optional OpenCode roles

OpenCode lanes are opt-in and do not change default panels. The runner selects the restored native V1 (>=1.18.29 <2) or stable V2 (>=2.0.0 <3) contract once from the CLI version banner. Compatible patch and minor versions pass through the required capability checks. Preserve explicit opencode:<provider>/<model>@default assignments. Exact IDs may appear in opencode debug models once the registry is ready; cold empty lists are not access proof. Reject auto, missing segments, and non-default effort. Do not pass --variant. Ordinary built-in providers and native authentication require the operator's explicit apiSpend: approved access fact. Never inspect or copy credential files, infer approval from authentication, or approve spending on the operator's behalf. An explicitly requested native ChatGPT subscription probe instead uses exactly openai/gpt-6.1-sol@default with --opencode-chatgpt-subscription --api-spend deny. Preserve the existing normal OpenCode login and native data location; do not inspect credentials or approve API spending. The runner requires exactly one visible native OpenAI OAuth connection before execution; V2 also requires the private configured endpoint while V1 uses the native builtin endpoint. This bounded mode trusts the normal native login and does not attest hidden credential metadata. The subscription opt-in is per attempt and cannot authorize another provider, model, or billing-enabled fallback. In step 6, probe each distinct assigned model through the external runner with the selected funding route. Configuration preflight proves only the private native sources; a successful final response proves executable access. Read-only probes have no shell. Writers require the assigned real Git worktree root and can edit files but cannot build or run tests. Follow Optional OpenCode models for permissions, isolation, and startup limits.

Optional Devin roles

Preserve loaded Devin assignments and accept explicitly requested named roles using the Optional Devin models rules in provider-dispatch. SWE-2 offers medium/high/max; SWE-1.6 uses the fixed default token without an effort question. For other models, use the exact CLI UID at default effort and follow the discovery guidance in provider-dispatch. Effort is part of the UID, so never ask a separate effort question or invent a variant suffix. An unavailable or unreadable listing does not reject an explicitly selected ID; the selected-pair probe still must pass. Neither family changes the first-run panel or requires installation or probing when unassigned. For an assigned Devin pair, run devin auth status, inspect devin models list --format json, and probe the exact model and effort through the external runner. An account gate is a failed selected route, never permission to substitute a model.

2b. Discover observable access

Before recommending anything, separate what is observable from what only the operator knows. Discover only supported, read-only facts for the providers the operator is interested in: CLI presence, authentication status, authoritative provider-reported plan metadata, and advertised model lists where the CLI exposes them (for example codex login status, grok models, cursor-agent status --format json, devin auth status, devin models list --format json, agy models). A provider-reported plan or tier is useful evidence about that plan at the observation time and may populate the optional display field; it does not by itself establish included entitlement. An installed binary, successful login, plan report, or model listing does not prove remaining usage, executable capacity, or freedom from provider-managed overage. Never read credential files or print secret values. When the parent exposes an official account/usage tool (such as a usage-limits surface on this host), its snapshot may inform a warning; label it with its source and observation time and do not persist transient usage as entitlement.

Ask only for routing facts discovery cannot prove: which providers have subscription/included access, expected capacity (standard, high, or unknown), and whether metered API spend is deny or approved for that provider. Reuse facts the operator already gave and access facts already persisted in the sheet; an existing explicit apiSpend choice remains binding until the operator changes it, so do not ask again. Plan labels, notes, and observation times are optional; never block setup or ask solely to fill them. Capacity may remain unknown. Funding may remain unknown while comparing options, but every provider selected by the final role map must have operator-confirmed funding and an authorized combination before probing or saving: included with either saved apiSpend choice, or metered with apiSpend: "approved". Unknown funding and metered funding with saved denial are blocked routes. Clarify or reassign them; never skip them to a later attempt. Provider-managed overage or on-demand credits can apply under OAuth without an API key, so never promise that denying API credentials guarantees zero charges; name the provider account's own billing controls as the place to set hard limits, and do not change billing settings, redeem credits, or enable paid billing.

3. Ask the reasoning budget

Ask for a budget before changing assignments. Prefer AskUserQuestion over free text. Offer these four options with these exact labels, and name the current budget when the loaded sheet records one.

• unlimited — keep max
• large — xhigh reasoning
• medium — high reasoning
• small — medium reasoning

Apply the choice to the normalized working table loaded in step 2, including every existing provider, model, effort, alias, and panel order. Use first-run defaults only for a missing sheet or missing role. Do not infer which loaded values were customized by comparing them with today's defaults. unlimited leaves every effort in this table unchanged. For large, medium, and small, use a ceiling of xhigh, high, or medium on the ladder max > xhigh > high > medium > low. Preserve any valid effort already at or below the ceiling. For an effort above the ceiling, propose the family's highest selectable effort at or below the target; if none qualifies, mark the role as needing a choice. Validate loaded descriptors before applying a ceiling, so an unsupported stored effort is not silently repaired. Aliases and fixed-default families such as SWE-1.6, Cursor, and Antigravity lanes do not change. small proposes claude:opus@medium for claude:opus@max but preserves claude:opus@low. large proposes devin:swe-2@high for devin:swe-2@max. Every budget preserves devin:swe-1.6@default, exact Antigravity slugs at @default, inherit-parent, and auto.

Show every proposed effort change before the final confirmation. This is a requested configuration change, not permission to substitute a model or effort after a failed probe. Honor explicit per-family overrides without raising other families' efforts.

4. Select role assignments

Show the normalized complete role map, the model matrix, and this parent's routes. Ask whether to keep the assignments or change named roles. Preserve current assignments by default; on a first run, explain that the example uses all three families but none is mandatory. The operator can replace named lanes with any supported provider's provider:model@effort descriptor — a recommended matrix family, another exact model ID the provider's CLI advertises, or an exact Devin, Cursor, Antigravity, or OpenCode slug — plus inherit-parent, or auto, or remove named entries from a panel. A request to omit a provider must resolve every occurrence, including single-model roles and panel entries. Do not silently remap missing providers, reset customized lanes, or drop an entire role. Keep at least two entries in architect runners, at least one entry in every other panel, and exactly one descriptor for each single-model role. Repeated descriptors are allowed: architect runners: inherit-parent, inherit-parent launches two independent candidates without requiring another provider. If a requested removal leaves fewer than two architect entries, ask for an explicit replacement or another entry before probing or writing; never add a provider silently.

Why and Reflect require the parent's live MCP surface. Keep their investigator, reviewer, and synthesizer roles on inherit-parent or auto. Preserve all documented role rows, and preserve the order of untouched lanes. Say when replacements or removals reduce provider diversity. If the operator already named role changes, apply those without asking them to repeat the choice.

When recommending a mix, reason from confirmed facts: task fit, included or reported capacity before metered spend, the requested reasoning budget, required MCP access, and panel provider diversity. Suggest concrete ordered fallbacks where they add coverage. A different model on the same provider can cover model capacity when the saved policy authorizes terminal failures. A second provider can cover account usage exhaustion. Explain each fallback's effect on quality and provider diversity. Every fallback must name an exact provider:model@effort descriptor, inherit-parent, or auto, with at most three attempts per seat. Choose recovery behavior separately in step 4a. An existing sheet's policy line, including its absence (quota-only), is preserved verbatim unless the operator explicitly accepts a change. Preserve existing customized assignments, efforts, lane order, and chains unless the operator accepts a change. Why and Reflect stay on inherit-parent or auto; an MCP-less external lane is not an equivalent substitute there.

Derive the assigned family set from the resulting role descriptors, excluding inherit-parent and auto. An unassigned family is optional: do not ask for its effort, check its CLI or credentials, or probe it. A missing Grok CLI cannot block a configuration with no Grok roles. Availability checks must not choose assignments for the operator.

4a. Choose automatic recovery

On first setup and reruns, show the current fallback mode, including usage exhaustion only when no # fallback line exists. Ask which mode to use, with these choices and effects. Reuse an explicit choice already made in this conversation instead of asking again; an unanswered question preserves the current policy. Recommend automatic recovery for a new sheet, but do not enable it without acceptance.

• Automatic recovery (recommended). Use the next saved fallback when usage is exhausted, a route is unavailable, the backend terminates unsuccessfully, or an explicitly configured deadline expires. Save # fallback: {"on":["usage-exhausted","route-unavailable","terminal-failure","deadline-exceeded"]}.
• Usage exhaustion only. Use the next saved fallback only on proven exhaustion. Save # fallback: {"on":["usage-exhausted"]} when changing modes; preserve an existing quota-only declaration or its absence when keeping that mode.
• No automatic fallback. Do not advance to another descriptor after a failed attempt. Save # fallback: {"on":[]}; removing the line would restore quota-only behavior. Preserve saved chains so they remain available if the operator later enables fallback.

For an existing custom subset, show its actual triggers and allow keeping it verbatim rather than forcing it into one of these presets. Explain that each mode uses only the exact saved chains; a seat without a backup gains no additional provider. Changing recovery never changes models, efforts, access or spending permission, and never adds a timeout. A completed response reporting failing project tests is task output, not a backend failure. Cancellation, billing blocks, safety denials, and unsupported capabilities stop under every fallback mode. A verified permission blockage cannot switch providers. Refer to saved fallback and backend recovery for receipt classification and writer inspection requirements.

Explain same-provider chains explicitly when present. usage-exhausted skips every remaining model on the exhausted provider. Model-capacity, overloaded, and transient terminal failures advance to a saved different model only with terminal-failure enabled. A proved unavailable route advances with route-unavailable enabled. The default quota-only policy stops on capacity failures. Selecting a chain does not enable broader recovery or change its provider's apiSpend value.

Ask a separate continuation question on first setup and reruns, showing the current # continuation policy or its absence. Offer Resume the same model after a corrected permission blockage or completed parent handoff with # continuation: {"on":["permission","handoff"],"max":2}, or Stop without automatic continuation, represented by no continuation line. The limit is two total executions per descriptor, including the original, not two retries. Keep the current choice unless the operator explicitly changes it; reuse a choice already made and preserve custom causes or limits verbatim when keeping them. Explain that continuation requires parent inspection of partial work and side effects, a concrete corrected blockage or completed operation, stopped prior writers, and a fresh execution. It never bypasses a denial or switches models. Do not infer continuation consent from accepting automatic fallback. Show both selected policies again at confirmation.

5. Validate and choose assigned efforts

Every non-alias value must match <provider>:<model>@<effort> on a supported provider. Apply the optional Cursor, Antigravity, and OpenCode rules above to their descriptors. The model matrix supplies recommended defaults and effort guidance, never an allowlist: the model is the exact ID the provider's CLI accepts, not a matrix row. Where the CLI advertises a model list — grok models, devin models list --format json (variants[].model_uid only), cursor-agent models, agy models, opencode debug models — choose the ID from it, remembering that a listing is evidence, not entitlement. Use current host capabilities for Claude and Codex where exposed, and let the step 6 probe prove an explicitly selected alias or exact model ID. Effort stays per provider: low through max for Claude, Codex, and Grok; fixed default for Cursor, Antigravity, OpenCode, and Devin UIDs, whose effort is part of the ID; the legacy devin:swe-2@medium|high|max and devin:swe-1.6@default mappings unchanged. Matrix rows keep their Selectable efforts guidance for the listed families. An invalid descriptor, out-of-domain effort, duplicate role, or unknown role is inconsistent state; never mutate an unknown model into a matrix family name or substitute a different model for the selected one. Show the conflicting rows verbatim and resolve them through an explicit provider-qualified descriptor or alias replacement before probing or writing.

Within one seat, attempt -> attempt is an ordered chain with at most three attempts. Different models on the same provider are valid. Reject repeated descriptors, the same provider/model at different efforts, and an alias together with a descriptor on the parent's provider. Why and Reflect rows may contain aliases only. A seat's commas still mean independent lanes; chains never merge seats. Each Codex attempt under a Codex parent uses native spawn_agent with its exact model and effort, including fallbacks.

Use the resulting efforts from step 3 as the requested efforts. unlimited has no replacement target and never resets an existing effort to max. Collect a different effort only when the operator requests an override, a newly assigned model needs a choice, or the resulting map has a conflict. Name the model, its valid efforts for that provider, and its current value; propose the matrix Default effort for a matrix family and high for another Claude, Codex, or Grok model. Empty input keeps that value. If the resulting roles use mixed efforts for one provider/model, show all conflicting rows and ask for one effort from its valid set. Do not invent precedence. Honor efforts the operator already explicitly selected.

An effort-only rerun preserves each role's family and lane order. Rewrite every occurrence of an assigned family to its selected effort; leave aliases unchanged. If every role uses an alias, there are no family effort questions or model-pair probes.