---
name: create-plan
description: Use when a user asks to create or maintain a structured implementation plan in Codex, including milestones, bite-sized stories, and resumable local planning artifacts under ai_plan.
---

# Create Plan (Codex Native Superpowers)

Create and maintain a local plan workspace under `ai_plan/` at project root.

## Overview

This skill wraps the current Superpowers flow for Codex:
1. Design first with `superpowers:brainstorming`
2. Then build an implementation plan with `superpowers:writing-plans`
3. Persist a local execution package in `ai_plan/YYYY-MM-DD-<short-title>/`

**Core principle:** Codex uses native skill discovery from `~/.agents/skills/`. Do not use deprecated `superpowers-codex bootstrap` or `use-skill` CLI commands.

## Prerequisite Check (MANDATORY)

Required:
- Superpowers skills symlink: `~/.agents/skills/superpowers -> ~/.codex/superpowers/skills`
- `superpowers:brainstorming`
- `superpowers:writing-plans`

Verify before proceeding:

```bash
test -L ~/.agents/skills/superpowers
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md
```

If any dependency is missing, stop and return:

`Missing dependency: native Superpowers skills are required (superpowers:brainstorming, superpowers:writing-plans). Ensure ~/.agents/skills/superpowers is configured, then retry.`

## Required Skill Invocation Rules

- Invoke relevant skills through native discovery (no CLI wrapper).
- Announce skill usage explicitly:
  - `I've read the [Skill Name] skill and I'm using it to [purpose].`
- For skills with checklists, track checklist items with `update_plan` todos.
- Tool mapping for Codex:
  - `TodoWrite` -> `update_plan`
  - `Task` subagents -> unavailable in Codex; do the work directly and state the limitation
  - `Skill` -> use native skill discovery from `~/.agents/skills/`

## Process

### Phase 1: Analyze
- Explore the codebase and existing patterns.

### Phase 2: Gather Requirements
- Ask questions one at a time until user says ready.
- Confirm scope, constraints, success criteria, dependencies.

### Phase 3: Design (REQUIRED SUB-SKILL)

Invoke `superpowers:brainstorming`, then propose 2-3 approaches and recommend one.

### Phase 4: Plan (REQUIRED SUB-SKILL)

Invoke `superpowers:writing-plans`, then break work into milestones and bite-sized stories.

### Phase 5: Initialize Local Plan Workspace (MANDATORY)

At project root:
1. Ensure `ai_plan/` exists. Create it if missing.
2. Ensure `.gitignore` contains `/ai_plan/`.
3. If `.gitignore` was changed, commit that change immediately (local commit only).

Recommended commit message:
- `chore(gitignore): ignore ai_plan local planning artifacts`

### Phase 6: Generate Plan Files (MANDATORY)

Create `ai_plan/YYYY-MM-DD-<short-title>/` with all files below:
1. `original-plan.md` - copy of original planner-generated plan.
2. `final-transcript.md` - copy of final planning transcript used to reach approved plan.
3. `milestone-plan.md` - full implementation spec (from template).
4. `story-tracker.md` - story/milestone status tracker (from template).
5. `continuation-runbook.md` - execution instructions and context (from template).

Use templates from this skill's `templates/` folder.

### Phase 7: Handoff

Always instruct the executing agent:
> Read `ai_plan/YYYY-MM-DD-<short-title>/continuation-runbook.md` first, then execute from that folder.

Do not rely on planner-private files during implementation.

## Quick Reference

| Phase | Action | Required Output |
|---|---|---|
| 1 | Analyze codebase/context | Constraints and known patterns |
| 2 | Gather requirements (one question at a time) | Confirmed scope and success criteria |
| 3 | Invoke `superpowers:brainstorming` | Chosen design approach |
| 4 | Invoke `superpowers:writing-plans` | Milestones and bite-sized stories |
| 5 | Initialize `ai_plan/` + `.gitignore` | Local planning workspace ready |
| 6 | Build plan package from templates | Full plan folder with required files |
| 7 | Handoff with runbook-first instruction | Resumable execution context |

## Execution Rules to Include in Plan (MANDATORY)

- Run lint/typecheck/tests after each milestone.
- Prefer linting changed files only for speed.
- Commit locally after each completed milestone (**do not push**).
- Stop and ask user for feedback.
- Apply feedback, rerun checks, and commit again.
- Move to next milestone only after user approval.
- After all milestones are completed and approved, ask permission to push.
- Only after approved push: mark plan as completed.

## Gitignore Note

`ai_plan/` is intentionally local and must stay gitignored. Do not treat inability to commit plan-file updates in `ai_plan/` as a problem.

## Common Mistakes

- Using deprecated commands like `superpowers-codex bootstrap` or `superpowers-codex use-skill`.
- Jumping to implementation planning without running `superpowers:brainstorming` first.
- Asking multiple requirement questions in one message.
- Forgetting to create/update `.gitignore` for `/ai_plan/`.
- Omitting one or more required files in the plan package.
- Handoff without explicit "read runbook first" direction.

## Rationalizations and Counters

| Rationalization | Counter |
|---|---|
| "Bootstrap CLI is faster" | Deprecated for Codex; native discovery is the supported path. |
| "I can skip brainstorming for small tasks" | Creative/planning work still requires design validation first. |
| "I don't need `update_plan` for checklist skills" | Checklist tracking is mandatory for execution reliability. |
| "I can keep plan files outside `ai_plan/`" | This skill standardizes local resumable planning under `ai_plan/`. |

## Red Flags - Stop and Correct

- You are about to run any `superpowers-codex` command.
- You started writing milestones before design validation.
- You did not announce which skill you invoked and why.
- You are marking planning complete without all required files.
- Handoff does not explicitly point to `continuation-runbook.md`.

## Verification Checklist

- [ ] `ai_plan/` exists at project root
- [ ] `.gitignore` includes `/ai_plan/`
- [ ] `.gitignore` ignore-rule commit was created if needed
- [ ] Plan directory created under `ai_plan/YYYY-MM-DD-<short-title>/`
- [ ] `original-plan.md` present
- [ ] `final-transcript.md` present
- [ ] `milestone-plan.md` present
- [ ] `story-tracker.md` present
- [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder