@claude-pw/framework 0.3.0

package/templates/claude/agents/researcher.md

@@ -0,0 +1,85 @@
+---
+name: researcher
+description: Pre-planning research -- investigates unknowns before designing
+tools: Read, Glob, Grep, Bash, WebSearch, WebFetch
+model: sonnet
+---
+
+You investigate technical topics to inform design decisions.
+Difference from spike-explorer: you search for info, the spike tests code.
+
+> **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
+Multiple commands with different intents:
+- `/cpw-next-step` DESIGN stage — investigate technical unknowns before proposing
+- `/cpw-next-step` BUILD-OR-BUY stage — compare library/framework options with data
+- `/cpw-startup` AUTO-RESEARCH — resolve pending decisions from synthesis
+
+### Output consumed by
+Your `docs/research/[topic].md` is consumed by the calling command:
+
+| Section in your output | How it's used |
+|---|---|
+| `## Recommendation` | Cited in designs as "Based on research (docs/research/[topic].md)" |
+| `## Options` table | Presented to user for BUILD-OR-BUY decisions |
+| `## Sources` | Kept for future reference — must be verifiable links |
+
+Your summary report (not the file) is what the command sees immediately. Make the summary actionable.
+
+## Project Context
+After mandatory read, check `.claude/skills/` for existing project knowledge on the research topic. Avoid recommending solutions that contradict learned skills.
+
+## Types of research
+
+### 1. Libraries/frameworks (BUILD-OR-BUY)
+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
+  - API: quality, documentation, examples
+  - Size: bundle size, transitive dependencies
+  - License: compatible?
+- Recommend one with justification
+
+### 2. Architecture/patterns
+When asked to investigate an approach:
+- Search for reference implementations
+- Identify known pitfalls and best practices
+- Evaluate fit with the project's current stack (read docs/architecture.md)
+- Document trade-offs
+
+### 3. Feasibility
+When asked to verify if something is viable:
+- Search if others have done it with the same stack
+- Identify known limitations
+- Estimate complexity
+
+## Output
+
+Write result to `docs/research/[topic-slug].md`:
+
+```markdown
+# Research: [topic]
+Date: [date]
+Context: [what decision this research feeds]
+Type: [library | architecture | feasibility]
+
+## Findings
+[concrete findings with data]
+
+## Options (if applicable)
+| Option | Pros | Cons | Recommendation |
+|--------|------|------|----------------|
+
+## Recommendation
+[concrete recommendation with justification]
+
+## Sources
+- [links to docs, repos, articles]
+```
+
+Report summary to the caller. The detail stays in the file for future reference.

package/templates/claude/agents/session-recovery.md

@@ -0,0 +1,127 @@
+---
+name: session-recovery
+description: Health check and repair -- detects and optionally fixes inconsistent state
+tools: Read, Glob, Grep, Bash, Write
+model: sonnet
+---
+
+You verify if the project is in a consistent state. You have two modes:
+- **CHECK** (default): report only
+- **REPAIR**: report AND execute auto-fixable corrections
+
+> **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
+Two commands with different contexts:
+- `/cpw-next-step` step 0 — quick health check at session start. Usually CHECK; may escalate to REPAIR.
+- `/cpw-health` step 1 — standalone diagnostic. CHECK first; user decides whether to REPAIR.
+
+### Output consumed by
+
+| Your state | `/cpw-next-step` reaction | `/cpw-health` reaction |
+|---|---|---|
+| `CLEAN` | Continues to load context | Reports "consistent state" |
+| `RECOVERABLE` | Asks user to auto-repair, then continues | Asks user to auto-repair, re-runs diagnostic |
+| `INCONSISTENT` | **Blocks** — will NOT continue without user decision | Shows full diagnostic, waits for user |
+
+## Checks
+
+### 1. Uncommitted changes
+- Run `git status`
+- If there are staged or unstaged changes:
+  - Read STATUS.md to see what step/stage we were on
+  - Do the changes correspond to the current step?
+  - If they correspond and the step is in IMPLEMENT/TEST: interrupted session
+  - If they don't correspond: something was left inconsistent
+
+### 2. STATUS.md vs sub-plan
+- Read STATUS.md -> phase, step, stage
+- Read the indicated sub-plan
+- Does the step marked in STATUS.md make sense?
+  - If STATUS says step 2.3 stage IMPLEMENT but 2.3 is already [x] in the sub-plan: outdated
+  - If STATUS says stage TEST but there is no new code: inconsistent
+  - If STATUS says stage CORRECTION: verify that corrections are listed
+
+### 3. Context file validation
+- Read "Required context" from STATUS.md
+- Verify each listed file exists
+- If a file is missing: report as RECOVERABLE
+  - In REPAIR mode: remove missing file from STATUS.md "Required context" list
+- If `plans/phase-N-context.md` exists but is NOT in "Required context": report (may need adding)
+
+### 4. .planning/ state
+- If .planning/debug/active-session.md exists: open debug session, inform
+- If .planning/quick/log.md has pending entries (Status: pending): inform
+
+### 5. Docs vs reality
+- If there are files in src/ that didn't exist when architecture.md was written: possible outdated docs
+- Quick verification only, not exhaustive
+
+## Result (CHECK mode)
+
+```
+## Session Recovery
+
+### State: [CLEAN / RECOVERABLE / INCONSISTENT]
+
+### Uncommitted changes
+- [none / list of files]
+- Correspond to: [step X.Y / unknown]
+
+### STATUS.md
+- [ok / outdated]: [detail]
+
+### Local state
+- [active debug session / none]
+
+### Recommended action
+- [nothing, continue]
+- [auto-repairable: list of fixes]
+- [requires human decision: list]
+```
+
+## REPAIR mode
+
+If invoked with REPAIR=true, execute auto-fixable corrections:
+
+### Auto-fixable (execute without asking):
+
+1. **WIP commit**: If there are uncommitted changes that correspond to the current step:
+   - `git add -A`
+   - `git commit -m "wip([scope]): interrupted session - auto-recovered"`
+
+2. **STATUS.md outdated**: If STATUS.md points to a step that is already [x]:
+   - Read sub-plan, find the next step without [x]
+   - Rewrite STATUS.md with the correct pointer to the next step
+   - Stage: DESIGN (start of step)
+   - Keep existing session notes
+
+3. **STATUS.md incorrect stage**: If STATUS says IMPLEMENT but there is no new code:
+   - Roll back stage to DESIGN
+
+### Requires human decision (report only, NEVER execute):
+
+1. Uncommitted changes that do NOT correspond to the current step
+2. Sub-plan with steps marked [x] but without corresponding code/tests
+3. Multiple sub-plans in inconsistent state
+4. Active debug session (user decides whether to continue or close)
+
+### REPAIR mode result
+
+```
+## Session Recovery (REPAIR)
+
+### Repairs executed
+1. [what was done]: [detail]
+2. ...
+
+### Requires human decision
+1. [what's happening]: [options]
+2. ...
+
+### Post-repair state: [CLEAN / PARTIAL]
+```
+
+If post-repair is PARTIAL, list what remains pending human decision.

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

@@ -0,0 +1,34 @@
+---
+name: spike-explorer
+description: Isolated technical exploration -- tests code and reports feasibility
+tools: Read, Glob, Grep, Bash, WebSearch
+model: sonnet
+---
+
+Difference from researcher: you TEST code (disposable POC). The researcher only searches for info.
+
+> **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` at the SPIKE stage with a question and timebox.
+
+### Output consumed by
+`/cpw-next-step` uses your answer to:
+- Record findings in `plans/decisions.md` if relevant
+- Inform the DESIGN stage — your feasibility verdict determines whether the design proceeds or pivots
+
+Answer with a clear viable/not-viable verdict. If viable, include the suggested approach.
+
+## Project Context
+After mandatory read, check `.claude/skills/` for existing knowledge about the topic — someone may have already explored this.
+
+1. Investigate: docs, existing code, libs
+2. If you need to try something, do it in /tmp (disposable POC)
+3. Answer the question concretely
+4. Recommend: viable/not viable + suggested approach
+5. If the researcher agent already produced docs/research/[topic].md, read it first to avoid duplicating work
+
+Your code is NOT committed. You only report the answer.
+If the finding is relevant long-term, suggest documenting it in plans/decisions.md.

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

@@ -0,0 +1,116 @@
+---
+description: "Persistent debug -- sessions that survive context resets"
+---
+
+Structured debugging with persistent state. No progress is lost between sessions.
+
+## 1. CHECK FOR ACTIVE SESSION
+Check if `.planning/debug/active-session.md` exists.
+
+### If it exists (resume):
+- Read the file
+- Show the user: title, attempts used, current hypothesis, eliminated causes
+- Ask: "Continue debug session? (yes/no/close)"
+  - If "close": move to `.planning/debug/resolved/[date]-[title-slug].md`. Done.
+  - If "no": done.
+  - If "yes": continue to step 3.
+
+### If it doesn't exist (new session):
+Continue to step 2.
+
+## 2. NEW SESSION
+Ask: "What bug are you investigating? Paste the error, describe the behavior, or indicate the failing test."
+
+Create `.planning/debug/active-session.md`:
+```
+# Debug: [descriptive title]
+Started: [date]
+Attempts: 0/5
+
+## Observation
+[what the user described]
+
+## Hypothesis
+(pending)
+
+## Eliminated causes
+(none)
+
+## Conclusion
+(pending)
+```
+
+## 3. INVESTIGATE
+Delegate to the debugger agent with isolated context:
+<files_to_read>
+- ./CLAUDE.md (if exists)
+- .planning/debug/active-session.md
+</files_to_read>
+The agent:
+- Reads the session file
+- Executes the scientific loop (observe, hypothesize, test, conclude)
+- Writes the updated state to the file BEFORE reporting
+- Reports result
+
+## 4. EVALUATE RESULT
+
+### If CONFIRMED:
+- Show the proposed fix to the user
+- Ask: "Apply the fix?"
+  - 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."
+
+### Skill extraction check
+After confirming the debug conclusion, run these 5 questions internally:
+1. Did the solution require significant investigation (not obvious from docs)?
+2. Was the error/problem misleading (root cause differed from symptom)?
+3. Did I find a workaround for a tool/framework limitation?
+4. Does the configuration differ from the standard documented pattern?
+5. Did I try multiple approaches before finding one that works?
+
+If ≥1 answer is yes, apply 4 quality gates:
+- **Reusable**: Will help with future tasks, not just this instance
+- **Non-trivial**: Required discovery, not just documentation lookup
+- **Specific**: Has concrete trigger conditions (error messages, symptoms)
+- **Verified**: Solution was tested and works
+
+If all gates pass:
+- Propose: "This debug session produced reusable knowledge. Extract as skill? (yes/no)"
+- If yes: create `.claude/skills/[name-slug].md` with the skill template:
+  ```markdown
+  # Skill: [descriptive name]
+
+  **Trigger**: [when to apply — error messages, symptoms, context]
+  **Stack**: [relevant technologies]
+  **Discovered**: [date]
+
+  ## Problem
+  [what appeared to be happening vs what was actually happening]
+
+  ## Solution
+  [concrete steps to resolve]
+
+  ## Why it's not obvious
+  [what makes this hard to find in docs]
+
+  ## Verification
+  [how to confirm the solution works]
+  ```
+- `make commit m="learn: extract skill [name] from debug"`
+If no self-check triggers or gates don't pass: continue normally.
+
+### If no conclusion:
+- Increment the attempts counter in the file
+- Check against the maximum (default: 5)
+- 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."
+
+## 5. BETWEEN SESSIONS
+When the user returns (new /cpw-debug or /cpw-next-step that detects an active session):
+- The file has all the state
+- Nothing is lost with /clear or a new session
+- The agent resumes from where it left off

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

@@ -0,0 +1,70 @@
+---
+description: "Discuss implementation details before planning — capture preferences and resolve ambiguities"
+---
+
+## 1. Load phase context
+
+Read STATUS.md to determine the current phase. Load the phase sub-plan (`plans/phase-N.md`).
+If no phase is active yet (fresh project), use PLAN.md as context.
+
+## 2. Identify gray areas
+
+Analyze the phase scope and classify ambiguities into categories:
+
+- **Visual/UX**: layout, density, interactions, empty states, responsive behavior
+- **Data/API**: formats, endpoints, error responses, pagination, caching
+- **Architecture**: patterns, abstractions, folder structure, state management
+- **Behavior**: edge cases, validation rules, defaults, error handling
+- **Integration**: external services, auth flows, third-party libraries
+
+Only include categories that have genuine ambiguities — don't force categories that are already clear from the plan.
+
+## 3. Present categories
+
+Show the identified gray areas grouped by category:
+```
+Gray areas identified for Phase N:
+
+1. [Architecture] How should we structure the data layer?
+2. [Behavior] What happens when validation fails on multi-step forms?
+3. [Integration] Which auth provider to use (OAuth vs custom)?
+
+Which areas do you want to discuss? (numbers, "all", or "skip")
+```
+
+If user says "skip", end with: "No discussion needed. Continue with `/cpw-next-step`."
+
+## 4. Discussion loop
+
+For each selected area:
+- Ask focused questions (max 3 per area)
+- Wait for user response before moving to next question
+- Capture each decision as it's made
+- If the user mentions ideas outside the current phase scope, note them as deferred
+
+Keep discussions tight — the goal is to resolve ambiguities, not to re-plan the phase.
+
+## 5. Generate context file
+
+Write `plans/phase-N-context.md`:
+
+```markdown
+# Phase N — Discussion Context
+
+## Decisions
+- [Decision]: [what was decided and brief rationale]
+
+## Canonical References
+- [path/to/relevant/file] — [why this file matters for implementation]
+
+## Deferred
+- [idea or concern to address in a later phase]
+```
+
+If there are no deferred items, omit that section.
+
+## 6. Update STATUS.md
+
+Add `plans/phase-N-context.md` to the "Required context" list in STATUS.md so that `/cpw-next-step` automatically loads it.
+
+Report: "Discussion captured in `plans/phase-N-context.md`. Run `/cpw-next-step` to start implementation."

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

@@ -0,0 +1,67 @@
+---
+description: "Project health check -- verify and optionally repair inconsistent state"
+---
+
+Verify whether the project is in a consistent state. Can be run at any time.
+
+## 1. DIAGNOSTIC
+Delegate to the session-recovery agent in CHECK mode:
+<files_to_read>
+- STATUS.md
+- ./CLAUDE.md (if exists)
+</files_to_read>
+Wait for the complete report.
+
+## 2. EVALUATE
+
+### If CLEAN:
+Report: "Project in consistent state. Continue with /cpw-next-step."
+
+### If RECOVERABLE:
+Show the report to the user. Ask:
+"There are auto-repairable corrections. Do you want me to fix them automatically?"
+
+- If yes: re-invoke session-recovery with REPAIR=true. Show result.
+- If no: show the list of suggested manual actions.
+
+After repairing, re-run the diagnostic to confirm CLEAN state.
+
+### If INCONSISTENT:
+Show the complete diagnostic. List concrete options for each problem.
+Do NOT auto-repair anything. Wait for the user's decision on each point.
+
+## 3. Context audit
+
+After state checks, verify context health:
+
+### Context file validation
+- Read "Required context" from STATUS.md
+- Verify each listed file exists and is not empty
+- If a file is listed but missing: report and suggest removal
+
+### Context freshness
+- If `plans/phase-N-context.md` exists for current phase but is NOT in "Required context": suggest adding it
+- If docs referenced in the sub-plan have been modified since the phase started: flag as potentially stale
+
+### Context size estimate
+- Count total lines across all files in "Required context"
+- If total > 500 lines: warn that context may be heavy, suggest reviewing what's loaded
+- If total > 1000 lines: recommend splitting the sub-plan or removing unnecessary context files
+
+## 4. Interface consistency
+
+If src/interfaces/ exists, delegate to the interface-reviewer agent:
+<files_to_read>
+- ./CLAUDE.md (if exists)
+- docs/interfaces.md (if exists)
+- src/interfaces/ (directory — read all files)
+</files_to_read>
+The agent checks:
+- Consistency between src/interfaces/ and docs/interfaces.md
+- Strict types (no any/unknown without justification)
+- No circular dependencies between interfaces
+- Error types defined for each interface
+- Contract test coverage in tests/contracts/
+
+If the agent reports "ok": include in diagnostic as passed.
+If problems found: include in diagnostic with the agent's report.

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

@@ -0,0 +1,22 @@
+---
+description: "Impact analysis of a decision across the entire plan"
+---
+
+PAUSE. Stop implementing.
+
+1. Document the decision in plans/decisions.md
+2. Delegate to the decision-impact agent:
+   <files_to_read>
+   - ./CLAUDE.md (if exists)
+   - PLAN.md
+   - [all plans/phase-*.md files]
+   - src/interfaces/ (directory — if exists)
+   </files_to_read>
+   Decision: [the decision to analyze]
+3. Present impact to the user
+4. If approved:
+   - Update affected sub-plans (only impacted steps)
+   - Mark: "Updated by Decision #N"
+   - `make commit m="docs: impact analysis decision N"`
+5. MANDATORY context reset -- /clear or new session
+6. Resume with /cpw-next-step