@claude-pw/framework 0.7.0 → 0.8.0

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.7.0",
+  "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

@@ -8,10 +8,6 @@ description: "Load context and execute the next pipeline stage"
 
 ## 0. Health check (session start)
 
-### Orphan phase-active cleanup
-If `.planning/.phase-active` exists AND `--phase` flag is NOT active:
-- Delete the file (leftover from interrupted session)
-
 ### Post-update detection
 If `.planning/.updated-from` exists:
 - Read the file — it contains the previous version
@@ -270,7 +266,7 @@ Estimated context resets: [N / based on step count, suggest /clear every 3 steps
 ```
 
 Ask: "Execute this plan? (yes / adjust / cancel)"
-- **yes**: create `.planning/.phase-active` (enables auto-approve for tool permissions), then proceed with auto-advance
+- **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)
 
@@ -580,7 +576,6 @@ If all deliverables passed (or issues were fixed):
   ## Session notes
   - (empty)
   ```
-- Delete `.planning/.phase-active` if it exists (re-enables normal tool permissions)
 - If `--phase` flag is active: STOP. Do NOT advance to next phase. Report:
   ```
   Phase N complete. UAT passed.

package/templates/claude/settings.json

@@ -4,15 +4,6 @@
     "command": "node .claude/hooks/cpw-statusline.js"
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "",
-        "hooks": [{
-          "type": "command",
-          "command": "bash .claude/hooks/cpw-phase-approve.sh"
-        }]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "matcher": "",

package/templates/claude/hooks/cpw-phase-approve.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-# Auto-approve tool calls during --phase execution
-# Created by: /cpw-next-step --phase (creates .planning/.phase-active)
-# Removed by: /cpw-next-step at UAT or phase end
-
-PHASE_FILE=".planning/.phase-active"
-
-if [ -f "$PHASE_FILE" ]; then
-  # Check for stale file (>24h)
-  if [ "$(find "$PHASE_FILE" -mmin +1440 2>/dev/null)" ]; then
-    rm -f "$PHASE_FILE"
-    exit 0
-  fi
-  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"--phase active: plan approved by user"}}'
-fi
-exit 0