prizmkit 1.0.45 → 1.0.58

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

@@ -92,7 +92,7 @@ Execute the selected scenario workflow in conversation mode with mandatory check
 
 ### Checkpoints (Mandatory Gates)
 
-Never skip checkpoints. If any checkpoint fails, follow error recovery flow (see §Error Recovery).
+Checkpoints catch cascading errors early — skipping one means the next phase builds on unvalidated assumptions, which compounds into much harder debugging later.
 
 | Checkpoint | Artifact/State | Criteria | Phase |
 |-----------|----------------|----------|-------|
@@ -311,16 +311,17 @@ Resume incremental planning? (Y/n)"
 
 ### Artifact Path Convention
 
-Recommended structure for feature planning artifacts:
+The primary output `feature-list.json` is always written to the **project root** — this is where `dev-pipeline-launcher` and all pipeline scripts expect it.
 
 ```
-.prizmkit/planning/
-  ├── feature-list.json              # Primary output (always here)
-  ├── feature-list.validated.json    # Checkpoint backup after CP-AP-5
-  └── <ISO-timestamp>.backup.json    # Optional incremental backups
+<project-root>/
+  ├── feature-list.json              # Primary output (always here, at project root)
+  └── .prizmkit/planning/            # Optional organization for backups
+      ├── feature-list.validated.json    # Checkpoint backup after CP-AP-5
+      └── <ISO-timestamp>.backup.json    # Optional incremental backups
 ```
 
-Mention this path when summarizing (Phase 8 handoff) to help users organize future sessions.
+The pipeline reads `feature-list.json` from the project root by default. If the user specifies a custom path, the launcher accepts it as an argument.
 
 Maintainer note: evaluation workflow moved to `assets/evaluation-guide.md`.
 

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

@@ -0,0 +1,174 @@
+---
+name: "bug-fix-workflow"
+tier: companion
+description: "Interactive single-bug fix in current session. Guides through triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', '修这个 bug', '交互式修复', '手动修 bug'. (project)"
+---
+
+# Bug Fix Workflow
+
+Fix a single bug interactively within the current AI CLI session. This is the in-session counterpart to `bugfix-pipeline-launcher` (which runs multiple bugs in the background).
+
+## When to Use
+
+- User wants to fix **one specific bug** right now, with full visibility
+- User says "fix this bug", "debug this error", "help me fix B-001", "修这个 bug"
+- User has a stack trace or error and wants interactive debugging
+- User prefers hands-on fixing over background pipeline
+
+**Do NOT use when:**
+- User has multiple bugs to fix in batch → `bug-planner` + `bugfix-pipeline-launcher`
+- User wants to plan/collect bugs without fixing → `bug-planner`
+- User wants background autonomous fixing → `bugfix-pipeline-launcher`
+- User wants to build features → `feature-workflow`
+
+## Input
+
+The bug can come from:
+- **A bug-fix-list.json entry**: "fix B-001" → read the entry from bug-fix-list.json
+- **A stack trace/error message**: user pastes error directly
+- **A description**: "the login page crashes when I click submit"
+- **A failed test**: "this test is failing: src/auth/__tests__/login.test.ts"
+
+## Execution
+
+### Phase 1: Triage
+
+**Goal**: Understand the bug, locate affected code, classify severity.
+
+1. **Gather bug info**:
+   - If bug ID given (e.g. B-001): read entry from `bug-fix-list.json`
+   - If raw error: extract error message, stack trace, affected files
+   - If description: ask clarifying questions to narrow down the issue
+2. **Read project context**: `.prizm-docs/root.prizm` → relevant L1/L2 docs for affected modules
+3. **Locate affected code**: read the files mentioned in the error/stack trace
+4. **Check known issues**: search `.prizm-docs/` TRAPS sections for matching patterns
+5. **Classify**: root cause (confirmed/suspected), blast radius, fix complexity
+6. **Present diagnosis to user**:
+   ```
+   Bug: Login page crash on submit
+   Root Cause: AuthService.handleLogin() receives null token when API returns 401
+   Affected Files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
+   Fix Complexity: Low (null check + error handling)
+   ```
+   Ask: "Does this diagnosis look right? Should I proceed with the fix?"
+
+### Phase 2: Reproduce
+
+**Goal**: Create a failing test that proves the bug exists.
+
+1. **Write a reproduction test** that demonstrates the bug:
+   - Name: `<module>.test.ts` → add a test case named `should handle <bug scenario>`
+   - The test captures the exact failure condition
+2. **Run the test** → confirm it **fails** (red)
+3. **Show result to user**: "Reproduction test written and confirmed failing."
+
+If the bug is hard to reproduce automatically (e.g. environment-specific):
+- Ask the user for reproduction steps
+- Write a manual reproduction checklist instead
+- Proceed to Phase 3 with the manual checklist
+
+### Phase 3: Fix
+
+**Goal**: Implement the minimal fix. Red test → green.
+
+1. **Implement the fix**:
+   - Change the minimum amount of code to fix the root cause
+   - Do NOT refactor or add unrelated improvements — fix the bug only
+   - Follow existing code conventions (read from `.prizm-docs/` RULES/PATTERNS)
+2. **Run the reproduction test** → must **pass** (green)
+3. **Run the full module test suite** → must pass (no regressions)
+4. **Show the fix to user**:
+   - Summary of changes made
+   - Test results (reproduction + regression)
+   - Ask: "Fix looks good? Any concerns?"
+
+If the fix causes test regressions:
+- Show which tests broke and why
+- Revise the fix (max 3 attempts)
+- If still failing after 3 attempts, escalate to user with analysis
+
+### Phase 4: Review
+
+**Goal**: Verify fix quality before committing.
+
+1. **Self-review** the changes:
+   - Does the fix address the root cause (not just the symptom)?
+   - Are there edge cases not covered?
+   - Is the reproduction test thorough enough?
+   - Does the fix follow project conventions?
+2. **Run full test suite** one final time
+3. **Present review summary**:
+   ```
+   Fix Review:
+   - Root cause addressed: Yes (null check added at auth service level)
+   - Edge cases: Covered (401, 403, network error)
+   - Regression: None (48/48 tests pass)
+   - Code quality: Clean, follows existing patterns
+
+   Ready to commit.
+   ```
+
+### Phase 5: Commit
+
+**Goal**: Commit the fix with proper conventions.
+
+1. **Run `/prizmkit-retrospective`** (Job 1: structural sync only):
+   - Update `.prizm-docs/` if file structure changed
+   - Add TRAPS entry only if a genuinely new pitfall was discovered
+   - Skip knowledge injection for routine bug fixes
+2. **Run `/prizmkit-committer`**:
+   - Commit message: `fix(<scope>): <description>`
+   - Include both fix code and reproduction test
+   - Do NOT push (user decides when to push)
+3. **If bug came from bug-fix-list.json**: inform user to update bug status
+   ```
+   Bug B-001 fixed and committed.
+   To update the bug list: manually set B-001 status to "fixed" in bug-fix-list.json
+   Or retry the pipeline to pick up remaining bugs.
+   ```
+
+## Artifacts
+
+Bug fix artifacts are stored at `.prizmkit/bugfix/<BUG_ID>/`:
+- `fix-plan.md` — Triage output (diagnosis, root cause, fix approach)
+- `fix-report.md` — Post-fix summary (what changed, test results, TRAPS added)
+
+Only 2 artifact files per bug, consistent with the pipeline convention.
+
+## Comparison with Pipeline Bug Fix
+
+| Dimension | bug-fix-workflow (this skill) | bugfix-pipeline-launcher |
+|-----------|-------------------------------|--------------------------|
+| Scope | One bug at a time | All bugs in batch |
+| Execution | Interactive, in-session | Background daemon |
+| Visibility | Full user interaction at each phase | Async, check status periodically |
+| Best for | Complex bugs needing user input | Batch of well-defined bugs |
+| Artifacts | Same (fix-plan.md + fix-report.md) | Same |
+| Commit prefix | `fix(<scope>):` | `fix(<scope>):` |
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Bug ID not found in bug-fix-list.json | Ask user to provide bug details directly |
+| Cannot reproduce the bug | Ask for more context, try alternative reproduction |
+| Fix causes regressions | Revert, analyze, retry (max 3 rounds) |
+| Root cause unclear after investigation | Present findings, ask user for guidance |
+| Affected files are in unfamiliar module | Read `.prizm-docs/` L1/L2 for that module first |
+
+## HANDOFF
+
+| From | To | Condition |
+|------|----|-----------|
+| `bug-planner` | **this skill** | User picks one bug to fix interactively |
+| `bugfix-pipeline-launcher` | **this skill** | User wants to fix a stuck/complex bug manually |
+| **this skill** | `bugfix-pipeline-launcher` | After fixing, user wants to continue with remaining bugs |
+| **this skill** | `prizmkit-retrospective` | Built into Phase 5 (structural sync) |
+
+## Output
+
+- Fixed code with reproduction test
+- `.prizmkit/bugfix/<BUG_ID>/fix-plan.md`
+- `.prizmkit/bugfix/<BUG_ID>/fix-report.md`
+- Git commit with `fix(<scope>):` prefix
+- Updated `.prizm-docs/` TRAPS (if new pitfall discovered)

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

@@ -1,7 +1,7 @@
 ---
 name: "bug-planner"
 tier: companion
-description: "Interactive bug planning that produces bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. (project)"
+description: "Interactive bug planning that produces bug-fix-list.json for the Bug Fix Pipeline. Supports multiple input formats: error logs, stack traces, user reports, failed tests, monitoring alerts. Use this skill whenever the user has bugs to report, errors to parse, or test failures to organize. Trigger on: 'plan bug fixes', 'report bugs', 'I have some bugs', 'these tests are failing', 'here is an error log', 'parse these errors', '修复 bug', '生成 bug 列表', '规划 bug 修复'. (project)"
 ---
 
 # Bug Planner
@@ -17,33 +17,28 @@ User says:
 - "here's an error log", "parse these errors"
 - After receiving bug reports, error logs, or failed test output
 
-## Commands
+**Do NOT use when:**
+- User wants to start fixing bugs now (use `bugfix-pipeline-launcher`)
+- User wants to fix a single bug interactively (use `bug-fix-workflow`)
+- User wants to plan features (use `app-planner`)
 
-### prizmkit.bug-plan
+## Intent Routing
 
-Launch the interactive bug planning process.
+This skill handles multiple operations. Determine the user's intent and execute the matching operation:
 
-### prizmkit.bug-plan-from-log \<log-file-or-content\>
-
-Auto-generate bug entries from error logs or stack traces.
-
-### prizmkit.bug-plan-from-tests \<test-output\>
-
-Auto-generate bug entries from failed test case output.
-
-### prizmkit.bug-plan-validate \<bug-fix-list.json\>
-
-Validate an existing `bug-fix-list.json` against the schema.
-
-### prizmkit.bug-plan-summary \<bug-fix-list.json\>
-
-Print a summary of bugs grouped by severity and status.
+| User Intent | Operation | Trigger Phrases |
+|---|---|---|
+| Plan bugs interactively | **Interactive Planning** | "plan bug fixes", "report bugs", "规划 bug 修复" |
+| Parse error logs into bugs | **From Log** | "parse this error log", "here's a stack trace", "parse these errors" |
+| Parse test failures into bugs | **From Tests** | "these tests are failing", "parse test output" |
+| Validate existing bug list | **Validate** | "validate bug list", "check bug-fix-list.json" |
+| Summarize bug list | **Summary** | "bug summary", "show bug list", "list bugs" |
 
 ---
 
-## Interactive Planning Process
+## Operation: Interactive Planning
 
-The interactive `prizmkit.bug-plan` command guides through 4 phases:
+Launch the interactive bug planning process through 4 phases.
 
 ### Phase 1: Project Context
 
@@ -179,14 +174,11 @@ Next steps:
 - Review: cat bug-fix-list.json
 - Start fixing: say "开始修复" or "start fixing bugs" to launch the bugfix pipeline
 - Or run directly: ./dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json
-- Fix one interactively: invoke bug-fix-workflow for each bug
 ```
 
 ---
 
-## Non-Interactive Commands
-
-### prizmkit.bug-plan-from-log
+## Operation: From Log
 
 Batch-parse error logs to generate bug entries without interactive prompts:
 
@@ -202,7 +194,7 @@ Batch-parse error logs to generate bug entries without interactive prompts:
 4. Output draft `bug-fix-list.json` for user review
 5. Ask: "Review and confirm? You can edit individual entries."
 
-### prizmkit.bug-plan-from-tests
+## Operation: From Tests
 
 Batch-parse failed test output:
 
@@ -212,7 +204,7 @@ Batch-parse failed test output:
 4. Set verification_type to `automated` (test already exists)
 5. Output draft `bug-fix-list.json`
 
-### prizmkit.bug-plan-validate
+## Operation: Validate
 
 Validate existing `bug-fix-list.json`:
 
@@ -226,7 +218,7 @@ Validate existing `bug-fix-list.json`:
    - Invalid `affected_feature` references (if feature-list.json exists)
 4. Output: validation result with specific errors/warnings
 
-### prizmkit.bug-plan-summary
+## Operation: Summary
 
 Print human-readable summary:
 
@@ -269,10 +261,6 @@ After `bug-fix-list.json` is generated, the user can:
 | Invalid feature reference | Warn and ask user to correct or remove reference |
 | Schema validation failure | Show specific errors, offer to fix interactively |
 
-## Path References
-
-All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
-
 ## Output
 
 - `bug-fix-list.json` conforming to `dev-pipeline/templates/bug-fix-list-schema.json`

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

@@ -1,17 +1,15 @@
 ---
 name: "bugfix-pipeline-launcher"
-description: "Launch and manage the bugfix pipeline from within a cbc session. Start pipeline in background, monitor logs, check status, stop pipeline. Invoke when user wants to start fixing bugs, run the bugfix pipeline, or check bugfix progress. (project)"
+description: "Launch and manage the bugfix pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start fixing bugs, run the bugfix pipeline, check bugfix progress, or stop the bugfix pipeline. Trigger on: 'start fixing bugs', 'run bugfix pipeline', 'bugfix status', 'stop bug fix', '启动 bug 修复', '开始修复 bug', '修复进度', '停止修复'. (project)"
 ---
 
 # Bugfix-Pipeline Launcher
 
 Launch the autonomous bug fix pipeline from within a cbc conversation. The pipeline runs as a fully detached background process -- closing the cbc session does NOT stop the pipeline.
 
-### Mandatory Execution Mode (MUST)
+### Execution Mode
 
-- Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop/status/log actions.
-- NEVER run `dev-pipeline/run-bugfix.sh run ...` directly from this skill.
-- Reason: foreground `run-bugfix.sh` can be terminated by AI CLI command timeout (e.g. cbc 120s), while daemon mode survives session timeout.
+Always use daemon mode via `dev-pipeline/launch-bugfix-daemon.sh` for start/stop/status/log actions. Foreground `run-bugfix.sh` can be terminated by AI CLI command timeout (e.g. cbc 120s), while daemon mode survives session timeout — this prevents half-finished bug fixes that leave the codebase in an inconsistent state.
 
 ### When to Use
 

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

@@ -1,17 +1,15 @@
 ---
 name: "dev-pipeline-launcher"
-description: "Launch and manage the dev-pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Invoke when user wants to start building features, run the pipeline, or check pipeline progress. (project)"
+description: "Launch and manage the dev-pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start building features, run the pipeline, check pipeline progress, retry features, or stop the pipeline. Trigger on: 'run pipeline', 'start pipeline', 'start building', 'pipeline status', 'stop pipeline', 'retry feature', '启动流水线', '开始实现', '流水线状态', '停止流水线'. (project)"
 ---
 
 # Dev-Pipeline Launcher
 
 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.
 
-### Mandatory Execution Mode (MUST)
+### Execution Mode
 
-- Always use daemon mode via `dev-pipeline/launch-daemon.sh` for start/stop/status/log actions.
-- NEVER run `dev-pipeline/run.sh run ...` directly from this skill.
-- Reason: foreground `run.sh` can be terminated by AI CLI command timeout (e.g. cbc 120s, claude may vary), while daemon mode survives session timeout.
+Always use daemon mode via `dev-pipeline/launch-daemon.sh` for start/stop/status/log actions. Foreground `run.sh` can be terminated by AI CLI command timeout (e.g. cbc 120s, claude may vary), while daemon mode survives session timeout — this prevents half-finished features that leave the codebase in an inconsistent state.
 
 ### When to Use
 
@@ -284,4 +282,4 @@ Notes:
 - **Single instance**: Only one pipeline can run at a time. The PID file prevents duplicates.
 - **Pipeline coexistence**: Feature and bugfix pipelines use separate state directories (`state/` vs `bugfix-state/`), so they can run simultaneously without conflict.
 - **State preservation**: Stopping and restarting the pipeline resumes from where it left off -- completed features are not re-run.
-- **HANDOFF**: After pipeline completes all features, suggest running `prizmkit-code-review` for overall review, or `prizmkit-summarize` to archive.
+- **HANDOFF**: After pipeline completes all features, suggest running `prizmkit-retrospective` for project memory update, or ask user what's next.

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

@@ -1,7 +1,7 @@
 ---
 name: "feature-workflow"
 tier: companion
-description: "One-stop entry point for feature development. Orchestrates app-planner → dev-pipeline-launcher → background execution. Handles multi-feature batch development from a single request. (project)"
+description: "One-stop entry point for feature development. Orchestrates app-planner → dev-pipeline-launcher → background 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', '开发一个新应用', '构建系统', '一键完成', '批量实现'. (project)"
 ---
 
 # Feature Workflow
@@ -28,7 +28,7 @@ User says:
 ## Overview
 
 ```
-prizmkit.feature <需求描述>
+feature-workflow <需求描述>
    │
    ├── Phase 1: Plan → app-planner → feature-list.json
    │
@@ -58,48 +58,31 @@ With this skill, users can:
 
 ---
 
-## Commands
+## Input Modes
 
-### prizmkit.feature \<需求描述\>
+**Mode A: From natural language requirements** (default)
 
-One-stop feature development from natural language requirements.
-
-**INPUT**: Natural language description of the project or features. Can be:
+Natural language description of the project or features. Can be:
 - A project vision: "开发一个任务管理 App，支持用户登录、任务增删改查、任务分类"
 - A batch of features: "实现用户注册、登录、找回密码这三个功能"
 - An incremental request: "给现有系统追加用户头像上传和昵称修改功能"
 
-**FLOW**:
-1. Invoke `app-planner` with the description
-2. After feature-list.json is generated, invoke `dev-pipeline-launcher`
-3. Monitor and report progress
-
-### prizmkit.feature --from \<feature-list.json\>
-
-Skip planning, directly launch pipeline from existing feature-list.json.
-
-**USE WHEN**:
-- feature-list.json already exists
-- User wants to restart/resume pipeline execution
-
-**FLOW**:
-1. Skip `app-planner` (file already exists)
-2. Invoke `dev-pipeline-launcher` directly
-3. Monitor and report progress
+Flow: app-planner → dev-pipeline-launcher → monitor
 
-### prizmkit.feature \<需求描述\> --incremental
+**Mode B: From existing feature-list.json**
 
-Add new features to an existing project (incremental mode).
+When user says "run pipeline from existing file" or feature-list.json already exists:
+- Skip `app-planner` (file already exists)
+- Invoke `dev-pipeline-launcher` directly
+- Monitor and report progress
 
-**USE WHEN**:
-- Project already has features implemented
-- User wants to add new features to existing codebase
+**Mode C: Incremental (add to existing project)**
 
-**FLOW**:
-1. Invoke `app-planner` in incremental mode (reads existing feature-list.json)
-2. Append new features to existing list
-3. Invoke `dev-pipeline-launcher`
-4. Monitor and report progress
+When user says "add features to existing project" or the project already has features:
+- Invoke `app-planner` in incremental mode (reads existing feature-list.json)
+- Append new features to existing list
+- Invoke `dev-pipeline-launcher`
+- Monitor and report progress
 
 ---
 
@@ -248,18 +231,18 @@ While the pipeline runs in background, the user can continue the conversation:
 
 | Dimension | feature-workflow | bug-fix-workflow | refactor-workflow |
 |-----------|-----------------|------------------|-------------------|
-| **Purpose** | New features (batch) | Bug fixes (batch) | Code restructuring |
-| **Planning Skill** | `app-planner` | `bug-planner` | None (direct invocation) |
-| **Launcher Skill** | `dev-pipeline-launcher` | `bugfix-pipeline-launcher` | None (in-session) |
-| **Input** | Requirements description | Bug reports / logs | Module / code target |
-| **Output** | Multiple `feat()` commits | Multiple `fix()` commits | Single `refactor()` commit |
-| **Execution Mode** | Background daemon | Background daemon | In-session |
+| **Purpose** | New features (batch) | Single bug fix (interactive) | Code restructuring |
+| **Planning Skill** | `app-planner` | None (triage built-in) | None (analysis built-in) |
+| **Execution** | Background daemon | In-session, interactive | In-session |
+| **Input** | Requirements description | Bug report / stack trace | Module / code target |
+| **Output** | Multiple `feat()` commits | Single `fix()` commit | Single `refactor()` commit |
+| **Batch alternative** | (this is the batch flow) | `bug-planner` + `bugfix-pipeline-launcher` | N/A |
 
 ---
 
 ## Path References
 
-All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+All internal asset paths use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
 
 ## Output
 
@@ -267,4 +250,4 @@ All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compa
 - Background pipeline running (Phase 2)
 - Progress updates (Phase 3)
 - Multiple git commits with `feat(<scope>):` prefix
-- Updated `REGISTRY.md` (via prizmkit.summarize per feature)
+- Updated `.prizm-docs/` (via prizmkit-retrospective per feature)

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

@@ -1,6 +1,6 @@
 ---
 name: "prizm-kit"
-description: "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management. Use 'prizmkit.*' for help. (project)"
+description: "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management. Use this skill whenever the user asks about PrizmKit workflow, wants to know which command to use, or needs help choosing between full workflow and fast path. Trigger on: '/prizmkit', 'prizmkit help', 'which prizmkit command', 'how do I start a feature'. (project)"
 ---
 
 # PrizmKit — Full-Lifecycle Development Toolkit
@@ -25,6 +25,8 @@ PrizmKit is a comprehensive, independent AI development toolkit that covers the
 - Architectural decisions
 - Data model or API changes
 
+The full workflow generates spec, plan, and task artifacts that create a traceable record of what was built and why — this matters for future maintainability and AI context loading.
+
 **Use fast path (implement -> commit directly):**
 - Bug fixes with clear root cause
 - Single-file config or typo fixes
@@ -32,15 +34,36 @@ PrizmKit is a comprehensive, independent AI development toolkit that covers the
 - Documentation-only changes
 - Test additions for existing code
 
+The fast path skips artifact generation because these changes don't introduce new concepts that future sessions need to understand.
+
 For fast-path changes, you can directly use the implement command with inline task description, then the commit command.
-- CodeBuddy: `prizmkit.implement` → `prizmkit.commit`
-- Claude Code: `/prizmkit-implement` → `/prizmkit-committer`
+
+## Workflow Example
+
+**Full workflow** for adding a user avatar upload feature:
+```
+/prizmkit-specify    → writes .prizmkit/specs/001-avatar-upload/spec.md
+/prizmkit-plan       → writes plan.md with tasks (architecture, data model, API, UI)
+/prizmkit-analyze    → checks spec↔plan consistency, finds gaps
+/prizmkit-implement  → executes tasks in order, marks [x] as done
+/prizmkit-code-review → reviews against spec, outputs PASS/NEEDS FIXES
+/prizmkit-committer  → updates .prizm-docs/, commits feat(avatar): add upload
+```
+
+**Fast path** for fixing a null pointer bug:
+```
+/prizmkit-implement  → "fix null check in UserService.getAvatar()"
+/prizmkit-committer  → commits fix(user): handle null avatar gracefully
+```
+
+### Fast Path Commands
+ `/prizmkit-implement` → `/prizmkit-committer`
 
 ### Bug Fix Documentation Policy
 
 **Bug fixes MUST NOT create new documentation entries.** Bug fixes are refinements of incomplete existing features — they complete what was already planned, not introduce new functionality. Specifically:
 
-- Do NOT run `prizmkit.summarize` for bug fix commits (no new REGISTRY.md entries)
+- Run `/prizmkit-retrospective` with structural sync only (Job 1) for bug fix commits — skip knowledge injection unless genuinely new TRAP discovered
 - Do NOT create new spec/plan/tasks under `.prizmkit/specs/` for bug fixes
 - Do NOT update `.prizm-docs/` module docs for pure bug fixes (no interface/dependency change)
 - Bug fix commits use `fix(<scope>):` prefix in Conventional Commits, not `feat:`
@@ -53,7 +76,7 @@ PrizmKit produces two complementary knowledge layers:
 
 ```
 .prizm-docs/           → Project "what is" (static: structure, interfaces, rules, traps, decisions)
-.prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → tasks → code)
+.prizmkit/specs/       → Feature "what to do" (workflow: spec → plan → code(implement))
 ```
 
 ## Skill Inventory
@@ -61,18 +84,17 @@ PrizmKit produces two complementary knowledge layers:
 ### Foundation (3)
 - **prizm-kit** — Full-lifecycle dev toolkit entry point
 - **prizmkit-init** — Project takeover: scan → assess → generate docs → initialize
-- **prizmkit-prizm-docs** — Prizm documentation framework: `prizmkit.doc.init`, `prizmkit.doc.update`, `prizmkit.doc.status`, `prizmkit.doc.rebuild`, `prizmkit.doc.validate`, `prizmkit.doc.migrate`
+- **prizmkit-prizm-docs** — Prizm documentation framework with 6 operations: init, update, status, rebuild, validate, migrate
 
-### Spec-Driven Workflow (9)
+### Spec-Driven Workflow (8)
 - **prizmkit-specify** — Create structured feature specifications from natural language
 - **prizmkit-clarify** — Interactive requirement clarification
 - **prizmkit-plan** — Generate technical plan with data model, API contracts, and executable task breakdown (all in one plan.md)
 - **prizmkit-analyze** — Cross-document consistency analysis (spec ↔ plan ↔ tasks)
 - **prizmkit-implement** — Execute tasks following TDD approach
 - **prizmkit-code-review** — Review code against spec and plan
-- **prizmkit-summarize** — Archive completed features to REGISTRY.md
-- **prizmkit-committer** — Commit workflow with automatic Prizm doc update
-- **prizmkit-retrospective** — Post-feature learning: extract lessons → update Prizm docs
+- **prizmkit-retrospective** — Sole .prizm-docs/ maintainer: structural sync + knowledge injection (TRAPS/RULES/DECISIONS)
+- **prizmkit-committer** — Pure git commit: diff analysis, safety checks, Conventional Commits
 
 ### Quality Assurance (5)
 - **prizmkit-tool-tech-debt-tracker** — [Tier 1] Technical debt identification and tracking via code pattern analysis
@@ -96,13 +118,29 @@ PrizmKit produces two complementary knowledge layers:
 - **prizmkit-tool-onboarding-generator** — [Tier 2] Generate developer onboarding guides
 - **prizmkit-tool-api-doc-generator** — [Tier 2] Extract API documentation from source code
 
-### Pipeline & Companion (6)
-- **feature-workflow** — [Tier 1] End-to-end feature workflow: specify → plan → analyze → implement → review → commit
-- **refactor-workflow** — [Tier 1] End-to-end refactor workflow: analyze → plan → implement → review → commit
+### Pipeline & Companion (7)
+- **feature-workflow** — One-stop feature development: plan → launch pipeline → monitor
+- **refactor-workflow** — End-to-end refactor: analyze → plan → implement → review → commit
 - **app-planner** — Interactive app planning that produces feature-list.json for dev-pipeline
 - **bug-planner** — Interactive bug planning that produces bug-fix-list.json for bugfix-pipeline
-- **dev-pipeline-launcher** — Launch and manage the dev-pipeline from within a CLI session
-- **bugfix-pipeline-launcher** — Launch and manage the bugfix pipeline from within a CLI session
+- **bug-fix-workflow** — Interactive single-bug fix in current session (triage → reproduce → fix → review → commit)
+- **dev-pipeline-launcher** — Launch and manage the feature dev-pipeline (background daemon)
+- **bugfix-pipeline-launcher** — Launch and manage the bugfix pipeline (background daemon)
+
+### Scenario Decision Tree
+
+Not sure which skill to use? Follow this:
+
+| I want to... | Use this |
+|---|---|
+| Build a new app or batch of features from scratch | `feature-workflow` (one-stop) |
+| Plan features first, then decide when to build | `app-planner` → `dev-pipeline-launcher` |
+| Launch pipeline for an existing feature-list.json | `dev-pipeline-launcher` |
+| Fix multiple bugs in batch | `bug-planner` → `bugfix-pipeline-launcher` |
+| Fix one specific bug right now, interactively | `bug-fix-workflow` |
+| Refactor/restructure code without changing behavior | `refactor-workflow` |
+| Add a single small feature (spec → plan → implement) | `/prizmkit-specify` → `/prizmkit-plan` → `/prizmkit-implement` |
+| Quick bug fix or config change | Fast path: `/prizmkit-implement` → `/prizmkit-committer` |
 
 ### Tier Definitions
 
@@ -128,10 +166,8 @@ python3 ${SKILL_DIR}/scripts/install-prizmkit.py --target <project-skills-dir>
 
 ## Hook / Rules Configuration
 
-**CodeBuddy:** Uses native `type: prompt` hooks for automatic doc updates before commits.
-The hook is configured automatically by `prizmkit-init`. See `assets/hooks/prizm-commit-hook.json`.
-
-**Claude Code:** Uses `.claude/rules/` glob-scoped markdown files for automatic enforcement.
-Rules are created automatically by `prizmkit-init` (or `/prizmkit-init`). See:
-- `assets/claude-md-template.md` for the project memory template
+Both CodeBuddy and Claude Code use unified commands for automatic doc updates and commit enforcement.
+Hooks and rules are configured automatically by `prizmkit-init`. See:
+- `core/templates/hooks/commit-intent.json` for the commit hook template
+- `assets/project-memory-template.md` for the project memory template
 - The init skill creates `prizm-documentation.md` and `prizm-commit-workflow.md` rules

package/bundled/skills/prizm-kit/assets/{claude-md-template.md → project-memory-template.md}

@@ -10,8 +10,8 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 
 ### Auto-Update Protocol
 - BEFORE EVERY COMMIT: Update affected `.prizm-docs/` files
-- The `.claude/rules/` files will enforce this automatically
-- Use `/prizmkit-committer` command for the complete commit workflow
+- Platform hooks (rules or UserPromptSubmit) will remind you automatically
+- Use `/prizmkit-committer` for the complete commit workflow
 
 ### Doc Format Rules
 - All `.prizm` files use KEY: value format, not prose