prizmkit 1.1.111 → 1.1.112

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

@@ -1,379 +1,245 @@
 ---
 name: "refactor-workflow"
-description: "Triage-based refactor workflow. Clarifies behavior-preserving refactoring goals, then lets the user choose Fast Path for simple current-session/current-workspace refactors or Pipeline Path for complex/batch refactors via refactor-planner → refactor-pipeline-launcher. Use when 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', 'batch refactor'."
+description: "Thin L3 refactor workflow router for behavior-preserving code restructuring. Clarifies enough to choose Fast Path, Pipeline Path, or existing-list launch; routes deep code analysis and item decomposition to refactor-planner and execution configuration to refactor-pipeline-launcher. Use when the user wants to refactor, clean up, restructure, decouple, simplify, migrate internal structure, extract modules, or run an existing refactor list without changing product behavior. Trigger on: 'refactor', 'clean up code', 'restructure', 'optimize code structure', 'extract module', 'decouple', 'code migration', 'batch refactor', 'run refactor list'."
 ---
 
 # Refactor Workflow
 
-Triage-based entry point for code refactoring. The workflow clarifies behavior-preserving goals, assesses risk and scope, asks the user to choose an approach, then follows one of two paths:
+Thin L3 entry point for behavior-preserving refactoring. This workflow routes the user to the right path, prepares a concise handoff brief, and avoids duplicating `refactor-planner` or `refactor-pipeline-launcher` internals.
 
-- **Fast Path** — a simple behavior-preserving refactor is implemented directly in the **current session** and **current workspace** with the normal PrizmKit lifecycle commands.
-- **Pipeline Path** — complex or batch refactors are planned with `refactor-planner`, launched with `refactor-pipeline-launcher`, then monitored.
+## Responsibility Boundary
 
-This skill keeps Fast Path and Pipeline Path separate. Pipeline monitoring only happens after the user selects Pipeline Path and the launcher starts execution.
+This workflow owns:
+- Scenario recognition: Fast Path, Pipeline Path, existing-list launch, or behavior-change reroute.
+- Lightweight behavior-risk triage.
+- User path selection through `AskUserQuestion`.
+- Prompt brief handoff to Fast Path L1 skills, `refactor-planner`, or `refactor-pipeline-launcher`.
+- Continuation after `refactor-planner` when the user entered through this workflow.
 
-## When to Use
-
-User says:
-- "Refactor the auth module", "Clean up this code", "Restructure the payment service"
-- "Extract shared logic into a separate module", "Optimize code structure"
-- "Do this small behavior-preserving cleanup now"
-- "Batch refactor these modules", "Code refactoring across multiple files"
-- Code has accumulated tech debt that needs structural improvement
-- Module needs to be split, merged, or reorganized
-
-**Do NOT use this skill when:**
-- User only wants to plan refactoring without execution → use `refactor-planner` directly
-- User only wants to launch an existing `.prizmkit/plans/refactor-list.json` → use `refactor-pipeline-launcher`
-- User wants to add features → use `feature-workflow`
-- User wants to fix bugs → use `bug-fix-workflow` or `bug-planner` + `bugfix-pipeline-launcher`
-
----
-
-## Overview
-
-The shared contract is:
-
-1. **Brainstorm** — clarify refactoring type, collect reference materials, read relevant code/docs/tests, and confirm behavior-preservation requirements.
-2. **Assess difficulty and behavior risk** — decide whether the request is a simple behavior-preserving Fast Path candidate or a complex/batch Pipeline Path candidate.
-3. **AskUserQuestion approach selection** — present selectable options; never silently choose the path.
-4. **Execute selected path**:
-   - **Fast Path**: `/prizmkit-plan` → `/prizmkit-implement` with behavior-preservation tests/checks → `/prizmkit-code-review` → `/prizmkit-retrospective` → `/prizmkit-committer` in the current workspace.
-   - **Pipeline Path**: `refactor-planner` → `refactor-pipeline-launcher` → monitoring.
-
-### Terminology
-
-| Term | Meaning |
-|------|---------|
-| **Fast Path** | Current-session/current-workspace implementation for simple, behavior-preserving refactors. It does not create or consume `.prizmkit/plans/refactor-list.json` and does not start the refactor pipeline. |
-| **Pipeline Path** | Complex or batch refactor execution. Planner handoff goes to `refactor-planner`; launcher handoff goes to `refactor-pipeline-launcher`; monitoring follows only after launch. |
-| **Current session** | The interactive AI CLI session that is already discussing the refactor with the user. |
-| **Current workspace** | The current git checkout and working tree, not a background pipeline worktree/session. |
-| **Behavior preservation** | External behavior, public contracts, tests, and user-visible outcomes remain unchanged unless the user explicitly approves a behavior change as a feature. |
-| **Monitoring** | Status/log follow-up for a launched refactor pipeline; it is not part of the Fast Path. |
-
-### Workspace and Branch Model
-
-- **Fast Path**: work happens in the current workspace and current interactive session. Use the current branch unless the project policy or user explicitly asks to create a branch.
-- **Pipeline Path**: `refactor-pipeline-launcher` and the dev-pipeline manage per-refactor branches/worktrees. This workflow does not create a top-level branch before handing off to the launcher.
-
----
-
-## Input Modes
-
-**Mode A: Natural language refactoring goal** (default)
-
-Natural language description of the refactoring goals. Can be:
-- A simple behavior-preserving refactor: "Extract this helper function and keep behavior unchanged"
-- A module target: "Refactor the auth module — extract shared middleware, simplify the token flow"
-- A batch of refactors: "Clean up the payment service, decouple the notification module, and extract common utilities"
-- An incremental request: "Also refactor the logging layer to use structured logging"
-
-Flow: brainstorm → complexity/behavior-risk assessment → AskUserQuestion → Fast Path or Pipeline Path.
-
-**Mode B: Existing `.prizmkit/plans/refactor-list.json`**
-
-When the user says "run pipeline from existing file" or `.prizmkit/plans/refactor-list.json` already exists and should be executed:
-- Skip brainstorm and `refactor-planner`
-- Invoke `refactor-pipeline-launcher` directly
-- Monitor and report progress
-
-**Mode C: Incremental refactor request**
-
-When user says "add more refactors":
-- Brainstorm only the new refactoring goals
-- Assess whether the new scope is simple and behavior-preserving enough for Fast Path
-- For simple work: use Fast Path in the current workspace
-- For complex or batch work: invoke `refactor-planner` in incremental mode, then `refactor-pipeline-launcher`
-
----
-
-## Phase 1: Brainstorm — Deep Refactoring Goal Clarification
-
-**Goal**: Through interactive Q&A and deep code reading, transform the user's rough refactoring idea into fully clarified, implementation-ready refactoring goals. This phase is the foundation for safe, behavior-preserving code changes — vague goals produce risky refactors.
-
-**CRITICAL RULE**: The number of questions is **unlimited**. Do NOT rush through this phase. Ask as many rounds as needed until every aspect is clear. Refactoring is inherently risky — thorough understanding prevents broken behavior.
-
-### Step 1.1: Clarify Refactoring Type
-
-**First question** — ask the user to classify the refactoring approach:
-
-| Type | Description | Example |
-|------|-------------|---------|
-| **Incremental** | Piece-by-piece restructuring, each step independently safe | "Gradually extract shared utilities over several PRs" |
-| **Comprehensive** | Full rewrite of a module/area in one pass | "Rewrite the auth module with new architecture" |
-| **Targeted** | Specific, focused change to a particular part | "Extract the validation logic from the controller" |
-
-Then ask:
-- **What** code needs restructuring (modules, files, patterns)
-- **Why** it needs refactoring (tech debt, coupling, complexity, readability, performance structure)
-- **What outcome** they want (target architecture, desired structure, quality goals)
-- **What behavior must remain unchanged** (public APIs, outputs, workflows, tests, performance-sensitive paths)
-
-### Step 1.2: Collect Reference Materials
+This workflow does not own:
+- Deep code analysis, item decomposition, dependency ordering, behavior-preservation strategy selection, schema validation, or plan review gates — those belong to `refactor-planner`.
+- Execution mode, runtime configuration, preflight, command assembly, status/log/stop/retry details — those belong to `refactor-pipeline-launcher`.
+- Product behavior changes — those should route to feature work unless explicitly framed as a behavior-preserving migration.
 
-**Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill:
-1. Acknowledge what was received: "I received the following materials: [list]"
-2. Read/fetch all provided materials immediately
-3. You MUST still ask: "Are there any additional materials you'd like to provide?"
-4. NEVER skip this collection step just because the user already provided some materials
+## Behavior-Preservation Boundary
 
-**If the user has NOT provided any materials upfront**, ask the user explicitly what resources they have. Do NOT skip this step — user-provided materials are far more valuable than blind directory scanning.
+Refactoring means external behavior remains unchanged:
+- Public product behavior stays the same.
+- User-visible outcomes stay the same.
+- Public contracts stay stable unless the user explicitly confirms a compatibility-preserving migration.
+- Tests and behavior checks are used to prove the change is structural.
 
-Ask:
-1. **Code paths** — "Which files or directories are the main targets? Any specific files I should look at?"
-2. **Design documents** — "Do you have any design docs, architecture diagrams, or refactoring proposals I should read?"
-3. **Knowledge docs** — "Are there related `.prizmkit/prizm-docs/`, README files, or internal wiki pages for the target area?"
-4. **Related issues/PRs** — "Any related issues, PRs, or previous refactoring attempts I should be aware of?"
-5. **Behavior checks** — "Which tests, commands, or manual scenarios prove behavior must stay the same?"
+If the request requires changed product behavior, new user-facing functionality, or a breaking public API change, route to `feature-workflow`. Internal API, import path, or module boundary changes can still be refactoring when external behavior remains unchanged and the planner can define a safe migration strategy.
 
-Record everything the user provides — these become inputs for Step 1.3.
-
-### Step 1.3: Parallel Deep Reading
-
-Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.3 for the parallel agent dispatch procedure — spawn 4 agents (A: code paths, B: documents, C: prizm-docs, D: test files) to build comprehensive understanding before discussion. Synthesize findings before proceeding.
-
-### Step 1.4: Discuss Refactoring Plan
+## When to Use
 
-Read `${SKILL_DIR}/references/brainstorm-guide.md` §Step 1.4 for the full discussion framework — code structure, scope, behavior preservation, risk assessment, and constraints. Present what was learned from parallel reading, then ask targeted questions grounded in real code. **Adapt question depth to the refactoring complexity.**
+Use this workflow when the user wants a guided refactoring entry point:
+- Clean up or restructure existing code.
+- Extract modules, helpers, middleware, or shared logic.
+- Decouple modules or simplify structure.
+- Plan or execute behavior-preserving migrations.
+- Decide whether a refactor is small enough for current-session Fast Path or should use the refactor pipeline.
+- Continue from an existing `.prizmkit/plans/refactor-list.json`.
 
-### Step 1.5: Confirm and Supplement
+Do not use this workflow when the user only wants:
+- Refactor planning without execution intent -> use `refactor-planner`.
+- Launch/status/logs/retry for an existing refactor list -> use `refactor-pipeline-launcher`.
+- New functionality or changed product behavior -> use `feature-workflow`.
+- Bug repair -> use `bug-fix-workflow` or the bug pipeline skills.
 
-After the discussion:
+## Route Overview
 
-1. **Summarize** the refactoring plan — present it back to the user
-2. **Ask explicitly**: "Is there anything else you'd like to discuss or supplement before we proceed to formal planning?"
-3. **Identify gaps** — if any areas are still unclear, list them explicitly and ask follow-up questions
-4. **Repeat** until the user confirms: "That covers everything" or "Let's proceed"
+| User situation | Route |
+|---|---|
+| Simple local behavior-preserving refactor | Fast Path in current workspace |
+| Batch, cross-module, high-risk, weak-test, or multi-step refactor | `refactor-planner` -> return here -> `refactor-pipeline-launcher` |
+| Product behavior change or breaking public API change | Route to `feature-workflow` |
+| User explicitly says to run an existing refactor list | `refactor-pipeline-launcher` |
+| Refactor list exists but the user did not explicitly ask to run it | Ask launch / inspect / update |
 
-Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the full checklist of when brainstorming is complete vs when more questions are needed.
+## Route Selection
 
-### Step 1.6: Requirements Summary
+### Step 1: Detect the entry mode
 
-Once brainstorming is complete, produce a structured goals summary. Read `${SKILL_DIR}/references/brainstorm-guide.md` §Refactoring Goals Summary Template for the structured output format. Present the summary to the user and get explicit confirmation before proceeding.
+Classify the request before asking detailed refactoring questions:
 
-The summary must include behavior-preservation expectations: tests to run, public contracts to keep stable, and any explicitly approved behavior changes. If behavior changes are required, route them as feature work rather than refactoring unless the user explicitly scopes them here.
+- **Behavior-preserving refactor**: the user asks to clean up, restructure, simplify, extract, decouple, or migrate implementation structure.
+- **Behavior change**: the user asks to change what the product does, add functionality, or break a public contract.
+- **Existing list launch**: the user explicitly asks to run, start, resume, check, retry, or stop `.prizmkit/plans/refactor-list.json`.
+- **Unclear**: the request mixes cleanup with behavior changes.
 
-**CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.
+If behavior preservation is unclear, ask one concise clarification question before route selection.
 
----
+### Step 2: Lightweight triage for behavior-preserving work
 
-### Step 1.7: Complexity Assessment & Approach Selection
+Use lightweight criteria only. Do not perform full code analysis or item decomposition here.
 
-After confirming refactoring goals, assess whether this refactor needs the Pipeline Path or can be done directly in the current session/current workspace.
+Fast Path candidate when all are true:
+- One focused refactor or a small tightly related cleanup.
+- Expected work is localized and follows existing patterns.
+- Behavior-preservation checks are obvious or already available.
+- No broad dependency ordering, public behavior change, or risky migration is needed.
 
-**Simple behavior-preserving refactor → Fast Path candidate** (ALL must be true):
-- Single module, no cross-module impact
-- ≤3 files affected
-- No public API or interface changes
-- Straightforward transformation (extract method, rename, move file, simplify logic)
-- Existing tests or focused checks cover the affected behavior
-- No behavior change risk beyond what tests/checks can verify
+Pipeline Path candidate when any are true:
+- Multiple refactor items or batch refactoring request.
+- Cross-module or multi-layer impact.
+- Import-path, internal API, or module-boundary migration needs ordering.
+- Weak test coverage creates behavior-preservation risk.
+- The user wants autonomous/background execution.
+- The request needs `refactor-planner` to analyze code, split items, validate ordering, and review entries.
 
-**Complex or batch refactors → Pipeline Path candidate** (ANY is true):
-- Multiple refactor items or batch refactoring request
-- Cross-module impact (>2 modules affected)
-- Public API or interface changes required
-- Multiple interrelated refactoring steps with dependency ordering
-- Comprehensive rewrite of a module
-- Insufficient test coverage in target area (risk of hidden behavior changes)
-- Requires coordination with other ongoing work
+### Step 3: Ask for path selection
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment: for a simple refactor, "This refactor appears straightforward and behavior-preserving enough for the current-session Fast Path." For a complex or batch refactor, "This refactor is complex or batch-oriented and should use the Pipeline Path."
+Use `AskUserQuestion`; do not render path options as plain text.
 
+```text
+Question: How would you like to proceed?
+Header: Approach
+Options:
+- Refactor now (Fast Path) — current session/current workspace via /prizmkit-plan -> /prizmkit-implement with behavior checks
+- Use Pipeline Path — refactor-planner creates/reviews refactor-list.json, then refactor-pipeline-launcher configures execution
+- Continue clarifying — ask a few more route-level questions before choosing
 ```
-AskUserQuestion:
-  question: "How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Refactor now (Fast Path — current session/current workspace)"
-      description: "Run /prizmkit-plan → /prizmkit-implement → /prizmkit-code-review → /prizmkit-retrospective → /prizmkit-committer directly in this workspace with behavior-preservation checks"
-    - label: "Use Pipeline Path (refactor-planner → refactor-pipeline-launcher)"
-      description: "Generate .prizmkit/plans/refactor-list.json with refactor-planner, then launch autonomous execution with refactor-pipeline-launcher"
-```
-
-- **Refactor now (Fast Path)**:
-  1. Invoke `/prizmkit-plan` with the goals summary → generates `spec.md` + `plan.md` including behavior-preservation strategy
-  2. Invoke `/prizmkit-implement` to execute the plan in the current workspace and verify behavior stays unchanged
-  3. Run `/prizmkit-code-review` for quality and behavior-preservation review
-  4. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
-  5. Commit via `/prizmkit-committer` with `refactor(<scope>):` prefix
-  6. End workflow — do not call `refactor-planner`, do not call `refactor-pipeline-launcher`, and do not enter monitoring
-- **Use Pipeline Path** → Continue to Phase 2 (Planner handoff)
-
-**NEVER proceed without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
-
-**CHECKPOINT CP-RW-0.5**: Approach selected by user (Fast Path or Pipeline Path).
-
----
-
-## Phase 2: Plan — Pipeline Path Only
-
-**Goal**: Generate structured `.prizmkit/plans/refactor-list.json` from the clarified refactoring goals.
-
-Run this phase only when the user selected Pipeline Path or provided a batch/complex refactor request that they chose to send through the pipeline.
-
-**STEPS**:
-
-1. **Planner handoff — invoke `refactor-planner`** with the full goals summary from Phase 1:
-   - Pass the structured goals summary as input — NOT the raw user conversation
-   - For new refactoring: standard planning mode
-   - For existing projects with `--incremental`: incremental planning mode
-   - **Input**: Markdown goals summary (refactor targets, scope, behavior preservation strategy)
-   - **Output**: `.prizmkit/plans/refactor-list.json` (schema: `dev-pipeline-refactor-list-v1`) containing `project_name`, `refactors[]` with id (R-NNN), title, description, scope, type, priority, complexity, behavior_preservation, acceptance_criteria, dependencies, status
 
-2. **Interactive planning** (if `refactor-planner` requires clarification):
-   - Because Phase 1 was thorough, `refactor-planner` should need minimal clarification
-   - If questions arise, answer from the Phase 1 context or pass through to user
+If the request appears to change product behavior:
 
-3. **Validate output**:
-   - Confirm `.prizmkit/plans/refactor-list.json` exists
-   - Show summary: total refactor items, complexity distribution, dependencies, behavior-preservation coverage
-
-**CHECKPOINT CP-RW-1**: `.prizmkit/plans/refactor-list.json` generated and validated.
+```text
+Question: This appears to change behavior rather than only restructure code. What should we do?
+Header: Boundary
+Options:
+- Route to feature-workflow (Recommended) — treat behavior change as feature work
+- Keep as refactor — only if behavior remains externally unchanged or this is a compatibility-preserving migration
+- Continue clarifying — define which behavior must stay unchanged
+```
 
-**If `.prizmkit/plans/refactor-list.json` already exists or user says `--from <file>`**: skip ahead per the [Resume table](#resume--interruption-recovery).
+For an auto-discovered existing refactor list:
 
----
+```text
+Question: Existing refactor-list.json found. What should we do with it?
+Header: Refactor list
+Options:
+- Launch existing list — hand off to refactor-pipeline-launcher
+- Inspect summary first — show refactor count/status, then ask again
+- Update/re-plan — hand off to refactor-planner in incremental mode
+- Ignore and start fresh — continue route selection from the new request
+```
 
-## Phase 3: Launch — Pipeline Path Only
+If the user explicitly asked to run an existing list, that explicit request counts as path selection; hand off directly to `refactor-pipeline-launcher`.
 
-**Goal**: Start the refactoring pipeline after planner handoff has produced a validated refactor list.
+## Workflow Handoff Brief
 
-**STEPS**:
+When handing off, include this prompt brief in the next skill invocation. Do not write the brief to disk.
 
-1. **Show refactor summary** before launching:
-   ```
-   Ready to launch Pipeline Path with N refactor items:
-     R-001: Extract auth middleware (medium complexity)
-     R-002: Decouple notification service (high complexity)
-     R-003: Simplify token flow (low complexity)
+```markdown
+## Workflow Handoff Brief
 
-   Proceed? (Y/n)
-   ```
+### Source
+- workflow: refactor-workflow
+- selected_path: fast_path | pipeline_path | existing_list_launch | behavior_change_reroute
 
-2. **Launcher handoff — invoke `refactor-pipeline-launcher`**:
-   - **Input**: Path to validated `.prizmkit/plans/refactor-list.json`
-   - The launcher handles all prerequisites checks
-   - The launcher presents execution mode choices to the user (foreground/background/manual)
-   - The launcher preserves strict behavior-check defaults
-   - Do NOT duplicate execution mode selection here — let the launcher handle it
-   - **Output**: PID/status, log file path, execution mode selected
-   - Returns PID/status and log file location
+### User Goal
+- original_request: <preserve the user's wording>
+- normalized_goal: <lightly normalized refactoring goal>
 
-3. **Verify launch success**:
-   - Confirm pipeline is running
-   - Record PID and log path for Phase 4
+### Scope
+- included: <explicitly in scope>
+- excluded: <explicitly out of scope or unknown>
 
-**CHECKPOINT CP-RW-2**: Pipeline launched successfully.
+### Behavior Preservation
+- must_remain_unchanged: <public behavior, user-visible outcomes, APIs, workflows, tests>
+- suspected_behavior_changes: <items that may need feature-workflow>
 
----
+### Materials
+- provided_paths: <paths/directories supplied by the user>
+- provided_docs_or_urls: <docs, links, screenshots, or specs supplied by the user>
+- notes: <rules, constraints, or emphasis from the user>
 
-## Phase 4: Monitor — Pipeline Path Only
+### Decision
+- route_reason: <why this path was selected>
+- user_confirmed: yes
 
-**Goal**: Track pipeline progress and report to user. Monitoring applies only after `refactor-pipeline-launcher` has started a pipeline.
+### Next Skill Instruction
+- For planner: Use this brief as input; perform your own required code analysis, behavior-preservation planning, validation, generation, and review gate.
+- For Fast Path: Use this brief to create spec.md/plan.md and implement only this behavior-preserving scope.
+```
 
-**STEPS**:
+## Selected Path Execution
 
-1. **Initial status check**:
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status
-   ```
+### Fast Path
 
-2. **Offer monitoring options**:
-   - "I'll check progress periodically. Say 'status' anytime for an update."
-   - "Say 'logs' to see recent activity."
-   - "Say 'stop' to pause the pipeline."
+Use Fast Path only after explicit user selection.
 
-3. **Periodic progress reports** (when user asks):
-   ```bash
-   python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
-   ```
+1. Invoke `/prizmkit-plan` with the handoff brief and behavior-preservation expectations.
+2. Invoke `/prizmkit-implement` after the plan is ready.
+3. Run behavior-preservation checks identified in the plan.
+4. Run `/prizmkit-code-review` as the quality and behavior-preservation gate.
+5. Run `/prizmkit-retrospective` before commit because refactors often change durable structure.
+6. Run `/prizmkit-committer` with a `refactor(<scope>):` message.
+7. End the workflow after commit; do not call `refactor-planner`, `refactor-pipeline-launcher`, or monitoring.
 
-4. **Completion report** (when pipeline finishes all refactor items):
-   ```
-   Pipeline completed: 3/3 refactor items
+If the refactor starts changing behavior or grows beyond Fast Path criteria, pause and ask whether to switch to `feature-workflow` or Pipeline Path.
 
-   Summary:
-   - R-001: Extract auth middleware → COMMITTED (refactor(auth): extract shared middleware)
-   - R-002: Decouple notification service → COMMITTED (refactor(notifications): decouple from core)
-   - R-003: Simplify token flow → COMMITTED (refactor(auth): simplify token refresh)
+### Pipeline Path
 
-   Next steps:
-   - Review changes: git log --oneline -5
-   - Run tests: npm test
-   - Push when ready: git push
-   ```
+1. Invoke `refactor-planner` with the handoff brief.
+2. `refactor-planner` performs code analysis, item decomposition, behavior-preservation planning, validation, and plan review.
+3. After `refactor-planner` reports a validated `.prizmkit/plans/refactor-list.json`, show a concise summary: item count, ordering highlights, preservation strategy summary, and review/validation outcome.
+4. Ask whether to proceed to launch.
+5. If yes, invoke `refactor-pipeline-launcher`.
 
-**CHECKPOINT CP-RW-3**: All refactor items completed or user stopped pipeline.
+Do not duplicate launcher execution-mode, strict-behavior-check, or runtime configuration questions in this workflow; the launcher owns them.
 
----
+### Existing list launch
 
-## Resume — Interruption Recovery
+If the user explicitly requested launch/status/logs/retry/stop for an existing refactor list, invoke `refactor-pipeline-launcher` with the user's intent and list path.
 
-The workflow supports resuming by detecting existing state:
+If this workflow discovered the list on its own, use the `Existing refactor-list.json found` question in §Route Selection before invoking the launcher.
 
-| State Found | Resume From |
-|-------------|-------------|
-| Fast Path `spec.md` + `plan.md` exist, code not committed | Resume `/prizmkit-implement` / review / retrospective / commit based on current state |
-| No `.prizmkit/plans/refactor-list.json` and no Fast Path artifacts | Phase 1: Brainstorm |
-| `.prizmkit/plans/refactor-list.json` exists, no pipeline state | Phase 3: Launch |
-| `.prizmkit/plans/refactor-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
-| All refactors completed | Report completion, suggest next steps |
+## Resume Guidance
 
-**Resume**: If `.prizmkit/plans/refactor-list.json` exists, ask user: "Existing refactor plan found with N items. Resume Pipeline Path or re-plan?" If Fast Path artifacts exist, ask whether to continue the current-workspace refactor or discard/re-plan.
+| State found | Action |
+|---|---|
+| Fast Path `spec.md` / `plan.md` exists | Ask whether to continue current-workspace refactor or re-plan |
+| Valid `.prizmkit/plans/refactor-list.json` exists and user wants execution | Invoke `refactor-pipeline-launcher` |
+| Valid refactor list exists but intent is unclear | Ask launch / inspect / update |
+| No plan/list artifacts | Start route selection |
 
----
+For interrupted autonomous pipeline sessions, prefer `refactor-pipeline-launcher` status/retry operations or `recovery-workflow` when the user explicitly asks to recover a broken AI session.
 
-## Interaction During Pipeline
+## Runtime Status Reference
 
-While the pipeline runs, the user can continue the conversation:
+This workflow does not assemble runtime commands, but it may show lightweight status before handoff or recovery. Use the canonical Python runtime forms:
 
-| User says | Action |
-|-----------|--------|
-| "status" / "progress" | Show current progress |
-| "logs" | Show recent log activity |
-| "stop" | Stop the pipeline (state preserved) |
-| "show R-002 logs" | Show specific refactor item's session log |
+```bash
+python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor status
+python3 ./.prizmkit/dev-pipeline/cli.py refactor status .prizmkit/plans/refactor-list.json
+```
 
----
+For start/stop/logs/retry execution, hand off to `refactor-pipeline-launcher`; do not duplicate launcher configuration here.
 
 ## Error Handling
 
-| Error | Action |
-|-------|--------|
-| User's refactoring goal is too vague | Ask for more context: "Can you describe what's wrong with the current code structure?" |
-| Brainstorming stalls | Offer concrete options: "Would you prefer incremental or comprehensive refactoring?" |
-| No tests exist for target module | WARN user, recommend writing tests/checks before Fast Path; consider Pipeline Path for risky refactors |
-| Fast Path starts risking behavior change | Pause and ask whether to switch to Pipeline Path (`refactor-planner` → `refactor-pipeline-launcher`) |
-| `refactor-planner` cannot parse goals | Refine the goals summary and retry |
-| `.prizmkit/plans/refactor-list.json` generation failed | Show error, retry with refined input |
-| Pipeline launch failed | Show daemon log, suggest manual start with `python3 ./.prizmkit/dev-pipeline/cli.py refactor run .prizmkit/plans/refactor-list.json` or `python3 ./.prizmkit/dev-pipeline/cli.py daemon refactor start .prizmkit/plans/refactor-list.json` |
-| All refactor items blocked/failed | Show status, suggest retrying specific items |
-| User wants to cancel mid-brainstorming | Save conversation context, offer to resume later |
-| Behavior regression detected during Fast Path | Revert or fix immediately before commit; refactoring cannot ship with behavior regression |
-| Behavior regression detected during pipeline | Pipeline handles per-item retries/failures; report failed items and behavior checks |
-
----
+| Situation | Action |
+|---|---|
+| Behavior change is required | Route to `feature-workflow` unless user confirms a behavior-preserving migration |
+| User wants planning only | Route to `refactor-planner` and stop after planner summary |
+| User wants execution only | Route to `refactor-pipeline-launcher` |
+| No behavior checks exist | Warn user; recommend Pipeline Path unless scope is very small |
+| Fast Path reveals broader risk | Pause and ask whether to switch to Pipeline Path |
+| Planner needs more detail | Let `refactor-planner` ask its own clarification questions |
+| Launcher finds baseline/config issues | Let `refactor-pipeline-launcher` handle confirmation and configuration |
 
-## HANDOFF
+## Handoff Map
 
 | From | To | Condition |
-|------|----|-----------|
-| **this skill** | `/prizmkit-plan` | User selects Fast Path for simple behavior-preserving refactor work in the current workspace |
-| **this skill** | `/prizmkit-implement` | Fast Path plan is ready for current-session implementation with behavior checks |
-| **this skill** | `/prizmkit-code-review` | Fast Path refactor is complete and needs quality/behavior-preservation review |
-| **this skill** | `/prizmkit-retrospective` | Fast Path refactor changes need `.prizmkit/prizm-docs/` sync before commit |
-| **this skill** | `/prizmkit-committer` | Fast Path refactor is reviewed, docs are synced, and behavior preservation is verified |
-| **this skill** | `refactor-planner` | User selects Pipeline Path for complex or batch refactors |
-| `refactor-planner` | `refactor-pipeline-launcher` | Planner handoff produced validated `.prizmkit/plans/refactor-list.json` |
-| `refactor-pipeline-launcher` | **this skill** | Launcher handoff completed and monitoring/status follow-up is needed |
-
----
+|---|---|---|
+| `refactor-workflow` | `feature-workflow` | Request requires product behavior change |
+| `refactor-workflow` | `/prizmkit-plan` | User selects Fast Path |
+| `refactor-workflow` | `refactor-planner` | User selects Pipeline Path |
+| `refactor-planner` | `refactor-workflow` | Planner completed from workflow-origin Pipeline Path |
+| `refactor-workflow` | `refactor-pipeline-launcher` | User confirms launch after planner completion or explicitly requests existing-list execution |
 
 ## Output
 
-Output depends on the selected path:
-
-- **Fast Path**: `spec.md` + `plan.md`, behavior-preserving current-workspace code changes, behavior test/check evidence, `/prizmkit-code-review` result, updated `.prizmkit/prizm-docs/`, and one `refactor(<scope>):` commit from `/prizmkit-committer`.
-- **Pipeline Path**: structured refactoring goals summary, `.prizmkit/plans/refactor-list.json`, pipeline execution via `refactor-pipeline-launcher`, monitoring updates, and per-refactor commits managed by the dev-pipeline.
+- Fast Path: `spec.md`, `plan.md`, behavior-preserving code changes, behavior-check evidence, review result, Prizm docs sync, and one refactor commit.
+- Pipeline Path: handoff brief, validated `.prizmkit/plans/refactor-list.json` from `refactor-planner`, and pipeline launch/status handled by `refactor-pipeline-launcher`.

package/package.json

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

package/src/scaffold.js

@@ -1130,6 +1130,11 @@ export async function installPipeline(projectRoot, dryRun, options = {}) {
     const src = path.join(pipelineSource, relativeFile);
     const tgt = path.join(pipelineTarget, relativeFile);
 
+    if (!await fs.pathExists(src)) {
+      skippedCount++;
+      continue;
+    }
+
     if (await fs.pathExists(tgt) && !overwriteExisting) {
       skippedCount++;
       continue;

package/bundled/dev-pipeline/templates/agent-prompts/reviewer-review.md

@@ -1,6 +0,0 @@
-"Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` (if it exists) for goals and Verification Gates; if spec.md does not exist, read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` Section 1 Task Contract instead.
-2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks.
-3. Review the current workspace changes and return structured findings only. Do not run `/prizmkit-code-review`, do not apply fixes, do not run test suites, and do not spawn other agents.
-4. The main orchestrator owns the review-fix loop: Reviewer Agent → filter → orchestrator fix.
-Report: PASS/NEEDS_FIXES, findings with severity/location/problem/suggestion/verification, and a concise summary."