Engineering workflows for OpenAI Codex: investigate, design, implement, review, and verify.
An independent Codex adaptation of Lauren Tan’s pstack, with 52 core skills, 23 playbooks, and an additional Thermo-Nuclear Code Quality Review. Start with a goal and a checkable completion criterion. The workflows guide your agent through understanding the code, choosing an approach, making the change, and reporting evidence.
Install · Examples · Skills · Updates · Compatibility
Use a Codex CLI version with plugin marketplace support. Run in your terminal:
codex plugin marketplace add LeonardSEO/pstack-for-codex --ref main
codex plugin add pstack-for-codex@leonardseo-pstackStart a new Codex session in your project, then invoke:
$poteto-mode Fix the search filter resetting when I change pages.
Done when the selected filter survives pagination and a regression test passes.
You can also select the skill from your host’s skill picker. No separate model setup is required: workflows inherit the current Codex model by default.
If your CLI reports an unknown plugin command, update Codex to a version that supports plugins. Installation commands register the marketplace and install the plugin; they do not change your application code.
Give the agent a concrete outcome and the evidence you expect.
Fix a regression
$poteto-mode Fix duplicate submissions when Save is clicked twice.
Done when only one record is created and the regression test passes.
Understand a subsystem
$how Explain how authentication reaches the API in this repository.
Include ownership boundaries and references to the relevant code.
Review a change without editing
$thermo-nuclear-code-quality-review Audit this branch against main.
Focus on structural complexity, unnecessary abstractions, and branching growth.
Report actionable findings with file and line references. Do not edit files.
Compare implementation options
$arena Compare two approaches to caching the product list.
Judge them on correctness, invalidation behavior, and maintenance cost.
Parallel candidates require available and permitted native agent tools. When delegation is unavailable, the runtime contract specifies sequential fallback and disclosure of the verification limits.
| Your goal | Skill | What it guides |
|---|---|---|
| Take a task from investigation to verification | poteto-mode |
Select a playbook and coordinate the work |
| Understand existing behavior | how |
Trace architecture, runtime flow, and ownership |
| Understand a design decision | why |
Investigate motivation and supporting evidence |
| Design a change across boundaries | architect |
Examine structure before implementation |
| Compare alternative solutions | arena |
Evaluate candidates and verify the synthesized result |
| Challenge a proposed design | interrogate |
Apply adversarial review to assumptions and tradeoffs |
| Audit maintainability strictly | thermo-nuclear-code-quality-review |
Identify structural regressions and opportunities to remove complexity |
| Check what a change could break | blast-radius |
Examine downstream effects and prove key safety assumptions |
| Develop through observable behavior | tdd |
Use failing and passing tests to guide implementation |
| Make verification reusable | create-verification-skill |
Record a repeatable project verification workflow |
| Improve technical documentation | technical-writing |
Structure explanations around the reader’s task |
| Find your next workflow | poteto-help |
Explore the available skills and their uses |
The full skill collection also includes engineering principles covering domain models, type boundaries, root causes, idempotency, and behavior-focused tests.
The 23 playbooks cover bug fixes, features, refactoring, performance investigations, prototypes, evaluations, PR preparation, shipping, and session recovery. Each workflow remains subject to your project instructions and authorized scope.
The port adapts the workflows to Codex’s exposed capabilities:
- Native tools: use the host’s actual shell, file, question, and agent tools.
- Inherited models: keep the current model and reasoning settings unless a supported override is authorized.
- Explicit configuration: optional project preferences live in
.agents/pstack-config.md, whichpoteto-modereads explicitly. - Clear approval boundaries: repository instructions and host permissions govern publishing, deployment, messages, and destructive actions.
- Honest verification: distinguish static package checks, tests, independent review, and live integration evidence.
The package supplies skills, playbooks, reference prompts, and portable helpers. Browser access, forge authentication, credentials, MCP servers, and cloud runners depend on your host. Session loops end with the session; future wakeups require a separate scheduling capability. Benny resources are retained as historical references.
Read the runtime contract for execution rules and the sync design for conversion scope and verification limits. Helper scripts may require their documented runtimes, such as Bash, Node, Bun, git, gh, or jq.
A GitHub Action checks pstack upstream daily at 04:17 UTC and supports manual runs. Upstream is authoritative: it replaces local differences in imported files, adds new content and removes files deleted upstream. A complete candidate is built and checked before it is committed directly to main, then the existing versioned release procedure runs. Content warnings do not block publication; source retrieval, unsafe paths and invalid package structure do. No review PR or AI API key is required, and upstream helper code is not executed during synchronization.
Refresh your installation:
codex plugin marketplace upgrade leonardseo-pstack
codex plugin add pstack-for-codex@leonardseo-pstackStart a new session after updating. GitHub may delay scheduled runs and disables schedules in inactive public repositories after 60 days. Repository branch rules must permit the sync workflow to push.
Releases provide tagged snapshots and release notes. For a fresh installation pinned to this release, replace --ref main in the installation command with --ref v0.15.23. A pinned marketplace stays on that ref until you change it.
Each automated release includes a ZIP archive and a SHA-256 checksum. The marketplace commands above are the recommended installation route. Codex adaptations do not receive a separate version number. A version-only upstream change also updates the plugin; changes within the same upstream version keep that version. Existing published releases remain immutable; follow main for later Codex fixes within the same version. After validation, the workflow ensures the current version has a release, skips an already published release, and can finish a draft left by an interrupted upload. Assets are uploaded before the release becomes public.
thermo-nuclear-code-quality-review comes from Cursor’s cursor-team-kit. Its entire directory is excluded from pstack synchronization, including additions, edits, and deletions of a same-name upstream skill. This skill is maintained manually, with its MIT attribution preserved.
Documentation corrections, compatibility fixes, and reproducible bug reports are welcome. Open an issue with the plugin version, Codex version, invoked skill, expected result, and relevant evidence. Remove credentials and private data before sharing logs.
For changes to the package or synchronizer, run the repository checks:
python3 -m pip install -r requirements.txt
python3 -m unittest discover -s tests -v
python3 scripts/validate.pyThe commit in upstream.json records the last copied source. It is not a merge base. The synchronizer reads the complete committed pstack tree and rebuilds the package from it, including previously unknown directories and executable file modes. Do not edit imported files to maintain a permanent fork: the next sync overwrites those edits, even if upstream has not changed.
The Codex manifest, marketplace entry, runtime contract, existing Codex skill metadata and the independent review skill/license remain locally owned. Native host configuration is stored below references-host, and automation examples below references-benny, without activating host integrations. The plugin's imported README and guides follow upstream; this repository README describes the Codex installation.
Known translations in scripts/codex_adaptations.json are applied when unambiguous. Missing or overlapping matches retain upstream text and produce warnings. Unknown host instructions, model names and broken content links are warnings, not publication gates. The runtime contract governs execution; a successful sync does not prove that every upstream integration works in Codex.
The Action publishes a JSON/Markdown report with the source commit, file counts, warnings and push/release status. If main changes before the push, the candidate is rebuilt from the new main in a fresh temporary worktree, up to three attempts, without force-pushing. An unchanged candidate creates no empty commit. Published releases remain immutable even when main changes within the same upstream version.
See the sync design for ownership and failure behavior. Tests replay the October regressions, verify upstream overwrite/deletion, and exercise direct pushes, races and denied pushes against local Git remotes.
Based on Lauren Tan’s pstack, with the additional review skill from cursor-team-kit. Original copyright notices are preserved in LICENSE and LICENSE-cursor-team-kit.
An independent, MIT-licensed adaptation for Codex. This project is not an official Cursor or OpenAI distribution. See OpenAI’s plugin packaging documentation for the plugin and marketplace formats.