prizmkit 1.0.45 → 1.0.58

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-analyze"
-description: "Cross-document consistency analysis for spec.md, plan.md, and tasks.md. Detects duplications, ambiguities, gaps, and rule conflicts. Read-only. (project)"
+description: "Cross-document consistency analysis for spec.md, plan.md, and tasks.md. Detects duplications, ambiguities, gaps, and rule conflicts. Read-only. Use this skill to check if spec and plan are aligned, validate documents before coding, or as a quality gate after planning. Trigger on: 'analyze', 'check consistency', 'validate spec', 'review plan', 'is the spec ready', 'check if spec and plan are aligned', 'validate documents before coding'. (project)"
 ---
 
 # PrizmKit Analyze
@@ -8,23 +8,17 @@ description: "Cross-document consistency analysis for spec.md, plan.md, and task
 Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md before implementation. Identifies duplications, ambiguities, underspecified items, rule conflicts, and coverage gaps.
 
 ### When to Use
-- After `prizmkit.plan` to validate spec-plan-tasks alignment before implementation
+- After `/prizmkit-plan` to validate spec-plan-tasks alignment before implementation
 - User says "analyze", "check consistency", "validate spec", "review plan"
-- Before `prizmkit.implement` as a quality gate
-
-## Commands
-
-### prizmkit.analyze
-
-Cross-document consistency analysis.
+- Before `/prizmkit-implement` as a quality gate
 
 **PRECONDITION:** `spec.md` and `plan.md` exist in `.prizmkit/specs/###-feature-name/`. `plan.md` must include a Tasks section.
 
 ## Operating Constraints
 
-**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report to conversation only. Offer an optional remediation plan (user must explicitly approve before any edits).
+**Read-only analysis**: Do not modify any files. The analysis output goes to conversation only, with an optional remediation plan the user must explicitly approve. This separation matters because the user needs to understand what's wrong before deciding what to change — auto-fixing consistency issues often introduces new ones.
 
-**Prizm Rules Authority**: The project rules in `.prizm-docs/root.prizm` RULES section are **non-negotiable** within this analysis scope. Rule conflicts are automatically CRITICAL severity and require adjustment of the spec, plan, or tasks — not dilution or silent ignoring of the rule. If a rule itself needs to change, that must occur via a separate `prizmkit.doc.update`.
+**Prizm Rules take precedence**: The project rules in `.prizm-docs/root.prizm` RULES section are the source of truth. If a spec or plan element conflicts with a MUST/NEVER directive, the spec/plan needs to change, not the rule. This prevents well-intentioned features from silently violating project-wide constraints. If a rule itself is wrong, that's a separate conversation via prizmkit-prizm-docs (Update operation).
 
 ## Execution Steps
 
@@ -37,7 +31,7 @@ Derive absolute paths:
 - PLAN = `.prizmkit/specs/###-feature-name/plan.md`
 - TASKS = `.prizmkit/specs/###-feature-name/tasks.md` (optional)
 
-Abort with an error message if spec.md or plan.md is missing — instruct the user to run the missing prerequisite command (`prizmkit.specify` or `prizmkit.plan`).
+Abort with an error message if spec.md or plan.md is missing — instruct the user to run the missing prerequisite command (`/prizmkit-specify` or `/prizmkit-plan`).
 
 ### Step 2: Load Artifacts (Progressive Disclosure)
 
@@ -152,13 +146,13 @@ Output a Markdown report (**no file writes**) with the following structure:
 
 At end of report, output a concise Next Actions block:
 
-- If CRITICAL issues exist: **Recommend resolving before `prizmkit.implement`**
+- If CRITICAL issues exist: **Recommend resolving before `/prizmkit-implement`**
 - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
 - Provide explicit command suggestions:
-  - "Run `prizmkit.specify` to refine requirements"
-  - "Run `prizmkit.plan` to adjust architecture or tasks"
+  - "Run `/prizmkit-specify` to refine requirements"
+  - "Run `/prizmkit-plan` to adjust architecture or tasks"
   - "Edit tasks.md to add coverage for requirement X"
-  - "Proceed to `prizmkit.implement`" (if clean)
+  - "Proceed to `/prizmkit-implement`" (if clean)
 
 ### Step 8: Offer Remediation
 
@@ -167,19 +161,37 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t
 ## Operating Principles
 
 ### Context Efficiency
-- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
-- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
-- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
-- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
-
-### Analysis Guidelines
-- **NEVER modify files** (this is read-only analysis)
-- **NEVER hallucinate missing sections** (if absent, report them accurately)
-- **Prioritize Prizm Rules violations** (these are always CRITICAL)
-- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
-- **Report zero issues gracefully** (emit success report with coverage statistics)
-
-**HANDOFF:** `prizmkit.implement` (if clean) or `prizmkit.specify` / `prizmkit.plan` (if issues found)
+- Focus on actionable findings, not exhaustive documentation — the goal is to surface problems, not prove you read everything
+- Load artifacts incrementally; reading all content upfront wastes tokens on sections irrelevant to the feature
+- Cap findings at 50 rows to keep the report scannable; summarize overflow with counts
+- Rerunning without changes should produce consistent IDs and counts (deterministic)
+
+### Analysis Approach
+- Do not modify files — read-only analysis ensures artifacts remain stable for the implement phase
+- If a section is absent, report it accurately rather than guessing what it might contain
+- Prizm Rules violations are always CRITICAL — they represent project-wide constraints that outrank individual feature decisions
+- Cite specific instances rather than generic patterns — "spec §2.1 says REST but plan §Architecture says GraphQL" is more useful than "terminology inconsistency found"
+- If zero issues found, report success with coverage statistics — a clean report is valuable confirmation
+
+## Example Finding
+
+```
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| D1 | Rules Alignment | CRITICAL | plan.md §Architecture | Plan specifies SQLite but root.prizm RULES has "MUST: use PostgreSQL for all persistent storage" | Change plan to use PostgreSQL or request rule amendment via prizmkit-prizm-docs |
+| E1 | Coverage Gap | HIGH | spec.md §FR-3 | "User can export reports as PDF" has no corresponding task in plan.md Tasks section | Add export task to Phase 3 of plan.md |
+```
+
+**HANDOFF:** `/prizmkit-implement` (if clean) or `/prizmkit-specify` / `/prizmkit-plan` (if issues found)
+
+## Loop Protection
+
+In unattended pipeline mode, the analyze→fix→analyze cycle can loop indefinitely if issues keep reappearing. To prevent this:
+
+- Track an `analyze_iteration` counter starting at 1. Each re-run of this skill after remediation increments the counter.
+- **max_iterations = 5**: If `analyze_iteration >= 5`, you MUST proceed to `/prizmkit-implement` regardless of remaining findings. Log a warning: "Loop protection triggered — proceeding to implement with N unresolved findings (iterations: 5/5)."
+- Unresolved findings from the final iteration should be noted in the handoff so that `/prizmkit-code-review` can catch them downstream.
+- This guard exists because some findings oscillate (fixing one re-introduces another) and blocking forever is worse than proceeding with known issues.
 
 ## Output
 

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

@@ -1,51 +1,61 @@
 ---
 name: "prizmkit-clarify"
-description: "Interactive requirement clarification. Resolves ambiguities in feature specs by asking sequential questions. Invoke after 'specify' or when spec has NEEDS CLARIFICATION markers. (project)"
+description: "Interactive requirement clarification. Resolves ambiguities in feature specs by asking sequential questions with recommended answers. Use when spec has unclear parts or you're unsure about requirements before planning. Use this skill whenever a spec has [NEEDS CLARIFICATION] markers, vague requirements, or the user wants to refine their feature definition before planning. Trigger on: 'clarify', 'refine spec', 'resolve ambiguities', 'spec has questions', 'unsure about requirements', 'spec is unclear'. (project)"
 ---
 
 # PrizmKit Clarify
 
 Interactive requirement clarification that resolves ambiguities in feature specifications. Asks focused questions one at a time, updating the spec atomically after each answer.
 
-## Commands
-
-### prizmkit.clarify
-
-Resolve ambiguities and underspecified areas in a feature specification.
+### When to Use
+- After `/prizmkit-specify` when spec has `[NEEDS CLARIFICATION]` markers
+- User says "clarify", "resolve ambiguities", "refine spec"
+- Before `/prizmkit-plan` to ensure spec is unambiguous
 
 **PRECONDITION:** `spec.md` exists in current feature directory (`.prizmkit/specs/###-feature-name/`)
 
-**STEPS:**
+## Execution Steps
 
 1. Read `spec.md` from `.prizmkit/specs/###-feature-name/`
 2. Scan for `[NEEDS CLARIFICATION]` markers and underspecified areas
-3. Categorize ambiguities by dimension:
-   - Functional scope
-   - Data model
-   - UX flow
-   - Non-functional requirements
-   - Error handling
-   - Edge cases
-   - Integration points
-   - Security
-   - Performance
-   - Accessibility
-4. Ask questions ONE AT A TIME (not all at once), max 5 questions
-5. For each question: provide a recommended answer with rationale
-6. After each answer: immediately update `spec.md` atomically (not batch)
-7. Support early termination: user says "done" or "stop"
+3. Categorize ambiguities by dimension and prioritize — address the ones that would most affect architecture and data model first, since those are hardest to change later:
+   - Functional scope (what does it do?)
+   - Data model (what entities, relationships?)
+   - UX flow (what does the user see?)
+   - Error handling (what happens when things fail?)
+   - Non-functional requirements (performance, security)
+   - Edge cases, integration points, accessibility
+4. Ask questions one at a time (max 5 per session) — batch questions overwhelm users and produce lower-quality answers because they rush through without thinking deeply about each one
+5. For each question: provide a recommended answer with rationale. The recommendation gives users a concrete starting point to accept, modify, or reject — this is much faster than open-ended questions
+6. After each answer: immediately update `spec.md` (not batched at the end). Atomic updates mean the spec is always in a consistent state, even if the session is interrupted
+7. Support early termination: user says "done" or "stop" — end immediately
 8. Remove resolved `[NEEDS CLARIFICATION]` markers
 9. After all questions resolved or user terminates: output summary of changes made
 
-**KEY RULES:**
-- NEVER ask all questions at once — sequential, one at a time
-- ALWAYS provide a recommended answer with rationale for each question
-- Updates to `spec.md` MUST be atomic (after each answer, not batched)
-- Max 5 questions per session
-- Respect early termination — "done" or "stop" ends the session immediately
-- Do NOT introduce implementation details — keep spec at WHAT/WHY level
+## Example Session
+
+**Question 1:**
+> spec.md §3.2 says "User can upload files" but doesn't specify which file types or size limits.
+>
+> **Recommended answer:** Accept JPEG, PNG, and PDF up to 10MB. These are the most common user upload types, and 10MB covers high-res photos without straining storage.
+>
+> Do you agree, or would you like different constraints?
+
+**User:** "Also allow SVG, and make it 25MB"
+
+**Action:** Update spec.md §3.2:
+```
+File upload: accepts JPEG, PNG, PDF, SVG. Max size: 25MB per file.
+```
+Remove `[NEEDS CLARIFICATION]` marker from §3.2.
+
+## Guidelines
+
+- Keep questions at the WHAT/WHY level — do not introduce implementation details (HOW). The spec describes the problem space; implementation choices belong in plan.md
+- 5-question limit per session keeps clarification focused. If more questions remain, tell the user and suggest running clarify again after they've had time to think
+- If the user's answer contradicts an existing requirement, point out the conflict and ask which one should change
 
-**HANDOFF:** `prizmkit.plan`
+**HANDOFF:** `/prizmkit-plan`
 
 ## Output
 

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

@@ -1,70 +1,75 @@
 ---
 name: "prizmkit-code-review"
-description: "Code review against spec, plan, and best practices. Read-only analysis with severity ratings. Invoke after implementation or when user requests review. (project)"
+description: "Code review against spec, plan, and best practices. Read-only analysis with severity ratings. Use this skill after implementation to catch spec compliance gaps, security issues, and pattern violations before committing. Trigger on: 'review', 'check code', 'review my implementation', 'code review', 'is it ready to commit'. (project)"
 ---
 
 # PrizmKit Code Review
 
-Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. Produces a structured review report with severity ratings. This skill is strictly read-only and does not modify any files.
+Perform a comprehensive code review against the feature spec, implementation plan, and project best practices. Produces a structured review report with severity ratings. This skill is strictly read-only — it surfaces issues without auto-fixing them, so you can decide what actually needs changing.
 
-## Commands
-
-### prizmkit.code-review
-
-Review implemented code against spec and plan.
+### When to Use
+- After `/prizmkit-implement` to verify code quality before commit
+- User says "review", "check code", "review my implementation"
+- As a quality gate before `/prizmkit-committer`
 
 **PRECONDITION:** `spec.md`, `plan.md`, `tasks.md` exist in `.prizmkit/specs/###-feature-name/` with completed tasks
 
-**STEPS:**
+## Execution Steps
 
 1. Read `spec.md`, `plan.md`, `tasks.md` as review baseline
 2. Read `.prizm-docs/root.prizm` RULES for project conventions
 3. Scan all code files referenced in completed tasks
 4. Review across 6 dimensions:
-   - **Spec compliance**: Does code implement all acceptance criteria?
-   - **Plan adherence**: Does implementation follow architectural decisions?
-   - **Code quality**: Naming, structure, complexity, DRY
-   - **Security**: Common vulnerabilities (injection, auth, data exposure)
-   - **Consistency**: Follows project patterns from `.prizm-docs/` PATTERNS
-   - **Test coverage**: Are critical paths tested?
+   - **Spec compliance**: Does code implement all acceptance criteria? Missing criteria are the #1 source of "it works but it's wrong" bugs
+   - **Plan adherence**: Does implementation follow architectural decisions in plan.md? Deviations may be improvements or may break assumptions other components depend on
+   - **Code quality**: Naming, structure, complexity, DRY. Focus on maintainability — will someone understand this code in 6 months?
+   - **Security**: Injection (SQL, XSS, command), auth/authz gaps, sensitive data exposure, insecure defaults. Security issues are always HIGH+ because they're the hardest to catch later
+   - **Consistency**: Follows project patterns from `.prizm-docs/` PATTERNS section. Inconsistent patterns increase cognitive load for every future reader
+   - **Test coverage**: Are critical paths tested? Focus on paths that handle user input, money, or state transitions
 5. Generate findings with severity: `CRITICAL` > `HIGH` > `MEDIUM` > `LOW`
-6. Max 30 findings
-7. Verdict: `PASS` | `PASS WITH WARNINGS` | `NEEDS FIXES`
-8. OUTPUT: Structured review report (to conversation only, NOT written to file)
-
-**KEY RULES:**
-- This is STRICTLY READ-ONLY — does NOT modify any files
-- Output goes to conversation ONLY, not to any file
-- Max 30 findings to keep review actionable
-- Every CRITICAL finding MUST include a specific fix suggestion
-- Spec compliance failures are always rated HIGH or CRITICAL
-- Security findings are always rated HIGH or CRITICAL
-
-**VERDICT CRITERIA:**
+6. Determine verdict (see criteria below)
+7. Output structured review report to conversation only
+
+## Severity & Verdict
+
+Spec compliance failures are always HIGH or CRITICAL — if the code doesn't match what was agreed in the spec, that's a functional gap, not a style issue. Security findings follow the same rule.
+
+**Verdict criteria:**
 - `PASS`: No CRITICAL or HIGH findings
 - `PASS WITH WARNINGS`: No CRITICAL findings, some HIGH findings
 - `NEEDS FIXES`: Any CRITICAL findings present
 
-**HANDOFF:** `prizmkit.summarize` (if PASS) or `prizmkit.implement` (if NEEDS FIXES)
+Cap findings at 30 to keep the review actionable. If there are more, summarize the overflow with counts by dimension. Every CRITICAL finding includes a specific fix suggestion — telling someone "this is broken" without saying how to fix it wastes their time.
 
-## Output
+If you're unsure whether something is a bug or intentional design, flag it as MEDIUM with a note asking the developer to confirm. Don't silently skip uncertain findings.
 
-Review report is output to conversation only. No files are created or modified.
+## Example Finding
 
-**Report Format:**
 ```
-## Code Review: [Feature Name]
+#### [CRITICAL] SQL Injection in User Search
+- File: src/services/userService.ts:47
+- Dimension: security
+- Description: User input `searchTerm` is interpolated directly into SQL query string without parameterization
+- Suggestion: Use parameterized query: `db.query('SELECT * FROM users WHERE name LIKE $1', [`%${searchTerm}%`])`
+
+#### [HIGH] Missing Acceptance Criterion
+- File: src/routes/upload.ts
+- Dimension: spec-compliance
+- Description: spec.md §AC-3 requires "display progress bar during upload" but no progress tracking is implemented
+- Suggestion: Add upload progress callback using xhr.upload.onprogress or fetch with ReadableStream
+```
 
-### Summary
-- Files reviewed: N
-- Findings: N (Critical: N, High: N, Medium: N, Low: N)
-- Verdict: [PASS | PASS WITH WARNINGS | NEEDS FIXES]
+**HANDOFF:** `/prizmkit-retrospective` (if PASS) or `/prizmkit-implement` (if NEEDS FIXES)
 
-### Findings
+## Loop Protection
 
-#### [SEVERITY] Finding Title
-- File: path/to/file:line
-- Dimension: [spec-compliance | plan-adherence | code-quality | security | consistency | test-coverage]
-- Description: [What was found]
-- Suggestion: [How to fix]
-```
+In unattended pipeline mode, the review→fix→review cycle can loop indefinitely if fixes introduce new issues. To prevent this:
+
+- Track a `review_iteration` counter starting at 1. Each review-fix-review cycle increments the counter.
+- **max_iterations = 5**: If `review_iteration >= 5`, you MUST proceed to `/prizmkit-retrospective` regardless of remaining findings. Log remaining issues as known technical debt: "Loop protection triggered — proceeding to retrospective with N unresolved findings (iterations: 5/5)."
+- Unresolved findings should be recorded in the review report so they can be tracked as follow-up work.
+- This guard exists because some review cycles oscillate (fixing one issue introduces another) and blocking forever is worse than shipping with documented known issues.
+
+## Output
+
+Review report is output to conversation only. No files are created or modified.

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

@@ -1,17 +1,18 @@
 ---
 name: "prizmkit-committer"
-description: "Commit workflow with automatic Prizm doc updates, changelog management, and learning capture. Invoke when user wants to commit, finish task, or ship changes. (project)"
+description: "Pure git commit workflow with safety checks. Stages files, analyzes diff, generates Conventional Commits message, and commits. Does NOT modify .prizm-docs/ — memory maintenance is handled by /prizmkit-retrospective before this skill is invoked. Trigger on: 'commit', '提交', 'finish', 'done', 'ship it', 'save my work'. (project)"
 ---
 
 # PrizmKit Committer
 
-Automated commit workflow that keeps Prizm documentation in sync, manages changelog entries, and captures learnings from each commit.
+Pure git commit workflow. Analyzes changes, generates a Conventional Commits message, performs safety checks, and commits.
+
+**This skill does NOT modify any project files.** It only reads and commits. All documentation and memory maintenance must be completed before invoking this skill (via `/prizmkit-retrospective`).
 
 ### When to Use
 - User says "commit", "提交", "finish", "done with this task", "ship it"
-- After implementing a feature or fixing a bug
-- CodeBuddy: the UserPromptSubmit hook will remind to use this skill
-- Claude Code: the `.claude/rules/prizm-commit-workflow.md` rule will enforce this
+- After `/prizmkit-retrospective` has finished memory maintenance
+- The UserPromptSubmit hook will remind to use this skill when commit intent is detected
 
 ### Workflow
 
@@ -24,53 +25,7 @@ git status
 - If "nothing to commit, working tree clean": inform user and stop
 - If there are changes: proceed
 
-#### Step 2: Prizm Documentation Update (CRITICAL — must complete before commit)
-
-2a. Get changed files:
-```bash
-git diff --cached --name-status
-```
-If nothing staged, also check:
-```bash
-git diff --name-status
-```
-
-2b. Read .prizm-docs/root.prizm to get MODULE_INDEX
-
-2c. Map each changed file to its module using MODULE_INDEX paths
-
-2d. For each affected module:
-- IF L2 doc exists (.prizm-docs/<module>/<submodule>.prizm):
-  - Update KEY_FILES (add new files, remove deleted, note modified)
-  - Update INTERFACES (if public signatures changed)
-  - Update DEPENDENCIES (if imports changed)
-  - Append to module CHANGELOG section
-  - Update UPDATED timestamp
-- IF L1 doc exists (.prizm-docs/<module>.prizm):
-  - Update FILES count
-  - Update KEY_FILES (if major files added/removed)
-  - Update UPDATED timestamp
-- Update root.prizm:
-  - Update MODULE_INDEX file counts (only if counts changed)
-  - UPDATED timestamp (only if structural changes)
-
-2e. Append to .prizm-docs/changelog.prizm:
-Format: `- YYYY-MM-DD | <module-path> | <verb>: <one-line description>`
-Verbs: add, update, fix, remove, refactor, rename, deprecate
-
-2f. Stage prizm docs:
-```bash
-git add .prizm-docs/
-```
-
-SKIP CONDITIONS for doc update:
-- Only internal implementation changed (no interface/dependency change)
-- Only comments, whitespace, or formatting changed
-- Only test files changed
-- Only .prizm files changed (avoid circular updates)
-- Bug fixes to existing features (bugs are incomplete features being refined, not new functionality — no new doc entries needed)
-
-#### Step 3: Diff Analysis
+#### Step 2: Diff Analysis
 ```bash
 git diff HEAD
 ```
@@ -79,16 +34,12 @@ Analyze:
 - Scope: affected module name
 - Description: imperative mood summary
 
-#### Step 4: Update CHANGELOG.md
-If CHANGELOG.md exists, append entry following Keep a Changelog format.
-If manage_changelog.py exists in skill scripts:
-```bash
-python3 ${SKILL_DIR}/scripts/manage_changelog.py add --type <type> --message "<description>"
-```
+#### Step 3: Update CHANGELOG.md
+If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
 
-#### Step 5: Git Commit
+#### Step 4: Git Commit
 
-5a. Safety check before staging:
+4a. Safety check before staging:
 ```bash
 git diff --name-only
 git ls-files --others --exclude-standard
@@ -99,18 +50,18 @@ Review the output for sensitive files. If any file matches these patterns, **STO
 - `credentials.*`, `*secret*`
 - `*.sqlite`, `*.db` (database files)
 
-5b. Stage and commit:
+4b. Stage and commit:
 ```bash
-git add -A
+git add <specific-files>
 git diff --cached --name-only
 ```
-Review staged file list one final time, then:
+Stage files explicitly by name rather than using `git add -A`, which can accidentally include sensitive files or large binaries that appeared between the safety check and staging. Review staged file list one final time, then:
 ```bash
 git commit -m "<type>(<scope>): <description>"
 ```
 Follow Conventional Commits format.
 
-#### Step 6: Verification
+#### Step 5: Verification
 ```bash
 git log -1 --stat
 ```
@@ -121,9 +72,9 @@ Then verify working tree is clean:
 git status
 ```
 - If "nothing to commit, working tree clean": commit verified successfully, proceed
-- If there are uncommitted changes remaining: **STOP** and report error — all changes must be captured in the commit. Run `git add -A && git commit --amend --no-edit` to include missed files, then re-verify
+- If there are uncommitted changes remaining: **STOP** and report what files were missed. Stage the missed files explicitly by name and create a new commit (do NOT amend the previous commit — amending risks destroying unrelated changes from prior commits)
 
-#### Step 7: Optional Push
+#### Step 6: Optional Push
 Ask user: "Push to remote?"
 - Yes: `git push`
 - No: Stop
@@ -131,5 +82,16 @@ Ask user: "Push to remote?"
 ### Error Handling
 - If git diff is empty but untracked files exist: run `git add -N .` first (respects .gitignore)
 - If CHANGELOG.md script fails: update manually or ask user
-- If .prizm-docs/ doesn't exist: skip Step 2 entirely (project not initialized)
-- If sensitive files are detected during Step 5a safety check: warn user and do NOT stage them automatically
+- If sensitive files are detected during Step 4a safety check: warn user and do NOT stage them automatically
+
+## Example
+
+**Feature commit:**
+```
+git commit -m "feat(avatar): add user avatar upload with S3 storage"
+```
+
+**Bug fix commit:**
+```
+git commit -m "fix(auth): handle null token in refresh flow"
+```

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

@@ -1,46 +1,68 @@
 ---
 name: "prizmkit-implement"
-description: "Execute implementation following tasks.md. Respects task ordering, dependencies, and TDD approach. Marks tasks complete as they finish. Invoke with 'implement' or 'build'. (project)"
+description: "Execute implementation following plan.md tasks. Respects task ordering, dependencies, and TDD approach. Marks tasks complete as they finish. Use this skill whenever you're ready to write code for a planned feature, or for fast-path changes where the user describes a simple fix directly. Trigger on: 'implement', 'build', 'code it', 'start coding', '开发', 'write the code'. (project)"
 ---
 
 # PrizmKit Implement
 
-Execute implementation by following the task breakdown in tasks.md. Respects task ordering, dependency constraints, and applies a TDD approach where applicable. Marks each task complete as it finishes.
+Execute implementation by following the task breakdown in plan.md. Respects task ordering, dependency constraints, and applies a TDD approach where applicable. Marks each task complete as it finishes.
 
-## Commands
-
-### prizmkit.implement
-
-Implement the feature by executing tasks from tasks.md.
+### When to Use
+- After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
+- User says "implement", "build", "code it", "start coding", "开发"
+- For fast-path: user describes a simple change directly (skip specify/plan)
 
 **PRECONDITION:** `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
 
-**STEPS:**
+## Execution Steps
 
 1. Read `plan.md` (including Tasks section), `spec.md` for full context
-2. Load project context (use first available source):
-   - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read it (Section 3 has Prizm docs + TRAPS, Section 4 has source files). Do NOT re-read `.prizm-docs/` or individual source files.
-   - Otherwise → read relevant `.prizm-docs/` L1/L2 for affected modules (check TRAPS and DECISIONS sections)
+2. Load project context — use the most efficient source available:
+   - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS, Section 4 has source files. This snapshot was built in Phase 1 of the pipeline to avoid re-reading dozens of individual files, saving significant tokens.
+   - Otherwise → read relevant `.prizm-docs/` L1/L2 for affected modules. Pay special attention to TRAPS (gotchas, race conditions) and DECISIONS (past architectural choices you should respect).
 3. Check if checkpoint tasks are complete before proceeding to next phase
 4. For each unchecked task in order:
-   a. If task has `[P]` marker and previous parallel tasks are running, can proceed in parallel
-   b. Read L2 doc for target file's module (if exists)
-   c. Implement following TDD: write test first if applicable
-   d. Mark task as `[x]` in `plan.md` Tasks section
-   e. If error occurs: for sequential tasks, stop and report; for parallel tasks, continue others
-5. At each checkpoint: verify build passes and tests pass
+   a. If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group
+   b. Read L2 doc for target file's module (if exists) — TRAPS save you from repeating known mistakes
+   c. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
+   d. Mark task as `[x]` in `plan.md` Tasks section immediately — not batched at the end. Immediate marking means the plan always reflects true progress, even if the session is interrupted.
+   e. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
+5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
 6. After all tasks: run full test suite
-7. Output: implementation summary with pass/fail status
+7. Output implementation summary with pass/fail status
+
+## Task Format in plan.md
+
+Tasks in plan.md look like this:
+```markdown
+## Tasks
+
+### Phase 1: Data Layer
+- [ ] Create User model with avatar field in src/models/user.ts
+- [ ] Add S3 upload utility in src/lib/s3.ts
+- [x] ~~Set up database migration~~ (already done)
+
+### Phase 2: API [P]
+- [ ] [P] POST /api/avatar endpoint in src/routes/avatar.ts
+- [ ] [P] DELETE /api/avatar endpoint in src/routes/avatar.ts
+
+### Phase 3: UI
+- [ ] Avatar upload component in src/components/AvatarUpload.tsx
+- [ ] CP: Integration checkpoint — full test suite must pass
+```
+
+- `[ ]` / `[x]` — unchecked / completed
+- `[P]` — can run in parallel with other `[P]` tasks in the same phase
+- `CP:` — checkpoint where build + tests must pass before continuing
+
+## Recovery
 
-**KEY RULES:**
-- NEVER skip a checkpoint — build and tests MUST pass before proceeding to next phase
-- Sequential tasks MUST execute in order — stop on failure
-- Parallel tasks (`[P]` marker) MAY continue if one fails, but report all failures
-- TDD approach: write test first, then implement, then verify test passes
-- Read TRAPS before implementing: prefer `context-snapshot.md` Section 3 (if exists), otherwise `.prizm-docs/` TRAPS section
-- Mark each task `[x]` in `plan.md` Tasks section immediately upon completion (not batched)
+If a session is interrupted mid-implementation:
+- Completed tasks are already marked `[x]` in plan.md (because we mark immediately)
+- Resume by re-running `/prizmkit-implement` — it picks up from the first unchecked task
+- context-snapshot.md persists across sessions for consistent context
 
-**HANDOFF:** `prizmkit.code-review`
+**HANDOFF:** `/prizmkit-code-review`
 
 ## Output