From 4c1edd84fb5674272167b1fd1b118f4e33eb3c61 Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:49:11 +0700 Subject: [PATCH 1/6] feat(pstack-omp): run each role on its configured model through carrier agents A role whose configured model differs from its mapped agent's task.agentModelOverrides entry now runs on pstack-worker or pstack-reader, with the model named in the task call. A role that keeps its agent's model but changes the level sends effort instead. setup-pstack checks task.perCallModel, task.enableEffort and the modelRoles entries these need, and no longer rewrites task.agentModelOverrides for each role. --- README.md | 10 ++++++-- agents/pstack-reader.md | 26 +++++++++++++++++++ agents/pstack-worker.md | 28 +++++++++++++++++++++ skills/how/SKILL.md | 2 +- skills/poteto-mode/SKILL.md | 2 +- skills/pstack-omp/SKILL.md | 33 ++++++++++++++++++++++--- skills/pstack-omp/references/runtime.md | 13 ++++++---- skills/reflect/SKILL.md | 2 +- skills/setup-pstack/SKILL.md | 11 ++++++--- skills/why/SKILL.md | 2 +- 10 files changed, 111 insertions(+), 18 deletions(-) create mode 100644 agents/pstack-reader.md create mode 100644 agents/pstack-worker.md diff --git a/README.md b/README.md index 74e01dc..d2baa4c 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 two carriers, `pstack-worker` and `pstack-reader`. They +run a role on a model its usual agent does not run. 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,12 @@ $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). Each agent's own model lives in OMP settings +(`task.agentModelOverrides`). A role whose configured model differs from its +agent's runs on a carrier, with the model named in the task call. That needs +`task.perCallModel: on` and a `modelRoles` entry that names the model. A role +that only changes the level needs `task.enableEffort: true`. The setup skill +checks these and asks before it changes them. Then route your first real task through the main workflow: diff --git a/agents/pstack-reader.md b/agents/pstack-reader.md new file mode 100644 index 0000000..370216d --- /dev/null +++ b/agents/pstack-reader.md @@ -0,0 +1,26 @@ +--- +name: pstack-reader +description: "pstack carrier for read-only roles. Runs one standalone review, research, exploration, or judging brief on the model its caller names, for a role whose configured model its mapped agent does not run." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - yield +model: + - "@default" +thinkingLevel: high +read-summarize: false +--- + +# pstack reader + +You fill the canonical pstack role that the brief's ROLE section names, such as `reviewer`, `synthesizer`, `explorer`, or an arena cross-judge. Hold that role's contract as the brief states it. You carry the role only because its configured model differs from the model its usual agent runs. + +You are read-only. Do not change files, branches, or external state, and run only commands that leave them unchanged. Ground every finding in a file and line, a command you ran with its output, or a cited source. When the brief gives frozen evidence, judge that evidence and do not alter it. + +Do not call `task`, start children, or ask the user directly. Finish through `yield` with `PASS`, `ISSUES`, or `BLOCKED`, the findings or verdict, the evidence for each, the commands you ran, and open questions for the root. diff --git a/agents/pstack-worker.md b/agents/pstack-worker.md new file mode 100644 index 0000000..60dea22 --- /dev/null +++ b/agents/pstack-worker.md @@ -0,0 +1,28 @@ +--- +name: pstack-worker +description: "pstack carrier for roles that write files. Runs one standalone brief on the model its caller names, for a role whose configured model its mapped agent does not run." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@default" +thinkingLevel: high +read-summarize: false +--- + +# pstack worker + +You fill the canonical pstack role that the brief's ROLE section names, such as `implementer`, `planner`, or an arena runner. Hold that role's contract as the brief states it. You carry the role only because its configured model differs from the model its usual agent runs. + +Follow the standalone brief exactly. Write only to the paths, worktree, or branch it assigns, and keep its one-writer assignment. 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 or artifacts, verification results, deviations, and unresolved risks. diff --git a/skills/how/SKILL.md b/skills/how/SKILL.md index ca7d025..a9f5257 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`). Spawn each in its default role. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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. ## 1. Assess complexity diff --git a/skills/poteto-mode/SKILL.md b/skills/poteto-mode/SKILL.md index 7a10f31..1b66203 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -111,7 +111,7 @@ 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`. 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`. **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. diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index d2d4a9b..ff10831 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -13,7 +13,9 @@ 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 two carrier agents, `pstack-worker` and +`pstack-reader`, which run a role on a model its mapped agent does not run. See +Model routing. | Canonical role | OMP agent | Contract | |---|---|---| @@ -39,6 +41,8 @@ security-reviewer librarian task sonic +pstack-worker +pstack-reader ``` A canonically routed task item's `agent` value must be one of those names. Canonical role labels and model aliases are not agent names. @@ -227,9 +231,30 @@ The root resolves a child question and sends the answer through `write agent://< 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. -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 role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). OMP fixes each agent's model in `task.agentModelOverrides` and refuses a task item's `model` field for any agent with an entry there. Route each spawn in this order: -Recommended role aliases: +1. A missing line keeps the mapped agent and sends no `model` or `effort`. +2. A line of `inherit-parent` or `auto` starts the carrier with the parent's own `provider/model-id` in `model`. +3. For a real `provider/model-id:level`, read `cfg://task/agentModelOverrides`. When the mapped agent's entry names the same `provider/model-id`, start the mapped agent with no `model`: + - If the level matches the entry, send no `effort`. + - Otherwise send `effort` when it reaches the level. `lo`, `med`, and `hi` select the lowest, middle, and highest level the model supports. On `anthropic/claude-opus-5-5`, which supports `low` to `max`, they ran at `low`, `high`, and `max`. + - Any other level goes to step 4. +4. Otherwise start the carrier with the line's value in `model`. The `:level` suffix sets its effort. + +The carrier depends on what the role may do: + +| Roles | Carrier | +|---|---| +| `planner`, `designer`, `implementer`, `owner`, `mechanical`, and every panel seat that writes, such as arena and architect runners and interrogate adversaries | `pstack-worker` | +| `explorer`, `watcher`, `reviewer`, `researcher`, `synthesizer`, and arena's cross-judge | `pstack-reader` | + +A carrier's brief names the canonical role it fills in its ROLE section, because the carrier has no specialist prompt of its own. + +A `model` needs `task.perCallModel: on` and a chat role in the operator's `modelRoles` that names the model. An `effort` needs `task.enableEffort: true`. When OMP refuses a spawn for one of these, start the mapped agent with no `model` or `effort`, and tell the user which setting or role is missing. `/setup-pstack` adds them. A per-call worker never falls back to another model, so an unavailable model fails the spawn. Report that failure and do not retry silently on another model. + +Do not use a model alias as the `agent` value. Report the actual resolved model when independence matters. + +Recommended defaults for each agent's own model, set in `task.agentModelOverrides` or `modelRoles`: | OMP agent | Recommendation | |---|---| @@ -242,7 +267,7 @@ Recommended role aliases: | `task` | `@task` or a stronger implementation role | | `sonic` | `@tiny` or `@smol` | -These are recommendations, not task payload fields. +Leave `pstack-worker` and `pstack-reader` out of `task.agentModelOverrides`. An entry there makes OMP refuse every per-call model for that carrier. ## Writing diff --git a/skills/pstack-omp/references/runtime.md b/skills/pstack-omp/references/runtime.md index 29d791d..0fd5891 100644 --- a/skills/pstack-omp/references/runtime.md +++ b/skills/pstack-omp/references/runtime.md @@ -29,8 +29,9 @@ child, review, transcript, or live check happened unless OMP reported it. 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. +`librarian` agents this package ships in `agents/`. The package's +`pstack-worker` and `pstack-reader` carriers run a role on a model its mapped +agent does not run. 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,9 +42,11 @@ 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. +definition, and normal fallback). A role runs on its mapped agent when that +agent's override already names the role's model. Otherwise it runs on a carrier +with the model in the task item's `model` field. The Model routing section of +the `pstack-omp` skill gives the exact steps. 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 diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index 2c105cc..8a0fb65 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -26,7 +26,7 @@ That covers the session (`_.jsonl`) and subagent (`_: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. +Leave `task.agentModelOverrides` alone unless the user asks to change an agent's own default model. Roles that map to one agent may name different models, because a carrier runs each role whose model differs from its agent's. Write the settings and roles step 4 approved, preserving unrelated keys. ### 6. Confirm diff --git a/skills/why/SKILL.md b/skills/why/SKILL.md index 64beba1..e0725e8 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. Spawn it in that role. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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 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. From 71158bace18ae2dfe05b480493961fdeb651eb1c Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 00:38:04 +0700 Subject: [PATCH 2/6] refactor(pstack-omp): route off-map models through one pstack-worker Model routing is now two cases. The mapped agent runs a role when it already runs the role's model, with effort for a level change. Every other role runs on pstack-worker with the model named per call. pstack-reader is removed. pstack-worker takes read-only roles too, and its prompt tells it to change nothing when the role is read-only. --- README.md | 13 ++++------ agents/pstack-reader.md | 26 ------------------- agents/pstack-worker.md | 8 +++--- skills/pstack-omp/SKILL.md | 33 ++++++------------------- skills/pstack-omp/references/runtime.md | 14 +++++------ skills/setup-pstack/SKILL.md | 11 +++------ 6 files changed, 25 insertions(+), 80 deletions(-) delete mode 100644 agents/pstack-reader.md diff --git a/README.md b/README.md index d2baa4c..098a281 100644 --- a/README.md +++ b/README.md @@ -55,9 +55,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 two carriers, `pstack-worker` and `pstack-reader`. They -run a role on a model its usual agent does not run. +`planner`, `designer`, `librarian`, and `pstack-worker` agents this package +ships in `agents/`. Missing integrations are reported honestly and fail closed; for example, Benny requires an available Slack/tracker/control adapter rather than pretending those tools exist. @@ -75,11 +74,9 @@ 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). Each agent's own model lives in OMP settings -(`task.agentModelOverrides`). A role whose configured model differs from its -agent's runs on a carrier, with the model named in the task call. That needs -`task.perCallModel: on` and a `modelRoles` entry that names the model. A role -that only changes the level needs `task.enableEffort: true`. The setup skill -checks these and asks before it changes them. +(`task.agentModelOverrides`). A role whose configured model its agent does not +run goes to `pstack-worker`, with the model named in the task call. That needs +`task.perCallModel: on` and a `modelRoles` entry that names the model. Then route your first real task through the main workflow: diff --git a/agents/pstack-reader.md b/agents/pstack-reader.md deleted file mode 100644 index 370216d..0000000 --- a/agents/pstack-reader.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -name: pstack-reader -description: "pstack carrier for read-only roles. Runs one standalone review, research, exploration, or judging brief on the model its caller names, for a role whose configured model its mapped agent does not run." -tools: - - read - - grep - - glob - - find - - bash - - lsp - - ast_grep - - web_search - - yield -model: - - "@default" -thinkingLevel: high -read-summarize: false ---- - -# pstack reader - -You fill the canonical pstack role that the brief's ROLE section names, such as `reviewer`, `synthesizer`, `explorer`, or an arena cross-judge. Hold that role's contract as the brief states it. You carry the role only because its configured model differs from the model its usual agent runs. - -You are read-only. Do not change files, branches, or external state, and run only commands that leave them unchanged. Ground every finding in a file and line, a command you ran with its output, or a cited source. When the brief gives frozen evidence, judge that evidence and do not alter it. - -Do not call `task`, start children, or ask the user directly. Finish through `yield` with `PASS`, `ISSUES`, or `BLOCKED`, the findings or verdict, the evidence for each, the commands you ran, and open questions for the root. diff --git a/agents/pstack-worker.md b/agents/pstack-worker.md index 60dea22..c84c223 100644 --- a/agents/pstack-worker.md +++ b/agents/pstack-worker.md @@ -1,6 +1,6 @@ --- name: pstack-worker -description: "pstack carrier for roles that write files. Runs one standalone brief on the model its caller names, for a role whose configured model its mapped agent does not run." +description: "pstack delegate for a role whose configured model its usual agent does not run. Runs one standalone brief on the model its caller names." tools: - read - grep @@ -21,8 +21,8 @@ read-summarize: false # pstack worker -You fill the canonical pstack role that the brief's ROLE section names, such as `implementer`, `planner`, or an arena runner. Hold that role's contract as the brief states it. You carry the role only because its configured model differs from the model its usual agent runs. +You fill the canonical pstack role that the brief's ROLE section names, such as `implementer`, `reviewer`, or an arena runner, and you hold that role's contract as the brief states it. -Follow the standalone brief exactly. Write only to the paths, worktree, or branch it assigns, and keep its one-writer assignment. 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. +Follow the standalone brief exactly. Write only to the paths, worktree, or branch it assigns. When the role is read-only, such as `reviewer`, `synthesizer`, `explorer`, or a judge, change no files, branches, or external state. 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 or artifacts, verification results, deviations, and unresolved risks. +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 or findings, the evidence for each, verification results, deviations, and unresolved risks. diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index ff10831..af5c82c 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -12,10 +12,8 @@ While this skill is active, its role map is the specific pstack execution contra ## Canonical role map 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/`. The package also ships two carrier agents, `pstack-worker` and -`pstack-reader`, which run a role on a model its mapped agent does not run. See -Model routing. +agents plus the `planner`, `designer`, `librarian`, and `pstack-worker` agents +this package ships in `agents/`. | Canonical role | OMP agent | Contract | |---|---|---| @@ -42,7 +40,6 @@ librarian task sonic pstack-worker -pstack-reader ``` A canonically routed task item's `agent` value must be one of those names. Canonical role labels and model aliases are not agent names. @@ -229,28 +226,12 @@ 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. +A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). An agent's own model comes from `task.agentModelOverrides`, which you can read at `cfg://task/agentModelOverrides`. OMP refuses a task item's `model` field for any agent listed there. -A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). OMP fixes each agent's model in `task.agentModelOverrides` and refuses a task item's `model` field for any agent with an entry there. Route each spawn in this order: +- **The mapped agent already runs the line's model, or the role has no line.** Start the mapped agent. If only the level differs, set `effort`. `lo`, `med`, and `hi` select the lowest, middle, and highest level the model supports, so a level between those goes to the next case. +- **Anything else.** Start `pstack-worker` with the line's value in `model`, and name the canonical role in the brief's ROLE section. For `inherit-parent` or `auto`, put the parent's own `provider/model-id` there. -1. A missing line keeps the mapped agent and sends no `model` or `effort`. -2. A line of `inherit-parent` or `auto` starts the carrier with the parent's own `provider/model-id` in `model`. -3. For a real `provider/model-id:level`, read `cfg://task/agentModelOverrides`. When the mapped agent's entry names the same `provider/model-id`, start the mapped agent with no `model`: - - If the level matches the entry, send no `effort`. - - Otherwise send `effort` when it reaches the level. `lo`, `med`, and `hi` select the lowest, middle, and highest level the model supports. On `anthropic/claude-opus-5-5`, which supports `low` to `max`, they ran at `low`, `high`, and `max`. - - Any other level goes to step 4. -4. Otherwise start the carrier with the line's value in `model`. The `:level` suffix sets its effort. - -The carrier depends on what the role may do: - -| Roles | Carrier | -|---|---| -| `planner`, `designer`, `implementer`, `owner`, `mechanical`, and every panel seat that writes, such as arena and architect runners and interrogate adversaries | `pstack-worker` | -| `explorer`, `watcher`, `reviewer`, `researcher`, `synthesizer`, and arena's cross-judge | `pstack-reader` | - -A carrier's brief names the canonical role it fills in its ROLE section, because the carrier has no specialist prompt of its own. - -A `model` needs `task.perCallModel: on` and a chat role in the operator's `modelRoles` that names the model. An `effort` needs `task.enableEffort: true`. When OMP refuses a spawn for one of these, start the mapped agent with no `model` or `effort`, and tell the user which setting or role is missing. `/setup-pstack` adds them. A per-call worker never falls back to another model, so an unavailable model fails the spawn. Report that failure and do not retry silently on another model. +A `model` needs `task.perCallModel: on` and a `modelRoles` entry that names the model. `effort` needs `task.enableEffort: true`. If OMP refuses the spawn, start the mapped agent without them, tell the user what is missing, and never retry on another model. Do not use a model alias as the `agent` value. Report the actual resolved model when independence matters. @@ -267,7 +248,7 @@ Recommended defaults for each agent's own model, set in `task.agentModelOverride | `task` | `@task` or a stronger implementation role | | `sonic` | `@tiny` or `@smol` | -Leave `pstack-worker` and `pstack-reader` out of `task.agentModelOverrides`. An entry there makes OMP refuse every per-call model for that carrier. +Leave `pstack-worker` out of `task.agentModelOverrides`, or OMP refuses every per-call model for it. ## Writing diff --git a/skills/pstack-omp/references/runtime.md b/skills/pstack-omp/references/runtime.md index 0fd5891..aaaa5ba 100644 --- a/skills/pstack-omp/references/runtime.md +++ b/skills/pstack-omp/references/runtime.md @@ -28,10 +28,9 @@ 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 package's -`pstack-worker` and `pstack-reader` carriers run a role on a model its mapped -agent does not run. The live `task` inventory wins over this document. +`security-reviewer`, `task`, `sonic`) and to the `planner`, `designer`, +`librarian`, and `pstack-worker` 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 @@ -43,10 +42,9 @@ 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). A role runs on its mapped agent when that -agent's override already names the role's model. Otherwise it runs on a carrier -with the model in the task item's `model` field. The Model routing section of -the `pstack-omp` skill gives the exact steps. Do not use a model alias as the -`agent` value. +agent already runs the role's model. Otherwise it runs on `pstack-worker` with +the model in the task item's `model` field. The Model routing section of the +`pstack-omp` skill has the rule. 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 diff --git a/skills/setup-pstack/SKILL.md b/skills/setup-pstack/SKILL.md index ea3d55f..098c985 100644 --- a/skills/setup-pstack/SKILL.md +++ b/skills/setup-pstack/SKILL.md @@ -13,7 +13,7 @@ Write `$PSTACK_CONFIG (or .pstack/config.md)`, the config file that sets pstack' ### 1. Detect available models -Enumerate the `provider/model-id` models OMP routes task agents to in this session, from `modelRoles` and `task.agentModelOverrides`. That is the dependable source. If `omp models` lists the user's available models, prefer it for completeness. If you cannot detect any, ask the user to paste the models they have access to. Never write a real model you have not confirmed is available. A role can run a model its mapped agent does not run, because a carrier agent takes the model per call. The Model routing section of the **pstack-omp** skill covers this. `inherit-parent` and `auto` are valid only when OMP can pass the current model to a child. +Enumerate the `provider/model-id` models OMP routes task agents to in this session, from `modelRoles` and `task.agentModelOverrides`. That is the dependable source. If `omp models` lists the user's available models, prefer it for completeness. If you cannot detect any, ask the user to paste the models they have access to. Never write a real model you have not confirmed is available. A role can name a model its mapped agent does not run, because `pstack-worker` then runs it per call. `inherit-parent` and `auto` are valid only when OMP can pass the current model to a child. ### 2. Load current state @@ -36,12 +36,7 @@ If the live session exposes models but no usable task facility, stop model mappi ### 4. Validate -Every real model written must be in the detected set. Role aliases pass only when the host task facility documents those aliases. If a chosen real model is not available, stop and ask again. Then check what the Model routing section of the **pstack-omp** skill needs for each role: - -- A role whose model differs from its mapped agent's `task.agentModelOverrides` entry runs per call. It needs `task.perCallModel: on` and a chat role in `modelRoles` that names the model. Prefer a chat role that already names it. Otherwise ask which chat role may take it, and say what that role runs today. An `inherit-parent` or `auto` value also runs per call and needs `task.perCallModel: on`, but OMP already approves the parent's own model. -- A role on its mapped agent's model at another level needs `task.enableEffort: true`. When the level is not the model's lowest, middle, or highest, it runs per call instead and needs the per-call settings above. - -List each missing setting or role and write it to the global OMP config only after the user approves. +Every real model written must be in the detected set. Role aliases pass only when the host task facility documents those aliases. If a chosen real model is not available, stop and ask again. A role whose model its mapped agent does not run needs `task.perCallModel: on` and a `modelRoles` entry that names the model, per the Model routing section of the **pstack-omp** skill. A role that only changes its agent's level needs `task.enableEffort: true`. List what is missing and write it to the global OMP config only after the user approves. ### 5. Write the config @@ -70,7 +65,7 @@ architect runners: :xhigh, :xhigh interrogate reviewers: :xhigh, :xhigh ``` -Leave `task.agentModelOverrides` alone unless the user asks to change an agent's own default model. Roles that map to one agent may name different models, because a carrier runs each role whose model differs from its agent's. Write the settings and roles step 4 approved, preserving unrelated keys. +Leave `task.agentModelOverrides` alone unless the user asks to change an agent's own default model. Roles that map to one agent may still name different models. Write the settings and roles step 4 approved, preserving unrelated keys. ### 6. Confirm From 5125baa2061b0e60079d2827e835c2e585140edc Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:27:12 +0700 Subject: [PATCH 3/6] refactor(pstack-omp): name the model on the mapped agent, keep pstack-worker for overridden agents With no task.agentModelOverrides entry, OMP accepts a per-call model on any agent. The mapped agent now takes the role line's value in model, and the :level suffix sets the effort. pstack-worker takes a role only when its mapped agent has an override with another value. The effort mapping and the task.enableEffort requirement are gone. setup-pstack no longer writes overrides. It adds a modelRoles entry for each model that no role names. --- README.md | 8 ++++---- agents/pstack-worker.md | 2 +- skills/pstack-omp/SKILL.md | 11 ++++------- skills/pstack-omp/references/runtime.md | 9 +++++---- skills/setup-pstack/SKILL.md | 6 +++--- 5 files changed, 17 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 098a281..f039861 100644 --- a/README.md +++ b/README.md @@ -73,10 +73,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). Each agent's own model lives in OMP settings -(`task.agentModelOverrides`). A role whose configured model its agent does not -run goes to `pstack-worker`, with the model named in the task call. That needs -`task.perCallModel: on` and a `modelRoles` entry that names the model. +when set). Each role runs on its mapped agent, with that model named in the task +call. That needs `task.perCallModel: on` and a `modelRoles` entry that names +each model. Leave `task.agentModelOverrides` empty, because OMP refuses a +per-call model for any agent listed there. Then route your first real task through the main workflow: diff --git a/agents/pstack-worker.md b/agents/pstack-worker.md index c84c223..d99ad73 100644 --- a/agents/pstack-worker.md +++ b/agents/pstack-worker.md @@ -1,6 +1,6 @@ --- name: pstack-worker -description: "pstack delegate for a role whose configured model its usual agent does not run. Runs one standalone brief on the model its caller names." +description: "pstack delegate for a role whose mapped agent cannot take a per-call model. Runs one standalone brief on the model its caller names." tools: - read - grep diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index af5c82c..349864b 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -226,16 +226,15 @@ The root resolves a child question and sends the answer through `write agent://< ## Model routing -A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). An agent's own model comes from `task.agentModelOverrides`, which you can read at `cfg://task/agentModelOverrides`. OMP refuses a task item's `model` field for any agent listed there. +A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). Start the role's mapped agent with the line's value in the task item's `model` field. The `:level` suffix sets the effort, so put an adjusted level there and not in `effort`. For `inherit-parent` or `auto`, put the parent's own `provider/model-id`. A role with no line sends no `model`, and the agent runs on its own default. -- **The mapped agent already runs the line's model, or the role has no line.** Start the mapped agent. If only the level differs, set `effort`. `lo`, `med`, and `hi` select the lowest, middle, and highest level the model supports, so a level between those goes to the next case. -- **Anything else.** Start `pstack-worker` with the line's value in `model`, and name the canonical role in the brief's ROLE section. For `inherit-parent` or `auto`, put the parent's own `provider/model-id` there. +OMP refuses `model` for an agent listed in `task.agentModelOverrides`, which you can read at `cfg://task/agentModelOverrides`. When the mapped agent is listed there with another value, start `pstack-worker` with the same `model`, and name the canonical role in the brief's ROLE section. When its entry is the line's value, start the mapped agent with no `model`. -A `model` needs `task.perCallModel: on` and a `modelRoles` entry that names the model. `effort` needs `task.enableEffort: true`. If OMP refuses the spawn, start the mapped agent without them, tell the user what is missing, and never retry on another model. +A `model` needs `task.perCallModel: on` and a `modelRoles` entry that names the model. If OMP refuses the spawn, start the mapped agent with no `model`, tell the user what is missing, and never retry on another model. Do not use a model alias as the `agent` value. Report the actual resolved model when independence matters. -Recommended defaults for each agent's own model, set in `task.agentModelOverrides` or `modelRoles`: +An agent started with no `model` runs on its own default. Set those defaults through `modelRoles`, and leave `task.agentModelOverrides` empty so that every agent accepts a per-call model. Recommended roles: | OMP agent | Recommendation | |---|---| @@ -248,8 +247,6 @@ Recommended defaults for each agent's own model, set in `task.agentModelOverride | `task` | `@task` or a stronger implementation role | | `sonic` | `@tiny` or `@smol` | -Leave `pstack-worker` out of `task.agentModelOverrides`, or OMP refuses every per-call model for it. - ## Writing Apply `unslop` to every reply, brief, report, review, task dispatch, commit message, and agent-facing edit. diff --git a/skills/pstack-omp/references/runtime.md b/skills/pstack-omp/references/runtime.md index aaaa5ba..6acd1a1 100644 --- a/skills/pstack-omp/references/runtime.md +++ b/skills/pstack-omp/references/runtime.md @@ -41,10 +41,11 @@ 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). A role runs on its mapped agent when that -agent already runs the role's model. Otherwise it runs on `pstack-worker` with -the model in the task item's `model` field. The Model routing section of the -`pstack-omp` skill has the rule. Do not use a model alias as the `agent` value. +definition, and normal fallback). A role runs on its mapped agent with the +role's model in the task item's `model` field. `pstack-worker` takes the role +only when the mapped agent has a `task.agentModelOverrides` entry, because OMP +then refuses the field. The Model routing section of the `pstack-omp` skill has +the rule. 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 diff --git a/skills/setup-pstack/SKILL.md b/skills/setup-pstack/SKILL.md index 098c985..e84f563 100644 --- a/skills/setup-pstack/SKILL.md +++ b/skills/setup-pstack/SKILL.md @@ -13,7 +13,7 @@ Write `$PSTACK_CONFIG (or .pstack/config.md)`, the config file that sets pstack' ### 1. Detect available models -Enumerate the `provider/model-id` models OMP routes task agents to in this session, from `modelRoles` and `task.agentModelOverrides`. That is the dependable source. If `omp models` lists the user's available models, prefer it for completeness. If you cannot detect any, ask the user to paste the models they have access to. Never write a real model you have not confirmed is available. A role can name a model its mapped agent does not run, because `pstack-worker` then runs it per call. `inherit-parent` and `auto` are valid only when OMP can pass the current model to a child. +Enumerate the `provider/model-id` models OMP routes task agents to in this session, from `modelRoles` and `task.agentModelOverrides`. That is the dependable source. If `omp models` lists the user's available models, prefer it for completeness. If you cannot detect any, ask the user to paste the models they have access to. Never write a real model you have not confirmed is available. A role can name any detected model, because the model goes on each task call. `inherit-parent` and `auto` are valid only when OMP can pass the current model to a child. ### 2. Load current state @@ -36,7 +36,7 @@ If the live session exposes models but no usable task facility, stop model mappi ### 4. Validate -Every real model written must be in the detected set. Role aliases pass only when the host task facility documents those aliases. If a chosen real model is not available, stop and ask again. A role whose model its mapped agent does not run needs `task.perCallModel: on` and a `modelRoles` entry that names the model, per the Model routing section of the **pstack-omp** skill. A role that only changes its agent's level needs `task.enableEffort: true`. List what is missing and write it to the global OMP config only after the user approves. +Every real model written must be in the detected set. Role aliases pass only when the host task facility documents those aliases. If a chosen real model is not available, stop and ask again. Each role's model goes on the task call, per the Model routing section of the **pstack-omp** skill. That needs `task.perCallModel: on` and a `modelRoles` entry that names each model. For a model that no role names, add a role that nothing else reads, such as `pstack-opus`. List what is missing and write it to the global OMP config only after the user approves. ### 5. Write the config @@ -65,7 +65,7 @@ architect runners: :xhigh, :xhigh interrogate reviewers: :xhigh, :xhigh ``` -Leave `task.agentModelOverrides` alone unless the user asks to change an agent's own default model. Roles that map to one agent may still name different models. Write the settings and roles step 4 approved, preserving unrelated keys. +Do not write `task.agentModelOverrides`. An entry there makes OMP refuse a per-call model for that agent, so offer to remove the entries that exist. Roles that map to one agent may name different models. Write the settings and roles step 4 approved, preserving unrelated keys. ### 6. Confirm From d45f1f954ea91f6fb482a031c5d41b86d182d3eb Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 02:56:24 +0700 Subject: [PATCH 4/6] fix(pstack-omp): fail a spawn whose configured model cannot run, and drop pstack-worker A per-call spawn that OMP refuses or cannot run now stops and reports the missing setting, role, or model. It no longer restarts on the agent's default model. how, why, reflect, swarm and arena no longer fall back to a default model or agent. Arena's cross-judge still moves to the next configured pool entry. pstack-worker is removed. With no overrides it never ran, and an override now fails the spawn instead of moving the role to another agent. The Model routing table lists the modelRoles entry each agent follows when no model is named, as observed on OMP 18.20.2. --- README.md | 3 +-- agents/pstack-worker.md | 28 ------------------------- skills/arena/SKILL.md | 4 ++-- skills/how/SKILL.md | 2 +- skills/pstack-omp/SKILL.md | 26 +++++++++-------------- skills/pstack-omp/references/runtime.md | 9 ++++---- skills/reflect/SKILL.md | 2 +- skills/swarm/SKILL.md | 2 +- skills/why/SKILL.md | 2 +- 9 files changed, 21 insertions(+), 57 deletions(-) delete mode 100644 agents/pstack-worker.md diff --git a/README.md b/README.md index f039861..22fc1f6 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,7 @@ 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`, `librarian`, and `pstack-worker` agents this package -ships in `agents/`. +`planner`, `designer`, and `librarian` agents this package ships in `agents/`. Missing integrations are reported honestly and fail closed; for example, Benny requires an available Slack/tracker/control adapter rather than pretending those tools exist. diff --git a/agents/pstack-worker.md b/agents/pstack-worker.md deleted file mode 100644 index d99ad73..0000000 --- a/agents/pstack-worker.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -name: pstack-worker -description: "pstack delegate for a role whose mapped agent cannot take a per-call model. Runs one standalone brief on the model its caller names." -tools: - - read - - grep - - glob - - find - - bash - - lsp - - ast_grep - - web_search - - edit - - write - - yield -model: - - "@default" -thinkingLevel: high -read-summarize: false ---- - -# pstack worker - -You fill the canonical pstack role that the brief's ROLE section names, such as `implementer`, `reviewer`, or an arena runner, and you hold that role's contract as the brief states it. - -Follow the standalone brief exactly. Write only to the paths, worktree, or branch it assigns. When the role is read-only, such as `reviewer`, `synthesizer`, `explorer`, or a judge, change no files, branches, or external state. 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 or findings, the evidence for each, verification results, deviations, and unresolved risks. diff --git a/skills/arena/SKILL.md b/skills/arena/SKILL.md index fe46952..8c399fb 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)`. 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. Families go by canonical role: an entry belongs to the role it fills. Route each entry's model per the Model routing section of the **pstack-omp** skill. If the host task runner rejects a configured entry, stop and report it, per that section, and 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 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, 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. 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. ## Phase D: Pick a base diff --git a/skills/how/SKILL.md b/skills/how/SKILL.md index a9f5257..0c7db9a 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. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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`). Spawn each in its default role. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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 the model, stop and report it, per that 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. ## 1. Assess complexity diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index 349864b..2d73c84 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -12,8 +12,8 @@ While this skill is active, its role map is the specific pstack execution contra ## Canonical role map Use the live host's configured names. This mapping targets OMP's bundled task -agents plus the `planner`, `designer`, `librarian`, and `pstack-worker` agents -this package ships in `agents/`. +agents plus the `planner`, `designer`, and `librarian` agents this package ships +in `agents/`. | Canonical role | OMP agent | Contract | |---|---|---| @@ -39,7 +39,6 @@ security-reviewer librarian task sonic -pstack-worker ``` A canonically routed task item's `agent` value must be one of those names. Canonical role labels and model aliases are not agent names. @@ -228,24 +227,19 @@ The root resolves a child question and sends the answer through `write agent://< A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). Start the role's mapped agent with the line's value in the task item's `model` field. The `:level` suffix sets the effort, so put an adjusted level there and not in `effort`. For `inherit-parent` or `auto`, put the parent's own `provider/model-id`. A role with no line sends no `model`, and the agent runs on its own default. -OMP refuses `model` for an agent listed in `task.agentModelOverrides`, which you can read at `cfg://task/agentModelOverrides`. When the mapped agent is listed there with another value, start `pstack-worker` with the same `model`, and name the canonical role in the brief's ROLE section. When its entry is the line's value, start the mapped agent with no `model`. - -A `model` needs `task.perCallModel: on` and a `modelRoles` entry that names the model. If OMP refuses the spawn, start the mapped agent with no `model`, tell the user what is missing, and never retry on another model. +A `model` needs `task.perCallModel: on`, a `modelRoles` entry that names the model, and no `task.agentModelOverrides` entry for the agent. A per-call spawn never switches models: an unavailable model or missing credentials fails it. If OMP refuses or fails the spawn, stop. Tell the user which setting, role, or model is missing, and do not start the role on another model or another agent. Do not use a model alias as the `agent` value. Report the actual resolved model when independence matters. -An agent started with no `model` runs on its own default. Set those defaults through `modelRoles`, and leave `task.agentModelOverrides` empty so that every agent accepts a per-call model. Recommended roles: +An agent started with no `model` runs on the role its own definition names. On OMP 18.20.2 those were: -| OMP agent | Recommendation | +| `modelRoles` entry | Agents | |---|---| -| `scout` | `@smol` | -| `planner` | `@plan` | -| `designer` | `@plan` | -| `reviewer` | `@advisor` | -| `security-reviewer` | `@advisor` | -| `librarian` | `@smol` | -| `task` | `@task` or a stronger implementation role | -| `sonic` | `@tiny` or `@smol` | +| `task` | `task` | +| `smol` | `scout`, `sonic`, `librarian` | +| `plan` | `planner`, `designer` | +| `slow` | `reviewer` | +| `default` | `security-reviewer`, and every agent above whose role is unset | ## Writing diff --git a/skills/pstack-omp/references/runtime.md b/skills/pstack-omp/references/runtime.md index 6acd1a1..5ee036d 100644 --- a/skills/pstack-omp/references/runtime.md +++ b/skills/pstack-omp/references/runtime.md @@ -28,8 +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`, -`librarian`, and `pstack-worker` agents this package ships in `agents/`. The +`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. Every child brief must stand alone. It must name its goal, role, writable scope, @@ -42,9 +42,8 @@ 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). A role runs on its mapped agent with the -role's model in the task item's `model` field. `pstack-worker` takes the role -only when the mapped agent has a `task.agentModelOverrides` entry, because OMP -then refuses the field. The Model routing section of the `pstack-omp` skill has +role's model in the task item's `model` field, and the spawn fails when OMP +cannot run that model. The Model routing section of the `pstack-omp` skill has the rule. Do not use a model alias as the `agent` value. Use concrete `provider/model-id` values in configuration only when OMP's live diff --git a/skills/reflect/SKILL.md b/skills/reflect/SKILL.md index 8a0fb65..0f1cc09 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -26,7 +26,7 @@ That covers the session (`_.jsonl`) and subagent (`_ Date: Mon, 16 Nov 2026 03:25:07 +0700 Subject: [PATCH 5/6] feat(pstack-omp): route each config line to an agent pinned by task.agentModelOverrides Replaces the per-call model routing on this branch. pstack never names a model on a task call again. The Model routing section maps every config line to an agent. Lines reuse task, reviewer, scout and librarian where their models agree. Ten new agents cover hardest tasks, judgment and prose, reflect tooling, swarm workers, three runner seats shared by arena, architect and interrogate, and three judge seats. Before each spawn the session compares the agent's override with the config line and stops when they differ. how, why, reflect, swarm and arena stop instead of falling back to a default model or agent. setup-pstack writes the overrides, and refuses inherit-parent, panels longer than three, disagreeing lines on one agent, fallback chains covering a configured model, and before_subagent_spawn handlers. verify.mjs fails when a config line in the setup-pstack template has no routing row or routes to an agent the package does not ship. --- README.md | 10 +++-- agents/pstack-hardest.md | 28 ++++++++++++++ agents/pstack-judge-1.md | 23 +++++++++++ agents/pstack-judge-2.md | 23 +++++++++++ agents/pstack-judge-3.md | 23 +++++++++++ agents/pstack-judgment.md | 28 ++++++++++++++ agents/pstack-reflect-tooling.md | 23 +++++++++++ agents/pstack-runner-1.md | 28 ++++++++++++++ agents/pstack-runner-2.md | 28 ++++++++++++++ agents/pstack-runner-3.md | 28 ++++++++++++++ agents/pstack-swarm-worker.md | 26 +++++++++++++ scripts/verify.mjs | 18 ++++++++- skills/arena/SKILL.md | 4 +- skills/how/SKILL.md | 2 +- skills/poteto-mode/SKILL.md | 2 +- skills/pstack-omp/SKILL.md | 51 ++++++++++++++++++------- skills/pstack-omp/references/runtime.md | 23 ++++++----- skills/reflect/SKILL.md | 2 +- skills/setup-pstack/SKILL.md | 22 +++++++---- skills/swarm/SKILL.md | 2 +- skills/why/SKILL.md | 2 +- 21 files changed, 351 insertions(+), 45 deletions(-) create mode 100644 agents/pstack-hardest.md create mode 100644 agents/pstack-judge-1.md create mode 100644 agents/pstack-judge-2.md create mode 100644 agents/pstack-judge-3.md create mode 100644 agents/pstack-judgment.md create mode 100644 agents/pstack-reflect-tooling.md create mode 100644 agents/pstack-runner-1.md create mode 100644 agents/pstack-runner-2.md create mode 100644 agents/pstack-runner-3.md create mode 100644 agents/pstack-swarm-worker.md diff --git a/README.md b/README.md index 22fc1f6..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,10 +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). Each role runs on its mapped agent, with that model named in the task -call. That needs `task.perCallModel: on` and a `modelRoles` entry that names -each model. Leave `task.agentModelOverrides` empty, because OMP refuses a -per-call model for any agent listed there. +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..c322e77 --- /dev/null +++ b/agents/pstack-runner-1.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-1 +description: "pstack panel seat 1 for arena runners, architect runners, and interrogate adversaries. Runs on entry 1 of those lines." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-1" +thinkingLevel: high +read-summarize: false +--- + +# Panel runner 1 + +You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. + +Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. + +Do not call `task`, start children, or ask the user directly. Run only the commands the panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt asks for. diff --git a/agents/pstack-runner-2.md b/agents/pstack-runner-2.md new file mode 100644 index 0000000..70a24e3 --- /dev/null +++ b/agents/pstack-runner-2.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-2 +description: "pstack panel seat 2 for arena runners, architect runners, and interrogate adversaries. Runs on entry 2 of those lines." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-2" +thinkingLevel: high +read-summarize: false +--- + +# Panel runner 2 + +You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. + +Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. + +Do not call `task`, start children, or ask the user directly. Run only the commands the panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt asks for. diff --git a/agents/pstack-runner-3.md b/agents/pstack-runner-3.md new file mode 100644 index 0000000..cf806e3 --- /dev/null +++ b/agents/pstack-runner-3.md @@ -0,0 +1,28 @@ +--- +name: pstack-runner-3 +description: "pstack panel seat 3 for arena runners, architect runners, and interrogate adversaries. Runs on entry 3 of those lines." +tools: + - read + - grep + - glob + - find + - bash + - lsp + - ast_grep + - web_search + - edit + - write + - yield +model: + - "@pstack-runner-3" +thinkingLevel: high +read-summarize: false +--- + +# Panel runner 3 + +You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. + +Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. + +Do not call `task`, start children, or ask the user directly. Run only the commands the panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt 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..8b5fac1 100644 --- a/scripts/verify.mjs +++ b/scripts/verify.mjs @@ -214,7 +214,23 @@ for (const entry of await readdir(join(root, "agents"))) { 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] ?? ""; +for (const [, line] of configShape.matchAll(/^([a-z][a-z ,]*): /gmu)) { + if (!lineAgents.has(line)) { + failures.push(`${relative(root, adapterPath)} has no Model routing row for the ${line} 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/arena/SKILL.md b/skills/arena/SKILL.md index 8c399fb..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. Families go by canonical role: an entry belongs to the role it fills. Route each entry's model per the Model routing section of the **pstack-omp** skill. If the host task runner rejects a configured entry, stop and report it, per that section, and 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. +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, 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. 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 0c7db9a..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. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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 the model, stop and report it, per that 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. +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-mode/SKILL.md b/skills/poteto-mode/SKILL.md index 1b66203..4c507b9 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -111,7 +111,7 @@ 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`), routed by the active adapter (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. diff --git a/skills/pstack-omp/SKILL.md b/skills/pstack-omp/SKILL.md index 2d73c84..17ce8df 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,21 +236,35 @@ The root resolves a child question and sends the answer through `write agent://< ## Model routing -A role's model comes from its line in `$PSTACK_CONFIG` (or `.pstack/config.md`). Start the role's mapped agent with the line's value in the task item's `model` field. The `:level` suffix sets the effort, so put an adjusted level there and not in `effort`. For `inherit-parent` or `auto`, put the parent's own `provider/model-id`. A role with no line sends no `model`, and the agent runs on its own default. +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. -A `model` needs `task.perCallModel: on`, a `modelRoles` entry that names the model, and no `task.agentModelOverrides` entry for the agent. A per-call spawn never switches models: an unavailable model or missing credentials fails it. If OMP refuses or fails the spawn, stop. Tell the user which setting, role, or model is missing, and do not start the role on another model or another agent. +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. -Do not use a model alias as the `agent` value. Report the actual resolved model when independence matters. - -An agent started with no `model` runs on the role its own definition names. On OMP 18.20.2 those were: - -| `modelRoles` entry | Agents | +| Config line | Agent | |---|---| -| `task` | `task` | -| `smol` | `scout`, `sonic`, `librarian` | -| `plan` | `planner`, `designer` | -| `slow` | `reviewer` | -| `default` | `security-reviewer`, and every agent above whose role is unset | +| `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. + +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 5ee036d..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,15 +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). A role runs on its mapped agent with the -role's model in the task item's `model` field, and the spawn fails when OMP -cannot run that model. The Model routing section of the `pstack-omp` skill has -the rule. 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 0f1cc09..8c9d532 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -26,7 +26,7 @@ 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. If a chosen real model is not available, stop and ask again. Each role's model goes on the task call, per the Model routing section of the **pstack-omp** skill. That needs `task.perCallModel: on` and a `modelRoles` entry that names each model. For a model that no role names, add a role that nothing else reads, such as `pstack-opus`. List what is missing and write it to the global OMP config only after the user approves. +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. +# 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,7 +71,7 @@ architect runners: :xhigh, :xhigh interrogate reviewers: :xhigh, :xhigh ``` -Do not write `task.agentModelOverrides`. An entry there makes OMP refuse a per-call model for that agent, so offer to remove the entries that exist. Roles that map to one agent may name different models. Write the settings and roles step 4 approved, preserving unrelated keys. +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 diff --git a/skills/swarm/SKILL.md b/skills/swarm/SKILL.md index 58aecbd..3f6cfcb 100644 --- a/skills/swarm/SKILL.md +++ b/skills/swarm/SKILL.md @@ -21,7 +21,7 @@ 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. Route the model per the Model routing section of the **pstack-omp** skill. If the host task runner rejects it, stop and report it, per that section. 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 diff --git a/skills/why/SKILL.md b/skills/why/SKILL.md index c8c2914..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. Route the line's value per the Model routing section of the **pstack-omp** skill, and run 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 the model, stop and report it, per that 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. +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. From 58df50d5cbb25ba4062747f37acf0f18432153d7 Mon Sep 17 00:00:00 2001 From: chen <23054115+cwkang1998@users.noreply.github.com> Date: Mon, 16 Nov 2026 04:45:53 +0700 Subject: [PATCH 6/6] fix(pstack-omp): close review gaps in model routing Config-line spawns send no effort, so the override's level holds. poteto-mode's effort rule applies only to roles with no line and drops its inherit-parent and closest-choice fallbacks. Remove leftover model-switching text from orchestrate, architect, poteto-help and setup-pstack. swarm and reflect now spawn on the line's agent instead of the canonical role. verify.mjs checks lines with hyphens, flags routing rows that are not config lines, requires each pstack agent to name only its own role, and keeps edit and write off the judges. Runner prompts no longer mention panels, seats or other models, so an eval candidate is not told it is being compared. --- agents/pstack-runner-1.md | 10 ++++---- agents/pstack-runner-2.md | 10 ++++---- agents/pstack-runner-3.md | 10 ++++---- scripts/verify.mjs | 26 +++++++++++++++++---- skills/architect/SKILL.md | 2 +- skills/poteto-help/SKILL.md | 2 +- skills/poteto-mode/SKILL.md | 2 +- skills/poteto-mode/playbooks/orchestrate.md | 2 +- skills/pstack-omp/SKILL.md | 2 +- skills/reflect/SKILL.md | 2 +- skills/setup-pstack/SKILL.md | 4 ++-- skills/swarm/SKILL.md | 2 +- 12 files changed, 46 insertions(+), 28 deletions(-) diff --git a/agents/pstack-runner-1.md b/agents/pstack-runner-1.md index c322e77..892f2a7 100644 --- a/agents/pstack-runner-1.md +++ b/agents/pstack-runner-1.md @@ -1,6 +1,6 @@ --- name: pstack-runner-1 -description: "pstack panel seat 1 for arena runners, architect runners, and interrogate adversaries. Runs on entry 1 of those lines." +description: "pstack runner 1, pinned to entry 1 of the runner config lines. Runs one standalone brief." tools: - read - grep @@ -19,10 +19,10 @@ thinkingLevel: high read-summarize: false --- -# Panel runner 1 +# Runner 1 -You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. -Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. +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 panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt asks for. +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 index 70a24e3..ef5d5c0 100644 --- a/agents/pstack-runner-2.md +++ b/agents/pstack-runner-2.md @@ -1,6 +1,6 @@ --- name: pstack-runner-2 -description: "pstack panel seat 2 for arena runners, architect runners, and interrogate adversaries. Runs on entry 2 of those lines." +description: "pstack runner 2, pinned to entry 2 of the runner config lines. Runs one standalone brief." tools: - read - grep @@ -19,10 +19,10 @@ thinkingLevel: high read-summarize: false --- -# Panel runner 2 +# Runner 2 -You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. -Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. +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 panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt asks for. +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 index cf806e3..10e13ac 100644 --- a/agents/pstack-runner-3.md +++ b/agents/pstack-runner-3.md @@ -1,6 +1,6 @@ --- name: pstack-runner-3 -description: "pstack panel seat 3 for arena runners, architect runners, and interrogate adversaries. Runs on entry 3 of those lines." +description: "pstack runner 3, pinned to entry 3 of the runner config lines. Runs one standalone brief." tools: - read - grep @@ -19,10 +19,10 @@ thinkingLevel: high read-summarize: false --- -# Panel runner 3 +# Runner 3 -You fill one seat of an `arena`, `architect`, or `interrogate` panel. The brief says which panel and passes its prompt. Hold that prompt's contract exactly. +Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract. -Work only in the worktree or output path the brief assigns. Other seats run the same brief on other models, so do not read or change their outputs. +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 panel's prompt calls for, and report only checks you executed. Finish through `yield` with what the panel's prompt asks for. +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/scripts/verify.mjs b/scripts/verify.mjs index 8b5fac1..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,14 +209,25 @@ 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 PANEL_SEATS = 3; const lineAgents = new Map( - [...adapter.matchAll(/^\| `([a-z ,]+)` \| `([a-z<>N-]+)` \|$/gmu)].map((match) => [match[1], match[2]]), + [...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]), @@ -226,11 +237,18 @@ const mappedAgents = [ ]; const setupPath = join(skillsRoot, "setup-pstack", "SKILL.md"); const configShape = (await readFile(setupPath, "utf8")).match(/^```\n# pstack model configuration[\s\S]*?\n```/mu)?.[0] ?? ""; -for (const [, line] of configShape.matchAll(/^([a-z][a-z ,]*): /gmu)) { +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/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 4c507b9..e7e3fa9 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -113,7 +113,7 @@ Use only these canonical lifecycle protocols: **Bounded session**, **Panel**, ** **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 17ce8df..1671c16 100644 --- a/skills/pstack-omp/SKILL.md +++ b/skills/pstack-omp/SKILL.md @@ -264,7 +264,7 @@ Before each spawn for a config line, read `cfg://task/agentModelOverrides` and c 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. -If a spawn fails, report the error. Never start the role on another agent or model. Report the resolved model when independence matters. +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/reflect/SKILL.md b/skills/reflect/SKILL.md index 8c9d532..c9e3e0d 100644 --- a/skills/reflect/SKILL.md +++ b/skills/reflect/SKILL.md @@ -24,7 +24,7 @@ That covers the session (`_.jsonl`) and subagent (`_` 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. +# 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 @@ -75,7 +75,7 @@ Then write `task.agentModelOverrides` in the global OMP config, preserving unrel ### 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 3f6cfcb..b1ae73e 100644 --- a/skills/swarm/SKILL.md +++ b/skills/swarm/SKILL.md @@ -26,7 +26,7 @@ Open a todolist with one entry per phase before launching anything. ## 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.