@claude-pw/framework 0.5.0 → 0.5.2

package/install.js

@@ -15,7 +15,7 @@ const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
 
-const VERSION = '0.3.0';
+const VERSION = require('./package.json').version;
 
 // --- Colors ---
 const c = {
@@ -290,14 +290,18 @@ async function main() {
   let projectName = '';
 
   // Parse arguments
-  for (const arg of args) {
+  let extractDir = null;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (arg === '--update') updateOnly = true;
+    else if (arg === '--extract') { extractDir = args[++i]; }
     else if (arg === '--version') { console.log(`claude-pw ${VERSION}`); process.exit(0); }
     else if (arg === '--help' || arg === '-h') {
       console.log('claude-pw — Structured Project Workflow for Claude Code\n');
       console.log('Usage:');
       console.log('  claude-pw [project-name]    Create new project');
       console.log('  claude-pw --update          Update .claude/ in existing project');
+      console.log('  claude-pw --extract <dir>   Extract templates to directory (for /cpw-update)');
       console.log('  claude-pw --version         Show version');
       process.exit(0);
     } else if (arg.startsWith('-')) {
@@ -318,6 +322,23 @@ async function main() {
 
   const date = new Date().toISOString().slice(0, 10);
 
+  // ============================================================
+  // EXTRACT MODE (for /cpw-update command)
+  // ============================================================
+  if (extractDir) {
+    if (!extractDir || typeof extractDir !== 'string') {
+      error('Usage: --extract <directory>');
+      process.exit(1);
+    }
+    fs.cpSync(templatesDir, extractDir, { recursive: true });
+    const releasesFile = path.join(scriptDir, 'RELEASES.md');
+    if (fs.existsSync(releasesFile)) {
+      fs.copyFileSync(releasesFile, path.join(extractDir, 'RELEASES.md'));
+    }
+    fs.writeFileSync(path.join(extractDir, '.version'), VERSION);
+    process.exit(0);
+  }
+
   // ============================================================
   // UPDATE MODE
   // ============================================================
@@ -372,15 +393,23 @@ async function main() {
     console.log('  settings.json (merge, custom hooks preserved)');
     console.log('  config.json (merge new fields)');
     if (allModified.length > 0) {
-      console.log(`\n  ${c.yellow('Modified by you (will be overwritten):')}`);
+      console.log(`\n  ${c.yellow('Modified (differs from new version):')}`);
       for (const f of allModified) console.log(`    ${f}`);
+      console.log(`\n  For intelligent merge of modified files, use ${c.bold('/cpw-update')} inside Claude instead.`);
     }
     console.log(`\n  Backup: .claude.backup.* (created before changes)\n`);
 
-    const confirm = await askQuestion('Apply? [y/N]: ');
-    if (!/^[yYsS]$/.test(confirm)) {
-      info('Cancelled.');
-      process.exit(0);
+    const confirm = await askQuestion(`${allModified.length > 0 ? 'Replace all (r) / Cancel (c): ' : 'Apply? [y/N]: '}`);
+    if (allModified.length > 0) {
+      if (!/^[rR]$/.test(confirm)) {
+        info('Cancelled. Use /cpw-update inside Claude for merge support.');
+        process.exit(0);
+      }
+    } else {
+      if (!/^[yYsS]$/.test(confirm)) {
+        info('Cancelled.');
+        process.exit(0);
+      }
     }
 
     // Backup
@@ -428,6 +457,10 @@ async function main() {
 
     // Write version
     fs.writeFileSync(versionFile, VERSION);
+
+    // Leave marker for /cpw-next-step to detect
+    fs.writeFileSync(path.join('.planning', '.updated-from'), installedVersion);
+
     info(`Actualizado a claude-pw v${VERSION}`);
     process.exit(0);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-pw/framework",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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

@@ -2,8 +2,20 @@
 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.
+
 ## 0. Health check (session start)
 
+### Post-update detection
+If `.planning/.updated-from` exists:
+- Read the file — it contains the previous version
+- Show: "Framework updated from v{old} to v{current}. Running health check..."
+- Delete the file
+- Run `/cpw-health` (full diagnostic, not just session-recovery)
+- After health check completes, continue normally
+
 ### Handoff detection
 If `.planning/handoff.md` exists:
 - Show the handoff summary to the user
@@ -25,8 +37,19 @@ Delegate to the session-recovery agent in CHECK mode:
 - If INCONSISTENT: show diagnostic. Do NOT continue without user decision.
 
 ## 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.
+
 - 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
 - Load ONLY files in "Required context" — nothing else
 - Read `.planning/config.json` -> autoAdvance (off | auto | yolo)
@@ -258,7 +281,7 @@ Then execute the current stage (check docs/tooling.md for tools mapped to this s
   Max retries: [from `maxConsecutiveFailures` in config, default: 3]
   Wait for the agent's structured report.
   - If SUCCESS → proceed to ACCEPTANCE with the report as summary
-  - If PARTIAL → present partial results to user. Options: continue to ACCEPTANCE / retry / abort
+  - If PARTIAL → if autoAdvance is auto/yolo or `--phase`: retry automatically (up to max retries). Otherwise: present partial results to user. Options: continue to ACCEPTANCE / retry / abort
   - If FAILED → present failure details. Options: retry with modified design / abort step
   - Deviations field → included in ACCEPTANCE summary for reviewer visibility
 - **TEST:** The implementer already ran tests. Review its test report.
@@ -309,7 +332,7 @@ If no self-check triggers or gates don't pass: continue normally.
 ### Auto-reflect check (CLOSE sub-step 5)
 Read `autoReflect` from `.planning/config.json` (default: "remind").
 If `autoReflect` is `"auto"` AND `.planning/learnings/queue.md` has entries:
-- Run a lightweight reflection (steps 1.5, 2, 4, 5 of /cpw-reflect — skip history scan and dedup)
+- Run a lightweight reflection: semantic validation → classify each entry with learning-extractor → apply approved changes → cleanup queue (skip history scan, skip user presentation for confidence ≥ 0.80, skip dedup)
 - Auto-approve entries with confidence ≥ 0.80
 - Present entries with confidence < 0.80 for manual approval
 - `make commit m="learn: auto-reflect session learnings"`
@@ -319,7 +342,8 @@ Update STATUS.md with the new stage when finished.
 
 ## 2. Advance based on mode
 
-Read `autoAdvance` from `.planning/config.json` (default: "off").
+If `--phase` flag was passed, set effective autoAdvance = "auto" for this invocation.
+Otherwise, read `autoAdvance` from `.planning/config.json` (default: "off").
 Read `maxConsecutiveFailures` from config (default: 3 for auto, 5 for yolo).
 
 ### off (default)
@@ -348,7 +372,13 @@ In yolo mode, Claude designs, implements, tests, closes, validates phases, and a
 - Commit messages are auto-generated in auto and yolo (no pause)
 - Phase validation always runs automatically when last step completes
 - Between phases: auto and yolo continue automatically (run tooling audit → next step); off always stops
-- If context fills up (3+ auto-advanced steps), suggest /clear and re-invoke /cpw-next-step
+- `--phase` flag: ALWAYS stop between phases, regardless of effective autoAdvance. Report:
+  ```
+  Phase N complete. UAT next.
+
+  Next: continue with `/cpw-next-step` for UAT.
+  ```
+- If context fills up (3+ auto-advanced steps), suggest /clear and re-invoke /cpw-next-step (add `--phase` if it was active)
 
 ## 3. Phase validation (auto-triggered when all steps are done)
 

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

@@ -267,12 +267,20 @@ Save responses in `.planning/config.json`:
   "modelProfile": "quality|balanced|budget",
   "modelOverrides": {},
   "gitStrategy": "trunk-based|feature-branch|gitflow",
-  "commitPlanning": false
+  "commitPlanning": false,
+  "toolingSources": ["skills.sh", "claude-code-templates"],
+  "maxConsecutiveFailures": 3,
+  "autoReflect": "remind"
 }
 ```
 
 If the user has no preference, use defaults (off/standard/balanced/no).
 
+Advanced settings (not asked during interview — edit `.planning/config.json` directly):
+- `toolingSources`: where to search for skills/MCPs during tooling audit (default: `["skills.sh", "claude-code-templates"]`)
+- `maxConsecutiveFailures`: halt auto-advance after N failures in same stage (default: 3 for auto, 5 for yolo)
+- `autoReflect`: process learning queue automatically (`off` / `remind` / `auto`, default: `remind`)
+
 **If `commitPlanning: true`:**
 - Remove `.planning/` from `.gitignore`
 - Planning artifacts (config, learnings, decisions, debug sessions) will be tracked in git

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

@@ -0,0 +1,119 @@
+---
+description: "Update claude-pw framework — diff, merge, apply intelligently"
+---
+
+## 1. Check version
+
+```bash
+INSTALLED=$(cat .claude/.claude-pw-version 2>/dev/null || echo "0.0.0")
+AVAILABLE=$(npx @claude-pw/framework --version 2>/dev/null)
+```
+
+If same version: "Already up to date at v${INSTALLED}." STOP.
+If different: show "Update available: v${INSTALLED} → v${AVAILABLE}"
+
+## 2. Extract new templates
+
+```bash
+rm -rf /tmp/cpw-update
+npx @claude-pw/framework --extract /tmp/cpw-update
+```
+
+Read `/tmp/cpw-update/RELEASES.md` and show changelog entries between installed and available versions.
+
+## 3. Diff files
+
+Compare each file in these categories:
+
+| Category | Project path | Template path |
+|----------|-------------|---------------|
+| Commands | `.claude/commands/*.md` | `/tmp/cpw-update/claude/commands/*.md` |
+| Agents | `.claude/agents/*.md` | `/tmp/cpw-update/claude/agents/*.md` |
+| Rules | `.claude/rules/*.md` | `/tmp/cpw-update/claude/rules/*.md` |
+| Hooks | `.claude/hooks/*.js` | `/tmp/cpw-update/claude/hooks/*.js` |
+| Settings | `.claude/settings.json` | `/tmp/cpw-update/claude/settings.json` |
+| Config | `.planning/config.json` | `/tmp/cpw-update/planning/config.json` |
+
+For each file, classify:
+- **NEW** — in template only → will be added
+- **UNCHANGED** — identical content → skip
+- **UPDATED** — template changed, user didn't modify → safe overwrite
+- **CONFLICT** — both changed → needs merge
+- **CUSTOM** — in project only → preserve (user's own file)
+
+Heuristic for UPDATED vs CONFLICT: if project file differs from new template AND contains sections/lines not present in the new template, it's a CONFLICT. If the new template is a strict superset of the project file (only additions), it's UPDATED.
+
+## 4. Present summary
+
+```
+Update: v{INSTALLED} → v{AVAILABLE}
+
+Commands:
+  UPDATED   cpw-next-step.md (+25 lines)
+  UNCHANGED cpw-startup.md
+  NEW       cpw-new-command.md
+  ...
+
+Agents:
+  UPDATED   implementer.md (+20 lines)
+  CONFLICT  researcher.md — you added custom content
+  CUSTOM    my-agent.md — your file, preserved
+  ...
+
+Config:
+  NEW FIELDS  [list of new fields with defaults]
+
+Apply? (all / review conflicts first / cancel)
+```
+
+## 5. Apply changes
+
+### NEW and UPDATED files:
+Copy from `/tmp/cpw-update/` to project. Overwrite safely.
+
+### CONFLICT files:
+For each conflicted file:
+1. Read user's version (project file)
+2. Read new template version (`/tmp/cpw-update/`)
+3. Identify user's custom additions (sections, rules, modifications not in template)
+4. Merge: start with new template, re-add user's custom sections at appropriate locations
+5. Show the merged result to user: "Here's the merged version of [file]. OK? (yes / edit / skip)"
+6. If skip: keep user's version unchanged
+
+### settings.json:
+Merge: add new hooks from template, preserve user's custom hooks. Do NOT overwrite existing hooks.
+
+### config.json:
+Add new fields with defaults. Do NOT overwrite user's existing values.
+
+### CUSTOM files:
+Never touch. Report: "[file] is your custom file — preserved."
+
+## 6. Finalize
+
+Update version:
+```bash
+echo "{AVAILABLE}" > .claude/.claude-pw-version
+```
+
+Clean up:
+```bash
+rm -rf /tmp/cpw-update
+```
+
+Commit:
+`make commit m="chore: update claude-pw to v{AVAILABLE}"`
+
+Report:
+```
+Updated to v{AVAILABLE}.
+
+Next: `/cpw-next-step` to continue with the plan.
+```
+
+## Rollback
+
+If the user reports issues after update:
+- Previous state is in git history: `git diff HEAD~1 -- .claude/`
+- Revert: `git checkout HEAD~1 -- .claude/`
+- Or selectively: `git checkout HEAD~1 -- .claude/agents/researcher.md`