omp-pstack is an independent adaptation of Poteto's P Stack for Oh My Pi (OMP). It provides multi-model coding workflows, engineering playbooks, verification guidance, and automation tools for OMP's native agents.
The original P Stack was created by Lauren Tan (poteto). Its engineering approach and much of its skill content originated in the upstream project. This adaptation preserves that credit and the original MIT license while owning the OMP-specific implementation and direction here.
omp plugin marketplace add https://github.com/Jrecos/omp-pstack
omp plugin install omp-pstack@omp-pstackUse OMP 18.10.2 with this checkout. The SDK is pinned to 18.10.2. Native task completion uses final text, and writable workers can use schema-gated isolation.
the helper commands (orch, watch-pr, check-plan, worktree-audit, log, plus the routine and benny commands documented below) live in the installed package. invoke them through the installed root, whatever scope you installed in.
the marketplace copies the plugin without installing npm dependencies. OMP can load the native extension, but the standalone CLI and CLI-backed skills need the package dependencies. install them before using those commands:
PSTACK_ROOT="$(omp plugin list --json | bun -e 'const d=await Bun.stdin.json(); const m=(d.marketplace??[]).filter(p=>p.id==="omp-pstack@omp-pstack"&&!p.shadowedBy).flatMap(p=>p.entries??[]).find(e=>e.enabled!==false&&e.installPath); const n=(d.npm??[]).find(p=>p.name==="omp-pstack"&&p.enabled!==false); process.stdout.write(m?.installPath ?? n?.path ?? "")')"
bun install --production --frozen-lockfile --cwd "${PSTACK_ROOT:?No active omp-pstack installation found}"
bun "$PSTACK_ROOT/src/cli.ts" routine listmarketplace installs are listed under the canonical id omp-pstack@omp-pstack, and each entry carries an installPath — project-scope installs are listed before user-scope (a shadowed user entry is marked shadowedBy), so the resolver above picks the active scope automatically. npm/link installs appear under npm with path. working from a checkout of this repository instead? skip the resolver: PSTACK_ROOT="$(pwd)".
Refresh the marketplace catalog before upgrading the installed plugin:
omp plugin marketplace update omp-pstack
omp plugin upgrade omp-pstack@omp-pstackRestart OMP after the upgrade to load the updated extension and skills. Check the installed version with omp plugin list.
After each upgrade or forced reinstall, repeat the installed CLI dependency setup before using CLI-backed skills.
plugin upgrade and forced reinstalls can use a stale marketplace cache. Do not skip marketplace update, and do not add the marketplace again.
If your OMP version has no plugin upgrade, refresh the catalog and force a reinstall:
omp plugin marketplace update omp-pstack
omp plugin install omp-pstack@omp-pstack --forceupdating replaces the plugin code (skills, CLI, runtime) but keeps your configuration: the managed rule rules/pstack-models.md, your approved model pool, and the prepared agent profiles under agents/ are regenerated on the next /setup-pstack save or pstack prepare, not by the update itself. after a breaking change to agent naming or profile layout, run /setup-pstack once and save to restage fresh profiles and sweep stale ones.
upgrading from a pre-0.15.0 config: the how critics role is retired and the 17-role parser rejects a config still carrying its line. before the next /setup-pstack save, edit rules/pstack-models.md to remove the how critics: role line, and any stale # how critics[...] address comments next to it. keep the approved model pool and every other role assignment. do not delete the whole config.
repo maintainers can verify manifest completeness, recorded source blobs, and byte-exact unadapted files against the pinned upstream commit with bun scripts/check-upstream.ts <cursor/plugins checkout>.
to move the pin, run bun scripts/sync-upstream.ts <cursor/plugins checkout> <commit> <version>. it copies unadapted files, three-way merges adapted files against the old upstream blob (conflicts land as <<<<<<< omp markers), adds new upstream files, and rewrites upstream.json. then resolve the markers, record new adaptations, and repin EXPECTED_HEADER and the inventory digest in scripts/check-content.ts.
two steps:
- run
/setup-pstack, pick a reasoning budget, and choose which models you want. - use
/poteto-modewhenever you're doing anything that requires rigor.
new here? the pstack guide walks you through a first real task, from setup and prompting through verification and overnight runs. stuck, or unsure which skill fits? ask /poteto-help.
The native capability assessment explains which host features fit P Stack, their measured effects, and the limits. Worktrees, worker isolation, and Benny's Docker boundary solve different problems.
that's it. the other skills are situational. the mode uses them as needed. /setup-pstack asks you to approve a model pool, choose a reasoning budget, and confirm the role map. no model is used without your approval. an unset role needs setup.
use /poteto-mode at the start of a task. it reads your request, picks from a set of playbooks, and runs the other skills as the steps need them.
For a substantive task, Poteto mode uses task-specific memory already in the conversation. It calls OMP's native recall tool only when that context is missing or a new historical question arises. This is separate from the P Stack recall skill, which reconstructs broader working history. Recalled claims are unverified until checked against current evidence and never authorize action. The mode instructs the agent to keep irrelevant or malicious memories out of replies and delegate briefs. If memory is unavailable, work continues without installing or repairing it.
These are agent instructions, not runtime guarantees of retrieval, deduplication, or filtering. Verify consequential remembered claims against current primary evidence.
To check a configured model, set PSTACK_SMOKE_MODEL to its authenticated selector and run bun scripts/smoke-memory-context.ts /tmp/pstack-memory-context.json. This optional native SDK smoke uses controlled memories and an isolated profile. It checks lookup discipline, rejected-memory omission, and a prepared read-only delegate. The same model also reviews unsupported incident and rationale claims. That verdict is not a semantic correctness guarantee. Inspect the recorded answers. A failure reports a model or integration limit rather than silently accepting it.
Poteto mode requires the Documentation completion gate for every permanent change. Features, fixes, refactors, and local work without a PR all use it. Casual chat and read-only questions do not.
The agent adds the gate to task todos before delivery and inspects the diff and existing doc conventions. It updates affected docs with technical-writing and unslop, without creating every doc type mechanically. Changed decisions supersede accepted ADRs rather than overwrite their history.
A fresh independent read-only reviewer checks changed docs claim by claim against source, contracts, and observed evidence. Each claim receives CONFIRMED, WRONG, or UNVERIFIABLE with its evidence. Missing evidence blocks completion rather than count as a pass. The agent corrects false claims, reruns applicable checks safely, and obtains fresh review of corrections. Unresolved required documentation blocks commit, ready, and complete. Final replies and PR Verification name docs paths and exercised accuracy checks. If no docs need changing, they give a concrete reason tied to the inspected diff and docs.
This is a mandatory instruction-level policy, not runtime hard enforcement. The plugin does not intercept commits or PR readiness to enforce it. The optional scripts/smoke-workflow-guidance.ts documentation cases exercise read-only guidance in actual OMP sessions with synthetic fixture files. Their recorded semantic conditions need review. Read receipts alone do not prove correctness, and the smoke does not write or independently review real change documentation end to end.
Use this lane only for a Feature request that explicitly asks for official GitHub Spec Kit. Install the pinned stable specify-cli 1.0.12 release and initialize a fresh, separate Git worktree from its root:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.12
specify init . --integration omp --non-interactive --ignore-agent-tools --script sh --force
specify integration status --jsonThe status must be ok with no findings. Then ask /poteto-mode Build <feature> with official Spec Kit. P Stack keeps its eight Feature steps and configured model roles. Its read-only pstack_speckit tool checks the installed CLI, OMP command source and rendered arguments, and plugin-owned SHA-256 pins for official commands, Bash scripts, and templates. It returns one phase's instructions without executing them. It does not register /speckit.* commands, run a workflow, or select a separate model. The feature spec, plan, quickstart, and tasks remain official CLI-generated OMP artifacts.
The pin covers the files that supply phase instructions or executable shell behavior. .specify/init-options.json, .specify/.gitignore, and .specify/workflows/ are not pinned because this lane supplies the feature directory explicitly, does not execute workflow YAML, and does not treat ignore rules as authority. Custom presets, template overrides, and extensions are rejected rather than trusted.
The tool also refuses active or malformed .specify/extensions.yml hooks, unsafe feature paths, symlinks, status warnings, shared checkouts, and missing official assets. Choose a new direct child of specs/ and pass it as featureDirectory even for the first specify phase. Do not put SPECIFY_FEATURE_DIRECTORY inside any phase argument. Keep one feature binding per worktree. Review .specify/feature.json against the original request and pass the same canonical directory to each later phase. The check does not sandbox another process that mutates files concurrently. If any gate fails, stop this opted-in run rather than switching to ordinary Feature.
Run bun run check:speckit-assets when reviewing a CLI pin change. This regenerates a clean official fixture and checks immutable plugin-owned hashes without repinning them. Review upstream source before changing a pin. For completion, inspect quickstart.md before execution and observe a real product effect. Generated files and exit status alone do not prove the Feature works.
just use /poteto-mode
this skill is the main shortcut for rigorous engineering work. it comes with twenty-three playbooks:
/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro
first, then fix and verify.
/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by
morning.
the twenty-three playbooks
| playbook | for |
|---|---|
| investigation | a read-only question. how does x work, why was y built this way, are we sure. |
| bug fix | reproduce a defect, root-cause it, and fix with runtime evidence. |
| perf | trace a measured slowness and improve it against a baseline. |
| hillclimb | sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win. |
| runtime forensics | diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation. |
| trace forensics | diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot). |
| feature | new or changed behavior, built from a named data shape. |
| refactoring | a behavior-preserving change to structure or shape. |
| prototype | a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it. |
| visual parity | pixel-exact ui equivalence between two implementations. |
| authoring a skill | writing or editing a SKILL.md. |
| eval | test how a skill or prompt change affects agent behavior, blinded. |
| babysit | drive a pr or a stack to merge-ready: conflicts, review threads, ci. |
| shipping | independently verify a green stack, then land the contiguous verified run bottom-up through github by default or origin when available. |
| autonomous run | drive a long task to completion without stopping. |
| orchestrate | a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents. |
| autopilot-full | run independent prs to merged with one owner per pr and a root swarm verification round at code-ready and after each patch-changing push. |
| autopilot-stack | build and verify one linear base-branch stack for the operator to review and land. |
| session pickup | resume or take over a prior agent's in-flight work. |
| pause safely | suspend in-flight work cleanly so it can be resumed later. |
| multi-phase plan | work that spans phases or stacked PRs. |
| worktree cleanup | reclaim disk by pruning merged or abandoned worktrees and stale ios simulators, safety-gated. |
| opening a pr | open a ready pr from small ordered commits with a conventional commits title and a briefing-style body. invoked at the end of every other playbook. |
when invoked it:
- matches your task to a playbook and opens a todo list whose first items are its steps, copied in verbatim.
- routes to the other skills as the steps fire.
- writes unslopped replies framed for the consumer and the maintainer.
the full rules and playbooks live in skills/poteto-mode/SKILL.md.
Invoking /poteto-mode turns on persistent mode for the current OMP session branch. The plugin keeps its rules in context on later turns. It applies when a playbook matches or the task needs rigor and stays out of the way otherwise. Say "stop poteto mode" or "normal mode" to turn it off.
/poteto-mode works extremely well with omp's built-in /loop command. you can make the agent work for many hours without sacrificing rigor.
/poteto-mode runs most supporting skills for you when a step needs them. Invoke a direct workflow skill when you want that specific behavior:
/how do we cancel runs? do we have an n+1 when we look up every run to cancel?
/interrogate review this pr.
The complete skills reference lists all 53 discoverable skills with their purposes and source files. It separates 29 direct workflow skills from 24 supporting principles. Bare /<name> commands are available for direct skills when no other command owns the name. OMP's /skill:<name> form reaches all 53.
| New skill | Use it when |
|---|---|
/poteto-help |
Find the skill, playbook, or principle for your goal and get a prompt to send. It runs only when you invoke it and does not start the work. |
/ketchup |
Catch up on this chat since your last message, in plain words, with enough context to decide each action item. |
/correct |
Fix repeated agent mistakes at the highest enforceable level, with architecture first and documentation last. Pair each rule with its enforcement. |
/benchmark-checklist |
Vet a measured number for its limiter, tuning, errors, repeatability, end-to-end relevance, and whether the timed work ran. |
/session-review reviews the last 10 sessions in the current workspace. Use /session-review 25 to select the last 25, or /session-review 25 --plugin-report to add a separate, sanitized plugin-feedback section. The bare command rejects invalid counts and flags locally before dispatching a model turn. The /skill:session-review alternative is prompt-driven and has no host-side argument gate. The review uses the full available history window, not only the last seven days, and never edits the repository or sends a report elsewhere. Results appear in chat unless you explicitly request a private saved copy.
The repository report names the selected sessions and cites entry IDs for supported findings, recoveries, and counterexamples. It checks relevant current files before suggesting a small change. Fewer available sessions, unreadable records, partial history, and uncertain causes stay visible in the coverage and limits. The optional plugin section is written to stand alone without session IDs, private paths, or transcript excerpts; inspect it yourself before sharing. History lives locally, but the configured model and provider process the selected content through your normal account. The history reader does not supply exact timing, cost, or full subagent traces.
Maintainers can exercise the command with PSTACK_SMOKE_MODEL=<authenticated-selector> bun scripts/smoke-session-review.ts. The smoke uses synthetic sessions in a disposable profile and records the observed reports in proofs/session-review.json.
most workflows start with /poteto-mode and let it route to a playbook. the other skills fire as the steps need them; invoke one directly only when you want that specific workflow.
all the examples
bug fix: /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even
when idle. repro first, then fix and verify.
perf: /poteto-mode a big list takes a second or two to load even though we virtualize.
run a cpu trace and tell me why.
feature: /poteto-mode build a small feature behind a feature flag. verify it really works.
prototype: /poteto-mode build two prototypes of the markdown renderer so we can compare.
spawn an agent for each.
multi-phase: /poteto-mode open source these skills as a plugin. nothing internal leaks, work
in a temp dir, show me the dependency graph first.
overnight run: /poteto-mode i'm going to bed. land the stack even if ci flakes. i want
everything merged by morning.
babysit: /poteto-mode check on pr 123. anything outstanding?
visual parity: /poteto-mode the row spacing is too tall when this flag is on. the second image
is correct. repro and fix until it matches.
figure it out: /poteto-mode i'm stepping away. migrate every caller from the synchronous store
to the new async one, keeping behavior identical. i want to trust it was done
right when i'm back.
how: /how do we cancel runs? do we have an n+1 when we look up every run to cancel?
why: /why is this feature flag not on yet?
architect: design this instrumentation to be high signal with no false positives. /architect
this first.
arena: /arena take my prompt to the arena verbatim. i want to compare their proposals
with yours.
swarm: /swarm check every package under packages/ against its check.sh. one worker per
package. one report.
interrogate: /interrogate review this pr.
tdd: /tdd implement
unslop: can we unslop and tighten the new changes?
reflect: /reflect that took too long. capture what we learned so the next run doesn't
repeat it.
correct: /correct
show-me-your-work: /show-me-your-work keep a decision trail i can review when i'm back.
automate-me: /automate-me
help: /poteto-help which skill should i use to review this branch?
/poteto-mode runs in the chat that receives it. That chat owns the playbook, the todo list, and every subagent spawn.
pstack ships the poteto-agent wrapper for delegates spawned during a run. Resolve the configured role through pstack_agent with kind: "poteto", then pass its returned agent to native task. The prepared agent pins your approved model and reads poteto-mode in full, including its inline principles index, before doing any work. Substituting the generic task agent skips that read and drifts. Do not spawn poteto-agent to run the playbook itself.
/poteto-mode and prepared Poteto agents use the same style instructions.
pstack ships Comment Sicko, a read-only comment reviewer available as the native comment-sicko agent. Dispatch native task with agent: "comment-sicko". Usually invoke it through /no-comments, not directly.
twenty-four short skills, one principle each. poteto-mode indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each.
all twenty-four principles
| principle | group | rule |
|---|---|---|
| laziness-protocol | core | Bias toward deletion and the smallest change that solves the problem. |
| foundational-thinking | core | Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious. |
| redesign-from-first-principles | core | Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on. |
| attack-the-premise | core | Apply when two or more fixes that share one premise have failed the same gate. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing another fix that assumes it. |
| subtract-before-you-add | core | Remove dead weight, redundant validators, and stub references first, then build on the simpler base. |
| minimize-reader-load | core | Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope. |
| outcome-oriented-execution | core | Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code. |
| experience-first | core | Choose user delight over implementation convenience; ship fewer polished features over more rough ones. |
| exhaust-the-design-space | core | Build 2-3 competing prototypes and compare side by side before committing. |
| build-the-lever | core | Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun. |
| model-the-domain | architecture | Encode the domain in a structure instead of scattered conditionals. |
| boundary-discipline | architecture | Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions. |
| type-system-discipline | architecture | Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas. |
| make-operations-idempotent | architecture | Converge to the same end state regardless of partial prior runs. |
| migrate-callers-then-delete-legacy-apis | architecture | Migrate callers and delete the old API in the same wave instead of preserving compatibility layers. |
| separate-before-serializing-shared-state | architecture | Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant. |
| prove-it-works | verification | Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'. |
| fix-root-causes | verification | Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes. |
| sequence-verifiable-units | verification | Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer. |
| test-behavior-not-implementation | verification | Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test. |
| explain-the-number | verification | Before trusting, reporting, or acting on a measured number, find what limits it. Rule out that it measured work other than the work you intended. |
| guard-the-context-window | delegation | Route bulk to subagents; keep summaries in the main thread, not raw payloads. |
| never-block-on-the-human | delegation | Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions. |
| encode-lessons-in-structure | meta | Encode the rule as a lint, metadata flag, runtime check, or script instead of more text. |
a few things poteto-mode references needed omp translations. the adapted guidance ships inside this plugin, under skills/poteto-mode/references/:
omp-deslop.mdreplaces thecursor-team-kitdeslopskill: the same diff-cleanliness checks over the diff against main.omp-control-cli.mdandomp-control-ui.mdreplacecontrol-cliandcontrol-ui: driving CLIs/TUIs and browser/Electron/web UIs with native tools (supervised processes,browser.*, hub process control).omp-create-skill.mdis the skill-authoring guidance other skills route through.
inside poteto-mode, the babysit playbook owns pr-status requests; don't route those to a built-in skill whose description matches the same words.
omp has native plan mode, which works well with pstack. planning is deliberately not the default: code is usually the best spec. when a plan is useful, /poteto-mode covers it.
poteto-mode encodes poteto's style. you may not want exactly that.
type /automate-me. it mines your recent transcripts, drafts a <your-name>-mode skill from how you've actually worked, and routes through pstack underneath. you keep pstack as the base and end up with your own routing skill alongside poteto-mode.
models are configurable too. type /setup-pstack. it detects the models you have access to, takes the approved pool first, and writes a small always-applied rule mapping each role (code, judgment, the review panels) to a pool member. every skill reads that rule; there are no hardcoded defaults left, so a role that isn't configured needs setup, and dispatch fails closed rather than substituting a model you didn't approve.
Rerunning setup keeps your approved pool and role identities unless you change them. It infers your current reasoning budget from saved effort suffixes. Removing a role line makes that role unconfigured. Run /setup-pstack to assign it again.
pstack also ships a dormant benny automation pack. benny triages slack issue reports, then reproduces and fixes confirmed bugs with real ui evidence. its files are not registered as slash skills.
to set it up, run the CLI from the installed root (see running the pstack CLI after install): bun "$PSTACK_ROOT/src/cli.ts" benny setup --target <repo> (intent documented in FOR_AGENTS.md). setup copies the pack into the target repository at .omp/automations/benny/, installs omp-pstack there at project scope for the shared skills, and keeps user configuration outside the copied pack under .omp/benny/. deployment is gated: pstack benny check (every check except canary), then a passing pstack benny canary, then a rerun of pstack benny check (all checks pass, including canary), before pstack benny enable.
evidence retention: every benny run's screenshots and recordings expire after control.artifact_retention_hours (default 24). the native runner sweeps expired evidence on startup and while runs settle, but a quiet host with no further events needs an external pass: schedule the one-shot sweep from cron or a systemd timer, e.g. hourly
bun "$PSTACK_ROOT/src/cli.ts" benny sweep --config .omp/benny/configuration.yamlwith PSTACK_ROOT resolved once per host as in running the pstack CLI after install. the sweep never deletes evidence owned by queued or running runs, and it fails closed (deletes nothing) when run ownership cannot be established.
.github/workflows/ci.yml checks each pull request's merge result with main, not just its head. It installs the frozen lockfile, runs type checking, the full test suite, and content integrity checks. Run the same suite locally with bun run test. This command uses bun test --isolate to prevent module mocks from leaking between files. It remains sequential so Docker fixtures do not run in parallel. The workflow also handles merge-queue checks. The job has read-only permissions and does not persist checkout credentials.
The Benny integration suites create private temporary OMP profiles and restore the previous profile after cleanup. They do not need an initialized developer profile. Docker-dependent suites rebuild their fixture image from current source with a bounded 10-minute setup hook.
The Docker fixture image uses the invoking host's non-root POSIX UID and GID. Benny uses the same identity for sandbox processes, bounded storage, and seed ownership checks so private host snapshots remain accessible without broader permissions. The trusted control adapter remains root-owned and read-only. Run these fixtures as a non-root user with Docker access.
Benny rejects UID 0, GID 0, or missing POSIX identity before sandbox resource creation. Preflight probes adapter readability as the same user that runs the sandbox, not the image's default user. This ownership contract targets rootful Docker. Rootless Docker and user-namespace remapping are not verified.
The real workspace proof reports failed adversarial probes by name. Its background-writer receipt records actual bytes written, the child's quota exit, and unchanged host-directory bytes. A successful aggregate alone is not evidence that a writer ran.
The mount probe checks namespace destinations and Docker's mount and bind records. It permits only the exact read-only snapshot and owned staging volume. Filesystem source names do not prove that a host home or root directory is mounted.
.github/workflows/pr-title.yml validates Conventional Commit pull request titles with a SHA-pinned action. It reads pull request metadata without checking out contribution code. These workflows do not configure branch protection. Make checks and title required checks in repository rules to enforce them before merge. Dependabot proposes weekly updates to GitHub Actions pins only, not npm dependencies or the OMP SDK pin.
Dependabot uses ci(deps): titles so action-update pull requests pass the same title check. Merging an action update intentionally produces a patch release under the per-pull-request policy.
After release checks pass, each pull request merged into main gets a GitHub release. .github/workflows/release.yml handles merged pull requests, including fork contributions, and queues release runs. It runs type checking, release regression tests, and content integrity checks on trusted main, then passes the verified commit to scripts/release.ts. If main changes before publication, the run fails rather than releasing unchecked code. The first release is 1.0.0. Later releases use the pull request title and breaking-change footer in its body, independent of the squash commit message:
| pull request | bump |
|---|---|
A title such as feat!: or fix(cli)!:, or a BREAKING CHANGE: or BREAKING-CHANGE: footer |
major |
feat: or feat(scope): |
minor |
everything else, including docs: and untyped titles |
patch |
The release commit updates package.json to match its vX.Y.Z tag. The annotated tag records the version, pull request, and release notes. A rerun uses that record instead of allocating another version. The script never moves or deletes tags, pushes the branch and tag atomically without force, and does not publish to npm. This project's version is independent of the upstream P Stack version recorded in upstream.json.
The native proof producers and content checker hash parsed package.json with only its top-level version omitted. A release-only version change therefore leaves native proof freshness intact. Nested versions, dependency pins, scripts, the lockfile, and producer sources remain binding. The shared digest helper is itself a required hashed input. SDK package manifests and all other listed sources keep their raw-byte hashes. Meaningful input changes require a real proof rerun, not an edited hash receipt.
To recover a failed or cancelled run, use gh workflow run release.yml -f pr=<number> from this repository, or select Run workflow in the Actions tab.
- If
mainchanged or the push was rejected, rerun aftermainis stable. - If a type, test, or content check fails, fix the checked source or regenerate stale proofs with their real producers before retrying. A version-only release does not require proof regeneration.
- If the tag was pushed but release publication failed, a rerun publishes that tag without another version bump.
- Before allocating a version, the script repairs missing releases for earlier managed tags.
After publication, verify that the GitHub release exists and its tag's package.json version matches the tag. A successful merge alone does not prove that publication succeeded.
The token needs permission to write repository contents. Future branch rules must allow the release bot's version commits. The queue holds 100 pending runs. GitHub cancels overflow runs, which need manual recovery. Releases follow queue order rather than merge order. Each release is a cumulative snapshot of verified main, so it can include changes merged after the pull request that triggered it.
Based on P Stack by Lauren Tan (poteto), adapted from upstream version 0.15.20. Exact upstream repository, commit, file lineage, and adaptation records are tracked in upstream.json.
Released under the MIT License. The original copyright notice is retained.