Codex Plan Skill

You are being asked to create a detailed implementation plan using Codex. Your job is to:

1. Understand the user's planning request (shown below as ARGUMENTS:)
2. Ask clarifying questions using AskUserQuestion
3. Craft an excellent, detailed prompt for Codex
4. Execute Codex to generate and save the plan

Always uses: gpt-5.4 with xhigh reasoning Output: codex-plan.md in current directory

---

Step 1: Analyze the Request

The user's planning request appears at the end of this instruction as ARGUMENTS: <request>.

Identify:

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

Fast-path (Trivial Tasks)

If the task is extremely trivial — single file config change, typo fix, <2 files affected, no architectural decisions — skip Codex. Write codex-plan.md yourself directly with a simplified structure:

# Plan: [Task Name]
**Generated**: [Date]
**Estimated Complexity**: Low
## Overview
[1-2 sentences]
## Task
- **Location**: [file path]
- **Description**: [what to do]
- **Acceptance Criteria**: [testable criteria]

Even on fast-path, still ask at least 1 clarifying question (Step 2) before writing the plan. After writing, skip to Step 6 (Verify Output).

---

Step 2: Ask Clarifying Questions (REQUIRED)

Use AskUserQuestion tool to ask 1-5 targeted questions before generating the plan.

Evaluate task ambiguity first:

• Simple/clear tasks (well-defined scope, obvious approach) → ask 1-2 questions
• Complex/ambiguous tasks (multiple approaches, unclear requirements) → ask 3-5 questions
• Never 0 — always ask at least 1 question to confirm understanding

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? (email/password, OAuth, SSO, magic links)
• RBAC or just authenticated/unauthenticated?
• Backend stack? (Node/Express, Python/Django, etc.)
• Session storage? (Database, Redis, JWT stateless)
• Features needed? (password reset, email verification, 2FA)
• Compliance requirements? (SOC2, GDPR, HIPAA)

For "build an API":

• What resources/entities to manage?
• REST or GraphQL?
• Authentication method?
• Expected scale/traffic?
• Rate limiting, caching, versioning?

For "fix a bug":

• How to reproduce reliably? (steps, environment, frequency)
• Expected vs actual behavior?
• Related test coverage? (existing tests that should have caught this)
• Affected platforms/browsers/environments?

For "refactoring":

• Must external API/interface remain compatible?
• Existing test coverage to rely on?
• Performance constraints? (must not regress)
• Incremental or big-bang? (can we merge partial progress?)

For "infrastructure/DevOps":

• Target environment? (local, staging, production)
• Existing CI/CD pipeline?
• Secrets management approach?
• Rollback requirements? (blue-green, canary, instant)

---

Step 3: Locate Target Files

You are the Product Manager and Locator. Your job is to FIND the relevant files, NOT to plan the implementation.

After getting answers, discover:

• Entry points: main files, CLI entry, route handlers
• Files to modify: specific files the task will touch
• Key imports/dependencies: modules these files depend on
• Existing patterns: naming conventions, error handling style, architecture

Produce a ## Target Files list for the Codex prompt:

## Target Files to Read
- `src/auth/login.ts` — current login handler, will be modified
- `src/middleware/session.ts` — session middleware, imports from login
- `src/types/user.ts` — User type definition, dependency

Do NOT summarize file contents — just list paths with one-line purpose. Codex will read them in full via <context_loading>.

---

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. Target Files — The file paths list from Step 3
5. Plan structure — Read from references/plan-template.md and inject its full content
6. Output instructions — Write to codex-plan.md in current directory

CRITICAL: Tell Codex to NOT ask any clarifying questions — it has all the information it needs and should just write the plan and save the file.

Adaptive template: For minor/trivial tasks, tell Codex it MUST omit irrelevant sections (Phases, E2E Tests, Rollback) and may output a flat task list instead, to comply with <output_verbosity_spec>.

Example Codex Prompt

Create a detailed implementation plan for [TASK DESCRIPTION].

## Requirements
- [Requirement 1 from clarifying questions]
- [Requirement 2]
- [Requirement 3]
- NOT needed: [Things explicitly excluded]

## Target Files to Read
- `[path/to/file1]` — [one-line purpose]
- `[path/to/file2]` — [one-line purpose]
- `[path/to/file3]` — [one-line purpose]

## Plan Structure

Read and follow the exact template structure from `references/plan-template.md`.

Adapt the template to task complexity:
- For minor tasks, OMIT irrelevant sections (e.g., multiple Phases, E2E Tests, Rollback) and use a flat task list instead.
- For complex tasks, use the full phased structure with all sections.

## Behavioral Constraints

<output_verbosity_spec>
- Default: 3-6 sentences or <=5 bullets for typical answers.
- Simple yes/no questions: <=2 sentences.
- Complex multi-step or multi-file tasks:
  - 1 short overview paragraph
  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
- Avoid long narrative paragraphs; prefer compact bullets and short sections.
- Do not rephrase the user's request unless it changes semantics.
</output_verbosity_spec>

<design_and_scope_constraints>
- Implement EXACTLY and ONLY what the user requests.
- No extra features, no added components, no UX embellishments.
- Style aligned to the design system at hand.
- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
- If any instruction is ambiguous, choose the simplest valid interpretation.
</design_and_scope_constraints>

<context_loading>
- Start by reading ALL files listed in "Target Files to Read" — in full, not just the sections mentioned in the task.
- Then expand to key files they import from or that depend on them.
- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
- Do not ask clarifying questions about things that are answerable by reading the codebase.
</context_loading>

## Instructions
- Write the complete plan to a file called `codex-plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file

Begin immediately.

---

Step 5: Execute Codex (REQUIRED)

Run this exact command with your crafted prompt:

codex exec --full-auto --skip-git-repo-check \
  -c model=gpt-5.4 \
  -c model_reasoning_effort=xhigh \
  -c model_reasoning_summary=concise \
  --output-last-message /tmp/codex-plan-result.txt \
  "YOUR_CRAFTED_PROMPT_HERE"

Then show the results:

cat /tmp/codex-plan-result.txt

---

Step 6: Verify Output (REQUIRED)

After Codex finishes (or after writing the plan yourself on fast-path):

1. Read the generated codex-plan.md
2. Check structure: file exists, is valid Markdown, contains at minimum:
   • # Plan: heading
   • ## Overview section
   • At least one ### Task entry
3. If checks fail OR codex exec returned an error/timeout:
   • Adjust the prompt (simplify requirements, fix ambiguities)
   • Retry execution once
4. If retry also fails: show the error to the user and explain what went wrong
5. If checks pass: show the plan results to the user

---

Important Rules

1. ALWAYS ask at least 1 clarifying question — Do not skip Step 2 (1-5 questions based on complexity)
2. ALWAYS use gpt-5.4 with xhigh reasoning — No exceptions (unless fast-path)
3. ALWAYS tell Codex not to ask questions — It should just execute
4. ALWAYS use --full-auto flag
5. ALWAYS verify output in Step 6 — Check structure, retry once on failure
6. Output file: codex-plan.md in current working directory

---

Now Execute

The user's planning request is shown as ARGUMENTS: below. Analyze it and begin with Step 1.