context-planning 0.7.0

package/commands/cp/map-codebase.md

@@ -0,0 +1,211 @@
+---
+name: cp-map-codebase
+description: Analyse the current codebase via 4 parallel sub-agents and write .planning/codebase/ docs that ground all later cp work. Native to cp — does NOT require Superpowers or any other workflow provider.
+argument-hint: "[--force] [--fast [--focus tech|arch|quality|concerns]]"
+requires: []
+---
+
+# /cp-map-codebase
+
+You are running `cp-map-codebase`. This is a **cp-native** command — it does
+not call the workflow provider. The provider abstraction is for *workflow*
+work (brainstorm/plan/execute/review/debug); map-codebase is *upfront context
+gathering* and lives entirely in the state layer.
+
+What you'll produce: 7 markdown docs in `.planning/codebase/` that match the
+GSD layout exactly, so `cp gsd-import` stays clean and the user can switch
+between cp and GSD any time.
+
+```
+.planning/codebase/
+├── STACK.md          ← tech focus (agent 1)
+├── INTEGRATIONS.md   ← tech focus (agent 1)
+├── ARCHITECTURE.md   ← arch focus (agent 2)
+├── STRUCTURE.md      ← arch focus (agent 2)
+├── CONVENTIONS.md    ← quality focus (agent 3)
+├── TESTING.md        ← quality focus (agent 3)
+└── CONCERNS.md       ← concerns focus (agent 4)
+```
+
+## Why this is cp-native
+
+The work decomposes into 4 independent reads + 7 file writes. Every modern
+agent harness has a native sub-agent dispatch (Copilot CLI's `task` tool,
+Claude Code's Task tool, etc.) that does this faster than any provider could.
+Delegating to a workflow skill would add latency and lose the parallelism.
+
+## Step 1 — Parse flags
+
+Parse `$ARGUMENTS`:
+
+- `--force` — pass through to `cp scaffold-codebase --force` (overwrites stubs).
+- `--fast [--focus <area>]` — single-agent scan mode. Spawn ONE agent for the
+  named focus (default `tech+arch`) instead of four. Useful for incremental
+  refreshes.
+- No flags — full parallel map.
+
+## Step 2 — Scaffold the stub files
+
+Run the cp wrapper. This creates `.planning/codebase/` and seeds 7 stub
+files from the templates. Idempotent — refuses to overwrite without `--force`.
+
+```
+cp scaffold-codebase
+```
+
+If `cp codebase-status` shows files already exist with content, ask the user
+whether to refresh (`--force`) or skip. **Never overwrite filled docs without
+explicit confirmation.**
+
+## Step 3 — Detect the host's sub-agent dispatch mechanism
+
+Pick the right one for your runtime:
+
+| Harness         | Mechanism                                                          |
+| --------------- | ------------------------------------------------------------------ |
+| Copilot CLI     | `task` tool, `agent_type: "explore"` (Haiku) or `"general-purpose"`|
+| Claude Code     | Task tool with `subagent_type: "general-purpose"`                  |
+| Cursor / others | Whatever native parallel-agent primitive exists                    |
+
+If you cannot find a parallel sub-agent primitive: skip to **Fallback (inline
+mode)** at the bottom of this command.
+
+## Step 4 — Dispatch 4 parallel mapper agents
+
+Spawn 4 agents IN PARALLEL (one tool-call block, all four invocations).
+Each agent gets:
+
+- A focus area (`tech` | `arch` | `quality` | `concerns`)
+- The exact output file paths it owns
+- The "be prescriptive, include file paths, current-state only" rules
+
+### Agent 1 — tech focus
+
+> You are a codebase mapper. Focus: **tech stack and external integrations**.
+>
+> Explore `{repo_root}` and write TWO files:
+>
+> 1. `.planning/codebase/STACK.md` — languages with versions (from manifest
+>    files), frameworks, top ~10 prod deps with purpose, dev tooling
+>    (build/test/lint/format with their npm/script commands), package manager
+>    and lockfile.
+> 2. `.planning/codebase/INTEGRATIONS.md` — APIs called (endpoint + auth +
+>    calling file path), DBs / data stores, message queues, auth providers,
+>    CI/CD pipelines, secrets/env-var loading paths. NEVER paste secret values.
+>
+> Rules: always cite file paths in backticks (e.g. `src/db/client.ts`). Be
+> prescriptive ("Use X") not descriptive ("X is used"). Describe current
+> state only — no history, no alternatives considered. Replace the stub
+> content entirely. Return only a one-line confirmation per file written.
+
+### Agent 2 — arch focus
+
+> You are a codebase mapper. Focus: **architecture and folder structure**.
+>
+> Explore `{repo_root}` and write TWO files:
+>
+> 1. `.planning/codebase/ARCHITECTURE.md` — architectural style (one paragraph),
+>    module boundaries (cite dirs), one end-to-end data-flow trace with file
+>    paths at each hop, key design patterns in use with file refs, cross-cutting
+>    concerns (logging/auth/caching/config/error handling) and where each lives,
+>    boundaries the executor must respect ("never import X from Y").
+> 2. `.planning/codebase/STRUCTURE.md` — annotated top-level tree, per-folder
+>    responsibilities (what belongs / does not), "where do I put a NEW
+>    CLI subcommand / HTTP route / test / migration?", filename conventions,
+>    generated/vendored/ignored paths to never edit.
+>
+> Rules as above. Replace stubs entirely. Return only confirmations.
+
+### Agent 3 — quality focus
+
+> You are a codebase mapper. Focus: **code conventions and testing**.
+>
+> Explore `{repo_root}` and write TWO files:
+>
+> 1. `.planning/codebase/CONVENTIONS.md` — naming (functions/vars/types/files),
+>    import/export style with example file ref, error handling pattern, logging
+>    (logger choice, levels, init location), comment & docs style, formatting/
+>    linting (tool + config path + commands).
+> 2. `.planning/codebase/TESTING.md` — test framework + version + all-tests
+>    and single-file commands, file layout (co-located vs mirror dir), naming
+>    pattern, AAA structure with one real example from the codebase, fixtures
+>    & mocks strategy, honest coverage picture, copy-pasteable run commands.
+>
+> Rules as above. Replace stubs entirely. Return only confirmations.
+
+### Agent 4 — concerns focus
+
+> You are a codebase mapper. Focus: **technical debt and risk**.
+>
+> Explore `{repo_root}` and write ONE file:
+>
+> 1. `.planning/codebase/CONCERNS.md` — issues bucketed Critical / High /
+>    Medium / Low. For each: file path + line range + symptom + fix approach.
+>    Plus a "Workarounds & gotchas" section ("if you change X, also update Y")
+>    and an "Areas that look safe to touch" section for low-risk regions with
+>    good test coverage.
+>
+> Rules: be specific — vague concerns are not actionable. Replace stub entirely.
+> Return only a confirmation.
+
+## Step 5 — Verify and commit
+
+Once all four agents complete:
+
+```
+cp codebase-status
+```
+
+Confirm every row shows `filled`, not `stub`. If any still look like stubs,
+ask the user whether to redispatch the matching agent.
+
+Then commit:
+
+```
+git add .planning/codebase/
+git commit -m "cp: map-codebase (7 docs)"
+```
+
+## Step 6 — Report
+
+Print:
+
+```
+✓ Codebase mapped → .planning/codebase/ (7 docs, N total lines)
+  Focus areas:    tech ✓  arch ✓  quality ✓  concerns ✓
+  Next:           cp init  (for brownfield first-time setup)
+                  /cp-plan-phase N  (to start using the new context)
+```
+
+## --fast mode
+
+When `--fast` is in `$ARGUMENTS`: spawn only ONE agent, with the focus area
+from `--focus` (default `tech+arch`, meaning it writes 4 files: STACK,
+INTEGRATIONS, ARCHITECTURE, STRUCTURE). Same prompt style, just sequential
+rather than 4-way parallel. Useful for quick refreshes after small changes.
+
+## Fallback (inline mode, no sub-agent dispatch available)
+
+If the harness has no parallel sub-agent primitive, do the work inline:
+
+1. Run `cp scaffold-codebase`.
+2. For each of the 4 focus areas in sequence, do an exploration pass (read
+   manifest files, glob for representative source files, sample 5–10 each)
+   and rewrite the corresponding doc(s) in place.
+3. Run `cp codebase-status` to verify, then commit.
+
+This is slower and consumes more context (no offloading), but produces the
+same output.
+
+## Notes
+
+- **No provider involved.** `cp doctor` will not show a `codebase_mapper`
+  role — that's correct; this command is built into cp.
+- **Stub markers:** the templates contain `fill via \`/cp-map-codebase\``
+  comments and an HTML comment per section explaining what to include.
+  Mapper agents should DELETE those markers when writing real content (so
+  `cp codebase-status` correctly reports `filled`).
+- **Brownfield bootstrap:** the recommended order for an existing project is
+  `cp scaffold-codebase` → `/cp-map-codebase` → `cp init`. The map gives
+  `cp init` real context to ground PROJECT.md against.
+- **Re-run any time** the codebase changes materially: `/cp-map-codebase --force`.

package/commands/cp/new-milestone.md

@@ -0,0 +1,136 @@
+---
+name: cp-new-milestone
+description: Start a new milestone on an existing cp project — gather goals, break into phases, update PROJECT.md/ROADMAP.md/STATE.md.
+argument-hint: "<milestone name, e.g. 'v1.1 Notifications'>"
+requires: [cp-plan-phase, cp-execute-phase]
+---
+
+# /cp-new-milestone
+
+You are running `cp-new-milestone`. The project already exists. Your job is
+to add a new milestone on top — gather its goals (delegated to the provider's
+brainstorm skill), break it into phases, and update the state layer.
+
+## TL;DR — use the v0.3 `cp` CLI wrapper
+
+After brainstorming the milestone name + goals with the user (Steps 1–3
+below), you can produce the ROADMAP shape the parser expects with a single
+shell call instead of hand-editing `## Phases`:
+
+```
+cp scaffold-milestone "v1.1 Notifications"
+```
+
+Output:
+```
+✓ .planning/ROADMAP.md
+Milestone:   v1.1 Notifications [in-progress]
+committed <hash>
+```
+
+This appends `### 🚧 v1.1 Notifications (In Progress)` inside `## Phases` and
+auto-commits. Refuses if a milestone of that name already exists. Use
+`--planned` for `### 📋 ... (Planned)` if you're queueing milestones rather
+than starting one now. Use `--dry-run` to preview without writing.
+
+Then for each phase the brainstorm identified, call `cp scaffold-phase`
+(see `/cp-plan-phase` for details) — no need to hand-edit ROADMAP anywhere.
+
+## Step 1 — Validate state
+
+- Read `.planning/PROJECT.md`. If it doesn't exist, stop and tell the user to
+  run `/cp-new-project` first.
+- Read `.planning/ROADMAP.md`, `.planning/STATE.md`.
+- Run `npx cp doctor` and note which provider/skills are available.
+
+## Step 2 — Get milestone name and intent
+
+- Milestone name comes from `$ARGUMENTS`. If empty, ask the user for it.
+- Briefly summarise what shipped previously (read the most recent
+  `### Phase N: ...` entries with all plans checked, or the last `<details>`
+  block in ROADMAP.md).
+
+## Step 3 — Delegate brainstorming
+
+Invoke the provider's `brainstorm` skill (e.g. Superpowers' `brainstorming`),
+passing the milestone name + the user's stated intent + a short summary of
+the project context (Core Value, last 3 validated requirements).
+
+Goal of the brainstorm: a clear, scoped specification for the milestone.
+
+**v0.7 design-capture (TWO destinations):**
+1. Save the FULL brainstorm transcript (verbatim Q&A) to
+   `.planning/MILESTONE-CONTEXT.md`. This is the unedited working file.
+2. Save the structured ADR summary (Status / Context / Decision /
+   Consequences / Architecture / etc.) to
+   `.planning/milestones/<slug>/DESIGN.md`. `cp scaffold-milestone`
+   already created the empty template — SP brainstorming overwrites it
+   with the populated version using its `path:` override parameter.
+
+At `cp complete-milestone`, MILESTONE-CONTEXT.md is automatically
+promoted into the milestone DESIGN.md as a "Brainstorm transcript"
+appendix and the transient file is deleted.
+
+## Step 4 — Update PROJECT.md
+
+- Move any newly-completed requirements from Active to Validated.
+- Add this milestone's new requirements to Active.
+- Update "Last updated" line to `today — added {milestone name}`.
+
+Show the diff, confirm with the user, write.
+
+## Step 5 — Break into phases
+
+Propose 2–6 phases for this milestone based on the spec. For each:
+
+- Continue phase numbering from the highest existing phase (DON'T restart at 1).
+- Heading: `### Phase N: {Name}`
+- Goal, Depends on, Success Criteria, plans list (start with 1 plan each).
+
+Confirm with the user, then append each phase block to `.planning/ROADMAP.md`.
+
+**Preferred (v0.3)** — for each phase, call:
+```
+cp scaffold-phase {N} --name "{phase name}" --plans {initial-plan-count}
+```
+This inserts `### Phase N: {name}` under the active milestone, creates
+`.planning/phases/{NN-slug}/PLAN.md` from the phase-PLAN template, and
+auto-commits. Pre-fills `- [ ] NN-MM: TBD` checkboxes for the requested
+plan count. Refuses if the phase number already exists.
+
+**Fallback (manual)** — if `cp` CLI is unavailable, edit ROADMAP.md by hand
+using `lib/roadmap.appendPhaseBlock`. Then rebuild the Progress table.
+
+Skip the "milestone bullet under `## Milestones`" step — the v0.3 template
+no longer has that section; the H3 milestone heading inside `## Phases` is
+the source of truth.
+
+## Step 6 — Update STATE.md
+
+- `Phase:` = the first new phase number of this milestone
+- `Plan:` = 1 of {plan count}
+- `Status:` = `Ready to plan`
+- `Current focus:` = first new phase name
+- `Last activity:` = `today — started milestone {name}`
+
+## Step 7 — Commit and report
+
+If `cp.behavior.atomic_commits` is true and we're in a git repo:
+```
+cp: start milestone {name} (phases X-Y)
+```
+
+Print:
+```
+✓ Milestone "{name}" planned.
+  Phases: X-Y
+  Spec:   .planning/MILESTONE-CONTEXT.md
+  Next:   /cp-plan-phase X
+```
+
+## Notes
+
+- The user should be able to interrupt and refine at any step.
+- Never write to ROADMAP/PROJECT before showing the proposed changes.
+- If the provider's brainstorm skill is unavailable, fall back to inline
+  Socratic questioning — but warn the user once.

package/commands/cp/new-project.md

@@ -0,0 +1,132 @@
+---
+name: cp-new-project
+description: Initialise a new context-planning project — scaffold .planning/, fill PROJECT.md via the provider's brainstorm skill, then create a first milestone + phase breakdown.
+argument-hint: "[project description, optional]"
+requires: [cp-new-milestone, cp-plan-phase]
+---
+
+# /cp-new-project
+
+You are running the `cp-new-project` command. Your job is to set up a fresh
+`.planning/` directory in the user's repo and use the configured workflow
+provider to fill in PROJECT.md and break the work into a first set of phases.
+
+## Step 1 — Initialise the state layer
+
+Run:
+
+```bash
+npx cp init
+```
+
+This is idempotent. It creates:
+
+- `.planning/PROJECT.md`     (template — empty)
+- `.planning/ROADMAP.md`     (template — single placeholder phase)
+- `.planning/STATE.md`       (template — position = pre-planning)
+- `.planning/cp-config.json` (default provider: superpowers)
+- `.planning/phases/`, `.planning/quick/`
+
+Report what was created vs kept.
+
+## Step 2 — Resolve the workflow provider
+
+Run:
+
+```bash
+npx cp doctor
+```
+
+Read the output. Identify:
+
+- `Provider:` line — which provider is configured (default: `superpowers`).
+- For role `brainstorm`, is the skill installed? (✓ or ✗)
+
+**If the brainstorm skill is missing AND the user has a way to install it,**
+print a one-line note recommending they install the provider and continue.
+Don't block.
+
+## Step 3 — Delegate to the brainstorm skill
+
+Hand off to the provider's `brainstorm` skill.
+
+For Superpowers users, that means invoking the `brainstorming` skill: explain
+to the user that you're going to refine the design through questions before
+writing any code, then run the skill's workflow with `$ARGUMENTS` (the
+project description) as seed.
+
+If the provider is `manual` (no real skill available), inline a minimal
+brainstorm:
+
+> Ask the user, one question at a time, until you have enough to fill the
+> PROJECT.md sections (What This Is, Core Value, Active Requirements, Out of
+> Scope, Constraints). Always confirm before writing.
+
+## Step 4 — Write PROJECT.md
+
+When the brainstorming skill returns the design (or the manual flow gathers
+enough info), populate `.planning/PROJECT.md`:
+
+- **What This Is** — 2-3 sentences in the user's words
+- **Core Value** — the ONE thing that matters
+- **Active Requirements** — `- [ ] {requirement}` bullets
+- **Out of Scope** — explicit exclusions with reasoning
+- **Constraints** — `- **{Type}**: {what} — {why}`
+- **Key Decisions** — initial table (can be empty)
+
+Show the user the proposed PROJECT.md (or the key sections) and confirm
+before writing.
+
+## Step 5 — Decide the first milestone + phase breakdown
+
+Propose **1 milestone** and **3–6 phases** based on the requirements.
+For each phase write:
+
+- `### Phase N: {Name}` heading
+- `**Goal**:` one line
+- `**Depends on**:` previous phase or "Nothing"
+- `**Success Criteria**:` 2-5 observable behaviors
+- Plans list: `- [ ] NN-01: {brief}` (start with 1 plan per phase; we
+  refine in /cp-plan-phase)
+
+Show the user the proposed roadmap and confirm.
+
+Then update `.planning/ROADMAP.md`:
+
+- Replace the placeholder milestone heading with the real milestone
+- Replace the placeholder phase block with the real phase blocks
+- Rebuild the Progress table (`require('context-planning/lib/roadmap').rebuildProgressTable`)
+
+## Step 6 — Update STATE.md and commit
+
+- Set `Phase: 1 of N`, `Plan: 1 of {phase1 plan count}`, `Status: Ready to plan`
+- Set `Current focus:` to phase 1 name
+- Set `Last activity:` to `today — initialised project`
+- Update `Last session` and `Stopped at` in Session Continuity
+
+If `cp.behavior.atomic_commits` is `true` in `.planning/config.json` and
+we're in a git repo, commit with:
+
+```
+cp: init project state for {project name}
+```
+
+## Step 7 — Tell the user what's next
+
+Print:
+
+```
+✓ Project initialised.
+  Phase 1: {name} — {N} plans
+  Next:    /cp-plan-phase 1
+```
+
+## Notes
+
+- Never invent requirements the user didn't agree to.
+- Confirm before writing each major file.
+- Read `.planning/config.json` (the merged GSD+cp config) for the provider
+  mapping. cp-specific keys live under `cp.*`. Don't hard-code `superpowers`
+  skill names.
+- If `.planning/PROJECT.md` already exists with real content (not the
+  placeholder), stop and tell the user to run `/cp-new-milestone` instead.

package/commands/cp/plan-phase.md

@@ -0,0 +1,195 @@
+---
+name: cp-plan-phase
+description: Create the phase directory and PLAN.md for phase N by delegating to the provider's plan skill.
+argument-hint: "<phase number, e.g. 1 or 2.1>"
+requires: [cp-execute-phase]
+---
+
+# /cp-plan-phase
+
+You are running `cp-plan-phase`. Your job is to take a phase that exists in
+ROADMAP.md and turn it into a concrete `PLAN.md` ready for execution.
+
+## TL;DR — use the v0.3 `cp` CLI wrapper
+
+If the phase doesn't yet exist in ROADMAP (e.g. the user jumped here from
+`/cp-new-milestone` without scaffolding the phases yet), create the phase
+shell first:
+
+```
+cp scaffold-phase {N} --name "{phase name}" --plans {initial-plan-count}
+```
+
+Output:
+```
+✓ .planning/ROADMAP.md
+✓ .planning/phases/{NN-slug}/PLAN.md
+Phase {N} added to milestone "{active milestone}" ({M} plans: {NN-01}, ...)
+committed <hash>
+```
+
+The wrapper inserts the `### Phase N: {name}` heading under the active
+milestone in ROADMAP, creates `.planning/phases/{NN-slug}/PLAN.md` from the
+`templates/phase-PLAN.md` template, pre-fills `- [ ] NN-MM: TBD` checkboxes
+for the requested plan count, and auto-commits. Use `--dry-run` to preview,
+`--milestone <name>` to target a non-active milestone, `--no-commit` to skip
+the commit.
+
+After the wrapper runs (or if the phase already exists), proceed below to
+fill in the per-plan details (objectives, tasks, success criteria) by
+delegating to the provider's plan skill.
+
+## Step 1 — Resolve the phase
+
+- `PHASE_NUM` = `$ARGUMENTS` (sanitize: must match `^[\d]+(\.\d+)?$`).
+- Read `.planning/ROADMAP.md`. Find the matching `### Phase {PHASE_NUM}: {Name}`
+  block. Extract:
+  - phase name
+  - goal
+  - success criteria
+  - requirements (the `**Requirements**:` line)
+  - planned plans list
+- If not found, stop and tell the user to add it first via `/cp-new-milestone`
+  or by editing ROADMAP.md.
+
+## Step 2 — Create the phase directory and PLAN file
+
+Use the cp helpers (`require('context-planning/lib/paths')`) to derive
+GSD-compatible filenames:
+
+```
+phaseDirName(N, name)      -> "01-foundation"   (zero-padded; decimals kept as-is)
+phasePlanPrefix(N, planN)  -> "01-01"
+planFile(N, name, planN)   -> ".planning/phases/01-foundation/01-01-PLAN.md"
+summaryFile(...)           -> ".planning/phases/01-foundation/01-01-SUMMARY.md"
+```
+
+Create the dir if missing. For each planned plan in the ROADMAP, create the
+stub PLAN file from `templates/PLAN.md`, substituting:
+
+- `{{PHASE_DIR}}`   — e.g. `01-foundation`
+- `{{PLAN_NUM_PADDED}}` — e.g. `01`
+- `{{PHASE_PLAN_PREFIX}}` — e.g. `01-01`
+- `{{WAVE}}`        — `1` initially; the plan skill or a future
+  parallelization pass can update it
+- `{{OBJECTIVE}}`, `{{PURPOSE}}`, `{{OUTPUT}}` — derived from the ROADMAP
+  goal + this plan's brief description
+- `{{PROVIDER}}`, `{{PLAN_SKILL}}` — from `cp doctor`
+
+PLAN frontmatter is GSD-shaped:
+```
+phase: 01-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+requirements: [REQ-01, REQ-02]   # populate from ROADMAP **Requirements**: line
+user_setup: []
+must_haves:
+  truths: []
+  artifacts: []
+  key_links: []
+```
+
+The `<tasks>` block stays empty for the plan skill to fill in (see Step 4).
+
+## Step 3 — Resolve the plan skill
+
+Run `npx cp doctor`. Find the `plan` role's resolved provider + skill.
+
+- If installed (default: Superpowers' `writing-plans`): invoke it.
+- If `manual`: warn the user the provider's plan skill is missing, then fall
+  back to inline plan-writing — ask the user about each task, scope, success.
+
+## Step 3.5 — Delegate to brainstorming for DESIGN.md (v0.7)
+
+Before invoking the plan skill, invoke the provider's `brainstorm` skill
+to fill in the phase-tier DESIGN.md.
+
+- `cp scaffold-phase` already created an empty template at
+  `.planning/phases/{phase-dir}/DESIGN.md`.
+- Pass to the brainstorm skill:
+  - The phase Goal, Success Criteria, and Requirements (from ROADMAP.md)
+  - The milestone DESIGN.md at `.planning/milestones/<slug>/DESIGN.md` as
+    context (so the phase design stays consistent with the milestone)
+  - A `path:` override pointing to
+    `.planning/phases/{phase-dir}/DESIGN.md` so SP writes there directly
+    instead of `docs/superpowers/specs/...`
+- Do NOT touch frontmatter keys cp populated (`phase`, `milestone`,
+  `status`, `created`). SP fills in Status, Context, Decision,
+  Consequences, Architecture, Components, Data Flow, Error Handling,
+  Testing Strategy, Alternatives Considered, Open Questions, References.
+
+If the brainstorm skill is unavailable (provider = manual), skip this
+step — DESIGN.md stays empty and the user can fill it later.
+
+The DESIGN.md becomes a context input to the plan skill in Step 4.
+
+## Step 4 — Delegate to the plan skill
+
+Pass to the plan skill:
+- The phase DESIGN.md at `.planning/phases/{phase-dir}/DESIGN.md` (v0.7)
+  as the architectural source-of-truth; plan tasks should align with the
+  Decision and Components sections.
+- The phase Goal and Success Criteria (verbatim from ROADMAP.md)
+- The Requirements list (from ROADMAP's `**Requirements**:` line)
+- The Context block from PROJECT.md (Core Value, related Active requirements)
+- A pointer to write the resulting plan into the GSD-shaped file
+  `.planning/phases/{phase-dir}/{phase}-{plan}-PLAN.md` — replacing the
+  `<tasks>` block. **Do not rename the file.** Do not touch frontmatter
+  keys cp populated (phase, plan, type, wave, depends_on, requirements);
+  the skill MAY append/refine `files_modified`, `must_haves.*`, and
+  `autonomous` once it has decomposed the work.
+- The instruction that each task should be 2-5 minutes, file-scoped, with a
+  clear verification step (per Superpowers' writing-plans conventions), and
+  each task expressed as a `<task type="auto">...</task>` block (GSD shape).
+
+The plan skill is expected to populate the `<tasks>` section of PLAN.md with
+one `<task>` block per actionable step.
+
+## Step 5 — Reconcile with ROADMAP.md plans list
+
+After the plan skill returns:
+
+- Count `<task type="auto">` blocks in the new PLAN.md.
+- If the count differs from the plans listed in ROADMAP.md for this phase,
+  show the user and ask whether to:
+  (a) keep the original ROADMAP plan count (let PLAN.md just decompose
+      each into sub-tasks), or
+  (b) replace the ROADMAP plans list with one entry per task in PLAN.md.
+
+  Default to (a). The plans list in ROADMAP.md is the COARSE checklist;
+  PLAN.md is the fine detail.
+
+## Step 6 — Update STATE.md
+
+- `Plan:` = `1 of {plan count}`
+- `Status:` = `Ready to execute`
+- `Last activity:` = `today — planned phase {N}`
+
+## Step 7 — Commit and report
+
+If `cp.behavior.atomic_commits` is true:
+```
+cp: plan phase {N} ({phase name})
+```
+
+Print:
+```
+✓ Phase {N} planned: {phase name}
+  Tasks:  {count}
+  File:   .planning/phases/{phase-dir}/{phase}-{plan}-PLAN.md
+  Next:   /cp-execute-phase {N}
+```
+
+## Notes
+
+- The plan skill OWNS the content of PLAN.md's `<tasks>` block.
+- Don't second-guess the plan skill's output — it's the workflow provider's
+  area of expertise.
+- If the user wants to tweak the plan, let them edit PLAN.md directly and
+  re-invoke `/cp-execute-phase`.
+- Filenames follow GSD convention: `{phase}-{plan}-PLAN.md` so a GSD
+  workflow can read and continue from the same file.