# Codex Plans

> Generates rigorous, peer-level implementation plans and technical blueprints before writing code. Applies the 7-rung Senior Decision Ladder to prevent over-engineering, audits dependencies and edge cases, and creates timestamped implementation plans inside codex-drive/plans/.

- Skill: `wwwroot/codex-plans` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wwwroot/codex-plans`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wwwroot/codex-plans/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wwwroot (https://skillmd.com/u/wwwroot)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wwwroot/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:

```markdown
# [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.