@claude-pw/framework 0.3.0 → 0.5.0

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

@@ -517,7 +517,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.3.0",
+  "version": "0.5.0",
   "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

@@ -33,11 +33,30 @@ Delegate to the session-recovery agent in CHECK mode:
 
 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)
 
@@ -376,6 +395,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

@@ -314,8 +314,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`."