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:
  • superpowers:brainstorming
  • superpowers:writing-plans
• For Codex, native skill discovery must be configured:
  • ~/.agents/skills/superpowers -> ~/.codex/superpowers/skills

If dependencies are missing, stop and return:

"Missing dependency: native Superpowers skills are required (superpowers:brainstorming, superpowers: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 ~/.config/opencode/skills/create-plan
cp -R skills/create-plan/opencode/* ~/.config/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 ~/.config/opencode/skills/create-plan/SKILL.md || true

Verify Superpowers dependencies exist in your agent skills root:

• Codex: ~/.agents/skills/superpowers/brainstorming/SKILL.md
• Codex: ~/.agents/skills/superpowers/writing-plans/SKILL.md
• Claude Code: ~/.claude/skills/superpowers/brainstorming/SKILL.md
• Claude Code: ~/.claude/skills/superpowers/writing-plans/SKILL.md
• OpenCode: ~/.config/opencode/skills/superpowers/brainstorming/SKILL.md
• OpenCode: ~/.config/opencode/skills/superpowers/writing-plans/SKILL.md

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 — includes Planning Guardrails section
  • story-tracker.md — includes Tracking Guardrails section
  • continuation-runbook.md — includes Skill Workflow Guardrails section

Template Guardrails

All plan templates now include guardrail sections that enforce:

Planning Guardrails (milestone-plan.md):

• Design validation before implementation planning
• Native skill discovery (no deprecated CLI wrappers)
• Milestone verification + local commits + explicit approval

Tracking Guardrails (story-tracker.md):

• Immediate status updates when work starts/completes
• Explicit user approval at each milestone boundary
• No pushes until all milestones approved
• Synchronization between tracker and plan files

Skill Workflow Guardrails (continuation-runbook.md):

• Native skill invocation before action
• Explicit skill announcements
• Checklist tracking for driven skills
• No deprecated CLI wrappers

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 use native skill discovery from ~/.agents/skills/ (no CLI wrappers).
• Must verify Superpowers skills symlink: ~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
• Must invoke required sub-skills with explicit announcements:
  • superpowers:brainstorming — for design exploration and approach validation
  • superpowers:writing-plans — for milestone and story breakdown
• Must track checklist-driven skills with update_plan todos.
• Deprecated CLI commands (superpowers-codex bootstrap, use-skill) must NOT be used.

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.