@claude-pw/framework 0.5.2 → 0.6.1

package/package.json

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

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

@@ -4,7 +4,7 @@ description: "Load context and execute the next pipeline stage"
 
 ## Arguments
 - No arguments: normal flow (respects `autoAdvance` from config)
-- `--phase`: auto-advance all steps in the current phase, pause at UAT. Overrides `autoAdvance` to `auto` for this invocation only. Does NOT cross to next phase.
+- `--phase`: plan the entire phase first, then auto-advance all steps to UAT. Shows execution plan for approval before starting. Overrides `autoAdvance` to `auto` for this invocation only. Does NOT cross to next phase.
 
 ## 0. Health check (session start)
 
@@ -230,6 +230,50 @@ Pipeline for Step [X.Y]:
 - CLOSE: ok
 ```
 
+### 1.7 Phase planning (only with --phase flag)
+
+This step runs ONLY when `--phase` flag is active AND this is the first step of the phase (or first invocation with --phase).
+
+Read the complete sub-plan. For each pending step (Status: [ ]):
+
+1. Read the step's input, output, and done criterion
+2. Evaluate which pipeline stages apply (same logic as the adaptive pipeline above)
+3. Note dependencies (Requires field)
+
+Present the execution plan:
+```
+Phase N: [phase name] — Execution Plan
+
+Steps remaining: X of Y
+
+Step N.1: [name]
+  Pipeline: [stages that will run]
+  Skipping: [stages skipped + reason]
+  Input: [from sub-plan]
+  Output: [from sub-plan]
+
+Step N.2: [name]
+  Requires: N.1
+  Pipeline: [stages that will run]
+  Skipping: [stages skipped + reason]
+  Input: [from sub-plan]
+  Output: [from sub-plan]
+
+...
+
+After all steps: phase validation → UAT (interactive).
+Estimated context resets: [N / based on step count, suggest /clear every 3 steps]
+```
+
+Ask: "Execute this plan? (yes / adjust / cancel)"
+- **yes**: proceed with auto-advance (normal --phase behavior)
+- **adjust**: ask what to change (skip a step, reorder, modify pipeline). Update sub-plan if needed, re-present.
+- **cancel**: exit --phase mode, continue as normal /cpw-next-step (step by step)
+
+After approval, continue to pipeline execution.
+
+---
+
 Then execute the current stage (check docs/tooling.md for tools mapped to this stage):
 - **SPIKE:** Define question + timebox. Delegate to the spike-explorer agent:
   <files_to_read>
@@ -532,11 +576,21 @@ If all deliverables passed (or issues were fixed):
   ## Session notes
   - (empty)
   ```
-- If autoAdvance is **off**: Recommend /clear, then report:
+- If `--phase` flag is active: STOP. Do NOT advance to next phase. Report:
+  ```
+  Phase N complete. UAT passed.
+
+  Next: run `/clear`, then `/cpw-next-step` (or `/cpw-next-step --phase`) for Phase N+1.
+
+  Optional before starting:
+    /cpw-discuss — clarify ambiguities for the next phase
+    /cpw-todos  — review pending todos
+  ```
+- If autoAdvance is **off** (and no --phase): Recommend /clear, then report:
   "Phase N complete. Before starting Phase N+1:"
   "  1. `/cpw-discuss` — clarify ambiguities for the next phase"
   "  2. `/cpw-todos` — review pending todos (some may fit the next phase)"
   "  3. `/cpw-next-step` — start directly"
-- If autoAdvance is **auto** or **yolo**: Suggest /clear for context refresh, then automatically continue with Phase N+1 (run tooling audit → first step).
+- If autoAdvance is **auto** or **yolo** (and no --phase): Suggest /clear for context refresh, then automatically continue with Phase N+1 (run tooling audit → first step).
 
 NEVER advance between phases without completing UAT first (in any mode).