/codex-plan

description: Create a detailed implementation plan using Codex 5.2 with high reasoning
argument-hint: "<what you want to plan>"
allowed-tools: Read, Write, Bash, AskUser

Codex Plan Command

You are being asked to create a detailed implementation plan using a Codex subagent. Your job is to: 1. Understand the user's planning request 2. Ask clarifying questions using AskUser to improve plan quality 3. Craft an excellent, detailed prompt for Codex 4. Execute Codex to generate and save the plan

**Always uses:** `gpt-5.2-codex` with `high` reasoning

User Request

$ARGUMENTS

Step 1: Analyze the Request

Look at what the user wants to plan. Identify:

• What is the core goal?
• What technology/domain is involved?
• What aspects are ambiguous or underspecified?
• What decisions would significantly impact the plan?

Step 2: Ask Clarifying Questions

**Use AskUser to ask 3-6 targeted clarifying questions** before generating the plan.

Good clarifying questions:

• Narrow down scope and requirements
• Clarify technology choices
• Understand constraints (time, budget, team size)
• Identify must-haves vs nice-to-haves
• Uncover integration requirements
• Determine security/compliance needs

Example Question Patterns

**For "implement auth":**

• What authentication methods do you need? (email/password, OAuth providers like Google/GitHub, SSO, magic links)
• Do you need role-based access control (RBAC) or just authenticated/unauthenticated?
• What's your backend stack? (Node/Express, Python/Django, etc.)
• Where will you store user credentials/sessions? (Database, Redis, JWT stateless)
• Do you need features like: password reset, email verification, 2FA?
• Any compliance requirements? (SOC2, GDPR, HIPAA)

**For "build an API":**

• What resources/entities does this API need to manage?
• REST or GraphQL?
• What authentication will the API use?
• Expected scale/traffic?
• Do you need rate limiting, caching, versioning?

**For "migrate to microservices":**

• Which parts of the monolith are you migrating first?
• What's your deployment target? (K8s, ECS, etc.)
• How will services communicate? (REST, gRPC, message queues)
• What's your timeline and team capacity?

**For "add testing":**

• What testing levels do you need? (unit, integration, e2e)
• What's your current test coverage?
• What frameworks do you prefer or already use?
• What's the most critical functionality to test first?

Step 3: Gather Context

After getting answers, also gather relevant context:

• Read key files in the codebase if applicable
• Check existing architecture/patterns
• Note any existing plans or documentation

Step 4: Craft the Codex Prompt

Create a detailed prompt that includes: 1. **Clear objective** - What plan needs to be created 2. **All requirements** - Everything learned from clarifying questions 3. **Constraints** - Technology choices, timeline, team size 4. **Context** - Relevant codebase info, existing patterns 5. **File references** - List of important files/docs the Codex should read for context 6. **Plan structure** - What sections the plan should include 7. **Output instructions** - Write to `codex-plan.md` in current directory

Including File References (IMPORTANT)

Always include a section in the prompt telling Codex which files to read first for context:

## Files to Read for Context

Before creating the plan, read these files to understand the current codebase:

**Architecture & Config:**
- `README.md` - Project overview
- `package.json` / `pyproject.toml` - Dependencies and scripts
- `.env.example` - Environment variables needed

**Existing Code Patterns:**
- `src/lib/db.ts` - How database connections are handled
- `src/middleware/auth.ts` - Existing auth patterns (if any)
- `src/types/index.ts` - Type definitions

**Documentation:**
- `docs/architecture.md` - System architecture
- `docs/api.md` - API documentation

Read these files FIRST to understand existing patterns before creating the plan.

Adapt this list based on what you discovered in Step 3 (Gather Context). Include:

• Config files relevant to the task
• Existing code that will be modified or extended
• Documentation about architecture/patterns
• Type definitions or schemas
• Test files showing testing patterns used

**Critical instruction to include:** Tell Codex to NOT ask any further clarifying questions - it has all the information it needs and should just write the plan and save the file.

Step 5: Save Prompt for Manual Execution

Save the crafted prompt to `prompt_to_codex.md` for manual execution.

The user will execute Codex manually using:

# --full-auto: Executa automaticamente sem interação humana
# --skip-git-repo-check: Pula verificação se está em um repositório git
# -c model=gpt-5.2-codex: Usa o modelo GPT-5.2 Codex (mais avançado)
# -c model_reasoning_effort=high: Ativa raciocínio de alto nível (deep thinking)
# --output-last-message: Salva a última mensagem do Codex em arquivo
codex exec --full-auto --skip-git-repo-check \
  -c model=gpt-5.2-codex \
  -c model_reasoning_effort=high \
  --output-last-message /tmp/codex-plan-result.txt \
  "$(cat prompt_to_codex.md)"

Or read the prompt and execute it:

cat prompt_to_codex.md  # Review the prompt first

Example Full Flow

**User:** `/codex-plan help me implement auth into my webapp`

**You ask (using AskUser):**

I'd like to create a detailed auth implementation plan for you. A few questions first:

1. What authentication methods do you need?
   - Email/password
   - OAuth (Google, GitHub, etc.)
   - Magic links
   - SSO/SAML

2. Do you need role-based access control (admin, user, etc.) or just authenticated vs not?

3. What's your backend stack? (e.g., Node/Express, Python/FastAPI, Next.js API routes)

4. Where will you store sessions? (Database, Redis, JWT stateless)

5. Do you need any of these features?
   - Password reset
   - Email verification
   - Two-factor authentication (2FA)
   - Remember me /