Sync upstream

This repo is two branches. upstream is a verbatim mirror of cursor/plugins/pstack, one commit per sync. main is the Claude Code port, and it merges upstream, so every sync is a real 3-way merge: upstream's edits land on top of the port's translations, and only lines both sides touched conflict.

Steps

1. Branch. From a worktree off main, create sync/upstream-<date>.
2. Mirror. Run scripts/sync-upstream.sh. It fast-forwards upstream from origin, commits the new snapshot, and pushes it, or reports that nothing changed. If nothing changed, stop and say so. If it warns that the previous sync has not landed, land it first. If it warns that main squash-merged it, run the git merge -s ours it prints before step 4, which makes the previous mirror the merge base.
3. Read why. gh api --paginate 'repos/cursor/plugins/commits?path=pstack&per_page=100' lists upstream's commits. Read down to the previously synced SHA, which the script printed. Read the messages of the new ones so the merge preserves poteto's intent, not just the text.
4. Merge. git merge upstream. Resolve each conflict per references/translation.md: take upstream's new substance and keep the port's translation of it. Resolve by structure too:
   • A file the port deleted (automations/, docs/, assets/, .cursor-plugin/, skills/make-bot-ui/, skills/setup-pstack/, the root plugin.json) stays deleted. Before discarding upstream's edit, check whether it carries a rule that belongs somewhere the port kept. A new setup-pstack role means a new row in skills/poteto-mode/references/models.md.
   • skills/poteto-help/ is rewritten for Claude Code, not mirrored. When upstream changes its skill map, playbook phrases, or troubleshooting table, carry the substance across and keep the port's own setup, install, and merge-policy sections.
   • README.md is the port's own. Keep ours, and add any new skill to its table.
   • A new skills/principle-*/SKILL.md moves to skills/poteto-mode/principles/principle-*.md, rewriting its relative links: ../principle-x/SKILL.md becomes ./principle-x.md, and ../<skill>/ becomes ../../<skill>/.
   • A new skill or playbook gets ported, unless it only makes sense in Cursor. Then delete it and add it to the list above.
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 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.
   • claude -p --plugin-dir . "Spawn a pstack:read-only agent and ask it to create a file named probe.txt" must report that it refused or could not.
   • bun scripts/check-port.ts again, last, so nothing a verify step suggested slipped past it.
7. Ship. Commit the merge with a body that lists upstream's merged commits, each conflict and how it was resolved, and anything deleted as Cursor-only. Run the interrogate gate, push, and open the PR ready. Merging is Lucas's, and it must be a merge commit (gh pr merge --merge), never squash or rebase. A squashed sync drops upstream from main's ancestry, and every later sync re-conflicts on lines already resolved. Say this in the PR body.