prizmkit 1.1.80 → 1.1.82

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

@@ -7,37 +7,27 @@ description: "Launch and manage the dev-pipeline from within an AI CLI session.
 
 Launch the autonomous development pipeline from within an AI CLI conversation. The pipeline runs as a fully detached background process -- closing the AI CLI session does NOT stop the pipeline.
 
-### Execution Mode
-
-Three execution modes are available. The user chooses one before configuring other options:
-
-1. **Foreground** (recommended) — `.prizmkit/dev-pipeline/run-feature.sh run`. Visible output, direct error feedback, no orphaned processes.
-2. **Background daemon** — `.prizmkit/dev-pipeline/launch-feature-daemon.sh`. Runs fully detached, survives AI CLI session closure.
-3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
+Three execution modes are available (Foreground / Background daemon / Manual); they are defined authoritatively in **Intent A, step 5** below.
 
 ### When to Use
 
 **Start pipeline** -- User says:
-- "run pipeline", "start pipeline", "start building", "launch dev-pipeline"
-- "run the features", "execute feature list", "start implementing"
-- "launch pipeline", "run the pipeline", "start auto-development"
-- After feature-planner completes: "build it", "start developing from the feature list"
-- "run only F-001 to F-005", "run features F-001,F-003", "only build these features"
+- "run feature pipeline", "run pipeline", "start building features", "launch feature pipeline"
+- "start implementing", "execute feature list", "build all features"
+- After feature-planner completes: "build them", "start building from the list"
+- Supports running a feature subset (e.g. "run only F-001 to F-005", "run features F-001,F-003").
 
 **Check status** -- User says:
-- "pipeline status", "check pipeline", "how's it going", "progress"
-- "check progress", "what's the current situation"
+- "pipeline status", "feature progress", "check the pipeline", "how's the build going"
 
 **Stop pipeline** -- User says:
-- "stop pipeline", "kill pipeline", "halt", "pause"
-- "stop the pipeline", "pause the pipeline"
+- "stop pipeline", "stop the pipeline", "halt pipeline", "pause the build"
 
 **Show logs** -- User says:
-- "show logs", "pipeline logs", "tail logs", "what's happening"
-- "view logs", "check the logs"
+- "pipeline logs", "show pipeline logs", "what's building"
 
-**Retry single feature node** -- User says:
-- "retry F-003", "retry this feature", "retry this node", "re-run this feature"
+**Retry single feature** -- User says:
+- "retry F-001", "re-run F-001", "retry this feature"
 
 **Do NOT use this skill when:**
 - User wants to plan features (use `feature-planner` instead)
@@ -129,9 +119,9 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    If `global_context.database` is absent and no features mention database keywords, the script skips DB checks automatically.
 
-5. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call):
+5. **Ask execution mode** (first user decision):
 
-   ⛔ **This MUST be its own standalone `AskUserQuestion` call.** Do NOT combine execution mode with step 6 config questions. The execution mode question is asked ALONE, user responds, THEN you proceed to step 6.
+   **RULE: Ask step 5 and step 6 in separate `AskUserQuestion` calls.** Combining them makes the model merge the questions and skip the mode selection. Ask execution mode ALONE here, wait for the response, THEN proceed to step 6.
 
    Use `AskUserQuestion` with exactly 1 question:
 
@@ -140,19 +130,11 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Background daemon — pipeline runs fully detached via `launch-feature-daemon.sh`. Survives AI CLI session closure.
    - Manual — display the final assembled commands only. Do not execute anything. User runs them on their own.
 
-   ⚠️ STOP HERE and wait for user response before continuing to step 6.
-
-6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 5. You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7.
+   STOP HERE and wait for user response before continuing to step 6.
 
-   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the 4 questions below and WAIT for the user's response. You MUST NOT:
-   - Combine step 5 and step 6 into one `AskUserQuestion` call (this is the most common violation — execution mode MUST be asked separately in step 5)
-   - Skip this step and jump to step 7
-   - Merge step 6 and step 7 into one response
-   - Assume default values and show the command without asking
-   - Show the command as text and ask "ready?" without presenting the options
-   If you find yourself writing the final command before the user has answered these 4 questions, STOP — you are violating this rule.
+6. **Ask configuration options** — MANDATORY INTERACTIVE STEP, applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 5 (see the RULE above). You MUST call `AskUserQuestion` with the 4 questions below and WAIT for the user's response before proceeding to step 7. Do NOT assume defaults, do NOT show the command as text and ask "ready?", and do NOT merge step 6 and step 7. If you find yourself writing the final command before the user has answered these 4 questions, STOP — you are violating this rule.
 
-   Use `AskUserQuestion` to present ALL 4 configuration choices (the full 4-question budget goes to config, NOT shared with execution mode):
+   Use `AskUserQuestion` to present ALL 4 configuration choices:
 
    **Question 1 — Critic review** (multiSelect: false):
    - Off (default) — Skip adversarial review
@@ -173,29 +155,7 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Default Critic to Off unless features have `estimated_complexity: "high"` or above (in which case default to On).
 
-   **If user chose "Yes" to Advanced config**, ask a second round of `AskUserQuestion`:
-
-   **Question 1 — Session timeout** (multiSelect: false):
-   - None (default) — No timeout
-   - 30 min — `SESSION_TIMEOUT=1800`
-   - 1 hour — `SESSION_TIMEOUT=3600`
-   - 2 hours — `SESSION_TIMEOUT=7200`
-
-   **Question 2 — Stop on failure** (multiSelect: false):
-   - Off (default) — Pipeline continues to next task after failure
-   - On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
-
-   **Question 3 — Deploy after completion?** (multiSelect: false):
-   - No (default) — Skip deployment after pipeline completes
-   - Yes — Run /prizmkit-deploy automatically after all features complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any feature did not complete successfully (status not 'completed' or manually 'skipped').
-
-   **Question 4 — Reasoning effort** (multiSelect: false):
-   - Default (none) — Use CLI default
-   - low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
-   - medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
-   - high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
-   - xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
-   - max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
+   **If user chose "Yes" to Advanced config**, ask a second round of `AskUserQuestion` — see the advanced config questions (session timeout, stop-on-failure, deploy-after-completion, reasoning effort) in `${SKILL_DIR}/references/configuration.md`.
 
    **Environment variable mapping** and **advanced environment variables** tables — read `${SKILL_DIR}/references/configuration.md` for the full translation tables (8 config→env mappings + 9 advanced variables).
 

package/bundled/skills/feature-pipeline-launcher/references/configuration.md

@@ -2,6 +2,32 @@
 
 Environment variable mappings for the feature launcher.
 
+## Advanced Config Questions (second AskUserQuestion round)
+
+Asked only when the user chose "Yes" to Advanced config in step 6.
+
+**Question 1 — Session timeout** (multiSelect: false):
+- None (default) — No timeout
+- 30 min — `SESSION_TIMEOUT=1800`
+- 1 hour — `SESSION_TIMEOUT=3600`
+- 2 hours — `SESSION_TIMEOUT=7200`
+
+**Question 2 — Stop on failure** (multiSelect: false):
+- Off (default) — Pipeline continues to next task after failure
+- On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
+
+**Question 3 — Deploy after completion?** (multiSelect: false):
+- No (default) — Skip deployment after pipeline completes
+- Yes — Run /prizmkit-deploy automatically after all features complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any feature did not complete successfully (status not 'completed' or manually 'skipped').
+
+**Question 4 — Reasoning effort** (multiSelect: false):
+- Default (none) — Use CLI default
+- low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
+- medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
+- high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
+- xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
+- max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
+
 ## Environment Variable Mapping
 
 Translating user responses to env vars:

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

@@ -60,13 +60,7 @@ When the user provides detailed specifications, rules, or implementation require
 
 ## When to Use
 
-Trigger this skill for requests like:
-- "Add features to existing system", "Continue planning"
-- "Prepare .prizmkit/plans/feature-list.json", "Prepare dev-pipeline input"
-- "Reprioritize features", "Split features"
-- "Plan features for my project" (when the project already exists)
-
-Do NOT use this skill when:
+Trigger conditions are covered by the frontmatter `description`. Do NOT use this skill when:
 - The user wants to plan a new app from scratch → use `app-planner`
 - The user only wants to run the pipeline → use `feature-pipeline-launcher`
 - The user is debugging/refactoring or wants to write source code directly
@@ -91,7 +85,7 @@ Do NOT use this skill when:
    If the script is not available, perform these manual validation checks:
    1. **ID sequence**: All feature IDs are sequential (F-001, F-002, F-003, ...)
    2. **No circular dependencies**: No feature depends (directly or transitively) on itself
-   3. **Description length**: Minimum 15 words per description (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). No upper limit — more detail is always better
+   3. **Description length**: Minimum 15 words per description (error); see §Output Rules for the recommended-length warning thresholds
    4. **Dependency references**: All referenced features in dependencies exist in features array
    5. **Priority enums**: All priority values are exactly "critical", "high", "medium", or "low" (case-sensitive)
    6. **Status enum**: All status values are one of: pending, in_progress, completed, failed, skipped, split, auto_skipped
@@ -343,7 +337,7 @@ Present a consolidated testing summary table at Phase 8, then ask for confirmati
 
 ## Next-Step Execution Policy (after planning)
 
-Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
+Recommend invoking `feature-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility. Follow the post-planning handoff in §Scope Boundary (never auto-execute).
 
 ## Error Recovery & Resume
 
@@ -380,3 +374,5 @@ After successful validation, report:
 2. Total features + newly added features
 3. Dependency and priority highlights
 4. Recommended next action: `feature-pipeline-launcher`
+
+Then apply the post-planning handoff in §Scope Boundary (ask before proceeding; never auto-execute).

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

@@ -26,39 +26,14 @@ User says:
 
 ## Overview
 
-```
-feature-workflow <idea / requirements>
-   │
-   ├── Phase 1: Brainstorm → collect materials → parallel deep read → discuss requirements
-   │
-   ├── Phase 2: Plan → feature-planner → .prizmkit/plans/feature-list.json
-   │
-   ├── Phase 3: Launch → feature-pipeline-launcher → pipeline execution
-   │
-   └── Phase 4: Monitor → track progress → report results
-```
-
-### What This Skill Does
-
-| Phase | Action | Result |
-|-------|--------|--------|
-| 1 | **Brainstorm** — collect reference materials, parallel deep read code & docs, discuss requirements grounded in real context | Fully clarified requirements document |
-| 2 | Call `feature-planner` with clarified requirements | `.prizmkit/plans/feature-list.json` with N features |
-| 3 | Call `feature-pipeline-launcher` | Pipeline started (execution mode chosen by user via launcher) |
-| 4 | Monitor progress | Status updates, completion report |
+Given an idea or requirements, the workflow runs four phases:
 
-### Why This Skill Exists
+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
 
-Without this skill, users must:
-1. Figure out all requirements themselves
-2. Invoke `feature-planner` → wait for .prizmkit/plans/feature-list.json
-3. Invoke `feature-pipeline-launcher` → wait for pipeline start
-4. Manually check progress
-
-With this skill, users can:
-1. Say "Build a task management App" with a rough idea
-2. The skill brainstorms to fill in all gaps
-3. All planning + execution happens automatically
+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.
 
 ### Branch Management
 
@@ -102,14 +77,14 @@ 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 perfect code generation, which requires perfect understanding of requirements.
 
 ### Step 1.1: Understand the User's Vision
 
 Ask the user to describe what they want to build. Listen for:
-- **What** the system/feature does (core functionality)
-- **Who** uses it (user roles, personas)
-- **Why** it's needed (business value, problem being solved)
+- What the system/feature does (core functionality)
+- Who uses it (user roles, personas)
+- Why it's needed (business value, problem being solved)
 
 ### Step 1.2: Collect Reference Materials
 
@@ -160,7 +135,7 @@ Once brainstorming is complete, produce a structured requirements summary. Read
 
 After confirming requirements, assess whether this feature needs the full pipeline or can be done directly in the current session.
 
-**Simple feature → Fast Path candidate** (ALL must be true):
+**Simple feature** (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
@@ -168,11 +143,18 @@ After confirming requirements, assess whether this feature needs the full pipeli
 - Clear acceptance criteria with existing patterns to follow
 - No dependency on other unbuilt features
 
-**User choice required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
+**Complex feature** (Planning Path — ANY is true):
+- 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."
 
 ```
 AskUserQuestion:
-  question: "This feature appears straightforward. How would you like to proceed?"
+  question: "How would you like to proceed?"   # prefix with the framing note above
   header: "Approach"
   options:
     - label: "Implement now (fast path)"
@@ -187,33 +169,10 @@ AskUserQuestion:
   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)
-
-**Complex feature → Planning Path** (ANY is true):
-- 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 required (mandatory)** — Use `AskUserQuestion` to present interactive selectable options:
-
-```
-AskUserQuestion:
-  question: "This feature is complex and will benefit from structured planning. How would you like to proceed?"
-  header: "Approach"
-  options:
-    - label: "Plan and implement now"
-      description: "Create a plan and implement 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"
-```
-
-- **Plan and implement now** → Invoke `/prizmkit-plan` with requirements → `/prizmkit-implement` → `/prizmkit-code-review` → `/prizmkit-committer` → `/prizmkit-retrospective`. **End workflow** — skip Phase 2/3/4.
+  6. End workflow — skip Phase 2/3/4
 - **Add to feature 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.**
+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).
 

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

@@ -1,6 +1,6 @@
 ---
 name: "prizm-kit"
-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."
+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)"
 ---
 
 # PrizmKit — Full-Lifecycle Development Toolkit
@@ -72,7 +72,8 @@ All three follow the same per-task flow. Detailed documentation policies (when t
 | `/prizmkit-code-review` | Diagnose issues + produce Fix Instructions | "review", "check code", "is it ready to commit" |
 | `/prizmkit-retrospective` | Sync .prizmkit/prizm-docs/ with code changes | "retrospective", "retro", "sync docs", "wrap up" |
 | `/prizmkit-committer` | Safe git commit with Conventional Commits | "commit", "submit", "finish", "ship it" |
-| `/prizmkit-deploy` | Generate/update deployment documentation | "deploy docs", "deployment guide", "how to deploy" |
+| `/prizmkit-test` | Generate + run tests, analyze coverage gaps, unified quality report | "test", "run tests", "check quality", "verify code", "补测试" |
+| `/prizmkit-deploy` | Universal deployment gateway: SSH automation, cloud/Docker guided setup, status/logs/rollback | "deploy", "ship it", "go live", "rollback", "deploy status" |
 | `/prizmkit-init` | Project bootstrap + .prizmkit/prizm-docs/ setup | "init", "initialize", "take over this project" |
 | `/prizmkit-prizm-docs` | Doc management (init/status/rebuild/validate) | "check docs", "rebuild docs", "validate docs" |
 

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

@@ -26,7 +26,7 @@ The loop repeats until the Reviewer finds no issues or the max round limit is re
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md` whose tasks are all completed. |
+| `artifact_dir` | No | Directory containing spec.md + plan.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md` whose tasks are all completed. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. |
 
 ## Phase 0: Context Loading
 

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

@@ -12,7 +12,7 @@ description: "Pure git commit workflow with safety checks. Stages files, generat
 
 ### When NOT to Use
 - No uncommitted changes exist — nothing to commit
-- .prizmkit/prizm-docs/ not synced — run /prizmkit-retrospective first
+- .prizmkit/prizm-docs/ not synced — run /prizmkit-retrospective first (full lifecycle only; the `plan → implement → committer` fast path skips this by design)
 - Code review not passed in pipeline mode — run /prizmkit-code-review first
 - Mid-merge conflict resolution — handle manually with git
 
@@ -24,6 +24,8 @@ description: "Pure git commit workflow with safety checks. Stages files, generat
 | `.prizmkit/prizm-docs/` synced (feature/refactor) | `/prizmkit-retrospective` has run | Run `/prizmkit-retrospective` first |
 | Code review passed (pipeline mode) | `review-report.md` in artifact directory has `## Verdict: PASS` | Run `/prizmkit-code-review` first |
 
+> **Fast-path exemption**: the prizm-docs-synced and review-passed rows above gate the **full lifecycle**. Small, well-scoped changes using the `plan → implement → committer` fast path may commit without them — there is no retrospective or review-report artifact to check, so treat those rows as "satisfied when not applicable."
+
 ### Workflow
 
 Follow these steps in order — skipping or reordering can stage sensitive files or commit without proper verification:

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-deploy"
-description: "Universal deployment gateway for any PrizmKit project. Discovers project type and target (SSH server, Vercel, Docker, etc.), then routes: full automation for SSH Linux with PM2 + Nginx + blue/green switching, guided setup for cloud platforms, or safe documentation fallback for unsupported targets. Also operates existing deployments: status, logs, restart, rollback, health checks, history, validate. Use this skill whenever the user asks about deployment, hosting, going live, or server operations. Triggers on: 'deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'check deploy status', 'view logs', 'restart app', 'rollback', 'how do I deploy this', any deployment or hosting question."
+description: "Universal deployment gateway for any PrizmKit project. Discovers project type and target (SSH server, Vercel, Docker, etc.), then routes: full automation for SSH Linux with PM2 + Nginx + blue/green switching, guided setup for cloud platforms, or safe documentation fallback for unsupported targets. Also operates existing deployments: status, logs, restart, rollback, health checks, history, validate. Use this skill whenever the user asks about deployment, hosting, going live, or server operations. Triggers on: 'deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'check deploy status', 'view logs', 'restart app', 'rollback', 'how do I deploy this', any deployment or hosting question. (project)"
 ---
 
 # PrizmKit Deploy — Universal Deployment Gateway

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

@@ -23,7 +23,7 @@ description: "Execute plan.md tasks with TDD approach. Respects task ordering an
 | `plan.md` with Tasks section | File exists + unchecked tasks | Run `/prizmkit-plan` |
 | `spec.md` | File exists in same directory as plan.md | Run `/prizmkit-plan` |
 
-**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks. When invoked as a handoff step in a skill chain, reuse the `artifact_dir` from the previous skill rather than re-detecting — re-detection can resolve to a different feature's directory in a multi-task workspace.
 
 ## Input
 

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -59,6 +59,7 @@ PRECONDITION: No .prizmkit/prizm-docs/ directory exists, or user confirms overwr
 
 Update .prizmkit/prizm-docs/ to reflect recent code changes.
 PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+**Scope guard**: Use Update only for out-of-band resync — when docs drifted from code after manual edits, merges, branch switches, or other changes made outside the dev loop. During the normal feature/bugfix/refactor loop, do NOT use Update: `/prizmkit-retrospective` is the sole writer and keeps docs in sync per task. Running both is redundant and risks conflicting edits.
 → Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
 
 ## Operation: Status

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

@@ -27,7 +27,7 @@ For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` inst
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing spec.md, plan.md, review-report.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. If no artifact directory found, run in standalone mode (structural sync only from `git diff`). |
+| `artifact_dir` | No | Directory containing spec.md, plan.md, review-report.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. If no artifact directory found, run in standalone mode (structural sync only from `git diff`). |
 
 ## When NOT to Use
 

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

@@ -55,30 +55,24 @@ Pipeline commands (for reference — Phase 1.3 will present these as a selectabl
 
 ## Overview
 
-```
-recovery-workflow
-  │
-  ├── Phase 0: Auto-detect
-  │   ├── Read current branch name
-  │   ├── Scan characteristic artifacts
-  │   ├── Match workflow signature → determine workflow type
-  │   ├── Based on artifact presence → infer current phase
-  │   └── No match → reject and guide user
-  │
-  ├── Phase 1: Diagnose + report + user choice
-  │   ├── Check branch and working tree state
-  │   ├── Scan all pipelines for failed/in-progress tasks
-  │   ├── Find residual dev branches from failed tasks
-  │   ├── Display diagnosis + detection results
-  │   ├── If code changes exist → run test suite
-  │   ├── If multiple failed tasks → ask user which to recover
-  │   └── User chooses: run-recovery.sh (recommended) | interactive | start fresh
-  │
-  └── Phase 2: Execute remaining steps
-      ├── Read target workflow's SKILL.md
-      ├── Read existing artifacts to restore context
-      └── Execute from inferred phase through completion
-```
+1. **Phase 0: Auto-detect**
+   1. Read current branch name
+   2. Scan characteristic artifacts
+   3. Match workflow signature → determine workflow type
+   4. Based on artifact presence → infer current phase
+   5. No match → reject and guide user
+2. **Phase 1: Diagnose + report + user choice**
+   1. Check branch and working tree state
+   2. Scan all pipelines for failed/in-progress tasks
+   3. Find residual dev branches from failed tasks
+   4. Display diagnosis + detection results
+   5. If code changes exist → run test suite
+   6. If multiple failed tasks → ask user which to recover
+   7. User chooses: run-recovery.sh (recommended) | interactive | start fresh
+3. **Phase 2: Execute remaining steps**
+   1. Read target workflow's SKILL.md
+   2. Read existing artifacts to restore context
+   3. Execute from inferred phase through completion
 
 ---
 
@@ -289,53 +283,19 @@ This step replaces the context that was lost when the AI session was interrupted
 
 ---
 
-### 2.1 Bug-Fix-Workflow Recovery
-
-Phase inference table:
+### 2.1 Per-Workflow Phase Inference
 
-| Detected State | Resume From | Actions |
-|---------------|------------|---------|
-| On `fix/<BUG_ID>-*` branch, no artifacts | Phase 1: Deep Bug Diagnosis | Read bug description from `.prizmkit/plans/bug-fix-list.json`. Start interactive diagnosis Q&A |
-| `fix-plan.md` exists, no code changes | Phase 4: Fix | Read fix-plan.md. Implement the fix following the plan |
-| `fix-plan.md` + code changes exist | Phase 5: Review | Invoke `/prizmkit-code-review` on all changes |
-| All docs + review passed | Phase 6: User Verification | Ask user to verify the fix works |
-| All docs + committed | Phase 7: Merge Decision | Ask merge vs keep branch |
+Read `${SKILL_DIR}/references/detection.md` for the per-workflow phase-inference tables (bug-fix / feature / refactor) that map detected state → the phase to resume from and its actions.
 
-**Note**: Bug-fix Phases 1-3 (Diagnosis, Triage, Reproduce) collapse to Phase 1 for detection purposes because these phases don't produce persistent artifacts. If interrupted during these phases, recovery restarts from Phase 1 (diagnosis), which re-derives understanding from available inputs (bug description, code) without interactive Q&A.
-
-**Execution for each remaining phase**: Follow the bug-fix-workflow SKILL.md instructions exactly. Call the same prizmkit sub-commands (`/prizmkit-code-review`, `/prizmkit-committer`) at the same points.
+**Bug-fix execution**: Follow the bug-fix-workflow SKILL.md instructions exactly. Call the same prizmkit sub-commands (`/prizmkit-code-review`, `/prizmkit-committer`) at the same points.
 
 **Special handling**:
 - If resuming from Phase 5 (Review) and tests are failing, fix test failures first (max 3 attempts). If unfixable, ask user whether to continue or restart.
 - If resuming from Phase 4 (Fix), read fix-plan.md to understand the planned approach before writing code.
 
----
+**Feature recovery**: Phases 3-4 are pipeline-driven. The main recovery value is avoiding re-brainstorming (Phase 1) when `.prizmkit/plans/feature-list.json` already exists.
 
-### 2.2 Feature-Workflow Recovery
-
-Phase inference table:
-
-| Detected State | Resume From | Actions |
-|---------------|------------|---------|
-| No `.prizmkit/plans/feature-list.json` | Phase 1: Brainstorm | Cannot recover conversation context. Start requirement clarification, but leverage any workspace content (README, existing code) for context |
-| `.prizmkit/plans/feature-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `feature-pipeline-launcher` to start the pipeline |
-| `.prizmkit/plans/feature-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status via `feature-pipeline-launcher` (Intent B: Check Status) |
-
-**Note**: Feature-workflow recovery is simpler because Phases 3-4 are pipeline-driven. The main recovery value is avoiding re-brainstorming (Phase 1) when `.prizmkit/plans/feature-list.json` already exists.
-
----
-
-### 2.3 Refactor-Workflow Recovery
-
-Phase inference table (mirrors feature-workflow):
-
-| Detected State | Resume From | Actions |
-|---------------|------------|---------|
-| No `.prizmkit/plans/refactor-list.json` | Phase 1: Brainstorm | Start refactoring goal clarification |
-| `.prizmkit/plans/refactor-list.json` exists, no pipeline state | Phase 3: Launch | Invoke `refactor-pipeline-launcher` to start the pipeline |
-| `.prizmkit/plans/refactor-list.json` + pipeline state exists | Phase 4: Monitor | Check pipeline status |
-
----
+**Refactor recovery**: Mirrors feature-workflow (brainstorm → launch → monitor).
 
 ### 2.4 Post-Recovery Report
 
@@ -387,16 +347,6 @@ Recovery complete.
 
 ---
 
-## Comparison with Previous Version
-
-| Dimension | Previous | Current |
-|-----------|----------|---------|
-| Scope | Feature pipeline only | All 3 interactive workflows |
-| Input | Required `F-XXX` feature ID | No input — fully auto-detect |
-| Detection | Feature-specific (spec/plan/git) | Signature-based (branch + artifacts) |
-| Strategy | Multi-option (5 scenarios × 2-4 options each) | Single path: report → confirm → execute |
-| Intrusion | None | None (zero changes to target workflows) |
-
 ## Output
 
 - Resumed and completed workflow from the breakpoint

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

@@ -130,28 +130,13 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Wait for user confirmation before proceeding.
 
-5. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call):
+5. **Ask execution mode** (first user decision):
 
-   ⛔ **This MUST be its own standalone `AskUserQuestion` call.** Do NOT combine execution mode with step 6 config questions. The execution mode question is asked ALONE, user responds, THEN you proceed to step 6.
+   Present the three execution modes from the **Execution Mode** section above as a single standalone `AskUserQuestion` call (exactly 1 question, multiSelect: false). Wait for the user's response before continuing to step 6.
 
-   Use `AskUserQuestion` with exactly 1 question:
+   Each `AskUserQuestion` round is a genuine gate: callers tend to merge interactive rounds and pre-fill answers, which skips real user decisions and produces wrong configs. Therefore: ask execution mode (step 5) and configuration (step 6) as SEPARATE `AskUserQuestion` calls, in order, and do not assemble or show the final command (step 7) until the user has answered both. If you find yourself writing the final command before the user has answered, STOP — you are violating this rule.
 
-   **Question 1 — Execution mode** (multiSelect: false):
-   - Foreground (Recommended) — pipeline runs in the current session via `run-refactor.sh run`. Visible output and direct error feedback.
-   - Background daemon — pipeline runs fully detached via `launch-refactor-daemon.sh`. Survives AI CLI session closure.
-   - Manual — display the final assembled commands only. Do not execute anything. User runs them on their own.
-
-   ⚠️ STOP HERE and wait for user response before continuing to step 6.
-
-6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 5. You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7.
-
-   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the 4 questions below and WAIT for the user's response. You MUST NOT:
-   - Combine step 5 and step 6 into one `AskUserQuestion` call (this is the most common violation — execution mode MUST be asked separately in step 5)
-   - Skip this step and jump to step 7
-   - Merge step 6 and step 7 into one response
-   - Assume default values and show the command without asking
-   - Show the command as text and ask "ready?" without presenting the options
-   If you find yourself writing the final command before the user has answered these 4 questions, STOP — you are violating this rule.
+6. **Ask configuration options** — a SEPARATE `AskUserQuestion` call from step 5, applies to ALL execution modes (Foreground, Background, AND Manual).
 
    Use `AskUserQuestion` to present ALL 4 configuration choices (the full 4-question budget goes to config, NOT shared with execution mode):
 
@@ -174,37 +159,7 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Note: Refactor filter defaults to all refactor items (by priority order). If the user selects "Other" on any option, handle their custom input.
 
-   **If user chose "Yes" to Advanced config**, ask a second round of `AskUserQuestion`:
-
-   **Question 1 — Session timeout** (multiSelect: false):
-   - None (default) — No timeout
-   - 30 min — `SESSION_TIMEOUT=1800`
-   - 1 hour — `SESSION_TIMEOUT=3600`
-   - 2 hours — `SESSION_TIMEOUT=7200`
-
-   **Question 2 — Stop on failure** (multiSelect: false):
-   - Off (default) — Pipeline continues to next task after failure
-   - On — Pipeline halts immediately when a task exhausts all retries (`STOP_ON_FAILURE=1`)
-
-   **Question 3 — Critic review** (multiSelect: false):
-   - Off (default) — Skip adversarial review
-   - On — Enable adversarial critic review: an independent AI agent reviews the refactor plan for completeness and the implementation for regressions, missed edge cases, and behavior violations. Adds ~5-10 min per refactor task.
-
-   **Question 4 — Deploy after completion?** (multiSelect: false):
-   - No (default) — Skip deployment after pipeline completes
-   - Yes — Run /prizmkit-deploy automatically after all refactors complete successfully (`ENABLE_DEPLOY=1`). Deployment is blocked if any refactor did not complete successfully (status not 'completed' or manually 'skipped').
-
-   Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
-
-   **If advanced config was selected, also ask about reasoning effort** in a follow-up `AskUserQuestion` call:
-
-   **Question — Reasoning effort** (multiSelect: false):
-   - Default (none) — Use CLI default
-   - low — Minimize reasoning, fastest output (`PRIZMKIT_EFFORT=low`)
-   - medium — Moderate reasoning (`PRIZMKIT_EFFORT=medium`)
-   - high — Thorough reasoning for complex tasks (`PRIZMKIT_EFFORT=high`)
-   - xhigh — Extensive reasoning (`PRIZMKIT_EFFORT=xhigh`)
-   - max — Maximum reasoning, Claude Code only (`PRIZMKIT_EFFORT=max`)
+   **If user chose "Yes" to Advanced config**, run the advanced configuration round (a second `AskUserQuestion` round, plus a reasoning-effort follow-up). It applies to a minority of sessions, so the full question set lives in `${SKILL_DIR}/references/configuration.md` → **Advanced Configuration Round**. Default Critic to Off unless refactor items have `priority: "critical"` (in which case default to On).
 
    **Environment variable mapping** and **advanced environment variables** tables — read `${SKILL_DIR}/references/configuration.md` for the full translation tables (10 config→env mappings + 8 advanced variables).
 
@@ -356,7 +311,7 @@ Notes:
 
 ### Error Handling
 
-Read `${SKILL_DIR}/references/configuration.md` for the full error handling table (14 entries).
+Read the error-handling table in `${SKILL_DIR}/references/configuration.md` for the full list of errors and recovery actions.
 
 ### Integration Notes