From ee95ca3590369f3db2db8aef05f3c7ee32b60b09 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 11:58:01 +0000 Subject: [PATCH 1/9] feat: make the site AI-agent readable with llms.txt, pre-rendered changelog, and generated markdown Co-Authored-By: Florin --- .github/scripts/extract-data.js | 22 ++ .github/scripts/generate.py | 363 +++++++++++++++++++++++++ .github/workflows/sync-pstack.yml | 14 +- README.md | 8 +- changelog.html | 432 +++++++++++++++++++++++++----- changelog.md | 59 ++++ index.html | 1 + llms-full.txt | 283 +++++++++++++++++++ llms.txt | 22 ++ robots.txt | 4 + sitemap.xml | 23 ++ 11 files changed, 1157 insertions(+), 74 deletions(-) create mode 100644 .github/scripts/extract-data.js create mode 100644 .github/scripts/generate.py create mode 100644 changelog.md create mode 100644 llms-full.txt create mode 100644 llms.txt create mode 100644 robots.txt create mode 100644 sitemap.xml diff --git a/.github/scripts/extract-data.js b/.github/scripts/extract-data.js new file mode 100644 index 0000000..c183ec4 --- /dev/null +++ b/.github/scripts/extract-data.js @@ -0,0 +1,22 @@ +#!/usr/bin/env node +const fs = require('fs'); +const path = require('path'); + +const repoRoot = path.resolve(__dirname, '..', '..'); +const indexPath = process.argv[2] || path.join(repoRoot, 'index.html'); + +const html = fs.readFileSync(indexPath, 'utf8'); +const scriptMatch = html.match(/ diff --git a/changelog.md b/changelog.md new file mode 100644 index 0000000..cba1ded --- /dev/null +++ b/changelog.md @@ -0,0 +1,59 @@ +# pstack upstream changelog + +Source: https://github.com/cursor/plugins/tree/main/pstack +Last synced: 2026-07-13T11:10:51+00:00 +Last commit: a29f5a8ca161b1de4ffc5484454958bebc04eaa5 + +## Recent changes + +- [2026-07-12] [pstack: bump version to 0.11.2 (#154)](https://github.com/cursor/plugins/commit/a29f5a8ca161b1de4ffc5484454958bebc04eaa5) (a29f5a8) by poteto +- [2026-07-12] [pstack: add the teach skill (compose how + why into one explanation) (#153)](https://github.com/cursor/plugins/commit/8f008c41981dca484d5beaf688d3aa2ea4ecf89b) (8f008c4) by poteto +- [2026-07-12] [pstack: bump version to 0.11.1 (#152)](https://github.com/cursor/plugins/commit/20bdb6cdfdd8ffa683befe62d76104e5654c861d) (20bdb6c) by poteto +- [2026-07-12] [maintain-verification-skill: cleanup granularity, re-doctor, evidence checks (#151)](https://github.com/cursor/plugins/commit/6714489fa233263f00e419f6cfc4759b07c81056) (6714489) by poteto +- [2026-07-12] [pstack: add create-verification-skill and maintain-verification-skill (#150)](https://github.com/cursor/plugins/commit/e42d29fd5c8fe4f13e3bee7f53b35f410f65aee8) (e42d29f) by poteto +- [2026-07-11] [pstack: give poteto-mode a human display name (#149)](https://github.com/cursor/plugins/commit/9d2a3f2d12bbe0dca3e61bbc0e9dbfe2df09fb56) (9d2a3f2) by poteto +- [2026-07-11] [pstack: lead the README with the two-step quickstart (#148)](https://github.com/cursor/plugins/commit/9251b2666bc9876396825c1f0df5685dbdaaddb5) (9251b26) by poteto +- [2026-07-11] [pstack: add model-the-domain principle; true up README (#147)](https://github.com/cursor/plugins/commit/a8145426e541afa424a403e3866496216c1b8142) (a814542) by poteto +- [2026-07-09] [pstack: make poteto-mode a sticky mode with a conditional reminder (#144)](https://github.com/cursor/plugins/commit/0dda29e839d15464a137af9935665a5a47ee09b8) (0dda29e) by poteto +- [2026-07-08] [pstack: route hardest tasks to claude-fable-5-thinking-max (#143)](https://github.com/cursor/plugins/commit/9b80b5349872b2a3404be58bd9236cc9b83833bb) (9b80b53) by poteto +- [2026-07-08] [pstack: route composer slots to grok-4.5-fast-xhigh (#142)](https://github.com/cursor/plugins/commit/dc2fae6625a268361243ca044eb5af141c124704) (dc2fae6) by poteto +- [2026-06-24] [pstack: add Benny issue automation pack (#137)](https://github.com/cursor/plugins/commit/0452e08a314c03621ec5ac1324f1ad1dd824f1a4) (0452e08) by poteto +- [2026-06-17] [pstack: add recall and blast-radius skills (#135)](https://github.com/cursor/plugins/commit/e46364b8be46000b7df0f260550cd712afbb8d36) (e46364b) by poteto +- [2026-06-14] [pstack: bump to 0.9.1, list the hillclimb playbook in the README (#133)](https://github.com/cursor/plugins/commit/cfd81b3961ef5fddc90e9f2994fa1c87cd454e61) (cfd81b3) by poteto +- [2026-06-14] [poteto-mode: add the Hillclimb playbook and tighten Autonomous run stop semantics (#132)](https://github.com/cursor/plugins/commit/b64f02a456924867d0d293cdb2f94eaecd25b50a) (b64f02a) by poteto +- [2026-06-07] [pstack: sync README with shipped principles and playbooks (#126)](https://github.com/cursor/plugins/commit/74dd2291e8e37b12fd6dc49b2acbd655c6bdaf12) (74dd229) by poteto +- [2026-06-07] [pstack: bump version to 0.9.0 (#125)](https://github.com/cursor/plugins/commit/a5cda8b561bb6536e880481734199a568cb647f4) (a5cda8b) by poteto +- [2026-06-06] [poteto-mode: shape refactoring commits before opening the PR (#124)](https://github.com/cursor/plugins/commit/91707573f17bde34e376f772ef4dd8f504747cb6) (9170757) by poteto +- [2026-06-06] [pstack: self-unblock empirical forks with a sketch instead of asking (#122)](https://github.com/cursor/plugins/commit/318e8f74ccc316b5f53e058de03fd1978ba5e041) (318e8f7) by poteto +- [2026-06-06] [pstack: add 'sequence work into verifiable units' principle (#123)](https://github.com/cursor/plugins/commit/27daaa309189aabce2dcaa2554cc940d65749a25) (27daaa3) by poteto +- [2026-06-06] [pstack: per-role model configuration via /setup-pstack (#121)](https://github.com/cursor/plugins/commit/6605d7adc3d4733b87273158c4cc49ae184409ab) (6605d7a) by poteto +- [2026-06-06] [pstack: bump version to 0.7.0 (#117)](https://github.com/cursor/plugins/commit/881e794248cd8d3855807abd7e48f2083809d175) (881e794) by poteto +- [2026-06-06] [pstack: add skeptical-reviewer trigger and arena routing for multi-shape work (#116)](https://github.com/cursor/plugins/commit/97d645a601330acf0257e51ce646aa497855c35f) (97d645a) by poteto +- [2026-06-06] [pstack: add pause-safely playbook (clean checkpoint for suspending work) (#115)](https://github.com/cursor/plugins/commit/2f3a47e6c404daa4bd24e8a0686751be39ed889b) (2f3a47e) by poteto +- [2026-06-05] [pstack: fold enforcement-strength rung into encode-lessons-in-structure (#114)](https://github.com/cursor/plugins/commit/64fe0147d32e0c05d2953501ddf9ff65ebcadc54) (64fe014) by poteto +- [2026-05-30] [pstack: concision pass on how, interrogate, architect, reflect (#106)](https://github.com/cursor/plugins/commit/c8402bc8e3673b973719fe3acc2c4837fef34f86) (c8402bc) by poteto +- [2026-05-30] [pstack: concision pass on why and poteto-mode (#105)](https://github.com/cursor/plugins/commit/f7e01457bba4499be1ce302484e4225f9a3c9eca) (f7e0145) by poteto +- [2026-05-29] [pstack: bump to 0.6.0 and refresh README (#104)](https://github.com/cursor/plugins/commit/683cdbda983ea8be4b766ac3fe94b7b88e7f75ad) (683cdbd) by poteto +- [2026-05-29] [pstack: frame reply impact for the consumer and the maintainer (#103)](https://github.com/cursor/plugins/commit/c532aa167cdbceb3440706ceacea2361e4d395df) (c532aa1) by poteto +- [2026-05-29] [pstack: build-the-lever defaults to building the tool for any non-trivial work (#102)](https://github.com/cursor/plugins/commit/ba7781cce69f65bf3edc0e789d28233d9e967f96) (ba7781c) by poteto +- [2026-05-29] [pstack: bump version to 0.5.0 (#101)](https://github.com/cursor/plugins/commit/bb3e1656658b12f0b1f2f1aa868449b678779487) (bb3e165) by poteto +- [2026-05-29] [pstack: interrogate gains a multi-model code-quality lens (#100)](https://github.com/cursor/plugins/commit/939812915e8a1c2359b0ea8d93fee7c29c41f60e) (9398129) by poteto +- [2026-05-29] [pstack: update Opus 4.7 references to 4.8 (#98)](https://github.com/cursor/plugins/commit/ec44aed93cda65227954d46c75be3a2f218144a3) (ec44aed) by poteto +- [2026-05-28] [pstack: architect usage-first design (caller's usage as the spec) (#99)](https://github.com/cursor/plugins/commit/0fe5b8a0952fd8888f9068f0693099ae74d25902) (0fe5b8a) by poteto +- [2026-05-28] [pstack: bump version to 0.4.0 (#93)](https://github.com/cursor/plugins/commit/9da4009e1278994a5623f23c262f8bde55830598) (9da4009) by poteto +- [2026-05-28] [pstack: build-the-lever can be a skill your subagents follow (#91)](https://github.com/cursor/plugins/commit/65f4dacee2ed677a295de8d295b889bbfe2ad27c) (65f4dac) by poteto +- [2026-05-27] [pstack: bump version to 0.3.0 (#90)](https://github.com/cursor/plugins/commit/6f2e0c63189ce3b661040153d82a32a2038560ba) (6f2e0c6) by poteto +- [2026-05-27] [show-me-your-work: add cross-model review of the trail (#89)](https://github.com/cursor/plugins/commit/47f3df82728f0df2233ed9d773ba0fba74cd79e3) (47f3df8) by poteto +- [2026-05-26] [pstack: bug-fix binary-search hypothesis loop, synthetic repro, /loop (#88)](https://github.com/cursor/plugins/commit/8d7ca2653dfe8632f02a33c426df28c064ca41be) (8d7ca26) by poteto +- [2026-05-26] [pstack: bump version to 0.2.0 (#86)](https://github.com/cursor/plugins/commit/21327bee99f30a73758c99f6c6459571bc9f6e98) (21327be) by poteto +- [2026-05-26] [pstack: refresh README playbooks (full list as a table) (#85)](https://github.com/cursor/plugins/commit/7dddd9bcfe5f53136ee4d9a8377da96a4860ef4a) (7dddd9b) by poteto +- [2026-05-26] [pstack: add build-the-lever principle (#84)](https://github.com/cursor/plugins/commit/7b1c32e4c3427c30ad2595630ed74815c52fe4e9) (7b1c32e) by poteto +- [2026-05-26] [pstack: add session-pickup and trace-forensics playbooks (#83)](https://github.com/cursor/plugins/commit/bbc0d75eb2f115124f6fbe9e5c8f27f579779345) (bbc0d75) by poteto +- [2026-05-26] [pstack: add refactoring playbook (#81)](https://github.com/cursor/plugins/commit/f18ffc1bd6b41a017ab97c53debcf140a8f754fd) (f18ffc1) by poteto +- [2026-05-25] [pstack: add figure-it-out and show-me-your-work to README examples (#80)](https://github.com/cursor/plugins/commit/a9e675642ea4297553a4d8c23f5d8a5b004f6626) (a9e6756) by poteto +- [2026-05-25] [pstack: harden show-me-your-work log.sh (formula-injection + mkdir -p) and shorten skill descriptions (#79)](https://github.com/cursor/plugins/commit/11ecc12a3ffc037b4ef3b64de2be449668e8afc7) (11ecc12) by poteto +- [2026-05-24] [pstack: add figure-it-out and show-me-your-work skills (#78)](https://github.com/cursor/plugins/commit/35f33923cde39e9c27d68d95517e4e4e83719c7c) (35f3392) by poteto +- [2026-05-24] [pstack: simplify the feature README example (#77)](https://github.com/cursor/plugins/commit/b8f2564c2e8da66b331c1dd63c2a2925d6739961) (b8f2564) by poteto +- [2026-05-23] [pstack: add usage examples to README (#76)](https://github.com/cursor/plugins/commit/3dd382f4dbf3753ea5c5fac0935bb5a8a0789021) (3dd382f) by poteto +- [2026-05-23] [pstack: add typescript-best-practices to README skills table](https://github.com/cursor/plugins/commit/6754d3c09e5ea95de453ac1330f8648a82bbe00a) (6754d3c) by poteto +- [2026-05-23] [Add pstack plugin](https://github.com/cursor/plugins/commit/24bd6eb895d63a6e76fabfea2cb344384d177d79) (24bd6eb) by poteto diff --git a/index.html b/index.html index 4e4c038..3d5fedc 100644 --- a/index.html +++ b/index.html @@ -15,6 +15,7 @@ + diff --git a/llms-full.txt b/llms-full.txt new file mode 100644 index 0000000..a158eb3 --- /dev/null +++ b/llms-full.txt @@ -0,0 +1,283 @@ +# pstack explained + +pstack is poteto's set of engineering skills for coding agents, installed with `/add-plugin pstack`. +This site is an unofficial reading aid at https://hustlecoding.github.io/pstack-explained/. + +## Overview + +Type `/poteto-mode` and describe a task. pstack matches the task to a playbook, then runs the appropriate skills as the steps fire. +Twenty principles apply across every playbook, biasing the work toward small diffs and real verification. + +## Playbooks + +A playbook is a step-by-step recipe for one kind of task. `/poteto-mode` copies the matched one in full before any work starts. + +### Investigation +Trigger: A read-only question. How does X work, why was Y built this way, are we sure about Z, should we do X or Y. +Detail: Read-only. The deliverable is a cited answer, not a change. Stay in the evidence instead of building a sketch to settle an empirical fork. + +### Bug fix +Trigger: A reported defect to reproduce, root-cause, and fix with runtime evidence. +Detail: Reproduce first on the same surface yourself. Trace each symptom to its root cause. Fix there, then verify against the real artifact. + +### Perf issue +Trigger: A measured slowness to trace and improve against a baseline. +Detail: One-off fix against a measured baseline, not a sustained loop. That distinguishes it from Hillclimb. + +### Hillclimb +Trigger: Sustained, scientific improvement of one metric against a target. Loop hypotheses with before/after measurement and one commit per accepted win. +Detail: Distinct from Perf issue, which is a one-off. Here you keep looping, logging each accepted win as its own commit. + +### Runtime forensics +Trigger: Diagnose a runtime symptom like a leak, idle-CPU spin, or glitch from live instrumentation. +Detail: The deliverable is a diagnosis, not a fix. Instrument the live system and read the symptom. + +### Trace forensics +Trigger: Diagnose a captured profiling artifact like a cpuprofile, trace, spindump, or heap snapshot handed to you after the fact. +Detail: The deliverable is a diagnosis, not a fix. The artifact is already captured; you read it. + +### Feature +Trigger: New or changed behavior, built from a named data shape. +Detail: Name the data shape first. Build the lever. Verify it works against the real artifact, not a proxy. + +### Refactoring +Trigger: A behavior-preserving change to structure or shape. Rename, extract, inline, dedupe, or move. +Detail: Behavior must stay identical. Bias to deletion and the smallest diff. Remove dead weight before restructuring. + +### Prototype +Trigger: A throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it instead of asking. +Detail: Built to decide, not to ship. The throwaway probe answers faster than a question to the human and hands back a result to react to. + +### Visual parity +Trigger: Pixel-exact UI equivalence. Matching two implementations or migrating a styling system. +Detail: Reproduce the drift first. Fix until it matches the reference, measured on the real surface. + +### Authoring a skill +Trigger: Writing or editing a SKILL.md. +Detail: Shape the trigger, the steps, and the reply contract. Encode lessons in structure rather than more text. + +### Eval +Trigger: Testing how a skill, structure, or prompt change affects agent behavior before promoting it. +Detail: Blinded comparison against a baseline. Measure behavior change before you promote the new version. + +### Autonomous run +Trigger: A long task to drive to completion without stopping. Run until done, /loop until X, going to bed. +Detail: Keep a decision trail via show-me-your-work so the human can audit it when they return. Commit the trail when stakes need a record. + +### Session pickup +Trigger: Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. +Detail: Reconstruct state from the record. Fire a fresh subagent with consolidated scope rather than trusting a done summary. + +### Pause safely +Trigger: Suspending in-flight work cleanly so it can be resumed. On an explicit pause, going offline, a restart, or imminent compaction. +Detail: The complement to Session pickup. Leave the work in a state another agent can pick up without guessing. + +### Multi-phase plan +Trigger: Work that spans phases or stacked PRs. +Detail: Break the work into verifiable units. Order delivery so the sequence proves itself, each unit green before the next. + +### Figure it out +Trigger: No bundled playbook fits. Design a bespoke, rigorous playbook for the task. +Detail: Used for large or cross-cutting efforts like a migration across many call sites, or work the user steps away from to trust later. + +### Opening a PR (meta playbook) +Trigger: Invoked at the end of every other playbook. +Detail: Not a task shape of its own. It fires once the matched playbook's work is done, to package and ship the result. + +## Skills + +Skills are the individual moves. Reach for one directly when you want a specific result instead of the full route. + +### /poteto-mode +When to use: Default entry point for any non-trivial task. Reads your request, picks a playbook, and routes the other skills as the steps fire. + +### /how +When to use: You want a walkthrough of how a subsystem works. + +### /why +When to use: You want to know why something was built this way. Discovers MCPs at runtime and queries each evidence category in parallel. + +### /recall +When to use: You are starting or resuming work and want your recent context on a topic rebuilt from your chat history and the shared record. + +### /blast-radius +When to use: A small-looking change and you want to know what else it could break, proven by running code rather than asserted. + +### /architect +When to use: About to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. + +### /arena +When to use: You want N parallel attempts at the same thing, then grab the best parts of each. + +### /interrogate +When to use: You have a diff and want four different models to try to break it, including a strict code-quality lens. + +### /automate-me +When to use: You want your own -mode skill, drafted from how you have actually worked. + +### /setup-pstack +When to use: You want to pick which models pstack uses per role. Detects your models and writes a config rule. + +### /reflect +When to use: A long task landed and you want the recipe captured as a skill edit so the next run does not repeat it. + +### /tdd +When to use: You are fixing a bug and there is a cheap local test path. Write the failing test first, then the fix. + +### /typescript-best-practices +When to use: You are reading or editing TypeScript. Grounds the type-system-discipline principle in syntax. + +### /figure-it-out +When to use: No bundled playbook fits. Designs a rigorous, auditable playbook for the task. + +### /show-me-your-work +When to use: You want a reviewable decision trail. Logs decisions to a TSV you can commit. + +### /unslop +When to use: You are cleaning up writing. Removes AI tells. + +## Principles + +Twenty rules in five families. Each principle has a name, when it applies, and the rule to follow. + +### Core +How to sequence work and scope it. The bias to delete before you add. + +- **Laziness Protocol** + - Applies when: Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. + - Rule: Bias to deletion and the smallest change that solves the problem. If a human maintainer would find it exhausting, it is a bad solution. + +- **Foundational Thinking** + - Applies when: Before writing logic. Core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share. + - Rule: Get the data shape right before writing logic. The right shape makes downstream code obvious. + +- **Redesign From First Principles** + - Applies when: Integrating a new requirement into an existing design. + - Rule: Do not bolt it on. Redesign as if the requirement had been there from day one. + +- **Subtract Before You Add** + - Applies when: Sequencing an addition, refactor, or rewrite. + - Rule: Remove complexity first, then build. Deletion gives a simpler base, which makes the next addition smaller and less brittle. + +- **Minimize Reader Load** + - Applies when: Reviewing or shaping code that is hard to trace. + - Rule: Count layers and hidden state. Collapse one-caller wrappers and shrink mutable scope. + +- **Outcome-Oriented Execution** + - Applies when: Planned rewrites and migrations with explicit phase boundaries. + - Rule: Optimize for the intended, verifiable end state. Do not preserve smooth intermediate states. + +- **Experience First** + - Applies when: Product, UX, or feature-scope tradeoffs. + - Rule: Choose user delight over implementation convenience. Ship fewer polished features over more rough ones. + +- **Exhaust the Design Space** + - Applies when: A novel interaction or architectural decision with no precedent. + - Rule: Build 2 to 3 competing prototypes and compare before committing. + +- **Build the Lever** + - Applies when: Any non-trivial work. + - Rule: Build the tool that does or proves it. The tool is the artifact a reviewer reruns. + +### Architecture +Boundaries, types, and shared state across concurrent actors. + +- **Boundary Discipline** + - Applies when: Wiring validation, error handling, or framework adapters. + - Rule: Guards at system boundaries. Trust internal types. Keep business logic in pure functions. + +- **Type System Discipline** + - Applies when: Designing types or a signature in any typed language. + - Rule: Make illegal states unrepresentable. The type checker is a proof assistant. + +- **Make Operations Idempotent** + - Applies when: Designing commands, lifecycle steps, or loops that run amid crashes and retries. + - Rule: Converge to the same end state regardless of partial prior runs. + +- **Migrate Callers Then Delete Legacy APIs** + - Applies when: Introducing a new internal API while old callers exist. + - Rule: Migrate callers and remove the old API in the same wave. No compatibility layers. + +- **Separate Before Serializing Shared State** + - Applies when: Concurrent actors might write the same file, branch, key, or object. + - Rule: Eliminate the sharing first. When sharing is real, enforce serialization structurally. + +### Verification +Proving it works against the real artifact, and ordering the work so each step can be checked. + +- **Prove It Works** + - Applies when: After a task, before declaring done. + - Rule: Verify against the real artifact. Not a proxy. Not that it compiles. + +- **Fix Root Causes** + - Applies when: Debugging. + - Rule: Trace each symptom to its root cause. Reproduce first. Ask why until you reach it. + +- **Sequence Work into Verifiable Units** + - Applies when: Multi-step work and how you stack commits and PRs. + - Rule: Order work as small units, each ending in a state you can check. Do not advance until the current one is green. + +### Delegation +Keeping context lean and staying unblocked on the human. + +- **Guard the Context Window** + - Applies when: Context fills up. Large outputs, long files, repeated reads, fan-out planning. + - Rule: Route bulk to subagents. Keep summaries in the main thread, not raw payloads. + +- **Never Block on the Human** + - Applies when: Tempted to ask should I do X on reversible work. + - Rule: Proceed. Present the result. Let the human course-correct after the fact. + +### Meta +Turning repeated corrections into structure that enforces itself. + +- **Encode Lessons in Structure** + - Applies when: You catch yourself writing the same instruction a second time. + - Rule: Encode it as a lint, metadata flag, runtime check, or script instead of more text. + +## Models per role + +pstack can use a different model for each role. Some roles run several models in parallel so the reviews come from different angles. +Run `/setup-pstack` to detect your models and write the rule. Skills read it and fall back to their own defaults when a line is missing, so you override only what you want. + +- **feature, refactoring** (single) — Code work that builds or restructures. +- **bug-fix** (single) — Reproduce, root-cause, and fix with evidence. +- **perf-issue** (single) — Trace measured slowness against a baseline. +- **hillclimb** (single) — Loop hypotheses against a target metric. +- **judgment and prose** (single) — Where judgment and writing quality matter most. +- **how explorer** (single) — Maps the subsystem inside the /how skill. +- **how explainer** (single) — Writes the /how walkthrough. +- **how critics** (panel) — One subagent per model reviews the explanation. +- **why investigators** (single) — Queries one evidence category inside /why. +- **why synthesizer** (single) — Combines the evidence into the cited answer. +- **reflect tooling** (single) — Captures the tooling recipe in /reflect. +- **reflect judgment, divergent, synthesizer** (single) — Captures the judgment recipe in /reflect. +- **arena runners** (panel) — One subagent per model produces a competing attempt. +- **architect runners** (panel) — One subagent per model explores a design. +- **interrogate reviewers** (panel) — One subagent per model tries to break the diff. + +## Recent upstream changelog + +Source: https://github.com/cursor/plugins/tree/main/pstack +Last synced: 2026-07-13T11:10:51+00:00 + +- [2026-07-12] pstack: bump version to 0.11.2 (#154) (a29f5a8) by poteto +- [2026-07-12] pstack: add the teach skill (compose how + why into one explanation) (#153) (8f008c4) by poteto +- [2026-07-12] pstack: bump version to 0.11.1 (#152) (20bdb6c) by poteto +- [2026-07-12] maintain-verification-skill: cleanup granularity, re-doctor, evidence checks (#151) (6714489) by poteto +- [2026-07-12] pstack: add create-verification-skill and maintain-verification-skill (#150) (e42d29f) by poteto +- [2026-07-11] pstack: give poteto-mode a human display name (#149) (9d2a3f2) by poteto +- [2026-07-11] pstack: lead the README with the two-step quickstart (#148) (9251b26) by poteto +- [2026-07-11] pstack: add model-the-domain principle; true up README (#147) (a814542) by poteto +- [2026-07-09] pstack: make poteto-mode a sticky mode with a conditional reminder (#144) (0dda29e) by poteto +- [2026-07-08] pstack: route hardest tasks to claude-fable-5-thinking-max (#143) (9b80b53) by poteto +- [2026-07-08] pstack: route composer slots to grok-4.5-fast-xhigh (#142) (dc2fae6) by poteto +- [2026-06-24] pstack: add Benny issue automation pack (#137) (0452e08) by poteto +- [2026-06-17] pstack: add recall and blast-radius skills (#135) (e46364b) by poteto +- [2026-06-14] pstack: bump to 0.9.1, list the hillclimb playbook in the README (#133) (cfd81b3) by poteto +- [2026-06-14] poteto-mode: add the Hillclimb playbook and tighten Autonomous run stop semantics (#132) (b64f02a) by poteto +- [2026-06-07] pstack: sync README with shipped principles and playbooks (#126) (74dd229) by poteto +- [2026-06-07] pstack: bump version to 0.9.0 (#125) (a5cda8b) by poteto +- [2026-06-06] poteto-mode: shape refactoring commits before opening the PR (#124) (9170757) by poteto +- [2026-06-06] pstack: self-unblock empirical forks with a sketch instead of asking (#122) (318e8f7) by poteto +- [2026-06-06] pstack: add 'sequence work into verifiable units' principle (#123) (27daaa3) by poteto diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..5015b98 --- /dev/null +++ b/llms.txt @@ -0,0 +1,22 @@ +# pstack explained + +pstack is poteto's set of engineering skills for coding agents. This site is an unofficial, interactive reading aid. + +- Live site: https://hustlecoding.github.io/pstack-explained/ +- Source: https://github.com/HustleCoding/pstack-explained +- Upstream pstack source: https://github.com/cursor/plugins/tree/main/pstack + +## AI-readable endpoints + +- `llms-full.txt` — complete pstack guide (playbooks, skills, principles, model roles) plus the latest upstream changelog +- `changelog.md` — plain Markdown changelog of changes to `cursor/plugins/pstack` +- `changelog.json` — machine-readable JSON changelog with the same entries +- `changelog.html` — rendered HTML changelog + +## How to use this site + +Type `/poteto-mode` and describe a task. pstack matches the task to a playbook, then runs the appropriate skills as the steps fire. Twenty principles apply across every playbook, biasing the work toward small diffs and real verification. + +## For AI agents fetching this page + +If you are an AI agent, fetch `llms-full.txt` for the complete pstack reference. Fetch `changelog.md` or `changelog.json` to see the latest changes in the upstream pstack repo and decide whether the local environment needs new skills, playbooks, or configuration updates. diff --git a/robots.txt b/robots.txt new file mode 100644 index 0000000..987a3c8 --- /dev/null +++ b/robots.txt @@ -0,0 +1,4 @@ +User-agent: * +Allow: / + +Sitemap: https://hustlecoding.github.io/pstack-explained/sitemap.xml diff --git a/sitemap.xml b/sitemap.xml new file mode 100644 index 0000000..a271c36 --- /dev/null +++ b/sitemap.xml @@ -0,0 +1,23 @@ + + + + https://hustlecoding.github.io/pstack-explained/ + 2026-07-13 + + + https://hustlecoding.github.io/pstack-explained/changelog.html + 2026-07-13 + + + https://hustlecoding.github.io/pstack-explained/changelog.md + 2026-07-13 + + + https://hustlecoding.github.io/pstack-explained/llms.txt + 2026-07-13 + + + https://hustlecoding.github.io/pstack-explained/llms-full.txt + 2026-07-13 + + From 1412bd390ccdce852a6878bc70ab138967a6fc10 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 12:56:41 +0000 Subject: [PATCH 2/9] feat: add teach, verification skills and Model the Domain principle from latest pstack Co-Authored-By: Florin --- index.html | 12 ++++++++---- llms-full.txt | 13 +++++++++++++ 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index 3d5fedc..a434017 100644 --- a/index.html +++ b/index.html @@ -205,9 +205,9 @@

pstack

-

20 principles · 17 playbooks · 16 skills

+

21 principles · 17 playbooks · 19 skills

Engineering skills that turn a coding agent into a careful crew. You describe a task, and pstack matches it to a playbook.

-

Type /poteto-mode and describe a task. pstack matches it to a playbook and runs the skills as the steps fire. Twenty principles apply across every playbook, biasing the work toward small diffs and real verification.

+

Type /poteto-mode and describe a task. pstack matches it to a playbook and runs the skills as the steps fire. Twenty-one principles apply across every playbook, biasing the work toward small diffs and real verification.

@@ -269,7 +269,7 @@

Skills

04

Principles

-

Twenty rules in five families. Tap any one to see when it applies and what it says.

+

Twenty-one rules in five families. Tap any one to see when it applies and what it says.

@@ -359,7 +359,10 @@

{cmd:"/typescript-best-practices", when:"You are reading or editing TypeScript. Grounds the type-system-discipline principle in syntax."}, {cmd:"/figure-it-out", when:"No bundled playbook fits. Designs a rigorous, auditable playbook for the task."}, {cmd:"/show-me-your-work", when:"You want a reviewable decision trail. Logs decisions to a TSV you can commit."}, - {cmd:"/unslop", when:"You are cleaning up writing. Removes AI tells."} + {cmd:"/unslop", when:"You are cleaning up writing. Removes AI tells."}, + {cmd:"/teach", when:"Explain a body of work plainly so a person actually understands it. Runs `how` and `why` and weaves what they find into one clear explanation."}, + {cmd:"/create-verification-skill", when:"Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform."}, + {cmd:"/maintain-verification-skill", when:"Periodic pass that keeps a project's verification skill and feature map honest."} ]; const GROUPS = [ @@ -386,6 +389,7 @@

{g:"arch", n:"Make Operations Idempotent", applies:"Designing commands, lifecycle steps, or loops that run amid crashes and retries.", rule:"Converge to the same end state regardless of partial prior runs."}, {g:"arch", n:"Migrate Callers Then Delete Legacy APIs", applies:"Introducing a new internal API while old callers exist.", rule:"Migrate callers and remove the old API in the same wave. No compatibility layers."}, {g:"arch", n:"Separate Before Serializing Shared State", applies:"Concurrent actors might write the same file, branch, key, or object.", rule:"Eliminate the sharing first. When sharing is real, enforce serialization structurally."}, + {g:"arch", n:"Model the Domain", applies:"When writing stateful logic, or when code branches a lot or repeats a shape assumption across files.", rule:"Encode the real domain in a data structure instead of scattering it across conditionals. Reach for state machines, typed models, lookup tables, reducers, or small module boundaries that gather repeated behavior. Don't force an abstraction if the current shape is already clear and local."}, {g:"verif", n:"Prove It Works", applies:"After a task, before declaring done.", rule:"Verify against the real artifact. Not a proxy. Not that it compiles."}, {g:"verif", n:"Fix Root Causes", applies:"Debugging.", rule:"Trace each symptom to its root cause. Reproduce first. Ask why until you reach it."}, diff --git a/llms-full.txt b/llms-full.txt index a158eb3..6f74dd9 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -136,6 +136,15 @@ When to use: You want a reviewable decision trail. Logs decisions to a TSV you c ### /unslop When to use: You are cleaning up writing. Removes AI tells. +### /teach +When to use: Explain a body of work plainly so a person actually understands it. Runs `how` and `why` and weaves what they find into one clear explanation. + +### /create-verification-skill +When to use: Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. + +### /maintain-verification-skill +When to use: Periodic pass that keeps a project's verification skill and feature map honest. + ## Principles Twenty rules in five families. Each principle has a name, when it applies, and the rule to follow. @@ -202,6 +211,10 @@ Boundaries, types, and shared state across concurrent actors. - Applies when: Concurrent actors might write the same file, branch, key, or object. - Rule: Eliminate the sharing first. When sharing is real, enforce serialization structurally. +- **Model the Domain** + - Applies when: When writing stateful logic, or when code branches a lot or repeats a shape assumption across files. + - Rule: Encode the real domain in a data structure instead of scattering it across conditionals. Reach for state machines, typed models, lookup tables, reducers, or small module boundaries that gather repeated behavior. Don't force an abstraction if the current shape is already clear and local. + ### Verification Proving it works against the real artifact, and ordering the work so each step can be checked. From 7c88c828fc8ed0ae19c33643a8dd7f50cb627bda Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 19:53:25 +0000 Subject: [PATCH 3/9] feat: add Agent Templates section for lionbenjamin/agent-templates Co-Authored-By: Florin --- index.html | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) diff --git a/index.html b/index.html index a434017..1c5cff0 100644 --- a/index.html +++ b/index.html @@ -30,6 +30,7 @@ --rule:#ededed; --rule2:#e0e0e0; --accent:#b45309; --accent-soft:#fdf4ea; --accent-line:#e8c39a; --core:#b45309; --arch:#1f6f8b; --verif:#4d7c2f; --deleg:#b13a5a; --meta:#7c4d9e; + --t-setup:#7c4d9e; --t-sdlc:#b45309; --t-orch:#b13a5a; --t-special:#1f6f8b; --maxw:880px; --navh:54px; --ff:"Hanken Grotesk",system-ui,-apple-system,sans-serif; --ff-mono:"IBM Plex Mono",ui-monospace,monospace; @@ -71,6 +72,8 @@ .sh .num{color:var(--accent); font-family:var(--ff-mono); font-size:12px; letter-spacing:.04em} .sh h2{font-weight:600; font-size:clamp(24px,3.6vw,31px); margin:7px 0 12px; letter-spacing:-.018em; line-height:1.15} .sh .lead{color:var(--dim); font-size:16px; line-height:1.6; margin:0; max-width:60ch} + .sh .lead a{color:var(--accent); text-decoration:none; border-bottom:1px solid var(--accent-line)} + .sh .lead a:hover{border-bottom-color:var(--accent)} /* routing */ .flow{margin:0 0 28px; font-size:15px; color:var(--dim); line-height:1.9} @@ -167,6 +170,8 @@ .kind.panel{color:var(--arch); border-color:rgba(31,111,139,.35); background:rgba(31,111,139,.06)} .mowns{color:var(--dim); font-size:13.5px; line-height:1.5} .models-note{color:var(--faint); font-size:13.5px; margin-top:20px; max-width:60ch; line-height:1.6} + .tmpl-note a{color:var(--accent); text-decoration:none; border-bottom:1px solid var(--accent-line)} + .tmpl-note a:hover{border-bottom-color:var(--accent)} /* modal */ .overlay{position:fixed; inset:0; background:rgba(20,20,20,.45); backdrop-filter:blur(4px); display:none; align-items:center; justify-content:center; z-index:60; padding:clamp(16px,4vw,24px)} @@ -218,6 +223,7 @@

pstack

Skills Principles Models + Templates Changelog @@ -287,6 +293,19 @@

Models per role

+
+
+
+ 06 +

Agent Templates

+

A companion toolkit by lionbenjamin: spec-driven agent workflows you install into Antigravity, Cursor, and Claude Code. Same idea as pstack — named workflows a coding agent runs — but organized as a spec-first SDLC, from a written constitution through spec, plan, code, and deploy.

+
+

/constitute /specify /plan /implement /deploy /retro

+
+

Install every workflow with ./install-workflows.sh, which copies them into ~/.claude/commands/, ~/.cursor/commands/, and the Antigravity dirs. Every step reads a shared technical constitution and a lessons-learned memory file, so the spec, the plan, the code, and the review stay consistent across sessions — spec-driven rigor with an auditable trail instead of one-shot vibe coding. Source and full docs: lionbenjamin/agent-templates.

+
+
+