prizmkit 1.1.79 → 1.1.81

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

@@ -26,39 +26,12 @@ User says:
 
 ## Overview
 
-```
-refactor-workflow <target / goals>
-   │
-   ├── Phase 1: Brainstorm → clarify type → collect materials → parallel deep read → discuss plan
-   │
-   ├── Phase 2: Plan → refactor-planner → .prizmkit/plans/refactor-list.json
-   │
-   ├── Phase 3: Launch → refactor-pipeline-launcher → pipeline execution
-   │
-   └── Phase 4: Monitor → track progress → report results
-```
-
-### What This Skill Does
-
-| Phase | Action | Result |
-|-------|--------|--------|
-| 1 | **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code | Fully clarified refactoring goals |
-| 2 | Call `refactor-planner` with clarified goals | `.prizmkit/plans/refactor-list.json` with N refactor items |
-| 3 | Call `refactor-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
-| 4 | Monitor progress | Status updates, completion report |
-
-### Why This Skill Exists
-
-Without this skill, users must:
-1. Figure out all refactoring goals and scope themselves
-2. Invoke `refactor-planner` → wait for .prizmkit/plans/refactor-list.json
-3. Invoke `refactor-pipeline-launcher` → wait for pipeline start
-4. Manually check progress
+Four phases take a rough refactoring idea to verified, behavior-preserving code so the user doesn't have to manually chain planner → launcher → monitoring:
 
-With this skill, users can:
-1. Say "Refactor the auth module to extract shared middleware" with a rough idea
-2. The skill brainstorms to fill in all gaps (scope, risks, behavior contracts)
-3. All planning + execution happens automatically
+1. **Brainstorm** — clarify type, collect reference materials, parallel deep read code & docs, discuss plan grounded in real code → fully clarified refactoring goals
+2. **Plan** — call `refactor-planner` → `.prizmkit/plans/refactor-list.json` with N refactor items
+3. **Launch** — call `refactor-pipeline-launcher` → pipeline started (execution mode chosen by user via launcher)
+4. **Monitor** — track progress → status updates, completion report
 
 ### Branch Management
 
@@ -80,21 +53,9 @@ Natural language description of the refactoring goals. Can be:
 
 Flow: brainstorm → refactor-planner → refactor-pipeline-launcher → monitor
 
-**Mode B: From existing .prizmkit/plans/refactor-list.json**
+**Mode B: From existing `.prizmkit/plans/refactor-list.json`** — user says "run pipeline from existing file", or the file already exists. Skip ahead per the [Resume table](#resume--interruption-recovery).
 
-When user says "run pipeline from existing file" or .prizmkit/plans/refactor-list.json already exists:
-- Skip brainstorm and `refactor-planner` (file already exists)
-- Invoke `refactor-pipeline-launcher` directly
-- Monitor and report progress
-
-**Mode C: Incremental (add to existing refactor plan)**
-
-When user says "add more refactors" or the project already has a .prizmkit/plans/refactor-list.json:
-- Brainstorm new refactoring goals with the user
-- Invoke `refactor-planner` in incremental mode (reads existing .prizmkit/plans/refactor-list.json)
-- Append new refactor items to existing list
-- Invoke `refactor-pipeline-launcher`
-- Monitor and report progress
+**Mode C: Incremental (add to existing refactor plan)** — user says "add more refactors". Brainstorm new goals, then invoke `refactor-planner` in incremental mode (appends to existing list) → launch → monitor.
 
 ---
 
@@ -139,59 +100,11 @@ Record everything the user provides — these become inputs for Step 1.3.
 
 ### Step 1.3: Parallel Deep Reading
 
-**Goal**: Build comprehensive understanding of the target code and context before discussing plans. Spawn multiple agents in parallel to read all relevant materials simultaneously.
-
-**Parallel reading tasks** (launch concurrently):
-
-| Agent | What to read | Purpose |
-|-------|-------------|---------|
-| Agent A | User-provided code paths — read full source files | Understand current structure, interfaces, dependencies |
-| Agent B | User-provided documents — design docs, proposals, wiki pages | Understand intended direction and constraints |
-| Agent C | `.prizmkit/prizm-docs/` for affected modules — L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
-| Agent D | Test files for the target area — find and read existing tests | Understand current test coverage and behavior contracts |
-
-**Also gather** (can be included in any agent's task):
-- `.prizmkit/config.json` → tech stack preferences
-- Directory structure of the target area
-- Dependency relationships (imports/exports between target and other modules)
-
-**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+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
 
-**Now** — with deep knowledge of the actual code and documents — discuss the refactoring plan with the user. This discussion is grounded in real code, not abstract questions.
-
-Present what you learned from the parallel reading:
-- Current code structure and its problems (with specific file/function references)
-- Existing test coverage status (which areas are safe, which are risky)
-- Known TRAPS and pitfalls from `.prizmkit/prizm-docs/`
-- Dependencies and potential impact on other modules
-
-Then ask targeted questions based on what you read. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
-
-**Code Structure:**
-- "I see the current structure does X — is the target state Y, or something different?"
-- What's the target state? What should the code look like after refactoring?
-- Are there specific code smells you've noticed? (duplication, deep nesting, god classes, tight coupling)
-
-**Scope:**
-- Based on the code I read, these modules are affected: [list]. Anything else in/out of scope?
-- For incremental refactoring: what's the order of priority?
-
-**Behavior Preservation:**
-- "These public APIs/interfaces exist: [list]. Which must remain unchanged?"
-- "I found these tests: [list]. Are they passing currently?"
-- Any undocumented behavior that callers depend on?
-
-**Risk Assessment:**
-- "I found these TRAPS in .prizmkit/prizm-docs/: [list]. Any other known gotchas?"
-- Does this code have external consumers (other teams, published APIs)?
-- Any concurrent development happening in the target area?
-
-**Constraints:**
-- Timeline or urgency? (affects whether to do incremental vs comprehensive)
-- Team coordination needed? (other developers working in the same area)
-- Deployment concerns? (feature flags, backward compatibility, migration)
+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.**
 
 ### Step 1.5: Confirm and Supplement
 
@@ -202,62 +115,11 @@ After the discussion:
 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"
 
-**Signs that brainstorming is complete:**
-- All refactoring goals have concrete target state descriptions
-- Scope boundaries are clearly defined (in/out)
-- Behavior preservation contracts are identified
-- Risk areas are acknowledged and mitigation is discussed
-- The user has confirmed the summary is accurate
-
-**Signs that more questions are needed:**
-- User's answers contain vague terms ("clean it up", "make it better", "fix the structure")
-- Scope is undefined ("refactor everything" without specifics)
-- No awareness of test coverage for the target area
-- Risk areas are handwaved ("it should be fine")
-- User says "I'm not sure" — help them think through it with concrete options
+Read `${SKILL_DIR}/references/brainstorm-guide.md` §Completion Signs for the full checklist of when brainstorming is complete vs when more questions are needed.
 
 ### Step 1.6: Requirements Summary
 
-Once brainstorming is complete, produce a structured goals summary:
-
-```markdown
-## Refactoring Goals Summary
-
-### Target: [Module/area name]
-
-### Refactoring Type: [Incremental / Comprehensive / Targeted]
-
-### Refactoring Objectives
-- [Bullet list of what structural changes are needed and why]
-
-### Current Problems
-- [What's wrong with the current structure — with specific code references]
-
-### Target State
-- [What the code should look like after refactoring]
-
-### Scope
-- **In scope**: [files, modules, directories]
-- **Out of scope**: [explicitly excluded areas]
-
-### Behavior Preservation Contracts
-- [What behavior must remain unchanged]
-- [Key APIs/interfaces that must be preserved]
-- [Existing test coverage status]
-
-### Risk Assessment
-- [Risk]: [Mitigation strategy]
-
-### Reference Materials Reviewed
-- [List of code paths, documents, .prizmkit/prizm-docs/ files that were read]
-
-### Constraints
-- [Timeline, coordination, deployment concerns]
-
-### Confirmed by user: ✓
-```
-
-Present this summary to the user and get explicit confirmation before proceeding.
+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.
 
 **CHECKPOINT CP-RW-0**: Refactoring goals fully clarified and confirmed by user.
 
@@ -275,28 +137,6 @@ After confirming refactoring goals, assess whether this refactor needs the full
 - Existing tests fully cover the affected code paths
 - No risk of behavior change
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
-
-```
-AskUserQuestion:
-  question: "This refactoring appears straightforward. How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Refactor now (fast path)"
-      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to refactor list (pipeline)"
-      description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
-```
-
-- **Refactor now** → Fast Path Workflow:
-  1. Invoke `/prizmkit-plan` with the refactoring goals → generates `spec.md` + `plan.md`
-  2. Invoke `/prizmkit-implement` to execute the plan (behavior preservation verified by tests)
-  3. After implementation, run `/prizmkit-code-review` for quality check
-  4. Commit via `/prizmkit-committer` with `refactor(<scope>):` prefix
-  5. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
-  6. **End workflow** — skip Phase 2/3/4
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline)
-
 **Complex refactor → Planning Path** (ANY is true):
 - Cross-module impact (>2 modules affected)
 - Public API or interface changes required
@@ -305,21 +145,21 @@ AskUserQuestion:
 - Insufficient test coverage in target area (risk of hidden behavior changes)
 - Requires coordination with other ongoing work
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Tailor the question text to the assessment ("This refactoring appears straightforward…" for simple, "This refactoring is complex and will benefit from structured planning…" for complex), but the two options are always the same:
 
 ```
 AskUserQuestion:
-  question: "This refactoring is complex and will benefit from structured planning. How would you like to proceed?"
+  question: <tailored to simple vs complex assessment>
   header: "Approach"
   options:
-    - label: "Plan and refactor now"
-      description: "Create a plan and refactor in this session using /prizmkit-plan + /prizmkit-implement"
+    - label: "Refactor now (fast path)"
+      description: "Plan and refactor directly in this session using /prizmkit-plan + /prizmkit-implement"
     - label: "Add to refactor list (pipeline)"
       description: "Generate .prizmkit/plans/refactor-list.json via refactor-planner, then launch pipeline for autonomous execution"
 ```
 
-- **Plan and refactor now** → Invoke `/prizmkit-plan` with goals → `/prizmkit-implement` → `/prizmkit-code-review` → `/prizmkit-committer` → `/prizmkit-retrospective`. **End workflow** — skip Phase 2/3/4.
-- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline)
+- **Refactor now** → Fast Path: `/prizmkit-plan` (goals → `spec.md` + `plan.md`) → `/prizmkit-implement` (behavior preservation verified by tests) → `/prizmkit-code-review` → `/prizmkit-committer` (`refactor(<scope>):` prefix) → `/prizmkit-retrospective` (sync `.prizmkit/prizm-docs/`). **End workflow** — skip Phase 2/3/4.
+- **Add to refactor list** → Continue to Phase 2 (Plan via pipeline).
 
 **NEVER proceed without explicit user confirmation via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 
@@ -350,7 +190,7 @@ AskUserQuestion:
 
 **CHECKPOINT CP-RW-1**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
-**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
+**If `.prizmkit/plans/refactor-list.json` already exists or user says `--from <file>`**: skip ahead per the [Resume table](#resume--interruption-recovery).
 
 ---
 

package/bundled/skills-windows/refactor-workflow/references/brainstorm-guide.md

@@ -0,0 +1,116 @@
+# Brainstorm Guide — Refactoring Context
+
+Procedural details for deep code analysis and discussion during refactor-workflow Phase 1.
+
+## Step 1.3: Parallel Deep Reading
+
+**Goal**: Build comprehensive understanding of the target code and context before discussing plans. Spawn multiple agents in parallel to read all relevant materials simultaneously.
+
+**Parallel reading tasks** (launch concurrently):
+
+| Agent | What to read | Purpose |
+|-------|-------------|---------|
+| Agent A | User-provided code paths — read full source files | Understand current structure, interfaces, dependencies |
+| Agent B | User-provided documents — design docs, proposals, wiki pages | Understand intended direction and constraints |
+| Agent C | `.prizmkit/prizm-docs/` for affected modules — L1/L2 docs, TRAPS, RULES | Understand existing architecture knowledge and known pitfalls |
+| Agent D | Test files for the target area — find and read existing tests | Understand current test coverage and behavior contracts |
+
+**Also gather** (can be included in any agent's task):
+- `.prizmkit/config.json` → tech stack preferences
+- Directory structure of the target area
+- Dependency relationships (imports/exports between target and other modules)
+
+**After all agents complete**: Synthesize findings into a coherent understanding before proceeding to discussion.
+
+## Step 1.4: Discuss Refactoring Plan
+
+**Now** — with deep knowledge of the actual code and documents — discuss the refactoring plan with the user. This discussion is grounded in real code, not abstract questions.
+
+Present what you learned from the parallel reading:
+- Current code structure and its problems (with specific file/function references)
+- Existing test coverage status (which areas are safe, which are risky)
+- Known TRAPS and pitfalls from `.prizmkit/prizm-docs/`
+- Dependencies and potential impact on other modules
+
+Then ask targeted questions based on what you read. **Adapt question depth to the refactoring complexity** — a simple extract-method refactor needs fewer questions than a full module decomposition.
+
+### Code Structure
+- "I see the current structure does X — is the target state Y, or something different?"
+- What's the target state? What should the code look like after refactoring?
+- Are there specific code smells you've noticed? (duplication, deep nesting, god classes, tight coupling)
+
+### Scope
+- Based on the code I read, these modules are affected: [list]. Anything else in/out of scope?
+- For incremental refactoring: what's the order of priority?
+
+### Behavior Preservation
+- "These public APIs/interfaces exist: [list]. Which must remain unchanged?"
+- "I found these tests: [list]. Are they passing currently?"
+- Any undocumented behavior that callers depend on?
+
+### Risk Assessment
+- "I found these TRAPS in .prizmkit/prizm-docs/: [list]. Any other known gotchas?"
+- Does this code have external consumers (other teams, published APIs)?
+- Any concurrent development happening in the target area?
+
+### Constraints
+- Timeline or urgency? (affects whether to do incremental vs comprehensive)
+- Team coordination needed? (other developers working in the same area)
+- Deployment concerns? (feature flags, backward compatibility, migration)
+
+## Completion Signs
+
+**Signs that brainstorming is complete:**
+- All refactoring goals have concrete target state descriptions
+- Scope boundaries are clearly defined (in/out)
+- Behavior preservation contracts are identified
+- Risk areas are acknowledged and mitigation is discussed
+- The user has confirmed the summary is accurate
+
+**Signs that more questions are needed:**
+- User's answers contain vague terms ("clean it up", "make it better", "fix the structure")
+- Scope is undefined ("refactor everything" without specifics)
+- No awareness of test coverage for the target area
+- Risk areas are handwaved ("it should be fine")
+- User says "I'm not sure" — help them think through it with concrete options
+
+## Refactoring Goals Summary Template
+
+Once brainstorming is complete, produce a structured goals summary using this template:
+
+```markdown
+## Refactoring Goals Summary
+
+### Target: [Module/area name]
+
+### Refactoring Type: [Incremental / Comprehensive / Targeted]
+
+### Refactoring Objectives
+- [Bullet list of what structural changes are needed and why]
+
+### Current Problems
+- [What's wrong with the current structure — with specific code references]
+
+### Target State
+- [What the code should look like after refactoring]
+
+### Scope
+- **In scope**: [files, modules, directories]
+- **Out of scope**: [explicitly excluded areas]
+
+### Behavior Preservation Contracts
+- [What behavior must remain unchanged]
+- [Key APIs/interfaces that must be preserved]
+- [Existing test coverage status]
+
+### Risk Assessment
+- [Risk]: [Mitigation strategy]
+
+### Reference Materials Reviewed
+- [List of code paths, documents, .prizmkit/prizm-docs/ files that were read]
+
+### Constraints
+- [Timeline, coordination, deployment concerns]
+
+### Confirmed by user: ✓
+```

package/package.json

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