@claude-pw/framework 0.3.0

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

@@ -0,0 +1,492 @@
+---
+description: "Load context and execute the next pipeline stage"
+---
+
+## 0. Health check (session start)
+
+### Handoff detection
+If `.planning/handoff.md` exists:
+- Show the handoff summary to the user
+- Ask: "Resume from this handoff? (yes/no)"
+- If yes: load context from handoff, delete handoff file, continue
+- If no: delete handoff file, proceed normally
+
+### Session recovery
+Delegate to the session-recovery agent in CHECK mode:
+<files_to_read>
+- STATUS.md
+- ./CLAUDE.md (if exists)
+</files_to_read>
+
+- If CLEAN: continue.
+- If RECOVERABLE: show suggested actions. Ask: "Repair automatically? (yes/no)".
+  - If yes: re-invoke session-recovery with REPAIR=true. Continue.
+  - If no: show manual actions. Wait.
+- If INCONSISTENT: show diagnostic. Do NOT continue without user decision.
+
+## 1. Load context
+- Read STATUS.md -> phase, step, stage
+- Read indicated sub-plan (plans/phase-N.md)
+- If `plans/phase-N-context.md` exists (from /cpw-discuss), load it too
+- Load ONLY files in "Required context" — nothing else
+- Read `.planning/config.json` -> autoAdvance (off | auto | yolo)
+
+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
+
+## 1.4 Branch creation (only at phase start, non-trunk strategies)
+
+This step runs ONLY when:
+- Step is the FIRST step of the phase (e.g., N.1)
+- `gitStrategy` is `"feature-branch"` or `"gitflow"` (skip for trunk-based)
+
+Read `gitStrategy` from `.planning/config.json`:
+- **feature-branch**: create branch `phase-N/[phase-description-slug]` from main. `git checkout -b phase-N/[slug]`
+- **gitflow**: ensure `develop` branch exists (create from main if not). Create branch `feature/phase-N-[slug]` from develop. `git checkout -b feature/phase-N-[slug] develop`
+
+Add "Branch: [branch-name]" to STATUS.md session notes.
+
+## 1.5 Tooling audit (only at phase start)
+
+This step runs ONLY when:
+- Stage = DESIGN
+- Step is the FIRST step of the phase (e.g., N.1, not N.2 or N.3)
+- The session notes in STATUS.md do NOT contain "Tooling audited for phase N"
+
+If any condition is false, skip to pipeline evaluation.
+
+### 1.5.1 Detect phase technologies
+- Read the current sub-plan (plans/phase-N.md) — extract technologies, libraries, domains
+- Read docs/architecture.md — extract stack context
+- Build a keyword list: frameworks, languages, domains (e.g., "React", "SQLite", "auth", "video processing")
+
+### 1.5.2 Search for relevant tools
+Read `toolingSources` from `.planning/config.json` (default: `["skills.sh", "claude-code-templates"]`).
+Only search sources listed in the config. For each keyword:
+
+**If "skills.sh" in toolingSources** — Skills and agents (88K+):
+```bash
+npx skills find "[keyword]"
+```
+Collect top results by install count. Filter for quality (>1K installs, maintained repos).
+
+**If "claude-code-templates" in toolingSources** — Agents, MCPs, hooks, settings (100+ curated):
+Browse for components matching the phase technologies:
+- Agents: `npx claude-code-templates@latest --agent [category/name] --yes`
+- MCPs: `npx claude-code-templates@latest --mcp [category/name] --yes`
+- Hooks: `npx claude-code-templates@latest --hook [category/name] --yes`
+
+**Other configurable sources** (add to `toolingSources` array if needed):
+- `"claude-plugins.dev"` → `npx skills-installer search "[keyword]"`
+- `"web-search"` → delegate to researcher agent for broader search:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - docs/architecture.md (if exists)
+  </files_to_read>
+  Type: tooling
+  Topic: [keyword search for broader tooling options]
+
+### 1.5.3 Audit current tooling
+- Read `.claude/settings.local.json` → `enabledMcpjsonServers` (active MCPs)
+- List installed skills: `npx skills list --json` (or scan `.claude/skills/`)
+- List installed agents: scan `.claude/agents/` for non-default agents
+- For each currently installed tool, evaluate: is it relevant to THIS phase?
+  - If yes → KEEP
+  - If no → propose DISABLE (not delete — can be re-enabled later)
+
+### 1.5.4 Present recommendations
+```
+══════════════════════════════════════════
+TOOLING AUDIT — Phase N: [phase name]
+══════════════════════════════════════════
+
+Technologies detected: [list]
+
+INSTALL (recommended):
+    1. [type] [name] — [why it helps]
+       Install: [exact command]
+    2. ...
+
+DISABLE (no longer needed for this phase):
+    3. [tool] — used in Phase M, not relevant now
+
+KEEP (still relevant):
+    4. [tool] — [why]
+
+Install/disable recommendations? (numbers, "all", or "skip")
+══════════════════════════════════════════
+```
+
+### 1.5.5 Execute approved changes
+- Skills from skills.sh: `npx skills add [repo] -s [skill] -y`
+- Components from claude-code-templates: `npx claude-code-templates@latest --[type] [path] --yes`
+- Disable MCPs: remove from `enabledMcpjsonServers` in `.claude/settings.local.json`
+- Disable skills: `npx skills remove [skill]`
+
+### 1.5.6 Generate tooling map
+Update docs/tooling.md with a **tooling map** that tells Claude WHEN and HOW to use each tool during this phase:
+
+```markdown
+# Tooling — Phase N
+
+## Active tools
+
+### [skill/agent/MCP name]
+- **Type:** skill | agent | MCP | hook
+- **Source:** skills.sh | claude-plugins.dev | claude-code-templates
+- **Installed for:** Phase N
+- **Use in steps:** [N.2, N.3, N.5] (map to specific sub-plan steps)
+- **When to use:** [concrete trigger — e.g., "during DESIGN stage when proposing component architecture", "during IMPLEMENT when writing React components", "during TEST for e2e browser tests"]
+- **How to use:** [exact invocation — e.g., "reference the skill's best practices when designing", "use the MCP's query tool for database operations", "delegate to agent for security review"]
+
+### [next tool...]
+...
+
+## Disabled (available for re-enable)
+- [tool] — was active in Phase M, disabled because [reason]
+```
+
+Read each installed skill's SKILL.md or description to understand its capabilities. Then cross-reference with the sub-plan steps to determine WHERE it applies.
+
+This map is the bridge between "installed" and "actually used."
+
+- Add "Tooling audited for phase N" to STATUS.md session notes (prevents re-running)
+
+### 1.5.7 Continue to pipeline
+Proceed with normal DESIGN stage evaluation below.
+
+---
+
+### 1.6 Load step-specific tooling
+If `docs/tooling.md` exists, read the "Active tools" section and filter for tools mapped to the CURRENT step (N.Y).
+For each relevant tool, note:
+- What it does
+- When to use it (which pipeline stage)
+- How to invoke it
+
+Keep this context available throughout the step's pipeline stages. When executing a stage, actively use the tools mapped to that stage — don't just have them installed, USE them.
+
+---
+
+If it's a STEP START (stage = DESIGN), evaluate the adaptive pipeline:
+
+```
+Pipeline for Step [X.Y]:
+- SPIKE: [ok / skip + reason]
+- DESIGN: ok
+- BUILD-OR-BUY: [ok / skip + reason]
+- FEASIBILITY: [ok / skip + reason]
+- COMPATIBILITY: [ok / skip + reason]
+- IMPLEMENT: [ok / skip + reason]
+- TEST: [ok / skip + reason]
+- ACCEPTANCE: ok
+- CLOSE: ok
+```
+
+Then execute the current stage (check docs/tooling.md for tools mapped to this stage):
+- **SPIKE:** Define question + timebox. Delegate to the spike-explorer agent:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - [current sub-plan: plans/phase-N.md]
+  - docs/architecture.md (if exists)
+  </files_to_read>
+  Question: [the spike question]
+  Timebox: [timebox]
+  Report result. Discard code. Record findings in plans/decisions.md if relevant.
+- **DESIGN:** Before proposing, check for technical unknowns. If found, delegate to the researcher agent:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - docs/architecture.md (if exists)
+  - [current sub-plan: plans/phase-N.md]
+  </files_to_read>
+  Type: [architecture | feasibility]
+  Topic: [the unknown to investigate]
+  Incorporate findings into the design. Cite: "Based on research (docs/research/[topic].md)". **Apply any skills mapped to DESIGN for this step** (e.g., best-practice skills, architecture agents). Then propose design. Wait for approval.
+- **BUILD-OR-BUY:** Delegate to the researcher agent:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - docs/architecture.md (if exists)
+  - [current sub-plan: plans/phase-N.md]
+  </files_to_read>
+  Type: library
+  Topic: [what to compare]
+  The agent searches and compares options. Present findings with recommendation. Wait for approval.
+- **FEASIBILITY:** Verify feasibility with the stack.
+- **COMPATIBILITY:** 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, circular deps, missing contracts, coverage. Then run `make test-contracts` if contract tests exist. If the agent reports problems, resolve them before proceeding to IMPLEMENT.
+- **IMPLEMENT:** Delegate to the implementer agent with:
+  <files_to_read>
+  - ./CLAUDE.md (if exists)
+  - [file paths from "Required context" in STATUS.md]
+  - docs/interfaces.md (if exists)
+  - docs/tooling.md (if exists)
+  - docs/conventions.md (if exists)
+  </files_to_read>
+  Design: [the approved DESIGN proposal — copy the full design text]
+  Interface contracts: [from COMPATIBILITY output, if that stage ran]
+  Skills: [mapped to IMPLEMENT from docs/tooling.md]
+  Test command: `make check` (or project-specific command from docs/tooling.md)
+  Max retries: [from `maxConsecutiveFailures` in config, default: 3]
+  Wait for the agent's structured report.
+  - If SUCCESS → proceed to ACCEPTANCE with the report as summary
+  - If PARTIAL → present partial results to user. Options: continue to ACCEPTANCE / retry / abort
+  - If FAILED → present failure details. Options: retry with modified design / abort step
+  - Deviations field → included in ACCEPTANCE summary for reviewer visibility
+- **TEST:** The implementer already ran tests. Review its test report.
+  - If all tests passed → proceed to ACCEPTANCE
+  - If the implementer reported PARTIAL → run `make check` to verify current state
+  - If additional test tools exist in docs/tooling.md (e.g., browser MCPs, e2e tests) → run those now
+  - **Use any testing skills/MCPs mapped to TEST for this step**
+- **ACCEPTANCE:** Summary for approval.
+- **CLOSE:**
+  1. If interfaces/architecture/contracts changed → update corresponding docs
+  2. If this step added a significant feature, new command, API endpoint, or changed the stack → update README.md (keep it current for anyone opening the repo)
+  3. Mark [x] in sub-plan
+  3. `make commit m="type(scope): description"`
+     - `make commit` respects commitPlanning from config.json
+     - If pre-commit fails: fix, retry
+  4. Skill self-check (see below)
+  5. Auto-reflect check (see below)
+  6. Git push (strategy-aware, see below)
+  7. Check if this was the LAST step in the phase (all steps [x] in sub-plan)
+     - If YES → go to step 3 (Phase validation)
+     - If NO → update STATUS.md to next step, stage DESIGN
+
+### Git push (CLOSE sub-step 6)
+Read `gitStrategy` from `.planning/config.json` (default: "trunk-based").
+- **trunk-based**: `make push` (push directly to main/master)
+- **feature-branch** / **gitflow**: `git push` to the current branch (do NOT push to main/develop directly)
+
+### Skill self-check (CLOSE sub-step 4)
+If the step involved debugging, workarounds, or non-obvious configuration, 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 step produced reusable knowledge. Extract as skill? (yes/no)"
+- If yes (or autoAdvance is auto/yolo): create `.claude/skills/[name-slug].md` using the skill template
+- `make commit m="learn: extract skill [name]"`
+If no self-check triggers or gates don't pass: continue normally.
+
+### Auto-reflect check (CLOSE sub-step 5)
+Read `autoReflect` from `.planning/config.json` (default: "remind").
+If `autoReflect` is `"auto"` AND `.planning/learnings/queue.md` has entries:
+- Run a lightweight reflection (steps 1.5, 2, 4, 5 of /cpw-reflect — skip history scan and dedup)
+- Auto-approve entries with confidence ≥ 0.80
+- Present entries with confidence < 0.80 for manual approval
+- `make commit m="learn: auto-reflect session learnings"`
+If `autoReflect` is `"remind"` or `"off"`: skip (the Stop hook handles reminders).
+
+Update STATUS.md with the new stage when finished.
+
+## 2. Advance based on mode
+
+Read `autoAdvance` from `.planning/config.json` (default: "off").
+Read `maxConsecutiveFailures` from config (default: 3 for auto, 5 for yolo).
+
+### off (default)
+Pause at every stage. User confirms each step.
+After CLOSE, report: "Step X.Y closed. Next: Step X.Z"
+
+### auto
+Auto-advance through ALL stages including DESIGN and ACCEPTANCE.
+Pause ONLY at:
+- **UAT** — always interactive (requires human testing)
+- **Ambiguous decisions** — when multiple valid options exist with no clear winner
+- **Errors** — test fail, build fail, pre-commit fail → offer: fix / skip / stop
+- **Consecutive failures** — HALT after N failures in same stage (default: 3, configurable via `maxConsecutiveFailures`)
+
+Auto-approves: all pipeline stages (SPIKE, DESIGN, BUILD-OR-BUY, FEASIBILITY, COMPATIBILITY, IMPLEMENT, TEST, ACCEPTANCE, CLOSE), commit messages, phase validation if passed, cross-phase advancement after UAT passes.
+
+### yolo
+Auto-advance through everything. Same as auto but also:
+- **UAT** — auto-approves if all deliverables pass; pauses ONLY if issues found
+- **Ambiguous decisions** — auto-selects first viable option
+- **Consecutive failures** — HALT after N failures (default: 5)
+
+In yolo mode, Claude designs, implements, tests, closes, validates phases, and advances — only stopping when something breaks or UAT finds actual issues.
+
+### Rules for all modes
+- Commit messages are auto-generated in auto and yolo (no pause)
+- Phase validation always runs automatically when last step completes
+- Between phases: auto and yolo continue automatically (run tooling audit → next step); off always stops
+- If context fills up (3+ auto-advanced steps), suggest /clear and re-invoke /cpw-next-step
+
+## 3. Phase validation (auto-triggered when all steps are done)
+
+This step runs automatically when the last step of a phase is completed.
+Do NOT wait for the user to invoke a separate command.
+
+### 3.1 Verify sub-plan
+- All steps must be [x] in plans/phase-N.md
+- If there are pending steps: this should not happen (step 1 CLOSE detected last step). Report error.
+
+### 3.2 Execute phase-validator
+Delegate to the phase-validator agent:
+<files_to_read>
+- ./CLAUDE.md (if exists)
+- [current sub-plan: plans/phase-N.md]
+- docs/architecture.md (if exists)
+- docs/interfaces.md (if exists)
+- docs/tooling.md (if exists)
+- plans/decisions.md (if exists)
+</files_to_read>
+Phase: N
+The agent validates: code, documentation, consistency, gate.
+Wait for its complete report.
+
+### 3.3 Evaluate result
+
+#### If CORRECTIONS NEEDED:
+- Do NOT close the phase
+- Update STATUS.md to correction mode:
+  ```
+  ## Now
+  - Phase: N
+  - Step: N.fix
+  - Stage: CORRECTION
+  - Sub-plan: plans/phase-N.md
+
+  ## Pending corrections
+  1. [correction from the validator report]
+  2. ...
+
+  ## Required context
+  - [files that need correction]
+
+  ## Session notes
+  - Phase-validator found [X] corrections
+  ```
+- 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.
+
+#### If APPROVED:
+- Update PLAN.md (phase marked as completed)
+- `make commit m="chore: complete phase N"`
+- `make push`
+- Continue to step 4 (User Acceptance Testing)
+
+## 4. User Acceptance Testing (after phase validation passes)
+
+This step runs automatically after phase-validator approves.
+The goal is to verify that features actually WORK from the user's perspective.
+UAT state persists in `.planning/uat.md` — survives `/clear` and context resets.
+
+### 4.1 Check for active UAT session
+If `.planning/uat.md` exists:
+- Read the file. It contains deliverables with their status (PENDING/PASSED/SKIPPED/ISSUE).
+- Resume from the first PENDING item.
+- Show: "Resuming UAT for Phase N — [X] passed, [Y] remaining."
+
+If it does NOT exist: continue to 4.2.
+
+### 4.2 Extract testable deliverables
+Read the sub-plan (plans/phase-N.md) and extract user-observable outcomes:
+- Features the user should be able to use
+- Behaviors that should be visible
+- Interactions that should work
+
+Skip internal/non-observable items (refactors, type changes, internal restructuring).
+
+Write `.planning/uat.md`:
+```markdown
+# UAT — Phase N
+Started: [date]
+
+## Deliverables
+1. [PENDING] [Feature name] — [expected behavior]
+2. [PENDING] [Feature name] — [expected behavior]
+3. [PENDING] [Feature name] — [expected behavior]
+
+## Issues
+(none yet)
+```
+
+### 4.3 Walkthrough (conversational, one at a time)
+For each PENDING deliverable, present:
+```
+[1/N] [Feature name]
+Expected: [what should happen]
+
+Does it work? (yes / describe the issue / skip)
+```
+
+After each response, update `.planning/uat.md` immediately:
+- "yes", "y", "pass" → mark as `[PASSED]`
+- "skip" → mark as `[SKIPPED]`
+- Anything else → mark as `[ISSUE]`, add user's description to the Issues section
+
+This ensures progress is never lost — even if context resets mid-walkthrough.
+
+### 4.4 Results summary
+When all deliverables are resolved (no PENDING items left):
+```
+══════════════════════════════════════
+UAT RESULTS — Phase N
+══════════════════════════════════════
+Passed: X
+Issues: Y
+Skipped: Z
+
+Issues found:
+  1. [feature]: [user's description]
+  2. ...
+══════════════════════════════════════
+```
+
+### 4.5 Handle issues (if any)
+If there are issues:
+- For each issue, analyze the root cause (read relevant code)
+- Propose a fix plan (which files to change, what to fix)
+- Ask: "Fix these issues now? (yes/no)"
+  - If yes: execute fixes as a quick task, commit. Mark fixed items as `[PASSED]` in `.planning/uat.md`. Re-present only the fixed items for re-verification.
+  - If no: capture issues as todos in `.planning/quick/log.md` for later
+
+### 4.6 Phase advancement
+If all deliverables passed (or issues were fixed):
+- Delete `.planning/uat.md` (session complete)
+- Git strategy — phase merge (read `gitStrategy` from config):
+  - **trunk-based**: already on main, nothing to do
+  - **feature-branch**: create PR from `phase-N/[slug]` to main. Report PR URL. Wait for merge (or auto-merge if user approves). After merge: `git checkout main && git pull`
+  - **gitflow**: create PR from `feature/phase-N-[slug]` to develop. Report PR URL. Wait for merge. After merge: `git checkout develop && git pull`
+- Reset STATUS.md for next phase:
+  ```
+  ## Now
+  - Phase: [N+1]
+  - Step: [N+1].1
+  - Stage: DESIGN
+  - Sub-plan: plans/phase-[N+1].md
+
+  ## Required context
+  - [minimum for new phase]
+
+  ## Session notes
+  - (empty)
+  ```
+- If autoAdvance is **off**: Recommend /clear, then report:
+  "Phase N complete. Before starting Phase N+1:"
+  "  1. `/cpw-discuss` — clarify ambiguities for the next phase"
+  "  2. `/cpw-todos` — review pending todos (some may fit the next phase)"
+  "  3. `/cpw-next-step` — start directly"
+- If autoAdvance is **auto** or **yolo**: Suggest /clear for context refresh, then automatically continue with Phase N+1 (run tooling audit → first step).
+
+NEVER advance between phases without completing UAT first (in any mode).

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

@@ -0,0 +1,49 @@
+---
+description: "Save session state for later resume — create handoff document"
+---
+
+## 1. Capture current state
+- Read STATUS.md (phase, step, stage)
+- Read current sub-plan progress ([x] vs [ ])
+- Check for uncommitted changes (`git status`)
+
+## 2. Capture session context
+Ask the user:
+- "What were you working on?" (or infer from recent conversation)
+- "Any blockers or decisions pending?"
+- "Anything the next session should know?"
+
+If the user wants to skip details, infer from the conversation context.
+
+## 3. Generate handoff file
+Write `.planning/handoff.md`:
+
+```markdown
+# Session Handoff — [date]
+
+## State
+- Phase: N, Step: X.Y, Stage: [stage]
+- Progress: X/Y steps complete in current phase
+
+## What was happening
+- [description of current work]
+
+## Uncommitted changes
+- [list of modified files, or "none"]
+
+## Pending decisions
+- [any blockers or open questions]
+
+## Notes for next session
+- [user's notes]
+```
+
+## 4. Handle uncommitted work
+If there are uncommitted changes:
+- Ask: "Commit as WIP before pausing? (yes/no)"
+- If yes: `make commit m="wip([scope]): pause — [brief description]"`
+- If no: leave changes as-is (warn they may be lost if branch switches)
+
+## 5. Confirm
+Report: "Session paused. Handoff saved to `.planning/handoff.md`."
+Report: "Next session: run `/cpw-next-step` — it will detect the handoff and restore context."

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

@@ -0,0 +1,83 @@
+---
+description: "Quick task without full pipeline -- for ad-hoc work that doesn't affect the plan"
+---
+
+## Arguments
+- No arguments: normal flow (all approvals)
+- `--auto`: skip design approval and scope-creep confirmation. Overrides autoAdvance config.
+
+This command is for one-off tasks that do NOT justify the full pipeline.
+Do NOT touch STATUS.md, PLAN.md, or sub-plans. This lives outside the plan.
+
+## 0. Check arguments
+If `--auto` is passed, set AUTO=true. Otherwise AUTO=false.
+
+## 1. DESCRIBE
+Ask the user for a short description of the task (1-2 sentences).
+
+## 2. EVALUATE SIZE
+Before continuing, evaluate whether this is truly quick:
+
+Signs that it is NOT quick (recommend /cpw-next-step):
+- Touches more than 3 files
+- Requires changes in src/interfaces/ (needs RFC)
+- Affects more than one module
+- Needs an entry in plans/decisions.md
+- Is a new feature, not a tweak/fix
+
+If any apply:
+- If AUTO: show warning but continue anyway
+- If not AUTO: "This seems too large for quick mode. I recommend /cpw-next-step so it goes through the pipeline. Do you want to continue with /cpw-quick anyway?" Only continue if the user confirms.
+
+## 3. QUICK DESIGN
+Propose in 3-5 bullets:
+- What will be changed
+- In which files
+- What approach
+
+- If AUTO: show the design and proceed immediately
+- If not AUTO: wait for approval. Do NOT do formal design.
+
+## 4. IMPLEMENT
+Make the change. During implementation, apply deviation rules:
+- **Auto-fix**: lint/format errors, missing imports, type errors from your changes — fix and continue.
+- **Stop**: if you discover an architectural issue (schema change, interface break, different library needed) — stop and report to the user before continuing.
+- Only fix issues caused by THIS change. Note pre-existing issues but do not fix them.
+
+## 5. VERIFY
+- Run `make check` if it exists
+- If there's no make check, run the relevant tests
+- If there are no tests, manually verify it works
+
+## 6. SCOPE CHECK
+Before committing, run `git diff --stat` and evaluate the actual changes:
+
+- **More than 3 files changed** → warn: "This quick task touched [N] files."
+- **Files in more than 1 module/directory** → warn: "Changes span multiple modules."
+- **Any file in src/interfaces/** → warn: "Interface changes require RFC — this should not be a quick task."
+
+If any trigger:
+- If AUTO: show warning but commit anyway
+- If not AUTO:
+  ```
+  ⚠ This quick task grew beyond quick scope:
+    [list of warnings]
+
+  Options:
+    1. Commit anyway as quick task
+    2. Abort — move this work to the pipeline with /cpw-next-step
+  ```
+
+If no triggers: continue to commit.
+
+## 7. COMMIT
+`make commit m="quick: [short description]"`
+
+## 8. LOG
+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."