context-planning 0.7.0

package/commands/cp/progress.md

@@ -0,0 +1,147 @@
+---
+name: cp-progress
+description: Show where you are in the project — current phase, last activity, next plan, and progress %. Read-only.
+argument-hint: ""
+requires: []
+---
+
+# /cp-progress
+
+You are running `cp-progress`. This is a **read-only** diagnostic: tell the
+user exactly where they are in the project and what the obvious next action
+is. Do not modify any files.
+
+## TL;DR — use the `cp status` CLI wrapper
+
+The `cp status` CLI command does almost everything this command needs.
+Run it, format the output for the user, and add any extras (project name
+from PROJECT.md, continue-here notice).
+
+```bash
+cp status --json
+```
+
+Returns:
+
+```json
+{
+  "ok": true,
+  "milestone": "v0.1 MVP",
+  "milestoneStatus": "in-progress",
+  "phases": [
+    { "num": "1", "name": "Foundation", "done": 2, "total": 2 },
+    { "num": "2", "name": "Search",     "done": 0, "total": 1 }
+  ],
+  "nextPlan": {
+    "phaseNum": "2",
+    "phaseName": "Search",
+    "planId": "02-01",
+    "desc": "search command"
+  },
+  "stateContentPresent": true
+}
+```
+
+If `cp` isn't on PATH, fall back to the manual procedure in the
+["Fallback"](#fallback--manual-implementation) section.
+
+## Step 1 — Read project name
+
+Read the first `# heading` of `.planning/PROJECT.md` for the project name
+(or fall back to the repo dir basename). This is the only thing
+`cp status` doesn't surface.
+
+## Step 2 — Run `cp status`
+
+```bash
+cp status --json
+```
+
+If `ok: false`, surface the error message verbatim and suggest
+`/cp-new-project` or `cp init`.
+
+## Step 3 — Detect continue-here
+
+Check whether `.planning/.continue-here.md` (or
+`.planning/phases/{NN-slug}/.continue-here.md`) exists. If so, you'll add a
+suffix to the output.
+
+## Step 4 — Render the report
+
+Format like this (substitute values from the JSON):
+
+```
+cp progress
+───────────
+
+Project:    {project name}
+Milestone:  {milestone or "(none in progress)"}
+
+You are here:
+  Phase {num}: {name}   ({done}/{total} plans complete)
+  Plan  {nextPlan.planId}: {nextPlan.desc}    ← next action
+
+Overall:    {sum done}/{sum total} plans complete   {progress bar — see below}
+
+Phase breakdown:
+  ✓ Phase 1: Foundation                 (2/2 — Complete)
+  ▶ Phase 2: Search                     (0/1 — In progress)
+
+Suggested next:
+  /cp-execute-phase {nextPlan.phaseNum}     # PLAN exists for nextPlan? (see step 5)
+  /cp-plan-phase    {nextPlan.phaseNum}     # if not
+```
+
+**Progress bar** — match `lib/state.progressBar(pct)` exactly so STATE.md
+edits agree: `[██████░░░░] 60%` style (10-char bar of `█`/`░`).
+
+**Phase legend:**
+- `✓` Complete (done == total > 0)
+- `▶` In progress (the one "you are here", or 0 < done < total)
+- ` ` Not started (done == 0, total > 0)
+- `?` Planned (total == 0 — no plan file yet)
+
+## Step 5 — Decide the suggested next command
+
+Check `lib/paths.findPhaseDir(nextPlan.phaseNum)` — if it returns a real
+dir AND that dir contains `{nextPlan.planId}-PLAN.md`, suggest
+`/cp-execute-phase`. Otherwise suggest `/cp-plan-phase`.
+
+(Simpler heuristic: if `phases[i].total > 0` in the JSON, suggest execute;
+else suggest plan.)
+
+## Step 6 — Continue-here notice (if Step 3 found one)
+
+```
+↩ A continue-here.md is waiting. Run /cp-resume to restore mid-task context.
+```
+
+## Step 7 — Edge cases
+
+- **No milestone in progress:** print "Milestone: (none in progress)" and
+  suggest `/cp-new-milestone "<name>"`.
+- **All plans across all phases done:** suggest `/cp-complete-milestone`.
+- **STATE.md disagrees with ROADMAP (e.g. STATE says Phase 4 but ROADMAP
+  shows Phase 4 has no plans yet):** surface as a warning line but trust
+  ROADMAP (which is what `cp status` reads from).
+
+## Fallback — manual implementation
+
+If `cp` isn't on PATH, replicate `lib/lifecycle.statusReport(root)`:
+- `roadmap.listPhases(content)` → phases array with `{num, name, plans[]}`
+- Find the in-progress milestone heading (`### 🚧 {name} (In Progress)`
+  or just `(In Progress)` in the heading)
+- Filter `listPhases` results to those whose `num` is in
+  `findMilestoneInRoadmap(content, name).phases`
+- nextPlan = first phase × first plan where `!plan.done`
+
+Then render as above.
+
+## Notes
+
+- This command MUST NOT write any file. It only reads.
+- Keep output compact; the user runs this often.
+- The progress bar should match `lib/state.progressBar(pct)` exactly so
+  downstream STATE.md edits agree.
+- `cp status` already handles the milestone/phase/next-plan logic with
+  394-test coverage; prefer it over re-implementing.

package/commands/cp/quick.md

@@ -0,0 +1,104 @@
+---
+name: cp-quick
+description: Lightweight ad-hoc task. Creates a quick PLAN.md, drives it through the provider, records SUMMARY.md. No phase/roadmap baggage.
+argument-hint: "<task description>"
+requires: []
+---
+
+# /cp-quick
+
+You are running `cp-quick`. Use this for small, ad-hoc work that doesn't
+deserve a full phase: a bug fix, a small refactor, a dependency bump.
+
+## Step 1 — Parse arguments
+
+- If `$ARGUMENTS` starts with `list`: list everything under `.planning/quick/`
+  (one row per dir, status from frontmatter, no agent spawn). Stop.
+- If `$ARGUMENTS` starts with `resume <slug>`: find
+  `.planning/quick/*-<slug>/`, load its PLAN.md, jump to Step 4.
+- Otherwise: `TASK = $ARGUMENTS` is the task description. If empty, ask.
+
+## Step 2 — Slug + directory
+
+- `slug` = lowercase, hyphenated first 5-8 words of TASK, max 40 chars,
+  `[a-z0-9-]+` only.
+- `dir` = `.planning/quick/{YYYYMMDD}-{slug}/`. Create it.
+
+## Step 3 — Write a starter PLAN.md
+
+Copy `templates/quick-PLAN.md` to `{dir}/PLAN.md`, substituting
+`{{SLUG}}`, `{{TITLE}}` (first line of TASK, sentence case), `{{DESCRIPTION}}`
+(full TASK), `{{DATE}}` (today).
+
+## Step 4 — Resolve the plan skill (light)
+
+Run `npx cp doctor`. Resolve role `plan`.
+
+For quick tasks we want a LIGHTER plan than full phases. Two options:
+
+- (preferred) Invoke the provider's `plan` skill but instruct it to produce a
+  short plan (3–7 tasks max). Save into `{dir}/PLAN.md` (replace the
+  `## Approach` and `## Tasks` sections).
+- If the provider's plan skill is unavailable: ask the user 2-3 clarifying
+  questions, then write a short task list inline.
+
+Confirm the plan with the user before executing.
+
+## Step 5 — Execute
+
+Resolve role `execute`.
+
+- Preferred: provider's `execute` (Superpowers' `subagent-driven-development`
+  or `executing-plans` — whichever the provider config maps).
+- Manual: drive task-by-task inline; commit each atomically.
+
+Each task should produce a commit. Use Conventional Commits, prefixed with
+`(quick: {slug}) `.
+
+## Step 6 — Write SUMMARY.md
+
+When done, copy `templates/quick-SUMMARY.md` to `{dir}/SUMMARY.md`. Fill in:
+
+- `{{SLUG}}`, `{{TITLE}}`, `{{ONE_LINER}}` (substantive!),
+- `{{CREATED}}` from PLAN.md frontmatter, `{{COMPLETED}}` = now,
+  `{{DURATION_MIN}}` = diff,
+- `{{PROVIDER}}` from cp-config,
+- "What Changed" — files from `git diff --name-only {start_sha}..HEAD`,
+- "Commits" — `git log --oneline {start_sha}..HEAD`.
+
+Update PLAN.md frontmatter: `status: complete`.
+
+## Step 7 — Update STATE.md (lightly)
+
+Quick tasks don't move the phase/plan counters. They only update:
+
+- `Last activity:` = `today — quick task: {slug}`
+- `Last session` / `Stopped at` in Session Continuity
+- Append a row to the `## Quick Tasks Completed` table:
+  `| {YYYY-MM-DD} | {slug} | {one-liner} |`
+
+The Quick Tasks Completed table is created by `cp init` and is
+GSD-compatible (GSD's STATE.md template has the same section).
+
+## Step 8 — Commit and report
+
+```
+cp: quick task — {slug}
+```
+
+Print:
+```
+✓ Quick task complete: {slug}
+  {one-liner}
+  {N} commits, {M} files
+  SUMMARY: {dir}/SUMMARY.md
+```
+
+## Notes
+
+- Quick tasks live OUTSIDE the phase/roadmap structure on purpose.
+- Use a `--full` style of provider invocation (review + verification) ONLY
+  if the user passed `--full` in $ARGUMENTS.
+- Resume support: if PLAN.md frontmatter shows `status: in-progress` when
+  `/cp-quick resume <slug>` is invoked, continue from where execution left
+  off rather than re-planning.

package/commands/cp/resume.md

@@ -0,0 +1,125 @@
+---
+name: cp-resume
+description: Restore mid-task context from .continue-here.md (if present) or STATE.md, then keep going.
+argument-hint: ""
+requires: [cp-progress, cp-execute-phase]
+---
+
+# /cp-resume
+
+You are running `cp-resume`. The user stopped in the middle of something and
+wants to pick it back up. Your job is to **restore enough context to keep
+going**, then either continue the active plan or hand off to the right
+follow-up command.
+
+## Step 1 — Load planning context
+
+Read in this order (each only if it exists):
+
+1. `.planning/.continue-here.md`  — GSD-shape mid-task handoff note (highest
+   priority signal: the previous session wrote it intentionally).
+2. `.planning/STATE.md`            — current position + last activity.
+3. `.planning/ROADMAP.md`          — to translate STATE position into the
+   actual phase / plan that's in progress.
+4. `.planning/MILESTONE-CONTEXT.md` — current milestone goal, if any.
+5. The PLAN.md for the in-progress plan (derived from STATE.md + ROADMAP).
+
+## Step 2 — Identify the in-progress unit of work
+
+There are three cases. Try them in order:
+
+**(A) `.continue-here.md` exists**
+- Trust it as the source of truth. Parse it for:
+  - "Stopped at" line (a free-form description of where work paused)
+  - Any "Next" / "TODO" bullet list
+  - File pointers (PLAN.md, code files mid-edit)
+- This is GSD-compatible; format the file with the same shape so GSD's
+  `gsd-resume-work` will read it after a switch back.
+
+**(B) STATE.md `Status:` is `In progress`**
+- Use `Phase:` + `Plan:` from STATE.md to compute the active PLAN file:
+  - `lib/paths.findPhaseDir(phaseNum)` → phase dir
+  - filename `{phasePlanPrefix}-PLAN.md`
+- Read that PLAN.md's frontmatter. If `status: in-progress`, find the first
+  `<task>` block whose `<done>` criteria are not yet met (best-effort
+  heuristic: agent should re-check via `<verify>` commands).
+
+**(C) Nothing in progress**
+- Fall through to `/cp-progress`'s recommended next action (the next pending
+  plan in the lowest-numbered phase).
+
+## Step 3 — Verify the workspace
+
+Before suggesting the user keep going, sanity check:
+
+- `git status` — uncommitted changes? Show them; ask if the user wants them
+  before resuming (they may be the partial work from the previous session).
+- Run the PLAN.md's `<verify>` for any task marked `done` to confirm the
+  reported state matches reality. If a `done` task no longer passes verify,
+  flag it.
+- If a plan claims `wave > 1` and `depends_on` includes a plan id, confirm
+  that prerequisite plan is checked in ROADMAP.md. If not, surface the
+  ordering issue.
+
+## Step 4 — Restore context to the user
+
+Print:
+
+```
+cp resume
+─────────
+
+Project:     {project name}
+Milestone:   {milestone name or "(none)"}
+
+Resuming:    Phase {N} ({phase name}), plan {phase-plan id}
+Stopped at:  {one-line summary from .continue-here.md or STATE.md "Last activity"}
+
+Verified:
+  ✓ {task X is still passing}
+  ✗ {task Y now fails — needs re-investigation}
+  ? {task Z has no <verify> — skipped}
+
+Uncommitted changes:
+  {git status --short output, or "(clean)"}
+
+Plan file:   .planning/phases/{phase-dir}/{phase}-{plan}-PLAN.md
+
+Next action:
+  {pick the first unfinished <task> in PLAN.md and quote its <name>}
+
+Run:
+  /cp-execute-phase {N}    # continue automated execution
+  # or work this task manually and re-invoke /cp-resume when done
+```
+
+## Step 5 — Update STATE.md (Session Continuity only)
+
+Write back to STATE.md `## Session Continuity` only — do not touch other
+sections:
+
+- `Last session: {today's date}`
+- `Stopped at:   {one-line summary}` (kept from previous if unchanged)
+- `Resume file:  .planning/.continue-here.md` (if it exists) or `(none)`
+
+Use `lib/state.updateSessionContinuity`.
+
+## Step 6 — Hand off or stop
+
+If the user wants automatic continuation and the active plan's `autonomous`
+frontmatter is `true`, invoke `/cp-execute-phase N` directly.
+
+If `autonomous: false` (checkpointed plan) or the user wants control, stop
+here and let them drive.
+
+## Notes
+
+- This command MAY write only to STATE.md `## Session Continuity` and
+  optionally `.planning/.continue-here.md` (to refresh "Resumed at"). It MUST
+  NOT modify ROADMAP.md, PROJECT.md, or any PLAN.md / SUMMARY.md.
+- `.continue-here.md` is GSD-shaped — keep the same headings GSD writes:
+  `## Stopped at`, `## Next`, `## Context`.
+- If `cp.behavior.atomic_commits` is true and you wrote to STATE.md, commit:
+  ```
+  cp: resume — session restored
+  ```

package/commands/cp/write-summary.md

@@ -0,0 +1,33 @@
+---
+name: cp-write-summary
+description: Write a phase SUMMARY from JSON frontmatter and optional markdown body.
+argument-hint: "<plan-id> --from <json> [--body <md>] [--overwrite] [--dry-run]"
+requires: []
+---
+
+# /cp-write-summary
+
+## Required keys (v0.7 hard-block)
+
+- `key-decisions`: **REQUIRED**. Array with ≥1 entry. Each entry is one
+  sentence describing a non-trivial decision made during the plan
+  (architecture, library choice, trade-off, deferred work, etc.).
+  Trivial / mechanical steps do not count.
+
+The cp CLI exits with code 2 and prints the following exact message if
+this constraint is violated:
+
+  Error: 'key-decisions' is required and must have ≥1 entry. See spec at
+  docs/superpowers/specs/2026-05-20-v0-7-design-capture-design.md
+
+If a plan genuinely had no decisions worth recording (e.g. a typo fix),
+note that explicitly: `key-decisions: ['mechanical edits only — no design decisions']`.
+
+Use `cp write-summary` to write `{plan-id}-SUMMARY.md` into the phase directory.
+Pass frontmatter JSON with `--from`; optionally supply markdown body content with
+`--body`. Use `--dry-run` to preview the normalised frontmatter and `--overwrite`
+to replace an existing summary.
+
+```bash
+cp write-summary 16-03 --from summary.json --body summary-body.md
+```

package/docs/MIGRATION-v0.5.md

@@ -0,0 +1,140 @@
+# Migrating to cp v0.5
+
+## What changed
+
+v0.5 restructures provider detection from hardcoded literal sentinel
+matching to a data-driven **harnesses × providers** cross-product.
+Adding a new harness (AI editor) or workflow provider is now a config-only
+edit — no code changes needed.
+
+## Automatic migration
+
+**Most users don't need to do anything.** The first time any `cp` command
+runs in your project after upgrading to v0.5, `loadConfig()` automatically:
+
+1. Bumps `cp.version` from 1 to 2.
+2. Adds the `cp.harnesses` block (4 harnesses with `plugin_roots`).
+3. Adds `plugin_shape` to the `superpowers` provider.
+4. Adds the `echo-provider` schema-test stub.
+5. Unions any new sentinels into `cp.providers.*.detect.any_of`.
+6. Fills missing `behavior.*` keys.
+
+A one-line notice is printed to stderr:
+```
+cp: refreshed .planning/config.json with schema v1 → v2, new harness 'copilot', ...
+```
+
+The merge is **purely additive** — your existing config values are never
+overwritten or removed. Second invocation is a no-op.
+
+## Manual migration (optional)
+
+If you prefer explicit control:
+
+```bash
+# Preview what would change
+cp config refresh --dry-run
+
+# Apply
+cp config refresh
+```
+
+## Before / after config shape
+
+### v0.4.x (schema v1)
+
+```json
+{
+  "cp": {
+    "version": 1,
+    "workflow_provider": "superpowers",
+    "providers": {
+      "superpowers": {
+        "detect": {
+          "any_of": [".claude/plugins/superpowers", "..."]
+        },
+        "skills": { "brainstorm": "brainstorming", "..." }
+      },
+      "manual": { "..." }
+    },
+    "behavior": { "atomic_commits": true, "..." }
+  }
+}
+```
+
+### v0.5.0 (schema v2)
+
+```json
+{
+  "cp": {
+    "version": 2,
+    "workflow_provider": "superpowers",
+
+    "harnesses": {
+      "copilot": {
+        "description": "GitHub Copilot CLI",
+        "plugin_roots": ["~/.copilot/installed-plugins/*/"]
+      },
+      "claude": {
+        "description": "Claude Code",
+        "plugin_roots": ["~/.claude/plugins/", "~/.claude/skills/"]
+      },
+      "cursor": {
+        "description": "Cursor",
+        "plugin_roots": ["~/.cursor/extensions/*/"]
+      },
+      "aider": {
+        "description": "Aider (file-based, no plugin slot today)",
+        "plugin_roots": []
+      }
+    },
+
+    "providers": {
+      "superpowers": {
+        "plugin_shape": {
+          "dir_name": "superpowers",
+          "required_subdirs": ["skills/writing-plans", "skills/subagent-driven-development"]
+        },
+        "detect": { "any_of": ["... (8 sentinels, was 5 in v0.4.4)"] },
+        "skills": { "..." }
+      },
+      "echo-provider": {
+        "description": "Schema-test stub. Echoes the role name.",
+        "plugin_shape": { "dir_name": "echo-provider", "required_subdirs": [] },
+        "detect": { "any_of": [".planning/providers/echo-provider"] },
+        "skills": { "brainstorm": "echo", "..." }
+      },
+      "manual": { "..." }
+    },
+    "behavior": { "..." }
+  }
+}
+```
+
+## `cp doctor` output changes
+
+v0.5 rewrites the doctor output into 5 sections:
+
+1. **Harnesses detected** — which AI editors have plugins installed
+2. **Providers detected** — which workflow providers were found, and via which harness
+3. **Configured workflow_provider** — what's active, with switch hint
+4. **Roles → resolved skill** — same as before, with harness annotation
+5. **GSD compatibility** — unchanged
+
+New flags: `--json` (machine-parsable), `--quiet` (configured + roles only).
+
+## Removing local workarounds
+
+If you manually added `installed-plugins/superpowers-marketplace/superpowers`
+to your project's `.planning/config.json` `detect.any_of` as a workaround
+for the v0.4.4 detection bug, you can now remove it — the auto-heal merge
+adds it from upstream defaults. Run `cp config refresh --dry-run` to verify.
+
+## New commands
+
+| Command | Description |
+|---|---|
+| `cp config refresh [--dry-run]` | Re-sync local config with upstream defaults |
+| `cp install echo-provider` | Install the schema-test stub provider |
+| `cp doctor --json` | Machine-parsable detection report |
+| `cp doctor --quiet` | Minimal: configured + roles only |