Codex Plans

Codex Plans — Technical Planning & Roadmapping Skill

The planning engine of AI Codex. Translates requirements and ideas into step-by-step, risk-mitigated technical implementation plans with anti-overengineering discipline.

Overview

codex-plans conducts deep technical analysis before code is modified or written. It applies the Senior Decision Ladder (anti-overengineering & YAGNI), audits codebase impact, evaluates failure modes and performance constraints, and outputs a comprehensive implementation plan into codex-drive/plans/.

When to Trigger

• User runs /codex-plans (e.g., /codex-plans add authentication flow, /codex-plans migrate database schema, /codex-plans optimize memory allocations)
• Following /codex-start when a feature or task requires formal execution steps
• Any multi-file change, major refactor, or complex architectural evolution

The Senior Decision Ladder (Anti-Overengineering Protocol)

Before proposing any new file, abstraction, or dependency, codex-plans must evaluate the solution against the 7-Rung Decision Ladder and stop at the lowest rung that solves the problem:

  ▲  RUNG 7: Write minimum necessary custom code & abstractions
  │  RUNG 6: Can this be written in ≤ 5 lines of simple, clear code?
  │  RUNG 5: Does an existing project dependency already solve it?
  │  RUNG 4: Is there a native platform, runtime, or browser API available?
  │  RUNG 3: Does the language standard library already provide this?
  │  RUNG 2: Is a working pattern or utility already in the codebase? (Reuse)
  │  RUNG 1: Does this need to exist at all? (YAGNI — You Ain't Gonna Need It)

Rule: If a feature can be accomplished with standard library functions or native APIs without adding new packages or layers of indirection, the plan MUST reject the extra abstraction.

Execution Workflow

 ┌────────────────────────────────────────────────────────┐
 │ 1. CLIMB THE SENIOR DECISION LADDER                    │
 │    Apply YAGNI, standard library, and reuse checks.    │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 2. DECOMPOSE REQUIREMENTS & EDGE CASES                 │
 │    Extract core invariants, failure modes, constraints.│
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 3. AUDIT WORKSPACE & DEPENDENCY IMPACT                 │
 │    Trace affected files, API contracts, and schemas.   │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 4. CONSULT CODEX DOMAIN EDITIONS                      │
 │    Incorporate standards from skills/codex/<edition>/. │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 5. GENERATE TIMESTAMPED PLAN IN CODEX-DRIVE            │
 │    Write codex-drive/plans/YYYY-MM-DD-<slug>.plan.md   │
 └──────────────────────────┬─────────────────────────────┘
                            │
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │ 6. USER REVIEW & APPROVAL GATE                         │
 │    Present plan summary, highlight risks, request go.  │
 └────────────────────────────────────────────────────────┘

Spec-Driven Lifecycle & Archival

Plans follow a structured lifecycle:

1. PROPOSAL: Drafted in codex-drive/specs/YYYY-MM-DD-<slug>.spec.md.
2. ACTIVE PLAN: Formulated in codex-drive/plans/YYYY-MM-DD-<slug>.plan.md.
3. EXECUTION: Executed task-by-task with continuous verification.
4. COMPLETION & ARCHIVAL: Upon completion via /codex-goal, learnings are merged into codex-drive/brains/knowledge-base.brain.md and historical plans are archived to codex-drive/plans/archive/.

Plan File Specification (codex-drive/plans/)

All plans generated by codex-plans MUST be written as Markdown (.md) files with exact date-time metadata.

Filename Format:

codex-drive/plans/YYYY-MM-DD-<slug>.plan.md

Standard Implementation Plan Template:

# [Feature / Task Name] Implementation Plan

> **Created At**: YYYY-MM-DD HH:MM:SS (Local Time)
> **Active Codex Edition**: [`skills/codex/<edition>/`](file:///...)
> **Status**: PROPOSED | APPROVED | IN_PROGRESS | COMPLETED
> **Target Branch / Workspace**: `...`

---

## 1. Executive Summary & Objective
[Clear, concise description of the task, why it is needed, and what it achieves]

## 2. Decision Ladder Audit (Anti-Overengineering Check)
- **YAGNI Verified**: Confirmed feature is necessary and not speculative.
- **Stdlib / Native Reuse**: Leveraging native platform APIs instead of third-party libraries.
- **Estimated Code Delta**: +XX lines / -YY lines (Net minimal footprint).

## 3. Critical Decisions & User Review Required
> [!IMPORTANT]
> List any breaking changes, architectural trade-offs, or significant decisions that require confirmation.

## 4. Scope & Edge Cases
- **Primary Happy Path**:
  - [ ] Flow 1
- **Edge Cases & Failure Modes**:
  - [ ] Network timeout / offline behavior
  - [ ] Concurrent mutation / race conditions
  - [ ] Validation errors & boundary limits

## 5. Proposed Codebase Changes

### [Component / Layer Name]
Summary of modifications in this component.

- `[NEW]` [`path/to/new_file.ext`](file:///...) — Brief rationale
- `[MODIFY]` [`path/to/existing_file.ext`](file:///...) — Specific lines/functions to edit
- `[DELETE]` [`path/to/old_file.ext`](file:///...) — Deprecated file

---

## 6. Phased Execution Roadmap

### Phase 1: Foundation & Contracts
1. Step 1 (e.g., Define types, interfaces, and database migrations)
2. Step 2 (e.g., Implement core domain logic and invariants)

### Phase 2: Integration & Infrastructure
3. Step 3 (e.g., Wire endpoints, repositories, and UI views)
4. Step 4 (e.g., Add structured logging and error handling)

### Phase 3: Verification & Polish
5. Step 5 (e.g., Write automated unit/integration tests)
6. Step 6 (e.g., Profile performance and memory allocations)

---

## 7. Verification & Testing Strategy
- **Automated Tests**:
  - Command: `npm test` / `cargo test` / `pytest` / `dotnet test`
  - Specific test cases to write or run
- **Manual Verification**:
  - Step-by-step instructions to manually verify behavior

## 8. Rollback & Contingency Plan
Steps to safely revert changes if unexpected issues occur in production.

Response Protocol

When codex-plans completes:

1. Provide a direct link to [View Implementation Plan](file:///.../codex-drive/plans/YYYY-MM-DD-<slug>.plan.md).
2. Highlight the Decision Ladder Findings (how over-engineering was avoided).
3. Highlight any Critical Open Questions or Breaking Changes that need immediate user feedback.
4. Await user approval before executing the changes.