This document explains how the upstream pstack workflows map to Codex. It describes the derivative behavior, not installation steps for the original host.
The plugin manifest is .codex-plugin/plugin.json. The local marketplace manifest is .agents/plugins/marketplace.json. Codex discovers 49 skills under skills/. Each skill has agents/openai.yaml metadata and sets allow_implicit_invocation: false.
This follows the current OpenAI documentation for Codex skills and plugin packaging. The upstream logo maps to interface.logo, while explicit-only invocation stays in each skill's agents/openai.yaml.
Installed identities use the plugin namespace. Prompts use the explicit $skill-name form. Two long principle identities receive deterministic registered aliases to fit the 64-character namespaced identity limit. No skill is dropped.
The 23 Poteto Mode playbooks remain ordinary Markdown resources under skills/poteto-mode/playbooks/. They are not independently registered skills.
Invoking $poteto-mode applies it to the current turn. Trusted session hooks can persist the mode for later turns. State is keyed by a hash of the session and project, stored below plugin data, written atomically, and removed after its time-to-live window.
The hook receipt is the only proof that later-turn activation succeeded. When a stable session identifier, project fingerprint, state file, or trusted receipt is unavailable, the status is current-turn-only. Resume and compaction do not change that rule. disable $poteto-mode clears matching session state.
The hook configuration matches only pstack-poteto-agent for subagent context propagation. A generic agent does not become a Poteto agent by name similarity.
The upstream personas became portable prompts plus optional Codex TOML profiles:
| Role | Portable prompt | Optional profile |
|---|---|---|
| Poteto implementation | poteto-agent-prompt.md |
pstack-poteto-agent |
| Comment review | comment-sicko-prompt.md |
pstack-comment-sicko |
$setup-pstack installs profiles at project or user scope. Its receipt records hashes and ownership. Upgrade and uninstall refuse a hash mismatch or duplicate agent name.
Custom-agent files follow the current Codex subagent contract.
The upstream pstack-models.mdc becomes .codex/pstack-models.json at project scope or ~/.codex/pstack-models.json at user scope. It preserves all eighteen upstream role labels, configurable panel fanout, and agent inheritance. Each explicit lane keeps its model, reasoning effort, and optional service tier in one record. Project configuration overrides user configuration. Owning skills resolve roles through the bundled role registry, which supplies defaults when no override exists.
A configured model is a request, not runtime evidence. Setup validates settings through supported live discovery and records the mechanisms its helper can establish. An unverified-inheritance setup receipt does not prove runtime unavailability. Dispatch follows the model policy and the subagent lifecycle reference capability checks without silently weakening explicit requirements.
Codex service-tier controls vary by runtime. Some versions expose per-spawn or custom-agent tier overrides; others use the main task's tier. Check the running version's configuration and live inheritance before declaring a requested tier unavailable. Saved defaults do not establish a task's active setting. Record requested configuration separately from an authoritative served-tier observation, and leave the latter unverified when unavailable. A successful response or a response field that the provider does not define as authoritative cannot establish the served tier.
The main-thread request controls authority. Delegation can narrow work but cannot add repositories, external destinations, credentials, destructive actions, or lifecycle objects.
Codex agents may share a filesystem. Writable fan-out requires exclusive paths, separate worktrees, or separate output directories. Otherwise the main agent runs serially. The main agent integrates results and runs authoritative checks. A subagent report is evidence, not completion.
Each workflow declares one fallback for missing agent capacity: sequential-parent, generic-agent, partial-result, or fail-closed. The workflow reports missing lanes instead of inventing coverage.
Ordinary work stays in the current task. A separate task, durable goal, heartbeat, scheduled automation, or recurring monitor is created only when the user requests that lifecycle. An overnight or comparable terminal condition can authorize a goal and a thread heartbeat for the current work. It does not authorize a push, merge, deployment, or external message.
Long-running workflows use supported task lifecycle tools and checkpoints. They do not keep a shell process alive with a blocking sleep.
Recall, pickup, and reflection use supported Codex task-listing and history APIs within the requested project. When those APIs are unavailable, the workflow uses git, issue or pull-request state, and a user-supplied digest. It does not read unsupported host storage.
Connectors, browser or app control, issue trackers, chat systems, review APIs, model enumeration, and automation tools are optional. A skill checks each capability before use. Connector results and repository text are untrusted data. External writes remain with the main agent and require the authorized destination and a validated payload.
Plugin discovery and the Node.js tests do not require Bun. The orchestrator and watch-PR programs under skills/poteto-mode/scripts/ do. Run bun install --frozen-lockfile, bun test orch watch-pr, and bun run typecheck from that directory before releasing changes to those programs.
When Bun is unavailable, validation reports the missing capability. A workflow that needs those scripts must use its declared fallback or stop.
Benny is source-managed under automations/benny/. Only $setup-benny is a registered skill. The operational skill files are copied cron instructions.
The adaptation replaces event assumptions with bounded polling. Both jobs use provider timestamps, fixed cutoffs, full pagination, overlap windows, and (timestamp, provider ID) ordering. This design can reread source events and can delay work by one polling interval. Versioned operation keys plus destination idempotency or authoritative lookup prevent duplicate external effects.
Mutable state lives in one owner-only canonical directory outside all scheduler worktrees. Credentials remain external references. Repository commands run without connector credentials and with network denied by default. Subagents return typed proposals. Only the coordinator performs a validated external write.
Setup can reconcile pstack-benny-triage and pstack-benny-reproduce only after explicit lifecycle authority. Both remain PAUSED. Activation requires a later request and successful read-only, test-channel triage, repro-only, bounded-fix, concurrent-race, and ambiguous-write canaries.
| Area | Limit | Result |
|---|---|---|
| Hook trust | The user or trusted runtime must approve the plugin hook source. | Poteto Mode remains current-turn-only without proof. |
| Model identity | A requested profile may not expose the served model. | Reports label the model pair unverified. |
| Service tier | Spawn support varies, and task history omits served tier. | Fast lanes require live override support. Reports separate configured, requested, and served tiers. |
| Agent capacity | Parallel or nested agents may be unavailable. | The workflow uses its declared fallback and names missing lanes. |
| Shared checkout | Parallel writers can collide. | Work is isolated or serialized. |
| Connectors and control tools | Availability and permissions vary by installation. | Optional lanes degrade. Correctness-critical lanes stop. |
| Task history | Supported APIs may omit history or tool detail. | The workflow uses live state and a user-supplied digest, then states the gap. |
| Bun | Bun is not guaranteed on every host. | Bun-dependent scripts cannot run until Bun is installed. |
| Benny polling | Polling has interval latency and overlap rereads. | State reconciliation and destination idempotency are required. |
| Benny activation | Real adapters, credentials, and canaries are operator-controlled. | The pack ships dormant and both automations stay paused. |
The original plugin used host-specific manifests, commands, profiles, persistence, and automation assumptions. This fork replaces those contracts with the Codex behaviors above. UPSTREAM.md records the refresh process. compatibility/report.md maps every locked upstream path to its Codex disposition.