@claude-pw/framework 0.4.0 → 0.5.1

package/README.es.md

@@ -8,6 +8,20 @@ Workflow estructurado para proyectos con Claude Code.
 
 Claude Code es potente pero sin estructura, los proyectos no triviales se vuelven caóticos — sin plan, sin gestión de contexto, sin quality gates, sin continuidad entre sesiones. claude-pw soluciona esto instalando comandos, agentes, reglas y hooks sobre las features nativas de Claude Code. Node.js + markdown, agnóstico al lenguaje.
 
+## Instalación
+
+Requiere [Node.js](https://nodejs.org/) >= 18 y [Claude Code](https://code.claude.com/docs/en/setup).
+
+```bash
+npm install -g @claude-pw/framework
+```
+
+O ejecuta directamente con npx (sin instalar):
+
+```bash
+npx @claude-pw/framework mi-proyecto
+```
+
 ## Inicio rápido
 
 ### Proyecto nuevo

package/README.ja.md

@@ -8,6 +8,20 @@ Claude Code のための構造化プロジェクトワークフロー。
 
 Claude Code は強力ですが、構造がなければ非自明なプロジェクトは混沌とします — 計画なし、コンテキスト管理なし、品質ゲートなし、セッション間の継続性なし。claude-pw は Claude Code のネイティブ機能の上にコマンド、エージェント、ルール、フックをインストールすることでこれを解決します。純粋な Node.js + markdown、言語非依存。
 
+## インストール
+
+[Node.js](https://nodejs.org/) >= 18 と [Claude Code](https://code.claude.com/docs/en/setup) が必要です。
+
+```bash
+npm install -g @claude-pw/framework
+```
+
+または npx で直接実行（インストール不要）：
+
+```bash
+npx @claude-pw/framework my-project
+```
+
 ## クイックスタート
 
 ### 新規プロジェクト

package/README.md

@@ -8,6 +8,20 @@ Structured Project Workflow for Claude Code.
 
 Claude Code is powerful but without structure, non-trivial projects get chaotic — no plan, no context management, no quality gates, no continuity between sessions. claude-pw fixes this by installing commands, agents, rules, and hooks on top of Claude Code's native features. Pure Node.js + markdown, language-agnostic.
 
+## Install
+
+Requires [Node.js](https://nodejs.org/) >= 18 and [Claude Code](https://code.claude.com/docs/en/setup).
+
+```bash
+npm install -g @claude-pw/framework
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx @claude-pw/framework my-project
+```
+
 ## Quick start
 
 ### New project

package/README.pt-br.md

@@ -8,6 +8,20 @@ Fluxo de trabalho estruturado para projetos com Claude Code.
 
 Claude Code é poderoso, mas sem estrutura, projetos não triviais viram caos — sem plano, sem gestão de contexto, sem portões de qualidade, sem continuidade entre sessões. claude-pw resolve isso instalando comandos, agentes, regras e hooks sobre os recursos nativos do Claude Code. Node.js puro + markdown, agnóstico de linguagem.
 
+## Instalação
+
+Requer [Node.js](https://nodejs.org/) >= 18 e [Claude Code](https://code.claude.com/docs/en/setup).
+
+```bash
+npm install -g @claude-pw/framework
+```
+
+Ou execute diretamente com npx (sem instalação):
+
+```bash
+npx @claude-pw/framework my-project
+```
+
 ## Início rápido
 
 ### Novo projeto

package/README.zh-cn.md

@@ -8,6 +8,20 @@ Claude Code 结构化项目工作流。
 
 Claude Code 功能强大，但缺乏结构时，非简单项目会变得混乱——没有计划、没有上下文管理、没有质量门控、会话之间没有连续性。claude-pw 通过在 Claude Code 原生功能（命令、代理、规则、钩子）之上安装结构化工作流来解决这个问题。纯 Node.js + markdown，与编程语言无关。
 
+## 安装
+
+需要 [Node.js](https://nodejs.org/) >= 18 和 [Claude Code](https://code.claude.com/docs/en/setup)。
+
+```bash
+npm install -g @claude-pw/framework
+```
+
+或使用 npx 直接运行（无需安装）：
+
+```bash
+npx @claude-pw/framework my-project
+```
+
 ## 快速开始
 
 ### 新项目

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
@@ -517,7 +546,12 @@ async function main() {
 
   // Root files with template variable substitution
   const vars = { PROJECT_NAME: projectName, DATE: date };
-  if (!fs.existsSync('CLAUDE.md')) copyTemplate(path.join(templatesDir, 'CLAUDE.md.tpl'), 'CLAUDE.md', vars);
+  if (fs.existsSync('CLAUDE.md')) {
+    const backupName = `CLAUDE.md.user-backup`;
+    fs.copyFileSync('CLAUDE.md', backupName);
+    info(`CLAUDE.md existente respaldado en ${backupName}`);
+  }
+  copyTemplate(path.join(templatesDir, 'CLAUDE.md.tpl'), 'CLAUDE.md', vars);
   if (!fs.existsSync('PLAN.md')) copyTemplate(path.join(templatesDir, 'PLAN.md.tpl'), 'PLAN.md', vars);
   if (!fs.existsSync('STATUS.md')) copyTemplate(path.join(templatesDir, 'STATUS.md.tpl'), 'STATUS.md', vars);
   copyIfMissing(path.join(templatesDir, 'CHANGELOG.md'), 'CHANGELOG.md');

package/package.json

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

package/templates/CLAUDE.md.tpl

@@ -1,5 +1,7 @@
 # {{PROJECT_NAME}}
 
+> If `CLAUDE.md.user-backup` exists, it contains your original CLAUDE.md. Review it during `/cpw-startup` and merge any project-specific instructions into this file.
+
 ## Stack
 TODO: Phase 0
 

package/templates/claude/agents/codebase-mapper.md

@@ -30,6 +30,17 @@ Use the exact section headers above — the startup command parses them by name.
 ## Project Context
 After mandatory read, check `.claude/skills/` and `.claude/rules/` — include discovered skills and rules in your Conventions section.
 
+## Tool Strategy
+
+| Priority | Tool | Use for |
+|----------|------|---------|
+| 1st | Glob | File discovery — map structure before reading |
+| 2nd | Grep | Pattern detection — imports, configs, conventions |
+| 3rd | Read | Representative files — 1-2 per module, not everything |
+| 4th | Bash | Dependency analysis — `ls`, `wc`, lockfile parsing |
+
+Scan wide, read selectively. Do NOT read every file — use Glob/Grep to identify what matters, then Read only representative samples.
+
 ## Analysis to perform
 
 ### 1. Stack detection

package/templates/claude/agents/researcher.md

@@ -32,6 +32,16 @@ Your summary report (not the file) is what the command sees immediately. Make th
 ## Project Context
 After mandatory read, check `.claude/skills/` for existing project knowledge on the research topic. Avoid recommending solutions that contradict learned skills.
 
+## Tool Strategy
+
+| Priority | Tool | Use for | Trust |
+|----------|------|---------|-------|
+| 1st | WebFetch | Official docs, READMEs, changelogs (when you have the URL) | High |
+| 2nd | WebSearch | Ecosystem discovery, community patterns, comparisons | Verify first |
+| 3rd | Read + Grep | Existing project code for patterns and prior decisions | High |
+
+**Verification protocol:** If a finding comes only from WebSearch, verify against official docs (WebFetch) before recommending. Mark unverified claims as "LOW confidence" in your output. Training data is 6-18 months stale — prefer live sources.
+
 ## Types of research
 
 ### 1. Libraries/frameworks (BUILD-OR-BUY)

package/templates/claude/agents/spike-explorer.md

@@ -24,6 +24,16 @@ Answer with a clear viable/not-viable verdict. If viable, include the suggested
 ## Project Context
 After mandatory read, check `.claude/skills/` for existing knowledge about the topic — someone may have already explored this.
 
+## Tool Strategy
+
+| Priority | Tool | Use for | Trust |
+|----------|------|---------|-------|
+| 1st | Read + Grep | Check existing code and prior research (docs/research/) | High |
+| 2nd | WebSearch | Find examples, docs, known issues | Verify first |
+| 3rd | Bash (in /tmp) | Test viability with disposable POC | High (empirical) |
+
+Prefer empirical evidence (run it) over theoretical research (read about it). If you can test it in /tmp in under 5 minutes, test it.
+
 1. Investigate: docs, existing code, libs
 2. If you need to try something, do it in /tmp (disposable POC)
 3. Answer the question concretely

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

@@ -60,7 +60,12 @@ The agent:
   - If "yes": implement the fix, run tests, commit
   - Run skill extraction check (see below)
   - Move session to `.planning/debug/resolved/[date]-[title-slug].md`
-  - Report: "Bug resolved. Fix applied and committed."
+  - Report:
+    ```
+    Bug resolved. Fix applied and committed.
+
+    Next: `/cpw-next-step` to continue where you left off.
+    ```
 
 ### Skill extraction check
 After confirming the debug conclusion, run these 5 questions internally:
@@ -107,7 +112,12 @@ If no self-check triggers or gates don't pass: continue normally.
 - If attempts remain:
   "Attempt [N]/[max]. Eliminated causes: [list]. Do you want to continue? (yes/no/increase limit)"
 - If the limit is reached:
-  "All [max] attempts exhausted. Options: (a) increase limit, (b) escalate to /cpw-impact, (c) close as unresolved."
+  ```
+  All [max] attempts exhausted.
+
+  Recommended: close as unresolved and continue with `/cpw-next-step`.
+  Alternatives: (a) increase limit (b) escalate to /cpw-impact
+  ```
 
 ## 5. BETWEEN SESSIONS
 When the user returns (new /cpw-debug or /cpw-next-step that detects an active session):

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

@@ -65,3 +65,10 @@ The agent checks:
 
 If the agent reports "ok": include in diagnostic as passed.
 If problems found: include in diagnostic with the agent's report.
+
+## 5. REPORT
+
+After all checks complete, present the full diagnostic and guide next steps:
+- If everything passed: "Project healthy. Continue with `/cpw-next-step`."
+- If repairs were applied: "Repairs applied. Run `/cpw-health` again to verify, or continue with `/cpw-next-step`."
+- If issues remain unresolved: "Unresolved issues listed above. Fix them manually, then run `/cpw-next-step`."

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

@@ -2,6 +2,10 @@
 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)
 
 ### Handoff detection
@@ -25,19 +29,49 @@ 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)
 
 If stage = CORRECTION:
 - Read "Pending corrections" from STATUS.md
-- Show the list to the user
-- Resolve each correction one by one
-- After fixing all: `make commit m="fix(phase-N): validator corrections"`
-- Report: "Corrections resolved. Re-running phase validation..."
-- Go to step 3 (Phase validation) to re-validate
+- Read "Correction attempts" from session notes (default: 0)
+- Show the list to the user. For each correction, offer:
+  - **Fix** — resolve the correction now
+  - **Defer** — move to next phase as a known issue (logged in plans/decisions.md)
+  - **Skip** — not applicable, remove with justification
+
+- After processing all corrections (fixed, deferred, or skipped):
+  - If any were fixed: `make commit m="fix(phase-N): validator corrections"`
+  - If any were deferred: add to plans/decisions.md as "Deferred from Phase N validation: [description]"
+  - Increment "Correction attempts" in STATUS.md session notes
+
+- If correction attempts >= 2 AND there are still unfixed corrections:
+  ```
+  Phase N has been through 2 correction rounds with remaining issues.
+
+  Options:
+    1. Fix remaining corrections (one more round)
+    2. Defer all remaining to next phase and advance
+    3. Run /cpw-health for a full diagnostic
+  ```
+
+- If all corrections are fixed or deferred:
+  - Re-run phase validation (step 3) — but ONLY for fixed items
+  - Deferred items do NOT block phase advancement
 
 ## 1.4 Branch creation (only at phase start, non-trunk strategies)
 
@@ -239,7 +273,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.
@@ -290,7 +324,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"`
@@ -300,7 +334,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)
@@ -329,7 +364,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)
 
@@ -376,6 +417,7 @@ Wait for its complete report.
   ## Session notes
   - Phase-validator found [X] corrections
   ```
+- If there are deferred corrections from a previous round, do NOT re-add them — they are already in plans/decisions.md
 - Report: "Phase N has pending corrections. Run /cpw-next-step to resolve them."
 - STOP here. The next /cpw-next-step invocation will detect stage = CORRECTION and handle fixes, then re-run phase validation.
 

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

@@ -80,4 +80,9 @@ Add a line to `.planning/quick/log.md`:
 | [date] | [description] | [changed files] | [short commit hash] |
 ```
 
-Report: "Quick task completed. If this generated more work, consider adding it to the plan with /cpw-next-step."
+Report:
+```
+Quick task completed.
+
+Next: `/cpw-next-step` to continue with the plan.
+```

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

@@ -158,6 +158,8 @@ Move processed entries to `.planning/learnings/applied.md` with this format:
 ```
 Remove processed entries from queue.md.
 
+Report: "Learnings applied. Continue with `/cpw-next-step`."
+
 ## 6. Deduplication (only with --dedupe)
 
 ### 6.1 Load destinations
@@ -207,3 +209,5 @@ Unique entries: N (no changes needed)
 - For each similar group: ask whether to apply the consolidated version
 - Apply approved changes with Edit
 - `make commit m="learn: deduplicate learnings"`
+
+Report: "Deduplication complete. Continue with `/cpw-next-step`."

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
@@ -314,8 +322,14 @@ Present the plan phase by phase for review:
 
 ## 6. COMMIT AND START
 - `make commit m="chore: initial plan from startup ([mode])"`
-- Report: "Plan generated. Run `/clear` first to reset context, then:"
-- "  1. `/cpw-discuss` — clarify ambiguities before building (recommended)"
-- "  2. `/cpw-todos` — review pending todos before starting"
-- "  3. `/cpw-next-step` — start Phase 0 directly"
 - IMPORTANT: startup fills the context window significantly. Always recommend `/clear` before continuing.
+- Report:
+  ```
+  Plan generated and committed.
+
+  Next: run `/clear`, then `/cpw-next-step`
+
+  Optional before starting:
+    /cpw-discuss — clarify ambiguities for the current phase
+    /cpw-todos  — review pending todos
+  ```

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

@@ -45,7 +45,7 @@ Append to `.planning/quick/log.md`:
 ```
 
 ### 5. Confirm and continue
-Report: "Captured: [description]. Continue with current work."
+Report: "Captured: [description]. Continue with `/cpw-next-step`."
 Do NOT change context, read additional files, or start working on the todo.
 
 ---
@@ -98,3 +98,6 @@ Actions:
 
 ### Action d: Back to list
 - Return to step 2
+
+When the user is done reviewing (no more selections or says "done"):
+Report: "Todo review complete. Continue with `/cpw-next-step`."

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`