prizmkit 1.1.77 → 1.1.79

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

@@ -0,0 +1,184 @@
+---
+name: "prizmkit-plan"
+description: "Specify and plan tasks: natural language → spec.md & plan.md with architecture and executable tasks. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new task', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
+---
+
+# PrizmKit Plan
+
+A universal spec + plan generator. Takes a natural-language description of ANY development task (new feature, refactoring, bug fix, migration, etc.) and produces `spec.md` (WHAT/WHY) and `plan.md` (HOW) with executable tasks.
+
+### When to Use
+- Any non-trivial development task that benefits from written specification and planning
+- Before `/prizmkit-implement` — to create the spec + task breakdown
+- User says "specify", "plan", "new task", "I want to add...", "architect", "design", "break it down"
+
+### When NOT to Use
+- Config tweaks, typo fixes, trivial one-line changes → edit directly
+- Simple changes where the developer already knows exactly what to do and the scope is ≤10 lines in a single file
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `description` | Yes | Natural-language description of the task |
+| `artifact_dir` | No | Directory to write spec.md + plan.md into. If omitted, auto-generates under `.prizmkit/specs/` (see Phase 0 Step 2). |
+
+## Execution
+
+### Phase 0: Specify (→ spec.md)
+
+**Skip condition**: If `spec.md` already exists in the artifact directory, skip to Phase 1.
+
+**Steps:**
+
+1. Gather input: read the task description. If no description is provided and interactive session is available, ask the user; otherwise abort with an error.
+2. Determine artifact directory:
+   - If `artifact_dir` is provided → use it directly
+   - If not provided → scan `.prizmkit/specs/` for existing `###-*` directories, find highest numeric prefix, next = highest + 1 (zero-padded to 3 digits; start at `001` if empty). Create `.prizmkit/specs/###-task-slug/`
+   - Auto-generate 2-10 word task slug from description
+3. Load project context: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
+4. Generate `spec.md` from template (`${SKILL_DIR}/assets/spec-template.md`):
+   - Fill sections based on the task description — all sections are optional, include only what is relevant
+   - `[NEEDS CLARIFICATION]` markers for all ambiguous items
+5. **Database design detection**: If changes involve data persistence (new entities, fields, schema changes), add `## Data Model` section — scan existing schema files to extract naming conventions, ID strategy, constraint patterns. Mark uncertain decisions with `[NEEDS CLARIFICATION]`.
+6. Run quality validation : all goals have criteria? scope defined? DB conventions documented (if applicable)?
+7. **Auto-clarification**: If any `[NEEDS CLARIFICATION]` markers remain and interactive session is available, enter interactive clarification.
+   → Read `${SKILL_DIR}/references/clarify-guide.md` for question strategy and update rules.
+   If non-interactive, resolve ambiguities by choosing the most conservative option and annotating the decision.
+   Resolve all markers before proceeding to Phase 1.
+
+**Writing principles**: Focus on WHAT and WHY, never HOW. Every goal needs acceptance criteria. Scope boundaries must be explicit. Mark all genuine ambiguities — the clarification phase resolves them.
+
+**Internal ID hygiene**: PrizmKit IDs (`F-001`, `B-001`, `R-001`), task IDs (`T-100`), session IDs, run IDs, branch names, absolute worktree paths, and `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths are internal tracking metadata. They may appear in specs, plans, commit messages, and non-memory pipeline artifacts, but must never be written to `.prizmkit/prizm-docs/`, user-visible product copy, UI text, API responses, or expected UI strings in tests. If a behavior is scoped to the current feature, describe the product behavior without the ID.
+
+### Phase 1: Design (spec.md → plan.md)
+
+**Precondition**: `spec.md` exists in the artifact directory.
+
+**Steps:**
+
+1. Read `spec.md` from the artifact directory
+2. Load project context if not already loaded in Phase 0: read `.prizmkit/prizm-docs/root.prizm` and relevant L1/L2 docs
+3. Resolve any remaining `[NEEDS CLARIFICATION]` by proposing solutions
+4. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
+   - Change approach (how the changes integrate with existing system)
+   - Component / file changes
+   - Data model changes (with **database design gate** — read ALL existing schema files, ensure new schema follows existing patterns, resolve all DB ambiguities inline before proceeding)
+   - Interface design (API endpoints, request/response formats)
+   - Testing strategy
+   - Risk assessment
+   - Behavior preservation strategy (if the task modifies existing behavior — include what must remain unchanged and how to verify)
+5. Cross-check: every goal in spec.md maps to plan components — unmapped goals = coverage gaps
+6. Check alignment with `.prizmkit/prizm-docs/root.prizm` RULES section
+
+### Phase 2: Task Generation (plan.md → Tasks section)
+
+1. If interactive session is available, ask user for strategy; otherwise infer automatically: MVP-first / Incremental / Parallel
+2. Append `## Tasks` section to `plan.md` using template in `${SKILL_DIR}/assets/plan-template.md`:
+   - Phases: Setup (T-001~T-009) → Foundation (T-010~T-099) → Core (T-100+) → Polish (T-900+)
+   - Each task: `- [ ] [T-NNN] [P?] [G-N?] Description — file: path/to/file`
+   - Checkpoint tasks between phases for validation
+   - Organize Core tasks by goals (G-1, G-2, ...) or by logical grouping appropriate to the task
+3. Verify consistency and coverage → read `${SKILL_DIR}/references/verification-checklist.md` and run all checks. Fix any issues inline before output.
+4. Output: `plan.md` path, summary of design decisions, task count.
+
+**HANDOFF:** `/prizmkit-implement`
+
+## 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
+```
+
+## References
+
+- Spec template: `${SKILL_DIR}/assets/spec-template.md`
+- Plan template: `${SKILL_DIR}/assets/plan-template.md`
+- Clarification guide: `${SKILL_DIR}/references/clarify-guide.md`
+- Verification checklist: `${SKILL_DIR}/references/verification-checklist.md`
+
+## Output
+
+| Directory | Files |
+|---|---|
+| `artifact_dir` (provided or auto-generated `.prizmkit/specs/###-slug/`) | `spec.md` + `plan.md` |

package/bundled/skills-windows/prizmkit-plan/assets/plan-template.md

@@ -0,0 +1,115 @@
+# Plan: [TITLE]
+
+## Change Approach
+[Description of the technical approach — how these changes integrate with the existing system]
+
+## Component Design
+
+### New Components
+- [Component]: [Purpose]
+
+### Modified Components
+- [Component]: [What changes and why]
+
+## Behavior Preservation Strategy
+<!-- Include when the task modifies existing behavior. Delete if not applicable (e.g., greenfield feature). -->
+<!-- Strategy: one of test-gate / snapshot / manual -->
+<!-- test-gate: all tests must pass after each task -->
+<!-- snapshot: before-after comparison of outputs -->
+<!-- manual: reviewer verification at checkpoints -->
+- Strategy: [test-gate / snapshot / manual]
+- Baseline: [describe green test suite or snapshot state]
+
+## Data Model
+<!-- Include when changes involve database / data persistence. Delete if not applicable. -->
+<!-- IMPORTANT: Read existing schema/model files BEFORE designing new tables -->
+
+### Existing Schema Audit
+<!-- List existing tables/models reviewed. Note observed conventions. -->
+- Tables reviewed: [list tables examined]
+- Naming convention: [snake_case/camelCase — document what existing schema uses]
+- ID strategy: [UUID/auto-increment/CUID — match existing]
+- Timestamp fields: [created_at/updated_at pattern — match existing]
+- Soft delete: [yes/no, field name if applicable]
+- Constraint patterns: [NOT NULL defaults, UNIQUE patterns, index conventions]
+
+### Schema Changes
+| Entity | Type | Fields | Constraints | Relationships | Migration Notes |
+|--------|------|--------|-------------|---------------|-----------------|
+| [name] | new/modify | [field: type, ...] | [NOT NULL, UNIQUE, INDEX, ...] | [FK → existing_table(id)] | [migration strategy] |
+
+### Style Conformance Checklist
+- [ ] Table/column naming matches existing conventions
+- [ ] ID strategy consistent with existing tables
+- [ ] Timestamp fields follow existing patterns
+- [ ] Foreign key constraints and indexes defined
+- [ ] Soft delete strategy matches existing pattern (if applicable)
+- [ ] All fields have explicit nullability (NOT NULL or nullable)
+
+### Unresolved Questions
+<!-- NONE — all DB design questions must be resolved inline before proceeding to Tasks -->
+
+## Interface Design
+[API endpoints, request/response formats, module interfaces — include all details here]
+
+## Integration Points
+- [Service/Module]: [How integrated]
+
+## Testing Strategy
+- Unit: [Approach]
+- Integration: [Approach]
+- E2E: [Approach]
+
+## Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk] | [H/M/L] | [Plan] |
+
+## Deployment Considerations
+<!-- Include when there is deployment impact (new services, infra, environment changes). Delete if not applicable. -->
+
+### New Infrastructure Requirements
+- [Component]: [Deployment target from config deploy_strategy] — [any special config needed]
+
+### New Environment Variables
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| [VAR_NAME] | yes/no | [Purpose] | [example value] |
+
+### Deployment Impact
+- [ ] No infrastructure changes needed (skip this section)
+- [ ] New service/container required
+- [ ] New environment variables added
+- [ ] Database migration required in production
+- [ ] CI/CD pipeline update needed
+
+## Pre-Implementation Gates
+- [ ] Spec coverage: all goals mapped to components
+- [ ] Data model reviewed — existing schema conventions documented and followed (if applicable)
+- [ ] All `[NEEDS CLARIFICATION]` items resolved
+- [ ] Testing approach agreed
+- [ ] Behavior preservation strategy defined (if modifying existing behavior)
+- [ ] Root cause confirmed with reproduction test design (if fixing a defect)
+
+## Tasks
+
+### Strategy: [MVP-first | Incremental | Parallel]
+
+### Phase: Setup
+- [ ] [T-001] [Description] — file: [path]
+
+### Phase: Foundation
+- [ ] [T-010] [Description] — file: [path]
+
+### Phase: Core
+<!-- Organize by goals (G-1, G-2, ...) or by logical grouping appropriate to the task -->
+- [ ] [T-100] [P] [G-1] [Task description] — file: [path]
+
+### Phase: Polish
+- [ ] [T-900] Final verification
+- [ ] [T-901] Documentation update
+
+### Checkpoints
+- [ ] [CP-1] After Setup: project builds and tests pass
+- [ ] [CP-2] After Foundation: base changes verified
+- [ ] [CP-3] After each Core group: acceptance criteria pass

package/bundled/skills-windows/prizmkit-plan/assets/spec-template.md

@@ -0,0 +1,73 @@
+# [TITLE]
+
+## Overview
+[One paragraph describing the purpose and motivation]
+
+## Goals
+
+### G-1: [Goal Title]
+[Goal description — use whatever format best suits the task:
+  - User Story format: "As a [role], I want [capability], so that [benefit]."
+  - Objective format: "Objective: [change to make]. Target state: [desired outcome]."
+  - Fix format: "Fix: [symptom]. Root cause: [brief cause]."
+  - Or any other clear format.]
+
+**Acceptance Criteria:**
+- [ ] [Criterion 1 — Given/When/Then, or a concrete verifiable statement]
+
+## Scope
+
+### In Scope
+- [Item 1]
+
+### Out of Scope
+- [Item 1]
+
+## Behavior Preservation
+<!-- Include this section when the task modifies existing behavior (refactoring, bug fixes, migrations, etc.). Delete if not applicable. -->
+- [What behavior / contracts / interfaces must remain unchanged]
+- [Existing test suites that must continue to pass]
+
+## Root Cause
+<!-- Include this section when the task is fixing a defect. Delete if not applicable. -->
+- Error classification: [Runtime / Network / Auth / Data / Logic / Config / External]
+- Root cause: [specific code location and mechanism]
+- Affected files: [file list with line numbers]
+- Impact: [blast radius — which modules / features are affected]
+
+## Dependencies
+- [Dependency 1]: [Why needed]
+
+## Data Model
+<!-- Include this section when changes involve database / data persistence. Delete if not applicable. -->
+
+### Existing Schema Reference
+<!-- Read existing schema/model files BEFORE designing new tables. Document observed conventions here. -->
+- Tables reviewed: [list existing tables related to this change]
+- Naming convention: [snake_case/camelCase — match existing]
+- ID strategy: [UUID/auto-increment — match existing]
+- Timestamp pattern: [created_at/updated_at — match existing]
+- Soft delete: [yes/no, field name — match existing]
+
+### New/Modified Entities
+| Entity | Type (new/modify) | Key Fields | Relationships | Constraints |
+|--------|-------------------|------------|---------------|-------------|
+| [entity_name] | new | [field: type] | [FK to existing_table] | [NOT NULL, UNIQUE, etc.] |
+
+### Open Data Model Questions
+<!-- All questions here MUST be resolved before /prizmkit-plan generates Tasks -->
+- [NEEDS CLARIFICATION] [Any uncertain data model decisions — field types, nullability, relationships]
+
+## Constraints
+- [Constraint 1]
+
+## Clarifications
+[NEEDS CLARIFICATION]: [Ambiguous item]
+
+## Review Checklist
+- [ ] All goals have acceptance criteria
+- [ ] Scope boundaries are clearly defined
+- [ ] Dependencies are identified
+- [ ] No implementation details (WHAT not HOW)
+- [ ] Behavior preservation defined (if modifying existing behavior)
+- [ ] Root cause identified with evidence (if fixing a defect)

package/bundled/skills-windows/prizmkit-plan/references/clarify-guide.md

@@ -0,0 +1,67 @@
+# Clarification Phase — Execution Guide
+
+Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLARIFICATION]` markers exist, or during Phase 1 (design) when data model ambiguities arise.
+
+---
+
+## Question Strategy
+
+**Ask one question at a time.** Batching questions produces lower-quality answers.
+
+For each question:
+1. Cite the exact location in spec.md (e.g., "§Goals G-1 says..." or "§Scope says...")
+2. State what is ambiguous and why it matters for implementation
+3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
+
+**Prioritize by implementation impact** (highest first):
+1. Data model (entities, relationships, field types, constraints, naming) — **hardest to change after code is written**
+2. Functional scope boundaries
+3. UX flow and error handling
+4. Non-functional requirements (performance, security)
+5. Edge cases and integration points
+
+## Update Discipline
+
+After **each** user answer:
+- Immediately update `spec.md` (do not batch at the end)
+- Remove the resolved `[NEEDS CLARIFICATION]` marker
+- Re-evaluate for new ambiguities exposed by the answer
+
+## No Limits Policy
+
+**There is no cap on rounds or questions.** Keep asking until:
+- All `[NEEDS CLARIFICATION]` markers are removed, AND
+- No vague or underspecified areas remain, AND
+- You are fully confident about the requirements
+
+If the user's answer raises new questions — ask those too. If a previously-resolved item needs revisiting due to new context — go back.
+
+## Early Termination
+
+If the user says "done", "stop", or "enough" — end immediately and output a summary of:
+- What was resolved
+- What remains unclear (list any open `[NEEDS CLARIFICATION]` items)
+
+## Example Exchange
+
+**Question:**
+> §Goals G-1 says "User can upload files" but doesn't specify file types or size limits.
+>
+> **Recommended:** Accept JPEG, PNG, PDF up to 10MB — covers common use cases without straining storage.
+>
+> Do you agree, or different constraints?
+
+**User:** "Also allow SVG, make it 25MB"
+
+**Action:** Update spec.md §Goals G-1 → `File upload: JPEG, PNG, PDF, SVG. Max 25MB per file.` Remove marker.
+
+**Follow-up question triggered by answer:**
+> SVGs can contain embedded scripts (XSS risk). Should uploaded SVGs be sanitized (strip `<script>` + event handlers), or restricted to trusted users only?
+>
+> **Recommended:** Sanitize all SVG uploads — allows all users to upload safely.
+
+## Guidelines
+
+- Stay at WHAT/WHY level — no implementation details (HOW) in spec
+- If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
+- If the user seems fatigued: "I have N more questions — continue now or later?" — but never silently stop with unresolved ambiguities

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,115 @@
+---
+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.
+
+## 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
+```