prizmkit 1.1.78 → 1.1.80

package/bundled/skills-windows/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-windows/prizmkit-plan/references/verification-checklist.md

@@ -0,0 +1,60 @@
+# Verification Checklist — Spec & Plan Consistency
+
+Run this checklist after generating the Tasks section in plan.md. Fix any issues inline before outputting the final plan.
+
+---
+
+## Coverage
+
+- [ ] Every goal (G-N) in spec.md has at least one task in plan.md
+- [ ] Every task has a target file path (`— file: path/to/file`)
+- [ ] Risk assessment contains at least one risk with a mitigation plan
+- [ ] If spec includes `## Behavior Preservation` → at least one verification task exists
+- [ ] If spec includes `## Root Cause` → at least one reproduction test task exists
+
+## Duplication Detection
+
+- [ ] No near-duplicate requirements exist across spec.md sections (same intent, different wording)
+- [ ] If duplicates found, consolidate to the clearer phrasing and remove the other
+
+## Orphan Detection
+
+- [ ] No task exists without a mapped goal (orphan task)
+- [ ] No plan component exists without a corresponding spec requirement
+
+## Ambiguity Scan
+
+- [ ] No unresolved `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` markers remain
+- [ ] No vague criteria without measurable thresholds (e.g., "fast", "secure", "scalable", "intuitive" — replace with concrete numbers or conditions)
+
+## Terminology Consistency
+
+- [ ] Same concept uses the same name in both spec.md and plan.md (no terminology drift)
+- [ ] Data entities referenced in plan.md exist in spec.md (and vice versa)
+
+## Task Ordering
+
+- [ ] No task references the output of a later task without an explicit dependency note
+- [ ] Foundation tasks precede Core tasks that depend on them
+- [ ] Checkpoint tasks exist between phases
+
+## Rules Alignment
+
+- [ ] No spec or plan element conflicts with `.prizmkit/prizm-docs/root.prizm` RULES MUST/NEVER directives
+- [ ] Tech stack choices in plan.md match `.prizmkit/prizm-docs/root.prizm` TECH_STACK (if defined)
+
+## Database Design (skip if no Data Model section)
+
+- [ ] New entity/field naming follows conventions documented in "Existing Schema Audit"
+- [ ] All fields have explicit nullability (NOT NULL or nullable)
+- [ ] Foreign key constraints and indexes are defined
+- [ ] ID strategy and timestamp patterns match existing tables
+- [ ] No unresolved questions remain in Data Model "Unresolved Questions" section
+- [ ] Style Conformance Checklist in plan.md is fully checked
+
+## Action on Failure
+
+If any check fails:
+1. Fix the issue directly in spec.md or plan.md
+2. Re-run the failed checks only
+3. Do not proceed to output until all checks pass

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

@@ -0,0 +1,128 @@
+---
+name: "prizmkit-prizm-docs"
+description: "Project documentation specification and standard for AI-optimized progressive context loading. Defines the .prizmkit/prizm-docs/ 3-level hierarchy (L0/L1/L2), format rules, size limits, and loading protocol. Use this skill to: bootstrap docs for new projects (init), check doc freshness (status), regenerate stale modules (rebuild), validate format compliance (validate), or migrate existing docs (migrate). For incremental doc updates after code changes, use /prizmkit-retrospective instead — it is the sole writer of .prizmkit/prizm-docs/ during development. Trigger on: 'initialize docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs are stale', 'prizm docs'. (project)"
+---
+
+# Prizm Docs - AI Documentation Framework
+
+Full specification: ${SKILL_DIR}/assets/prizm-docs-format.md
+
+## Intent Routing
+
+This skill handles 6 operations. When invoked, determine the user's intent and execute the matching operation:
+
+| User Intent | Operation | Trigger Phrases |
+|---|---|---|
+| Bootstrap new project docs | **Init** | "initialize docs", "set up prizm docs", "bootstrap documentation" |
+| Sync docs after code changes | **Update** | "update docs", "sync documentation", "docs are stale" |
+| Check doc freshness | **Status** | "check docs", "are docs up to date", "doc status" |
+| Regenerate module docs | **Rebuild** | "rebuild docs for X", "regenerate module docs" |
+| Check format compliance | **Validate** | "validate docs", "check doc format", "docs valid?" |
+| Convert existing docs | **Migrate** | "migrate docs", "convert docs to prizm format" |
+
+---
+
+## Role Clarification
+
+**This skill vs `/prizmkit-retrospective`**:
+
+| Aspect | `/prizmkit-prizm-docs` | `/prizmkit-retrospective` |
+|--------|----------------------|--------------------------|
+| **Role** | Documentation SPECIFICATION + BOOTSTRAP | Incremental WRITER during development |
+| **When** | Project setup, health checks, migrations | After feature completion, before commit |
+| **Writes** | Initial .prizmkit/prizm-docs/ structure (init, rebuild, migrate) | Incremental updates to existing .prizmkit/prizm-docs/ |
+| **Reads** | Source code structure (for init/rebuild) | git diff + code changes (for sync) |
+| **Knowledge** | Defines format rules, size limits, loading protocol | Extracts TRAPS/RULES/DECISIONS into `.prizmkit/prizm-docs/` |
+
+**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.
+PRECONDITION: No .prizmkit/prizm-docs/ directory exists, or user confirms overwrite.
+→ Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
+
+## Operation: Update
+
+Update .prizmkit/prizm-docs/ to reflect recent code changes.
+PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+→ Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
+
+## Operation: Status
+
+Check freshness of all .prizm docs.
+PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+→ Read `${SKILL_DIR}/references/op-status.md` for detailed steps.
+
+## Operation: Rebuild
+
+Regenerate docs for a specific module from scratch. Requires a module path argument.
+PRECONDITION: .prizmkit/prizm-docs/ exists. Module path is valid.
+→ Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
+
+## Operation: Validate
+
+Check format compliance and consistency of all .prizm docs.
+PRECONDITION: .prizmkit/prizm-docs/ exists.
+→ Read `${SKILL_DIR}/references/op-validate.md` for detailed steps.
+
+## Operation: Migrate
+
+Convert existing documentation to .prizmkit/prizm-docs/ format.
+PRECONDITION: Existing docs/ or docs/AI_CONTEXT/ directory. No .prizmkit/prizm-docs/ (or user confirms overwrite).
+
+STEPS:
+1. DISCOVER existing docs: Scan docs/, docs/AI_CONTEXT/, README.md, ARCHITECTURE.md, and any structured documentation files.
+2. EXTRACT information from existing docs: project metadata, module descriptions, architecture patterns, rules, decisions, dependencies.
+3. MAP existing doc content to Prizm levels: project-wide info -> L0 root.prizm, module-level info -> L1 docs (MODULE, FILES, RESPONSIBILITY, KEY_FILES, DEPENDENCIES), detailed module info -> L2 docs (INTERFACES, DATA_FLOW, TRAPS, DECISIONS, domain-specific sections).
+4. CONVERT prose content to KEY: value format. Strip markdown formatting, tables, diagrams. Condense explanatory text into single-line values.
+5. GENERATE .prizmkit/prizm-docs/ structure following standard init procedure but seeded with extracted information instead of scanning source code alone.
+6. VALIDATE migrated docs against Prizm format rules and size limits.
+7. REPORT migration summary: files processed, content mapped, information that could not be automatically converted (requires manual review).
+
+OUTPUT: Migration report with list of source docs processed, generated .prizm files, and any manual review items.
+
+## Error Handling
+
+- **root.prizm is corrupted or invalid format**: Back up the existing file, then run Rebuild on all modules to regenerate from source code.
+- **Broken pointers (-> references to non-existent files)**: Create the missing .prizm file if the source module exists; remove the pointer if the source module was deleted.
+- **Size limit exceeded**: For L0, consolidate MODULE_INDEX entries. For L1, move implementation details to L2. For L2, trim non-essential derived detail and keep only durable project knowledge.
+- **No git history available**: Fall back to filesystem timestamps for freshness checks; warn user that accuracy may be reduced.
+
+### Key Protocols (reference)
+For detailed protocol specifications, see prizm-docs-format.md:
+- Progressive Loading: Section 6.1
+- Auto-Update: Section 7.1
+- RULES hierarchy: Section 3.1
+
+## Examples
+
+**Init output (Node.js project):**
+```
+Generated .prizmkit/prizm-docs/:
+  root.prizm (L0) — 3 modules in MODULE_INDEX
+  routes.prizm (L1) — 12 files, 4 interfaces
+  models.prizm (L1) — 8 files, 3 interfaces
+  services.prizm (L1) — 15 files, 6 interfaces
+```
+
+**Update after adding new API endpoint:**
+```
+Changed: src/routes/avatar.ts (A), src/models/user.ts (M)
+Updated: .prizmkit/prizm-docs/routes.prizm — added avatar.ts to KEY_FILES, new POST /api/avatar interface
+Updated: .prizmkit/prizm-docs/models.prizm — updated User interface with avatar_url field
+Skipped: .prizmkit/prizm-docs/services.prizm — no changes in services module
+```