Use when the user explicitly says `plan on step x` or `plan on phase x`. Do not activate on loose planning language.
Planning-only workflow for any software project. Discover repo context, run setup if required docs are missing, run the design workflow, update planning artifacts, and stop before any implementation begins.
Always at root (framework conventions, never moved):
CLAUDE.md / AGENTS.md / GEMINI.mdDiscoverable docs (BACKLOG.md, IMPLEMENTATION_PLAN.md, ARCHITECTURE_NOTES.md):
Apply this lookup order for each doc, and record the resolved path for use throughout the rest of the workflow:
./BACKLOG.md)docs/planning/ (e.g. docs/planning/BACKLOG.md)If docs are split across locations (some at root, some in ): follow the majority. If evenly split, ask the user which location to treat as canonical before proceeding.
docs/planning/For new docs (created in Step 0): default to docs/planning/ to keep root clean. Match the location of existing discoverable docs if any are already present.
Run doc location discovery (above) before doing anything else.
Scan for the required planning docs using the resolved paths:
| Doc | Purpose | Required |
|---|---|---|
CLAUDE.md / AGENTS.md / GEMINI.md | Project instructions | Required |
BACKLOG.md | Phase/task checklist | Required |
IMPLEMENTATION_PLAN.md | Phase roadmap | Required |
ARCHITECTURE_NOTES.md | Architecture reference | Recommended |
If one or more required docs are missing:
docs/planning/ (or the project's canonical location if already established) using the stubs at the bottom of this skill. Adapt to the project's existing naming and style conventions.If only ARCHITECTURE_NOTES.md is absent and no architecture decisions are needed for this step, skip creation silently. Create it in Step 6 only if planning produces architecture decisions worth recording.
If all required docs are present, skip this step and proceed to Step 1.
Activate only for:
plan on step xplan on phase xDo not activate for loose forms like plan the next step, planning for ACL, or phase 3 planning. If unclear, ask the user to clarify.
step and phaseTreat step and phase as aliases by default. When reading repo docs:
Before proposing any design, read (using the resolved paths from discovery):
CLAUDE.md, AGENTS.md, or GEMINI.md)IMPLEMENTATION_PLAN.mdARCHITECTURE_NOTES.mdBACKLOG.mddocs/superpowers/specs/, docs/planning/, or wherever specs live)Use the current codebase state, not only the backlog wording, to define the planning boundary.
After reading repo context, use the brainstorming skill for the requested planning target.
After design approval:
docs/superpowers/specs/).docs/superpowers/plans/).Update BACKLOG.md at its resolved path as part of the planning workflow.
### Phase N Execution Checklist format.[ ] (not started). Do not mark any items [x] here; that happens during execution as tasks are completed.Update IMPLEMENTATION_PLAN.md and ARCHITECTURE_NOTES.md only when planning materially changes the phase map, architecture defaults, or system responsibilities. Do not churn those docs for local target-level details.
If ARCHITECTURE_NOTES.md does not exist and this step produces architecture decisions worth recording, create it at the canonical planning location using the stub below.
After design approval, use the writing-plans skill to produce the implementation plan.
The plan should:
After updating spec, plan, and backlog, stop and ask whether to begin implementation.
Do not start coding, enter implementation mode, or run execution skills automatically.
The handoff must identify:
BACKLOG.md was updated (and its path)Keep this skill planning-only. Do not use it to implement code, execute plan tasks, infer planning intent from approximate wording, or rewrite unrelated planning docs without a concrete architectural reason.
Use these as starting points when creating missing files. Adapt headings and sections to match any existing conventions in the project.
# Backlog
## Status Legend
- [ ] Not started
- [x] Complete
- [~] In progress
<!-- Add phase checklists below as phases are planned. -->
# Implementation Plan
## Overview
<!-- Brief description of the project and its delivery strategy. -->
## Phases
<!-- Each phase should have a goal, key deliverables, and success criteria. -->
### Phase 1 — [Name]
**Goal:** ...
**Deliverables:** ...
**Success criteria:** ...
# Architecture Notes
## Stack
<!-- Languages, frameworks, databases, infrastructure. -->
## Key Decisions
<!-- Record significant architecture choices and the reasoning behind them. -->
## Component Responsibilities
<!-- What each major component owns. -->
## Design Constraints
<!-- Non-negotiable constraints that shape the architecture. -->