prizmkit 1.1.79 → 1.1.81

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-deploy"
-description: "Universal deployment gateway for any PrizmKit project. Discovers project type and target (SSH server, Vercel, Docker, etc.), then routes: full automation for SSH Linux with PM2 + Nginx + blue/green switching, guided setup for cloud platforms, or safe documentation fallback for unsupported targets. Also operates existing deployments: status, logs, restart, rollback, health checks, history, validate. Use this skill whenever the user asks about deployment, hosting, going live, or server operations. Triggers on: 'deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'check deploy status', 'view logs', 'restart app', 'rollback', 'how do I deploy this', any deployment or hosting question."
+description: "Universal deployment gateway for any PrizmKit project. Discovers project type and target (SSH server, Vercel, Docker, etc.), then routes: full automation for SSH Linux with PM2 + Nginx + blue/green switching, guided setup for cloud platforms, or safe documentation fallback for unsupported targets. Also operates existing deployments: status, logs, restart, rollback, health checks, history, validate. Use this skill whenever the user asks about deployment, hosting, going live, or server operations. Triggers on: 'deploy', 'ship it', 'take this live', 'deploy to Vercel', 'deploy to my server', 'check deploy status', 'view logs', 'restart app', 'rollback', 'how do I deploy this', any deployment or hosting question. (project)"
 ---
 
 # PrizmKit Deploy — Universal Deployment Gateway
@@ -14,6 +14,51 @@ Three possible outcomes depending on what's supported:
 
 When invited, behave as a deployment engineer. Ask until you understand what is being deployed, where it runs, how it is built, how it starts, what secrets it needs, how traffic reaches it, and how health is checked.
 
+### When to Use
+- User says "deploy", "ship it", "take this live", "deploy to Vercel", "deploy to my server"
+- User wants to check deploy status, view logs, restart app, rollback
+- First-time deployment configuration or repair
+- Any deployment, hosting, or server operation question
+
+### When NOT to Use
+- Project has no code to deploy (empty/scaffold project)
+- Local dev environment startup — use the project's dev scripts instead
+- Purely CI/CD pipeline debugging unrelated to deployment
+- User wants to edit application code — use /prizmkit-plan and /prizmkit-implement
+
+## Data Safety Gate
+
+Before executing any command that could **irreversibly destroy, overwrite, or modify data**, pause and get explicit user confirmation. This is a hard gate — the cost of a false negative (losing real data) is catastrophic, while asking one extra question costs nothing.
+
+### Detection
+
+Before running any shell command, scan it for these patterns:
+
+| Category | Dangerous patterns | What's at risk |
+|----------|-------------------|----------------|
+| Database schema | `prisma db push --force-reset`, `prisma db push --accept-data-loss`, `prisma migrate reset`, `prisma migrate dev --create-only` | All existing data dropped, schema reset |
+| Database data | `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, `DELETE FROM` without `WHERE`, `UPDATE` without `WHERE` | Data deletion or corruption |
+| File system | `rm -rf`, `> /etc/`, overwriting existing configs without backup | Config loss, system breakage |
+| Cloud resources | `terraform destroy`, `kubectl delete`, cloud resource deletion, S3 bucket removal | Infrastructure/service loss |
+
+### Confirmation Flow
+
+When a dangerous pattern is detected:
+
+1. **Stop.** Do not execute. Do not ask "should I proceed?" while already running the command.
+2. **Explain** what the command will do and what data will be lost, in plain language.
+3. **Ask** an explicit yes/no question. Accept only a clear "yes" or equivalent — ambiguous responses ("sure, I guess", "ok go ahead") count as "no" when the consequence is data loss.
+4. **Only proceed** on unambiguous consent. If the user says anything other than a clear affirmative, abort.
+5. **Record** the confirmation decision and the command that was run in deploy history.
+
+### Headless Mode
+
+If a destructive data operation is detected in headless mode, **refuse and exit** with `DATA_SAFETY_DENIED`. Data destruction must never happen without human oversight — an unattended pipeline that runs `--force-reset` could wipe a production database with no one watching.
+
+### Examples
+
+Read `${SKILL_DIR}/references/data-safety-examples.md` for concrete few-shot examples of dangerous commands caught by this gate, including the correct and incorrect ways to handle them.
+
 ## Deployment Discovery
 
 Before doing anything else, discover what you're deploying and where. This phase routes the request to the right adapter or fallback. It runs regardless of mode (interactive or headless), but interactive mode may ask questions; headless mode reads from existing config and exits with `NEEDS_INPUT` if critical details are missing.
@@ -245,39 +290,7 @@ Write `deploy.config.json` with all collected values and `validated: {}` stubs f
 
 Before first deployment, bootstrap the server. Present a plan showing every privileged action before executing anything.
 
-**Always-run preflight:**
-```
-locale-gen en_US.UTF-8           # fix locale warnings on bare Ubuntu
-apt-get update -qq               # refresh package list
-```
-
-**Check-and-install (idempotent):** Node.js, npm, PM2, Nginx, Git. Use v22 LTS if v25 not available.
-
-**Detect port conflicts:** `ss -tlnp | grep :80 || true`. If port 80/443 is occupied, report and ask how to resolve.
-
-**User and directory setup:**
-```
-useradd -m -s /bin/bash <runtimeUser>   # if not exists
-mkdir -p /var/www/<project>/{releases,shared,deploy-logs}
-chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
-```
-
-**PM2 startup:**
-```
-env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
-```
-
-**Deploy key (Pull mode only):**
-```
-sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
-sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
-```
-
-**Security baseline (firewall):** After core tools are installed, ask whether to configure ufw. If user agrees, read `references/firewall-setup.md` for the full interactive flow and rule templates.
-
-**Database setup:** If Discovery detected database drivers, ask whether to install the database on the server. If user agrees, read `references/database-setup.md` for platform-specific setup commands and security notes.
-
-After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.
+Read `${SKILL_DIR}/references/ssh-bootstrap-flow.md` for the full bootstrap procedure (preflight, check-and-install, user/dir setup, PM2 startup, deploy key). When the bootstrap reaches firewall or database steps, it routes to `references/firewall-setup.md` and `references/database-setup.md`. Key rules: bootstrap operations must be idempotent, existing config files must be backed up before modification, and each step's result must be recorded.
 
 ### SSH: Direct Upload Deployment
 
@@ -310,37 +323,7 @@ Full procedure in `references/ssl-setup.md`.
 
 ### SSH: Deployment Execution Flow
 
-Pipeline runs in strict order. Each group must complete before the next begins. If any step before traffic switch fails, STOP — do not touch the live version.
-
-**Pre-flight — Change Summary:** Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD`. If first deployment, show last 5 commits. If no new commits, warn "没有新的代码变更。确定要重新部署吗？"
-
-**Group 1 — Pre-flight & Prepare:**
-- Verify SSH, runtime user, tools, deploy key, port availability.
-- Generate `releaseId`: `YYYYMMDD-<short-commit-sha>`. Create `releases/<releaseId>`.
-- Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
-
-**Group 2 — Fetch & Build:**
-
-- **CI/CD Pull mode** (server-side build): git clone → install → copy `.env.production` before build (NEXT_PUBLIC_* vars are baked at build time) → build. If build fails: STOP.
-- **CI/CD Push mode** (runner-side build): extract tarball, skip install/build.
-- **Direct-upload mode**: build was already done locally and SCP'd. Skip this group.
-
-**Group 3 — Stage & Health Check:**
-- Start new version on inactive port via PM2: `pm2 start npm --name <project>-<app>-<color> -- run start -- -p <inactivePort>`.
-- PM2 process naming: `<project>-<app>-<color>` (e.g., `prizm-ideas-web-green`).
-- Wait 3-5 seconds, run health checks against new port. If any fails: STOP, do NOT switch traffic.
-
-**Group 4 — Switch & Verify:**
-- Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
-- `systemctl reload nginx`. Update `current` symlink to new release.
-- Write `shared/deploy-metadata.json` with new `activeColor`, `activePort`, `lastReleaseId`.
-- Run health checks against public endpoint. If any fails: rollback immediately.
-
-**Group 5 — Cleanup & Record:**
-- Stop old PM2 process. Remove oldest releases beyond `releaseRetention` count. `pm2 save`.
-- Write deploy-history JSON. Update `deploy.config.json` validation status.
-
-**Post-deploy — Completion Summary:** Output a summary (project, URL, version, duration, health status) and append to deploy.md. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).
+Read `${SKILL_DIR}/references/ssh-execution-flow.md` for the full 5-group pipeline: pre-flight, fetch & build, stage & health check, switch & verify, cleanup & record. Key invariant: if any step before traffic switch fails, STOP — do not touch the live version.
 
 ### SSH: Blue/Green PM2 + Nginx Strategy
 
@@ -405,14 +388,7 @@ Deploy history records secret presence metadata only (e.g., `{"SUPABASE_SERVICE_
 
 ### SSH: Existing Deployment Takeover
 
-When deploying to a server that already has deployment assets:
-
-1. Detect: existing `/var/www/<project>` directory, existing PM2 processes with similar names, Nginx config referencing the same domain/IP, port conflicts.
-2. Report findings and ask for takeover decision:
-   - **Take over and backup**: Back up existing config, then proceed.
-   - **Coexist**: Use different directory/ports/process names.
-   - **Manual resolve**: Stop and let the user handle it.
-3. Record takeover decision and validation results in config and history.
+When deploying to a server that already has deployment assets, read `${SKILL_DIR}/references/ssh-takeover.md` for the detection procedure and takeover decision flow. Record takeover decision and validation results in config and history.
 
 ### SSH: Nginx Management
 

package/bundled/skills/prizmkit-deploy/references/data-safety-examples.md

@@ -0,0 +1,120 @@
+# Data Safety Examples
+
+Few-shot examples for the Data Safety Gate in `/prizmkit-deploy`. Read this file when a dangerous command pattern is detected — it shows the correct confirmation flow and illustrates what happens when the gate is skipped.
+
+## Example 1: Prisma Force Reset (the incident)
+
+**Context:** User runs `/prizmkit-deploy` to deploy a Next.js + Prisma project. During database setup, the model needs to sync the Prisma schema with the database.
+
+**Wrong — skipping the gate:**
+```
+Model: I'll sync your database schema now.
+$ prisma db push --force-reset --accept-schema
+→ All tables dropped. All production data lost. No backup. No confirmation.
+```
+This happened in production. `--force-reset` drops and recreates every table. `--accept-schema` bypasses Prisma's own confirmation prompt. The model ran both flags without asking the user whether existing data should be preserved.
+
+**Correct — with the safety gate:**
+```
+Model: I detected that your database needs a schema sync. However, before I do anything:
+
+WARNING: The Prisma schema has changes that could affect existing data.
+- New tables to create: 0
+- Tables that may be modified: 2 (users, orders)
+- If I run `prisma db push --force-reset`, ALL existing data will be DESTROYED.
+
+Options:
+1. prisma db push (safe — only adds missing tables/columns, no data loss)
+2. prisma db push --force-reset (DANGEROUS — drops and recreates all tables, all data lost)
+3. prisma migrate dev (creates a migration file you can review first)
+
+Which approach do you want? (1/2/3)
+```
+
+The `--accept-schema` flag should never be used — it suppresses Prisma's own built-in safety prompts that protect the user.
+
+## Example 2: Prisma Migrate Reset
+
+**Context:** User wants to reset their dev database to a clean state for testing.
+
+**Correct detection and confirmation:**
+```
+Model: `prisma migrate reset` will:
+- Drop the entire database
+- Recreate it from scratch
+- Run all migrations
+
+This is a DESTRUCTIVE operation. All data in the database will be permanently lost.
+
+Are you sure this is a dev/test database with no important data? (yes/no)
+```
+
+In production or any environment with real data: refuse immediately. This command should only run in dev with explicit user confirmation.
+
+## Example 3: Raw SQL Data Modification
+
+**Context:** During deployment, the model considers running a SQL command to fix a data issue.
+
+**Correct detection and confirmation:**
+```
+Model: To fix the duplicate user records, I would run:
+```sql
+DELETE FROM users WHERE email IS NULL AND created_at < '2025-01-01';
+```
+
+This would delete approximately 340 user records. BEFORE I run this:
+
+1. Would you like me to run a SELECT first to show you exactly which rows would be deleted?
+2. Do you want to back up the users table before deletion?
+3. Confirm: Delete these 340 records? (yes/no)
+
+I will not proceed without your explicit confirmation.
+```
+
+## Example 4: Overwriting Production Configuration
+
+**Context:** During bootstrap, the model needs to write an Nginx config, but one already exists at the target path.
+
+**Correct detection and confirmation:**
+```
+Model: Found existing Nginx config at /etc/nginx/sites-enabled/myapp.
+
+This file is NOT managed by PrizmKit (no `# PrizmKit Managed:` marker).
+Overwriting it could break existing site configuration.
+
+Options:
+1. Back up the existing config to /etc/nginx/sites-enabled/myapp.bak, then write new config
+2. Create new config alongside existing one with a different name
+3. Skip — keep the existing config as-is
+
+Which approach? (1/2/3)
+```
+
+## Example 5: Confirmation Dialogue Template
+
+When the gate triggers, use this dialogue structure:
+
+```
+============================================================
+DATA SAFETY GATE — DESTRUCTIVE OPERATION DETECTED
+============================================================
+
+Command: <the dangerous command>
+Risk level: HIGH / CRITICAL
+What will be lost: <plain-language description of affected data>
+
+Current state:
+- Database: <name>, <size>, <table count>
+- Affected tables: <list>
+- Last backup: <date if known, or "unknown — backup recommended">
+
+Recommended safe approach:
+<alternative if one exists>
+
+Do you want to proceed with this destructive operation?
+Type "yes, I understand the data will be lost" to confirm.
+Any other response will abort.
+============================================================
+```
+
+This format forces the user to read and acknowledge the risk before proceeding.

package/bundled/skills/prizmkit-deploy/references/ssh-bootstrap-flow.md

@@ -0,0 +1,49 @@
+# SSH Bootstrap Flow
+
+Bootstraps the server before first deployment. Present a plan showing every privileged action before executing anything.
+
+## Always-Run Preflight
+
+```
+locale-gen en_US.UTF-8           # fix locale warnings on bare Ubuntu
+apt-get update -qq               # refresh package list
+```
+
+## Check-and-Install (idempotent)
+
+Node.js, npm, PM2, Nginx, Git. Use v22 LTS if v25 not available.
+
+## Detect Port Conflicts
+
+`ss -tlnp | grep :80 || true`. If port 80/443 is occupied, report and ask how to resolve.
+
+## User and Directory Setup
+
+```
+useradd -m -s /bin/bash <runtimeUser>   # if not exists
+mkdir -p /var/www/<project>/{releases,shared,deploy-logs}
+chown -R <runtimeUser>:<runtimeUser> /var/www/<project>
+```
+
+## PM2 Startup
+
+```
+env PATH=$PATH:/usr/bin pm2 startup systemd -u <runtimeUser> --hp /home/<runtimeUser>
+```
+
+## Deploy Key (Pull mode only)
+
+```
+sudo -u <runtimeUser> ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
+sudo -u <runtimeUser> ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+```
+
+## Security Baseline (Firewall)
+
+After core tools are installed, ask whether to configure ufw. If user agrees, read `references/firewall-setup.md` for the full interactive flow and rule templates.
+
+## Database Setup
+
+If Discovery detected database drivers, ask whether to install the database on the server. If user agrees, read `references/database-setup.md` for platform-specific setup commands and security notes.
+
+After each bootstrap step, record the result. Bootstrap operations must be idempotent. Back up any existing config files before modifying them.

package/bundled/skills/prizmkit-deploy/references/ssh-execution-flow.md

@@ -0,0 +1,41 @@
+# SSH: Deployment Execution Flow
+
+Pipeline runs in strict order. Each group must complete before the next begins. If any step before traffic switch fails, STOP — do not touch the live version.
+
+## Pre-flight — Change Summary
+
+Show what will be deployed using `git log --oneline <last-deployed-commit>..HEAD`. If first deployment, show last 5 commits. If no new commits, warn "没有新的代码变更。确定要重新部署吗？"
+
+## Group 1 — Pre-flight & Prepare
+
+- Verify SSH, runtime user, tools, deploy key, port availability.
+- Generate `releaseId`: `YYYYMMDD-<short-commit-sha>`. Create `releases/<releaseId>`.
+- Determine target color: read `activeColor` from `shared/deploy-metadata.json` and use the opposite. If first deploy (no metadata, no `current` symlink), default to blue (port 3101).
+
+## Group 2 — Fetch & Build
+
+- **CI/CD Pull mode** (server-side build): git clone → install → copy `.env.production` before build (NEXT_PUBLIC_* vars are baked at build time) → build. If build fails: STOP.
+- **CI/CD Push mode** (runner-side build): extract tarball, skip install/build.
+- **Direct-upload mode**: build was already done locally and SCP'd. Skip this group.
+
+## Group 3 — Stage & Health Check
+
+- Start new version on inactive port via PM2: `pm2 start npm --name <project>-<app>-<color> -- run start -- -p <inactivePort>`.
+- PM2 process naming: `<project>-<app>-<color>` (e.g., `prizm-ideas-web-green`).
+- Wait 3-5 seconds, run health checks against new port. If any fails: STOP, do NOT switch traffic.
+
+## Group 4 — Switch & Verify
+
+- Update Nginx upstream to new port. Run `nginx -t` — abort on failure.
+- `systemctl reload nginx`. Update `current` symlink to new release.
+- Write `shared/deploy-metadata.json` with new `activeColor`, `activePort`, `lastReleaseId`.
+- Run health checks against public endpoint. If any fails: rollback immediately.
+
+## Group 5 — Cleanup & Record
+
+- Stop old PM2 process. Remove oldest releases beyond `releaseRetention` count. `pm2 save`.
+- Write deploy-history JSON. Update `deploy.config.json` validation status.
+
+## Post-deploy — Completion Summary
+
+Output a summary (project, URL, version, duration, health status) and append to deploy.md. If `deployStrategy` is `"direct-upload"`, offer CI/CD upgrade (see §SSH: Post-Deploy CI/CD Upgrade).

package/bundled/skills/prizmkit-deploy/references/ssh-takeover.md

@@ -0,0 +1,20 @@
+# SSH: Existing Deployment Takeover
+
+When deploying to a server that already has deployment assets.
+
+## Detection
+
+1. Check for existing `/var/www/<project>` directory
+2. Check for existing PM2 processes with similar names
+3. Check Nginx config referencing the same domain/IP
+4. Check for port conflicts
+
+## Decision Flow
+
+Report findings and ask for takeover decision:
+
+- **Take over and backup**: Back up existing config, then proceed.
+- **Coexist**: Use different directory/ports/process names.
+- **Manual resolve**: Stop and let the user handle it.
+
+Record takeover decision and validation results in config and history.

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

@@ -10,6 +10,12 @@ description: "Execute plan.md tasks with TDD approach. Respects task ordering an
 - User says "implement", "build", "code it", "start coding", "develop"
 - For fast-path: user describes a simple change directly (fast-path skips specify, but still requires a simplified plan.md with Tasks section)
 
+### When NOT to Use
+- No plan.md exists — run /prizmkit-plan first
+- All tasks in plan.md are already checked off — nothing to implement
+- Trivial one-line changes (typo, config tweak) — edit directly without the full workflow
+- Design/planning phase — use /prizmkit-plan to produce spec and plan first
+
 **PRECONDITION:**
 
 | Required Artifact | Check | If Missing |
@@ -17,7 +23,7 @@ description: "Execute plan.md tasks with TDD approach. Respects task ordering an
 | `plan.md` with Tasks section | File exists + unchecked tasks | Run `/prizmkit-plan` |
 | `spec.md` | File exists in same directory as plan.md | Run `/prizmkit-plan` |
 
-**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks.
+**Artifact directory**: Accept `artifact_dir` from caller. If not provided, scan `.prizmkit/` subdirectories for the most recently modified `plan.md` with unchecked tasks. When invoked as a handoff step in a skill chain, reuse the `artifact_dir` from the previous skill rather than re-detecting — re-detection can resolve to a different feature's directory in a multi-task workspace.
 
 ## Input
 

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

@@ -86,89 +86,7 @@ A universal spec + plan generator. Takes a natural-language description of ANY d
 
 ## Examples
 
-### Example 1: New Feature
-
-**Input:** "I want users to upload avatars"
-
-**Phase 0 output:** `.prizmkit/specs/003-user-avatar/spec.md`
-```markdown
-# User Avatar Upload
-## Overview
-Allow registered users to upload and manage profile pictures.
-## Goals
-### G-1: Upload Avatar
-As a registered user, I want to upload a profile picture,
-so that other users can visually identify me.
-**Acceptance Criteria:**
-- Given I am on my profile page
-- When I select an image file and click upload
-- Then my avatar is updated and visible across the platform
-## Scope
-- **In scope:** Upload, display, remove avatar; image format validation
-- **Out of scope:** Image cropping/editing, avatar history
-```
-
-**Phase 1-2 output:** `plan.md` excerpt:
-```markdown
-## Tasks
-### Phase: Foundation (T-010~T-019)
-- [ ] [T-010] [G-1] Add avatar_url field to User model — file: src/models/user.ts
-- [ ] [T-011] [G-1] Create S3 upload utility — file: src/lib/s3.ts
-### Phase: Core [P] (T-100~T-109)
-- [ ] [T-100] [P] [G-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
-```
-
-### Example 2: Refactoring
-
-**Input:** "Extract shared auth middleware from the API routes"
-
-**Phase 0 output:** `.prizmkit/specs/004-extract-auth-middleware/spec.md`
-```markdown
-# Extract Auth Middleware
-## Overview
-Consolidate duplicated authentication logic scattered across route files into a single shared middleware.
-## Goals
-### G-1: Extract Shared Authentication Logic
-Consolidate duplicated auth checks from 5 route files into a single middleware module.
-**Acceptance Criteria:**
-- All existing auth-related tests pass without modification
-- Auth logic exists in exactly one file (src/middleware/auth.ts)
-- No route file contains inline token verification
-## Scope
-- **In scope:** src/routes/users.ts, orders.ts, admin.ts, payments.ts, profile.ts
-- **Out of scope:** Authorization (role-based access), rate limiting
-## Behavior Preservation
-- All 23 existing API tests must pass unchanged
-- Response formats and HTTP status codes must not change
-- Error message strings must remain identical
-```
-
-### Example 3: Bug Fix
-
-**Input:** "Login page crashes when API returns 401"
-
-**Phase 0 output:** `.prizmkit/specs/005-login-401-crash/spec.md`
-```markdown
-# Fix: Login Crash on 401 Response
-## Overview
-Login page throws unhandled exception when auth API returns 401, causing a white screen.
-## Goals
-### G-1: Handle 401 Response Gracefully
-When the auth API returns 401, display an error message instead of crashing.
-**Acceptance Criteria:**
-- Given user submits invalid credentials, When API returns 401, Then error message "Invalid credentials" is displayed
-- Given user submits invalid credentials, When API returns 401, Then no unhandled exception is thrown
-## Root Cause
-- Error classification: Runtime
-- Root cause: `AuthService.handleLogin()` at src/services/auth.ts:42 does not handle null token
-- Affected files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
-## Scope
-- **In scope:** Null handling in auth service, error display in login page
-- **Out of scope:** Other HTTP error codes (403, 500), auth flow redesign
-## Behavior Preservation
-- All existing login success tests must pass unchanged
-- Auth token flow for valid credentials must not change
-```
+Read `${SKILL_DIR}/references/examples.md` for worked examples of feature, refactoring, and bug fix planning.
 
 ## References
 

package/bundled/skills/prizmkit-plan/references/examples.md

@@ -0,0 +1,85 @@
+# Plan Examples
+
+## Example 1: New Feature
+
+**Input:** "I want users to upload avatars"
+
+**Phase 0 output:** `.prizmkit/specs/003-user-avatar/spec.md`
+```markdown
+# User Avatar Upload
+## Overview
+Allow registered users to upload and manage profile pictures.
+## Goals
+### G-1: Upload Avatar
+As a registered user, I want to upload a profile picture,
+so that other users can visually identify me.
+**Acceptance Criteria:**
+- Given I am on my profile page
+- When I select an image file and click upload
+- Then my avatar is updated and visible across the platform
+## Scope
+- **In scope:** Upload, display, remove avatar; image format validation
+- **Out of scope:** Image cropping/editing, avatar history
+```
+
+**Phase 1-2 output:** `plan.md` excerpt:
+```markdown
+## Tasks
+### Phase: Foundation (T-010~T-019)
+- [ ] [T-010] [G-1] Add avatar_url field to User model — file: src/models/user.ts
+- [ ] [T-011] [G-1] Create S3 upload utility — file: src/lib/s3.ts
+### Phase: Core [P] (T-100~T-109)
+- [ ] [T-100] [P] [G-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
+```
+
+## Example 2: Refactoring
+
+**Input:** "Extract shared auth middleware from the API routes"
+
+**Phase 0 output:** `.prizmkit/specs/004-extract-auth-middleware/spec.md`
+```markdown
+# Extract Auth Middleware
+## Overview
+Consolidate duplicated authentication logic scattered across route files into a single shared middleware.
+## Goals
+### G-1: Extract Shared Authentication Logic
+Consolidate duplicated auth checks from 5 route files into a single middleware module.
+**Acceptance Criteria:**
+- All existing auth-related tests pass without modification
+- Auth logic exists in exactly one file (src/middleware/auth.ts)
+- No route file contains inline token verification
+## Scope
+- **In scope:** src/routes/users.ts, orders.ts, admin.ts, payments.ts, profile.ts
+- **Out of scope:** Authorization (role-based access), rate limiting
+## Behavior Preservation
+- All 23 existing API tests must pass unchanged
+- Response formats and HTTP status codes must not change
+- Error message strings must remain identical
+```
+
+## Example 3: Bug Fix
+
+**Input:** "Login page crashes when API returns 401"
+
+**Phase 0 output:** `.prizmkit/specs/005-login-401-crash/spec.md`
+```markdown
+# Fix: Login Crash on 401 Response
+## Overview
+Login page throws unhandled exception when auth API returns 401, causing a white screen.
+## Goals
+### G-1: Handle 401 Response Gracefully
+When the auth API returns 401, display an error message instead of crashing.
+**Acceptance Criteria:**
+- Given user submits invalid credentials, When API returns 401, Then error message "Invalid credentials" is displayed
+- Given user submits invalid credentials, When API returns 401, Then no unhandled exception is thrown
+## Root Cause
+- Error classification: Runtime
+- Root cause: `AuthService.handleLogin()` at src/services/auth.ts:42 does not handle null token
+- Affected files: src/services/auth.ts (L42), src/pages/login.tsx (L28)
+## Scope
+- **In scope:** Null handling in auth service, error display in login page
+- **Out of scope:** Other HTTP error codes (403, 500), auth flow redesign
+## Behavior Preservation
+- All existing login success tests must pass unchanged
+- Auth token flow for valid credentials must not change
+```

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

@@ -36,6 +36,19 @@ This skill handles 6 operations. When invoked, determine the user's intent and e
 
 **Key principle**: `/prizmkit-prizm-docs` defines WHAT the docs should look like and bootstraps them. `/prizmkit-retrospective` is the SOLE WRITER that keeps docs in sync with code during ongoing development.
 
+### When to Use
+- First-time project documentation setup (init)
+- Checking if docs are up to date (status)
+- Rebuilding stale module docs after major changes (rebuild)
+- Validating doc format compliance (validate)
+- Migrating existing docs to Prizm format (migrate)
+- User says "initialize docs", "check doc status", "rebuild docs", "validate docs"
+
+### When NOT to Use
+- Incremental doc updates after code changes → use /prizmkit-retrospective (the sole writer during development)
+- Project has no .prizmkit/prizm-docs/ and user doesn't want to initialize
+- User wants to edit code → use /prizmkit-plan and /prizmkit-implement
+
 ## Operation: Init
 
 Bootstrap .prizmkit/prizm-docs/ for the current project.
@@ -46,6 +59,7 @@ PRECONDITION: No .prizmkit/prizm-docs/ directory exists, or user confirms overwr
 
 Update .prizmkit/prizm-docs/ to reflect recent code changes.
 PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+**Scope guard**: Use Update only for out-of-band resync — when docs drifted from code after manual edits, merges, branch switches, or other changes made outside the dev loop. During the normal feature/bugfix/refactor loop, do NOT use Update: `/prizmkit-retrospective` is the sole writer and keeps docs in sync per task. Running both is redundant and risks conflicting edits.
 → Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
 
 ## Operation: Status

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

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