@claude-pw/framework 0.11.3 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.es.md CHANGED
@@ -60,7 +60,7 @@ npx @claude-pw/framework --update
60
60
  1. **`/cpw-startup`** te entrevista, escanea código existente (si hay), y genera un plan con fases, pasos y docs de arquitectura. En ciclos posteriores, carga el contexto previo y agrega nuevas fases.
61
61
  2. **`/cpw-discuss`** identifica zonas grises y captura tus preferencias antes de construir (opcional, por fase)
62
62
  3. **`/cpw-next-step`** ejecuta un pipeline adaptativo por paso — luego cierra, commitea y avanza automáticamente
63
- 4. Cuando todas las fases se completan, **`/cpw-cleanup --complete`** se ejecuta automáticamente: genera un resumen del plan, revisa docs, archiva todas las fases, resetea el estado de ejecución y deja el proyecto listo para el siguiente `/cpw-startup`
63
+ 4. Cuando todas las fases se completan, **`/cpw-cleanup`** se ejecuta automáticamente: genera un resumen del plan, revisa docs, archiva todas las fases, resetea el estado de ejecución y deja el proyecto listo para el siguiente `/cpw-startup`
64
64
 
65
65
  Cada paso pasa por:
66
66
 
@@ -138,7 +138,7 @@ Issue capturado. ¿Arreglar ahora? (sí/no)
138
138
  | `/cpw-todos` | Captura ideas para después o revisa todos pendientes |
139
139
  | `/cpw-reflect` | Revisa correcciones capturadas, convierte en learnings (`--scan-history`, `--dedupe`) |
140
140
  | `/cpw-impact` | Analiza impacto de decisiones en todo el plan |
141
- | `/cpw-cleanup` | Archiva fases completadas y limpia estado (`--complete` para reset completo del plan) |
141
+ | `/cpw-cleanup` | Archiva fases completadas y limpia estado (auto-detecta reset completo cuando el plan termina) |
142
142
  | `/cpw-update` | Actualización inteligente del framework — diff, merge de conflictos, preserva customizaciones |
143
143
 
144
144
  ## Configuración
package/README.ja.md CHANGED
@@ -60,7 +60,7 @@ npx @claude-pw/framework --update
60
60
  1. **`/cpw-startup`** インタビューを行い、既存コード(あれば)をスキャンし、フェーズ・ステップ・アーキテクチャドキュメントを含む計画を生成。後続サイクルでは、以前のコンテキストを読み込み、新しいフェーズを追加。
61
61
  2. **`/cpw-discuss`** グレーゾーンを特定し、ビルド前にあなたの好みを把握(任意、フェーズごと)
62
62
  3. **`/cpw-next-step`** ステップごとに適応型パイプラインを実行 — 完了後、自動的にクローズ・コミット・次へ進行
63
- 4. 全フェーズ完了時、**`/cpw-cleanup --complete`** が自動実行:計画サマリー生成、ドキュメントレビュー、全フェーズアーカイブ、実行状態リセット、次の `/cpw-startup` に備える
63
+ 4. 全フェーズ完了時、**`/cpw-cleanup`** が自動実行:計画サマリー生成、ドキュメントレビュー、全フェーズアーカイブ、実行状態リセット、次の `/cpw-startup` に備える
64
64
 
65
65
  各ステップは以下を経由します:
66
66
 
@@ -138,7 +138,7 @@ Issue captured. Fix now? (yes/no)
138
138
  | `/cpw-todos` | アイデアの記録または保留中の TODO の確認 |
139
139
  | `/cpw-reflect` | キャプチャした修正をレビューし、学習に変換(`--scan-history`, `--dedupe`) |
140
140
  | `/cpw-impact` | 計画全体にわたる意思決定の影響分析 |
141
- | `/cpw-cleanup` | 完了フェーズのアーカイブと状態クリーンアップ(`--complete` で計画全体リセット) |
141
+ | `/cpw-cleanup` | 完了フェーズのアーカイブと状態クリーンアップ(計画完了時に自動で完全リセット) |
142
142
  | `/cpw-update` | スマートフレームワーク更新 — 差分、コンフリクトマージ、カスタマイズ保持 |
143
143
 
144
144
  ## 設定
package/README.md CHANGED
@@ -60,7 +60,7 @@ npx @claude-pw/framework --update
60
60
  1. **`/cpw-startup`** interviews you, scans existing code (if any), and generates a plan with phases, steps, and architecture docs. On subsequent cycles, loads prior context and appends new phases.
61
61
  2. **`/cpw-discuss`** identifies gray areas and captures your preferences before building (optional, per phase)
62
62
  3. **`/cpw-next-step`** runs an adaptive pipeline per step — then closes, commits, and advances automatically
63
- 4. When all phases complete, **`/cpw-cleanup --complete`** runs automatically: generates a plan summary, reviews docs for drift, archives all phase files, resets execution state, and leaves the project ready for the next `/cpw-startup`
63
+ 4. When all phases complete, **`/cpw-cleanup`** runs automatically: generates a plan summary, reviews docs for drift, archives all phase files, resets execution state, and leaves the project ready for the next `/cpw-startup`
64
64
 
65
65
  Every step goes through:
66
66
 
@@ -138,7 +138,7 @@ Issue captured. Fix now? (yes/no)
138
138
  | `/cpw-todos` | Capture ideas for later or review pending todos |
139
139
  | `/cpw-reflect` | Review captured corrections, convert to learnings (`--scan-history`, `--dedupe`) |
140
140
  | `/cpw-impact` | Analyze decision impact across the entire plan |
141
- | `/cpw-cleanup` | Archive completed phases and clean state (`--complete` for full plan reset) |
141
+ | `/cpw-cleanup` | Archive completed phases and clean state (auto-detects full reset when plan is done) |
142
142
  | `/cpw-update` | Smart framework update — diff, merge conflicts, preserve customizations |
143
143
 
144
144
  ## Configuration
package/README.pt-br.md CHANGED
@@ -60,7 +60,7 @@ npx @claude-pw/framework --update
60
60
  1. **`/cpw-startup`** entrevista você, analisa o código existente (se houver) e gera um plano com fases, etapas e documentos de arquitetura. Em ciclos posteriores, carrega o contexto anterior e adiciona novas fases.
61
61
  2. **`/cpw-discuss`** identifica áreas cinzentas e captura suas preferências antes de construir (opcional, por fase)
62
62
  3. **`/cpw-next-step`** executa um pipeline adaptativo por etapa — então fecha, commita e avança automaticamente
63
- 4. Quando todas as fases completam, **`/cpw-cleanup --complete`** executa automaticamente: gera resumo do plano, revisa docs, arquiva todas as fases, reseta estado de execução e deixa o projeto pronto para o próximo `/cpw-startup`
63
+ 4. Quando todas as fases completam, **`/cpw-cleanup`** executa automaticamente: gera resumo do plano, revisa docs, arquiva todas as fases, reseta estado de execução e deixa o projeto pronto para o próximo `/cpw-startup`
64
64
 
65
65
  Cada etapa passa por:
66
66
 
@@ -138,7 +138,7 @@ Issue captured. Fix now? (yes/no)
138
138
  | `/cpw-todos` | Capturar ideias para depois ou revisar todos pendentes |
139
139
  | `/cpw-reflect` | Revisar correções capturadas, converter em aprendizados (`--scan-history`, `--dedupe`) |
140
140
  | `/cpw-impact` | Analisar impacto de decisões em todo o plano |
141
- | `/cpw-cleanup` | Arquivar fases completadas e limpar estado (`--complete` para reset completo do plano) |
141
+ | `/cpw-cleanup` | Arquivar fases completadas e limpar estado (auto-detecta reset completo quando o plano termina) |
142
142
  | `/cpw-update` | Atualização inteligente do framework — diff, merge de conflitos, preserva customizações |
143
143
 
144
144
  ## Configuração
package/README.zh-cn.md CHANGED
@@ -60,7 +60,7 @@ npx @claude-pw/framework --update
60
60
  1. **`/cpw-startup`** 对你进行访谈,扫描现有代码(如果有),生成包含阶段、步骤和架构文档的计划。后续周期中,加载之前的上下文并追加新阶段。
61
61
  2. **`/cpw-discuss`** 识别灰色地带,在构建前捕获你的偏好(可选,按阶段)
62
62
  3. **`/cpw-next-step`** 按步骤运行自适应流水线——然后自动关闭、提交并推进
63
- 4. 当所有阶段完成时,**`/cpw-cleanup --complete`** 自动运行:生成计划摘要、审查文档、归档所有阶段文件、重置执行状态,为下一个 `/cpw-startup` 做好准备
63
+ 4. 当所有阶段完成时,**`/cpw-cleanup`** 自动运行:生成计划摘要、审查文档、归档所有阶段文件、重置执行状态,为下一个 `/cpw-startup` 做好准备
64
64
 
65
65
  每个步骤经过:
66
66
 
@@ -138,7 +138,7 @@ UAT 演练:
138
138
  | `/cpw-todos` | 捕获想法或查看待办事项 |
139
139
  | `/cpw-reflect` | 审查捕获的修正,转化为学习成果(`--scan-history`、`--dedupe`) |
140
140
  | `/cpw-impact` | 分析决策对整个计划的影响 |
141
- | `/cpw-cleanup` | 归档已完成阶段并清理状态(`--complete` 用于完整计划重置) |
141
+ | `/cpw-cleanup` | 归档已完成阶段并清理状态(计划完成时自动执行完整重置) |
142
142
  | `/cpw-update` | 智能框架更新 — 差异对比、冲突合并、保留自定义 |
143
143
 
144
144
  ## 配置
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@claude-pw/framework",
3
- "version": "0.11.3",
3
+ "version": "0.12.0",
4
4
  "description": "Structured Project Workflow for Claude Code — adaptive pipeline, context management, quality gates",
5
5
  "bin": {
6
6
  "claude-pw": "./install.js"
@@ -5,123 +5,8 @@ description: "Archive completed phases and clean accumulated state"
5
5
  ## Arguments
6
6
  - No arguments: dry-run (show what would be cleaned, ask for confirmation)
7
7
  - `--execute`: skip confirmation, execute immediately
8
- - `--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.
9
8
 
10
- ---
11
-
12
- ## --complete mode (plan completion cycle)
13
-
14
- If `--complete` is passed, execute the full completion cycle. This mode is designed to
15
- close a finished plan, archive everything, and leave the project ready for `/cpw-startup`.
16
-
17
- ### 1. Plan completion summary
18
- Generate `.planning/plan-summary.md`:
19
- - Read all phase sub-plans (plans/phase-N.md for each phase in PLAN.md)
20
- - Read plans/decisions.md
21
- - For each phase, extract: name, step count, Objective line
22
- - From decisions.md, extract decisions made during these phases
23
- - Get date range from git: first plan commit and today
24
-
25
- Write `.planning/plan-summary.md`:
26
- ```markdown
27
- # Plan Summary
28
-
29
- ## Completed
30
- - **Date**: [today]
31
- - **Phases**: [N]
32
- - **Steps**: [total across all phases]
33
-
34
- ## Phases
35
- | # | Phase | Steps | Key output |
36
- |---|-------|-------|------------|
37
- | 0 | Stack and Scaffolding | 6 | Project setup, toolchain, CI |
38
- | 1 | Interfaces | 5 | Module contracts, type system |
39
- | ... | ... | ... | ... |
40
-
41
- ## Key decisions
42
- - Phase N: [decision summary from decisions.md]
43
- - ...
44
-
45
- ## Key deliverables
46
- - [extracted from each phase's Objective]
47
- - ...
48
- ```
49
-
50
- If a previous `.planning/plan-summary.md` exists (from a prior cycle), rename it
51
- to `.planning/plan-summary-[date].md` before writing the new one.
52
-
53
- ### 2. Docs evolution review
54
- Review if docs/ need updating after the full plan:
55
- - Read `docs/architecture.md` — does it reflect what was actually built?
56
- Compare with the plan phases and deliverables. If outdated, update it.
57
- - Read `docs/interfaces.md` — are interfaces current with the final state of `src/interfaces/`?
58
- If outdated, update it.
59
- - If any docs were updated:
60
- `make commit m="docs: update architecture and interfaces after plan completion"`
61
-
62
- This is a lightweight pass to catch drift — not a full rewrite.
63
-
64
- ### 3. Archive ALL phase files
65
- ```bash
66
- mkdir -p .planning/archive
67
- ```
68
- For every phase in PLAN.md (regardless of `archiveCompletedPhases` config — in --complete mode, everything gets archived):
69
- - Move `plans/phase-N.md` to `.planning/archive/phase-N.md`
70
- - Move `plans/phase-N-context.md` to `.planning/archive/phase-N-context.md` (if exists)
71
-
72
- Update PLAN.md: sub-plan column → `(archived)` for all phases.
73
-
74
- ### 4. Reset execution state
75
- Clean execution artifacts. These served the current plan cycle and are not needed for the next:
76
- - **Delete** `STATUS.md` (session pointer — no longer needed)
77
- - **Reset** `.planning/quick/log.md` to empty table header only
78
- - **Delete** all files in `.planning/debug/resolved/`
79
- - **Delete** `.planning/debug/active-session.md` (if exists)
80
- - **Delete** `.planning/handoff.md` (if exists)
81
- - **Delete** `.planning/uat.md` (if exists)
82
-
83
- Do NOT touch (project context that survives between cycles):
84
- - `plans/decisions.md` — cumulative project history
85
- - `docs/*` — project documentation (just reviewed in step 2)
86
- - `.planning/config.json` — workflow settings carry over
87
- - `.planning/plan-summary.md` — just generated in step 1
88
- - `.planning/learnings/queue.md` — pending corrections carry over (may still need processing)
89
- - `.planning/learnings/applied.md` — deduplication reference (knowledge already extracted to rules/skills)
90
- - `PLAN.md` — updated with (archived) markers
91
- - `CLAUDE.md` — project instructions
92
- - `.claude/skills/*` — extracted knowledge
93
- - `.claude/rules/*` — project rules
94
- - All source code, tests, Makefile, etc.
95
-
96
- ### 5. Commit
97
- `make commit m="chore: plan complete — archived [N] phases, reset execution state"`
98
-
99
- ### 6. Report
100
- ```
101
- ══════════════════════════════════════
102
- PLAN COMPLETE
103
- ══════════════════════════════════════
104
- All [N] phases finished.
105
- Summary: .planning/plan-summary.md
106
-
107
- Archived: [N] phase files → .planning/archive/
108
- Cleaned: STATUS.md, quick log, debug sessions
109
-
110
- Project is ready for the next development cycle.
111
- Run /cpw-startup to begin.
112
- ══════════════════════════════════════
113
- ```
114
-
115
- STOP.
116
-
117
- ---
118
-
119
- ## Standard mode (mid-plan cleanup)
120
-
121
- If `--complete` is NOT passed, run the standard cleanup flow below.
122
- This is for archiving completed phases while the plan is still in progress.
123
-
124
- ### 0. Load state
9
+ ## 0. Load state and detect mode
125
10
 
126
11
  Read `.planning/config.json` -> extract `cleanupPolicy` (use defaults if missing):
127
12
  - `archiveCompletedPhases`: true
@@ -129,53 +14,97 @@ Read `.planning/config.json` -> extract `cleanupPolicy` (use defaults if missing
129
14
  - `keepResolvedDebug`: 5
130
15
  - `keepQuickLogDone`: 10
131
16
 
132
- Read PLAN.md -> extract phases table. Identify phases with Status = "done".
133
- Read STATUS.md -> identify current phase (to avoid archiving it).
17
+ Read PLAN.md -> extract phases table.
134
18
 
135
- If no completed phases and no accumulated state to clean:
136
- ```
137
- Nothing to clean up. All phases are current or pending.
138
- ```
139
- STOP.
19
+ **Auto-detect mode:**
20
+ - If ALL phases have Status "done" AND no phase has Status "in progress" or "pending" → **COMPLETE mode** (plan finished)
21
+ - Otherwise **MID-PLAN mode** (plan still in progress)
22
+
23
+ ## 1. Identify what to clean
140
24
 
141
- ### 1. Identify what to clean
25
+ ### 1.1 Phase files
142
26
 
143
- #### 1.1 Completed phase files
144
- If `archiveCompletedPhases` is true:
145
- For each phase with Status "done" in PLAN.md:
27
+ **COMPLETE mode:** archive ALL phase files (every phase in PLAN.md).
28
+ **MID-PLAN mode:** archive only phases with Status "done" that still have files in `plans/` (if `archiveCompletedPhases` is true). NEVER archive the current phase or pending phases. Read STATUS.md to identify current phase.
29
+
30
+ For each phase to archive:
146
31
  - Check if `plans/phase-N.md` still exists (not already archived)
147
32
  - Check if `plans/phase-N-context.md` exists
148
33
  - Add to archive list
149
- - NEVER archive the current phase or pending phases
150
34
 
151
- #### 1.2 Quick log done entries
152
- Read `.planning/quick/log.md` (if exists):
153
- - Count entries with Status: done or dismissed
154
- - If count > `keepQuickLogDone`: mark oldest excess entries for removal
35
+ ### 1.2 Quick log done entries
36
+
37
+ **COMPLETE mode:** mark ALL entries for removal (reset to empty table header).
38
+ **MID-PLAN mode:** read `.planning/quick/log.md` (if exists). If done/dismissed entries > `keepQuickLogDone`: mark oldest excess for removal.
155
39
 
156
- #### 1.3 Resolved debug sessions
40
+ ### 1.3 Resolved debug sessions
157
41
  List `.planning/debug/resolved/` (if exists):
158
- - Count files
159
42
  - If count > `keepResolvedDebug`: mark oldest files for deletion (by filename date prefix)
160
43
 
161
- #### 1.4 Applied learnings
44
+ ### 1.4 Applied learnings
162
45
  Read `.planning/learnings/applied.md` (if exists):
163
46
  - Count entries (each entry starts with `---`)
164
47
  - If count > `keepAppliedLearnings`: mark oldest excess entries for trimming
165
48
 
166
- #### 1.5 Stale files
167
- - `.planning/handoff.md` — if it exists AND STATUS.md does NOT show a handoff in progress
168
- - `.planning/uat.md` — if it exists AND all phases it references are done (no active UAT)
49
+ NEVER touch `.planning/learnings/queue.md` pending corrections always carry over.
169
50
 
170
- ### 2. Present cleanup plan
51
+ ### 1.5 Stale files
52
+ - `.planning/handoff.md` — if it exists
53
+ - `.planning/uat.md` — if it exists AND all phases it references are done
54
+ - `.planning/debug/active-session.md` — **COMPLETE mode only** (if exists)
171
55
 
56
+ ### 1.6 COMPLETE mode extras
57
+ Only in COMPLETE mode:
58
+ - STATUS.md will be deleted (session pointer no longer needed)
59
+ - Plan summary will be generated
60
+ - Docs will be reviewed for drift
61
+
62
+ ## 2. Present cleanup plan
63
+
64
+ **COMPLETE mode:**
65
+ ```
66
+ ══════════════════════════════════════
67
+ PLAN COMPLETE — Cleanup
68
+ ══════════════════════════════════════
69
+
70
+ GENERATE:
71
+ - .planning/plan-summary.md (plan history)
72
+
73
+ DOCS REVIEW:
74
+ - docs/architecture.md (check for drift)
75
+ - docs/interfaces.md (check for drift)
76
+
77
+ ARCHIVE (move to .planning/archive/):
78
+ - plans/phase-0.md (6 steps)
79
+ - plans/phase-1.md (4 steps)
80
+ - plans/phase-2.md (5 steps)
81
+
82
+ TRIM:
83
+ - quick/log.md: reset to empty
84
+ - debug/resolved/: delete N old sessions (keeping last M)
85
+ - learnings/applied.md: trim N old entries (keeping last M)
86
+
87
+ DELETE:
88
+ - STATUS.md
89
+ - .planning/handoff.md
90
+ - .planning/debug/active-session.md
91
+
92
+ NO CHANGES:
93
+ - plans/decisions.md (cumulative)
94
+ - .planning/learnings/queue.md (pending corrections)
95
+ - .planning/config.json (workflow settings)
96
+ - docs/* (reviewed, not deleted)
97
+ - .claude/skills/*, .claude/rules/*
98
+ ══════════════════════════════════════
99
+ ```
100
+
101
+ **MID-PLAN mode:**
172
102
  ```
173
103
  Cleanup Summary:
174
104
 
175
105
  ARCHIVE (move to .planning/archive/):
176
106
  - plans/phase-0.md (6 steps, all done)
177
107
  - plans/phase-0-context.md
178
- - plans/phase-1.md (4 steps, all done)
179
108
 
180
109
  TRIM:
181
110
  - quick/log.md: remove N done entries (keeping last M)
@@ -203,9 +132,52 @@ STOP.
203
132
  If `--execute`: show the summary and proceed to step 3.
204
133
  Otherwise: ask "Proceed? (yes/no)". If no: STOP.
205
134
 
206
- ### 3. Execute
135
+ ## 3. Execute
136
+
137
+ ### 3.1 COMPLETE mode: Plan summary
138
+ Only in COMPLETE mode. Generate `.planning/plan-summary.md`:
139
+ - Read all phase sub-plans (plans/phase-N.md for each phase in PLAN.md)
140
+ - Read plans/decisions.md
141
+ - For each phase, extract: name, step count, Objective line
142
+ - From decisions.md, extract decisions made during these phases
143
+ - Get date range from git: first plan commit and today
144
+
145
+ Write `.planning/plan-summary.md`:
146
+ ```markdown
147
+ # Plan Summary
148
+
149
+ ## Completed
150
+ - **Date**: [today]
151
+ - **Phases**: [N]
152
+ - **Steps**: [total across all phases]
153
+
154
+ ## Phases
155
+ | # | Phase | Steps | Key output |
156
+ |---|-------|-------|------------|
157
+ | 0 | Stack and Scaffolding | 6 | Project setup, toolchain, CI |
158
+ | 1 | Interfaces | 5 | Module contracts, type system |
159
+ | ... | ... | ... | ... |
160
+
161
+ ## Key decisions
162
+ - Phase N: [decision summary from decisions.md]
163
+ - ...
164
+
165
+ ## Key deliverables
166
+ - [extracted from each phase's Objective]
167
+ - ...
168
+ ```
169
+
170
+ If a previous plan-summary.md exists (prior cycle), rename to `plan-summary-[date].md`.
171
+
172
+ ### 3.2 COMPLETE mode: Docs evolution review
173
+ Only in COMPLETE mode. Review if docs/ need updating:
174
+ - Read `docs/architecture.md` — does it reflect what was actually built? If outdated, update.
175
+ - Read `docs/interfaces.md` — are interfaces current? If outdated, update.
176
+ - If any docs were updated: `make commit m="docs: update architecture and interfaces after plan completion"`
207
177
 
208
- #### 3.1 Archive phase files
178
+ Lightweight pass to catch drift — not a full rewrite.
179
+
180
+ ### 3.3 Archive phase files
209
181
  ```bash
210
182
  mkdir -p .planning/archive
211
183
  ```
@@ -213,7 +185,7 @@ For each phase in the archive list:
213
185
  - Move `plans/phase-N.md` to `.planning/archive/phase-N.md`
214
186
  - Move `plans/phase-N-context.md` to `.planning/archive/phase-N-context.md` (if exists)
215
187
 
216
- #### 3.2 Update PLAN.md
188
+ ### 3.4 Update PLAN.md
217
189
  For each archived phase, change the sub-plan column from `plans/phase-N.md` to `(archived)`:
218
190
  ```
219
191
  | 0 | Stack and Scaffolding | plans/phase-0.md | done |
@@ -223,25 +195,30 @@ becomes:
223
195
  | 0 | Stack and Scaffolding | (archived) | done |
224
196
  ```
225
197
 
226
- #### 3.3 Trim quick log
227
- Remove done/dismissed entries beyond the keep limit from `.planning/quick/log.md`.
228
- Keep the most recent N entries (by date). Preserve the table header.
198
+ ### 3.5 Trim quick log
199
+ **COMPLETE mode:** reset `.planning/quick/log.md` to empty table header only.
200
+ **MID-PLAN mode:** remove done/dismissed entries beyond the keep limit. Keep the most recent N entries (by date). Preserve the table header.
229
201
 
230
- #### 3.4 Delete old debug sessions
202
+ ### 3.6 Trim debug sessions
231
203
  Delete files from `.planning/debug/resolved/` beyond the keep limit.
232
204
  Delete the oldest by filename date prefix.
233
205
 
234
- #### 3.5 Trim applied learnings
206
+ ### 3.7 Trim applied learnings
235
207
  Remove the oldest entries from `.planning/learnings/applied.md` beyond the keep limit.
236
208
  Keep the most recent N entries. Each entry is delimited by `---`.
237
209
 
238
- #### 3.6 Delete stale files
239
- Delete identified stale files (handoff.md, uat.md).
210
+ ### 3.8 Delete stale files
211
+ Delete identified stale files (handoff.md, uat.md, and active-session.md in COMPLETE mode).
212
+
213
+ ### 3.9 COMPLETE mode: Delete STATUS.md
214
+ Only in COMPLETE mode. Delete STATUS.md (session pointer no longer needed — its absence signals a completed plan to /cpw-startup and /cpw-next-step).
240
215
 
241
- #### 3.7 Commit
216
+ ### 3.10 Commit
242
217
  Read `commitPlanning` from `.planning/config.json`.
243
218
 
244
- Build commit message based on what was actually executed:
219
+ **COMPLETE mode:** `make commit m="chore: plan complete archived [N] phases, reset execution state"`
220
+
221
+ **MID-PLAN mode:** Build commit message based on what was actually executed:
245
222
  - If phases were archived AND state was trimmed: `"chore: archive phases N-M and trim planning state"`
246
223
  - If only phases were archived: `"chore: archive completed phases N-M"`
247
224
  - If only state was trimmed: `"chore: trim accumulated planning state"`
@@ -252,11 +229,29 @@ Git add the changes:
252
229
  - `.planning/` (only if `commitPlanning: true`)
253
230
 
254
231
  Check if there are staged changes (`git diff --cached --quiet`).
255
- - If there are changes: `make commit m="[built message]"`
232
+ - If there are changes: commit
256
233
  - 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."
257
234
 
258
- ### 4. Report
235
+ ## 4. Report
236
+
237
+ **COMPLETE mode:**
238
+ ```
239
+ ══════════════════════════════════════
240
+ PLAN COMPLETE
241
+ ══════════════════════════════════════
242
+ All [N] phases finished.
243
+ Summary: .planning/plan-summary.md
244
+
245
+ Archived: [N] phase files → .planning/archive/
246
+ Trimmed: quick log, [K] debug sessions, [L] learnings
247
+ Cleaned: STATUS.md, handoff, debug active session
248
+
249
+ Project is ready for the next development cycle.
250
+ Run /cpw-startup to begin.
251
+ ══════════════════════════════════════
252
+ ```
259
253
 
254
+ **MID-PLAN mode:**
260
255
  ```
261
256
  Cleanup complete.
262
257
 
@@ -582,10 +582,11 @@ Read PLAN.md. Check if there is a next phase (any phase with Status "pending" or
582
582
 
583
583
  **If there is NO next phase — plan complete:**
584
584
 
585
- All phases are done. Delegate the full completion cycle to `/cpw-cleanup --complete`.
586
- This will: generate plan summary, review docs, archive all phases, reset execution state.
585
+ All phases are done. Delegate to `/cpw-cleanup` which will auto-detect COMPLETE mode
586
+ (all phases done) and run the full completion cycle: plan summary, docs review, archive
587
+ all phases, trim state, reset execution artifacts.
587
588
 
588
- Execute `/cpw-cleanup --complete` now (invoke the command inline, do NOT ask the user to run it manually).
589
+ Execute `/cpw-cleanup --execute` now (invoke the command inline, skip confirmation).
589
590
 
590
591
  After cleanup completes, STOP. Do NOT attempt to advance to a non-existent phase.
591
592
 
@@ -10,7 +10,7 @@ analysis report. You can stop after the scan by declining plan generation.
10
10
 
11
11
  ### Check for existing completed plan (new cycle detection)
12
12
  Detect new cycle by ANY of these signals:
13
- 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)
13
+ 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)
14
14
  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)
15
15
 
16
16
  If PLAN.md exists with phases "in progress" or "pending" → NOT a new cycle. Skip to standard mode detection below.