diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index 6bfbc7b..cba9c6e 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -1,19 +1,65 @@ -# Set up pstack in Codex +# Set up pstack -Open this checkout in a fresh Codex session. Project skills are discovered from `.agents/skills/`. See the [README](../../README.md#install) for installing into another project or using the plugin manifest. +In this page you install the plugin, pick which models pstack uses, and run your first task. Setup is one command plus a short conversation. -Run `$pstack:setup-pstack`. Every unconfigured role inherits the current Codex model and reasoning. Setup can select explicit models and separate reasoning levels only when the host confirms they are available. Project configuration lives at `.agents/pstack-models.md`; personal configuration, when requested, lives at `~/.agents/pstack-models.md`. Pstack reads the file itself; it is not a host rule and needs no restart. +## Install the plugin -Panel roles use comma-separated lists, with one worker per entry, including `inherit-parent`. A cross-judge pool selects one judge. Two workers using the same model are independent perspectives, not a multi-model comparison. Start with the inherited defaults and change only the roles you need. +From any directory, run: -Setup offers `$pstack:create-verification-skill` if the project has no real-app harness, and `$pstack:create-formal-verification-skill` if a critical property would benefit from a proof or model checker. Both are optional. Generated skills go in `.agents/skills/`. +```bash +codex plugin marketplace add pstack-ports/codex-pstack +codex plugin add pstack@codex-pstack +``` + +Start a new Codex session in the project where you want to use pstack. The installed skills appear as `pstack:`, such as `$pstack:setup-pstack`. The [Codex adapter](../harness/codex.md) covers the other differences. + +## Pick your models + +Run: + +```text +/setup-pstack +``` + +[`/setup-pstack`](../../.agents/skills/setup-pstack/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 `.agents/pstack-models.md` in the active project, or `~/.agents/pstack-models.md` when you ask for personal settings, 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. + +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-pstack` 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-pstack` again. + +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. -Start a task with: +## Accept the verification offers, or don't + +At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../.agents/skills/create-verification-skill/SKILL.md). + +Say yes and it writes `.agents/skills/verify-/`, a project-local skill that teaches agents to drive your app the way a user does. It proves the skill works once before handing it over. Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers it in depth. + +If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most. + +Then setup offers once to generate a formal verification skill with [`/create-formal-verification-skill`](../../.agents/skills/create-formal-verification-skill/SKILL.md), unless the project already has one. Tests check the cases someone thought to write. A formal verification skill checks one key property of your code, such as "a job never runs twice at once", in every case within a stated scope. Say yes when your code has concurrency, retries, a state machine, or a parser, where a bug is costly and tests rarely reach the case that breaks. Otherwise say no, and run it later if that changes. [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers it. + +After setup, the next pstack task reads the file. A restart is unnecessary. + +## Keep the cost in check + +pstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer: + +- Rerun `/setup-pstack` and pick a smaller reasoning budget or cheaper models. A strong model in the main chat with cheaper, faster models in the code roles is a good split. +- Set a role to `auto` or `inherit-parent` so it runs on the chat's own model. +- Shorten a panel list. Each entry runs one subagent. +- Save `/poteto-mode` for work that needs rigor. A small, obvious edit doesn't. + +## Run your first task + +Pick something real but small, and describe it the way you'd describe it to a colleague: ```text -$pstack:poteto-mode add a --json flag to this command. text output stays byte-identical. verify both. +/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both. ``` -Pstack chooses a playbook, tracks its steps, and uses the [Codex adapter](../harness/codex.md) for tools and delegation. Start each new task that needs this workflow with `$pstack:poteto-mode`. Long-running goals and scheduled/event-driven work require a facility actually available in your host. +Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/poteto-mode` skips a step, the step stays in the list with `skip: `, so you can see what it chose not to do. + +From here you can type normal follow-ups. Invoke `$pstack:poteto-mode` for each task that needs it. -Next: [Route work through poteto-mode](./02-poteto-mode.md). +Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).