wizard-mode

name	wizard-mode
description	Planning-first Codex operating mode for ambiguous, multi-step, risky, QA-heavy, or context-heavy work that benefits from Codex thread forks. Use when the user asks for wizard mode, codexwizards, planning before execution, goal-setting, intent inference, same-workspace thread review, callback thread forks, QA thread forks, adversarial review, or help figuring out what Codex should do next.

Wizard Mode

Overview

Use wizard mode to work deliberately without turning the thread into paperwork. Infer what the user means, name the context you are relying on, set a goal only when it helps, then choose whether to stay solo or bring in same-workspace forked Codex threads. Prefer thread forks when reusing the completed conversation context would make review, QA, or alternate thinking stronger.

Operating Loop

1. Start with a right-sized planning posture unless the request is direct or explicitly asks for immediate execution.
2. Infer intent when the user is vague; follow tightly when the user is explicit.
3. Choose the relevant context scope: last turn, recent turns, whole thread, repo state, or explicit pasted context.
4. Set or update a goal when the task is multi-step, uncertain, thread-fork-coordinated, or likely to span turns.
5. Decide whether to work solo or create same-directory callback thread forks for review, QA, simplification, or scoped fixing.
6. Execute the right-sized next move: small when the path is obvious, broader when the work needs design, context gathering, QA, or thread-fork review. Revise as new information arrives.

Thread Affordances

Use Codex app thread tools when they are available. Do not assume every session exposes every tool; fall back gracefully when a tool is missing.

• Use fork_thread for durable collaborator threads that reuse completed context from the requesting thread.
• Prefer same-directory thread forks by default so all collaborators stay in the same workspace.
• Use send_message_to_thread for thread-fork callbacks to the requesting thread.
• Rely on delegation metadata such as source_thread_id for callback identity; do not require forks to repeat their own thread id in the callback body.
• Use read_thread or list_threads as parent-pull fallback when a callback is missing or unclear.
• Use set_thread_title, set_thread_pinned, and set_thread_archived when available to keep active workflows legible and finished forks out of the way.

Same-Workspace Policy

Default to same-directory thread forks. Treat the requesting thread as the home base and forked Codex threads as temporary collaborators with the same completed conversation context.

Allow multiple writers in the same checkout when useful, but make every writer aware of shared state:

• Before writing, re-read the files you will touch and account for concurrent thread edits.
• Do not revert unfamiliar changes.
• Keep edits scoped to the assigned responsibility.
• Prefer disjoint write areas when assigning thread-fork roles.
• If overlap or conflict risk is high, send a callback asking for coordination before editing.
• Report changed files, checks run, and unresolved risks in the final callback.

Use read-only thread forks for planning, critique, test design, and review. Grant write permission explicitly for fixer or QA-fixer thread forks, and make the shared-checkout warning plain.

Callback Thread Forks

Use callback thread forks when independent durable thinking with reused context will improve the result: adversarial review, QA, simplification, risky implementation, unclear requirements, or multi-path investigation.

Common fork roles:

• Skeptic: challenge assumptions, find regressions, and identify hidden risks.
• QA: verify behavior like a user, using browser, computer, app, or test tools when available.
• Simplifier: look for unnecessary complexity and propose a cleaner route.
• Fixer: make scoped changes when the workflow grants write permission.

Give each forked Codex thread enough context to work and return cleanly:

• the return thread id as <return_thread_id>
• a natural-language role and task
• the same-workspace write policy
• permission boundaries
• an instruction to send one final prose callback to the return thread
• an instruction to archive itself after a successful callback when archiving is available

Prefer prose callbacks over rigid schemas. A good callback says what the forked thread did, what changed or was learned, what remains, and what the requesting thread should do next.

Example callback prompt:

When finished, send a concise prose callback to <return_thread_id>. Do not include your own thread id; Codex delegation metadata should carry source identity. After the callback succeeds, archive this thread fork if the archive tool is available. If callback or archive tools are unavailable, say so in your own final response.

Example callback:

I finished the QA pass. I found and fixed one broken empty-state path, ran the focused component test, and did not see other regressions. The only thing left is for the requesting thread to review the diff and decide whether to run the full suite. I am archiving this fork now.

Thread Lifecycle

Keep the requesting thread as the durable home of the workflow.

• Pin it while a substantial multi-thread-fork or multi-turn workflow is active when pinning is available.
• Track active thread-fork roles and callback status in compact prose, not a large plan file.
• Synthesize callbacks into the main decision or implementation path.
• Archive completed forks that did not self-archive.
• Leave only the requesting thread visible at completion unless the user intentionally preserves a thread fork.

Stay solo when the task is straightforward, the cost of thread forks outweighs the benefit, or the user asks for direct execution.