diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json index 68cc4443a..b39e7626e 100644 --- a/pstack/.cursor-plugin/plugin.json +++ b/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.15.15", + "version": "0.15.16", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/pstack/docs/guide/04-design.md b/pstack/docs/guide/04-design.md index 61d5bbb59..5e804d082 100644 --- a/pstack/docs/guide/04-design.md +++ b/pstack/docs/guide/04-design.md @@ -103,7 +103,7 @@ Writing the tutorial first forces the caller's view. You describe the API to a h pstack has no planning skill, on purpose. When you do want a written plan, ask for it once the design is settled: ```text -/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps. +/poteto-mode turn this design into a plan. every PR gets its own verification steps. ``` The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and it names which execution playbook should run it next. @@ -111,7 +111,7 @@ The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-p For a migration, state the bar in the prompt: ```text -/poteto-mode plan the migration of our ui library to the new styling system. small verifiable PRs, each with visual regression checks. the result must match the original exactly, bugs included. +/poteto-mode plan the migration of our ui library to the new styling system. every PR gets visual regression checks. the result must match the original exactly, bugs included. ``` "bugs included" keeps the migration from quietly fixing things on the way, which would make the old and new output impossible to compare. For a project that spans many days, you can commit the plan to the repo for a while so other agents see the work in progress. Delete it when the work lands. diff --git a/pstack/docs/guide/06-verify-and-ship.md b/pstack/docs/guide/06-verify-and-ship.md index 007ea2cab..9e24b0ba3 100644 --- a/pstack/docs/guide/06-verify-and-ship.md +++ b/pstack/docs/guide/06-verify-and-ship.md @@ -99,7 +99,7 @@ Apps change and feature maps rot. Run this at least once a day, ideally from a s /poteto-mode open the pr. small ordered commits, evidence in the description. ``` -The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Five narrow PRs beat one fat one, and stacked follow-ups beat a growing branch. +The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Each change you ask for gets one PR, and the agent stacks PRs only when a measured collision forces a split, such as an open PR that rewrites the same lines and must land first. ## Drive the PR to merge-ready with Babysit diff --git a/pstack/docs/guide/10-recipes-and-pitfalls.md b/pstack/docs/guide/10-recipes-and-pitfalls.md index 68751e7c0..7b843d508 100644 --- a/pstack/docs/guide/10-recipes-and-pitfalls.md +++ b/pstack/docs/guide/10-recipes-and-pitfalls.md @@ -31,7 +31,7 @@ You pick from things that run, not from descriptions. The agent answers its own ## Turn a settled design into a plan ```text -/poteto-mode turn this design into a plan. small verifiable PRs, each with its own proof. +/poteto-mode turn this design into a plan. every PR gets its own proof. ``` Ask only after the design settles. The plan is the deliverable, and it names the playbook that will execute it. diff --git a/pstack/skills/figure-it-out/SKILL.md b/pstack/skills/figure-it-out/SKILL.md index fbf3fb122..cb743364e 100644 --- a/pstack/skills/figure-it-out/SKILL.md +++ b/pstack/skills/figure-it-out/SKILL.md @@ -24,7 +24,7 @@ Present the framing and tradeoffs before committing to a long run. Reversible wo ## Phase B: Design the workflow -Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first. Scaffold and verification come before features (the **foundational-thinking** principle skill). +Decompose into atomic, independently-verifiable units. Sequence riskiest-unknown-first. Scaffold and verification come before features (the **foundational-thinking** principle skill). - Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value". - For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill). diff --git a/pstack/skills/poteto-help/references/recipes.md b/pstack/skills/poteto-help/references/recipes.md index 73118e2a2..3a7452b99 100644 --- a/pstack/skills/poteto-help/references/recipes.md +++ b/pstack/skills/poteto-help/references/recipes.md @@ -26,8 +26,8 @@ Swap in the real paths, skills, and done checks. Informal wording works. - `/poteto-mode we need . /architect it first, and answer open questions with prototypes. let me review before proceeding.` - `/poteto-mode write a tutorial for how i would use first. then /teach me why it beats the current one.` - `ask /arena for a second opinion on this thread and our approach.` -- `/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.` -- `/poteto-mode plan the migration of to . small verifiable PRs. the result must match the original exactly, bugs included.` +- `/poteto-mode turn this design into a plan. every PR gets its own verification steps.` +- `/poteto-mode plan the migration of to . the result must match the original exactly, bugs included.` ## Review and ship diff --git a/pstack/skills/poteto-mode/playbooks/feature.md b/pstack/skills/poteto-mode/playbooks/feature.md index 79a6bbbe0..f6c9fad17 100644 --- a/pstack/skills/poteto-mode/playbooks/feature.md +++ b/pstack/skills/poteto-mode/playbooks/feature.md @@ -11,7 +11,7 @@ - **Smallest safe decomposition.** If one worker is best, name why. 4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. 5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. -6. Rebase into small, ordered commits. Stack follow-ups. +6. Rebase into small, ordered commits. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. 7. If the design is contested, `interrogate` before shipping. 8. Run **Opening a PR**. diff --git a/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md b/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md index f8ed78a65..5ed8bc71c 100644 --- a/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md +++ b/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md @@ -5,7 +5,7 @@ 1. When the change is one or two files with an obvious approach, skip the plan. Say so and stop. 2. Settle open questions by prototype before you write. Run `playbooks/prototype.md` for each. Keep the branch, the SHA, and the screenshots for Appendix A. Ask the operator only about a product or preference call that no run can settle. Give options (the **never-block-on-the-human** principle skill). 3. Explore in subagents with `subagent_type: "poteto-agent"` and an explicit model per the Subagents section (the **guard-the-context-window** principle skill). Each returns file pointers, conventions, test commands, and entry points. No inlined dumps. -4. Copy the skeleton below into the plan file and fill every placeholder. Unless the operator names a path, write the file under the agent store's `docs/`. Keep every heading and every sub-block in the order shown. One section per PR. One PR is one change with its own evidence (the **sequence-verifiable-units** principle skill). Name the execution playbook in **How to read this**. Pick between `playbooks/autopilot-full.md` and `playbooks/autopilot-stack.md` per the rule at the end of `playbooks/autopilot-stack.md`. A standing program takes `playbooks/orchestrate.md`. +4. Copy the skeleton below into the plan file and fill every placeholder. Unless the operator names a path, write the file under the agent store's `docs/`. Keep every heading and every sub-block in the order shown. One section per PR. One PR is one change the operator asked for, with its own evidence (the **sequence-verifiable-units** principle skill). Split one across PRs only on a measured collision per **Size and stacks** in `playbooks/opening-a-pr.md`. Name the execution playbook in **How to read this**. Pick between `playbooks/autopilot-full.md` and `playbooks/autopilot-stack.md` per the rule at the end of `playbooks/autopilot-stack.md`. A standing program takes `playbooks/orchestrate.md`. 5. Write under `/technical-writing` in full, then `/unslop`. The body is one Diátaxis mode, how-to. Appendices hold explanation and reference. Each heading states the task or the finding. No long dashes. No mid-sentence colons. 6. Run `node pstack/skills/poteto-mode/scripts/check-plan.mjs ` and fix every line it prints (the **encode-lessons-in-structure** principle skill). 7. Hand back. Post the plan path and the script's output, then stop. Execution starts on the operator's explicit go, under the execution playbook the plan names. @@ -17,7 +17,7 @@ ````markdown # plan - + ## How to read this diff --git a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md index 4e2598972..f884db494 100644 --- a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md +++ b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md @@ -4,7 +4,7 @@ Invoked at the end of every other playbook. **Worktree.** Work from a git worktree off main. Subagents inherit it. Multiple `Task` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally. -**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. +**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is landable and ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. **PRs.** Run `/deslop` from `cursor-team-kit` over the diff before commit. Run `/no-comments` before review. Write every PR title, PR description, and commit body with `/technical-writing`, then apply `/unslop`. Apply every technical-writing layer except Diátaxis. Use one word for each action, keep articles, and avoid `-ing` when a plain verb works. @@ -27,7 +27,7 @@ After these sections, attach videos or screenshots when they prove a claim. Do n **Built-in PR tool.** When the run provides a built-in PR tool, create, edit, retarget, and mark ready through it, never through a forge CLI. Its own instructions say how. A PR made with the CLI misses what the tool tracks, such as a description later runs can edit. Use the resolved forge for everything the tool does not cover, and for every PR operation when the run has no such tool. -**Size and stacks.** Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. Without a built-in PR tool, create a child with `origin pr create --status open --base ` or `gh pr create --base ` according to the resolved forge, and retarget an existing child with `origin pr edit --base ` or `gh pr edit --base `. Branch from trunk only for independent work. Rebase on trunk before substantial stack work. +**Size and stacks.** Default to one PR per change the operator asked for, with small ordered commits inside it that tell the story. Split into a stack only when a measured collision forces it: an open PR rewrites the same hunk and must land first, or one part needs its own rollout. Name that measurement in the plan. Fewer files or "easier to review" is not a reason to split. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. Without a built-in PR tool, create a child with `origin pr create --status open --base ` or `gh pr create --base ` according to the resolved forge, and retarget an existing child with `origin pr edit --base ` or `gh pr edit --base `. Branch from trunk only for independent work. Rebase on trunk before substantial stack work. **Readiness.** Open every PR ready, never as a draft. A built-in PR tool can default to draft, so set `draft: false` on every creation call through it. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a PR still opens as a draft, mark it ready through the PR tool, or run `origin pr ready ` or `gh pr ready ` according to the resolved forge. Run `origin pr view ` or `gh pr view ` before you refer to PR status. diff --git a/pstack/skills/poteto-mode/playbooks/visual-parity.md b/pstack/skills/poteto-mode/playbooks/visual-parity.md index 248830ec7..d8e083cef 100644 --- a/pstack/skills/poteto-mode/playbooks/visual-parity.md +++ b/pstack/skills/poteto-mode/playbooks/visual-parity.md @@ -6,6 +6,6 @@ 2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. 3. Migrate one component at a time. Parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase. 4. Verify each component against its baseline via image diff on the matching surface via the control skill. A nonzero diff is a fail. Investigate the pixel delta. `/loop` per component until the diff is zero. -5. Run **Opening a PR** per component or per safe batch. +5. Run **Opening a PR**. **Reply:** components migrated, the diff result for each, the baseline harness location, what's left.