ai-coding-skills/skills/create-plan/codex/SKILL.md

name, description

name	description
create-plan	Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context. Trigger for "create a plan", "make a plan", "plan this", "start planning", and similar requests.

Create Plan (Codex)

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

Prerequisite Check (MANDATORY)

This Codex variant depends on Superpowers and must use explicit Superpowers CLI commands.

Required:

• Superpowers repo: https://github.com/obra/superpowers
• Codex Superpowers runner: ~/.codex/superpowers/.codex/superpowers-codex
• brainstorming skill
• writing-plans skill

Verify command availability before proceeding:

test -x ~/.codex/superpowers/.codex/superpowers-codex
~/.codex/superpowers/.codex/superpowers-codex --help

If any dependency is missing, stop immediately and return:

"Missing dependency: Superpowers Codex skills are required (brainstorming, writing-plans). Install from https://github.com/obra/superpowers, then retry."

Process

Phase 1: Bootstrap Superpowers (REQUIRED)

Run this exact command:

~/.codex/superpowers/.codex/superpowers-codex bootstrap

Phase 2: Analyze

• Explore the codebase and existing patterns.

Phase 3: Gather Requirements

• Ask questions one at a time until user says ready.
• Confirm scope, constraints, success criteria, dependencies.

Phase 4: Design (REQUIRED SUB-SKILL)

Run this exact command:

~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming

Then propose 2-3 approaches and recommend one.

Phase 5: Plan (REQUIRED SUB-SKILL)

Run this exact command:

~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans

Then break work into milestones and bite-sized stories.

Phase 6: 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 7: 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 8: 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.

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.

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