Repository navigation
README: refresh "What Open Pstack adds" and other stale text for 1.16.0 #245
Description
Current scope (maintainer, 2026-10-22, after the design pass)
Corrections to the request below:
- "Models and token use" names no providers. The incomplete provider lists are in "What Open Pstack adds" and the "Claude Code and Codex" table.
- A quiet setup rerun also needs one valid
codex writer sandbox:line, no inconsistency or kept-predecessor choice, and passing probes. It still validates, snapshots, reads back and runs the smoke test (setup-pstack/SKILL.md:42). - The two verification offers came from Lauren's pstack (
UPSTREAM.md:41). "Get started" may describe them, but "What Open Pstack adds" does not list them. docs/reference.mdalso repeats the old routes in "Running on Codex" (lines 86, 87, 89), calls the three-model panel "upstream" (line 206), and names only Grok in its opening paragraph (line 5).
Acceptance, revised: the README names all nine provider integrations in one place, says which six run read-only lanes, and links other routing text to that place. Text about the default panel says it is the default.
Design-pass points accepted: the opening paragraph tells a Claude Code user to choose between pstack@cursor-plugins and pstack@open-pstack, and to install only one; the provider bullet says the difference is running other providers' models from Claude Code and Codex through their CLIs, because Lauren's pstack in Cursor is already multi-model; the model-proof wording keeps "where the provider reports it"; delete the two migration notes and the incomplete optional-model list in "Get started"; "changes only what Claude Code and Codex require" becomes a pointer to UPSTREAM.md; the upstream-install paragraph moves from "Staying close" to the opening.
Design-pass points rejected:
- Moving "Changes tested where they run" out of "What Open Pstack adds": README: lead with what Open Pstack adds beyond Lauren's pstack #167's scope (Eric, 2026-10-12) lists verified releases there. Reworded to say what the rule covers.
- Deleting the registry bullet's "one registry entry" sentence: README: lead with what Open Pstack adds beyond Lauren's pstack #167's scope names it.
- Deleting the allowlist and sandbox details: README: lead with what Open Pstack adds beyond Lauren's pstack #167's scope names them. Corrected instead: every external provider except Claude and Codex gets an allowlisted environment.
- Deleting the interview paragraph and quotation: not stale, so outside this issue.
- "Only Sol has
ultra" is wrong: it is right. Luna's efforts stop atmax(model-catalog.md:15).
Original request
Outcome
README.md describes Open Pstack as it ships in 1.16.0, for a developer who is new to pstack. Its "What Open Pstack adds" section lists only what Lauren's pstack does not have, now that her pstack also installs in Claude Code. docs/reference.md drops two statements that 1.16.0 and earlier releases made wrong.
Why
"What Open Pstack adds" was written for #167 on 2026-10-13. Since then:
- Lauren's pstack installs in Claude Code. Cursor's pstack 0.15.26 added
pstack@cursor-plugins, with Claude models only and no Codex. The section opens with "Beyond translating pstack for Claude Code and Codex", and the opening paragraphs say "If Claude Code or Codex is your main coding environment, use this repository". Neither tells a Claude Code user how to choose between the two. Only the last paragraph of "Staying close to Lauren's pstack" mentions the Cursor install. - Six more providers. The runner has run read-only lanes on Devin (1.9.0), DeepSeek Harness and Antigravity (1.11.0), OpenCode (1.12.0), Amp (1.13.0) and Cursor CLI (1.14.0). "What Open Pstack adds", "Models and token use" and the "Claude Code and Codex" table name only Claude, Codex and Grok.
- Allowlisted environments. The section says "Grok gets only an allowlisted environment". The model catalog's Routes table gives every external provider except Claude and Codex an allowlisted environment.
- Setup. Since 1.16.0 (setup-pstack: on a rerun with a valid sheet and passing probes, steps 4/6/7 should take the sheet as their answers #46), a setup rerun on a valid sheet with no change named does not ask again, and setup ends by offering to generate a verification skill and a formal verification skill. "Get started" says setup "asks before saving the choices".
- Old migration notes. "Get started" keeps two notes written for single releases: "as soon as this release is installed" (fix(pstack): use rolling Claude model aliases #39, 1.2.1) and "A model sheet from an earlier release keeps its panel" (1.5.0). They read as if they describe 1.16.0.
docs/reference.md. Its substitution table says Claude Code encodes the transcript folder with/→-. Since recall and session pickup name the wrong transcript folder in worktree sessions #235 the rule is: each/and each.becomes-. Its "Cross-vendor dispatch" paragraph names only Codex and Grok as external lanes.
Acceptance criteria
- "What Open Pstack adds" lists only what Lauren's pstack, in Cursor or in its Claude Code install, does not have. Each item matches
mainand links to the file that shows it. - From the opening section, a Claude Code user can tell when to install Open Pstack and when to install Cursor's
pstack@cursor-plugins, and that only one of the two should be installed. - Wherever the README lists the providers the runner can use, it names all nine and says which ones run read-only lanes.
- The setup description in "Get started" matches 1.16.0.
- The two
docs/reference.mdstatements are corrected. - The text stays plain, as the rest of the README is. No promotional wording.
- The live gate classifies the change as no runtime change and records that.
Constraints
README-UPSTREAM.mdstays unchanged.- No item describes unshipped work as shipped.
- Keep the README's section order. Move or trim text only where the refresh makes it redundant.
Suggestions, not requirements
- Split the provider bullet in two: the three providers that can write (Claude, Codex, Grok) and the six that run read-only lanes.
- Replace the two migration notes with one current sentence, or delete them if
CHANGES.mdalready says it.
Source: Eric, 2026-10-22, after the 1.16.0 announcement draft showed that the section describes Claude Code support as unique.
Activity
ericlitman commentedon Oct 22, 2026
The fix is open as #246.
Merge pull request #246 from ericlitman/docs/245-readme-refresh
ericlitman commentedon Oct 22, 2026
Closeout, checked by an independent reader. Merged as #246; six sentences it got wrong are fixed by #248 (#247).
README refresh (#245)
Each criterion comes from the issue's creation text, then from the current-scope block I wrote after the design pass on 2026-10-22.
Done as written. The PR body's Evidence table gives the source for each claim. The verification offers came from Lauren's pstack (
UPSTREAM.md:41), so they went to "Get started" instead. "Lauren's pstack does not run in Codex" rests oncursor/main:harness/pstack/, which holds onlyclaude-code/.README.md:17). The provider bullet says the difference is running other providers' models from Claude Code and Codex through their CLIs, and keeps "where the provider reports it" (README.md:21). The model-sheet bullet says setup probes each chosen model and that a rerun that changes nothing keeps the sheet (README.md:22). The panels bullet namesarena,architectandinterrogateand says Lauren's pstack defaults to Opus 5.5 and Grok (README.md:23). [Reader addition: the draft did not list these changes.]AGENTS.md, and the build lane left it as written. [Reader addition]README.md:7) still says "Open Pstack brings Lauren Tan (@poteto)'s pstack to Claude Code and Codex." I kept it: it is still true, it claims no uniqueness, and the paragraph after the quotation explains the Claude Code choice. [Reader addition: the reader asked for a recorded decision on this line.]pstack@cursor-plugins, and to install only one.Done as written, in the paragraph after the quotation (
README.md:13). The paragraph that said the same in "Staying close" is deleted.Done differently. The design pass showed that naming all nine everywhere repeats text. The revised criterion: name all nine in one place and link the other routing text there. The "Models from other providers" bullet names all nine. [Reader correction] "Models and token use" and the "Claude Code and Codex" table link the model catalog's routes table, which the provider bullet also links, not the bullet itself. The Install paragraph's sentence about other providers has no link.
README.md:46says "For the full three-model review". [Reader addition] Fixed in README: correct six sentences from the 1.16.0 refresh #247.Done as written, with one gap. The build agent wrote that a rerun "asks" after a failed probe;
CHANGES.md1.16.0 says a failed probe stops setup without writing, and I corrected the sentence before the push. The two migration notes and the optional-model list are deleted, and a link to the model catalog replaces the list (README.md:94-96). [Reader correction] "After its smoke test, setup offers to generate…" (README.md:96) does not say that a rerun that changes nothing only mentions each offer. Fixed in README: correct six sentences from the 1.16.0 refresh #247.docs/reference.mdstatements are corrected.Done, and wider. The transcript encoding (line 200) and the cross-vendor paragraph (line 210, which now links the route table) are corrected. [Reader correction] The design pass found four more stale lines (86, 87, 89 and 206), and I added line 5 in the current-scope block. Line 206 also adds that Lauren's pstack defaults to Opus 5.5 and Grok. [Reader correction] Line 5 now names "Grok and six read-only providers" as runner lanes and leaves out the Codex and Claude lanes that also use the runner. Fixed in README: correct six sentences from the 1.16.0 refresh #247.
Done. I read the diff for it. No reviewer raised wording.
Done as written.
verify-open-pstackran from main06dab3dc, planned 0 sessions, and publishedlive-gatesuccess onf04d96f8.Constraints:
README-UPSTREAM.mdis unchanged (the PR touches 2 files). No item describes unshipped work. The section order is unchanged.[Reader addition] Other changes in #246 that the draft did not report: "You need another provider's command-line tool only when your model sheet assigns that provider" (
README.md:46); "account and allowance of the tool that runs it" (README.md:142); the Codex cell "Codex models, such as Sol, stay inside Codex" (README.md:153); the Grok sentence replaced by "The other providers take part only through the runner. pstack itself runs inside Claude Code or Codex." (README.md:157); and theUPSTREAM.mdpointer in "Staying close" (README.md:177). Sections reviewed and left unchanged: "What pstack does", "Use poteto-mode", "Useful skills" (all 15 skills exist onmain), "Learn from the original", "Contributing" and "License".[Reader addition] Errors in the merged text, found by the reader and confirmed against
main, now filed as #247:README.md:177saysUPSTREAM.mdlists each adaptation.UPSTREAM.md:15saysCHANGES.mdandNOTICE.mddo.README.md:157says "pstack itself". It means Open Pstack.README.md:21and:154say "signed-in" command-line tools. OpenCode's free model needs no key.docs/reference.md:89lists only the Claude and Codex optional models. It was outside README: refresh "What Open Pstack adds" and other stale text for 1.16.0 #245's scope.docs: refresh the README and reference for 1.16.0 (ericlitman#245)