Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -72,8 +74,10 @@ $setup-pstack
It detects the models and task agents your OMP session actually exposes, lets
you choose the defaults for implementation and review work, and writes concrete
`provider/model-id` assignments to `.pstack/config.md` (or to `$PSTACK_CONFIG`
when set). Model routing itself lives in OMP settings (`modelRoles`,
`task.agentModelOverrides`); the configuration file is the portable record.
when set). It also writes each agent's model to `task.agentModelOverrides` in
your global OMP config. pstack never names a model on a task call. Before each
spawn it checks that the agent's override matches the config line, and it stops
when they differ.

Then route your first real task through the main workflow:

Expand Down
28 changes: 28 additions & 0 deletions agents/pstack-hardest.md
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions agents/pstack-judge-1.md
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions agents/pstack-judge-2.md
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions agents/pstack-judge-3.md
Original file line number Diff line number Diff line change
@@ -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.
28 changes: 28 additions & 0 deletions agents/pstack-judgment.md
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 23 additions & 0 deletions agents/pstack-reflect-tooling.md
Original file line number Diff line number Diff line change
@@ -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.
28 changes: 28 additions & 0 deletions agents/pstack-runner-1.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
name: pstack-runner-1
description: "pstack runner 1, pinned to entry 1 of the runner config lines. Runs one standalone brief."
tools:
- read
- grep
- glob
- find
- bash
- lsp
- ast_grep
- web_search
- edit
- write
- yield
model:
- "@pstack-runner-1"
thinkingLevel: high
read-summarize: false
---

# Runner 1

Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract.

Write only to the worktree or output path the brief assigns.

Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for.
28 changes: 28 additions & 0 deletions agents/pstack-runner-2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
name: pstack-runner-2
description: "pstack runner 2, pinned to entry 2 of the runner config lines. Runs one standalone brief."
tools:
- read
- grep
- glob
- find
- bash
- lsp
- ast_grep
- web_search
- edit
- write
- yield
model:
- "@pstack-runner-2"
thinkingLevel: high
read-summarize: false
---

# Runner 2

Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract.

Write only to the worktree or output path the brief assigns.

Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for.
28 changes: 28 additions & 0 deletions agents/pstack-runner-3.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
name: pstack-runner-3
description: "pstack runner 3, pinned to entry 3 of the runner config lines. Runs one standalone brief."
tools:
- read
- grep
- glob
- find
- bash
- lsp
- ast_grep
- web_search
- edit
- write
- yield
model:
- "@pstack-runner-3"
thinkingLevel: high
read-summarize: false
---

# Runner 3

Follow the standalone brief exactly, including any prompt it passes, and hold that prompt's contract.

Write only to the worktree or output path the brief assigns.

Do not call `task`, start children, or ask the user directly. Run only the commands the brief calls for, and report only checks you executed. Finish with what the brief asks for.
26 changes: 26 additions & 0 deletions agents/pstack-swarm-worker.md
Original file line number Diff line number Diff line change
@@ -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.
40 changes: 37 additions & 3 deletions scripts/verify.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -209,12 +209,46 @@ for (const entry of await readdir(join(root, "agents"))) {
failures.push(`${relative(root, path)} is missing frontmatter ${key}`);
}
}
packageAgents.add(name);
const list = (key) => [...(frontmatter.match(new RegExp(`^${key}:\\n((?: - .*\\n?)*)`, "mu"))?.[1] ?? "").matchAll(/^ - "?([^"\n]+)"?$/gmu)].map((match) => match[1]);
packageAgents.set(name, { path, tools: list("tools"), models: list("model") });
}
for (const [name, agent] of packageAgents) {
if (!name.startsWith("pstack-")) continue;
// A second model, or a role something else sets, would let the agent run without its override.
if (agent.models.length !== 1 || agent.models[0] !== `@${name}`) {
failures.push(`${relative(root, agent.path)} must name only its own role, @${name}, as its model`);
}
if (name.startsWith("pstack-judge-") && agent.tools.some((tool) => tool === "edit" || tool === "write")) {
failures.push(`${relative(root, agent.path)} is a judge and must not have edit or write`);
}
}
const adapterPath = join(skillsRoot, "pstack-omp", "SKILL.md");
const adapter = await readFile(adapterPath, "utf8");
const roster = adapter.match(/The reference roster is closed:\n\n```text\n([\s\S]*?)\n```/u)?.[1];
const mappedAgents = [...adapter.matchAll(/^\| `[a-z]+` \| `([a-z-]+)` \|/gmu)].map((match) => match[1]);
const PANEL_SEATS = 3;
const lineAgents = new Map(
[...adapter.matchAll(/^\| `([a-z ,-]+)` \| `([a-z<>N-]+)` \|$/gmu)].map((match) => [match[1], match[2]]),
);
const mappedAgents = [
...[...adapter.matchAll(/^\| `[a-z]+` \| `([a-z-]+)` \|/gmu)].map((match) => match[1]),
...[...lineAgents.values()].flatMap((agent) =>
agent.includes("<N>") ? Array.from({ length: PANEL_SEATS }, (_, i) => agent.replace("<N>", String(i + 1))) : [agent],
),
];
const setupPath = join(skillsRoot, "setup-pstack", "SKILL.md");
const configShape = (await readFile(setupPath, "utf8")).match(/^```\n# pstack model configuration[\s\S]*?\n```/mu)?.[0] ?? "";
const configLines = [...configShape.matchAll(/^([a-z][a-z ,-]*): /gmu)].map((match) => match[1]);
if (configLines.length === 0) failures.push(`${relative(root, setupPath)} has no config shape to check routing against`);
for (const line of configLines) {
if (!lineAgents.has(line)) {
failures.push(`${relative(root, adapterPath)} has no Model routing row for the ${line} line in ${relative(root, setupPath)}`);
}
}
for (const line of lineAgents.keys()) {
if (!configLines.includes(line)) {
failures.push(`${relative(root, adapterPath)} routes ${line}, which is not a line in ${relative(root, setupPath)}`);
}
}
if (!roster) failures.push(`${relative(root, adapterPath)} is missing the closed agent roster`);
for (const agent of new Set([...(roster?.split("\n") ?? []), ...mappedAgents])) {
if (!ompBundledAgents.has(agent) && !packageAgents.has(agent)) {
Expand Down
2 changes: 1 addition & 1 deletion skills/architect/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
4 changes: 2 additions & 2 deletions skills/arena/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Every candidate gets the same prompt, so the prompt is the contract.

1. State the artifact each candidate is producing.
2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task.
3. Pick the runners. Use the `arena runners` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, default to one each on the canonical `planner` and `implementer` roles. An `auto` or `inherit-parent` entry in this line means the parent model. If the host task runner rejects a configured entry, run that seat on its family's default and say so. Families go by canonical role: an entry belongs to the role it fills, and that role is its default. If the family has no default, or the host task runner rejects that default, use the closest valid agent of the same family from its error message, or drop the seat and say so when there is none. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill.
3. Pick the runners. Use the `arena runners` line in `$PSTACK_CONFIG (or .pstack/config.md)`, and start entry N on its seat agent per the Model routing section of the **pstack-omp** skill. If the configuration or that line is missing, default to one each on the canonical `planner` and `implementer` roles. If that section's check stops a seat, or the spawn fails, stop and report it. Do not run the seat on another model. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Set each child's reasoning effort for the job through the task runner's effort setting when the host exposes it, per the Delegation section of the **poteto-mode** skill.
4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill.

## Phase B: Fan out
Expand All @@ -27,7 +27,7 @@ If a candidate produces no output, proceed with N-1 and note the dropout.

## Phase C: Cross-judge

After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in `$PSTACK_CONFIG (or .pstack/config.md)`. If the configuration or that line is missing, choose from the canonical `reviewer` and `planner` roles. Spawn one readonly judge subagent. The judge is never from the parent's family. Here a family is the model an entry resolves to through the host's model settings, not the canonical role from Phase A step 3, because the parent fills no role. Try only the entries from another family, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. If the host task runner rejects an entry, use a valid slug of the same model at the closest level or speed from the error message, or move to the next entry when there is none. If no entry from another family runs, try the default pool's entries from another family the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If you do not know the parent's model, try the pool's real slugs in pool order and say that the family check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.
After all Phase B candidates complete, choose one entry from the `arena cross-judge pool` line in `$PSTACK_CONFIG (or .pstack/config.md)`, and start entry N on its judge agent per the Model routing section of the **pstack-omp** skill. If the configuration or that line is missing, choose from the canonical `reviewer` and `planner` roles. Spawn one readonly judge subagent. The judge is never from the parent's family. Here a family is the model an entry names, not the canonical role from Phase A step 3, because the parent fills no role. Try only the entries from another family, in pool order. If that section's check stops an entry, or its spawn fails, report it and move to the next entry. If no entry from another family runs, skip the judge, pick the base alone in Phase D, and say so. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing.

## Phase D: Pick a base

Expand Down
Loading