# 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

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

### Claude Code

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

### OpenCode

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

## Verify Installation

```bash
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.