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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .claude/skills/sync-upstream/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This repo is two branches. `upstream` is a verbatim mirror of `cursor/plugins/ps
5. **Lint to zero.** Run `bun scripts/check-port.ts` and translate every finding. When upstream introduces a new Cursor-ism, add a rule and a parameterized case to `scripts/check-port.test.ts` first, then translate.
6. **Verify.**
- `bun test ./scripts/check-port.test.ts`
- `cd skills/poteto-mode/scripts && bun test orch watch-pr`
- `cd skills/poteto-mode/scripts && bun run test`
- `claude plugin validate .`. Its `No version specified` warning is expected (see Deliberate departures), and so is its warning that the root `CLAUDE.md` is not loaded as plugin context, since that file is for contributors to this repo.
- `claude -p --plugin-dir . "/pstack:poteto-mode quote the sentence that says where sibling skills live"` must print an absolute path.
- `claude -p --plugin-dir . "Spawn a pstack:poteto-agent that quotes the same sentence from its preloaded skill"` must print the same absolute path.
Expand Down
11 changes: 6 additions & 5 deletions .claude/skills/sync-upstream/references/translation.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Upstream slugs (`claude-opus-5-5-max`, `gpt-5.6-sol-max`, `grok-4.7-xhigh-fast`,
| iOS surfaces | the iOS Simulator tool |
| `create-skill` (Cursor built-in) | the `skill-creator` skill |
| `/visualize` (Cursor built-in) | the session's visual tool: an inline widget or an Artifact, when the session has one |
| Origin (`origin pr ...`, `--forge origin`) | delete. `gh` is the only forge, in prose and in scripts (`orch`, `worktree-audit.sh`) |
| Origin (`origin pr ...`, `--forge origin`) | delete. `gh` is the only forge, in prose and in scripts (`worktree-audit.sh`) |
| a stack as a base-branch chain changed with `gh pr edit --base` | `gh stack` (`link`, `sync`, `rebase`, `push`). GitHub restacks the rest server-side after a bottom PR merges, so upstream's post-merge retarget goes away |
| Bugbot, Cursor's agentic security review | "review bots" (Bugbot, Copilot, Greptile, CodeRabbit, and similar). The file keeps its name `references/bugbot-triage.md` |
| `setup-pstack` | edit `skills/poteto-mode/references/models.md` |
Expand All @@ -69,17 +69,18 @@ These override upstream wherever they conflict.

A sync must keep these even when upstream's line differs.

- `interrogate`, `typescript-best-practices`, and `poteto-mode` drop `disable-model-invocation`. interrogate is the pre-PR gate CLAUDE.md names, typescript-best-practices needs its `paths:` trigger, and poteto-mode is the auto-invoked entry point. Every other skill keeps the flag.
- `interrogate`, `typescript-best-practices`, `poteto-mode`, and `statechart` drop `disable-model-invocation`. interrogate is the pre-PR gate CLAUDE.md names, statechart is what a generated formal verification skill tells agents to run, typescript-best-practices needs its `paths:` trigger, and poteto-mode is the auto-invoked entry point. Every other skill keeps the flag.
- poteto-mode's Autonomy pauses for anything sent as the user (team chat, comments on other people's PRs) and for merges. Upstream let team chat proceed.
- automate-me writes the mode skill to `~/.claude/skills/<handle>-mode/` instead of a project skill shipped by PR.
- Autopilot-full needs an explicit merge grant. Babysit and Shipping never merge without an explicit request.
- orchestrate and swarm isolation: remote by default for orchestrate workers, and a worktree for any swarm worker that checks out, builds, or runs.
- Orchestrate keeps its state in `~/.claude/projects/<slug>/pstack/orchestrate/<project-slug>/notes.md`, where upstream uses Cursor's Project tracker and store. Owners merge through `merge-gate`. In a `gh stack`, one owner is the single writer, because `gh stack sync` and `rebase` push every branch. The verifier runs on the other of `opus` and `sonnet` from the owner, since upstream's different-family rule has no all-Claude equivalent.
- Arena's cross-judge is the first `arena cross-judge pool` entry whose model differs from the parent's. Upstream picks by model family, and the port's pool is all Claude, so a family rule would always skip the judge. Opus and sonnet count as different judges.
- `.claude-plugin/plugin.json` carries no `version`, where upstream's `.cursor-plugin/plugin.json` does. Claude Code then versions a GitHub-hosted install by commit SHA, so every merge to `main` reaches `claude plugin update`. A version string that does not change blocks updates. The `plugin-version` rule in `scripts/check-port.ts` keeps it out. `claude plugin validate` warns about the missing version. That warning is expected.
- interrogate adds the blind-spot lenses (`references/blind-spots.md`, Step 3 item 5), a PR number or URL as scope, the lead checking each Act on and Consider finding against source, and the someone-else's-PR flow (`references/review-comments.md`), all folded in from Lucas's retired pr-review-swarm skill. When a playbook runs it as the pre-PR gate, it hands the verdict back instead of ending the turn. The gate's rules live in Opening a PR step 2. It runs no tool-based analyzers: a CodeScene change-set step was tried and removed after an eval showed the reviewers already covered everything it found (PR #2).
- interrogate adds the blind-spot lenses (`references/blind-spots.md`, chosen in Frame and passed to every adversary), a PR number or URL as scope with each adversary's worktree on the PR head, and the someone-else's-PR flow (`references/review-comments.md`), all folded in from Lucas's retired pr-review-swarm skill. When a playbook runs it as the pre-PR gate, it hands the findings back instead of ending the turn. The gate's rules live in Opening a PR step 2, which applies every verified finding or treats it as a blocker. Upstream dropped interrogate from opening a PR. The port keeps it as the gate. It runs no tool-based analyzers: a CodeScene change-set step was tried and removed after an eval showed the reviewers already covered everything it found (PR #2).
- `skills/poteto-mode/scripts/merge-gate/` is port-only. It reuses watch-pr's readiness verdict without editing watch-pr, and adds the policy: allowed repos, human-only paths needing a human approval on the head, and head pinning with `--match-head-commit`. A PR in a GitHub native stack refuses `gh pr merge`, so the gate falls back to the merge-async REST endpoint with the same head SHA. `--stack` gates native stack positions 1 to the target as one unit: each open PR runs the same per-PR decision, with its expected base being the head of the open PR below it instead of trunk, and one merge-async call on the target, pinned to its head, lands the range atomically. merge-async pins only that head, so the gate re-reads every head and the stack just before the call and refuses a merged head it did not gate (`merged-ungated-head`). Upstream has no native stacks. Every playbook merges only through it, and a refusal is final: human-only changes are the user's to merge. The policy lives outside git, and editing it is on poteto-mode's always-pause list.
- `principle-never-block-on-the-human` narrows its force-push example to "force-push to a shared branch", matching poteto-mode's Autonomy. Autopilot owners force-push their own branches with a lease on every rebase.
- models.md uses only `opus` and `sonnet`. `fable` is dropped for cost: every role that upstream maps to it, and every panel slot, goes to `opus` or `sonnet`. interrogate runs two reviewers (`opus`, `sonnet`), accepting that both share one family and give less independent review than a cross-family pair.
- `orch frontier set` walks the PR base chain with `gh` only. Upstream's `--forge` option and its Origin branch are removed, so the command takes no forge.
- models.md uses only `opus` and `sonnet`. `fable` is dropped for cost: every role that upstream maps to it, and every panel slot, goes to `opus` or `sonnet`. interrogate runs two adversaries (`opus`, `sonnet`), accepting that both share one family and give less independent review than a cross-family pair.
- Autopilot-stack owners never force-push a branch once the root links it into the `gh stack`. They only add commits, and take the root's push as their new base and lease. Moving a PR out of a stack is the user's, since `gh stack modify` is interactive.
- Shipping and Autopilot-full merge through `merge-gate`, never `gh pr merge --squash`, and never arm `--auto`, because GitHub merges at once without required checks.
- `skills/poteto-mode/scripts/check-plan.test.ts` uses the port's plan template: "Ten lanes at the PR head" with no model, and the "Re-read them at every tick" marker.
Expand Down
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,17 @@ You can also call the other skills directly:
| `recall` | you're resuming work and want your recent context rebuilt from past sessions |
| `bro` | you want the last message restated in plain language |
| `ketchup` | you want a short catch-up on what changed since your last message, with what still needs you |
| `ketchup-video` | you want the `ketchup` catch-up as a short subtitled video of slides, with the calls waiting on you as text under it |
| `in-your-own-words` | you want the agent to play back your goal and the problem before it starts |
| `sharpen` | you want a task approached the way a top expert would, without overspecifying it |
| `sharpen` | you want a prompt made deeper, not bigger, before you send it. It returns the rewritten prompt and doesn't do the task |
| `correct` | agents keep repeating the same mistake in a repo and each one should become impossible |
| `benchmark-checklist` | you ran a benchmark and want the measurement vetted before you report it |
| `poteto-help` | you're new to pstack or unsure which skill fits. Type `/pstack:poteto-help` with a question |
| `blast-radius` | a small-looking change might break something else |
| `architect` | code crosses a function boundary and the caller's shape should be settled first |
| `arena` | you want several parallel attempts at the same thing, then the best parts of each |
| `swarm` | you want parallel workers over different slices, then one report |
| `interrogate` | a diff needs adversarial review. It is also the pre-PR gate |
| `interrogate` | a diff needs adversarial review, where only findings a run proves survive. It is also the pre-PR gate |
| `tdd` | a bug has a cheap local test path |
| `no-comments` | strip the comments this change added before review |
| `unslop`, `technical-writing` | prose, docs, PR descriptions, commit messages |
Expand All @@ -55,6 +56,8 @@ You can also call the other skills directly:
| `show-me-your-work` | long or unattended runs that need a decision trail |
| `reflect` | a long task landed and the lesson should become a skill edit |
| `create-verification-skill`, `maintain-verification-skill` | a project needs a scripted way to prove app behavior |
| `create-formal-verification-skill`, `maintain-formal-verification-skill` | a race, invariant, or other property needs proof past what tests reach |
| `statechart` | you want a TLA+ model drawn as a chart a PM or designer can read, with the shortest path to each state that breaks a rule |
| `automate-me` | you want your own `<name>-mode` skill drafted from how you work |

The 24 principles live in `skills/poteto-mode/principles/`. poteto-mode reads them on demand instead of loading them into every session.
Expand Down
2 changes: 1 addition & 1 deletion scripts/check-port.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ describe("findingsFor", () => {
["a principle entry that names its file", "skills/poteto-mode/SKILL.md", "## Principles\n\n- **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**). Multi-step work."],
["a step range that exists", "skills/x/SKILL.md", "Run Opening a PR steps 1 to 3."],
["a step named after its playbook", "skills/x/SKILL.md", "Use step 2 of the Perf issue playbook."],
["a step that exists by path", "skills/poteto-mode/playbooks/babysit.md", "Publish it per `playbooks/autopilot-stack.md` step 3."],
["a step that exists by path", "skills/poteto-mode/playbooks/babysit.md", "Publish it per `playbooks/autopilot-stack.md` step 2."],
["a step that exists by title", "skills/x/SKILL.md", "Run Opening a PR step 2."],
["a bold bullet outside both indexes", "skills/poteto-mode/SKILL.md", "## Autonomy\n\n- **Made Up Thing.** Something."],
["a playbook title that resolves", "skills/poteto-mode/SKILL.md", "## Playbooks\n\n- **Opening a PR.** Invoked at the end."],
Expand Down
6 changes: 3 additions & 3 deletions skills/arena/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,11 @@ 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` role in `models.md`, one that differs from the parent's model when possible. Spawn one judge on that model with `subagent_type: "pstack:read-only"`. It 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 the first model in the `arena cross-judge pool` role in `models.md` that differs from the parent's model. If every entry matches the parent's model, skip the judge, pick the base alone in Phase D, and say so. Spawn one judge on that model with `subagent_type: "pstack:read-only"`. It 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

Read every candidate end to end before picking. Score each against the rubric criterion by criterion, not on holistic feel, and compare with the cross-judge. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding.
Read every candidate end to end before picking. Score each against the rubric criterion by criterion, not on holistic feel, and compare with the cross-judge when Phase C ran one. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous. Read both rationales before deciding.

Pick the base a future maintainer can extend most easily without breaking invariants. When two feel tied, prefer the cleaner boundary or smaller API, per the Laziness Protocol.

Expand All @@ -45,4 +45,4 @@ Verify the synthesized artifact like any other output, per **principle-prove-it-

## Outputs

One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result.
One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict or that Phase C skipped the judge, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result.
Loading
Loading