@claude-pw/framework 0.9.1 → 0.11.0

package/RELEASES.md

@@ -2,6 +2,27 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [0.11.0] - 2026-03-15
+
+### Changed
+- Plan completion is now a clean cycle: last phase → auto-delegates to `/cpw-cleanup --complete`
+- `/cpw-cleanup --complete` mode: generates plan summary, reviews docs, archives ALL phases, resets execution state, deletes STATUS.md
+- `/cpw-startup` new cycle detection simplified: PLAN.md + config.json exist, STATUS.md absent
+- `/cpw-next-step` slimmed down — completion logic moved to cleanup (net -110 lines)
+- Workflow is now fully cyclical: startup → next-step (loop) → cleanup --complete → startup
+
+## [0.10.0] - 2026-03-15
+
+### Added
+- Plan completion lifecycle: summary generation (plan-summary.md), docs evolution review, DONE state in STATUS.md
+- Robust new cycle detection in `/cpw-startup`: 3 signals (STATUS.md DONE, PLAN.md all-done, PLAN.md all-archived)
+- Context loading before new cycle interview: loads architecture, interfaces, decisions, prior summary
+- Plan summary preserved across cycles (renamed to plan-summary-[date].md)
+
+### Fixed
+- `/cpw-next-step` no longer creates dead-end STATUS.md pointing to non-existent phase after last phase completes
+- `/cpw-cleanup` edge cases: empty results after filtering, commit skip when only .planning/ modified, dynamic commit messages
+
 ## [0.9.0] - 2026-03-15
 
 ### Added

package/install.js

@@ -547,6 +547,7 @@ async function main() {
   copyIfMissing(path.join(templatesDir, 'planning', 'learnings', 'queue.md'), path.join('.planning', 'learnings', 'queue.md'));
   copyIfMissing(path.join(templatesDir, 'planning', 'learnings', 'applied.md'), path.join('.planning', 'learnings', 'applied.md'));
   copyIfMissing(path.join(templatesDir, 'planning', 'config.json'), path.join('.planning', 'config.json'));
+  copyIfMissing(path.join(templatesDir, 'planning', 'plan-summary.md'), path.join('.planning', 'plan-summary.md'));
 
   // Root files with template variable substitution
   const vars = { PROJECT_NAME: projectName, DATE: date };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-pw/framework",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Structured Project Workflow for Claude Code — adaptive pipeline, context management, quality gates",
   "bin": {
     "claude-pw": "./install.js"

package/templates/claude/commands/cpw-cleanup.md

@@ -5,8 +5,123 @@ description: "Archive completed phases and clean accumulated state"
 ## Arguments
 - No arguments: dry-run (show what would be cleaned, ask for confirmation)
 - `--execute`: skip confirmation, execute immediately
+- `--complete`: full plan completion cycle (summary, docs review, archive ALL, reset state). Auto-triggered by `/cpw-next-step` when the last phase completes. Can also be run manually.
 
-## 0. Load state
+---
+
+## --complete mode (plan completion cycle)
+
+If `--complete` is passed, execute the full completion cycle. This mode is designed to
+close a finished plan, archive everything, and leave the project ready for `/cpw-startup`.
+
+### 1. Plan completion summary
+Generate `.planning/plan-summary.md`:
+- Read all phase sub-plans (plans/phase-N.md for each phase in PLAN.md)
+- Read plans/decisions.md
+- For each phase, extract: name, step count, Objective line
+- From decisions.md, extract decisions made during these phases
+- Get date range from git: first plan commit and today
+
+Write `.planning/plan-summary.md`:
+```markdown
+# Plan Summary
+
+## Completed
+- **Date**: [today]
+- **Phases**: [N]
+- **Steps**: [total across all phases]
+
+## Phases
+| # | Phase | Steps | Key output |
+|---|-------|-------|------------|
+| 0 | Stack and Scaffolding | 6 | Project setup, toolchain, CI |
+| 1 | Interfaces | 5 | Module contracts, type system |
+| ... | ... | ... | ... |
+
+## Key decisions
+- Phase N: [decision summary from decisions.md]
+- ...
+
+## Key deliverables
+- [extracted from each phase's Objective]
+- ...
+```
+
+If a previous `.planning/plan-summary.md` exists (from a prior cycle), rename it
+to `.planning/plan-summary-[date].md` before writing the new one.
+
+### 2. Docs evolution review
+Review if docs/ need updating after the full plan:
+- Read `docs/architecture.md` — does it reflect what was actually built?
+  Compare with the plan phases and deliverables. If outdated, update it.
+- Read `docs/interfaces.md` — are interfaces current with the final state of `src/interfaces/`?
+  If outdated, update it.
+- If any docs were updated:
+  `make commit m="docs: update architecture and interfaces after plan completion"`
+
+This is a lightweight pass to catch drift — not a full rewrite.
+
+### 3. Archive ALL phase files
+```bash
+mkdir -p .planning/archive
+```
+For every phase in PLAN.md (regardless of `archiveCompletedPhases` config — in --complete mode, everything gets archived):
+- Move `plans/phase-N.md` to `.planning/archive/phase-N.md`
+- Move `plans/phase-N-context.md` to `.planning/archive/phase-N-context.md` (if exists)
+
+Update PLAN.md: sub-plan column → `(archived)` for all phases.
+
+### 4. Reset execution state
+Clean all execution artifacts. These served the current plan cycle and are not needed for the next:
+- **Delete** `STATUS.md` (session pointer — no longer needed)
+- **Reset** `.planning/quick/log.md` to empty table header only
+- **Delete** all files in `.planning/debug/resolved/`
+- **Delete** `.planning/debug/active-session.md` (if exists)
+- **Reset** `.planning/learnings/queue.md` to empty
+- **Reset** `.planning/learnings/applied.md` to empty (already applied to rules/skills)
+- **Delete** `.planning/handoff.md` (if exists)
+- **Delete** `.planning/uat.md` (if exists)
+
+Do NOT touch (project context that survives between cycles):
+- `plans/decisions.md` — cumulative project history
+- `docs/*` — project documentation (just reviewed in step 2)
+- `.planning/config.json` — workflow settings carry over
+- `.planning/plan-summary.md` — just generated in step 1
+- `PLAN.md` — updated with (archived) markers
+- `CLAUDE.md` — project instructions
+- `.claude/skills/*` — extracted knowledge
+- `.claude/rules/*` — project rules
+- All source code, tests, Makefile, etc.
+
+### 5. Commit
+`make commit m="chore: plan complete — archived [N] phases, reset execution state"`
+
+### 6. Report
+```
+══════════════════════════════════════
+PLAN COMPLETE
+══════════════════════════════════════
+All [N] phases finished.
+Summary: .planning/plan-summary.md
+
+Archived: [N] phase files → .planning/archive/
+Cleaned: STATUS.md, quick log, debug sessions, learnings
+
+Project is ready for the next development cycle.
+Run /cpw-startup to begin.
+══════════════════════════════════════
+```
+
+STOP.
+
+---
+
+## Standard mode (mid-plan cleanup)
+
+If `--complete` is NOT passed, run the standard cleanup flow below.
+This is for archiving completed phases while the plan is still in progress.
+
+### 0. Load state
 
 Read `.planning/config.json` -> extract `cleanupPolicy` (use defaults if missing):
 - `archiveCompletedPhases`: true
@@ -23,9 +138,9 @@ Nothing to clean up. All phases are current or pending.
 ```
 STOP.
 
-## 1. Identify what to clean
+### 1. Identify what to clean
 
-### 1.1 Completed phase files
+#### 1.1 Completed phase files
 If `archiveCompletedPhases` is true:
 For each phase with Status "done" in PLAN.md:
 - Check if `plans/phase-N.md` still exists (not already archived)
@@ -33,26 +148,26 @@ For each phase with Status "done" in PLAN.md:
 - Add to archive list
 - NEVER archive the current phase or pending phases
 
-### 1.2 Quick log done entries
+#### 1.2 Quick log done entries
 Read `.planning/quick/log.md` (if exists):
 - Count entries with Status: done or dismissed
 - If count > `keepQuickLogDone`: mark oldest excess entries for removal
 
-### 1.3 Resolved debug sessions
+#### 1.3 Resolved debug sessions
 List `.planning/debug/resolved/` (if exists):
 - Count files
 - If count > `keepResolvedDebug`: mark oldest files for deletion (by filename date prefix)
 
-### 1.4 Applied learnings
+#### 1.4 Applied learnings
 Read `.planning/learnings/applied.md` (if exists):
 - Count entries (each entry starts with `---`)
 - If count > `keepAppliedLearnings`: mark oldest excess entries for trimming
 
-### 1.5 Stale files
+#### 1.5 Stale files
 - `.planning/handoff.md` — if it exists AND STATUS.md does NOT show a handoff in progress
 - `.planning/uat.md` — if it exists AND all phases it references are done (no active UAT)
 
-## 2. Present cleanup plan
+### 2. Present cleanup plan
 
 ```
 Cleanup Summary:
@@ -87,9 +202,9 @@ STOP.
 If `--execute`: show the summary and proceed to step 3.
 Otherwise: ask "Proceed? (yes/no)". If no: STOP.
 
-## 3. Execute
+### 3. Execute
 
-### 3.1 Archive phase files
+#### 3.1 Archive phase files
 ```bash
 mkdir -p .planning/archive
 ```
@@ -97,7 +212,7 @@ For each phase in the archive list:
 - Move `plans/phase-N.md` to `.planning/archive/phase-N.md`
 - Move `plans/phase-N-context.md` to `.planning/archive/phase-N-context.md` (if exists)
 
-### 3.2 Update PLAN.md
+#### 3.2 Update PLAN.md
 For each archived phase, change the sub-plan column from `plans/phase-N.md` to `(archived)`:
 ```
 | 0 | Stack and Scaffolding | plans/phase-0.md | done |
@@ -107,22 +222,22 @@ becomes:
 | 0 | Stack and Scaffolding | (archived) | done |
 ```
 
-### 3.3 Trim quick log
+#### 3.3 Trim quick log
 Remove done/dismissed entries beyond the keep limit from `.planning/quick/log.md`.
 Keep the most recent N entries (by date). Preserve the table header.
 
-### 3.4 Delete old debug sessions
+#### 3.4 Delete old debug sessions
 Delete files from `.planning/debug/resolved/` beyond the keep limit.
 Delete the oldest by filename date prefix.
 
-### 3.5 Trim applied learnings
+#### 3.5 Trim applied learnings
 Remove the oldest entries from `.planning/learnings/applied.md` beyond the keep limit.
 Keep the most recent N entries. Each entry is delimited by `---`.
 
-### 3.6 Delete stale files
+#### 3.6 Delete stale files
 Delete identified stale files (handoff.md, uat.md).
 
-### 3.7 Commit
+#### 3.7 Commit
 Read `commitPlanning` from `.planning/config.json`.
 
 Build commit message based on what was actually executed:
@@ -139,7 +254,7 @@ Check if there are staged changes (`git diff --cached --quiet`).
 - If there are changes: `make commit m="[built message]"`
 - If there are NO changes (e.g., only .planning/ was modified and commitPlanning is false): skip commit. Report: "Only local state cleaned (.planning/ is gitignored) — no commit needed."
 
-## 4. Report
+### 4. Report
 
 ```
 Cleanup complete.

package/templates/claude/commands/cpw-next-step.md

@@ -43,13 +43,22 @@ Delegate to the session-recovery agent in CHECK mode:
 ## 1. Load context
 
 If STATUS.md does not exist:
-- Report:
-  ```
-  No STATUS.md found — this project hasn't been initialized yet.
-
-  Next: run `/cpw-startup` to set up the project.
-  ```
-- STOP. Do not continue.
+- If PLAN.md exists AND `.planning/config.json` exists:
+  - This project completed a plan cycle. Report:
+    ```
+    Plan completed — project is ready for the next development cycle.
+
+    Next: run `/cpw-startup` to start a new cycle.
+    ```
+  - STOP.
+- Otherwise:
+  - Report:
+    ```
+    No STATUS.md found — this project hasn't been initialized yet.
+
+    Next: run `/cpw-startup` to set up the project.
+    ```
+  - STOP.
 
 - Read STATUS.md -> phase, step, stage
 - Read indicated sub-plan (plans/phase-N.md)
@@ -566,6 +575,21 @@ If all deliverables passed (or issues were fixed):
   - **trunk-based**: already on main, nothing to do
   - **feature-branch**: create PR from `phase-N/[slug]` to main. Report PR URL. Wait for merge (or auto-merge if user approves). After merge: `git checkout main && git pull`
   - **gitflow**: create PR from `feature/phase-N-[slug]` to develop. Report PR URL. Wait for merge. After merge: `git checkout develop && git pull`
+- Delete `.planning/.phase-active` if it exists (re-enables normal tool permissions)
+
+#### Check if this is the LAST phase
+Read PLAN.md. Check if there is a next phase (any phase with Status "pending" or a `plans/phase-[N+1].md` file).
+
+**If there is NO next phase — plan complete:**
+
+All phases are done. Delegate the full completion cycle to `/cpw-cleanup --complete`.
+This will: generate plan summary, review docs, archive all phases, reset execution state.
+
+Execute `/cpw-cleanup --complete` now (invoke the command inline, do NOT ask the user to run it manually).
+
+After cleanup completes, STOP. Do NOT attempt to advance to a non-existent phase.
+
+**If there IS a next phase — normal advancement:**
 - Reset STATUS.md for next phase:
   ```
   ## Now
@@ -580,7 +604,6 @@ If all deliverables passed (or issues were fixed):
   ## Session notes
   - (empty)
   ```
-- Delete `.planning/.phase-active` if it exists (re-enables normal tool permissions)
 - If `--phase` flag is active: STOP. Do NOT advance to next phase. Report:
   ```
   Phase N complete. UAT passed.

package/templates/claude/commands/cpw-startup.md

@@ -8,6 +8,54 @@ analysis report. You can stop after the scan by declining plan generation.
 
 ## 0. MODE DETECTION
 
+### Check for existing completed plan (new cycle detection)
+Detect new cycle by ANY of these signals:
+1. PLAN.md exists AND `.planning/config.json` exists AND STATUS.md does NOT exist (post-completion state — STATUS.md was deleted by /cpw-cleanup --complete)
+2. PLAN.md exists AND all phases have Status "done" AND no phase has Status "in progress" or "pending" (implicit completion — cleanup may not have run)
+
+If PLAN.md exists with phases "in progress" or "pending" → NOT a new cycle. Skip to standard mode detection below.
+
+If ANY signal matches → **NEW CYCLE** mode:
+
+#### Load project context
+Before interviewing, load what exists:
+- Read `docs/architecture.md` — current architecture
+- Read `docs/interfaces.md` — current interfaces
+- Read `plans/decisions.md` — accumulated decisions
+- Read `.planning/plan-summary.md` (if exists) — what was built in the last cycle
+- Read `.planning/config.json` — workflow settings (carry over, don't re-ask)
+
+#### Present status and ask
+```
+Detected a completed plan.
+
+Previously built:
+  [summary from plan-summary.md, or phase list from PLAN.md if no summary]
+
+Architecture: [key points from architecture.md]
+Active decisions: [count from decisions.md]
+
+Starting a new development cycle. This will:
+  - Keep all existing code, docs, and project structure
+  - Keep .planning/config.json (workflow settings carry over)
+  - Keep plans/decisions.md (cumulative)
+  - Add new phases to PLAN.md (continuing phase numbering)
+
+What do you want to build next?
+```
+
+#### Route to interview
+- Skip mode detection (already have code), skip scan (already know the codebase), skip workflow configuration (config.json already exists).
+- Go directly to step 3 (INTERVIEW) — scope the interview to the NEW work only. Use the loaded docs as context for what already exists.
+- In step 4 (PLAN GENERATION):
+  - Do NOT overwrite PLAN.md — append new phases to the existing table, continuing the phase numbering (e.g., if last phase was 5, new phases start at 6)
+  - Do NOT overwrite docs/ or decisions.md
+  - Do NOT regenerate Phase 0 (stack already set up) or Phase 1 (interfaces already defined) unless the user explicitly requests it
+  - Generate new phase-N.md sub-plans for the new work
+  - Reset STATUS.md to point to the first new phase
+- Continue to step 5 (PLAN REVIEW) and step 6 (COMMIT AND START) as normal.
+
+### Standard mode detection (no existing plan or plan in progress)
 Check the directory state:
 - Are there source files? (src/, lib/, app/, *.py, *.ts, *.go, etc.)
 - Is there git history? (more than 3 commits)

package/templates/planning/plan-summary.md

@@ -0,0 +1,16 @@
+# Plan Summary
+
+## Completed
+- **Date**: --
+- **Phases**: --
+- **Steps**: --
+
+## Phases
+| # | Phase | Steps | Key output |
+|---|-------|-------|------------|
+
+## Key decisions
+(from plans/decisions.md)
+
+## Key deliverables
+(from phase objectives)