context-planning 0.7.0

package/templates/STATE.md

@@ -0,0 +1,78 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated {{DATE}})
+
+**Core value:** {{CORE_VALUE}}
+**Current focus:** {{CURRENT_PHASE_NAME}}
+
+## Current Position
+
+Phase: {{PHASE_NUM}} of {{TOTAL_PHASES}} ({{CURRENT_PHASE_NAME}})
+Plan: {{PLAN_NUM}} of {{TOTAL_PLANS_IN_PHASE}} in current phase
+Status: {{STATUS}}
+Last activity: {{DATE}} — {{LAST_ACTIVITY}}
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: -
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| -     | -     | -     | -        |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*Updated after each plan completion.*
+
+## Accumulated Context
+
+### Decisions
+
+<!-- Recent decisions; full log in PROJECT.md "Key Decisions". -->
+
+(none yet)
+
+### Pending Todos
+
+<!-- Captured during sessions (e.g., via /cp-capture in a future release). -->
+
+(none yet)
+
+### Blockers / Concerns
+
+<!-- Issues that affect future work. -->
+
+(none yet)
+
+## Deferred Items
+
+Items acknowledged and carried forward from previous milestone close:
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* |      |        |             |
+
+## Quick Tasks Completed
+
+<!-- Appended by /cp-quick on completion. GSD-compatible table. -->
+
+| Date | Slug | One-liner |
+|------|------|-----------|
+| *(none yet)* | | |
+
+## Session Continuity
+
+Last session: {{DATE}}
+Stopped at: {{LAST_ACTIVITY}}
+Resume file: {{CONTINUE_HERE_PATH_OR_NONE}}

package/templates/SUMMARY.md

@@ -0,0 +1,75 @@
+---
+phase: {{PHASE_DIR}}
+plan: {{PLAN_NUM_PADDED}}
+subsystem: {{SUBSYSTEM}}
+tags: []
+
+# Dependency graph
+requires: []
+provides: []
+affects: []
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: []
+
+key-files:
+  created: []
+  modified: []
+
+key-decisions: []
+patterns-established: []
+
+requirements-completed: []
+
+# Metrics
+duration: {{DURATION_MIN}}min
+completed: {{COMPLETED_DATE}}
+---
+
+# Phase {{PHASE_NUM}}: {{PHASE_NAME}} Summary
+
+**{{ONE_LINER}}**
+
+## Performance
+
+- **Duration:** {{DURATION_HUMAN}}
+- **Started:** {{STARTED_ISO}}
+- **Completed:** {{COMPLETED_ISO}}
+- **Tasks:** {{TASKS_COUNT}}
+- **Files modified:** {{FILES_COUNT}}
+
+## Accomplishments
+
+<!-- 2-4 bullets — substantive outcomes, NOT "phase complete". -->
+
+## Task Commits
+
+<!-- One line per task; atomic commit hashes. -->
+
+## Files Created / Modified
+
+<!-- `path/to/file.ext` — what it does -->
+
+## Decisions Made
+
+<!-- Key decisions with brief rationale, or "None — followed plan as written". -->
+
+## Deviations from Plan
+
+<!-- "None — plan executed exactly as written" OR list of auto-fixes. -->
+
+## Issues Encountered
+
+<!-- Problems during planned work and how they were resolved, or "None". -->
+
+## Next Phase Readiness
+
+<!-- What's ready, any blockers/concerns to surface in STATE.md. -->
+
+---
+*Phase: {{PHASE_DIR}}*
+*Plan: {{PLAN_NUM_PADDED}}*
+*Provider: {{PROVIDER}} ({{EXECUTE_SKILL}})*
+*Completed: {{COMPLETED_DATE}}*

package/templates/codebase/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# Architecture
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (arch focus).
+
+High-level system shape. The "how the pieces fit" reference loaded by
+`/cp-plan-phase` for backend/API/data work.
+
+## Architectural style
+
+<!-- e.g. layered, hexagonal, MVC, plugin/host, event-driven. One short paragraph. -->
+
+## Module boundaries
+
+<!-- List the top-level modules and what each owns. Cite directory paths. -->
+
+## Data flow
+
+<!-- Trace one canonical request/event end-to-end through the modules. File paths at each hop. -->
+
+## Key design patterns
+
+<!-- Patterns the codebase actively uses (Repository, Factory, Strategy, …) with file refs. -->
+
+## Cross-cutting concerns
+
+<!-- Logging, auth, caching, config, error handling — where each is implemented. -->
+
+## Boundaries the executor must respect
+
+<!-- "Never import X from Y." "All HTTP goes through `src/http/`." Prescriptive rules. -->

package/templates/codebase/CONCERNS.md

@@ -0,0 +1,30 @@
+# Known Concerns
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (concerns focus).
+
+Tech debt, fragility, and pitfalls the executor should be aware of. Drives
+refactor / cleanup phases. Be specific — vague concerns are not actionable.
+
+## Critical
+
+<!-- Anything that could cause data loss, security issues, or production outages. Include impact + fix approach. -->
+
+## High
+
+<!-- Real bugs or fragility with clear impact. File path + line range + symptom. -->
+
+## Medium
+
+<!-- Refactor candidates, code smells, missing tests in important areas. -->
+
+## Low
+
+<!-- Cosmetic, minor inconsistencies, things to clean up opportunistically. -->
+
+## Workarounds & gotchas
+
+<!-- "If you change X, also update Y." "This looks unused but is called via reflection." -->
+
+## Areas that look safe to touch
+
+<!-- Sections with good test coverage and clear boundaries — explicitly safe for the executor. -->

package/templates/codebase/CONVENTIONS.md

@@ -0,0 +1,30 @@
+# Code Conventions
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (quality focus).
+
+Prescriptive rules — written so the executor can apply them without
+re-reading the rest of the codebase.
+
+## Naming
+
+<!-- Functions, variables, types/classes, constants, files. One bullet per rule. -->
+
+## Import / export style
+
+<!-- ESM vs CJS, default vs named, ordering, path aliases. Cite an example file. -->
+
+## Error handling
+
+<!-- Throw vs Result<T,E>, custom error classes, where errors are caught/logged. -->
+
+## Logging
+
+<!-- Logger choice, levels, format, where the logger is initialised. -->
+
+## Comments & docs
+
+<!-- When comments are warranted, JSDoc/TSDoc style, README expectations. -->
+
+## Formatting & linting
+
+<!-- Formatter (prettier/biome/black), lint config path, command to run, auto-fix command. -->

package/templates/codebase/INTEGRATIONS.md

@@ -0,0 +1,30 @@
+# External Integrations
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (tech focus).
+
+Inventory every external system this codebase talks to. Used by phases that
+touch I/O boundaries.
+
+## APIs called
+
+<!-- For each: endpoint base URL, auth mechanism, calling file path. -->
+
+## Databases / data stores
+
+<!-- Engine + version, schema location, connection-config file path, migration tool. -->
+
+## Message queues / pub-sub
+
+<!-- Broker, topic/queue names, producer & consumer file paths. -->
+
+## Auth providers
+
+<!-- OAuth/OIDC/JWT/sessions. Token storage strategy. -->
+
+## CI/CD & deployment
+
+<!-- Pipeline files (`.github/workflows/*.yml`, etc.), target environments, deploy command. -->
+
+## Secrets & config
+
+<!-- Where env vars are loaded (file paths), what is required vs optional. NEVER paste secret values. -->

package/templates/codebase/STACK.md

@@ -0,0 +1,26 @@
+# Tech Stack
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (tech focus).
+
+Reference for `/cp-plan-phase` and `/cp-execute-phase` so they don't re-discover
+languages, frameworks, or versions every turn.
+
+## Languages & Runtimes
+
+<!-- e.g. Node.js 20.x, TypeScript 5.4, Python 3.11. Cite version source (package.json/pyproject.toml). -->
+
+## Frameworks
+
+<!-- Web/UI/backend frameworks with versions and entry-point file paths. -->
+
+## Dependencies (production)
+
+<!-- Top ~10 by importance, NOT the full lockfile. Include purpose: "lodash — utility helpers in `src/util/`". -->
+
+## Dependencies (dev tooling)
+
+<!-- Build, test, lint, format. Include the npm/script command that drives each. -->
+
+## Package manager & lockfile
+
+<!-- npm/pnpm/yarn/uv/poetry. Lockfile path. Install command. -->

package/templates/codebase/STRUCTURE.md

@@ -0,0 +1,32 @@
+# Folder Structure
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (arch focus).
+
+Answers "where does this new file go?" for `/cp-execute-phase`.
+
+## Top-level layout
+
+<!-- Annotated tree of top-level directories with one-line purpose for each. -->
+
+```
+.
+├── bin/        ← CLI entry points
+├── lib/        ← runtime modules (no I/O)
+├── …
+```
+
+## Folder responsibilities
+
+<!-- Per directory: what belongs here, what does NOT, naming pattern for files. -->
+
+## Where do I put a NEW …
+
+<!-- New CLI subcommand → … ; new HTTP route → … ; new test → … ; new migration → … -->
+
+## Filename conventions
+
+<!-- kebab-case vs camelCase, suffixes (`.test.ts`, `.spec.js`, etc.). -->
+
+## Generated / vendored / ignored
+
+<!-- Paths the executor must never edit by hand. Include why. -->

package/templates/codebase/TESTING.md

@@ -0,0 +1,39 @@
+# Testing
+
+Generated: {{DATE}} — fill via `/cp-map-codebase` (quality focus).
+
+The reference `/cp-plan-phase` loads for any test-related work and that
+`/cp-execute-phase` reads before writing tests.
+
+## Test framework & runner
+
+<!-- vitest/jest/pytest/etc. Version. Command to run all tests. Command to run one file. -->
+
+## Test file layout
+
+<!-- Co-located vs `test/` mirror. Naming pattern (`*.test.ts`, `test_*.py`). -->
+
+## Test naming & structure
+
+<!-- describe/it vs flat. AAA pattern. Example from the codebase. -->
+
+## Fixtures & mocks
+
+<!-- Where fixtures live, how mocks are wired, http mocking strategy. -->
+
+## What is covered vs not
+
+<!-- Honest picture: unit ✓, integration partial, e2e none, etc. Cite which folders are well-covered. -->
+
+## How to run
+
+```
+# all tests
+…
+
+# single file
+…
+
+# coverage
+…
+```

package/templates/config.json

@@ -0,0 +1,173 @@
+{
+  "mode": "interactive",
+  "granularity": "standard",
+  "workflow": {
+    "research": false,
+    "plan_check": false,
+    "verifier": false,
+    "auto_advance": false,
+    "nyquist_validation": false,
+    "security_enforcement": false,
+    "discuss_mode": "discuss",
+    "research_before_questions": false,
+    "code_review_command": null,
+    "plan_bounce": false,
+    "plan_bounce_passes": 2,
+    "cross_ai_execution": false,
+    "cross_ai_command": "",
+    "cross_ai_timeout": 300
+  },
+  "ship": {
+    "pr_body_sections": []
+  },
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false,
+    "sub_repos": []
+  },
+  "git": {
+    "create_tag": false
+  },
+  "parallelization": {
+    "enabled": true,
+    "plan_level": true,
+    "task_level": false,
+    "skip_checkpoints": true,
+    "max_concurrent_agents": 3,
+    "min_plans_for_parallel": 2
+  },
+  "gates": {
+    "confirm_project": true,
+    "confirm_phases": true,
+    "confirm_roadmap": true,
+    "confirm_breakdown": true,
+    "confirm_plan": true,
+    "execute_next_plan": true,
+    "issues_review": true,
+    "confirm_transition": true
+  },
+  "safety": {
+    "always_confirm_destructive": true,
+    "always_confirm_external_services": true
+  },
+  "hooks": {
+    "context_warnings": true
+  },
+  "project_code": null,
+  "agent_skills": {},
+  "claude_md_path": "./CLAUDE.md",
+
+  "cp": {
+    "$comment": "context-planning settings. GSD ignores unknown top-level keys, so both tools can coexist.",
+    "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": {
+        "description": "Jesse Vincent's Superpowers plugin (https://github.com/obra/superpowers)",
+        "plugin_shape": {
+          "dir_name": "superpowers",
+          "required_subdirs": ["skills/writing-plans", "skills/subagent-driven-development"]
+        },
+        "detect": {
+          "any_of": [
+            ".claude/plugins/superpowers",
+            ".claude/skills/superpowers",
+            ".github/skills/brainstorming",
+            ".github/skills/writing-plans",
+            ".github/skills/subagent-driven-development",
+            "installed-plugins/superpowers-marketplace/superpowers",
+            "installed-plugins/superpowers-marketplace/superpowers/skills/writing-plans",
+            "installed-plugins/superpowers-marketplace/superpowers/skills/subagent-driven-development"
+          ]
+        },
+        "skills": {
+          "brainstorm": "brainstorming",
+          "plan": "writing-plans",
+          "execute": "subagent-driven-development",
+          "execute_simple": "executing-plans",
+          "review": "requesting-code-review",
+          "receive_review": "receiving-code-review",
+          "finish": "finishing-a-development-branch",
+          "worktree": "using-git-worktrees",
+          "tdd": "test-driven-development",
+          "debug": "systematic-debugging",
+          "verify": "verification-before-completion"
+        }
+      },
+      "echo-provider": {
+        "description": "Schema-test stub. Echoes the role name. Not for end users.",
+        "plugin_shape": { "dir_name": "echo-provider", "required_subdirs": [] },
+        "detect": { "any_of": [".planning/providers/echo-provider"] },
+        "skills": {
+          "brainstorm": "echo",
+          "plan": "echo",
+          "execute": "echo",
+          "execute_simple": "echo",
+          "review": "echo",
+          "receive_review": "echo",
+          "finish": "echo",
+          "worktree": "echo",
+          "tdd": "echo",
+          "debug": "echo",
+          "verify": "echo"
+        }
+      },
+      "manual": {
+        "description": "Inline fallback. cp emits step-by-step instructions instead of delegating to an external skill. Use this when no other workflow provider is installed.",
+        "detect": { "always": true },
+        "skills": {
+          "brainstorm": "cp:manual/brainstorm",
+          "plan": "cp:manual/plan",
+          "execute": "cp:manual/execute",
+          "execute_simple": "cp:manual/execute",
+          "review": "cp:manual/review",
+          "receive_review": "cp:manual/receive_review",
+          "finish": "cp:manual/finish",
+          "worktree": "cp:manual/worktree",
+          "tdd": "cp:manual/tdd",
+          "debug": "cp:manual/debug",
+          "verify": "cp:manual/verify"
+        },
+        "prompts": {
+          "brainstorm": "You are running the cp MANUAL brainstorm fallback. Have a back-and-forth conversation with the user to refine the idea: (1) ask ONE clarifying question at a time about goals, constraints, users, success criteria; (2) reflect what you heard before each next question; (3) when the picture feels concrete, write the result to the file the calling cp command nominated (typically .planning/MILESTONE-CONTEXT.md or .planning/PROJECT.md). Do not start coding. Do not edit ROADMAP.md or STATE.md — the cp command owns those.",
+          "plan": "You are running the cp MANUAL plan fallback. Read the upstream context the calling cp command pointed you at (MILESTONE-CONTEXT.md, prior SUMMARY.md files, the relevant section of REQUIREMENTS.md if present). Produce a PLAN.md using the template at templates/PLAN.md: GSD-shape frontmatter (phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves) plus a body that lists discrete <task> blocks. Each <task> needs a one-line goal, the files it touches, and a <verify> command that proves it. Stop after writing PLAN.md — execution is a separate role.",
+          "execute": "You are running the cp MANUAL execute fallback. Open PLAN.md and walk it task-by-task. For each <task>: (1) make the smallest change that satisfies the goal; (2) run the <verify> command and report the result; (3) if it passes, mark the task done and commit (one task = one commit, message format: 'cp: {phase}-{plan} — {task name}'); (4) if it fails, stop and ask the user before continuing. After the final task, write SUMMARY.md (template at templates/SUMMARY.md) capturing subsystems/tags/requires/provides/affects/tech-stack/key-files/key-decisions/patterns-established/requirements-completed/duration. Do not tick ROADMAP.md or update STATE.md — the cp execute-phase command does that.",
+          "review": "You are running the cp MANUAL review fallback. Read the diff for the last phase commit range. Produce a short review covering: (a) bugs or regressions; (b) deviations from PLAN.md's must_haves; (c) untested edge cases; (d) anything that would surprise a future maintainer. Be specific (file + line). Do not modify code. Output a short markdown report.",
+          "receive_review": "You are running the cp MANUAL receive-review fallback. For each review finding, decide: fix now, defer (add to todos/), or reject (with rationale). Apply fixes as small atomic commits. Re-run the relevant <verify> commands after each fix.",
+          "finish": "You are running the cp MANUAL finish fallback. Stage the integration of the work just completed. Steps: (1) confirm all PLAN.md <verify> commands still pass; (2) confirm SUMMARY.md is written and ROADMAP.md tick is recorded by cp; (3) print the commit range and a short \"what shipped\" digest; (4) suggest a PR title and body if the project uses PRs; (5) STOP — do not open the PR or push branches without explicit user confirmation.",
+          "worktree": "You are running the cp MANUAL worktree fallback. If git is initialised, propose `git worktree add ../<repo>-<phase-slug> <branch>` to isolate this phase's work. Print the exact command. Do not execute it without user confirmation.",
+          "tdd": "You are running the cp MANUAL TDD fallback. For each behaviour you're about to implement: (1) write the test first and run it (it must FAIL — confirm the failure mode is the one you expected); (2) write the smallest code that makes it pass; (3) run the full local test suite to confirm no regressions; (4) commit (test + impl together is fine). Never skip step 1.",
+          "debug": "You are running the cp MANUAL debug fallback. Use the scientific method: (1) state the observed symptom precisely; (2) state your current hypothesis; (3) design a single experiment that would discriminate the hypothesis from one alternative; (4) run it and report the result; (5) update the hypothesis and repeat. Do not propose a fix until at least one experiment has narrowed the cause.",
+          "verify": "You are running the cp MANUAL verify fallback. For the claim 'X is done', enumerate every <verify> command in the relevant PLAN.md and run each. Report PASS/FAIL with the actual output (not just exit code). If anything is FAIL, do not declare the work complete."
+        }
+      }
+    },
+    "behavior": {
+      "atomic_commits": true,
+      "fall_back_to_manual_if_provider_missing": true,
+      "auto_update_state_after_phase": true,
+      "auto_tick_roadmap_after_phase": true,
+      "gsd_compat_mode": true
+    }
+  }
+}

package/templates/phase-PLAN.md

@@ -0,0 +1,32 @@
+---
+phase: "{{PHASE_NUM}}"
+name: {{PHASE_NAME}}
+milestone: {{MILESTONE_NAME}}
+status: in-progress
+created: {{DATE}}
+---
+
+# Phase {{PHASE_NUM}}: {{PHASE_NAME}}
+
+**Milestone**: {{MILESTONE_NAME}}
+**Created**: {{DATE}}
+
+## Goal
+
+{Describe what this phase delivers in 1-2 sentences.}
+
+## Success Criteria
+
+<!-- Observable from the user's perspective. -->
+1. {behavior 1}
+2. {behavior 2}
+
+## Plans
+
+<!-- Each plan is a 1-3 hour atomic unit. Toggle with `cp tick {NN-MM}`. -->
+
+{{PLANS_LIST}}
+
+## Notes
+
+<!-- Free-form during phase execution. -->

package/templates/quick-PLAN.md

@@ -0,0 +1,24 @@
+---
+slug: {{SLUG}}
+type: quick
+status: in-progress
+created: {{DATE}}
+---
+
+# Quick Task: {{TITLE}}
+
+## Description
+
+{{DESCRIPTION}}
+
+## Approach
+
+<!-- Filled in by provider's plan skill (or inlined manually). -->
+
+## Tasks
+
+- [ ] {short, file-scoped task with verification}
+
+## Done When
+
+<!-- Clear, observable success condition. -->

package/templates/quick-SUMMARY.md

@@ -0,0 +1,25 @@
+---
+slug: {{SLUG}}
+type: quick
+status: complete
+created: {{CREATED}}
+completed: {{COMPLETED}}
+duration_minutes: {{DURATION_MIN}}
+provider: {{PROVIDER}}
+---
+
+# Quick Task: {{TITLE}}
+
+**{{ONE_LINER}}**
+
+## What Changed
+
+- `{path}` — {what}
+
+## Commits
+
+- `{hash}` — {message}
+
+## Notes
+
+<!-- Anything worth remembering for future sessions. -->