@claude-pw/framework 0.6.1 → 0.8.0

package/README.es.md

@@ -129,7 +129,7 @@ Issue capturado. ¿Arreglar ahora? (sí/no)
 |---------|----------|
 | `/cpw-startup` | Sesión de discovery — detecta modo, entrevista, genera plan |
 | `/cpw-discuss` | Captura preferencias y resuelve ambigüedades antes de construir |
-| `/cpw-next-step` | Ejecuta pipeline, cierra pasos, valida fases, corre UAT |
+| `/cpw-next-step` | Ejecuta pipeline, cierra pasos, valida fases, corre UAT (`--phase` para planear + auto-avanzar toda la fase) |
 | `/cpw-pause` | Guarda estado de sesión para retomar después |
 | `/cpw-quick` | Tarea ad-hoc fuera del pipeline (detección de scope-creep, `--auto`) |
 | `/cpw-debug` | Sesión de debug persistente — sobrevive resets de contexto |
@@ -137,6 +137,7 @@ Issue capturado. ¿Arreglar ahora? (sí/no)
 | `/cpw-todos` | Captura ideas para después o revisa todos pendientes |
 | `/cpw-reflect` | Revisa correcciones capturadas, convierte en learnings (`--scan-history`, `--dedupe`) |
 | `/cpw-impact` | Analiza impacto de decisiones en todo el plan |
+| `/cpw-update` | Actualización inteligente del framework — diff, merge de conflictos, preserva customizaciones |
 
 ## Configuración
 

package/README.ja.md

@@ -129,7 +129,7 @@ Issue captured. Fix now? (yes/no)
 |---------|-------------|
 | `/cpw-startup` | ディスカバリーセッション — モード検出、インタビュー、計画生成 |
 | `/cpw-discuss` | ビルド前に好みの把握と曖昧さの解消 |
-| `/cpw-next-step` | パイプライン実行、ステップクローズ、フェーズバリデーション、UAT 実行 |
+| `/cpw-next-step` | パイプライン実行、ステップクローズ、フェーズバリデーション、UAT 実行（`--phase` でフェーズ全体を計画 + 自動実行）|
 | `/cpw-pause` | セッション状態を保存して後で再開 |
 | `/cpw-quick` | パイプライン外のアドホックタスク（スコープクリープ検出、`--auto`） |
 | `/cpw-debug` | 永続デバッグセッション — コンテキストリセット後も継続 |
@@ -137,6 +137,7 @@ Issue captured. Fix now? (yes/no)
 | `/cpw-todos` | アイデアの記録または保留中の TODO の確認 |
 | `/cpw-reflect` | キャプチャした修正をレビューし、学習に変換（`--scan-history`, `--dedupe`） |
 | `/cpw-impact` | 計画全体にわたる意思決定の影響分析 |
+| `/cpw-update` | スマートフレームワーク更新 — 差分、コンフリクトマージ、カスタマイズ保持 |
 
 ## 設定
 

package/README.md

@@ -129,7 +129,7 @@ Issue captured. Fix now? (yes/no)
 |---------|-------------|
 | `/cpw-startup` | Discovery session — detect mode, interview, generate plan |
 | `/cpw-discuss` | Capture preferences and resolve ambiguities before building |
-| `/cpw-next-step` | Execute pipeline, close steps, validate phases, run UAT |
+| `/cpw-next-step` | Execute pipeline, close steps, validate phases, run UAT (`--phase` to plan + auto-advance entire phase) |
 | `/cpw-pause` | Save session state for later resume |
 | `/cpw-quick` | Ad-hoc task outside the pipeline (scope-creep detection, `--auto`) |
 | `/cpw-debug` | Persistent debug session — survives context resets |
@@ -137,6 +137,7 @@ Issue captured. Fix now? (yes/no)
 | `/cpw-todos` | Capture ideas for later or review pending todos |
 | `/cpw-reflect` | Review captured corrections, convert to learnings (`--scan-history`, `--dedupe`) |
 | `/cpw-impact` | Analyze decision impact across the entire plan |
+| `/cpw-update` | Smart framework update — diff, merge conflicts, preserve customizations |
 
 ## Configuration
 

package/README.pt-br.md

@@ -129,7 +129,7 @@ Issue captured. Fix now? (yes/no)
 |---------|-----------|
 | `/cpw-startup` | Sessão de descoberta — detectar modo, entrevistar, gerar plano |
 | `/cpw-discuss` | Capturar preferências e resolver ambiguidades antes de construir |
-| `/cpw-next-step` | Executar pipeline, fechar etapas, validar fases, executar UAT |
+| `/cpw-next-step` | Executar pipeline, fechar etapas, validar fases, executar UAT (`--phase` para planejar + auto-avançar toda a fase) |
 | `/cpw-pause` | Salvar estado da sessão para retomar depois |
 | `/cpw-quick` | Tarefa avulsa fora do pipeline (detecção de scope-creep, `--auto`) |
 | `/cpw-debug` | Sessão de debug persistente — sobrevive a resets de contexto |
@@ -137,6 +137,7 @@ Issue captured. Fix now? (yes/no)
 | `/cpw-todos` | Capturar ideias para depois ou revisar todos pendentes |
 | `/cpw-reflect` | Revisar correções capturadas, converter em aprendizados (`--scan-history`, `--dedupe`) |
 | `/cpw-impact` | Analisar impacto de decisões em todo o plano |
+| `/cpw-update` | Atualização inteligente do framework — diff, merge de conflitos, preserva customizações |
 
 ## Configuração
 

package/README.zh-cn.md

@@ -129,7 +129,7 @@ UAT 演练：
 |------|------|
 | `/cpw-startup` | 发现会话——检测模式、访谈、生成计划 |
 | `/cpw-discuss` | 构建前捕获偏好和解决歧义 |
-| `/cpw-next-step` | 执行流水线、关闭步骤、验证阶段、运行 UAT |
+| `/cpw-next-step` | 执行流水线、关闭步骤、验证阶段、运行 UAT（`--phase` 规划 + 自动推进整个阶段）|
 | `/cpw-pause` | 保存会话状态以便稍后恢复 |
 | `/cpw-quick` | 流水线外的临时任务（范围蔓延检测、`--auto`） |
 | `/cpw-debug` | 持久化调试会话——跨上下文重置存活 |
@@ -137,6 +137,7 @@ UAT 演练：
 | `/cpw-todos` | 捕获想法或查看待办事项 |
 | `/cpw-reflect` | 审查捕获的修正，转化为学习成果（`--scan-history`、`--dedupe`） |
 | `/cpw-impact` | 分析决策对整个计划的影响 |
+| `/cpw-update` | 智能框架更新 — 差异对比、冲突合并、保留自定义 |
 
 ## 配置
 

package/install.js

@@ -117,13 +117,13 @@ function applyModelProfile(agentsDir, configFile) {
       'phase-validator': 'opus', 'session-recovery': 'opus', debugger: 'opus',
       researcher: 'opus', 'codebase-mapper': 'opus', 'plan-checker': 'opus',
       'spike-explorer': 'opus', 'decision-impact': 'opus', 'interface-reviewer': 'opus',
-      'learning-extractor': 'opus', implementer: 'opus',
+      'learning-extractor': 'opus', implementer: 'opus', 'code-reviewer': 'opus',
     },
     budget: {
       'phase-validator': 'sonnet', 'session-recovery': 'haiku', debugger: 'haiku',
       researcher: 'sonnet', 'codebase-mapper': 'haiku', 'plan-checker': 'haiku',
       'spike-explorer': 'haiku', 'decision-impact': 'haiku', 'interface-reviewer': 'haiku',
-      'learning-extractor': 'haiku', implementer: 'sonnet',
+      'learning-extractor': 'haiku', implementer: 'sonnet', 'code-reviewer': 'sonnet',
     },
   };
 

package/package.json

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

package/templates/claude/agents/code-reviewer.md

@@ -0,0 +1,77 @@
+---
+name: code-reviewer
+description: Code review — security, quality, performance, conventions compliance
+tools: Read, Glob, Grep, Bash
+model: sonnet
+memory: project
+---
+
+> **Mandatory Initial Read**: If your prompt contains a `<files_to_read>` block, you MUST read every listed file before any other action. Skip files marked `(if exists)` when absent. This is your primary context.
+
+## Pipeline Context
+
+### Called by
+- `/cpw-next-step` ACCEPTANCE stage (optional — when step involves significant code changes)
+- User directly for ad-hoc reviews
+
+### Output consumed by
+- `/cpw-next-step` includes review findings in ACCEPTANCE summary
+- User reads directly for ad-hoc reviews
+
+Report problems only. If everything is clean: "Review passed."
+
+## Project Context
+After mandatory read, check `docs/conventions.md` and `.claude/rules/` for project-specific standards to enforce.
+
+## Review dimensions
+
+### 1. Security (check first)
+- Input validation on all external data
+- No hardcoded secrets, tokens, or credentials
+- SQL/NoSQL injection vectors
+- XSS in rendered output
+- Auth/authz on protected routes
+- Sensitive data exposure in logs or errors
+
+### 2. Correctness
+- Logic matches the design intent
+- Edge cases handled (null, empty, boundary values)
+- Error handling: no silent failures, errors propagated or logged
+- Resource cleanup (connections, file handles, timers)
+
+### 3. Performance
+- No N+1 queries or unbounded loops
+- Appropriate use of indexes, caching, pagination
+- No unnecessary re-renders or re-computations
+- Async operations where I/O bound
+
+### 4. Conventions compliance
+- Follows `docs/conventions.md` if it exists
+- Follows `.claude/rules/*.md` patterns
+- Consistent naming, structure, error handling with rest of codebase
+- No `any` / `unknown` without justification (TypeScript)
+
+### 5. Test coverage
+- New code has corresponding tests
+- Edge cases tested
+- Tests are meaningful (not just coverage theater)
+
+## Output format
+
+```
+## Code Review
+
+### Critical (must fix)
+- [file:line] [description]
+
+### Warnings (should fix)
+- [file:line] [description]
+
+### Suggestions (nice to have)
+- [file:line] [description]
+
+### Passed
+- [what was checked and found clean]
+```
+
+If no issues found in a category, omit it. If all clean: "Review passed."

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

@@ -3,6 +3,7 @@ name: codebase-mapper
 description: Analyzes existing codebase and produces structured documentation
 tools: Read, Glob, Grep, Bash
 model: sonnet
+memory: project
 ---
 
 You analyze an existing codebase to document its current state.
@@ -24,6 +25,9 @@ You analyze an existing codebase to document its current state.
 | `## Conventions` | `docs/conventions.md` | Code style rules for the project |
 | `## Integrations` | `docs/architecture.md` | Dependency mapping |
 | `## Concerns` | `docs/tech-debt.md` | Bluefield rewrite prioritization |
+| `## Dependencies` | `docs/architecture.md` | Dependency audit, upgrade planning |
+| `## Patterns` | `docs/architecture.md` | Architecture decisions |
+| `## Dev Workflow` | `docs/tooling.md` | Makefile generation, onboarding |
 
 Use the exact section headers above — the startup command parses them by name.
 
@@ -76,6 +80,22 @@ Scan wide, read selectively. Do NOT read every file — use Glob/Grep to identif
 - Identify services: databases, caches, message queues, cloud services
 - Result: list of integrations with type and usage
 
+### 5.5 Dependency analysis
+- Identify top 10 significant dependencies (skip types packages and basic utils)
+- For each: what it does in THIS project's context, not generic description
+- Flag version constraints that matter (e.g., React 18 vs 19, Next.js 14 vs 15)
+- Note unusual or custom packages (anything not widely known)
+- Result: dependency table with role and notes
+
+### 5.7 Pattern recognition
+Detect these patterns if present:
+- **Monorepo**: packages/, apps/, turbo.json, pnpm-workspace.yaml, lerna.json
+- **State management**: Redux, Zustand, Jotai, Pinia, MobX, Context API
+- **Auth**: NextAuth, Clerk, Auth0, Supabase Auth, custom JWT
+- **Deployment**: vercel.json, netlify.toml, fly.toml, Dockerfile, k8s/
+- **Data flow**: trace how data moves from user action → API → database → response
+- Result: list of detected patterns with confidence
+
 ### 6. Concerns and technical debt
 - Search for: TODO, FIXME, HACK, XXX, TEMP in the code
 - Identify large files (>400 lines)
@@ -109,6 +129,25 @@ The /cpw-startup command handles splitting it into docs/ files.
 ## Integrations
 [table: name, type, usage]
 
+## Dependencies
+| Package | Role in project | Version | Notes |
+|---------|----------------|---------|-------|
+[top 10 significant deps]
+
+## Patterns
+- Monorepo: [yes/no — tool if yes]
+- State: [library or "none"]
+- Auth: [approach]
+- Deploy: [target]
+- Data flow: [user → API → DB → response summary]
+
+## Dev Workflow
+- Install: [command]
+- Dev: [command]
+- Test: [command]
+- Build: [command]
+- Deploy: [command or "manual"]
+
 ## Concerns
 [prioritized list with location]
 ```

package/templates/claude/agents/debugger.md

@@ -3,6 +3,7 @@ name: debugger
 description: Structured debug with scientific method -- state persists between sessions
 tools: Read, Glob, Grep, Bash, Write
 model: sonnet
+memory: project
 ---
 
 Systematic debug. Your state is saved in a file that survives context resets.

package/templates/claude/agents/decision-impact.md

@@ -3,6 +3,7 @@ name: decision-impact
 description: Impact of a decision on the entire plan
 tools: Read, Glob, Grep
 model: sonnet
+maxTurns: 10
 ---
 
 > **Mandatory Initial Read**: If your prompt contains a `<files_to_read>` block, you MUST read every listed file before any other action. Skip files marked `(if exists)` when absent. This is your primary context.

package/templates/claude/agents/implementer.md

@@ -3,6 +3,7 @@ name: implementer
 description: Implements approved design and runs tests in fresh context — keeps orchestrator lean
 tools: Read, Glob, Grep, Bash, Write, Edit
 model: sonnet
+maxTurns: 50
 ---
 
 You receive an approved design and implement it with a fresh context window.

package/templates/claude/agents/interface-reviewer.md

@@ -3,6 +3,7 @@ name: interface-reviewer
 description: Interface consistency
 tools: Read, Glob, Grep
 model: sonnet
+maxTurns: 10
 ---
 
 > **Mandatory Initial Read**: If your prompt contains a `<files_to_read>` block, you MUST read every listed file before any other action. Skip files marked `(if exists)` when absent. This is your primary context.

package/templates/claude/agents/learning-extractor.md

@@ -3,6 +3,8 @@ name: learning-extractor
 description: Analyzes session corrections and extracts actionable learnings
 tools: Read, Glob, Grep
 model: haiku
+memory: project
+maxTurns: 5
 ---
 
 Your job: decide if a correction is a generalizable learning and where it should live.

package/templates/claude/agents/plan-checker.md

@@ -3,6 +3,7 @@ name: plan-checker
 description: Project status without polluting context
 tools: Read, Glob, Grep
 model: sonnet
+maxTurns: 5
 ---
 
 > **Mandatory Initial Read**: If your prompt contains a `<files_to_read>` block, you MUST read every listed file before any other action. Skip files marked `(if exists)` when absent. This is your primary context.

package/templates/claude/agents/researcher.md

@@ -49,10 +49,11 @@ When asked to evaluate options:
 - Search top 3-5 options in npm/pypi/crates/etc.
 - For each one evaluate:
   - Maintenance: last release, commit frequency, open issues
-  - Popularity: downloads, stars
+  - Popularity: downloads, stars, community size
   - API: quality, documentation, examples
   - Size: bundle size, transitive dependencies
   - License: compatible?
+  - Community: adoption trends, known issues, expert opinions
 - Recommend one with justification
 
 ### 2. Architecture/patterns
@@ -79,17 +80,17 @@ Context: [what decision this research feeds]
 Type: [library | architecture | feasibility]
 
 ## Findings
-[concrete findings with data]
+[concrete findings with data — mark each as HIGH/MEDIUM/LOW confidence]
 
 ## Options (if applicable)
-| Option | Pros | Cons | Recommendation |
-|--------|------|------|----------------|
+| Option | Pros | Cons | Community adoption | Recommendation |
+|--------|------|------|-------------------|----------------|
 
 ## Recommendation
 [concrete recommendation with justification]
 
 ## Sources
-- [links to docs, repos, articles]
+[numbered citations — use format: [N] Author/Project. "Title." Platform, Date. URL]
 ```
 
 Report summary to the caller. The detail stays in the file for future reference.

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

@@ -3,6 +3,7 @@ name: spike-explorer
 description: Isolated technical exploration -- tests code and reports feasibility
 tools: Read, Glob, Grep, Bash, WebSearch
 model: sonnet
+maxTurns: 20
 ---
 
 Difference from researcher: you TEST code (disposable POC). The researcher only searches for info.

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

@@ -266,7 +266,7 @@ 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)
+- **yes**: proceed with auto-advance. When delegating to agents during --phase, spawn them with `permissionMode: bypassPermissions` to avoid permission interruptions.
 - **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)