ai-coding-skills/docs/CREATE-PLAN.md

CREATE-PLAN

Purpose

Create structured implementation plans with milestone and story tracking.

Requirements

• Superpowers skills installed from: https://github.com/obra/superpowers
• Required dependencies:
  • brainstorming
  • writing-plans
• For Codex, Superpowers runner must exist at:
  • ~/.codex/superpowers/.codex/superpowers-codex

If dependencies are missing, stop and return:

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

Install

Codex

mkdir -p ~/.codex/skills/create-plan
cp -R skills/create-plan/codex/* ~/.codex/skills/create-plan/

Claude Code

mkdir -p ~/.claude/skills/create-plan
cp -R skills/create-plan/claude-code/* ~/.claude/skills/create-plan/

OpenCode

mkdir -p ~/.opencode/skills/create-plan
cp -R skills/create-plan/opencode/* ~/.opencode/skills/create-plan/

Verify Installation

test -f ~/.codex/skills/create-plan/SKILL.md || true
test -f ~/.claude/skills/create-plan/SKILL.md || true
test -f ~/.opencode/skills/create-plan/SKILL.md || true

Verify Superpowers dependencies exist in your agent skills root:

• .../skills/brainstorming/SKILL.md
• .../skills/writing-plans/SKILL.md

For Codex, verify runner:

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

Codex must invoke these explicit commands during planning:

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

Key Behavior

• Creates plans under ai_plan/YYYY-MM-DD-<short-title>/.
• Ensures /ai_plan/ is in .gitignore.
• Commits .gitignore update locally when added.
• Produces:
  • original-plan.md
  • final-transcript.md
  • milestone-plan.md
  • story-tracker.md
  • continuation-runbook.md

Variant Hardening Notes

Claude Code

• Must invoke explicit required sub-skills:
  • superpowers:brainstorming
  • superpowers:writing-plans
• Must enforce plan-mode file-write guard:
  • if in plan mode, instruct user to exit plan mode before generating files
• Must copy original-plan.md from ~/.claude/plans/ when available.

Codex

• Must run explicit commands:
  • ~/.codex/superpowers/.codex/superpowers-codex bootstrap
  • ~/.codex/superpowers/.codex/superpowers-codex use-skill brainstorming
  • ~/.codex/superpowers/.codex/superpowers-codex use-skill writing-plans

OpenCode

• Must use OpenCode native skill tool (not Claude/Codex invocation syntax).
• Must verify Superpowers skill discovery under:
  • ~/.config/opencode/skills/superpowers
• Must explicitly load:
  • superpowers/brainstorming
  • superpowers/writing-plans

Execution Workflow Rules

• Read runbook first.
• Complete one milestone at a time.
• Lint/typecheck/test (changed files first).
• Commit (do not push), ask for feedback, apply feedback, commit again.
• Move to next milestone only after approval.
• Ask permission before final push.