@claude-pw/framework 0.3.0

package/templates/claude/hooks/cpw-statusline.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Statusline for claude-pw — writes context metrics to bridge file
+// Receives JSON on stdin from Claude Code statusline system
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id || 'unknown';
+    const usedPct = Math.floor(data.context_window?.used_percentage || 0);
+    const remainingPct = Math.floor(data.context_window?.remaining_percentage || 100);
+    const model = data.model?.display_name || 'Claude';
+    const cost = data.cost?.total_cost_usd || 0;
+
+    // Write bridge file for context monitor hook
+    const bridge = path.join(os.tmpdir(), `cpw-ctx-${sessionId}.json`);
+    fs.writeFileSync(bridge, JSON.stringify({ used_pct: usedPct, remaining_pct: remainingPct, ts: Math.floor(Date.now() / 1000) }));
+
+    // Display statusline
+    if (usedPct >= 80) {
+      process.stdout.write(`\x1b[31m${model} │ ctx ${usedPct}% ⚠ CRITICAL\x1b[0m │ $${cost}\n`);
+    } else if (usedPct >= 65) {
+      process.stdout.write(`\x1b[33m${model} │ ctx ${usedPct}% ⚠ WARNING\x1b[0m │ $${cost}\n`);
+    } else {
+      process.stdout.write(`${model} │ ctx ${usedPct}% │ $${cost}\n`);
+    }
+  } catch (e) {
+    // Silent fail — never break the statusline
+  }
+});

package/templates/claude/rules/git.md

@@ -0,0 +1,27 @@
+---
+globs: [".husky/**", ".git/hooks/**"]
+---
+# Git
+- Conventional Commits: type(scope): description
+- Types: feat, fix, docs, chore, refactor, test, ci
+- NEVER --no-verify
+- ALWAYS make commit / make push
+- One step = one atomic commit
+- Read gitStrategy from .planning/config.json to determine branching behavior
+
+## Strategy: trunk-based (default)
+- Commit and push directly to main/master
+- No branches needed
+
+## Strategy: feature-branch
+- At phase start: create branch `phase-N/[description]` from main
+- Commit to branch during steps
+- At phase end (after UAT): create PR to main, do NOT push directly to main
+- After PR merged: pull main, start next phase branch from main
+
+## Strategy: gitflow
+- Work from develop branch (create if it doesn't exist)
+- At phase start: create branch `feature/phase-N-[description]` from develop
+- Commit to branch during steps
+- At phase end (after UAT): create PR to develop, do NOT push directly to develop
+- Release branches created separately when ready to ship

package/templates/claude/rules/interfaces.md

@@ -0,0 +1,9 @@
+---
+globs: ["src/interfaces/**"]
+---
+# Interfaces
+- Do NOT modify without RFC in plans/decisions.md
+- Change -> update docs/interfaces.md + tests/contracts/
+- Significant change -> /cpw-impact
+- Strict types, no any/unknown without justification
+- Each interface defines error types

package/templates/claude/rules/testing.md

@@ -0,0 +1,8 @@
+---
+globs: ["tests/**", "**/*.test.*", "**/*.spec.*"]
+---
+# Testing
+- describe("[Module] - [Function]", ...)
+- Contract: validate interface, not implementation
+- Unit: no real I/O, use mocks
+- New module -> contract tests first

package/templates/claude/settings.json

@@ -0,0 +1,42 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node .claude/hooks/cpw-statusline.js"
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "prompt=\"$CLAUDE_USER_PROMPT\"; if [ ${#prompt} -gt 500 ] && ! echo \"$prompt\" | grep -qiE '(recuerda:|remember:)'; then exit 0; fi; if echo \"$prompt\" | grep -qiE '(\\?$|^(please |can you |could you |por favor |puedes |podrias |ayudame ))'; then exit 0; fi; if echo \"$prompt\" | grep -qiE '(^no[, ]|no uses|no hagas|don.t use|actually|en realidad|mejor usa|use .+ not|instead of|en vez de|nunca |always |siempre |recuerda:|remember:)'; then echo \"[CORRECTION DETECTED] Capture this correction in .planning/learnings/queue.md as a new entry with this exact format:\\n---\\n- **Date**: [today]\\n- **Correction**: [exact user correction text]\\n- **Context**: [what you were doing when corrected]\\n- **Command**: [active command from STATUS.md or the current slash command, e.g., cpw-next-step, cpw-debug, cpw-quick, or 'none' if no command is active]\\n- **Pattern**: [explicit if contains remember:/recuerda:, guardrail if contains nunca/always/siempre/never, correction for the rest]\\n- **Confidence**: [0.90 for explicit, 0.80 for guardrail, 0.70 for correction]\\n- **Validated**: no\\n---\"; fi"
+        }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "queue='.planning/learnings/queue.md'; if [ -f \"$queue\" ] && grep -qE '^- \\*\\*Date\\*\\*:' \"$queue\" 2>/dev/null; then count=$(grep -c '^- \\*\\*Date\\*\\*:' \"$queue\" 2>/dev/null || echo 0); echo \"[AUTO-REFLECT] $count pending learning(s) in queue. Run /cpw-reflect to process them.\"; fi"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "node .claude/hooks/cpw-context-monitor.js"
+        }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{
+          "type": "command",
+          "command": "echo 'Update STATUS.md if you changed stage'"
+        }]
+      }
+    ]
+  }
+}

package/templates/docs/architecture.md

@@ -0,0 +1,4 @@
+# Architecture
+
+## Stack
+TODO: Phase 0, Step 0.1

package/templates/docs/codebase-map.md

@@ -0,0 +1,3 @@
+# Codebase Map
+
+TODO: Generated by /cpw-startup

package/templates/docs/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+TODO: Generated by /cpw-startup or defined in Phase 0

package/templates/docs/interfaces.md

@@ -0,0 +1,10 @@
+# Module Interfaces
+
+## Modules
+TODO: Phase 1
+
+## Diagram
+TODO: Step 1.3
+
+## Contracts
+TODO: With src/interfaces/

package/templates/docs/tech-debt.md

@@ -0,0 +1,3 @@
+# Tech Debt and Concerns
+
+TODO: Generated by /cpw-startup

package/templates/docs/tooling.md

@@ -0,0 +1,15 @@
+# Skills and MCP Servers
+
+## Installed
+
+| Name | Type | Domain | Use in the project | Installed on |
+|------|------|--------|-------------------|-------------|
+
+## Evaluated and discarded
+
+| Name | Reason |
+|------|--------|
+
+## Notes
+- Only install what has clear use in the plan
+- Review each phase if something new is needed

package/templates/gitignore

@@ -0,0 +1,17 @@
+# claude-pw - session state (always personal)
+STATUS.md
+
+# claude-pw - planning (gitignored by default, set commitPlanning: true in .planning/config.json to track)
+.planning/
+
+# Claude Code - local config
+.claude/settings.local.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editors
+*.swp
+*.swo
+*~

package/templates/husky/pre-commit

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -e
+
+echo "Pre-commit..."
+
+echo "  -> Lint..."
+make lint || { echo "  x Lint FAILED"; exit 1; }
+
+echo "  -> Format..."
+make format-check || { echo "  x Format FAILED"; exit 1; }
+
+echo "  -> Types..."
+make typecheck || { echo "  x Typecheck FAILED"; exit 1; }
+
+echo "  -> Tests..."
+make test || { echo "  x Tests FAILED"; exit 1; }
+
+if [ -d "tests/contracts" ] && [ "$(ls -A tests/contracts 2>/dev/null)" ]; then
+  echo "  -> Contracts..."
+  make test-contracts || { echo "  x Contracts FAILED"; exit 1; }
+fi
+
+echo "Pre-commit OK"

package/templates/planning/config.json

@@ -0,0 +1,11 @@
+{
+  "autoAdvance": "off",
+  "granularity": "standard",
+  "modelProfile": "balanced",
+  "modelOverrides": {},
+  "commitPlanning": false,
+  "toolingSources": ["skills.sh", "claude-code-templates"],
+  "maxConsecutiveFailures": null,
+  "gitStrategy": "trunk-based",
+  "autoReflect": "remind"
+}

package/templates/planning/learnings/applied.md

@@ -0,0 +1,3 @@
+# Applied learnings
+
+<!-- Format v2: metadata blocks separated by --- -->

package/templates/planning/learnings/queue.md

@@ -0,0 +1,5 @@
+# Captured corrections
+
+<!-- Format v2: metadata blocks separated by --- -->
+<!-- Pattern: explicit (0.90) | guardrail (0.80) | correction (0.70) -->
+<!-- Validated: no (pending) | yes (validated by /cpw-reflect) -->

package/templates/planning/quick/log.md

@@ -0,0 +1,4 @@
+# Quick log & Todos
+
+<!-- Format v2: metadata blocks separated by --- -->
+<!-- Status: pending | in-progress | done | dismissed -->

package/templates/plans/decisions.md

@@ -0,0 +1,9 @@
+# Decisions
+
+| # | Phase | Decision | Alternatives | Reason | Impact | Date |
+|---|-------|----------|-------------|--------|--------|------|
+
+## Interface RFCs
+
+| # | Module | Change | Status | Date |
+|---|--------|--------|--------|------|

package/templates/plans/phase-0.md

@@ -0,0 +1,57 @@
+# Phase 0: Stack and Scaffolding
+
+## Objective
+Define technologies, structure, toolchain, and environment setup.
+
+## Required context
+- PLAN.md
+- Functional requirements
+
+## Steps
+
+### Step 0.1: Stack definition
+- **Input:** Project requirements. If docs/codebase-map.md exists (from /cpw-startup), use it as a base.
+- **Output:** docs/architecture.md
+- **Done criterion:** Document approved
+- **Status:** [ ]
+
+### Step 0.2: Repo structure
+- **Requires:** 0.1
+- **Input:** docs/architecture.md
+- **Output:** Directories created
+- **Done criterion:** `tree -L 2` matches
+- **Status:** [ ]
+
+### Step 0.3: Skills and MCPs
+- **Requires:** 0.1, 0.2
+- **Input:** docs/architecture.md, defined stack, identified modules
+- **Output:** List of installed skills/MCPs, docs/tooling.md with justification
+- **Done criterion:** Skills/MCPs installed and verified working
+- **Status:** [ ]
+- **Notes:** Evaluate skills and MCP servers that accelerate development based on the project domain. Search by domain (e.g.: admin UI, video processing, DB management), do NOT overload -- only what has clear use in the plan. Document what was installed and why.
+
+### Step 0.4: Makefile + toolchain + changelog auto-gen
+- **Requires:** 0.3
+- **Input:** Stack + structure + installed skills
+- **Output:** Makefile, lint/format/test configs, changelog tooling
+- **Done criterion:** `make lint`, `make test`, `make build` OK
+- **Status:** [ ]
+
+### Step 0.5: Pre-commit + CI/CD + versioning
+- **Requires:** 0.4
+- **Input:** Configured toolchain
+- **Output:** Pre-commit hook, CI pipeline, semver
+- **Done criterion:** Pre-commit blocks broken commits, CI runs on push
+- **Status:** [ ]
+
+### Step 0.6: Setup Claude Code
+- **Requires:** 0.5
+- **Input:** All of the above
+- **Output:** CLAUDE.md, rules, commands, agents adjusted to the actual stack
+- **Done criterion:** /cpw-next-step works
+- **Status:** [ ]
+
+## Gate
+- [ ] `make check` passes
+- [ ] Pre-commit blocks broken commits
+- [ ] Claude Code tooling functional

package/templates/plans/phase-1.md

@@ -0,0 +1,49 @@
+# Phase 1: Interfaces and Modules
+
+## Objective
+Define modules, interfaces, and contracts before implementing.
+
+## Required context
+- docs/architecture.md
+- PLAN.md
+
+## Steps
+
+### Step 1.1: Module identification
+- **Input:** Requirements + architecture.md
+- **Output:** List in docs/interfaces.md
+- **Done criterion:** Modules with name, responsibility, boundaries
+- **Status:** [ ]
+
+### Step 1.2: Public interfaces
+- **Requires:** 1.1
+- **Input:** List of modules
+- **Output:** src/interfaces/ (one per module)
+- **Done criterion:** Compiles, strict types
+- **Status:** [ ]
+
+### Step 1.3: Contracts between modules
+- **Requires:** 1.2
+- **Input:** Interfaces
+- **Output:** Diagram in docs/
+- **Done criterion:** No circular deps
+- **Status:** [ ]
+
+### Step 1.4: Contract tests
+- **Requires:** 1.3
+- **Input:** Interfaces
+- **Output:** tests/contracts/ with stubs
+- **Done criterion:** `make test-contracts` passes
+- **Status:** [ ]
+
+### Step 1.5: Interface lock
+- **Requires:** 1.4
+- **Input:** All
+- **Output:** Interfaces in main, active RFC
+- **Done criterion:** Merged
+- **Status:** [ ]
+
+## Gate
+- [ ] Interfaces compile
+- [ ] Contract tests pass
+- [ ] docs/interfaces.md complete