@claude-pw/framework 0.10.0 → 0.11.0

package/RELEASES.md

@@ -2,6 +2,15 @@
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-pw/framework",
-  "version": "0.10.0",
+  "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,25 +43,24 @@ 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.
 
-- Read STATUS.md -> phase, step, stage
-- If phase = "DONE":
+    Next: run `/cpw-startup` to start a new cycle.
+    ```
+  - STOP.
+- Otherwise:
   - Report:
     ```
-    Plan is complete — all phases finished.
+    No STATUS.md found — this project hasn't been initialized yet.
 
-    Next:
-      /cpw-cleanup  — archive completed phases
-      /cpw-startup  — start a new development cycle
+    Next: run `/cpw-startup` to set up the project.
     ```
-  - STOP. Do not continue.
+  - STOP.
+
+- Read STATUS.md -> phase, step, stage
 - 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
@@ -583,84 +582,12 @@ Read PLAN.md. Check if there is a next phase (any phase with Status "pending" or
 
 **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.
+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.
 
-#### Mark DONE
-- Update STATUS.md to DONE state:
-  ```
-  ## Now
-  - Phase: DONE
-  - Step: --
-  - Stage: --
-  - Sub-plan: --
+Execute `/cpw-cleanup --complete` now (invoke the command inline, do NOT ask the user to run it manually).
 
-  ## 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.
+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:

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

@@ -10,9 +10,8 @@ analysis report. You can stop after the scan by declining plan generation.
 
 ### 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)
+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.