| name | popcorn-xp |
| description | Use when the user asks for a multi-agent XP-style session on Codex — "pair program", "xp session", "popcorn", "popcorn this task", "team of agents", or subagent pair work with LOG.md and ADVICE.md. Subagent/file-bus mode only (no Claude Agent Teams). Lead orchestrates; driver, navigator, and advisor use the vendored protocol skills. |
Popcorn XP (Codex lead)
You are the lead for a Popcorn XP session on OpenAI Codex. There is no native team transport like Claude Agent Teams; coordination is files + shared/runtime/bin/session (task bus, chat, advice, closeout).
Your job
- Create the session, keep pairing honest, spawn driver, navigator, and advisor subagents, and run close-check / close — not to do the implementation yourself unless the user asks.
- Default subagent mode:
printf 'subagent\n' > .popcorn-xp/{team}/.runtime-mode or omit .runtime-mode if your session helper defaults to subagent.
Project root, hooks, and transport
Codex passes cwd in hook stdin; it may be a subdirectory of the repository. Popcorn hooks and shared/runtime/bin/session resolve the project root with git -C <cwd> rev-parse --show-toplevel when CLAUDE_PROJECT_DIR is unset, then fall back to cwd. Keep .popcorn-xp/ at the git root (normal layout).
platforms/codex/subagent/manifests/hooks.json uses $(git rev-parse --show-toplevel)/platforms/codex/subagent/hooks/... so hook paths resolve from any checkout root; inside the script, cwd still drives where the session thinks the project lives until the git step above corrects it.
On Codex, use subagent mode only: shared/runtime/bin/session task bus, tasks/T{n}/, ADVICE.md. There is no Codex-native Agent Teams SendMessage transport.
Stop (not Claude’s SubagentStop) runs the OBJECTION gate via platforms/codex/subagent/hooks/codex-stop-advice.sh, which shells into the shared check-advice-on-complete.sh when configured.
Long-form Claude vs Codex design notes: docs/architecture/dual-mode-codex-companion.md (full repo).
Teammate skills
| Need | Skill |
|---|
| Core rules + subagent transport | popcorn-xp-protocol |
Wire via [[skills.config]] in agents/*.toml (typically under .agents/skills/... after npx skills add). This is the same protocol used by Claude subagent mode — symlinked from shared/skills/popcorn-xp-protocol/.
Before you vendor
- Plan to vendor
shared/runtime/bin/session (and shared/runtime/lib/) plus shared/hooks/scripts/advice/check-advice-on-complete.sh if you use the Codex Stop hook that shells into it.
- Add
.codex/ hooks and agents: run install/codex/generate.sh from a popcorn-xp checkout whose git root is that tree, or copy manifests/* and agents/*.toml from platforms/codex/subagent/ into your project’s .codex/.
- Ensure teammate
.toml files load popcorn-xp-protocol (see Setup in platforms/codex/subagent/README.md).
1. Session setup
Choose the teammate model. Ask the user which model to use for teammates:
What model should I use for the teammates? Options:
- gpt-5.4-mini xhigh — fast and cheap, good default for most tasks (default)
- gpt-5.4 low — full model, minimal reasoning
- gpt-5.4 medium — full model, moderate reasoning
- gpt-5.4 high — full model, maximum reasoning
(Default: gpt-5.4-mini xhigh)
Store their choice as {model} and {reasoning_effort} and pass both to every subagent spawn call. If the user doesn't have a preference, default to model="gpt-5.4-mini" with reasoning_effort="xhigh".
Set up the session:
- Pick a short team name (e.g.
fix-auth).
- Create
.popcorn-xp/{team}/, LOG.md, ADVICE.md, and a session wrapper that **exec**s your vendored shared/runtime/bin/session.
echo {team} > .popcorn-xp/.active-teamprintf 'subagent\n' > .popcorn-xp/{team}/.runtime-mode (or omit .runtime-mode if shared/runtime/bin/session defaults to subagent).- Spawn three teammates (driver, navigator, advisor) with
skills/... wired via [[skills.config]] in agents/*.toml, using the chosen {model} and {reasoning_effort}.
2. Tasks and pairing
- Each logical slice is a pair: drive + navigate task (navigator verifies after driver completes).
session task-init {n} before work on task n.- Use
session task-start {n} {driver} "next action" -- <owned files...> to kick off the driver atomically. It records the task header if needed, claims the drive seat, writes driver state, and records the write set before edits begin.
session task {n} remains available for a standalone LOG.md placeholder; real driver/navigator lines sync from task-claim / task-release.- Claims:
session task-claim, task-release, task-complete, task-abandon as in the popcorn-xp-protocol skill.
- Typed advice only in
ADVICE.md (session advice / session resolve). OBJECTION blocks completion until resolved.
3. Chat and cursors (subagent)
- Tactical:
session chat / session chat-read on tasks/T{n}/back-forth.md.
- Navigators in
waiting_on_driver: keep cursor-ack current.
- Advisors:
session review to advance review cursors when required.
4. Health and closeout
- Run
session health (or --strict) before risky handoffs. In strict mode, missing driver state or an empty driver write set is a failure.
- For UI work, capture browser evidence at the first meaningful visual checkpoint, not only at closeout. End-of-session Playwright capture is a confirmation step, not the primary verification path.
session retro-request → per-agent .retro-*.md or handoff-*.md as required.session close-check → append RETRO.md (≥5 real lines) → confirm RETRO.md exists before the final user summary → session close (or close --force only if you accept skipping gates). Successful close clears .popcorn-xp/.active-team (when it still names this team) and truncates context-store.log; run echo {team} > .popcorn-xp/.active-team again before the next slice. In each new RETRO.md entry, set Lead host: codex and Task transport: subagent (or team if you opted in) so future readers know which playbook and hooks applied — same fields as platforms/claude/popcorn-xp/skills/popcorn-xp/SKILL.md retro template.- Recovery: After two failures on session mechanics for the same drive seat (claims, rotation, close-check), switch to a bounded implementation worker or a fresh team instead of retrying the same seat.
5. Claude plugin parity
The full Claude lead playbooks are platforms/claude/popcorn-xp/skills/popcorn-xp/SKILL.md (file-bus) and platforms/claude/popcorn-xp-team/skills/popcorn-xp-team/SKILL.md (Agent Teams) — not required on disk for this Codex-only bundle.
Teammates
Spawn popcorn_xp_driver, popcorn_xp_navigator, popcorn_xp_advisor (or equivalent names) from .codex/agents/, with the model defaults in §1 above.
Do not activate
For ordinary single-agent coding without an explicit XP / pair / popcorn request, do not treat this skill as mandatory.
