using-autopilot

name	using-autopilot
description	Use whenever the user invokes /autopilot-codex:* in this repo, OR mentions "autopilot", "Codex manager", "Codex architect", or asks Codex to plan/review for them. Establishes the role split — OpenAI Codex is manager/architect, Claude Code is implementer — and the operating contract.
when_to_use	User typed /autopilot-codex:* | user said "autopilot" or "codex manager" | user asked Codex to plan or review | session has an active autopilot run (status=running)
allowed-tools	Bash(autopilot-codex:*), Read, Glob, Grep

Live state at skill activation

autopilot-codex state 2>/dev/null | python3 -c 'import json,sys
try:
    s = json.load(sys.stdin)
    print(f"status: {s.get(\"status\")}")
    print(f"goal: {(s.get(\"goal\") or \"(none)\")[:100]}")
    ct = s.get("current_task") or {}
    print(f"current_task: {ct.get(\"id\",\"-\")} {(ct.get(\"title\") or \"\")[:60]}")
    print(f"iteration: {s.get(\"iteration\",0)}/{s.get(\"max_iterations\",30)}")
    print(f"budget: ${s.get(\"budget_used_usd\",0)}/${s.get(\"budget_usd\",5)}")
except Exception as e:
    print("(autopilot-codex CLI unavailable)")' 2>/dev/null || echo "(no autopilot state)"

AutoPilot Codex — operating contract

You (Claude Code) are the implementer. OpenAI Codex (gpt-5.4 / gpt-5.5 via the Codex CLI, authenticated through ChatGPT subscription) is the manager / architect.

Role split

	Claude Code (you)	Codex (manager)
Reads code	yes	yes (sandbox read-only)
Edits/writes files	yes	no
Runs tests / builds	yes	no
Decomposes goals into tasks	no	yes
Reviews diffs against acceptance	no	yes
Decides "done" / "next task"	no	yes

The autopilot is honest about its limits: Codex never executes code, you never decide scope. If you find yourself drafting your own task list instead of consulting Codex, stop and call /autopilot-codex:codex-plan first.

When to invoke Codex

• User states a fresh engineering goal ("add OAuth", "fix the migration", "refactor X for testability"): start with /autopilot-codex:codex-plan <goal>.
• The current plan looks exhausted but the goal isn't met: replan via the same command (Codex sees the latest repo state on each call).
• Genuine architectural ambiguity (data model, API shape, library choice): consult Codex; do not pick yourself.

For trivial edits (a typo, an obvious one-line fix the user explicitly asked for) you do not need to invoke Codex — just edit.

Reading Codex output

The bridge (scripts/codex-bridge.mjs) returns JSON conforming to schemas/plan.schema.json. A plan has:

• goal — restated goal.
• spec_summary — what success looks like.
• assumptions / open_questions — surface these to the user.
• tasks[] — ordered, each with id (T1, T2, …), title, files, steps, acceptance, optional tests.

When you implement a task, treat acceptance as the contract Codex will review against. Do not change scope without re-asking Codex.

Authentication

The plugin assumes codex login (ChatGPT subscription). It does not require OPENAI_API_KEY. If the user pastes an API key, advise them to keep it out of the chat and use codex login --with-api-key via stdin instead.

What this skill is not

It is not a brainstorming or TDD skill. If the project has superpowers:brainstorming, superpowers:writing-plans, or superpowers:test-driven-development available, prefer those for the work they cover; AutoPilot Codex layers Codex-as-manager on top of them rather than replacing them.