prizmkit 1.0.45 → 1.0.66

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,83 @@
 ---
 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
+### 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`
 
-### prizmkit.code-review
+**PRECONDITION (multi-mode):**
+- **Feature mode**: `spec.md` and `plan.md` (with Tasks section) exist in `.prizmkit/specs/###-feature-name/` with completed tasks
+- **Refactor mode**: `refactor-analysis.md` and `plan.md` (with Tasks section) exist in `.prizmkit/refactor/<refactor-slug>/` with completed tasks. No `spec.md` is needed — review against `refactor-analysis.md` goals and behavior preservation instead.
+- **Bugfix mode**: `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with completed tasks. Review against the bug description and reproduction test.
+- **Auto-detect**: Check which artifact directory was passed by the calling workflow, or scan `.prizmkit/` for the most recently modified feature/refactor/bugfix directory.
 
-Review implemented code against spec and plan.
+## Execution Steps
 
-**PRECONDITION:** `spec.md`, `plan.md`, `tasks.md` exist in `.prizmkit/specs/###-feature-name/` with completed tasks
-
-**STEPS:**
-
-1. Read `spec.md`, `plan.md`, `tasks.md` as review baseline
+1. **Detect mode and load review baseline**:
+   - If `spec.md` exists → **Feature mode**: read `spec.md` + `plan.md` as baseline. Review dimensions: spec compliance, plan adherence, code quality, security, consistency, test coverage.
+   - If `refactor-analysis.md` exists → **Refactor mode**: read `refactor-analysis.md` + `plan.md` as baseline. Review dimensions shift: replace "spec compliance" with **behavior preservation** (observable behavior unchanged), replace "plan adherence" with **structural improvement** (is the code measurably better?). Also check test integrity and code quality.
+   - If `fix-plan.md` exists → **Bugfix mode**: read `fix-plan.md` as baseline. Review dimensions: bug is actually fixed, no regressions, reproduction test passes, minimal change scope.
+   - If none found → prompt user: "No review baseline found. Which workflow are you in? (feature/refactor/bugfix)"
 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 is a pure git commit tool. It does NOT modify any project files — no `.prizm-docs/`, no source code, no documentation.** It only reads diffs, generates a commit message, and commits. For feature/refactor workflows, run `/prizmkit-retrospective` before this skill to sync `.prizm-docs/`. For bug fixes, skip retrospective entirely — bug fixes do not update `.prizm-docs/`.
 
 ### 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,78 @@
 ---
 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
+### 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 (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
-### prizmkit.implement
+**PRECONDITION (multi-mode):**
+- **Feature mode** (default): `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
+- **Refactor mode**: `plan.md` exists in `.prizmkit/refactor/<refactor-slug>/` with a Tasks section containing unchecked tasks
+- **Bugfix mode**: `plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/` with a Tasks section containing unchecked tasks
+- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
 
-Implement the feature by executing tasks from tasks.md.
+## Execution Steps
 
-**PRECONDITION:** `plan.md` exists in `.prizmkit/specs/###-feature-name/` with a Tasks section containing unchecked tasks
-
-**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)
+1. **Detect mode and read context**:
+   - Locate `plan.md` (check the artifact directory passed by the calling workflow, or auto-detect per PRECONDITION above)
+   - Read `plan.md` (including Tasks section)
+   - Read the companion input document for full context:
+     - **Feature mode**: read `spec.md` in the same directory
+     - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
+     - **Bugfix mode**: read `fix-plan.md` in the same directory
+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