prizmkit 1.0.108 → 1.0.110

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.108",
-  "bundledAt": "2026-03-26T01:27:22.624Z",
-  "bundledFrom": "90a9f59"
+  "frameworkVersion": "1.0.110",
+  "bundledAt": "2026-03-26T02:24:41.453Z",
+  "bundledFrom": "9b18d27"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.108",
+  "version": "1.0.110",
   "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/app-planner/SKILL.md

@@ -14,10 +14,10 @@ Always produce a validated `feature-list.json` that conforms to `dev-pipeline-fe
 ## When to Use
 
 Trigger this skill for requests like:
-- "Plan an app", "Design a project", "Plan an app", "Design a new application"
-- "Add features to existing system", "Continue planning", "Add features", "Continue planning"
+- "Plan an app", "Design a project", "Design a new application"
+- "Add features to existing system", "Continue planning"
 - "Prepare feature-list.json", "Prepare dev-pipeline input"
-- "Reprioritize features", "Split features", "reprioritize/scope features"
+- "Reprioritize features", "Split features"
 
 Do NOT use this skill when:
 - user only wants to run pipeline now (invoke `dev-pipeline-launcher`)
@@ -376,9 +376,10 @@ When the session appears to be ending (user says "thanks", "that's all", "bye",
 1. **Remind**: "You set out to produce `feature-list.json` but we haven't completed it yet."
 2. **Offer 3 options**:
    - **(a) Continue to completion** — resume from current phase
-   - **(b) Abandon** — confirm user explicitly wants to exit without output
-3. **If (b) Save draft**: Write the draft file and remind user: "This is a draft, not validated. Run `/app-planner` again to resume and finalize."
-4. **If (c) Abandon**: Accept without further prompting.
+   - **(b) Save draft & exit** — write current progress as draft, exit session
+   - **(c) Abandon** — exit without saving
+3. **If (b)**: Write the draft file and remind user: "This is a draft, not validated. Run `/app-planner` again to resume and finalize."
+4. **If (c)**: Accept without further prompting.
 
 
 ## Handoff Message Template

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

@@ -23,14 +23,62 @@ Fix a single bug interactively within the current AI CLI session. This is the in
 
 ## Input
 
-The bug can come from:
-- **A bug-fix-list.json entry**: "fix B-001" → read the entry from bug-fix-list.json
-- **A stack trace/error message**: user pastes error directly
-- **A description**: "the login page crashes when I click submit"
-- **A failed test**: "this test is failing: src/auth/__tests__/login.test.ts"
+**PRECONDITION:**
+
+| Input Source | Detection | Example |
+|---|---|---|
+| Bug-fix-list.json entry | User says "fix B-001" → read entry from `bug-fix-list.json` | `fix B-001` |
+| Stack trace / error message | User pastes error directly | `TypeError: Cannot read property...` |
+| Natural language description | User describes the problem | "login page crashes on submit" |
+| Failed test | User references a failing test file | `src/auth/__tests__/login.test.ts` |
+
+At least one input source must be provided. If none is clear, ask the user to describe the bug.
+
+## 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 +156,75 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
-### Phase 5: Commit
+### Phase 5: User Verification
 
-**Goal**: Commit the fix with proper conventions.
+**Goal**: Let the user verify the fix works as expected before committing.
+
+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 +238,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 +255,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 +264,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/bug-planner/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "bug-planner"
 tier: companion
-description: "Interactive bug planning that produces bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. Use this skill whenever the user has bugs to report, errors to parse, or test failures to organize. Trigger on: 'plan bug fixes', 'report bugs', 'I have some bugs', 'these tests are failing', 'here is an error log', 'parse these errors', 'fix bugs', 'generate bug list', 'plan bug fixes'. (project)"
+description: "Interactive bug planning that produces bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. Use this skill whenever the user has bugs to report, errors to parse, or test failures to organize. Trigger on: 'plan bug fixes', 'report bugs', 'I have some bugs', 'these tests are failing', 'here is an error log', 'parse these errors', 'generate bug list'. (project)"
 ---
 
 # Bug Planner
@@ -12,9 +12,8 @@ Interactive skill that collects bug information from various input formats and g
 
 User says:
 - "plan bug fixes", "report bugs", "create bug list"
-- "fix bugs", "generate bug list", "plan bug fixes"
-- "I have some bugs to fix", "these tests are failing"
-- "here's an error log", "parse these errors"
+- "generate bug list", "I have some bugs to fix"
+- "these tests are failing", "here's an error log", "parse these errors"
 - After receiving bug reports, error logs, or failed test output
 
 **Do NOT use when:**
@@ -28,7 +27,7 @@ This skill handles multiple operations. Determine the user's intent and execute
 
 | User Intent | Operation | Trigger Phrases |
 |---|---|---|
-| Plan bugs interactively | **Interactive Planning** | "plan bug fixes", "report bugs", "plan bug fixes" |
+| Plan bugs interactively | **Interactive Planning** | "plan bug fixes", "report bugs" |
 | Parse error logs into bugs | **From Log** | "parse this error log", "here's a stack trace", "parse these errors" |
 | Parse test failures into bugs | **From Tests** | "these tests are failing", "parse test output" |
 | Validate existing bug list | **Validate** | "validate bug list", "check bug-fix-list.json" |

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

@@ -1,23 +1,35 @@
 ---
 name: "bugfix-pipeline-launcher"
-description: "Launch and manage the bugfix pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start fixing bugs, run the bugfix pipeline, check bugfix progress, or stop the bugfix pipeline. Trigger on: 'start fixing bugs', 'run bugfix pipeline', 'bugfix status', 'stop bug fix', 'launch bug fix', 'start fixing bugs', 'fix progress', 'stop fixing'. (project)"
+description: "Launch and manage the bugfix pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start fixing bugs, run the bugfix pipeline, check bugfix progress, or stop the bugfix pipeline. Trigger on: 'start fixing bugs', 'run bugfix pipeline', 'bugfix status', 'stop bug fix', 'launch bug fix', 'fix progress', 'stop fixing'. (project)"
 ---
 
 # 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
 
 **Start bugfix pipeline** -- User says:
 - "start fixing bugs", "run bugfix pipeline", "launch bug fixes", "fix all bugs"
-- "start bug fix", "run bug fix", "execute bug list", "begin fixing"
-- "launch bug fix", "start fixing bugs", "run bug fix pipeline", "start fixing bugs"
-- "fix all bugs", "batch fix", "launch fix pipeline"
+- "start bug fix", "execute bug list", "begin fixing", "batch fix"
 - After bug-planner completes: "fix them", "start fixing"
 
 **Check status** -- User says:
@@ -25,12 +37,11 @@ Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop
 - "fix progress", "bug fix status", "check fix progress", "how far along are the fixes"
 
 **Stop bugfix pipeline** -- User says:
-- "stop bug fix", "stop fixing", "halt bugfix", "pause bug fix"
-- "stop fixing", "pause bug fix", "stop fix pipeline"
+- "stop bug fix", "stop fixing", "halt bugfix", "pause bug fix", "stop fix pipeline"
 
 **Show logs** -- User says:
 - "bugfix logs", "show fix logs", "what's being fixed"
-- "view fix logs", "fix logs", "check fix status"
+- "view fix logs", "fix logs"
 
 **Do NOT use this skill when:**
 - User wants to plan/collect bugs (use `bug-planner` instead)
@@ -41,7 +52,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 +111,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 +285,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/dev-pipeline-launcher/SKILL.md

@@ -25,14 +25,13 @@ Use daemon mode (`launch-daemon.sh`) only when:
 **Start pipeline** -- User says:
 - "run pipeline", "start pipeline", "start building", "launch dev-pipeline"
 - "run the features", "execute feature list", "start implementing"
-- "launch pipeline", "start implementing", "run the pipeline", "start auto-development"
-- "implement next steps", "execute feature list", "start building"
+- "launch pipeline", "run the pipeline", "start auto-development"
 - After app-planner completes: "build it", "start developing from the feature list"
 - "run only F-001 to F-005", "run features F-001,F-003", "only build these features"
 
 **Check status** -- User says:
 - "pipeline status", "check pipeline", "how's it going", "progress"
-- "pipeline status", "check progress", "what's the current situation"
+- "check progress", "what's the current situation"
 
 **Stop pipeline** -- User says:
 - "stop pipeline", "kill pipeline", "halt", "pause"
@@ -40,11 +39,10 @@ Use daemon mode (`launch-daemon.sh`) only when:
 
 **Show logs** -- User says:
 - "show logs", "pipeline logs", "tail logs", "what's happening"
-- "view logs", "pipeline logs", "check the logs"
+- "view logs", "check the logs"
 
 **Retry single feature node** -- User says:
-- "retry F-003", "retry this feature", "retry this node"
-- "retry F-003", "retry this node", "re-run this feature"
+- "retry F-003", "retry this feature", "retry this node", "re-run this feature"
 
 **Do NOT use this skill when:**
 - User wants to plan features (use `app-planner` instead)
@@ -148,14 +146,13 @@ Detect user intent from their message, then follow the corresponding workflow:
 
 5. **Ask user to confirm**: "Ready to launch the pipeline? It will process N features."
 
-6. **Launch**:
-   ```bash
-   dev-pipeline/launch-daemon.sh start feature-list.json
-   ```
-   If user specified environment overrides (e.g. timeout, retries, verbose):
-   ```bash
-   dev-pipeline/launch-daemon.sh start feature-list.json --env "SESSION_TIMEOUT=7200 MAX_RETRIES=5"
-   ```
+6. **Launch** (based on chosen mode from step 4):
+   - Foreground: `dev-pipeline/run.sh run feature-list.json`
+   - Background: `dev-pipeline/launch-daemon.sh start feature-list.json`
+   - If user specified environment overrides:
+     ```bash
+     dev-pipeline/launch-daemon.sh start feature-list.json --env "SESSION_TIMEOUT=7200 MAX_RETRIES=5"
+     ```
 
 7. **Verify launch**:
    ```bash

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/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
 
@@ -54,6 +56,14 @@ Refactor artifacts stored at `.prizmkit/refactor/<refactor-slug>/`:
 - **`refactor-analysis.md`** — Code analysis (Phase 1)
 - **`plan.md`** — Refactoring plan with Tasks section (Phase 2)
 
+**PRECONDITION:**
+
+| Required | Check | If Missing |
+|---|---|---|
+| Refactoring target (module path, file path, or natural language description) | User provides target in request | Ask: "What module or code do you want to refactor?" |
+| Test suite exists for target module | Tests can be located and run | WARN user, recommend writing tests first before refactoring |
+| No uncommitted changes on current branch | `git status` is clean | Ask user to commit or stash changes first |
+
 **INPUT**: Target description. Can be:
 - Module or file path (e.g., "src/auth/")
 - Natural language description (e.g., "refactor the auth module, extract shared logic")
@@ -61,6 +71,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 +193,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 +239,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 +257,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 +271,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 +298,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 +314,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 +339,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.108",
+  "version": "1.0.110",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {