@claude-pw/framework 0.9.0 → 0.10.0

package/RELEASES.md

@@ -2,6 +2,18 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
+## [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.0",
+  "version": "0.10.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

@@ -78,6 +78,12 @@ NO CHANGES:
 
 If nothing to clean in a category, omit it from the summary.
 
+If ALL lists are empty after step 1 filtering (no files to archive, nothing exceeds retention limits, no stale files):
+```
+Nothing to clean — completed phases already archived and accumulated state within retention limits.
+```
+STOP.
+
 If `--execute`: show the summary and proceed to step 3.
 Otherwise: ask "Proceed? (yes/no)". If no: STOP.
 
@@ -119,12 +125,19 @@ Delete identified stale files (handoff.md, uat.md).
 ### 3.7 Commit
 Read `commitPlanning` from `.planning/config.json`.
 
+Build commit message based on what was actually executed:
+- If phases were archived AND state was trimmed: `"chore: archive phases N-M and trim planning state"`
+- If only phases were archived: `"chore: archive completed phases N-M"`
+- If only state was trimmed: `"chore: trim accumulated planning state"`
+
 Git add the changes:
 - `PLAN.md` (always — sub-plan column updated)
 - `plans/` (always — phase files removed)
 - `.planning/` (only if `commitPlanning: true`)
 
-`make commit m="chore: cleanup completed phases and accumulated state"`
+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
 

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

@@ -52,6 +52,16 @@ If STATUS.md does not exist:
 - STOP. Do not continue.
 
 - Read STATUS.md -> phase, step, stage
+- If phase = "DONE":
+  - Report:
+    ```
+    Plan is complete — all phases finished.
+
+    Next:
+      /cpw-cleanup  — archive completed phases
+      /cpw-startup  — start a new development cycle
+    ```
+  - STOP. Do not continue.
 - Read indicated sub-plan (plans/phase-N.md)
   - If the file does not exist: report "Sub-plan plans/phase-N.md not found. STATUS.md may be pointing to a non-existent phase. Run `/cpw-health` to diagnose." STOP.
 - If `plans/phase-N-context.md` exists (from /cpw-discuss), load it too
@@ -566,6 +576,93 @@ 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:**
+
+#### 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.
+
+#### 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.
+
+#### Mark DONE
+- Update STATUS.md to DONE state:
+  ```
+  ## Now
+  - Phase: DONE
+  - Step: --
+  - Stage: --
+  - Sub-plan: --
+
+  ## Required context
+  - PLAN.md
+
+  ## Session notes
+  - All phases completed on [date]
+  - Plan summary: .planning/plan-summary.md
+  ```
+- `make commit m="chore: plan complete — summary and status updated"`
+- Report:
+  ```
+  ══════════════════════════════════════
+  PLAN COMPLETE
+  ══════════════════════════════════════
+  All [N] phases finished.
+  Summary: .planning/plan-summary.md
+
+  Next steps:
+    1. /cpw-cleanup  — archive completed phases and clean state
+    2. /cpw-startup  — start a new development cycle (adds new phases to the existing project)
+    3. Nothing       — the project is done
+  ```
+- 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 +677,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,55 @@ 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. STATUS.md exists with `Phase: DONE` (explicit completion)
+2. PLAN.md exists AND all phases have Status "done" AND no phase has Status "in progress" or "pending" (implicit completion — STATUS.md may be missing or corrupted)
+3. PLAN.md exists with phases marked "(archived)" AND no active phases (post-cleanup completion)
+
+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)