prizmkit 1.0.106 → 1.0.109

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.106",
-  "bundledAt": "2026-03-25T15:56:50.507Z",
-  "bundledFrom": "d91f86f"
+  "frameworkVersion": "1.0.109",
+  "bundledAt": "2026-03-26T02:14:25.170Z",
+  "bundledFrom": "d4369e9"
 }

package/bundled/adapters/claude/command-adapter.js

@@ -102,8 +102,9 @@ export async function installCommand(corePath, targetRoot) {
   const skillName = path.basename(corePath);
   const hasAssets = existsSync(path.join(corePath, 'assets'));
   const hasScripts = existsSync(path.join(corePath, 'scripts'));
+  const hasRules = existsSync(path.join(corePath, 'rules'));
 
-  if (hasAssets || hasScripts) {
+  if (hasAssets || hasScripts || hasRules) {
     // Use directory structure for commands with resources
     const targetDir = path.join(targetRoot, COMMANDS_DIR, skillName);
     mkdirSync(targetDir, { recursive: true });
@@ -117,7 +118,7 @@ export async function installCommand(corePath, targetRoot) {
     }
 
     // Copy assets and scripts
-    for (const subdir of ['scripts', 'assets']) {
+    for (const subdir of ['scripts', 'assets', 'rules']) {
       const srcSubdir = path.join(corePath, subdir);
       if (existsSync(srcSubdir)) {
         cpSync(srcSubdir, path.join(targetDir, subdir), { recursive: true });

package/bundled/adapters/codebuddy/skill-adapter.js

@@ -58,7 +58,7 @@ export async function installSkill(corePath, targetRoot, options = {}) {
     }
 
     // Copy scripts/ and assets/ if they exist
-    for (const subdir of ['scripts', 'assets']) {
+    for (const subdir of ['scripts', 'assets', 'rules']) {
       const srcSubdir = path.join(corePath, subdir);
       if (existsSync(srcSubdir)) {
         cpSync(srcSubdir, path.join(targetDir, subdir), { recursive: true });

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.106",
+  "version": "1.0.109",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/bug-fix-workflow/SKILL.md

@@ -29,8 +29,51 @@ The bug can come from:
 - **A description**: "the login page crashes when I click submit"
 - **A failed test**: "this test is failing: src/auth/__tests__/login.test.ts"
 
+## Fast Path
+
+For trivial bugs with clear root cause and minimal scope:
+
+### Eligibility Criteria (ALL must be true)
+- Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
+- Fix is ≤10 lines of code in a single file
+- No cross-module impact
+- Existing tests cover the affected path (or bug is in untested utility)
+- No data model or API changes
+
+### Fast Path Workflow
+1. Branch Setup → `fix/<BUG_ID>-<short-desc>`
+2. Write reproduction test → confirm failing
+3. Apply fix → confirm test passes + full suite green
+4. Ask user: "Quick fix applied. Verify before commit? (Y/skip)"
+5. Commit with `fix(<scope>):` prefix
+6. Ask merge preference
+
+**Fast Path still requires**: fix branch, reproduction test, full test suite pass, user merge decision.
+
+---
+
 ## Execution
 
+### Phase 0: Branch Setup
+
+**Goal**: Create an isolated working branch to keep main clean.
+
+1. **Check current branch**:
+   ```bash
+   git branch --show-current
+   ```
+2. **If on `main` or a shared branch**: Create and switch to fix branch:
+   ```bash
+   git checkout -b fix/<BUG_ID>-<short-description>
+   ```
+   Example: `git checkout -b fix/B-001-login-null-crash`
+3. **If already on a fix branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
+4. **Record the original branch name** for later merge.
+
+**CHECKPOINT CP-BFW-0**: On a dedicated fix branch, not main/shared branch.
+
+---
+
 ### Phase 1: Triage
 
 **Goal**: Understand the bug, locate affected code, classify severity.
@@ -108,23 +151,75 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
-### Phase 5: Commit
+### Phase 5: User Verification
+
+**Goal**: Let the user verify the fix works as expected before committing.
 
-**Goal**: Commit the fix with proper conventions.
+1. **Ask user**: "Fix passes all tests. Would you like to verify before committing?"
+   - **(a) Run the app** — Start the dev server so you can manually test the fix scenario
+   - **(b) Run a specific command** — Specify a test or script to run
+   - **(c) Skip verification** — Proceed directly to commit (automated tests already pass)
+2. **If (a)**: Detect and suggest dev server command (e.g. `npm run dev`, `python manage.py runserver`), start it, wait for user confirmation: "Fix verified? (yes/no)"
+3. **If (b)**: Run the specified command, show results, ask confirmation
+4. **If (c)**: Proceed to Phase 6
+
+If user reports the fix is NOT working:
+- Return to Phase 3 (max 2 more attempts)
+- If still failing: escalate with analysis
+
+---
+
+### Phase 6: Commit & Merge
+
+**Goal**: Commit the fix and offer to merge back to the original branch.
 
 1. **Run `/prizmkit-committer`**:
    - Commit message: `fix(<scope>): <description>`
    - Include both fix code and reproduction test
    - Do NOT push (user decides when to push)
-   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/` (per project rules: "bugs are incomplete features, recording bug details causes doc bloat with no AI value")
+   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/`
    - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizm-docs/` or any project files
-2. **If bug came from bug-fix-list.json**: inform user to update bug status
+2. **Ask merge preference**:
+   ```
+   Fix committed on branch `fix/<BUG_ID>-<short-desc>`.
+   What would you like to do?
+   (a) Merge to <original-branch> and delete fix branch
+   (b) Keep fix branch (for PR review workflow)
+   (c) Decide later
+   ```
+3. **If (a)**:
+   ```bash
+   git checkout <original-branch>
+   git merge fix/<BUG_ID>-<short-description>
+   git branch -d fix/<BUG_ID>-<short-description>
+   ```
+4. **If (b)**: Inform user: "Branch `fix/<BUG_ID>-<short-desc>` retained. Create a PR when ready."
+5. **If bug came from bug-fix-list.json**: inform user to update bug status
    ```
    Bug B-001 fixed and committed.
    To update the bug list: manually set B-001 status to "fixed" in bug-fix-list.json
    Or retry the pipeline to pick up remaining bugs.
    ```
 
+## Resume — Interruption Recovery
+
+The workflow supports resuming from the last completed phase by detecting existing artifacts.
+
+**Detection logic**: Check `.prizmkit/bugfix/<BUG_ID>/` and git branch state:
+
+| Artifact Found | Resume From |
+|---------------|------------|
+| (nothing) | Phase 0: Branch Setup |
+| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Triage |
+| `fix-plan.md` only | Phase 3: Fix |
+| `fix-plan.md` + code changes exist | Phase 4: Review |
+| All docs + review passed | Phase 5: User Verification |
+| All docs + committed | Phase 6: Merge decision |
+
+**Resume**: If `<BUG_ID>` matches an existing `.prizmkit/bugfix/<BUG_ID>/` directory, resume instead of starting fresh.
+
+---
+
 ## Artifacts
 
 Bug fix artifacts are stored at `.prizmkit/bugfix/<BUG_ID>/`:
@@ -138,8 +233,10 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
 |-----------|-------------------------------|--------------------------|
 | Scope | One bug at a time | All bugs in batch |
-| Execution | Interactive, in-session | Background daemon |
+| Execution | Interactive, in-session | Foreground or background daemon |
+| Branch | Creates `fix/<BUG_ID>-*` branch | Pipeline manages branches |
 | Visibility | Full user interaction at each phase | Async, check status periodically |
+| User verification | Yes (Phase 5) | No (automated) |
 | Best for | Complex bugs needing user input | Batch of well-defined bugs |
 | Artifacts | Same (fix-plan.md + fix-report.md) | Same |
 | Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
@@ -153,6 +250,7 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | Fix causes regressions | Revert, analyze, retry (max 3 rounds) |
 | Root cause unclear after investigation | Present findings, ask user for guidance |
 | Affected files are in unfamiliar module | Read `.prizm-docs/` L1/L2 for that module first |
+| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
 
 ## HANDOFF
 
@@ -161,11 +259,11 @@ Only 2 artifact files per bug, consistent with the pipeline convention.
 | `bug-planner` | **this skill** | User picks one bug to fix interactively |
 | `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
 | **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
-| **this skill** | `prizmkit-committer` | Built into Phase 5 (pure commit, no doc sync) |
+| **this skill** | `prizmkit-committer` | Built into Phase 6 (pure commit, no doc sync) |
 
 ## Output
 
 - Fixed code with reproduction test
 - `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`
 - `.prizmkit/bugfix/<BUG_ID>/fix-report.md`
-- Git commit with `fix(<scope>):` prefix
+- Git commit with `fix(<scope>):` prefix on dedicated fix branch

package/bundled/skills/bugfix-pipeline-launcher/SKILL.md

@@ -5,11 +5,25 @@ description: "Launch and manage the bugfix pipeline from within an AI CLI sessio
 
 # Bugfix-Pipeline Launcher
 
-Launch the autonomous bug fix pipeline from within an AI CLI conversation. The pipeline runs as a fully detached background process -- closing the AI CLI session does NOT stop the pipeline.
+Launch the autonomous bug fix pipeline from within an AI CLI conversation. Supports foreground and background execution modes.
 
 ### Execution Mode
 
-Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop/status/log actions. Foreground `run-bugfix.sh` can be terminated by AI CLI command timeout, while daemon mode survives session timeout — this prevents half-finished bug fixes that leave the codebase in an inconsistent state.
+**Default: Foreground mode** via `dev-pipeline/run-bugfix.sh run` — this provides visible output and direct error feedback. Use `launch-bugfix-daemon.sh` only when the user explicitly requests background execution.
+
+Foreground `run-bugfix.sh` is preferred because:
+- Immediate visibility of errors and progress
+- No orphaned processes if something goes wrong
+- Session summary artifacts are written reliably
+
+Use daemon mode (`launch-bugfix-daemon.sh`) only when:
+- User explicitly requests background/detached execution
+- Pipeline must survive AI CLI session closure
+
+**Background mode documentation**: When the user chooses background/daemon mode, record the choice and PID in `.prizmkit/bugfix-pipeline-run.log` (append-only) with timestamp, so the decision is traceable:
+```
+[2026-03-26T10:30:00] MODE=daemon PID=12345 BUG_LIST=bug-fix-list.json BUGS=3
+```
 
 ### When to Use
 
@@ -41,7 +55,7 @@ Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop
 
 Before any action, validate:
 
-1. **bugfix pipeline exists**: Confirm `dev-pipeline/launch-bugfix-daemon.sh` is present and executable
+1. **bugfix pipeline exists**: Confirm `dev-pipeline/launch-bugfix-daemon.sh` and `dev-pipeline/run-bugfix.sh` are present and executable
 2. **For start**: `bug-fix-list.json` must exist in project root (or user-specified path)
 3. **Dependencies**: `jq`, `python3`, AI CLI (`cbc` or `claude`) must be in PATH
 
@@ -100,33 +114,61 @@ Detect user intent from their message, then follow the corresponding workflow:
      --action status 2>/dev/null
    ```
 
-4. **Ask user to confirm**: "Ready to launch the bugfix pipeline? It will process N bugs (by severity order) in the background."
+4. **Ask execution mode**: Present the user with a choice before launching:
+   - **(1) Foreground in session (recommended)**: Pipeline runs in the current session via `run-bugfix.sh run`. Visible output and direct error feedback.
+   - **(2) Background daemon**: Pipeline runs fully detached via `launch-bugfix-daemon.sh`. Survives session closure. Use only when user explicitly requests background execution.
+   - **(3) Manual — show commands**: Display the exact commands the user can run themselves. No execution.
+
+   Default to option 1 if user says "just run it" or doesn't specify. Default to option 2 only if user explicitly says "background", "detached", or "run in background".
+
+   **If option 1 (foreground)**:
+   ```bash
+   dev-pipeline/run-bugfix.sh run bug-fix-list.json
+   ```
 
-5. **Launch**:
+   **If option 2 (background)**:
    ```bash
    dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
    ```
-   If user specified environment overrides (e.g. timeout, retries, verbose):
+   After launch, **record the decision** for traceability:
    ```bash
-   dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json --env "SESSION_TIMEOUT=7200 MAX_RETRIES=5"
+   echo "[$(date -u +%Y-%m-%dT%H:%M:%S)] MODE=daemon PID=$(cat dev-pipeline/bugfix-state/daemon.pid 2>/dev/null) BUG_LIST=bug-fix-list.json BUGS=$(python3 -c "import json; print(len(json.load(open('bug-fix-list.json')).get('bugs',[])))")" >> .prizmkit/bugfix-pipeline-run.log
    ```
+   Note: Pipeline runs fully detached. Survives session closure.
+
+   **If option 3 (manual)**: Print commands and stop. Do not execute anything.
+   ```
+   # To run in foreground (recommended):
+   dev-pipeline/run-bugfix.sh run bug-fix-list.json
+
+   # To run in background (detached):
+   dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
+
+   # To check status:
+   dev-pipeline/run-bugfix.sh status bug-fix-list.json
+   ```
+
+5. **Ask user to confirm**: "Ready to launch the bugfix pipeline? It will process N bugs (by severity order)."
+
+6. **Launch** (based on chosen mode — see step 4).
 
-6. **Verify launch**:
+7. **Verify launch**:
    ```bash
    dev-pipeline/launch-bugfix-daemon.sh status
    ```
 
-7. **Start log monitoring** -- Use the Bash tool with `run_in_background: true`:
+8. **Start log monitoring** (daemon mode only) -- Use the Bash tool with `run_in_background: true`:
    ```bash
    tail -f dev-pipeline/bugfix-state/pipeline-daemon.log
    ```
    This runs in background so you can continue interacting with the user.
 
-8. **Report to user**:
-   - Pipeline PID
+9. **Report to user**:
+   - Execution mode chosen
+   - Pipeline PID (daemon mode) or session status (foreground)
    - Log file location
    - "You can ask me 'bugfix status' or 'show fix logs' at any time"
-   - "Closing this session will NOT stop the pipeline"
+   - (daemon mode only) "Closing this session will NOT stop the pipeline"
 
 ---
 
@@ -246,9 +288,10 @@ SESSION_TIMEOUT=3600 dev-pipeline/retry-bug.sh B-001 bug-fix-list.json
 ### Integration Notes
 
 - **After bug-planner**: This is the natural next step. When user finishes bug planning and has `bug-fix-list.json`, suggest launching the bugfix pipeline.
-- **Session independence**: The bugfix pipeline runs completely detached. User can close the AI CLI, open a new session later, and use this skill to check progress or stop the pipeline.
+- **Session independence**: In daemon mode, the bugfix pipeline runs completely detached. User can close the AI CLI, open a new session later, and use this skill to check progress or stop the pipeline.
 - **Single instance**: Only one bugfix pipeline can run at a time. The PID file prevents duplicates.
 - **Feature pipeline coexistence**: Bugfix and feature pipelines use separate state directories (`bugfix-state/` vs `state/`), so they can run simultaneously without conflict.
 - **State preservation**: Stopping and restarting the bugfix pipeline resumes from where it left off -- completed bugs are not re-fixed.
 - **Bug ordering**: Bugs are processed by severity (critical → high → medium → low), then by priority number within the same severity.
+- **Background mode traceability**: When daemon mode is chosen, the decision is logged to `.prizmkit/bugfix-pipeline-run.log` with timestamp, PID, and bug count for auditability.
 - **HANDOFF**: After pipeline completes all bugs, suggest running `prizmkit-retrospective` to capture lessons learned, or checking the fix reports in `.prizmkit/bugfix/`.

package/bundled/skills/feature-workflow/SKILL.md

@@ -32,7 +32,7 @@ feature-workflow <requirements description>
    │
    ├── Phase 1: Plan → app-planner → feature-list.json
    │
-   ├── Phase 2: Launch → dev-pipeline-launcher → background pipeline
+   ├── Phase 2: Launch → dev-pipeline-launcher → pipeline execution
    │
    └── Phase 3: Monitor → track progress → report results
 ```
@@ -42,7 +42,7 @@ feature-workflow <requirements description>
 | Phase | Action | Result |
 |-------|--------|--------|
 | 1 | Call `app-planner` | `feature-list.json` with N features |
-| 2 | Call `dev-pipeline-launcher` | Background pipeline started |
+| 2 | Call `dev-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
 | 3 | Monitor progress | Status updates, completion report |
 
 ### Why This Skill Exists
@@ -56,6 +56,13 @@ With this skill, users can:
 1. Say "Build a task management App" and walk away
 2. All planning + execution happens automatically
 
+### Branch Management
+
+The dev-pipeline handles branch management per-feature automatically:
+- Each feature is implemented on its own branch by the pipeline
+- Branches are created, committed, and managed by the pipeline session
+- This workflow does NOT create a top-level branch — the pipeline manages granular per-feature branches
+
 ---
 
 ## Input Modes
@@ -112,7 +119,7 @@ When user says "add features to existing project" or the project already has fea
 
 ## Phase 2: Launch
 
-**Goal**: Start the background development pipeline.
+**Goal**: Start the development pipeline.
 
 **STEPS**:
 
@@ -123,27 +130,20 @@ When user says "add features to existing project" or the project already has fea
      F-002: Task CRUD (medium complexity)
      F-003: Task categories (low complexity)
 
-   Pipeline will run in background. Close this session will NOT stop it.
    Proceed? (Y/n)
    ```
 
-2. **Ask execution mode**: Before invoking the launcher, present the choice:
-   - **(1) Background daemon (recommended)**: Runs detached, survives session closure.
-   - **(2) Foreground in session**: Runs in current session with visible output. Stops if session times out.
-   - **(3) Manual — show commands**: Display commands only, no execution.
-
-   Pass the chosen mode to `dev-pipeline-launcher`.
-
-3. **Invoke `dev-pipeline-launcher` skill**:
+2. **Invoke `dev-pipeline-launcher` skill**:
    - The launcher handles all prerequisites checks
-   - Starts `launch-daemon.sh` in background
-   - Returns PID and log file location
+   - The launcher presents execution mode choices to the user (foreground/background/manual)
+   - Do NOT duplicate execution mode selection here — let the launcher handle it
+   - Returns PID/status and log file location
 
-4. **Verify launch success**:
+3. **Verify launch success**:
    - Confirm pipeline is running
    - Record PID and log path for Phase 3
 
-**CHECKPOINT CP-FW-2**: Pipeline launched successfully in background.
+**CHECKPOINT CP-FW-2**: Pipeline launched successfully.
 
 ---
 
@@ -173,7 +173,7 @@ When user says "add features to existing project" or the project already has fea
 
 4. **Completion report** (when pipeline finishes all features):
    ```
-   ✅ Pipeline completed: 3/3 features
+   Pipeline completed: 3/3 features
 
    Summary:
    - F-001: User authentication → COMMITTED (feat: user auth)
@@ -190,9 +190,24 @@ When user says "add features to existing project" or the project already has fea
 
 ---
 
+## Resume — Interruption Recovery
+
+The workflow supports resuming by detecting existing state:
+
+| State Found | Resume From |
+|-------------|------------|
+| No `feature-list.json` | Phase 1: Plan |
+| `feature-list.json` exists, no pipeline state | Phase 2: Launch |
+| `feature-list.json` + pipeline state exists | Phase 3: Monitor (check status) |
+| All features completed | Report completion, suggest next steps |
+
+**Resume**: If `feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
+
+---
+
 ## Interaction During Pipeline
 
-While the pipeline runs in background, the user can continue the conversation:
+While the pipeline runs, the user can continue the conversation:
 
 | User says | Action |
 |-----------|--------|
@@ -220,7 +235,7 @@ While the pipeline runs in background, the user can continue the conversation:
 | Skill | Relationship |
 |-------|-------------|
 | `app-planner` | **Called by Phase 1** — generates feature-list.json |
-| `dev-pipeline-launcher` | **Called by Phase 2** — starts background pipeline |
+| `dev-pipeline-launcher` | **Called by Phase 2** — starts pipeline (handles execution mode selection) |
 | `bug-planner` | **Alternative** — for bug fix workflows |
 | `bugfix-pipeline-launcher` | **Alternative** — for bug fix pipelines |
 | `refactor-workflow` | **Alternative** — for code restructuring |
@@ -233,9 +248,11 @@ While the pipeline runs in background, the user can continue the conversation:
 |-----------|-----------------|------------------|-------------------|
 | **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring |
 | **Planning Skill** | `app-planner` | None (triage built-in) | None (analysis built-in) |
-| **Execution** | Background daemon | In-session, interactive | In-session |
+| **Branch** | Pipeline manages per-feature | `fix/<BUG_ID>-*` | `refactor/<slug>` |
+| **Execution** | Foreground or background daemon | In-session, interactive | In-session |
 | **Input** | Requirements description | Bug report / stack trace | Module / code target |
 | **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
+| **User verification** | No (pipeline automated) | Yes (Phase 5) | Yes (Phase 5) |
 | **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | N/A |
 
 ---
@@ -247,7 +264,7 @@ All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibil
 ## Output
 
 - `feature-list.json` (Phase 1 artifact)
-- Background pipeline running (Phase 2)
+- Pipeline execution (Phase 2)
 - Progress updates (Phase 3)
 - Multiple git commits with `feat(<scope>):` prefix
 - Updated `.prizm-docs/` (via prizmkit-retrospective per feature)

package/bundled/skills/prizm-kit/SKILL.md

@@ -71,6 +71,21 @@ PrizmKit produces two complementary knowledge layers:
 .prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → code(implement))
 ```
 
+## Core Skill Reference
+
+| Skill | Purpose | Trigger Phrases |
+|-------|---------|-----------------|
+| `/prizmkit-specify` | Natural language → structured spec.md | "specify", "new feature", "I want to add..." |
+| `/prizmkit-clarify` | Resolve spec ambiguities interactively | "clarify", "refine spec", "resolve ambiguities" |
+| `/prizmkit-plan` | Spec → plan.md with architecture + tasks | "plan", "architect", "break it down", "create tasks" |
+| `/prizmkit-analyze` | Cross-doc consistency check (read-only) | "analyze", "check consistency", "validate spec" |
+| `/prizmkit-implement` | Execute plan.md tasks, write code (TDD) | "implement", "build", "code it", "start coding" |
+| `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
+| `/prizmkit-retrospective` | Sync .prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
+| `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
+| `/prizmkit-init` | Project bootstrap + .prizm-docs/ setup | "init", "initialize", "take over this project" |
+| `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |
+
 **Reading guide**:
 - Need code structure/modules/interfaces/traps/decisions? → `.prizm-docs/`
 

package/bundled/skills/prizmkit-analyze/SKILL.md

@@ -12,7 +12,12 @@ Perform a non-destructive cross-artifact consistency and quality analysis across
 - User says "analyze", "check consistency", "validate spec", "review plan"
 - Before `/prizmkit-implement` as a quality gate
 
-**PRECONDITION:** `spec.md` and `plan.md` exist in `.prizmkit/specs/###-feature-name/`. `plan.md` must include a Tasks section.
+**PRECONDITION:**
+
+| Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|
+| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists | Run `/prizmkit-specify` |
+| `plan.md` (with Tasks section) | `.prizmkit/specs/###-feature-name/` | File exists + has Tasks section | Run `/prizmkit-plan` |
 
 ## Operating Constraints
 

package/bundled/skills/prizmkit-clarify/SKILL.md

@@ -12,7 +12,11 @@ Interactive requirement clarification that resolves ambiguities in feature speci
 - User says "clarify", "resolve ambiguities", "refine spec"
 - Before `/prizmkit-plan` to ensure spec is unambiguous
 
-**PRECONDITION:** `spec.md` exists in current feature directory (`.prizmkit/specs/###-feature-name/`)
+**PRECONDITION:**
+
+| Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|
+| `spec.md` | `.prizmkit/specs/###-feature-name/` | File exists with `[NEEDS CLARIFICATION]` markers or underspecified areas | Run `/prizmkit-specify` first |
 
 ## Execution Steps
 

package/bundled/skills/prizmkit-code-review/SKILL.md

@@ -7,8 +7,8 @@ description: "Code review with fix strategy formulation. Diagnoses issues across
 
 Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. This skill has two phases:
 
-1. **Diagnostic Review** — read-only analysis across 6 dimensions, producing findings with severity ratings
-2. **Fix Strategy Formulation** — for each finding, analyze root cause, impact, and produce actionable Fix Instructions with verification criteria
+1. **Diagnostic Review** — read-only analysis producing findings with severity ratings
+2. **Fix Strategy Formulation** — for each finding, produce actionable Fix Instructions
 
 The review itself is read-only. Fix Instructions are structured guidance for the developer — the reviewer does not modify code.
 
@@ -17,58 +17,35 @@ The review itself is read-only. Fix Instructions are structured guidance for the
 - User says "review", "check code", "review my implementation"
 - As a quality gate before `/prizmkit-committer`
 
-**PRECONDITION (multi-mode):**
-- **Feature mode**: `spec.md` and `plan.md` (with Tasks section) exist in `.prizmkit/specs/###-feature-name/` with completed tasks
-- **Refactor mode**: `refactor-analysis.md` and `plan.md` (with Tasks section) exist in `.prizmkit/refactor/<refactor-slug>/` with completed tasks. No `spec.md` is needed — review against `refactor-analysis.md` goals and behavior preservation instead.
-- **Bugfix mode**: `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with completed tasks. Review against the bug description and reproduction test.
-- **Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
+**PRECONDITION:**
+
+| Mode | Required Artifacts | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** | `spec.md` + `plan.md` (with Tasks) | `.prizmkit/specs/###-feature-name/` | Files exist + tasks completed | Run `/prizmkit-implement` |
+| **Refactor** | `refactor-analysis.md` + `plan.md` (with Tasks) | `.prizmkit/refactor/<refactor-slug>/` | Files exist + tasks completed. Review against behavior preservation, not spec. | Run `/prizmkit-implement` in refactor mode |
+| **Bugfix** | `fix-plan.md` | `.prizmkit/bugfix/<BUG_ID>/` | File exists + tasks completed. Review against bug description + reproduction test. | Run `/prizmkit-implement` in bugfix mode |
+
+**Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
 
 ## Phase 1: Diagnostic Review
 
-1. **Detect mode and load review baseline**:
-   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage.
-   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Review dimensions shift: replace "spec compliance" with **behavior preservation** (observable behavior unchanged), replace "plan adherence" with **structural improvement** (is the code measurably better?). Also check test integrity and code quality.
-   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Review dimensions: bug is actually fixed, no regressions, reproduction test passes, minimal change scope.
+1. **Detect mode and load review baseline + dimension rules**:
+   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-feature.md` for review dimensions.
+   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-refactor.md` for review dimensions.
+   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Load `${SKILL_DIR}/rules/dimensions-bugfix.md` for review dimensions.
    - If none found → prompt user: "No review baseline found. Which workflow are you in? (feature/refactor/bugfix)"
 2. Read **architecture index**: `.prizm-docs/root.prizm` RULES and PATTERNS for project conventions
 3. Read **past decisions**: check DECISIONS sections in relevant `.prizm-docs/` L1/L2 files — helps verify implementation respects established conventions
 4. Read '## Implementation Log' section of context-snapshot.md in the feature directory (if exists) — understand Dev's implementation decisions, trade-offs, and notable discoveries. This context helps distinguish intentional design choices from accidental patterns during review.
 5. Scan all code files referenced in completed tasks
-6. Review across 6 dimensions:
-   - **Spec compliance**: Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs
-   - **Plan adherence**: Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on
-   - **Code quality**: Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
-   - **Security**: Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later
-   - **Consistency**: Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader
-   - **Test coverage**: Are critical paths tested? Focus on paths that handle user input, money, or state transitions
+6. Review across all dimensions defined in the loaded rules file
 7. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
 
 ## Phase 2: Fix Strategy Formulation
 
-For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable):
-
-1. **Root Cause Analysis** — identify WHY the problem exists, not just WHAT is wrong. Trace the issue to its origin (wrong assumption? missing context? copy-paste error?)
-2. **Impact Analysis** — search the codebase for all callers/dependents of the affected code. List concrete file:line locations that will be affected by the fix
-3. **Fix Strategy** — concrete step-by-step modification plan:
-   - What to change, where, and in what order
-   - Which project conventions to follow (reference `.prizm-docs/` RULES)
-   - Dependencies between fixes (FIX-1 must be done before FIX-3)
-4. **Code Guidance** — show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation
-5. **Verification Criteria** — how to confirm the fix works:
-   - Specific commands to run (grep patterns, test commands)
-   - What the output should look like
-   - Edge cases to verify
-
-### Finding Grouping
-
-Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+Load `${SKILL_DIR}/rules/fix-strategy.md` for the complete fix formulation process, finding format, grouping rules, and priority ordering.
 
-### Fix Priority Ordering
-
-Order Fix Instructions by:
-1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
-2. **CRITICAL before HIGH** — severity determines priority within independent fixes
-3. **Grouped fixes together** — related findings are adjacent
+For each finding from Phase 1 (CRITICAL and HIGH are mandatory; MEDIUM/LOW when actionable), follow the fix strategy rules to produce structured Fix Instructions.
 
 ## Severity & Verdict
 
@@ -83,65 +60,6 @@ Cap findings at 30 to keep the review actionable. If there are more, summarize t
 
 If you're unsure whether something is a bug or intentional design, flag it as MEDIUM with a note asking the developer to confirm. Don't silently skip uncertain findings.
 
-## Finding Format
-
-```
-#### FIX-1: [CRITICAL] SQL Injection in User Search
-- Location: src/services/userService.ts:47
-- Dimension: security
-- Root Cause: User input `searchTerm` is interpolated directly into SQL query
-  string. The `buildQuery()` helper (line 12) accepts raw strings without
-  sanitization, and all callers trust it blindly.
-- Impact: All callers of `searchUsers()` are affected — found 3 call sites:
-  routes/api.ts:89, routes/admin.ts:34, services/reportService.ts:112
-- Fix Strategy:
-  1. Replace string interpolation with parameterized query at line 47
-  2. Update `buildQuery()` helper to accept params array
-  3. Update all 3 call sites to pass params
-  Note: project uses `pg` client directly (not ORM), follow the pattern
-  established in `orderService.ts:23` per .prizm-docs/ RULES
-- Code Guidance:
-  ```ts
-  // line 47: change from
-  const result = await db.query(`SELECT * FROM users WHERE name LIKE '%${searchTerm}%'`);
-  // to
-  const result = await db.query('SELECT * FROM users WHERE name LIKE $1', [`%${searchTerm}%`]);
-  ```
-- Verification:
-  - `grep -rn "\${.*}" src/ --include="*.ts"` returns no SQL-context matches
-  - Test `user.search.test.ts` covers parameterized path
-  - Existing test suite passes
-- Related: FIX-3 (same pattern in reportService)
-- Depends On: (none)
-- Blocks: FIX-3
-
-#### FIX-2: [HIGH] Missing Acceptance Criterion AC-3
-- Location: src/routes/upload.ts
-- Dimension: spec-compliance
-- Root Cause: spec.md §AC-3 requires "display progress bar during upload" but
-  the upload handler uses a simple fetch() without progress tracking.
-  Implementation Log does not mention this criterion — likely overlooked.
-- Impact: Upload route only — no cross-module impact
-- Fix Strategy:
-  1. Replace fetch() with XMLHttpRequest or fetch + ReadableStream
-  2. Add progress callback that emits percentage events
-  3. Wire progress events to the UI component (if frontend exists)
-- Code Guidance:
-  ```ts
-  // Replace simple fetch with progress-aware upload
-  const xhr = new XMLHttpRequest();
-  xhr.upload.onprogress = (e) => {
-    if (e.lengthComputable) onProgress(Math.round(e.loaded / e.total * 100));
-  };
-  ```
-- Verification:
-  - Upload a file > 1MB and verify progress callback fires
-  - Test covers progress event emission
-- Related: (none)
-- Depends On: (none)
-- Blocks: (none)
-```
-
 ## Review Notes Format
 
 When writing to context-snapshot.md, use this structured format:
@@ -156,7 +74,7 @@ When writing to context-snapshot.md, use this structured format:
 ### Fix Instructions (ordered by priority)
 
 #### FIX-1: [SEVERITY] Title
-(full finding format as above)
+(finding format per ${SKILL_DIR}/rules/fix-strategy.md)
 
 #### FIX-2: [SEVERITY] Title
 ...
@@ -177,7 +95,7 @@ In unattended pipeline mode, the review→fix→review cycle can loop indefinite
 - Track a `review_iteration` counter starting at 1. Each review-fix-review cycle increments the counter.
 - **max_iterations = 5**: If `review_iteration >= 5`, you MUST proceed to `/prizmkit-retrospective` regardless of remaining findings. Log remaining issues as known technical debt: "Loop protection triggered — proceeding to retrospective with N unresolved findings (iterations: 5/5)."
 - Unresolved findings should be recorded in the review report so they can be tracked as follow-up work.
-- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full 6-dimension review unless new code was added beyond the fix scope.
+- On re-review (iteration > 1): only check the specific Verification Criteria from previous Fix Instructions + scan for regressions. Do NOT re-run the full dimension review unless new code was added beyond the fix scope.
 
 ## Output
 

package/bundled/skills/prizmkit-code-review/rules/dimensions-bugfix.md

@@ -0,0 +1,25 @@
+# Review Dimensions — Bugfix Mode
+
+Review code against `fix-plan.md` and the bug description. Minimal scope — the fix should change as little as possible.
+
+## Bugfix-Specific Dimensions
+
+### Bug Actually Fixed
+- The reproduction steps from fix-plan.md no longer trigger the bug
+- The root cause identified in fix-plan.md is addressed (not just symptoms)
+- A regression test exists that would catch this bug if reintroduced
+
+### No Regressions
+- All existing tests still pass
+- The fix does not change behavior for non-buggy inputs
+- Related code paths are not inadvertently affected
+
+### Minimal Change Scope
+- Only files directly related to the bug are modified
+- No "while I'm here" refactoring mixed with the fix
+- If scope creep is detected, flag it — those changes belong in a separate commit
+
+### Reproduction Test
+- A test exists that reproduces the exact bug scenario
+- The test would fail on the pre-fix code and pass on the post-fix code
+- The test covers the specific input/state that triggered the bug

package/bundled/skills/prizmkit-code-review/rules/dimensions-feature.md

@@ -0,0 +1,43 @@
+# Review Dimensions — Feature Mode
+
+Review code against `spec.md` and `plan.md` across 6 dimensions:
+
+## 1. Spec Compliance
+Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs.
+- Check every acceptance criterion in spec.md has a corresponding implementation
+- Verify edge cases mentioned in spec are handled
+- Confirm scope boundaries are respected (no over-implementation, no under-implementation)
+
+## 2. Plan Adherence
+Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on.
+- Check component structure matches plan's architecture approach
+- Verify data model matches plan's schema design
+- Confirm API contracts (endpoints, request/response) match plan
+
+## 3. Code Quality
+Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
+- Function/variable names are descriptive and consistent with project conventions
+- No unnecessary complexity (cyclomatic complexity, deep nesting)
+- No copy-paste duplication that should be abstracted
+- Error messages are informative for debugging
+
+## 4. Security
+Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later.
+- User input is validated and sanitized before use in queries, HTML, or commands
+- Authentication and authorization checks are present on protected routes
+- Sensitive data (passwords, tokens, PII) is not logged or exposed in responses
+- Cryptographic operations use established libraries, not custom implementations
+
+## 5. Consistency
+Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader.
+- Code style matches existing codebase conventions
+- Error handling follows established patterns
+- File organization follows project structure conventions
+- Naming conventions align with `.prizm-docs/` RULES
+
+## 6. Test Coverage
+Are critical paths tested? Focus on paths that handle user input, money, or state transitions.
+- Happy path tests exist for each user story
+- Error/edge case tests for critical paths
+- Tests are deterministic (no flaky timing dependencies)
+- Test names clearly describe what they verify

package/bundled/skills/prizmkit-code-review/rules/dimensions-refactor.md

@@ -0,0 +1,25 @@
+# Review Dimensions — Refactor Mode
+
+Review code against `refactor-analysis.md` goals. Standard dimensions (code quality, security, consistency, test coverage) still apply — load `${SKILL_DIR}/rules/dimensions-feature.md` §3–§6 for those.
+
+## Refactor-Specific Dimensions
+
+### Behavior Preservation (replaces Spec Compliance)
+Observable behavior must remain unchanged. This is the #1 refactor risk — "improving" code that subtly changes behavior.
+- All existing tests still pass without modification (test changes during refactor are a red flag)
+- Public API signatures are unchanged (parameter types, return types, error types)
+- Side effects (logging, metrics, events) are preserved unless explicitly scoped for removal
+- Edge case handling is preserved — refactors often silently drop edge case branches
+
+### Structural Improvement (replaces Plan Adherence)
+Is the code measurably better against the refactor goals?
+- Complexity metrics improved (fewer nested conditions, shorter functions)
+- Coupling reduced (fewer cross-module imports, clearer boundaries)
+- Duplication reduced (DRY violations eliminated per refactor-analysis.md scope)
+- Readability improved (naming, organization, documentation)
+
+### Test Integrity
+Refactors must not weaken the test suite.
+- No tests were deleted or skipped
+- Test coverage percentage is equal or higher
+- If tests were rewritten, they cover the same behavioral scenarios

package/bundled/skills/prizmkit-code-review/rules/fix-strategy.md

@@ -0,0 +1,61 @@
+# Fix Strategy Formulation
+
+For each finding from the Diagnostic Review (CRITICAL and HIGH mandatory; MEDIUM/LOW when actionable):
+
+## Per-Finding Analysis
+
+### 1. Root Cause Analysis
+Identify WHY the problem exists, not just WHAT is wrong. Trace the issue to its origin (wrong assumption? missing context? copy-paste error?).
+
+### 2. Impact Analysis
+Search the codebase for all callers/dependents of the affected code. List concrete `file:line` locations that will be affected by the fix.
+
+### 3. Fix Strategy
+Concrete step-by-step modification plan:
+- What to change, where, and in what order
+- Which project conventions to follow (reference `.prizm-docs/` RULES)
+- Dependencies between fixes (FIX-1 must be done before FIX-3)
+
+### 4. Code Guidance
+Show before/after code snippets for the key change. Keep minimal — enough to unambiguate the approach, not a full implementation.
+
+### 5. Verification Criteria
+How to confirm the fix works:
+- Specific commands to run (grep patterns, test commands)
+- What the output should look like
+- Edge cases to verify
+
+## Finding Grouping
+
+Group related findings that should be fixed together. If FIX-1 and FIX-3 share the same root cause or affect the same code path, mark them as a group with a shared fix strategy. This prevents Dev from fixing symptoms individually only to have the underlying cause persist.
+
+## Fix Priority Ordering
+
+Order Fix Instructions by:
+1. **Dependencies first** — if FIX-2 depends on FIX-1, FIX-1 comes first
+2. **CRITICAL before HIGH** — severity determines priority within independent fixes
+3. **Grouped fixes together** — related findings are adjacent
+
+## Finding Format
+
+```
+#### FIX-N: [SEVERITY] Title
+- Location: file:line
+- Dimension: category
+- Root Cause: explanation
+- Impact: affected callers/dependents with file:line locations
+- Fix Strategy:
+  1. step one
+  2. step two
+  Note: reference project conventions from .prizm-docs/ RULES
+- Code Guidance:
+  ```language
+  // before → after
+  ```
+- Verification:
+  - command to run
+  - expected output
+- Related: FIX-X (if grouped)
+- Depends On: FIX-Y (if dependency)
+- Blocks: FIX-Z (if blocking)
+```

package/bundled/skills/prizmkit-committer/SKILL.md

@@ -14,6 +14,14 @@ Pure git commit workflow. Analyzes changes, generates a Conventional Commits mes
 - After `/prizmkit-retrospective` has finished architecture sync
 - The UserPromptSubmit hook will remind to use this skill when commit intent is detected
 
+**PRECONDITION:**
+
+| Required State | Check | If Missing |
+|---|---|---|
+| Uncommitted changes exist | `git status` shows modified/added/untracked files | Inform user "nothing to commit" and stop |
+| `.prizm-docs/` synced (feature/refactor) | `/prizmkit-retrospective` has run | Run `/prizmkit-retrospective` first |
+| Code review passed (pipeline mode) | `context-snapshot.md` has Review Notes with PASS/PASS_WITH_WARNINGS | Run `/prizmkit-code-review` first |
+
 ### Workflow
 
 Follow these steps STRICTLY in order:
@@ -32,9 +40,14 @@ By consulting the primary agent or based on the existing context, condense this
 If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
 
 #### Step 4: Git Commit
-```bash
-git add .
-```
+
+Stage changes using a safe strategy — **never use `git add .` or `git add -A`** as they may stage sensitive files (.env, credentials, secrets) or unintended changes:
+
+1. Review untracked files with `git status`. Warn the user if any files match sensitive patterns (`.env*`, `*credential*`, `*secret*`, `*.pem`, `*.key`).
+2. Stage tracked modified files: `git add -u`
+3. For new files: stage explicitly by name after confirming they should be included.
+4. Verify staged content with `git diff --cached --stat` before committing.
+
 ```bash
 git commit -m "<type>(<scope>): <description>"
 ```

package/bundled/skills/prizmkit-implement/SKILL.md

@@ -12,11 +12,15 @@ Execute implementation by following the task breakdown in plan.md. Respects task
 - User says "implement", "build", "code it", "start coding", "develop"
 - For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
-**PRECONDITION (multi-mode):**
-- **Feature mode** (default): `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
-- **Refactor mode**: `plan.md` exists in `.prizmkit/refactor/<refactor-slug>/` with a Tasks section containing unchecked tasks
-- **Bugfix mode**: `plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with a Tasks section containing unchecked tasks
-- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+**PRECONDITION:**
+
+| Mode | Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** (default) | `plan.md` with Tasks section | `.prizmkit/specs/###-feature-name/` | File exists + unchecked tasks | Run `/prizmkit-plan` |
+| **Refactor** | `plan.md` with Tasks section | `.prizmkit/refactor/<refactor-slug>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in refactor mode |
+| **Bugfix** | `plan.md` with Tasks section | `.prizmkit/bugfix/<BUG_ID>/` | File exists + unchecked tasks | Run `/prizmkit-plan` in bugfix mode |
+
+**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
 
 ## Execution Steps
 

package/bundled/skills/prizmkit-plan/SKILL.md

@@ -18,11 +18,15 @@ Generate a comprehensive technical implementation plan from a feature specificat
 - Simple bug fix or config change → use fast path (`/prizmkit-plan` with simplified output → `/prizmkit-implement` → `/prizmkit-committer`)
 - User just wants to explore/research → answer directly, no plan artifact needed
 
-**PRECONDITION (multi-mode):**
-- **Feature mode** (default): `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists. If spec.md is missing, prompt the user: "No spec found — want me to run /prizmkit-specify first?"
-- **Refactor mode**: `refactor-analysis.md` exists in `.prizmkit/refactor/<refactor-slug>/`. Use refactor-analysis.md as the input document in place of spec.md. Output plan.md to the same `.prizmkit/refactor/<refactor-slug>/` directory, NOT to `.prizmkit/specs/`.
-- **Bugfix mode**: Bug description provided by caller or `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/`. Output plan.md to the same directory.
-- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
+**PRECONDITION:**
+
+| Mode | Required Artifact | Directory | Check | If Missing |
+|---|---|---|---|---|
+| **Feature** (default) | `spec.md` + `.prizm-docs/root.prizm` | `.prizmkit/specs/###-feature-name/` | File exists | Prompt: "No spec found — run `/prizmkit-specify` first?" |
+| **Refactor** | `refactor-analysis.md` | `.prizmkit/refactor/<refactor-slug>/` | File exists | Run upstream refactor workflow |
+| **Bugfix** | `fix-plan.md` or bug description from caller | `.prizmkit/bugfix/<BUG_ID>/` | File exists or caller-provided | Run `/bug-fix-workflow` |
+
+**Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
 
 ## Execution Steps
 

package/bundled/skills/refactor-workflow/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "refactor-workflow"
 tier: 1
-description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 5-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
+description: "End-to-end refactor workflow: analyze → plan → implement → review → commit. 6-phase behavior-preserving pipeline with mandatory test gates. Use this skill whenever the user wants to restructure, clean up, or optimize code without changing behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'code refactoring'. (project)"
 ---
 
 # PrizmKit Refactor Workflow
 
-End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 5-phase behavior-preserving pipeline with mandatory test gates after each task.
+End-to-end orchestration skill for code refactoring and optimization. Chains existing PrizmKit skills into a 6-phase behavior-preserving pipeline with mandatory test gates after each task.
 
 ### When to Use
 - User says "refactor", "clean up code", "restructure", "extract module", "code refactoring", "optimize code structure"
@@ -23,22 +23,24 @@ End-to-end orchestration skill for code refactoring and optimization. Chains exi
 
 ```
 refactor-workflow
+  → Phase 0: Branch    → refactor/<slug> branch
   → Phase 1: Analyze   → refactor-analysis.md
   → Phase 2: Plan      → plan.md (including Tasks section)
   → Phase 3: Implement → (code)
   → Phase 4: Review    → (review report)
-  → Phase 5: Commit    → git commit
+  → Phase 5: Verify & Commit → git commit + merge decision
 ```
 
 ### Pipeline Phases
 
 | Phase | Name | Skill Used | Artifact |
 |-------|------|-----------|----------|
+| 0 | Branch Setup | git | → `refactor/<slug>` branch |
 | 1 | Analyze (Code Analysis) | Built-in code analysis + code reading | → `refactor-analysis.md` |
 | 2 | Plan (Refactor Plan & Tasks) | `/prizmkit-plan` | → `plan.md` (with Tasks section) |
 | 3 | Implement | `/prizmkit-implement` | (code changes) |
 | 4 | Code Review | `/prizmkit-code-review` | (review report) |
-| 5 | Commit | `/prizmkit-committer` | git commit |
+| 5 | Verify & Commit | `/prizmkit-committer` | git commit + merge |
 
 ### Key Principles
 
@@ -61,6 +63,26 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
+## Phase 0: Branch Setup
+
+**Goal**: Create an isolated working branch to keep main clean.
+
+1. **Check current branch**:
+   ```bash
+   git branch --show-current
+   ```
+2. **If on `main` or a shared branch**: Create and switch to refactor branch:
+   ```bash
+   git checkout -b refactor/<refactor-slug>
+   ```
+   Example: `git checkout -b refactor/extract-auth-middleware`
+3. **If already on a refactor branch**: Confirm with user: "Continue on current branch `<branch-name>`, or create a new one?"
+4. **Record the original branch name** for later merge.
+
+**CHECKPOINT CP-RW-0**: On a dedicated refactor branch, not main/shared branch.
+
+---
+
 ## Phase 1: Analyze — Code Analysis
 
 **Goal**: Assess current code state, identify refactoring targets, establish baseline.
@@ -163,23 +185,44 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 
 ---
 
-## Phase 5: Commit
+## Phase 5: Verify, Commit & Merge
 
-**Goal**: Commit with refactor convention.
+**Goal**: Let user verify, commit with refactor convention, and merge back.
 
 **STEPS:**
 
-1. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
+1. **User verification** (optional):
+   - Ask user: "Refactoring complete and all tests pass. Would you like to verify before committing?"
+     - **(a) Run the app** — Start dev server for manual verification
+     - **(b) Run a specific command** — Specify a test or script
+     - **(c) Skip** — Proceed to commit (tests already pass)
+   - If user reports issues: return to Phase 3
+2. **Invoke `/prizmkit-retrospective`** (Job 1: structural sync only):
    - Update KEY_FILES/INTERFACES/DEPENDENCIES in affected `.prizm-docs/` files
    - Skip knowledge injection unless refactoring revealed a genuinely new pitfall (e.g. a non-obvious coupling)
    - If structural changes are significant (module split/merge), update L1 doc
    - Stage doc changes: `git add .prizm-docs/`
-2. **Invoke `/prizmkit-committer`**:
+3. **Invoke `/prizmkit-committer`**:
    - Commit message: `refactor(<scope>): <description>`
    - Include all refactored code + any test updates
    - Do NOT push
-
-**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix.
+4. **Ask merge preference**:
+   ```
+   Refactoring committed on branch `refactor/<slug>`.
+   What would you like to do?
+   (a) Merge to <original-branch> and delete refactor branch
+   (b) Keep refactor branch (for PR review workflow)
+   (c) Decide later
+   ```
+5. **If (a)**:
+   ```bash
+   git checkout <original-branch>
+   git merge refactor/<slug>
+   git branch -d refactor/<slug>
+   ```
+6. **If (b)**: Inform user: "Branch `refactor/<slug>` retained. Create a PR when ready."
+
+**CHECKPOINT CP-RW-5**: Commit recorded with `refactor()` prefix. Merge decision made.
 
 ---
 
@@ -188,7 +231,7 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 For single-file refactoring (rename, extract method, <30 lines changed):
 
 ```
-Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit)
+Phase 0 (Branch) → Phase 1 (Analyze) → Phase 2 (Simplified Plan) → Phase 3 (Implement) → Phase 4 (Review) → Phase 5 (Commit & Merge)
 ```
 
 Skip Phase 2's detailed planning process, but still generate a lightweight `plan.md` with a simplified Tasks section (typically 1-2 tasks).
@@ -206,11 +249,13 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 - Single-task refactors typically have just one task in plan.md
 
 **Fast Path still requires:**
+- Refactor branch (Phase 0)
 - refactor-analysis.md (lightweight version with baseline)
 - plan.md (simplified, 1-2 tasks)
 - Full test suite run after implementation
 - Code review
 - `refactor(<scope>):` commit convention
+- Merge decision
 
 ---
 
@@ -218,15 +263,16 @@ Skip Phase 2's detailed planning process, but still generate a lightweight `plan
 
 The pipeline supports resuming from the last completed phase by detecting existing artifacts.
 
-**Detection logic**: Check `.prizmkit/refactor/<slug>/` for:
+**Detection logic**: Check `.prizmkit/refactor/<slug>/` and git branch state:
 
 | Artifact Found | Resume From |
 |---------------|------------|
-| (nothing) | Phase 1: Analyze |
+| (nothing) | Phase 0: Branch Setup |
+| On `refactor/<slug>` branch, no artifacts | Phase 1: Analyze |
 | `refactor-analysis.md` only | Phase 2: Plan |
 | `refactor-analysis.md` + `plan.md` | Phase 3: Implement |
 | All docs + code changes exist | Phase 4: Review |
-| All docs + review passed | Phase 5: Commit |
+| All docs + review passed | Phase 5: Verify & Commit |
 
 **Resume**: If `<slug>` matches an existing `.prizmkit/refactor/<slug>/` directory, resume instead of starting fresh.
 
@@ -244,6 +290,7 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | Review fails after 2 rounds | Escalate with review findings |
 | Refactoring creates circular dependency | STOP, revise plan |
 | Performance regression detected | STOP, investigate, revise approach |
+| Branch conflict during merge | Show conflict, ask user to resolve or keep branch |
 
 ---
 
@@ -259,23 +306,24 @@ The pipeline supports resuming from the last completed phase by detecting existi
 | `/prizmkit-retrospective` | Phase 5: structural sync before commit (Job 1 only, skip knowledge injection unless new pitfall) |
 | `feature-workflow` | Handoff target when new behavior is needed |
 | `/prizmkit-specify` | NOT used (no user stories for refactoring) |
-| `/prizmkit-analyze` | NOT used (no spec ↔ plan consistency needed) |
+| `/prizmkit-analyze` | NOT used (no spec <-> plan consistency needed) |
 
 ---
 
 ## Comparison with Feature and Bug Fix Pipelines
 
-| Dimension | Feature Workflow | Refactor Workflow | Bug Fix Pipeline |
+| Dimension | Feature Workflow | Refactor Workflow | Bug Fix Workflow |
 |-----------|-----------------|-------------------|------------------|
 | Input | Natural language requirement | Module/code target | Bug description |
-| Pipeline Phases | 6 (Fast: 4) | 5 (Fast: 3) | 5 (Fast: 3) |
-| Phase 1 | Specify (spec.md) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
+| Branch | Pipeline manages per-feature | `refactor/<slug>` | `fix/<BUG_ID>-*` |
+| Pipeline Phases | 3 (plan → launch → monitor) | 6 (branch → analyze → plan → implement → review → commit) | 7 (branch → triage → reproduce → fix → review → verify → commit) |
+| Phase 1 | Plan (app-planner) | Analyze (refactor-analysis.md) | Triage (fix-plan.md) |
 | Artifact Path | `.prizmkit/specs/<slug>/` | `.prizmkit/refactor/<slug>/` | `.prizmkit/bugfix/<id>/` |
 | Commit Prefix | `feat(<scope>):` | `refactor(<scope>):` | `fix(<scope>):` |
-| REGISTRY Update | ✅ | ❌ | ❌ |
 | Test Strategy | TDD per task | Full suite after EVERY task | Reproduction test |
-| Scope Guard | N/A | ✅ (enforced) | N/A |
-| Behavior Change | ✅ Expected | ❌ Forbidden | ✅ Fix behavior |
+| Scope Guard | N/A | Enforced | N/A |
+| Behavior Change | Expected | Forbidden | Fix behavior |
+| User Verification | No (pipeline) | Yes (Phase 5) | Yes (Phase 5) |
 
 ## Output
 
@@ -283,5 +331,5 @@ The pipeline supports resuming from the last completed phase by detecting existi
 - `plan.md` with Tasks section (Phase 2 artifact)
 - Refactored implementation code (Phase 3)
 - Code review report (Phase 4, conversation only)
-- Git commit with `refactor(<scope>):` prefix (Phase 5)
+- Git commit with `refactor(<scope>):` prefix on dedicated refactor branch (Phase 5)
 - Updated `.prizm-docs/` (if applicable)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.106",
+  "version": "1.0.109",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {