v1.0.0 — Workflow Engine

v1.0.0 — Workflow Engine

The first major release of context-planning. Ships a reusable YAML workflow engine on top of cp's stateful planning layer.

📘 Full guide: MIGRATION-v1.0.md

What's new

🔧 Workflow Engine

A reusable YAML workflow format with phase DAGs, parallel waves, top-level principles:, and three state tiers (milestone / phase / custom). Define a workflow once; run it many times.

🚀 cp run CLI family

Sub-command	Purpose
cp run <workflow> [name] [--plan-only]	Start a new workflow run
cp run resume <slug>	Re-emit the current wave's instruction
cp run retry <slug> <phase-id>	Roll back a phase and re-emit
cp run abandon <slug> [--yes]	Mark a run abandoned
cp run mark-complete <slug> <phase-id>	Advance the run (summary read from stdin)
cp run status [slug] [--json]	List runs or show one's state

🧩 cp workflow CLI family

Sub-command	Purpose
cp workflow ls [--json]	List built-in + project templates
cp workflow show <name>	Pretty-print a template
cp workflow validate <name-or-path> [--strict]	Schema + DAG validation
cp workflow diagram <name-or-path>	Emit Mermaid flowchart TD
cp workflow init	Bootstrap .planning/workflows/
cp workflow new <name> [--from <built-in>] [--force]	Scaffold a new template
cp workflow import <path> [--name <override>] [--force]	Validate + copy external template
cp workflow brainstorm [--workflow <name>]	AI-author a new workflow via your provider's brainstorm skill

📦 Three built-in templates

• dev.yaml — 6-phase milestone-bound dev workflow with a parallel research wave (brainstorm → research-prior-art ∥ research-constraints → plan → execute → review).
• debug.yaml — 5-phase custom-bound scientific-method debug cycle (collect-symptoms → repro → plan → fix → verify).
• quick.yaml — 3-phase custom-bound minimal workflow (discuss → execute → verify).

Customize per project with cp workflow new <name> --from quick; project-local templates in .planning/workflows/ override built-ins of the same name.

🧠 AI authoring

cp workflow brainstorm --workflow my-flow delegates to your configured provider's brainstorm skill (Superpowers by default) for conversational YAML workflow design. Falls back to a printed manual prompt when no provider is installed.

📜 Top-level principles: field

Global directives applied across every phase of a workflow:

principles:
  - Don't commit until the user explicitly confirms
  - Run autonomously until you hit a blocking issue, then surface it
  - Run the full test suite after each change

cp prepends them to every wave instruction emitted, so the agent always has the workflow's ground rules in context — regardless of which phase is running.

Migration

No migration required. v1.0 is purely additive. All pre-1.0 commands and the milestone/phase model continue to work unchanged. See MIGRATION-v1.0.md for the full template format reference, state tier guide, and FAQ.

Quality

• 304 new test assertions across the workflow engine: 200 lib-tier (unit-workflow.js × 75, unit-custom.js × 58, integration-runtime.js × 67) + 104 CLI-tier (dryrun-run-cli.js × 31, dryrun-workflow-cli.js × 53, integration-run-cli.js × 20).
• 34 test files in the suite, all green, 0 failures.

Stats

• Milestone closed: v1.0 Workflow Engine — Phases 40–42 collapsed in ROADMAP.
• Commits since v0.10.3: 24.

Credits

Designed with Copilot CLI using cp's own milestone/phase workflow. Execution skill resolution via Superpowers.

v0.10.3 - Collapse-aware audit + status renderer (hotfix)

Fixed

• cp audit false-positive phase-no-roadmap MEDIUMs on collapsed milestones. Phases inside a <details><summary>Phases X-Y</summary> are now recognized as in-roadmap. New helper roadmap.listCollapsedPhaseNums().
• cp status suggested cp complete-milestone for already-shipped milestones. Now prints Milestone is shipped. Start the next one: cp new-milestone ... when milestoneStatus === 'shipped'.
• findMilestoneInRoadmap: Phases 14-16 returned [14,16] not [14,15,16]. Integer ranges now expand fully.

Upgrade

npx context-planning@latest update

v0.10.2 — Defensive verify + --force (hotfix)

Fixed

• TypeError crash in cp complete-milestone when verify report omitted summariesMissing for missing phases. Now always populates report fields; CLI defensively coalesces every field before rendering the diagnostic.
• cp complete-milestone blocked on shipped/collapsed milestones with no inner ### Phase blocks. When found.status === 'shipped', verify is skipped entirely — the collapsed state IS the source of truth. Digest append + STATE reset + cleanup still run.

Added

• cp complete-milestone --force bypasses the verify gate for manual close-out (e.g. summaries live outside cp's expected location). Audit gate still runs (use --no-audit to skip that too).

Upgrade

npx context-planning@latest update (in any cp project)

v0.10.1 — Collapse-aware milestone close (hotfix)

v0.10.1 — Collapse-aware milestone close (hotfix)

Fixed

• cp complete-milestone returned milestone-not-found when
  ROADMAP.md was already collapsed into
  <details><summary>✅ <name> ... SHIPPED <date></summary>...</details>.
  This pattern is produced by the Superpowers writing-plans skill on
  the final phase's C2 commit, by hand-collapses, and by prior
  cp complete-milestone runs.
• cp status was blind to collapsed milestones. statusReport now
  falls back to STATE.md's milestone: frontmatter when no
  ### (In Progress) heading exists.
• cp complete-milestone is now idempotent: a second call against an
  already-shipped milestone returns {ok: true, alreadyShipped: true}
  cleanly (exit 0). If the milestone is collapsed but the digest
  hasn't been appended, it finishes the remaining bookkeeping.

Upgrade

npx -y --package=context-planning@latest -- cp update

No breaking changes; safe in-place upgrade.

Full Changelog: v0.10.0...v0.10.1

v0.10.0 — Autonomy

v0.10.0 — Autonomy

Adds an autonomous milestone driver: walk all pending phases of the
active milestone without per-phase approval, smart-gated on test
failure, audit-HIGH findings, and executor deviation. Stops produce
.planning/.continue-here.md and prompt inline — the session is
never exited.

Added

• cp autonomous CLI verb. Flags: optional START positional
  (phase number, milestone name, or auto-detect from STATE.md),
  --scope=phase|N|N-M|milestone, --check (preview),
  --json, --quiet. Exit codes: 0 success / 1 stopped or
  check-found / 2 hard error.
• /cp-autonomous slash skill (outer orchestrator). Pre-flights
  via the CLI, then delegates /cp-plan-phase (if PLAN.md is a
  stub) and /cp-execute-phase (one plan per call) with per-plan
  smart gates. Auto-installed by all four harness installers.
• Smart-gate triggers: test-failure, audit-high,
  deviation, plan-failed — each writes a reason-specific
  .continue-here.md and prompts inline via ask_user.
• Milestone hard-cap: even --scope=50 clamps to the active
  milestone's last phase.
• 22 new unit assertions in test/unit-autonomous.js.

Upgrade

npx -y --package=context-planning@latest -- cp update

That refreshes the skill files (including the new
cp-autonomous skill) in your project.

Docs

• Design spec:
  https://github.com/shushenglihotmail/context-planning/blob/main/docs/superpowers/specs/2026-05-21-v0-10-cp-autonomous-design.md
• Milestone DESIGN:
  https://github.com/shushenglihotmail/context-planning/blob/main/.planning/milestones/v0-10-autonomy/DESIGN.md

Full Changelog: v0.9.0...v0.10.0

v0.9.0 - Onboarding

v0.9.0 — Onboarding

Closes the onboarding UX gaps surfaced during v0.8 ship-out. Every install path is now one command.

Added

• cp update — one-shot per-repo refresh (case-4 onboarding helper). Detects installed harness(es), re-runs cp install <harness> --force for each, merges new config defaults, and auto-cleans low/medium drift. Recommended invocation:

  npx -y --package=context-planning@latest -- cp update
  

  Mirrors GSD's /gsd-update pattern (no global npm install required).
• /cp-update slash-command skill installed by all four harness installers on next cp install.
• /cp-map-codebase auto-init. When invoked in a repo without .planning/, the skill now runs cp init first with a mandatory user-visible notice, then proceeds with mapping. Case-2 onboarding (existing code, no planning) becomes a single command.
• Onboarding decision matrix in README maps the 4 install scenarios (greenfield / existing code / existing GSD state / existing cp upgrade) to a single one-line command each.
• Milestone digest surfaces phase DESIGN.md + REVIEW-LOG.md. renderDigest now emits Phase designs: (one link per phase with a non-stub DESIGN.md) and Reviews: (total entry count + per-phase REVIEW-LOG.md links). Closes the v0.7 inbox #1 gap. Stub designs filtered out automatically.

Changed

• README "Updating an existing install" rewritten to lead with the npx one-liner; manual per-verb invocations demoted to alternatives.
• README "Initialise a project" section clarified — cp init is rarely needed directly (all four onboarding paths handle it).

Fixed

• cp scaffold-milestone now appends new milestone headings to the END of the ## Phases section (was prepending at the top, which caused cp complete-milestone to scoop ALL prior loose phase headings into the new milestone and emit Phases: 1-N digests instead of just the milestone's own range).

Install

npm install -g context-planning@latest
cp --version    # 0.9.x

Or upgrade an existing repo in-place:

npx -y --package=context-planning@latest -- cp update

v0.8.0 — Consistency milestone

[0.8.0] - 2026-05-21 — Consistency milestone

The "drift defense" release. Plan/state docs and the codebase drift
apart over time; v0.8 ships a complete prevent → detect → repair
stack so they stay in sync.

See docs/drift-playbook.md for the full
walkthrough including a migration guide for pre-v0.8 projects.

Added (v0.8 — Consistency milestone)

• Agent literacy injection (Phase 30): templates/agent-instructions.md
  ships a drift-defense literacy block (verb list + finding-id → verb
  table) automatically injected into the ambient instruction file of
  every harness installer (Copilot CLI, Claude Code, Cursor, Aider).
  Idempotent via <!-- cp:drift-defense v1 --> sentinels. New
  install/common.js helpers buildDriftDefenseBlock(pluginRoot) and
  stripDriftBlock(text) are exported for advanced installer authors.
• CI template + bulk reconcile (Phase 29):
  • cp install --ci writes .github/workflows/cp-audit.yml from
    templates/ci/cp-audit.yml.example (sentinel # cp:ci v1,
    fetch-depth: 0, runs cp audit --severity high on every PR).
  • cp reconcile --all / cp reconcile --phase <range> for bulk
    SHA backfill. Range accepts 5 shapes (5, 5-8, 5..8, 5,7,9,
    5,7-9). Composable with --infer-shas, --accept, --dry-run,
    --no-commit.
• Post-commit tick-auto (Phase 28): opt-in cp.behavior.post_commit = "tick-auto" — after each commit whose subject matches
  cp(NN-MM[-slug]): ... AND that touched ALL of the plan's
  expected-key-files, the post-commit hook auto-ticks the plan with
  a trailing cp: tick plan NN-MM commit. Off by default — it subtly
  mutates history. lib/lifecycle.tryAutoTick() is the pure decision
  helper.
• Pre-commit hook smart shim (Phase 27): new bin/cp-hook.js shim
  • lib/hooks.js installer. cp install --hooks / --uninstall-hooks.
    Smart-shim walks for .planning/STATE.md markers so monorepos with
    multiple cp projects work. Per-project dispatch via
    cp.behavior.pre_commit (off / audit-high (default) /
    audit-any). Sentinel # cp:hook v1 for safe ownership detection.
    Handles both regular .git dirs AND gitdir: file format (worktrees).
• Repair commands (Phase 26): four new verbs to fix drift detected
  by cp audit:
  • cp reconcile <N> — --infer-shas fills missing base-commit
    / end-commit in PLAN/SUMMARY by inferring from cp(NN-MM): commit
    log; --accept rewrites a plan's expected-key-files from actual
    SUMMARY key-files (destructive — overwrites the plan to match
    code). Atomic commit per change.
  • cp supersede <planId> --by <newPlanId> — replaces plan
    checkbox with [~] and appends a "Superseded by" note to PLAN.md.
  • cp deviate <N> --summary "<text>" — appends a dated
    ## Deviation YYYY-MM-DD block to phase PLAN.md.
  • cp scaffold-phase --continue — bypasses prior-summary gate
    (distinct from --force) and stamps a "Continues from phase N-1"
    note in the new PLAN.md.
  • lib/audit-fix.js FIXERS registry extended with reconcile-backed
    entries for missing-base-commit and missing-end-commit so
    cp audit --fix auto-applies them.
• cp audit --fix (Phase 25): classify findings into auto/manual/skip,
  apply auto-fixers with one atomic commit per fix. Flags --max N
  (default 5), --severity high|medium|all, --dry-run. Exit codes
  0 (clean) / 1 (any failed) / 2 (manual findings remain). Pluggable
  FIXERS registry — phase 26 appends reconcile-backed entries.
• complete-milestone audit gate (Phase 23): runs cp audit as
  a refuse-on-HIGH/MEDIUM gate before milestone close-out. --audit-warn
  downgrades MEDIUM to warning; --no-audit bypasses entirely (with
  mandatory stderr override notice). Fail-closed on audit error.
• cp audit (Phase 24): read-only consistency checker for .planning/.
  Nine built-in checks covering ticked-without-summary, summary-without-tick,
  base-commit/end-commit completeness, expected-vs-actual key-files drift,
  STATE.md staleness, and roadmap ↔ phase-dir alignment. Severity tiers
  (HIGH/MEDIUM/LOW), exit codes 0/1/2, flags --json --strict --milestone <name> --phase <N> --quiet. Read-only — --fix arrives in Phase 25.
• scaffold-phase prior-summary gate (Phase 22): refuses if the
  immediately preceding phase has ticked plans without SUMMARYs. --force
  override prints a mandatory stderr notice for audit transparency.
• write-summary expected-key-files check (Phase 21): warns when the
  files touched between base/end commits don't match what PLAN.md declared.
  --strict-expected upgrades to refusal, --no-expected-check opts out.
• Derived STATE.md (Phase 20): STATE.md current-position block is now
  regenerated from ROADMAP + git, with cp state regen to refresh.
• SHA pinning (Phase 17): every PLAN.md gets base-commit at scaffold;
  every SUMMARY.md gets end-commit at write. Foundation for drift
  detection.

Docs

• New docs/drift-playbook.md — the canonical walkthrough of the
  prevent/detect/repair stack, including 5-step migration recipe for
  pre-v0.8 projects and a finding-id → repair-verb lookup table.
• README: new "Drift defense (v0.8)" section with 4-layer overview
  table linking to the playbook.

v0.7.0 - Design Capture

v0.7.0 — Design Capture

Milestone goal: Close three persistence gaps surfaced after the v0.6 release retrospective so the cp ↔ SP integration captures the design rationale, review history, and key decisions that drive a milestone — not just the artifacts that fall out the end.

What's new

Persistent design rationale (milestone + phase tiers)

• cp scaffold-milestone now creates .planning/milestones/<slug>/DESIGN.md from the new templates/DESIGN.md (a union of ADR + SP-brainstorm sections).
• cp scaffold-phase now emits a phase-tier DESIGN.md alongside PLAN.md (4 actions total: ROADMAP + PLAN + DESIGN + REVIEW-LOG).
• The cp-plan-phase skill gained a new Step 3.5 that delegates to SP brainstorming with a path: override to populate the phase DESIGN.md before planning starts.
• cp complete-milestone promotes the transient MILESTONE-CONTEXT.md into the milestone DESIGN.md as a "Brainstorm transcript" appendix, then deletes the transient file atomically.

Persistent subagent review history

• New append-only REVIEW-LOG.md per phase. Marker-anchored entries.
• The cp-execute-phase skill gained a new Step 4.5 that instructs the orchestrator to append one block per SP review cycle (verdict, findings, resolution + commit SHA).
• aggregateSummaries(...) now returns reviewLogRefs[] (deduped per phase) and reviewCount (total entries).

Key-decisions hard-block

cp write-summary now exits code 2 with the exact message:

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 the input JSON is missing key-decisions or has an empty array. 33 existing v0.6 dogfood SUMMARYs were backfilled.

Library extensions

• New lib/paths helpers: designFile, milestoneSlug, milestoneDir, milestoneDesignFile, reviewLogFile.
• New lib/milestone.promoteMilestoneContext(root, milestoneName, options).
• New lib/milestone.ValidationError (name + code: 'EVALIDATION') thrown by writeSummary.
• Aggregator returns phaseDesignRefs[], reviewLogRefs[], reviewCount alongside existing fields.
• New test/unit-design.js (59 assertions, 8 sections).
• New templates/DESIGN.md and templates/REVIEW-LOG.md.
• New scripts/backfill-v07-design.js — mid-flight migration helper.

No upstream SP changes

All capture logic lives in cp templates, lib, and skill docs. SP brainstorming is invoked with a path: override; SP subagent-driven-development is unchanged — the REVIEW-LOG.md append is a skill-level orchestrator instruction.

Quality gates

• Tests: 20 test files, all Failed: 0.
• Coverage: 89.37% lines / 77.63% branches (≥85L / ≥75B thresholds held).

Migration

For existing cp projects upgrading to v0.7:

1. npm install -g context-planning@0.7.0
2. Existing milestones / phases do NOT get DESIGN.md retroactively. Copy scripts/backfill-v07-design.js to your project and adapt for in-flight work.
3. SUMMARY files with empty key-decisions: [] will be rejected by the next cp write-summary. Backfill them once: open each .planning/phases/**/NN-MM-SUMMARY.md, replace the empty array with ≥1 entry. Trivial mechanical plans can use: key-decisions: ['mechanical edits only — no design decisions'].
4. cp doctor continues to find SP via Copilot CLI marketplace (added v0.4.5) and Claude Code (legacy) installs.

Spec

docs/superpowers/specs/2026-05-20-v0-7-design-capture-design.md — full ADR with Alternatives Considered (A-E) and Open Questions deferred to v0.8.

Diff stats

20 commits in v0.7.0 milestone:

• spec(v0.7) — 1
• plan(v0.7) × 2 — plans 16-01 + (16-02 ∥ 16-03)
• cp(16-01) × 7 — DESIGN.md infrastructure
• cp(16-02) × 5 — REVIEW-LOG.md infrastructure
• cp(16-03) × 3 — key-decisions hard-block
• release: v0.7.0 — version bump + CHANGELOG

Co-author

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

v0.6.0 - Quality Wave

v0.6.0 — Quality Wave

Production-hardening pass: break up the monolithic bin/cp.js, ship a cplan alias to dodge PowerShell's built-in cp, add multi-OS CI, and gate on coverage.

Added

• cplan binary alias. npm install -g context-planning now creates both cp and cplan shims. PowerShell users hit by the built-in cp → Copy-Item alias can invoke cplan instead. Help text, cp doctor banner, and CLI usage all note the dual name.
• bin/commands/<name>.js module layout. Every command is now a standalone module exporting { name, run(args) }. New registry (bin/commands/index.js) is the single source of truth — 18 entries. bin/cp.js is a 47-LOC thin dispatcher (down from 1218 LOC).
• GitHub Actions CI. Matrix { ubuntu-latest, windows-latest } × { node 20, node 22 }. README gets a ci badge.
• c8 coverage with threshold gate. npm run coverage (HTML+text, local) and npm run coverage:ci (lcov + json-summary + --check-coverage --lines 85 --branches 75). Dedicated CI job after the matrix; uploads coverage-report artifact (14-day retention). Current actual: 88.7% lines / 78.2% branches.

Fixed

• Windows CI worktree-path comparison. cp worktree list compared registry path vs git output via path.resolve(). Windows Actions runners expose temp paths via 8.3 short names (RUNNER~1) so registry stored short form while git returned long form — lookup always missed. New canonical() wraps fs.realpathSync.native; samePath() lowercases on win32.
• Cross-platform unit-statusline.js. Dropped a shell: 'cmd.exe' + 2>NUL invocation that ENOENT'd on Ubuntu.

Notes for users

• No breaking changes; all 19 test suites pass on Ubuntu+Windows × Node 20+22.
• Upgrade: npm install -g context-planning@latest then re-run cp install <harness> to get the new shim and updated skill stubs.

v0.5.0 — Generic provider/harness detection

v0.5.0 — Generic provider / harness detection

Restructures provider detection from hardcoded sentinel matching to a data-driven harnesses x providers cross-product.

Highlights

• Harnesses block in config — 4 harnesses (copilot, claude, cursor, aider) with plugin_roots using trailing-* glob
• plugin_shape on each provider — dir_name + required_subdirs for structured detection
• lib/detect.js (~250 LOC) — new zero-deps detection engine with tilde + trailing-* expansion
• lib/merge.js (~150 LOC) — additive config merge; brownfield projects auto-heal on first load
• cp config refresh [--dry-run] — explicit re-sync of local config with upstream defaults
• cp doctor rewrite — sectioned output + --json / --quiet flags
• echo-provider schema-test stub — proves the schema works with more than Superpowers
• 726 assertions across 19 test files (up from 592)

See MIGRATION-v0.5.md and CHANGELOG.md for full details.