---
name: create-plan
description: Use when starting a new feature, project, or complex task that needs structured planning with milestones, bite-sized stories, and resumable execution context in Opencode workflows. ALWAYS invoke when user says "create a plan", "make a plan", "plan this", "start planning", or similar planning requests.
---

# Create Plan (OpenCode)

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

## Prerequisite Check (MANDATORY)

This OpenCode variant depends on Superpowers skills being installed via OpenCode's native skill system.

Required:
- Superpowers repo: `https://github.com/obra/superpowers`
- OpenCode Superpowers skills symlink: `~/.config/opencode/skills/superpowers`
- `superpowers/brainstorming`
- `superpowers/writing-plans`

Verify before proceeding:

```bash
ls -l ~/.config/opencode/skills/superpowers
```

If dependencies are missing, stop immediately and return:

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

## Process

### Phase 1: Bootstrap Superpowers Context (REQUIRED)

Use OpenCode's native skill tool:
- list skills
- verify `superpowers/brainstorming` and `superpowers/writing-plans` are discoverable

### Phase 2: Analyze
- Explore the codebase and existing patterns.

### Phase 3: Gather Requirements
- Ask questions ONE AT A TIME until user says ready.
- Cover scope, constraints, success criteria, dependencies.
- Summarize before proceeding.

### Phase 4: Design (REQUIRED SUB-SKILL)

Use OpenCode's native skill tool to load:
- `superpowers/brainstorming`

Then present 2-3 approaches and recommend one.

### Phase 5: Plan (REQUIRED SUB-SKILL)

Use OpenCode's native skill tool to load:
- `superpowers/writing-plans`

Then break into milestones and bite-sized stories (2-5 min each).
Story IDs: `S-{milestone}{sequence}`.

### 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:
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 (template-based).
4. `story-tracker.md` - status tracking (template-based, all stories start as `pending`).
5. `continuation-runbook.md` - resume context and execution protocol (template-based).

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 `ai_plan` files only.

## Tracker Discipline (MANDATORY)

Before starting any story:
1. Open `story-tracker.md`
2. Mark story `in-dev`
3. Add notes if relevant
4. Then begin implementation

After completing any story:
1. Mark story `completed`
2. Add commit hash in Notes
3. Review pending stories
4. Update Last Updated and Stories Complete counts

## 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` created with all stories as `pending`
- [ ] `continuation-runbook.md` present
- [ ] Handoff explicitly says to read runbook first and execute from plan folder

## Exit Triggers for Question Phase
User says: "ready", "done", "let's plan", "proceed", "enough questions"