Skip to content

feat(pstack): shorter skill texts, worker.md, and Opus-first routing capped at xhigh - #1249

Merged
poteto merged 12 commits into
mainfrom
lauren/pstack-port-746f
Nov 16, 2026
Merged

poteto merged 12 commits into
mainfrom
lauren/pstack-port-746f

Conversation

@poteto

@poteto poteto commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Why

pstack's skill texts carried rules that no longer change what an agent does, started agents never saw the operator's rules unless a slash command loaded them, and model routing could send the hardest work to Fable 5.2 at max. This makes the texts shorter, gives started agents one rules file, and routes work to Opus 5.5 with no role above xhigh.

What changed

  • Shorter texts: 14 principle leaves, unslop, technical-writing, and the Opening a PR, Babysit and Multi-phase plan playbooks. check-plan.mjs and its test go, since nothing runs them now.
  • reflect is one file with no subagents. architect is a short brief that sends large or contested designs to arena. Both lose their reference files. arena's runner and judge steps are shorter.
  • poteto-mode: ten short triggers, shorter Subagents, reply and Playbooks sections, and no Comments section. The Orchestrate playbook is removed, and program-scale work routes to figure-it-out.
  • New poteto-mode/worker.md. Every agent /poteto-mode starts reads it first.
  • Routing: code, prose and judgment default to claude-opus-5-5-xhigh-fast. Outside a panel, Fable 5.2 runs only when the user names it or after two failed Opus 5.5 xhigh runs. No role runs above xhigh, and Opus 5.5 always runs its -fast slug. poteto-agent pins claude-opus-5-5-xhigh-fast.
  • setup-pstack writes # defaults: 3, offers large, medium and small budgets on a ladder that tops out at xhigh, retires hardest tasks, architect runners and both reflect roles, and migrates older rules.
  • The README, guide chapters 01, 02, 04, 05, 06, 07 and 09, and the Claude Code adapter follow. Version 0.15.43, harness tree regenerated.

Scope

  • Kept: pstack's role labels, budget ladder and # defaults marker, so a user's real choices survive the migration.
  • Left out: a setup step that resets every role to its default, and any watcher or check code beyond what pstack already ships.
  • The unlimited budget is removed, not capped, because it could only mean max. An old unlimited rule becomes large.

Tradeoffs

  • The shorter architect and principle texts drop the interface-depth wording that lived in the longer versions.

Blast Radius

Every pstack user gets the shorter texts. A user with an older pstack-models.mdc keeps their lines until they rerun /setup-pstack, and /poteto-mode reminds them once per session.

Verification

  • node scripts/generate-pstack-harness-trees.mjs --check: up to date. node scripts/check-pstack-docs.mjs: 0 problems. node scripts/validate-plugins.mjs: all valid.
  • node --test pstack/skills/*/scripts/test/*.test.ts: 269 pass, 70 skipped, 1 fail. The failure is a statechart symlink test that fails the same way on main on macOS.
  • A search of pstack/ for max finds no routing above xhigh.

laurentan added 12 commits November 16, 2026 12:30
Replace the bodies of 14 principle skills with shorter texts that keep
each rule and its test. Frontmatter is unchanged. Two references to
other skills now name the benchmark-checklist and
typescript-best-practices skills. The interface-compression wording in
four leaves goes with the longer bodies.
unslop keeps its stable rule numbers, so rule 14 (no mid-sentence colon)
still means the same thing where poteto-mode cites it. Retired rules
leave gaps. technical-writing keeps its four layers in shorter form and
still routes slop patterns to unslop and UI strings to your product's
copy guidelines. unslop keeps its current description.
The playbook keeps the worktree, small commits, /deslop, the title
form, the six body headings, stacking by base branch, and opening PRs
ready. Without a PR tool it opens ready with gh pr create (no --draft)
or origin pr create --status open. The detailed forge, readiness and
size sections go.

benchmark-checklist and autopilot-stack stop pointing at sections the
playbook no longer has. Guide chapters 05 and 06 describe the shorter
playbook.
Babysit keeps its three modes, the conflicts-threads-CI order, the
no-rebase rule, skeptical Bugbot triage and the no-merge line. It
keeps one forge rule: gh by default, origin pr when Origin's CLI
resolves the repository, never gt. The bundled watcher covers GitHub;
on Origin it reads origin pr view --checks and origin pr checks
--watch. Replies go through gh api --input or origin pr thread reply
--body-file, never through shell built from comment text.

Shipping step 5 names the queued watcher flags itself, and an
Autopilot-full owner rebases its own branch where Babysit reports a
rebase. Guide chapter 06 describes the shorter playbook.
The playbook keeps the skip rule for small changes, prototype-first
questions, a plan file with landing order, a dependency graph and one
checkbox section per PR, the unit, live and perf verification boxes,
and the stop before execution.

The new text never runs check-plan.mjs, and nothing else in pstack
names it, so the script and its test are deleted and the scripts
package test command drops it. Guide chapter 04 no longer says the plan
names its execution playbook.
reflect now reads the transcript itself, keeps only findings that will
still hold and would change a future agent's work, routes each to a
skill the session used, and waits for approval before any edit. It
keeps the rule that it never edits a skill under plugins/cache/ and
never opens a PR or pushes.

The three reviewers, the synthesizer and their four reference files are
deleted. setup-pstack drops the reflect tooling and reflect judgment,
divergent, synthesizer roles, so an existing line for either is a
retired role on the next run. poteto-mode stops listing reflect as a
skill that sets its own subagents or models. Guide chapter 09
describes the new flow.
architect now traces every system the change touches, sketches two
shapes, picks the one with one owner per piece of state, one way to do
each task and the least for callers to know, and redesigns when
workarounds repeat. A large or contested design runs the arena skill
instead.

The five phases, the runner prompt, the red-flag list and the
rationale template are deleted, along with the interface-depth text
that lived in them. setup-pstack drops the architect runners role.
poteto-mode, the Feature, Refactoring and Bug fix playbooks,
poteto-help and guide chapter 04 stop describing parallel design
exploration and the checkpoint option.
Phase A step 3 keeps the runner line, its default panel, the alias
rule, the fallback for a rejected slug (nearest slug of the same
family, or drop the seat and keep at least two runners) and the family
rule. Phase C keeps the judge pool, the other-vendor rule (Fable counts
as Claude), the unknown-parent case and the skip. The longer fallback
chains go.
poteto-mode:
- The trigger list becomes ten short lines. The long AskQuestion rule,
  the broken-skill rule and the throughput-checkpoint trigger go.
- The Subagents lead, second-opinion and fresh-subagent paragraphs get
  shorter. The model paragraphs change in a later commit.
- Writing the reply becomes one paragraph, and the Comments section is
  removed. no-comments still runs before review.
- Playbooks: match a playbook, copy its steps into the todolist tool
  first, and route large, cross-cutting or unattended work, or a task
  no playbook fits, to figure-it-out. The list names the 22 playbooks.
  A skipped step no longer stays in the list as skip: <reason>.

The Orchestrate playbook is deleted. Program-scale work routes to
figure-it-out. The README, poteto-help and guide chapters 01, 02 and
07 drop it, the playbook count becomes twenty-two, and Feature step 4
drops its pointer to the Comments section. The Claude Code adapter's
todolist row also covers the todolist tool.
Add poteto-mode/worker.md. It says who the operator is (the person the
run works for, not the agent that wrote the kickoff) and lists the
rules every started agent keeps: the kickoff's bar is the whole bar,
block only for a failing run or a user-facing bug, never ask a person
a question, open PRs ready, and the PR title and body shape.

poteto-mode gets a trigger: the first line of every kickoff, for a Task
subagent or a Project worker, is a pointer to worker.md by absolute
path, because those rules live in skills that load only from a slash
command. worker.md passes the same pointer on. Guide chapter 07
mentions it.
…on, cap at xhigh

Defaults:
- Code, prose and judgment: claude-opus-5-5-xhigh-fast.
- Trivial mechanical edits, swarm workers and verification:
  claude-opus-5-5-high-fast.
- Panels: claude-fable-5-2-high, claude-opus-5-5-high-fast and
  gemini-4-carbon-high. The arena cross-judge pool drops Fable, which
  is the same vendor as Opus and could judge only where Opus could.

Rules:
- Outside a panel, Fable 5.2 runs only when the user names it for the
  task or after two Opus 5.5 xhigh runs of the same brief fail their
  check. Difficulty alone never qualifies. The hardest tasks role is
  retired.
- No role runs above xhigh. The hardest work raises a role one step,
  up to xhigh. Panel seats keep their listed level.
- Opus 5.5 always runs its -fast slug. The rule that kept fast mode for
  urgent jobs is gone, and every "reasoning level and fast or standard
  speed" line now says "reasoning level".
- poteto-agent pins claude-opus-5-5-xhigh-fast, so an inherit-parent
  or auto role spawns generalPurpose. Explicit models now cover
  Project workers too.
- A second opinion and the show-me-your-work reviewer use another
  vendor's model. Eval agents that only dispatch, poll or pack results
  run on claude-opus-5-5-medium-fast.

setup-pstack writes # defaults: 3 and offers three budgets (large,
medium, small) on a ladder that tops out at xhigh. On the next run, a
rule without the new marker drops the retired roles, takes the new
cross-judge pool when it still holds the old three-seat default, turns
an unlimited budget into large, and keeps the earlier Grok migration
for rules older than # defaults: 2. Re-running the budget step rebuilds
unchanged roles from the new -fast defaults.

The README, guide chapter 01 and the Claude Code adapter describe the
new defaults. The adapter maps claude-fable-5-2-high to fable high and
says to pass model and effort on every poteto-agent spawn, so the
agent file's Cursor slug never reaches the Claude Code API.
Regenerate harness/pstack with node scripts/generate-pstack-harness-trees.mjs
so the Claude Code tree matches the skill, agent, guide and adapter
changes in this branch.
@poteto
poteto merged commit e559e62 into main Nov 16, 2026
1 check passed
@poteto
poteto deleted the lauren/pstack-port-746f branch November 16, 2026 21:28
poteto added a commit that referenced this pull request Nov 16, 2026
…capped at xhigh (#1249)

* docs(pstack): cut 14 principle leaves to shorter bodies

Replace the bodies of 14 principle skills with shorter texts that keep
each rule and its test. Frontmatter is unchanged. Two references to
other skills now name the benchmark-checklist and
typescript-best-practices skills. The interface-compression wording in
four leaves goes with the longer bodies.

* docs(pstack): cut unslop and technical-writing to shorter bodies

unslop keeps its stable rule numbers, so rule 14 (no mid-sentence colon)
still means the same thing where poteto-mode cites it. Retired rules
leave gaps. technical-writing keeps its four layers in shorter form and
still routes slop patterns to unslop and UI strings to your product's
copy guidelines. unslop keeps its current description.

* docs(pstack): cut the Opening a PR playbook to three paragraphs

The playbook keeps the worktree, small commits, /deslop, the title
form, the six body headings, stacking by base branch, and opening PRs
ready. Without a PR tool it opens ready with gh pr create (no --draft)
or origin pr create --status open. The detailed forge, readiness and
size sections go.

benchmark-checklist and autopilot-stack stop pointing at sections the
playbook no longer has. Guide chapters 05 and 06 describe the shorter
playbook.

* docs(pstack): cut the Babysit playbook to six rules

Babysit keeps its three modes, the conflicts-threads-CI order, the
no-rebase rule, skeptical Bugbot triage and the no-merge line. It
keeps one forge rule: gh by default, origin pr when Origin's CLI
resolves the repository, never gt. The bundled watcher covers GitHub;
on Origin it reads origin pr view --checks and origin pr checks
--watch. Replies go through gh api --input or origin pr thread reply
--body-file, never through shell built from comment text.

Shipping step 5 names the queued watcher flags itself, and an
Autopilot-full owner rebases its own branch where Babysit reports a
rebase. Guide chapter 06 describes the shorter playbook.

* docs(pstack): cut the multi-phase plan playbook to five steps

The playbook keeps the skip rule for small changes, prototype-first
questions, a plan file with landing order, a dependency graph and one
checkbox section per PR, the unit, live and perf verification boxes,
and the stop before execution.

The new text never runs check-plan.mjs, and nothing else in pstack
names it, so the script and its test are deleted and the scripts
package test command drops it. Guide chapter 04 no longer says the plan
names its execution playbook.

* feat(pstack): make reflect one short file with no subagents

reflect now reads the transcript itself, keeps only findings that will
still hold and would change a future agent's work, routes each to a
skill the session used, and waits for approval before any edit. It
keeps the rule that it never edits a skill under plugins/cache/ and
never opens a PR or pushes.

The three reviewers, the synthesizer and their four reference files are
deleted. setup-pstack drops the reflect tooling and reflect judgment,
divergent, synthesizer roles, so an existing line for either is a
retired role on the next run. poteto-mode stops listing reflect as a
skill that sets its own subagents or models. Guide chapter 09
describes the new flow.

* feat(pstack): cut architect to a short brief plus a route to arena

architect now traces every system the change touches, sketches two
shapes, picks the one with one owner per piece of state, one way to do
each task and the least for callers to know, and redesigns when
workarounds repeat. A large or contested design runs the arena skill
instead.

The five phases, the runner prompt, the red-flag list and the
rationale template are deleted, along with the interface-depth text
that lived in them. setup-pstack drops the architect runners role.
poteto-mode, the Feature, Refactoring and Bug fix playbooks,
poteto-help and guide chapter 04 stop describing parallel design
exploration and the checkpoint option.

* docs(pstack): trim arena's runner and cross-judge steps

Phase A step 3 keeps the runner line, its default panel, the alias
rule, the fallback for a rejected slug (nearest slug of the same
family, or drop the seat and keep at least two runners) and the family
rule. Phase C keeps the judge pool, the other-vendor rule (Fable counts
as Claude), the unknown-parent case and the skip. The longer fallback
chains go.

* feat(pstack): cut poteto-mode to its shorter text and drop Orchestrate

poteto-mode:
- The trigger list becomes ten short lines. The long AskQuestion rule,
  the broken-skill rule and the throughput-checkpoint trigger go.
- The Subagents lead, second-opinion and fresh-subagent paragraphs get
  shorter. The model paragraphs change in a later commit.
- Writing the reply becomes one paragraph, and the Comments section is
  removed. no-comments still runs before review.
- Playbooks: match a playbook, copy its steps into the todolist tool
  first, and route large, cross-cutting or unattended work, or a task
  no playbook fits, to figure-it-out. The list names the 22 playbooks.
  A skipped step no longer stays in the list as skip: <reason>.

The Orchestrate playbook is deleted. Program-scale work routes to
figure-it-out. The README, poteto-help and guide chapters 01, 02 and
07 drop it, the playbook count becomes twenty-two, and Feature step 4
drops its pointer to the Comments section. The Claude Code adapter's
todolist row also covers the todolist tool.

* feat(pstack): give started agents the operator's rules through worker.md

Add poteto-mode/worker.md. It says who the operator is (the person the
run works for, not the agent that wrote the kickoff) and lists the
rules every started agent keeps: the kickoff's bar is the whole bar,
block only for a failing run or a user-facing bug, never ask a person
a question, open PRs ready, and the PR title and body shape.

poteto-mode gets a trigger: the first line of every kickoff, for a Task
subagent or a Project worker, is a pointer to worker.md by absolute
path, because those rules live in skills that load only from a slash
command. worker.md passes the same pointer on. Guide chapter 07
mentions it.

* feat(pstack): route code to Opus 5.5 xhigh, make Fable 5.2 an exception, cap at xhigh

Defaults:
- Code, prose and judgment: claude-opus-5-5-xhigh-fast.
- Trivial mechanical edits, swarm workers and verification:
  claude-opus-5-5-high-fast.
- Panels: claude-fable-5-2-high, claude-opus-5-5-high-fast and
  gemini-4-carbon-high. The arena cross-judge pool drops Fable, which
  is the same vendor as Opus and could judge only where Opus could.

Rules:
- Outside a panel, Fable 5.2 runs only when the user names it for the
  task or after two Opus 5.5 xhigh runs of the same brief fail their
  check. Difficulty alone never qualifies. The hardest tasks role is
  retired.
- No role runs above xhigh. The hardest work raises a role one step,
  up to xhigh. Panel seats keep their listed level.
- Opus 5.5 always runs its -fast slug. The rule that kept fast mode for
  urgent jobs is gone, and every "reasoning level and fast or standard
  speed" line now says "reasoning level".
- poteto-agent pins claude-opus-5-5-xhigh-fast, so an inherit-parent
  or auto role spawns generalPurpose. Explicit models now cover
  Project workers too.
- A second opinion and the show-me-your-work reviewer use another
  vendor's model. Eval agents that only dispatch, poll or pack results
  run on claude-opus-5-5-medium-fast.

setup-pstack writes # defaults: 3 and offers three budgets (large,
medium, small) on a ladder that tops out at xhigh. On the next run, a
rule without the new marker drops the retired roles, takes the new
cross-judge pool when it still holds the old three-seat default, turns
an unlimited budget into large, and keeps the earlier Grok migration
for rules older than # defaults: 2. Re-running the budget step rebuilds
unchanged roles from the new -fast defaults.

The README, guide chapter 01 and the Claude Code adapter describe the
new defaults. The adapter maps claude-fable-5-2-high to fable high and
says to pass model and effort on every poteto-agent spawn, so the
agent file's Cursor slug never reaches the Claude Code API.

* chore(pstack): bump to 0.15.43 and regenerate the harness tree

Regenerate harness/pstack with node scripts/generate-pstack-harness-trees.mjs
so the Claude Code tree matches the skill, agent, guide and adapter
changes in this branch.

---------
kaneyxx added a commit to kaneyxx/omc-pstack-fy that referenced this pull request Nov 17, 2026
pstack moves from v0.15.42 (bf0c7cd) to v0.15.43 (e1cc031). Every
vendored change comes from cursor/plugins#1249, which shortens the
skill texts, adds `worker.md`, and caps every role at `xhigh`.

Decisions

- `hardest tasks` stays, the owner's choice of 2026-11-17. Upstream
  retired the role. Here the hardest changes still go to `hardest
  tasks` on `fable xhigh`. Outside a panel, `fable` runs in three
  cases. A role line or a skill default names it, the user named it,
  or two Opus xhigh runs of the same brief failed. The rules live in
  `80-personal.json`.
- A new rule covers Fable's quota. When a `fable` agent fails, at spawn
  or in its result, because its usage limit or quota is reached, the
  same brief reruns on `opus` at the same effort. An arena runner seat
  and any other non-reviewer role reruns on `opus` even when that
  repeats a model. Only a reviewer panel drops the seat, because a
  duplicate reviewer makes findings look independently confirmed. A
  pool that picks one entry moves to the next entry its own rule
  allows. The rejected-model fallback stays a separate rule.
- Babysit's trigger now says "not `oh-my-claudecode:babysit`", because
  OMC 5.8 ships a skill with the same description.
- Guide page 7 says that with OMC installed, a standing multi-day
  program goes to OMC's ultragoal, team, or ralph.
- The kickoff rule drops its folder search. A reader of the file knows
  its folder.
- No role runs above `xhigh`, as upstream says. setup-pstack writes
  `# defaults: 3`, offers `large`, `medium`, and `small`, and turns an
  old `unlimited` budget into `large`. It keeps the `hardest tasks`
  line and the migration of an `opus` value there to `fable xhigh`.
- `architect runners`, `reflect tooling`, and `reflect judgment,
  divergent, synthesizer` are retired, because `architect` and
  `reflect` no longer spawn subagents. Another vendor's model now sits
  only on `interrogate reviewers`, `arena cross-judge pool`, and
  `second opinion`. setup-pstack drops a retired line, a
  `reflect tooling` line that named another vendor included.
- `arena cross-judge pool` keeps three seats. Upstream dropped Fable
  because it counts Fable and Opus as one vendor. This build compares
  model aliases, so `fable` gives an `opus` or `sonnet` parent a Fable
  judge. Upstream's migration of an old three-entry pool has no
  counterpart.
- Panels keep sonnet in the Gemini seat.
- `-fast` drops. The rule that Opus always runs its fast slug has no
  counterpart, because the Agent tool has no fast mode.
- `agents/poteto-agent.md` gets no `model` line. Claude Code runs a
  subagent on its definition's `model` when the Agent call passes
  none, so a pinned model would stop an `inherit` role line from
  running the delegate on the parent's model. `inherit` still means
  omit `model` with `omc-pstack-fy:poteto-agent`.
- `worker.md` is ported. It names `AskUserQuestion` as the tool that
  shows a person a question. poteto-mode's kickoff rule names no
  Project worker, because Claude Code has no Projects, and it finds
  `worker.md` in the plugin cache when the lead has no path.
- fy-mode's For delegates section says that a brief naming it makes
  its rules part of the kickoff, and that they win over `worker.md`.
  fy-mode no longer names the Orchestrate playbook or the consumer and
  maintainer framing, which upstream deleted.
- The OMC bridge is unchanged. Its delegates read poteto-mode, whose
  kickoff rule covers every agent they start.
- poteto-mode's short triggers name skills in bold only. The rules
  write each as "the **name** skill", so the build links it to the
  file to Read.

Rules

- `40-core.json`. One substitution now turns "Pick each subagent's
  reasoning level" into "effort level" everywhere. It replaces the old
  substitution and 16 per-file edits. One substitution is deleted.
- `50-core-skills.json`. 16 edits rewritten for poteto-mode, arena, the
  README, and guide pages 1 and 7. 8 added for the poteto-agent `model`
  line, the kickoff rule, the bold skill names, `worker.md`, and the
  README panel. 11 deleted: 6 on poteto-mode text that is gone, both
  architect edits, and the effort sentence in arena, swarm, and
  figure-it-out. The Bugbot `allow` is deleted. The setup-pstack fork
  takes the new upstream hash.
- `60-history.json`. 4 rewritten for reflect's rule-file step,
  reflect's description tuning, show-me-your-work's reviewer, and the
  comment-sicko spawn. 20 deleted: 9 on reflect's old steps, 9 on its
  four deleted templates, and the effort sentence in automate-me and
  recall.
- `70-playbooks.json`. 2 rewritten for babysit's bot triage and the PR
  tool in Opening a PR. 50 deleted: all 17 for multi-phase-plan, all 9
  for the deleted Orchestrate playbook, 6 for the deleted `check-plan`
  script and test, 4 for babysit, 3 for Opening a PR, and the effort
  sentence in 11 playbooks.
- `80-personal.json`. 3 rewritten for the OMC paragraph, Chinese
  replies, and program routing, none of which names Orchestrate now.
  5 added for `hardest tasks` and the quota rule in poteto-mode, the
  README, and guide page 1. The `reflect tooling` edit is deleted.

Docs

- `docs/claude-code-mapping.md` records each decision above with its
  reason, drops the `reflect tooling` row, and drops the Project store
  and tracker that only the Orchestrate playbook used.
- The three READMEs say that upstream retired `hardest tasks` and that
  this plugin keeps it with the `opus` fallback. The `reflect tooling`
  line is gone.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant