diff --git a/README.md b/README.md index 74e01dc..8ea76cf 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,8 @@ needs delegation or OMP-specific lifecycle behavior. The runtime adapter maps canonical pstack roles to OMP's bundled task agents (`scout`, `reviewer`, `security-reviewer`, `task`, `sonic`) and to the `planner`, `designer`, and `librarian` agents this package ships in `agents/`. +The package also ships an agent for each config line that needs its own model, +such as `pstack-hardest` and the panel seats `pstack-runner-1` to `3`. Missing integrations are reported honestly and fail closed; for example, Benny requires an available Slack/tracker/control adapter rather than pretending those tools exist. @@ -72,8 +74,10 @@ $setup-pstack It detects the models and task agents your OMP session actually exposes, lets you choose the defaults for implementation and review work, and writes concrete `provider/model-id` assignments to `.pstack/config.md` (or to `$PSTACK_CONFIG` -when set). Model routing itself lives in OMP settings (`modelRoles`, -`task.agentModelOverrides`); the configuration file is the portable record. +when set). It also writes each agent's model to `task.agentModelOverrides` in +your global OMP config. pstack never names a model on a task call. Before each +spawn it checks that the agent's override matches the config line, and it stops +when they differ. Then route your first real task through the main workflow: diff --git a/agents/pstack-hardest.md b/agents/pstack-hardest.md new file mode 100644 index 0000000..49f8cfd --- /dev/null +++ b/agents/pstack-hardest.md @@ -0,0 +1,28 @@ +--- +name: pstack-hardest +description: "pstack delegate for the hardest code changes: cross-cutting design, gnarly concurrency, and subtle algorithms. Runs on the `hardest tasks` line's model." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-hardest" +thinkingLevel: high +read-summarize: false +--- + +# Hardest tasks + +You are the pstack `implementer` for a change the root rated among the hardest it delegates. Name the data shape and the invariants it must hold before you write logic, and keep the change as small as the brief allows. + +Follow the standalone brief exactly. Write only to the paths, worktree, or branch it assigns. When the brief leaves a decision open, resolve it from source, standing policy, or frozen evidence. Otherwise take the safest reversible reading and report it as an assumption. + +Do not call `task`, start children, or ask the user directly. Run only the verification the brief names, and report only checks you executed. Finish through `yield` with `PASS`, `ISSUES`, or `BLOCKED`, the changed files, verification results, deviations, and unresolved risks. diff --git a/agents/pstack-judge-1.md b/agents/pstack-judge-1.md new file mode 100644 index 0000000..a82a296 --- /dev/null +++ b/agents/pstack-judge-1.md @@ -0,0 +1,23 @@ +--- +name: pstack-judge-1 +description: "pstack arena cross-judge for entry 1 of the `arena cross-judge pool` line. Read-only." +tools: + - read + - grep + - glob + - find + - bash + - yield +model: + - "@pstack-judge-1" +thinkingLevel: high +read-summarize: false +--- + +# Arena judge 1 + +You are the cross-judge of an `arena` run. Score each candidate against the rubric the brief passes, criterion by criterion, and recommend a base with your rationale. The brief names candidates by path label only. + +You are read-only. Use the shell only to read. Change no files, branches, settings, or external state. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with the scores, the recommended base, and the evidence for each score. diff --git a/agents/pstack-judge-2.md b/agents/pstack-judge-2.md new file mode 100644 index 0000000..861f12a --- /dev/null +++ b/agents/pstack-judge-2.md @@ -0,0 +1,23 @@ +--- +name: pstack-judge-2 +description: "pstack arena cross-judge for entry 2 of the `arena cross-judge pool` line. Read-only." +tools: + - read + - grep + - glob + - find + - bash + - yield +model: + - "@pstack-judge-2" +thinkingLevel: high +read-summarize: false +--- + +# Arena judge 2 + +You are the cross-judge of an `arena` run. Score each candidate against the rubric the brief passes, criterion by criterion, and recommend a base with your rationale. The brief names candidates by path label only. + +You are read-only. Use the shell only to read. Change no files, branches, settings, or external state. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with the scores, the recommended base, and the evidence for each score. diff --git a/agents/pstack-judge-3.md b/agents/pstack-judge-3.md new file mode 100644 index 0000000..314cbd7 --- /dev/null +++ b/agents/pstack-judge-3.md @@ -0,0 +1,23 @@ +--- +name: pstack-judge-3 +description: "pstack arena cross-judge for entry 3 of the `arena cross-judge pool` line. Read-only." +tools: + - read + - grep + - glob + - find + - bash + - yield +model: + - "@pstack-judge-3" +thinkingLevel: high +read-summarize: false +--- + +# Arena judge 3 + +You are the cross-judge of an `arena` run. Score each candidate against the rubric the brief passes, criterion by criterion, and recommend a base with your rationale. The brief names candidates by path label only. + +You are read-only. Use the shell only to read. Change no files, branches, settings, or external state. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with the scores, the recommended base, and the evidence for each score. diff --git a/agents/pstack-judgment.md b/agents/pstack-judgment.md new file mode 100644 index 0000000..5b01707 --- /dev/null +++ b/agents/pstack-judgment.md @@ -0,0 +1,28 @@ +--- +name: pstack-judgment +description: "pstack delegate for judgment calls and prose: PR descriptions, docs, replies, and advisory verdicts. Runs on the `judgment and prose` line's model." +tools: + - read + - grep + - glob + - find + - bash + - web_search + - edit + - write + - yield +model: + - "@pstack-judgment" +thinkingLevel: high +read-summarize: false +--- + +# Judgment and prose + +You write the prose or make the judgment call the brief asks for. Ground every claim in a file, a command you ran, or a cited source, and mark anything you inferred as an inference. + +Write in short declarative sentences with plain words. Apply the `unslop` skill to everything you write, and the `technical-writing` skill to docs, PR descriptions, and commit messages. + +Write only to the output paths the brief assigns. When the brief asks for a verdict and not a file, change nothing. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with `PASS`, `ISSUES`, or `BLOCKED`, the prose or verdict, the evidence behind it, and open questions for the root. diff --git a/agents/pstack-reflect-tooling.md b/agents/pstack-reflect-tooling.md new file mode 100644 index 0000000..292b6c9 --- /dev/null +++ b/agents/pstack-reflect-tooling.md @@ -0,0 +1,23 @@ +--- +name: pstack-reflect-tooling +description: "pstack reviewer for the tooling lens of the reflect skill. Read-only. Runs on the `reflect tooling` line's model." +tools: + - read + - grep + - glob + - find + - bash + - yield +model: + - "@pstack-reflect-tooling" +thinkingLevel: high +read-summarize: false +--- + +# Reflect tooling reviewer + +You are the tooling reviewer of the `reflect` skill. Follow the prompt template the brief passes, which is `skills/reflect/references/tooling-reviewer.md`. + +You are read-only. Use the shell only to read. Change no files, branches, settings, or external state. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with the findings the template asks for, each with its evidence. diff --git a/agents/pstack-runner-1.md b/agents/pstack-runner-1.md new file mode 100644 index 0000000..892f2a7 --- /dev/null +++ b/agents/pstack-runner-1.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-1 +description: "pstack runner 1, pinned to entry 1 of the runner config lines. Runs one standalone brief." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-1" +thinkingLevel: high +read-summarize: false +--- + +# Runner 1 + +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. + +Write only to the worktree or output path the brief assigns. + +Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for. diff --git a/agents/pstack-runner-2.md b/agents/pstack-runner-2.md new file mode 100644 index 0000000..ef5d5c0 --- /dev/null +++ b/agents/pstack-runner-2.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-2 +description: "pstack runner 2, pinned to entry 2 of the runner config lines. Runs one standalone brief." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-2" +thinkingLevel: high +read-summarize: false +--- + +# Runner 2 + +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. + +Write only to the worktree or output path the brief assigns. + +Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for. diff --git a/agents/pstack-runner-3.md b/agents/pstack-runner-3.md new file mode 100644 index 0000000..10e13ac --- /dev/null +++ b/agents/pstack-runner-3.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-3 +description: "pstack runner 3, pinned to entry 3 of the runner config lines. Runs one standalone brief." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-3" +thinkingLevel: high +read-summarize: false +--- + +# Runner 3 + +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. + +Write only to the worktree or output path the brief assigns. + +Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for. diff --git a/agents/pstack-swarm-worker.md b/agents/pstack-swarm-worker.md new file mode 100644 index 0000000..dd706e1 --- /dev/null +++ b/agents/pstack-swarm-worker.md @@ -0,0 +1,26 @@ +--- +name: pstack-swarm-worker +description: "pstack swarm worker. Runs one slice, race arm, or verification lane of the swarm skill on the `swarm workers` line's model." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-swarm-worker" +thinkingLevel: high +read-summarize: false +--- + +# Swarm worker + +You run one slice, race arm, or verification lane of the `swarm` skill. Do only your slice, and write only to the output path the brief assigns. When the brief names commits or a measurement method, record both in your result. + +Do not call `task`, start children, or ask the user directly. Run only the verification the brief names, and report only checks you executed. Finish through `yield` with `PASS`, `ISSUES`, or `BLOCKED`, the result in the schema the brief asks for, and its evidence. diff --git a/scripts/verify.mjs b/scripts/verify.mjs index 639254b..da754a2 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -195,7 +195,7 @@ for (const path of skillFiles) { } const ompBundledAgents = new Set(["scout", "reviewer", "security-reviewer", "task", "sonic"]); -const packageAgents = new Set(); +const packageAgents = new Map(); for (const entry of await readdir(join(root, "agents"))) { if (!entry.endsWith(".md")) continue; const path = join(root, "agents", entry); @@ -209,12 +209,46 @@ for (const entry of await readdir(join(root, "agents"))) { failures.push(`${relative(root, path)} is missing frontmatter ${key}`); } } - packageAgents.add(name); + const list = (key) => [...(frontmatter.match(new RegExp(`^${key}:\\n((?: - .*\\n?)*)`, "mu"))?.[1] ?? "").matchAll(/^ - "?([^"\n]+)"?$/gmu)].map((match) => match[1]); + packageAgents.set(name, { path, tools: list("tools"), models: list("model") }); +} +for (const [name, agent] of packageAgents) { + if (!name.startsWith("pstack-")) continue; + // A second model, or a role something else sets, would let the agent run without its override. + if (agent.models.length !== 1 || agent.models[0] !== `@${name}`) { + failures.push(`${relative(root, agent.path)} must name only its own role, @${name}, as its model`); + } + if (name.startsWith("pstack-judge-") && agent.tools.some((tool) => tool === "edit" || tool === "write")) { + failures.push(`${relative(root, agent.path)} is a judge and must not have edit or write`); + } } const adapterPath = join(skillsRoot, "pstack-omp", "SKILL.md"); const adapter = await readFile(adapterPath, "utf8"); const roster = adapter.match(/The reference roster is closed:\n\n```text\n([\s\S]*?)\n```/u)?.[1]; -const mappedAgents = [...adapter.matchAll(/^\| `[a-z]+` \| `([a-z-]+)` \|/gmu)].map((match) => match[1]); +const PANEL_SEATS = 3; +const lineAgents = new Map( + [...adapter.matchAll(/^\| `([a-z ,-]+)` \| `([a-z<>N-]+)` \|$/gmu)].map((match) => [match[1], match[2]]), +); +const mappedAgents = [ + ...[...adapter.matchAll(/^\| `[a-z]+` \| `([a-z-]+)` \|/gmu)].map((match) => match[1]), + ...[...lineAgents.values()].flatMap((agent) => + agent.includes("") ? Array.from({ length: PANEL_SEATS }, (_, i) => agent.replace("", String(i + 1))) : [agent], + ), +]; +const setupPath = join(skillsRoot, "setup-pstack", "SKILL.md"); +const configShape = (await readFile(setupPath, "utf8")).match(/^```\n# pstack model configuration[\s\S]*?\n```/mu)?.[0] ?? ""; +const configLines = [...configShape.matchAll(/^([a-z][a-z ,-]*): /gmu)].map((match) => match[1]); +if (configLines.length === 0) failures.push(`${relative(root, setupPath)} has no config shape to check routing against`); +for (const line of configLines) { + if (!lineAgents.has(line)) { + failures.push(`${relative(root, adapterPath)} has no Model routing row for the ${line} line in ${relative(root, setupPath)}`); + } +} +for (const line of lineAgents.keys()) { + if (!configLines.includes(line)) { + failures.push(`${relative(root, adapterPath)} routes ${line}, which is not a line in ${relative(root, setupPath)}`); + } +} if (!roster) failures.push(`${relative(root, adapterPath)} is missing the closed agent roster`); for (const agent of new Set([...(roster?.split("\n") ?? []), ...mappedAgents])) { if (!ompBundledAgents.has(agent) && !packageAgents.has(agent)) { diff --git a/skills/architect/SKILL.md b/skills/architect/SKILL.md index a07a340..139e371 100644 --- a/skills/architect/SKILL.md +++ b/skills/architect/SKILL.md @@ -30,7 +30,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst 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 `$PSTACK_CONFIG (or .pstack/config.md)`, in place of the `arena runners` line. If the configuration or that line is missing, use the canonical `planner` and `implementer` roles. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A. +Take the runners from the `architect runners` line in `$PSTACK_CONFIG (or .pstack/config.md)`, in place of the `arena runners` line. If the configuration or that line is missing, use the canonical `planner` and `implementer` roles. Route each entry and handle a stopped or failed seat as the **arena** skill's Phase A step 3 says. 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. diff --git a/skills/arena/SKILL.md b/skills/arena/SKILL.md index fe46952..db607d3 100644 --- a/skills/arena/SKILL.md +++ b/skills/arena/SKILL.md @@ -16,7 +16,7 @@ Every candidate gets the same prompt, so the prompt is the contract. 1. State the artifact each candidate is producing. 2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task. -3. Pick the runners. Use the `arena runners` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, default to one each on the canonical `planner` and `implementer` roles. An `auto` or `inherit-parent` entry in this line means the parent model. If the host task runner rejects a configured entry, run that seat on its family's default and say so. Families go by canonical role: an entry belongs to the role it fills, and that role is its default. If the family has no default, or the host task runner rejects that default, use the closest valid agent of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. +3. Pick the runners. Use the `arena runners` line in `$PSTACK_CONFIG (or .pstack/config.md)`, and start entry N on its seat agent per the Model routing section of the **pstack-omp** skill. If the configuration or that line is missing, default to one each on the canonical `planner` and `implementer` roles. If that section's check stops a seat, or the spawn fails, stop and report it. Do not run the seat on another model. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-/candidate-/`), per the **separate-before-serializing-shared-state** principle skill. ## Phase B: Fan out @@ -27,7 +27,7 @@ If a candidate produces no output, proceed with N-1 and note the dropout. ## Phase C: Cross-judge -After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, choose from the canonical `reviewer` and `planner` roles. Spawn one readonly judge subagent. The judge is never from the parent's family. Here a family is the model an entry resolves to through the host's model settings, not the canonical role from Phase A step 3, because the parent fills no role. Try only the entries from another family, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. If the host task runner rejects an entry, use a valid slug of the same model at the closest level or speed from the error message, or move to the next entry when there is none. If no entry from another family runs, try the default pool's entries from another family the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If you do not know the parent's model, try the pool's real slugs in pool order and say that the family check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. +After all Phase B candidates complete, choose one entry from the `arena cross-judge pool` line in `$PSTACK_CONFIG (or .pstack/config.md)`, and start entry N on its judge agent per the Model routing section of the **pstack-omp** skill. If the configuration or that line is missing, choose from the canonical `reviewer` and `planner` roles. Spawn one readonly judge subagent. The judge is never from the parent's family. Here a family is the model an entry names, not the canonical role from Phase A step 3, because the parent fills no role. Try only the entries from another family, in pool order. If that section's check stops an entry, or its spawn fails, report it and move to the next entry. If no entry from another family runs, skip the judge, pick the base alone in Phase D, and say so. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. ## Phase D: Pick a base diff --git a/skills/how/SKILL.md b/skills/how/SKILL.md index ca7d025..aae2da8 100644 --- a/skills/how/SKILL.md +++ b/skills/how/SKILL.md @@ -10,7 +10,7 @@ Follow the [portable runtime contract](../pstack-omp/references/runtime.md) for Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code. -Every spawn is a read-only host task runner subagent. Explorers use the `how explorer` line in `$PSTACK_CONFIG (or .pstack/config.md)` (default role `explorer`), and every explainer uses the `how explainer` line (default role `synthesizer`). Spawn each in its default role. OMP applies the line's value through its model settings, never a `model` field on the task, and runs the role's default model if the configuration or the line is missing. An `auto` or `inherit-parent` value means the parent model. If the host task runner rejects a slug, use the default and say so. If it rejects the default, use the closest valid agent for that role from its error message. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. +Every spawn is a read-only host task runner subagent. Explorers use the `how explorer` line in `$PSTACK_CONFIG (or .pstack/config.md)` (default role `explorer`), and every explainer uses the `how explainer` line (default role `synthesizer`). Start the agent the Model routing section of the **pstack-omp** skill names for each line, and use the role's default agent if the configuration or the line is missing. If that section's check stops a spawn, or the spawn fails, stop and report it. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. ## 1. Assess complexity diff --git a/skills/poteto-help/SKILL.md b/skills/poteto-help/SKILL.md index c0846ca..beba4ca 100644 --- a/skills/poteto-help/SKILL.md +++ b/skills/poteto-help/SKILL.md @@ -41,7 +41,7 @@ When the model config is missing and it matters, ask whether the user wants to p Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. The [README](../../README.md) and [guide page 1](https://github.com/cursor/plugins/blob/main/pstack/docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md). -If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor. +If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor. This package is the OMP port of pstack. The [`pstack-omp`](../pstack-omp/SKILL.md) skill maps pstack's roles, delegation, and lifecycle to OMP task agents. The upstream guide also describes Cursor-only features, such as Custom Modes, `/loop`, and cloud agents, that OMP does not have. diff --git a/skills/poteto-mode/SKILL.md b/skills/poteto-mode/SKILL.md index 7a10f31..e7e3fa9 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -111,9 +111,9 @@ Use these canonical roles: Use only these canonical lifecycle protocols: **Bounded session**, **Panel**, **Long-lived owner**, and **One-shot watcher**. Their mechanics live in the active adapter. A child never starts another child; it returns proposed briefs to the root. -**Defaults for every child.** Background runs (a steer or resume of a running agent too, because a foreground call holds your turn while other reports wait), file pointers not inlined context, model per role from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`), never a `model` field on the task (configurable via `/setup-pstack`. Defaults come from OMP's model settings). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (the `hardest tasks` line), whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to the `mechanical` role. Per-role lines in `$PSTACK_CONFIG` (or `.pstack/config.md`) override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model. Each code playbook's configured model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`. +**Defaults for every child.** Background runs (a steer or resume of a running agent too, because a foreground call holds your turn while other reports wait), file pointers not inlined context, model per role from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`), routed by the active adapter (configurable via `/setup-pstack`). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (the `hardest tasks` line), whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to the `mechanical` role. Per-role lines in `$PSTACK_CONFIG` (or `.pstack/config.md`) override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default. Each code playbook's configured model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`. -**Match the effort to the job.** Before each start, begin from the role's line in `$PSTACK_CONFIG` (or `.pstack/config.md`), or the OMP default when the role has no line, and pick the reasoning level the job needs. The `# budget` line that `/setup-pstack` writes sets each role's starting level, `xhigh` by default. Raise it one step, up to `max`, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Apply the level through the host task runner's effort setting when the host exposes it. Otherwise the role's configured level stands. Verification is the exception and stays on the `swarm workers` line at its configured level. Change only the effort level and keep the model the role names, so a diverse panel stays diverse. If that model has no setting at the chosen level, use its nearest one. A role on `auto` or `inherit-parent` stays on the parent model. If the host task runner rejects the adjusted level, do not try another one. Use the role's configured level and say so. If the host task runner rejects that too, continue with the calling skill's fallback. A choice counts as rejected once a task error says it is not valid, or leaves it out of its list of valid choices. Never pass a rejected choice, and skip any fallback the host already rejected. When the calling skill has no fallback, use the closest valid choice for the role from the error's list, or omit the effort setting so the child runs at the host's default when the list has none. When the calling skill's fallback runs out without saying what to do next, omit the effort setting too. Say so in both cases. +**Match the effort to the job.** A spawn for a role with a line in `$PSTACK_CONFIG` (or `.pstack/config.md`) runs at the level its agent's override sets, so send no effort setting for it. To change that level, change the line and re-run `/setup-pstack`. For a role with no line, pick the reasoning level the job needs. Raise it one step, up to `max`, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Apply the level through the host task runner's effort setting when the host exposes it. Otherwise the agent's own level stands. If the host task runner rejects the level, omit the effort setting and say so. You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same prompt against a different model. Agreement is high-signal. diff --git a/skills/poteto-mode/playbooks/orchestrate.md b/skills/poteto-mode/playbooks/orchestrate.md index b454465..ff2bf50 100644 --- a/skills/poteto-mode/playbooks/orchestrate.md +++ b/skills/poteto-mode/playbooks/orchestrate.md @@ -19,7 +19,7 @@ Run it with your own tools. Spawn workers through the host task runner in canoni - **Read the diff or the artifact, not only the worker's summary.** Green CI is an input to a verdict, not a verdict. Behavioral work needs more than a type check. A verdict covers one head SHA, so a new push needs a new verdict. Read a sample of each sub-coordinator's kickoffs while its workers run, and fix its instructions when one fails. - **Send back work that drifts from scope or grows past what was asked.** Keep only the fixes that block the program, and park the rest as follow-ups. - **Check a PR's live state before you report on it,** with `gh pr view` and `gh pr checks` or your forge's equivalents, not the worker's last report. Account for every worker you spawned as done, replaced, or absorbed into another worker's scope. -- **Stop or replace a worker that stalls or loops.** Judge it by its pushes and PR activity, not its status text. Retry by cause: a smaller scope after a context or memory limit, the same kickoff after a dropped connection, and a different model after a tool error. After two retries, drop the unit and replan around it. When a stopped worker returns late, check its result against the PR's current state, and hand any unique findings to a fresh worker. +- **Stop or replace a worker that stalls or loops.** Judge it by its pushes and PR activity, not its status text. Retry by cause: a smaller scope after a context or memory limit, and the same kickoff after a dropped connection or a tool error. Never retry on another model. After two retries, drop the unit and replan around it. When a stopped worker returns late, check its result against the PR's current state, and hand any unique findings to a fresh worker. - **Ask the user only for a real decision or a blocker,** such as an irreversible action, a product or preference call that no experiment settles, or a dead end that survived a replan. Rebase mechanics, retries, CI flakes, review triage, and "should I keep going" never reach the user. **Reply:** what landed against the goal, each PR's live state and verdict with its link, what was dropped and why, and the decisions waiting on the user. diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index d2d4a9b..1671c16 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -13,7 +13,8 @@ While this skill is active, its role map is the specific pstack execution contra Use the live host's configured names. This mapping targets OMP's bundled task agents plus the `planner`, `designer`, and `librarian` agents this package ships -in `agents/`. +in `agents/`. The package also ships one agent for each config line that cannot +share an agent's model. Model routing maps config lines to agents. | Canonical role | OMP agent | Contract | |---|---|---| @@ -39,6 +40,16 @@ security-reviewer librarian task sonic +pstack-hardest +pstack-judgment +pstack-reflect-tooling +pstack-swarm-worker +pstack-runner-1 +pstack-runner-2 +pstack-runner-3 +pstack-judge-1 +pstack-judge-2 +pstack-judge-3 ``` A canonically routed task item's `agent` value must be one of those names. Canonical role labels and model aliases are not agent names. @@ -225,24 +236,35 @@ The root resolves a child question and sends the answer through `write agent://< ## Model routing -OMP resolves a task agent through its current settings, including `modelRoles`, `task.agentModelOverrides`, the agent definition, and normal fallback. Agent selection and model selection are separate decisions. +pstack never names a model on a task call. Each agent runs on its `task.agentModelOverrides` entry, which `/setup-pstack` writes from `$PSTACK_CONFIG` (or `.pstack/config.md`). Do not put a `model` field in a task item, and do not use a model alias as the `agent` value. -Do not put a `model` field in a task item. Do not use a model alias as the `agent` value. Configure routing through the installed OMP settings and report the actual resolved model when independence matters. +A spawn for a config line starts the agent below. Entry N of a panel line starts seat agent N. A role with no config line uses the canonical role map. -Recommended role aliases: - -| OMP agent | Recommendation | +| Config line | Agent | |---|---| -| `scout` | `@smol` | -| `planner` | `@plan` | -| `designer` | `@plan` | -| `reviewer` | `@advisor` | -| `security-reviewer` | `@advisor` | -| `librarian` | `@smol` | -| `task` | `@task` or a stronger implementation role | -| `sonic` | `@tiny` or `@smol` | - -These are recommendations, not task payload fields. +| `feature, refactoring` | `task` | +| `bug-fix` | `task` | +| `perf-issue` | `task` | +| `hillclimb` | `task` | +| `judgment and prose` | `pstack-judgment` | +| `hardest tasks` | `pstack-hardest` | +| `how explorer` | `scout` | +| `how explainer` | `reviewer` | +| `why investigators` | `librarian` | +| `why synthesizer` | `reviewer` | +| `reflect tooling` | `pstack-reflect-tooling` | +| `reflect judgment, divergent, synthesizer` | `reviewer` | +| `swarm workers` | `pstack-swarm-worker` | +| `arena runners` | `pstack-runner-` | +| `architect runners` | `pstack-runner-` | +| `interrogate reviewers` | `pstack-runner-` | +| `arena cross-judge pool` | `pstack-judge-` | + +Before each spawn for a config line, read `cfg://task/agentModelOverrides` and compare the agent's entry with the line's value, or with entry N for a panel line. If the entry is missing or differs, stop. Name the line, the agent, and both values, and tell the user to run `/setup-pstack`. A panel line with more entries than its three seats stops the same way. To run one model more than once, start its seat again. + +Lines that share an agent must name the same model and level, and the comparison enforces it. `inherit-parent` and `auto` are not valid values, because an override needs a concrete model. + +Send no `effort` on a spawn for a config line, because the override sets the level and `effort` would replace it. If a spawn fails, report the error. Never start the role on another agent or model. Report the resolved model when independence matters. ## Writing diff --git a/skills/pstack-omp/references/runtime.md b/skills/pstack-omp/references/runtime.md index 29d791d..5fbf36e 100644 --- a/skills/pstack-omp/references/runtime.md +++ b/skills/pstack-omp/references/runtime.md @@ -28,9 +28,8 @@ child, review, transcript, or live check happened unless OMP reported it. | `mechanical` | Fully specified low-judgment edits. | Map these roles to OMP's bundled task agents (`scout`, `reviewer`, -`security-reviewer`, `task`, `sonic`) and to the `planner`, `designer`, and -`librarian` agents this package ships in `agents/`. The live `task` inventory -wins over this document. +`security-reviewer`, `task`, `sonic`) and to the agents this package ships in +`agents/`. The live `task` inventory wins over this document. Every child brief must stand alone. It must name its goal, role, writable scope, acceptance criteria, verification command, forbidden scope, and report format. A @@ -41,14 +40,15 @@ delegation and the active playbook requires it. Model inventory is not model delegation. OMP resolves a task agent's model through its settings (`modelRoles`, `task.agentModelOverrides`, the agent -definition, and normal fallback), not through the task payload. Agent selection -and model selection are separate decisions: do not put a `model` field in a task -item and do not use a model alias as the `agent` value. - -Use concrete `provider/model-id` values in configuration only when OMP's live -model inventory reported them. `inherit-parent` runs a role on the parent chat -model; a missing role entry means the OMP default. A panel is a list of role or -model choices, and its size controls fan-out. +definition, and normal fallback), not through the task payload. Do not put a +`model` field in a task item and do not use a model alias as the `agent` value. +Each config line runs on the agent the Model routing section of the +`pstack-omp` skill names, and that agent's `task.agentModelOverrides` entry +must equal the line's value, or the spawn stops. + +Use concrete `provider/model-id:level` values in configuration only when OMP's +live model inventory reported them. A missing line means the role's default +agent. A panel is a list of up to three models, and its size controls fan-out. The optional configuration path is `$PSTACK_CONFIG`. If it is unset, use `.pstack/config.md` in the current project for project-local settings. Do not diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index 2c105cc..c9e3e0d 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -24,9 +24,9 @@ That covers the session (`_.jsonl`) and subagent (`_ `xhigh` > `high` > `medium` > `low`. If the model does not support that level, use its highest supported level at or below the target, else mark the role as needing a choice. `inherit-parent` and `auto` do not change. So `unlimited` turns `:xhigh` into `:max`. A model that tops out at `xhigh` stays at `xhigh` under `unlimited`. `large` keeps the defaults. `small` turns every default into `:medium`. +**(b) Apply it.** Build the working table from the skill defaults, and on a re-run keep any role you changed by family or list. `unlimited`, `large`, `medium`, and `small` set the effort level of every real model, panel entries included, to `max`, `xhigh`, `high`, or `medium`. The effort level is the model's `:level` suffix, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. If the model does not support that level, use its highest supported level at or below the target, else mark the role as needing a choice. So `unlimited` turns `:xhigh` into `:max`. A model that tops out at `xhigh` stays at `xhigh` under `unlimited`. `large` keeps the defaults. `small` turns every default into `:medium`. -**(c) Show the roles and confirm.** Show every role with its model, marking any real model 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) as the options. Prefer structured interaction tool 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 from a family 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. +**(c) Show the roles and confirm.** Show every role with its model, marking any real model 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 as the options. Prefer structured interaction tool over free text. For panel roles (arena runners, architect runners, interrogate reviewers) the value is a list of up to three models, and one subagent runs per entry, so the list length sets the count. `arena cross-judge pool` is also a list of up to three, but Arena runs one judge. It tries only values from a family other than the parent's, in list order, so order it by preference. `swarm workers` is the default model for every worker unless a race or comparison assigns another model per arm. If the live session exposes models but no usable task facility, stop model mapping with an explicit capability report naming the missing capability. Say that no pstack role can receive a different model in this session and do not present the portable defaults as an assignment or overwrite an existing role configuration with inactive aliases. ### 4. Validate -Every real model written must be in the detected set. Role aliases pass only when the host task facility documents those aliases. `inherit-parent` and `auto` pass only when the host can pass the current model to a child. If a chosen real model is not available, stop and ask again. +Every real model written must be in the detected set. If a chosen real model is not available, stop and ask again. Then refuse to write, and say which lines to change, when any of these holds: + +- A value is `inherit-parent`, `auto`, or a role alias. An override needs a concrete model. +- A panel line has more than three entries. +- Two lines that the Model routing section maps to one agent name different values, such as `feature, refactoring` and `bug-fix` on `task`. The same holds for entry N of `arena runners`, `architect runners`, and `interrogate reviewers`, which share `pstack-runner-`. +- A `retry.fallbackChains` entry, `default` included, covers a model in the config. It would let OMP switch a failing spawn to another model. +- An installed extension registers a `before_subagent_spawn` handler. It can replace a spawn's model. ### 5. Write the config -When the host supports per-child selection, write `$PSTACK_CONFIG (or .pstack/config.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. Each `` default is the model OMP resolves for the agent that role maps to in the `pstack-omp` role map. Shape: +Write `$PSTACK_CONFIG (or .pstack/config.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. Each `` default is the model OMP resolves for the agent that role maps to in the `pstack-omp` role map. 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. Alias entries in a panel list still count toward its fan-out. +# pstack model configuration. One line per role. A role with no line runs on its default agent's override. +# Each line runs on the agent the pstack-omp Model routing section names. /setup-pstack writes that agent's task.agentModelOverrides entry. # budget: large (xhigh) feature, refactoring: :xhigh bug-fix: :xhigh perf-issue: :xhigh hillclimb: :xhigh judgment and prose: :xhigh -hardest tasks: inherit-parent +hardest tasks: :max how explorer: :xhigh how explainer: :xhigh why investigators: :xhigh @@ -65,11 +71,11 @@ architect runners: :xhigh, :xhigh interrogate reviewers: :xhigh, :xhigh ``` -OMP routes a child's model through its settings, never through a task `model` field. Map each chosen value into `task.agentModelOverrides` for the agent its role maps to, preserving unrelated keys. Roles that map to the same agent share one model, so when their values differ, ask which one the agent keeps. +Then write `task.agentModelOverrides` in the global OMP config, preserving unrelated keys. Give each agent in the Model routing table the value of its config line, and give `pstack-runner-` and `pstack-judge-` entry N of their lines. Remove the entry for a seat agent whose lines have fewer entries. Keep the existing entries for agents no config line names, such as `planner`, `designer`, `security-reviewer`, and `sonic`, or ask for a model when one is missing. Re-read `cfg://task/agentModelOverrides` and confirm that every line matches its agent's entry. ### 6. Confirm -Tell the user the config was written and that it applies to new sessions. Re-running this skill updates it. If the session lacks per-child model selection, report that no role configuration was written or activated. Tell the user which model is active and how to switch it. +Tell the user the config and the overrides were written and that they apply to new sessions. Re-running this skill updates both. If the session cannot write the global OMP config, report that no override was written, so every spawn for a config line will stop until one is. Tell the user which model is active and how to switch it. ### 7. Offer a verification skill (optional) diff --git a/skills/swarm/SKILL.md b/skills/swarm/SKILL.md index f7033cb..b1ae73e 100644 --- a/skills/swarm/SKILL.md +++ b/skills/swarm/SKILL.md @@ -21,12 +21,12 @@ Open a todolist with one entry per phase before launching anything. 1. State the done predicate and the artifact or report the swarm must return. 2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning. -3. Pick the worker model from the `swarm workers` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, use the canonical `implementer` role. For `auto` or `inherit-parent`, the workers run on the parent model. If the host task runner rejects a slug, use the default and say so. If it rejects the default, use the closest valid agent for that role from its error message. For a model race, name each arm's model up front. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. +3. Start workers on the agent the Model routing section of the **pstack-omp** skill names for the `swarm workers` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, use the canonical `implementer` role. If that section's check stops a spawn, or the spawn fails, stop and report it. For a model race, start each arm on the seat agent for its model, per the same section. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. 4. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result. ## Phase B: Fan out -Spawn all N workers in one message in the canonical `implementer` role. For a model race, route each arm through an agent whose configured model differs, per the Model routing section of the **pstack-omp** skill, check each returned model identity, and report a capability gap when routing cannot realize the race. Set `isolated: true` when the task runner exposes `isolated`. Otherwise give each writer its own worktree or output path, or report that isolation is unavailable. Use `isolated: false` only when the worker needs access to something in the user's live checkout. +Spawn all N workers in one message on the agent the Model routing section of the **pstack-omp** skill names for the `swarm workers` line. For a model race, start each arm on a runner seat whose override names its model, per the same section, check each returned model identity, and stop when no seat runs a model the race needs. Set `isolated: true` when the task runner exposes `isolated`. Otherwise give each writer its own worktree or output path, or report that isolation is unavailable. Use `isolated: false` only when the worker needs access to something in the user's live checkout. When a worker must start from a non-default pushed branch, name that branch in its brief. diff --git a/skills/why/SKILL.md b/skills/why/SKILL.md index 64beba1..86fc790 100644 --- a/skills/why/SKILL.md +++ b/skills/why/SKILL.md @@ -10,7 +10,7 @@ Follow the [portable runtime contract](../pstack-omp/references/runtime.md) for Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape. -Each spawn below names a role line in `$PSTACK_CONFIG (or .pstack/config.md)` and a default role. Spawn it in that role. OMP applies the line's value through its model settings, never a `model` field on the task, and runs the role's default model if the configuration or the line is missing. An `auto` or `inherit-parent` value means the parent model. If the host task runner rejects a slug, use the default and say so. If it rejects the default, use the closest valid agent for that role from its error message. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. +Each spawn below names a role line in `$PSTACK_CONFIG (or .pstack/config.md)` and a default role. Start the agent the Model routing section of the **pstack-omp** skill names for that line, and use the role's default agent if the configuration or the line is missing. If that section's check stops a spawn, or the spawn fails, stop and report it. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill. Every spawn keeps MCP access. **Do not use a read-only mode that strips it.** That disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still shouldn't write anything.