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

name, description

name	description
create-plan	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:

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