prizmkit 1.1.107 → 1.1.108

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

@@ -1,75 +1,88 @@
 ---
 name: "feature-workflow"
-description: "One-stop entry point for feature development. Brainstorms requirements with the user until fully clarified, then orchestrates feature-planner → feature-pipeline-launcher → execution. Handles multi-feature batch development from a single request. Use this skill whenever the user wants to build an app, develop multiple features at once, or go from idea to running code in one step. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete', 'batch implement'."
+description: "Triage-based feature workflow. Clarifies requirements, then lets the user choose Fast Path for simple current-session/current-workspace implementation or Pipeline Path for complex/batch features via feature-planner → feature-pipeline-launcher. Use when the user wants to develop features from idea to running code with the right execution path for the task difficulty. Trigger on: 'build an app', 'develop features', 'implement all features', 'one-stop development', 'batch implement', 'build a new application', 'build a system', 'one-click complete'."
 ---
 
 # Feature Workflow
 
-One-stop entry point for feature development. Covers the complete journey from a vague idea to running code: deep requirement brainstorming → structured planning → autonomous pipeline execution.
+Triage-based entry point for feature development. The workflow clarifies requirements, assesses task difficulty, asks the user to choose an approach, then follows one of two paths:
+
+- **Fast Path** — simple feature work is implemented directly in the **current session** and **current workspace** with the normal PrizmKit lifecycle commands.
+- **Pipeline Path** — complex or batch features are planned with `feature-planner`, launched with `feature-pipeline-launcher`, then monitored.
+
+This skill keeps Fast Path and Pipeline Path separate. Pipeline monitoring only happens after the user selects Pipeline Path and the launcher starts execution.
 
 ## When to Use
 
 User says:
 - "Build a new application", "Build XXX system", "Create a project"
+- "Implement this feature now", "Add this simple feature", "Build one small workflow"
 - "One-click complete these features", "Batch implement these requirements"
-- "Build a task management App from scratch"
 - "Help me implement user login, registration, and avatar upload features"
-- After receiving a batch of related feature requests
+- After receiving either one scoped feature request or a batch of related feature requests
 
 **Do NOT use this skill when:**
-- User only wants to plan features (use `feature-planner` directly)
-- User only wants to launch pipeline for existing .prizmkit/plans/feature-list.json (use `feature-pipeline-launcher`)
-- User wants to fix bugs (use `bug-planner` + `bugfix-pipeline-launcher`)
-- User wants to refactor code (use `refactor-workflow`)
+- User only wants to plan features without execution → use `feature-planner` directly
+- User only wants to launch an existing `.prizmkit/plans/feature-list.json` → use `feature-pipeline-launcher`
+- User wants to fix bugs → use `bug-fix-workflow` or `bug-planner` + `bugfix-pipeline-launcher`
+- User wants to refactor code → use `refactor-workflow`
 
 ---
 
 ## Overview
 
-Given an idea or requirements, the workflow runs four phases:
+The shared contract is:
+
+1. **Brainstorm** — collect reference materials, deep read relevant code/docs, and clarify requirements.
+2. **Assess difficulty** — decide whether the request is simple enough for Fast Path or should use Pipeline Path.
+3. **AskUserQuestion approach selection** — present selectable options; never silently choose the path.
+4. **Execute selected path**:
+   - **Fast Path**: `/prizmkit-plan` → `/prizmkit-implement` → `/prizmkit-code-review` → `/prizmkit-retrospective` → `/prizmkit-committer` in the current workspace.
+   - **Pipeline Path**: `feature-planner` → `feature-pipeline-launcher` → monitoring.
 
-1. **Brainstorm** — collect reference materials, parallel deep read code & docs, discuss requirements grounded in real context → fully clarified requirements
-2. **Plan** — call `feature-planner` with clarified requirements → `.prizmkit/plans/feature-list.json` with N features
-3. **Launch** — call `feature-pipeline-launcher` → pipeline started (execution mode chosen by user via launcher)
-4. **Monitor** — track progress → status updates, completion report
+### Terminology
 
-The value: the user starts from a rough idea, the skill brainstorms to fill the gaps, and planning + execution happen automatically — no need to manually invoke each planner/launcher and poll for progress.
+| Term | Meaning |
+|------|---------|
+| **Fast Path** | Current-session/current-workspace feature implementation for simple, scoped work. It does not create or consume `.prizmkit/plans/feature-list.json` and does not start the dev-pipeline. |
+| **Pipeline Path** | Complex or batch feature execution. Planner handoff goes to `feature-planner`; launcher handoff goes to `feature-pipeline-launcher`; monitoring follows only after launch. |
+| **Current session** | The interactive AI CLI session that is already talking with the user. |
+| **Current workspace** | The current git checkout and working tree, not a background pipeline worktree/session. |
+| **Monitoring** | Status/log follow-up for a launched pipeline; it is not part of the Fast Path. |
 
-### Branch Management
+### Workspace and Branch Model
 
-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
+- **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**: `feature-pipeline-launcher` and the dev-pipeline manage per-feature branches/worktrees. This workflow does not create a top-level branch before handing off to the launcher.
 
 ---
 
 ## Input Modes
 
-**Mode A: From natural language requirements** (default)
+**Mode A: Natural language requirements** (default)
 
-Natural language description of the project or features. Can be:
+Natural language description of the project or feature(s). Can be:
+- A single simple feature: "Add CSV export to the reports page"
 - A project vision: "Build a task management App with user login, task CRUD, and task categories"
-- A batch of features: "Implement user registration, login, and password recovery features"
+- A batch of features: "Implement user registration, login, and password recovery"
 - An incremental request: "Add user avatar upload and nickname modification to the existing system"
 
-Flow: brainstorm → feature-planner → feature-pipeline-launcher → monitor
+Flow: brainstorm → complexity assessment → AskUserQuestion → Fast Path or Pipeline Path.
 
-**Mode B: From existing .prizmkit/plans/feature-list.json**
+**Mode B: Existing `.prizmkit/plans/feature-list.json`**
 
-When user says "run pipeline from existing file" or .prizmkit/plans/feature-list.json already exists:
-- Skip brainstorm and `feature-planner` (file already exists)
+When the user says "run pipeline from existing file" or `.prizmkit/plans/feature-list.json` already exists and should be executed:
+- Skip brainstorm and `feature-planner`
 - Invoke `feature-pipeline-launcher` directly
 - Monitor and report progress
 
-**Mode C: Incremental (add to existing project)**
+**Mode C: Incremental feature request**
 
 When user says "add features to existing project" or the project already has features:
-- Brainstorm new feature requirements with the user
-- Invoke `feature-planner` in incremental mode (reads existing .prizmkit/plans/feature-list.json)
-- Append new features to existing list
-- Invoke `feature-pipeline-launcher`
-- Monitor and report progress
+- Brainstorm only the new feature requirements
+- Assess whether the new scope is simple enough for Fast Path
+- For simple work: use Fast Path in the current workspace
+- For complex or batch work: invoke `feature-planner` in incremental mode, then `feature-pipeline-launcher`
 
 ---
 
@@ -77,7 +90,7 @@ When user says "add features to existing project" or the project already has fea
 
 **Goal**: Through interactive Q&A and deep context reading, transform the user's rough idea into fully clarified, implementation-ready requirements. This phase is the foundation for high-quality code generation — vague requirements produce vague code.
 
-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. The framework strives for perfect code generation, which requires perfect understanding of requirements.
+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. The framework strives for high-quality code generation, which requires strong requirement understanding.
 
 ### Step 1.1: Understand the User's Vision
 
@@ -133,66 +146,69 @@ Once brainstorming is complete, produce a structured requirements summary. Read
 
 ### Step 1.7: Complexity Assessment & Approach Selection
 
-After confirming requirements, assess whether this feature needs the full pipeline or can be done directly in the current session.
+After confirming requirements, assess whether this feature needs the Pipeline Path or can be done directly in the current session/current workspace.
 
-**Simple feature** (Fast Path candidate — ALL must be true):
+**Simple feature work → Fast Path candidate** (ALL must be true):
 - Single module, no cross-module architectural impact
 - ≤2 new files to create
 - No new external dependencies or infrastructure changes
-- Straightforward implementation (CRUD, utility, simple UI component)
+- Straightforward implementation (CRUD endpoint, utility, simple UI component, small workflow)
 - Clear acceptance criteria with existing patterns to follow
 - No dependency on other unbuilt features
 
-**Complex feature** (Planning Path — ANY is true):
+**Complex or batch features → Pipeline Path candidate** (ANY is true):
+- Multiple features or batch implementation request
 - Cross-module impact (>2 modules affected)
 - New infrastructure, dependencies, or architectural patterns required
 - Multiple interrelated features with dependency ordering
 - Data model or API design decisions needed
 - Requires integration with external services
 
-User choice is required (mandatory) — use `AskUserQuestion` to present interactive selectable options. Adjust the question framing to the assessment: for a simple feature, "This feature appears straightforward."; for a complex feature, "This feature is complex and will benefit from structured planning."
+**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options. Adjust the question framing to the assessment: for a simple feature, "This feature appears straightforward and can use the current-session Fast Path." For a complex or batch request, "This feature set is complex or batch-oriented and should use the Pipeline Path."
 
 ```
 AskUserQuestion:
-  question: "How would you like to proceed?"   # prefix with the framing note above
+  question: "How would you like to proceed?"
   header: "Approach"
   options:
-    - label: "Implement now (fast path)"
-      description: "Plan and implement directly in this session using /prizmkit-plan + /prizmkit-implement"
-    - label: "Add to feature list (pipeline)"
-      description: "Generate .prizmkit/plans/feature-list.json via feature-planner, then launch pipeline for autonomous execution"
+    - label: "Implement now (Fast Path — current session/current workspace)"
+      description: "Run /prizmkit-plan → /prizmkit-implement → /prizmkit-code-review → /prizmkit-retrospective → /prizmkit-committer directly in this workspace"
+    - label: "Use Pipeline Path (feature-planner → feature-pipeline-launcher)"
+      description: "Generate .prizmkit/plans/feature-list.json with feature-planner, then launch autonomous execution with feature-pipeline-launcher"
 ```
 
-- **Implement now** → Fast Path Workflow:
+- **Implement now (Fast Path)**:
   1. Invoke `/prizmkit-plan` with the requirements summary → generates `spec.md` + `plan.md`
-  2. Invoke `/prizmkit-implement` to execute the plan
-  3. After implementation, run `/prizmkit-code-review` for quality check
-  4. Commit via `/prizmkit-committer` with `feat(<scope>):` prefix
-  5. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
-  6. End workflow — skip Phase 2/3/4
-- **Add to feature list** → Continue to Phase 2 (Plan via pipeline)
+  2. Invoke `/prizmkit-implement` to execute the plan in the current workspace
+  3. Run `/prizmkit-code-review` for quality check
+  4. Run `/prizmkit-retrospective` to sync `.prizmkit/prizm-docs/`
+  5. Commit via `/prizmkit-committer` with `feat(<scope>):` prefix
+  6. End workflow — do not call `feature-planner`, do not call `feature-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-FW-0.5**: Approach selected by user (fast path or pipeline).
+**CHECKPOINT CP-FW-0.5**: Approach selected by user (Fast Path or Pipeline Path).
 
 ---
 
-## Phase 2: Plan
+## Phase 2: Plan — Pipeline Path Only
+
+**Goal**: Generate structured `.prizmkit/plans/feature-list.json` from the clarified requirements.
 
-**Goal**: Generate structured .prizmkit/plans/feature-list.json from the clarified requirements.
+Run this phase only when the user selected Pipeline Path or provided a batch/complex request that they chose to send through the pipeline.
 
 **STEPS**:
 
-1. **Invoke `feature-planner` skill** with the full requirements summary from Phase 1:
+1. **Planner handoff — invoke `feature-planner`** with the full requirements summary from Phase 1:
    - Pass the structured requirements summary as input — NOT the raw user conversation
    - For new projects: standard planning mode
    - For existing projects with `--incremental`: incremental planning mode
    - **Input**: Markdown requirements summary (feature descriptions, goals, constraints)
    - **Output**: `.prizmkit/plans/feature-list.json` (schema: `dev-pipeline-feature-list-v1`) containing `project_name`, `features[]` with id (F-NNN), title, description, priority, dependencies, acceptance_criteria, status
 
-2. **Interactive planning** (if feature-planner requires clarification):
-   - Because Phase 1 was thorough, feature-planner should need minimal clarification
+2. **Interactive planning** (if `feature-planner` requires clarification):
+   - Because Phase 1 was thorough, `feature-planner` should need minimal clarification
    - If questions arise, answer from the Phase 1 context or pass through to user
 
 3. **Validate output**:
@@ -201,19 +217,19 @@ Never proceed without explicit user confirmation via `AskUserQuestion`. Do NOT r
 
 **CHECKPOINT CP-FW-1**: `.prizmkit/plans/feature-list.json` generated and validated.
 
-**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely.
+**If user says `--from <file>`**: Skip Phase 1 and Phase 2 entirely and go to Phase 3.
 
 ---
 
-## Phase 3: Launch
+## Phase 3: Launch — Pipeline Path Only
 
-**Goal**: Start the development pipeline.
+**Goal**: Start the development pipeline after planner handoff has produced a validated feature list.
 
 **STEPS**:
 
 1. **Show feature summary** before launching:
    ```
-   Ready to launch pipeline with N features:
+   Ready to launch Pipeline Path with N features:
      F-001: User authentication (high complexity)
      F-002: Task CRUD (medium complexity)
      F-003: Task categories (low complexity)
@@ -221,9 +237,9 @@ Never proceed without explicit user confirmation via `AskUserQuestion`. Do NOT r
    Proceed? (Y/n)
    ```
 
-2. **Invoke `feature-pipeline-launcher` skill**:
+2. **Launcher handoff — invoke `feature-pipeline-launcher`**:
    - **Input**: Path to validated `.prizmkit/plans/feature-list.json`
-   - The launcher handles all prerequisites checks
+   - The launcher handles all prerequisite checks
    - The launcher presents execution mode choices to the user (foreground/background/manual)
    - The launcher asks whether to enable Critic Agent (adversarial review) — passes `--critic` flag if chosen
    - Do NOT duplicate execution mode or critic selection here — let the launcher handle it
@@ -237,9 +253,9 @@ Never proceed without explicit user confirmation via `AskUserQuestion`. Do NOT r
 
 ---
 
-## Phase 4: Monitor
+## Phase 4: Monitor — Pipeline Path Only
 
-**Goal**: Track pipeline progress and report to user.
+**Goal**: Track pipeline progress and report to user. Monitoring applies only after `feature-pipeline-launcher` has started a pipeline.
 
 **STEPS**:
 
@@ -282,13 +298,14 @@ Never proceed without explicit user confirmation via `AskUserQuestion`. Do NOT r
 The workflow supports resuming by detecting existing state:
 
 | State Found | Resume From |
-|-------------|------------|
-| No `.prizmkit/plans/feature-list.json` | Phase 1: Brainstorm |
+|-------------|-------------|
+| Fast Path `spec.md` + `plan.md` exist, code not committed | Resume `/prizmkit-implement` / review / retrospective / commit based on current state |
+| No `.prizmkit/plans/feature-list.json` and no Fast Path artifacts | Phase 1: Brainstorm |
 | `.prizmkit/plans/feature-list.json` exists, no pipeline state | Phase 3: Launch |
 | `.prizmkit/plans/feature-list.json` + pipeline state exists | Phase 4: Monitor (check status) |
 | All features completed | Report completion, suggest next steps |
 
-**Resume**: If `.prizmkit/plans/feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume pipeline or re-plan?"
+**Resume**: If `.prizmkit/plans/feature-list.json` exists, ask user: "Existing feature plan found with N features. Resume Pipeline Path or re-plan?" If Fast Path artifacts exist, ask whether to continue the current-workspace implementation or discard/re-plan.
 
 ---
 
@@ -311,6 +328,7 @@ While the pipeline runs, the user can continue the conversation:
 |-------|--------|
 | User's idea is too vague to brainstorm | Ask for more context: "Can you describe the main problem this solves?" |
 | Brainstorming stalls | Offer concrete options: "Would you prefer A or B?" |
+| Fast Path starts looking complex | Pause and ask whether to switch to Pipeline Path (`feature-planner` → `feature-pipeline-launcher`) |
 | `feature-planner` cannot parse requirements | Refine the requirements summary and retry |
 | `.prizmkit/plans/feature-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 feature run .prizmkit/plans/feature-list.json` or `python3 ./.prizmkit/dev-pipeline/cli.py daemon feature start .prizmkit/plans/feature-list.json` |
@@ -319,15 +337,18 @@ While the pipeline runs, the user can continue the conversation:
 
 ---
 
-## Relationship to Other Skills
+## HANDOFF
 
-| Skill | Relationship |
-|-------|-------------|
-| `feature-planner` | **Called by Phase 2** — generates .prizmkit/plans/feature-list.json from clarified requirements |
-| `feature-pipeline-launcher` | **Called by Phase 3** — 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 |
+| From | To | Condition |
+|------|----|-----------|
+| **this skill** | `/prizmkit-plan` | User selects Fast Path for simple feature work in the current workspace |
+| **this skill** | `/prizmkit-implement` | Fast Path plan is ready for current-session implementation |
+| **this skill** | `/prizmkit-code-review` | Fast Path implementation is complete and needs quality review |
+| **this skill** | `/prizmkit-retrospective` | Fast Path feature changes need `.prizmkit/prizm-docs/` sync before commit |
+| **this skill** | `/prizmkit-committer` | Fast Path feature changes are reviewed and docs are synced |
+| **this skill** | `feature-planner` | User selects Pipeline Path for complex or batch features |
+| `feature-planner` | `feature-pipeline-launcher` | Planner handoff produced validated `.prizmkit/plans/feature-list.json` |
+| `feature-pipeline-launcher` | **this skill** | Launcher handoff completed and monitoring/status follow-up is needed |
 
 ---
 
@@ -343,9 +364,7 @@ All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibil
 
 ## Output
 
-- Structured requirements summary (Phase 1 artifact)
-- `.prizmkit/plans/feature-list.json` (Phase 2 artifact)
-- Pipeline execution (Phase 3)
-- Progress updates (Phase 4)
-- Multiple git commits with `feat(<scope>):` prefix
-- Updated `.prizmkit/prizm-docs/` (via prizmkit-retrospective per feature)
+Output depends on the selected path:
+
+- **Fast Path**: `spec.md` + `plan.md`, current-workspace code changes, `/prizmkit-code-review` result, updated `.prizmkit/prizm-docs/`, and one `feat(<scope>):` commit from `/prizmkit-committer`.
+- **Pipeline Path**: structured requirements summary, `.prizmkit/plans/feature-list.json`, pipeline execution via `feature-pipeline-launcher`, monitoring updates, and per-feature commits managed by the dev-pipeline.

package/bundled/skills/{prizm-kit → prizmkit}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: "prizm-kit"
+name: "prizmkit"
 description: "Full-lifecycle dev toolkit index. Routes to the right PrizmKit skill for spec-driven development, Prizm docs, code quality, deployment, and knowledge management. Use when the user asks 'which command?', 'help', 'how do I start a feature', 'get started', 'what tools', 'dev workflow', 'lifecycle', or '/prizmkit'. Use this as the entry point for the full PrizmKit development lifecycle. (project)"
 ---
 

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

@@ -115,7 +115,7 @@ When Python is unavailable, apply these rules exactly — they match the script'
 
 ### Step 1: Spawn Reviewer Agent
 
-Include the dev rules read in Phase 0 step 4 and the workspace diff/status captured in Phase 0 step 5 in the Reviewer prompt. In Claude Code, spawn the dedicated PrizmKit Reviewer with `subagent_type: prizm-dev-team-reviewer` and `run_in_background=false`. Do not route the PrizmKit reviewer flow through `Explore` or a generic code-explorer agent. If the current platform has no dedicated Reviewer agent, perform the review pass in the Main Agent without editing files during that pass. Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
+Include the dev rules read in Phase 0 step 4 and the workspace diff/status captured in Phase 0 step 5 in the Reviewer prompt. In Claude Code, spawn the dedicated PrizmKit Reviewer with `subagent_type: prizm-dev-team-reviewer`, `run_in_background=false`, and default/no worktree isolation. Do not request worktree isolation; this prevents AI tool-created `.claude/worktrees/...` subagent worktrees. PrizmKit pipeline-managed linked git worktrees under `.prizmkit/state/worktrees/...` are separate and controlled by `USE_WORKTREE`. Do not route the PrizmKit reviewer flow through `Explore` or a generic code-explorer agent. If the current platform has no dedicated Reviewer agent, perform the review pass in the Main Agent without editing files during that pass. Read `${SKILL_DIR}/references/reviewer-agent-prompt.md` for the full prompt template — fill `{goals}`, `{plan decisions}`, `{scoped test report}`, `{workspace context}`, `{dev rules}`, `{round N}`, and `{round_context}` before spawning.
 
 Round context varies by round:
 - Round 1: "This is the first review. Examine all changes comprehensively."

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

@@ -51,9 +51,22 @@ When the user provides detailed specifications, rules, or implementation require
 1. **Verbatim preservation**: The user's exact wording MUST be preserved in `description` and `acceptance_criteria` fields. Do NOT paraphrase, summarize, abstract, or simplify.
 2. **No autonomous simplification**: A 200-word user specification must NOT become a 30-word description. Match the detail level of the user's input.
 3. **Clarify, don't assume**: If any user-provided rule is ambiguous or potentially conflicts with another, ASK the user to clarify. No limit on clarification rounds. Do NOT proceed with unresolved ambiguities.
-4. **Populate `user_context`**: ALL user-provided materials (supplementary content, rules, file path references) MUST be written into the `user_context` array of each refactor item in the generated `.prizmkit/plans/refactor-list.json`. Format:
-   - Supplementary content or rules → store as-is (verbatim text)
-   - File references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
+4. **Task-scoped `user_context`**: In single-refactor planning, write the relevant user-provided materials into that refactor item's `user_context`. In multi-refactor planning, multi-refactor `user_context` must contain only the user text, file references, goals, and constraints relevant to that specific refactor item.
+   - Preserve the matching user wording verbatim, but scope it to the item it belongs to.
+   - Do NOT copy the full multi-refactor request into every item.
+   - Ensure there are no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials in a refactor item's `user_context`.
+   - Shared global context may be copied to every item only when it is explicitly applicable to all generated items.
+   - If a goal, constraint, target file, or architecture note applies to only one refactor item, attach it only to that matching item.
+   - If applicability is unclear, ask the user to map the material to the correct refactor item before generating the final list.
+5. **`user_context` format**:
+   - Refactor-specific supplementary content, goals, or constraints → store as-is (verbatim text) on the matching refactor item only
+   - Refactor-specific file references → store as path string, e.g. `src/auth/login.ts:42-78` or `src/utils/validate.ts — focus on validateEmail function`
+   - Truly shared global constraints → repeat only when they apply to every generated refactor item
+
+**Multi-refactor isolation example:**
+- User request includes: `Refactor A: extract auth validation into middleware`, `Refactor B: split dashboard chart utilities`, and `Shared: preserve all public APIs`.
+- The auth middleware refactor `user_context` includes `Refactor A: extract auth validation into middleware` and the shared API constraint; it MUST NOT include `Refactor B: split dashboard chart utilities`.
+- The chart utilities refactor `user_context` includes `Refactor B: split dashboard chart utilities` and the shared API constraint; it MUST NOT include `Refactor A: extract auth validation into middleware`.
 
 ## When to Use
 - "Plan refactoring", "Scope a restructuring"
@@ -252,10 +265,13 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
    ```
    The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes.
 3. If validation fails -> fix the draft and retry (max 3 attempts)
-4. If validation passes -> present final summary
+4. If validation passes -> run the mandatory Post-Generation Plan Review Gate (see §Post-Generation Plan Review Gate below); apply accepted fixes to the draft/source plan, regenerate, and revalidate until pass
+5. If review and validation pass -> present final summary
 
 **CHECKPOINT CP-RP-6**: `.prizmkit/plans/refactor-list.json` generated and validated.
 
+**CHECKPOINT CP-RP-7**: `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated.
+
 ## Checkpoints (Mandatory Gates)
 
 | Checkpoint | Artifact/State | Criteria | Phase |
@@ -267,6 +283,32 @@ See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review chec
 | **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
 | **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
 | **CP-RP-6** | Output Valid | `.prizmkit/plans/refactor-list.json` passes validation script | 7 |
+| **CP-RP-7** | Plan Review Passed | `/prizmkit-code-review` reviewed only newly added/changed refactor entries; accepted fixes were regenerated and revalidated | 7 |
+
+## Post-Generation Plan Review Gate
+
+User requirement preserved verbatim: `每次完成任务规划的时候，应该调用/prizmkit-code-review 对新增的计划内容进行review，确保生成新增的计划的正确行和完整性。`
+
+Run this gate **after** `.prizmkit/plans/refactor-list.json` passes the validation/generate script and **before** the final handoff summary recommends `refactor-pipeline-launcher`. This gate applies to full workflow, Mode B from analysis, and fast-path refactor planning.
+
+1. **Identify review scope**: compare the final validated refactor list against the pre-session list when one existed. Review only newly added or changed refactor entries. Do not re-review unchanged historical entries except when needed to verify dependency references or behavior-preservation interactions.
+2. **Invoke `/prizmkit-code-review` as a planning-quality gate** with an explicit prompt that this is a refactor-plan-entry review, not an implementation review. The review must check:
+   - schema correctness and compatibility with `dev-pipeline-refactor-list-v1`
+   - dependency/DAG soundness, including safe behavior-preserving order
+   - description completeness and headless execution readiness
+   - acceptance criteria specificity and measurable behavior-preservation verification
+   - `behavior_preservation` strategy quality and target scope consistency
+   - preservation of user-provided wording in `description`, `acceptance_criteria`, and `user_context`
+   - task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, or supplementary materials, and shared context appears on multiple items only when explicitly global
+   - priority/complexity calibration: every reviewed refactor has a short priority rationale and complexity rationale, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
+3. **Keep the review planning-only**: do NOT start `refactor-pipeline-launcher`, do NOT run the refactor pipeline, do NOT run tests/builds/installs, and do NOT implement source-code refactors.
+4. **Apply accepted review fixes through the draft/source plan**: when a finding is accepted, update `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft representation first, then regenerate the final file with:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
+   ```
+   Do not hand-patch the final JSON as the source of truth; map final-output findings back to draft entries before regeneration.
+5. **Revalidate after every accepted fix batch**: the generate script must pass again before the planner can proceed. If validation fails, fix the draft and rerun until pass.
+6. **Report the gate outcome** in the final summary: include `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result.
 
 ## Output Rules
 
@@ -307,6 +349,44 @@ Browser verification is a feature-pipeline capability only. Refactors use `behav
 
 ---
 
+## Priority and Complexity Calibration (Mandatory)
+
+Refactor planning must not collapse into uniform `Priority: high` and `Complexity: high`. Refactoring work can be low or medium priority even when it touches several files. Do not use high/high merely because code needs cleanup, the user cares about maintainability, the target is framework code, or multiple files are involved.
+
+### Priority Rubric
+
+| Priority | Use When | Do NOT Use Merely Because |
+|----------|----------|---------------------------|
+| `critical` | Behavior-preserving restructure is required to unblock an imminent release, security/compliance fix, or safe migration with no acceptable workaround. | The refactor is large or architectural in wording. |
+| `high` | Current structure blocks core feature delivery, creates ongoing correctness/security/data-risk, prevents supported runtime upgrades, or many downstream tasks cannot proceed. | The code is messy, multi-file, or important to the user. |
+| `medium` | Refactor improves maintainability, testability, or dependency boundaries for planned work but does not block current operation. | Medium is the normal default for useful refactors. |
+| `low` | Local cleanup, rename, simplification, documentation-oriented organization, or isolated code-health improvement with low behavior risk. | Small scope alone does not make it low if it blocks a high-impact outcome. |
+
+### Complexity Rationale Rules
+
+Assign complexity from concrete refactor scope indicators and include a short rationale:
+- file count and expected import/update sites
+- cross-module scope and dependency depth
+- public API/interface or import-path change
+- existing test coverage and behavior-preservation strategy
+- behavior-preservation risk and snapshot/manual verification needs
+- migration impact, rollout phases, or compatibility shims
+
+Use `low` for 1-3 files in one module with good tests and no public API/import-path change. Use `medium` for 4-8 files or two modules with bounded public impact and clear behavior-preservation tests. Use `high` only for 9+ files, 3+ modules, public API/import-path migration, weak test coverage, manual preservation risk, or cross-module migration impact.
+
+### Required Planning Review Summary
+
+Before writing `.prizmkit/plans/refactor-list.json`, show a calibration table with rationale columns:
+
+```
+ID    | Title                       | Priority | Priority Rationale              | Complexity | Complexity Rationale
+R-001 | Break auth/user cycle        | high     | Blocks feature work; core risk  | high       | 3 modules + public imports + weak tests
+R-002 | Extract chart format helpers | medium   | Maintainability for planned UI  | medium     | 5 files; bounded helper API; tests exist
+R-003 | Rename local temp variable   | low      | Local readability only          | low        | One file; no interface or behavior change
+```
+
+Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high-priority and high-complexity criteria and the rationale names those criteria.
+
 ## Refactoring-Specific Features
 
 ### Behavior Preservation Check
@@ -319,7 +399,7 @@ Auto-detect inter-item dependencies and enforce safe ordering. Read `${SKILL_DIR
 
 ### Complexity Assessment
 
-Assess each item's complexity based on file count, cross-module scope, test coverage, and pattern familiarity. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules.
+Assess each item's complexity from concrete indicators: file count, cross-module scope, public API/import-path changes, dependency depth, test coverage, behavior-preservation risk, and migration impact. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules. Every confirmation/review summary must include a short complexity rationale.
 
 ## Next-Step Execution Policy (after planning)
 
@@ -364,9 +444,10 @@ Prevent accidental session exit without deliverable completion.
 
 ## Handoff Message Template
 
-After successful validation, report:
+After successful validation and the Post-Generation Plan Review Gate, report:
 1. Output file path
 2. Total refactor items
 3. Dependency ordering highlights (which items must run first)
 4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
-5. Recommended next action: `refactor-pipeline-launcher`
+5. Review result: `/prizmkit-code-review` verdict, reviewed refactor IDs, accepted fixes (or "none"), and final validation result
+6. Recommended next action: `refactor-pipeline-launcher`

package/bundled/skills/refactor-planner/references/fast-path.md

@@ -36,7 +36,7 @@ For simple refactoring with minimal scope.
    ```bash
    python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py generate --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json
    ```
-5. If valid -> summarize and recommend next step
+5. If valid -> run the mandatory Post-Generation Plan Review Gate from the main `refactor-planner` skill before summarizing or recommending `refactor-pipeline-launcher`.
 6. If invalid -> apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## When NOT to Use Fast Path
@@ -55,5 +55,6 @@ AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow", "Implement
 User: [Selects "Fast-path"]
 AI: "Drafting R-001..."
 AI: [Validates immediately]
+AI: [Runs the Post-Generation Plan Review Gate on R-001 only]
 AI: "Ready to proceed to dev-pipeline."
 ```

package/bundled/skills/refactor-planner/references/planning-phases.md

@@ -11,8 +11,9 @@ Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and depe
 For each refactoring goal:
 1. Identify atomic refactoring operations
 2. Determine inter-item dependencies (safe renames first, structural changes later)
-3. Assess complexity per item (file count, cross-module scope, test coverage)
-4. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
+3. Assess complexity per item from concrete indicators (file count, cross-module scope, public API/import-path impact, dependency depth, test coverage, behavior-preservation risk, migration impact)
+4. Assign priority from concrete impact (blocked delivery, correctness/security/data risk, maintainability value, or local cleanup), not from size or user urgency alone
+5. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
 
 ---
 
@@ -26,7 +27,9 @@ Refactor Item R-001:
   Type: [extract/rename/restructure/simplify/decouple/migrate]
   Scope: [files list]
   Priority: [critical/high/medium/low]
+  Priority Rationale: [short concrete impact reason]
   Complexity: [low/medium/high]
+  Complexity Rationale: [short scope/risk reason]
   Behavior Preservation: [test-gate/snapshot/manual]
   Acceptance Criteria:
     - [criterion 1]
@@ -63,11 +66,11 @@ Continue until all items are confirmed or skipped.
 Present review summary:
 
 ```
-Item       | Deps Valid | Preservation | Gaps           | Status
-R-001      | OK         | test-gate    | -              | Ready
-R-002      | OK         | test-gate    | -              | Ready
-R-003      | OK         | manual       | No test coverage| Needs attention
-R-004      | OK         | snapshot     | -              | Ready
+Item       | Priority | Priority Rationale       | Complexity | Complexity Rationale        | Deps Valid | Preservation | Gaps           | Status
+R-001      | high     | Blocks core feature work  | high       | 3 modules + public imports  | OK         | test-gate    | -              | Ready
+R-002      | medium   | Planned maintainability   | medium     | 5 files + tests exist       | OK         | test-gate    | -              | Ready
+R-003      | low      | Local readability only    | low        | One file, no API change     | OK         | manual       | No test coverage| Needs attention
+R-004      | medium   | Reduces bounded coupling  | medium     | 2 modules + snapshot check  | OK         | snapshot     | -              | Ready
 ```
 
 If issues found, discuss with user and resolve before proceeding.
@@ -100,13 +103,28 @@ Auto-detect inter-item dependencies and enforce safe ordering:
 
 ## Complexity Assessment
 
+Complexity is a behavior-preserving execution risk estimate, not a measure of how much the user wants the refactor. Do not default to high because a refactor spans multiple files, targets framework code, or improves maintainability.
+
 Assess each item's complexity based on:
-- **File count**: 1-2 files = low, 3-5 files = medium, 6+ files = high
+- **File count**: 1-3 files = low, 4-8 files = medium, 9+ files = high
 - **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
-- **Test coverage**: high coverage = reduces complexity, low coverage = increases complexity
-- **Pattern familiarity**: well-known pattern = low, novel restructuring = high
+- **Public API/import-path impact**: no public change = low, bounded internal interface = medium, public API/import migration = high
+- **Dependency depth**: 0-2 import/update sites = low, 3-5 = medium, 6+ = high
+- **Test coverage**: strong existing tests can keep complexity lower; weak/missing tests increase complexity
+- **Behavior-preservation risk**: test-gate with clear assertions = lower, snapshot/manual verification = higher
+- **Migration impact**: no rollout = low, compatibility shim = medium, cross-module migration or phased rollout = high
+
+Take the highest well-supported individual assessment as the item's complexity, then record the rationale in the confirmation table.
+
+### Mixed Calibration Examples
+
+| Refactor | Priority | Complexity | Rationale |
+|----------|----------|------------|-----------|
+| Break circular dependency blocking auth feature work | high | high | Blocks core delivery; 3 modules, public imports, and weak tests. |
+| Extract chart formatting helpers from dashboard files | medium | medium | Improves planned maintainability; 5 files with bounded helper API and existing tests. |
+| Rename local variable in parser for readability | low | low | Local cleanup only; one file, no interface or behavior change. |
 
-Take the highest of these individual assessments as the item's complexity.
+Anti-pattern: do not generate an all-high refactor list unless every item independently satisfies documented high-priority and high-complexity criteria.
 
 ---