prizmkit 1.0.0 → 1.0.1

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

@@ -0,0 +1,156 @@
+---
+name: "prizmkit-init"
+description: "Project takeover and bootstrap. Scans any project, generates Prizm docs, configures hooks. Use 'prizmkit.init' to start. (project)"
+---
+
+# PrizmKit Init
+
+Project takeover and bootstrap skill. Scans any project (brownfield or greenfield), generates Prizm documentation, and configures platform-specific hooks for documentation sync. Supports CodeBuddy, Claude Code, and dual-platform installations.
+
+### When to Use
+- Taking over a new project (brownfield or greenfield)
+- User says "initialize PrizmKit", "set up PrizmKit", "take over this project"
+- First time using PrizmKit on a project
+
+### Commands
+
+#### prizmkit.init
+Full project initialization.
+
+**PLATFORM DETECTION (before anything else):**
+1. Check for platform indicators in the current environment:
+   - CodeBuddy: `.codebuddy/` directory exists, or running inside `cbc` session
+   - Claude Code: `.claude/` directory exists, or running inside `claude` session
+   - Both: Both directories exist
+   - Unknown: Neither exists — ask the user which platform(s) to configure
+2. Store detected platform in `.prizmkit/config.json` as `"platform": "codebuddy" | "claude" | "both"`
+
+MODE DETECTION:
+- If `.prizm-docs/` exists: Ask user if they want to reinitialize or update
+- If project has source code: brownfield mode
+- If project is nearly empty: greenfield mode
+
+BROWNFIELD WORKFLOW (existing project):
+
+**Step 1: Project Scanning**
+1. Detect tech stack from build files (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Cargo.toml`, etc.)
+2. Map directory structure — identify source directories, test directories, config files
+3. Identify entry points by language convention
+4. Catalog dependencies (external packages)
+5. Count source files per directory
+
+**Step 2: State Assessment**
+2a. Run dependency analysis:
+  - Count outdated dependencies (if lockfile exists)
+  - Note any known vulnerability patterns
+
+2b. Scan for technical debt indicators:
+  - Count TODO/FIXME/HACK/XXX comments
+  - Identify large files (>500 lines)
+  - Check for test directories and coverage config
+
+2c. Generate `ASSESSMENT.md` in project root with findings
+
+**Step 3: Prizm Documentation Generation**
+3a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm:
+  - Create `.prizm-docs/` directory structure
+  - Generate `root.prizm` (L0) with project meta and module index
+  - Generate L1 docs for all discovered modules
+  - Create `changelog.prizm`
+  - Skip L2 (lazy generation)
+
+3b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
+
+**Step 4: PrizmKit Workspace Initialization**
+4a. Create `.prizmkit/` directory:
+  - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
+  - `.prizmkit/specs/` (empty)
+
+**Step 5: Hook & Settings Configuration (Platform-Specific)**
+
+**If platform is CodeBuddy (or both):**
+5a-cb. Read or create `.codebuddy/settings.json`
+5b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
+5c-cb. Preserve any existing hooks
+
+**If platform is Claude Code (or both):**
+5a-cl. Read or create `.claude/settings.json`
+5b-cl. Add `permissions` and `allowedTools` entries if needed
+5c-cl. Create `.claude/rules/prizm-documentation.md` with glob-scoped rules:
+  ```yaml
+  ---
+  description: PrizmKit documentation rules
+  globs:
+    - "**/*.ts"
+    - "**/*.js"
+    - "**/*.py"
+    - "**/*.go"
+  ---
+  When modifying source files:
+  1. Read `.prizm-docs/root.prizm` to understand project structure
+  2. After changes, update affected `.prizm-docs/` files
+  3. Follow Prizm doc format (KEY: value, not prose)
+  ```
+5d-cl. Create `.claude/rules/prizm-commit-workflow.md` with commit-scoped rules:
+  ```yaml
+  ---
+  description: PrizmKit commit workflow enforcement
+  globs:
+    - "**/*"
+  ---
+  Before any git commit:
+  1. Run git diff --cached --name-status
+  2. Map changed files to modules via root.prizm MODULE_INDEX
+  3. Update affected .prizm-docs/ files
+  4. Stage .prizm-docs/ changes
+  5. Use /prizmkit-committer for the complete workflow
+  ```
+5e-cl. Preserve any existing Claude settings and rules
+
+**Step 6: Project Memory Update (Platform-Specific)**
+
+**If platform is CodeBuddy (or both):**
+6a-cb. Read existing `CODEBUDDY.md` (or create if missing)
+6b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
+6c-cb. Do not duplicate if already present
+
+**If platform is Claude Code (or both):**
+6a-cl. Read existing `CLAUDE.md` (or create if missing)
+6b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
+6c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
+6d-cl. Do not duplicate if already present
+
+**Step 7: Report**
+Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, assessment highlights, platform-specific configuration applied, next recommended steps.
+
+Include platform-specific guidance:
+- CodeBuddy: "Use `prizmkit.specify` to start your first feature"
+- Claude Code: "Use `/prizmkit-specify` to start your first feature"
+
+GREENFIELD WORKFLOW (new project):
+- Skip Steps 1-2 (no code to scan)
+- Step 3: Create minimal `.prizm-docs/` with just `root.prizm` skeleton
+- Steps 4-6: Same as brownfield
+- Step 7: Recommend starting with specify for first feature (platform-appropriate command format)
+
+### Gradual Adoption Path
+After init, PrizmKit operates in phases:
+- **Passive** (default): Generates docs, doesn't enforce workflow
+- **Advisory**: Suggests improvements, flags issues (enable in config)
+- **Active**: Enforces spec-driven workflow for new features (enable in config)
+
+User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "advisory" | "active"`
+
+### Platform Reference
+
+| Concept | CodeBuddy | Claude Code |
+|---------|-----------|-------------|
+| Command invocation | `prizmkit.xxx` | `/prizmkit-xxx` |
+| Project memory | `CODEBUDDY.md` | `CLAUDE.md` |
+| Settings | `.codebuddy/settings.json` | `.claude/settings.json` |
+| Skills/Commands | `.codebuddy/skills/` | `.claude/commands/` |
+| Agents | `.codebuddy/agents/` | `.claude/agents/` |
+| Rules | hooks in settings.json | `.claude/rules/*.md` |
+| CLI command | `cbc` | `claude` |
+
+IMPORTANT: Use `${SKILL_DIR}` placeholder for all path references. Never hardcode absolute paths.

package/bundled/skills/prizmkit-log-analyzer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "prizmkit-log-analyzer"
+tier: 2
+description: "[Tier 2] Log pattern recognition via text analysis. Identifies error frequencies and correlations from provided log content. (project)"
+---
+
+# PrizmKit Log Analyzer
+
+Analyze log files to identify anomaly patterns, frequency trends, and error correlations for production issue investigation.
+
+## Commands
+
+### prizmkit.analyze-logs \<log-file-or-directory\>
+
+Analyze log files and produce a structured report of findings.
+
+**STEPS:**
+
+1. Read and parse log files (auto-detect format):
+   - JSON structured logs
+   - Structured text (key=value pairs)
+   - Syslog format
+   - Custom formats (infer delimiter and field positions)
+2. Extract entries with normalized fields:
+   - **Timestamp**: parse to comparable datetime
+   - **Level**: DEBUG, INFO, WARN, ERROR, FATAL
+   - **Source**: service name, module, class, or file
+   - **Message**: the log message body
+   - **Metadata**: request ID, user ID, trace ID (if present)
+3. Analyze patterns:
+   - **Error frequency**: count by type and time window (per minute, per hour)
+   - **Correlation**: errors that consistently appear together or in sequence
+   - **Anomaly detection**: sudden spikes in error rate, new error types not seen before
+   - **Timeline**: when did behavior change relative to deployments or config changes
+   - **Request tracing**: follow request IDs across log entries to reconstruct flows
+4. Identify top issues:
+   - Most frequent errors (by count)
+   - Most recent new errors (not seen in earlier log entries)
+   - Errors with increasing trend (getting worse over time)
+   - Errors correlated with specific endpoints, users, or time windows
+5. Generate analysis report:
+   - **Timeline of events**: chronological summary of significant changes
+   - **Top 10 error patterns**: with frequency, first/last occurrence, and sample messages
+   - **Correlation findings**: errors that co-occur or cascade
+   - **Anomaly alerts**: unusual patterns that warrant investigation
+   - **Recommended investigation priorities**: ranked list of what to look at first
+
+## Path References
+
+All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
+## Output
+
+- Structured analysis report printed to console
+- Summary suitable for sharing with team or pasting into incident reports

package/bundled/skills/prizmkit-monitoring-setup/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: "prizmkit-monitoring-setup"
+tier: 2
+description: "[Tier 2] Generate monitoring config templates for Prometheus/Grafana/CloudWatch/etc. Cannot test or validate actual metrics collection. (project)"
+---
+
+# PrizmKit Monitoring Setup
+
+Generate comprehensive monitoring, alerting, and log collection configurations for your project's observability stack.
+
+## Commands
+
+### prizmkit.monitoring
+
+Generate monitoring and observability configurations.
+
+**STEPS:**
+
+1. Read `.prizm-docs/root.prizm` for tech stack and architecture (services, databases, external dependencies)
+2. Ask user: monitoring stack
+   - Prometheus + Grafana
+   - ELK (Elasticsearch, Logstash, Kibana)
+   - CloudWatch (AWS)
+   - Datadog
+   - Other (specify)
+3. Identify key metrics to monitor:
+   - **Application (RED metrics)**:
+     - Request **R**ate: requests per second by endpoint
+     - **E**rror rate: 4xx/5xx responses, exception counts
+     - **D**uration: latency percentiles (p50, p95, p99)
+   - **System**:
+     - CPU utilization and saturation
+     - Memory usage and swap
+     - Disk I/O and space
+     - Network throughput and errors
+   - **Business**:
+     - Feature-specific metrics derived from spec (signups, transactions, etc.)
+     - SLA/SLO compliance indicators
+   - **Database**:
+     - Connection pool utilization
+     - Query latency by type (read/write)
+     - Replication lag
+     - Slow query count
+4. Generate monitoring configs:
+   - **Metrics collection**: Scrape configs, exporters, or agent configurations
+   - **Alert rules** with severity levels:
+     - Critical: immediate page (service down, data loss risk)
+     - Warning: investigate soon (degraded performance, approaching limits)
+     - Info: awareness (deployment events, scaling events)
+   - **Dashboard definition**: JSON/YAML for Grafana or equivalent
+     - Overview dashboard: service health at a glance
+     - Detail dashboard: per-service deep dive
+   - **Log format and collection config**:
+     - Structured log format recommendation
+     - Log shipping configuration
+     - Log retention policy
+5. Generate health check endpoint code if not existing:
+   - Liveness probe: process is running
+   - Readiness probe: dependencies are available
+   - Startup probe: initialization complete
+6. Write configs to standard locations:
+   - Prometheus: `monitoring/prometheus.yml`, `monitoring/alerts.yml`
+   - Grafana: `monitoring/dashboards/`
+   - Application: health check endpoint in source code
+
+## Path References
+
+All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
+## Output
+
+- Monitoring configuration files in `monitoring/` directory
+- Alert rule definitions
+- Dashboard JSON/YAML files
+- Health check endpoint code (if generated)

package/bundled/skills/prizmkit-onboarding-generator/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: "prizmkit-onboarding-generator"
+tier: 2
+description: "[Tier 2] Generate onboarding documentation from Prizm docs context. Quality depends on existing .prizm-docs/ completeness. (project)"
+---
+
+# PrizmKit Onboarding Generator
+
+Generate a comprehensive developer onboarding guide from project context, covering everything a new team member needs to be productive.
+
+## Commands
+
+### prizmkit.onboarding
+
+Generate a complete onboarding guide for new developers.
+
+**STEPS:**
+
+1. Read `.prizm-docs/root.prizm` for complete project overview (tech stack, architecture, conventions)
+2. Read `.prizm-docs/` L1 module docs for detailed module information
+3. Read existing `README.md`, `CONTRIBUTING.md` if present (avoid duplicating existing docs; reference them instead)
+4. Generate `ONBOARDING.md` covering:
+   - **Environment Setup**:
+     - Prerequisites (language runtimes, tools, accounts)
+     - Step-by-step install commands (copy-paste ready)
+     - Configuration files to create or modify
+     - Verification commands to confirm setup works
+   - **Architecture Overview**:
+     - High-level system description (from root.prizm ARCHITECTURE and LAYERS)
+     - Key services/modules and their responsibilities
+     - Data flow between components
+     - External dependencies and integrations
+   - **Key Directories**:
+     - What each top-level directory contains
+     - Where to find specific types of code (models, controllers, tests, configs)
+   - **Build and Test Commands**:
+     - How to build the project
+     - How to run the full test suite
+     - How to run specific tests
+     - How to run linters and formatters
+   - **Development Workflow**:
+     - Branch naming convention
+     - Development cycle: branch, develop, test, commit, PR
+     - Code review expectations
+     - CI/CD pipeline overview
+   - **Key Concepts and Domain Terminology**:
+     - Domain-specific terms and their meanings
+     - Acronyms used in the codebase
+   - **Common Tasks** (step-by-step guides):
+     - Adding a new API endpoint
+     - Adding a new database migration
+     - Creating a new test
+     - Deploying to staging
+   - **Debugging Tips and Common Pitfalls**:
+     - Known gotchas from TRAPS sections
+     - Common setup issues and solutions
+     - Useful debugging commands
+   - **Where to Find Help**:
+     - Documentation locations
+     - Team contacts or channels
+     - Issue tracker and how to file bugs
+5. Write to `ONBOARDING.md` in project root
+
+## Path References
+
+All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
+## Output
+
+- `ONBOARDING.md` in project root: complete onboarding guide for new developers

package/bundled/skills/prizmkit-perf-profiler/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: "prizmkit-perf-profiler"
+tier: 2
+description: "[Tier 2] Static analysis for potential performance issues with profiling tool recommendations. Does not measure actual runtime performance. (project)"
+---
+
+# PrizmKit Performance Profiler
+
+Identify performance bottlenecks through static code analysis and profiling guidance. Suggests targeted optimizations with expected impact.
+
+## Commands
+
+### prizmkit.perf-profile [module-or-file]
+
+Analyze code for performance bottlenecks and generate optimization recommendations.
+
+**STEPS:**
+
+1. Read `.prizm-docs/` for architecture and module relationships (dependencies, data flow, hot paths)
+2. If specific file/module given: focus analysis on that scope; otherwise analyze project-wide critical paths
+3. Analyze for common bottleneck patterns:
+   - **N+1 queries**: ORM/database calls inside loops
+   - **Missing indexes**: queries filtering or sorting on unindexed columns
+   - **Synchronous blocking in async code**: blocking I/O in async handlers, missing await
+   - **Unnecessary serialization/deserialization**: repeated JSON parse/stringify, redundant marshaling
+   - **Memory leaks**: growing collections without bounds, unclosed resources, event listener accumulation
+   - **Inefficient algorithms**: O(n^2) where O(n) or O(n log n) is possible, nested loops over large datasets
+   - **Missing caching opportunities**: repeated expensive computations or external calls with stable inputs
+   - **Excessive logging in hot paths**: string formatting and I/O in tight loops
+   - **Large payload transfers**: over-fetching from database, sending unnecessary fields to client
+   - **Connection management**: not reusing connections, missing connection pooling
+4. Generate profiling recommendations:
+   - Suggest profiling tools appropriate for the project's tech stack:
+     - Node.js: `--prof`, `clinic.js`, `0x`
+     - Python: `cProfile`, `py-spy`, `line_profiler`
+     - Java: JFR, async-profiler, VisualVM
+     - Go: `pprof`, `trace`
+     - Rust: `perf`, `flamegraph`, `criterion`
+   - Provide specific commands to run the profiler against the identified hot paths
+   - Identify measurement baselines to establish before optimizing
+5. Output performance report:
+   - **Suspected bottlenecks**: ranked by likely impact (HIGH / MEDIUM / LOW)
+   - **Suggested optimizations**: for each bottleneck, concrete code changes or architectural adjustments
+   - **Profiling commands**: copy-paste ready commands to validate each suspicion
+   - **Expected impact**: qualitative assessment of improvement (e.g., "Eliminates N+1, expect ~10x query reduction for list endpoints")
+6. Suggest updating `.prizm-docs/` TRAPS section with discovered performance pitfalls for future reference
+
+## Path References
+
+All internal asset paths MUST use `${SKILL_DIR}` placeholder for cross-IDE compatibility.
+
+## Output
+
+- Performance analysis report printed to console
+- Profiling command suggestions ready to execute

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

@@ -0,0 +1,54 @@
+---
+name: "prizmkit-plan"
+description: "Generate technical implementation plan from feature spec. Creates plan.md, data-model.md, API contracts, and research docs. Invoke after 'specify' when ready to plan. (project)"
+---
+
+# PrizmKit Plan
+
+Generate a comprehensive technical implementation plan from a feature specification. Produces plan.md with architecture approach, component design, data model, API contracts, testing strategy, and risk assessment.
+
+## Commands
+
+### prizmkit.plan
+
+Create a technical implementation plan for a specified feature.
+
+**PRECONDITION:** `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists
+
+**STEPS:**
+
+**Phase 0 — Research:**
+1. Read `spec.md` and `.prizm-docs/root.prizm` for project context
+2. Read relevant `.prizm-docs/` L1/L2 docs for affected modules
+3. Resolve any remaining `[NEEDS CLARIFICATION]` by proposing solutions
+4. Research technical approach based on project's tech stack
+
+**Phase 1 — Design:**
+5. Generate `plan.md` from template (`${SKILL_DIR}/assets/plan-template.md`):
+   - Architecture approach (how feature fits into existing structure)
+   - Component design (new/modified components)
+   - Data model changes (new entities, modified schemas)
+   - Interface design (API endpoints, request/response formats, module interfaces)
+   - Integration points (external services, internal modules)
+   - Testing strategy (unit, integration, e2e)
+   - Risk assessment
+6. Cross-check plan against spec: every user story MUST map to plan components
+7. Check alignment with project rules from `.prizm-docs/root.prizm` RULES section
+8. Output: `plan.md` path and summary of design decisions
+
+**KEY RULES:**
+- Every user story in spec.md MUST have a corresponding component or task in the plan
+- Architecture decisions MUST align with existing project patterns from `.prizm-docs/`
+- Risk assessment MUST include at least one risk with mitigation strategy
+- Supporting details (data model, interface design) are included as sections within plan.md, not as separate files
+
+**HANDOFF:** `prizmkit.tasks` or `prizmkit.code-review`
+
+## Template
+
+The plan template is located at `${SKILL_DIR}/assets/plan-template.md`.
+
+## Output
+
+All outputs are written to `.prizmkit/specs/###-feature-name/`:
+- `plan.md` — The implementation plan (includes architecture, component design, data model, interface design, testing strategy, risk assessment)

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

@@ -0,0 +1,37 @@
+# Implementation Plan: [FEATURE_TITLE]
+
+## Architecture Approach
+[How this feature integrates with existing system architecture]
+
+## Component Design
+
+### New Components
+- [Component]: [Purpose]
+
+### Modified Components
+- [Component]: [What changes and why]
+
+## Data Model
+[Entity definitions, schemas, and relationships — include all details here]
+
+## 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] |
+
+## Pre-Implementation Gates
+- [ ] Spec coverage: all user stories mapped to components
+- [ ] Data model reviewed
+- [ ] API contracts defined
+- [ ] Testing approach agreed

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

@@ -0,0 +1,140 @@
+---
+name: "prizmkit-prizm-docs"
+description: "AI-only documentation framework for progressive context loading. Manages .prizm-docs/ with 3-level hierarchy (L0/L1/L2). Use 'prizmkit.doc.init' to bootstrap, 'prizmkit.doc.update' to sync, 'prizmkit.doc.status' to check freshness, 'prizmkit.doc.rebuild' to regenerate, 'prizmkit.doc.validate' to check compliance, 'prizmkit.doc.migrate' to convert existing docs."
+---
+
+# Prizm Docs - AI Documentation Framework
+
+Full specification: ${SKILL_DIR}/assets/PRIZM-SPEC.md
+
+## Commands
+
+### prizmkit.doc.init
+
+Bootstrap .prizm-docs/ for the current project.
+
+PRECONDITION: No .prizm-docs/ directory exists, or user confirms overwrite.
+
+STEPS:
+1. Detect project type by scanning for build system files (go.mod, package.json, requirements.txt, Cargo.toml, pom.xml, *.csproj). Identify primary language, framework, build command, test command, and entry points.
+2. Discover modules by finding directories with 3+ source files. Recognize common patterns (controllers/, services/, models/, components/, hooks/, utils/, lib/, pkg/, internal/, cmd/, api/, routes/, middleware/). Exclude vendor/, node_modules/, .git/, build/, dist/, __pycache__/, target/, bin/. If module count > 30, ask user for include/exclude patterns.
+3. Create .prizm-docs/ directory structure mirroring the source tree.
+4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with arrow pointers, RULES extracted from CODEBUDDY.md/README/linter configs, and PATTERNS. Set PRIZM_VERSION: 2, UPDATED: today's date. Max 4KB.
+5. Generate L1 .prizm files for each discovered module. Each L1 includes MODULE, FILES count, RESPONSIBILITY, SUBDIRS with pointers, KEY_FILES (5-10 most important), INTERFACES (public/exported only), DEPENDENCIES (imports, imported-by, external), RULES, DATA_FLOW. Max 3KB each.
+6. DO NOT generate L2 docs during init. L2 is created lazily on first file modification in a sub-module, or when AI needs deep understanding of a module (ON_DEEP_READ trigger).
+7. Create changelog.prizm with initial entry: `- YYYY-MM-DD | root | add: initialized prizm documentation framework`
+8. Configure UserPromptSubmit hook in .codebuddy/settings.json per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 11.
+9. Append Prizm protocol section to CODEBUDDY.md per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 12.
+10. Validate all generated docs: size limits (L0 <= 4KB, L1 <= 3KB), pointer resolution (every -> reference resolves), no circular dependencies, UPDATED timestamps set, KEY: value format compliance, no anti-patterns (prose, code blocks, markdown headers).
+11. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
+
+OUTPUT: List of generated files, module count, and validation results.
+
+### prizmkit.doc.update
+
+Update .prizm-docs/ to reflect recent code changes.
+
+PRECONDITION: .prizm-docs/ exists with root.prizm.
+
+STEPS:
+1. Get changed files via `git diff --cached --name-status`. If nothing staged, use `git diff --name-status`. If no git changes at all, do full rescan comparing code against existing docs.
+2. Map changed files to modules by matching against MODULE_INDEX in root.prizm. Group changes by module.
+3. Classify each change: A (added) -> new KEY_FILES/INTERFACES entries. D (deleted) -> remove entries, update counts. M (modified) -> check interface/dependency changes. R (renamed) -> update all path references.
+4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DEPENDENCIES, CHANGELOG, UPDATED), then L1 (FILES count, KEY_FILES, INTERFACES, DEPENDENCIES, UPDATED), then L0 (MODULE_INDEX counts, UPDATED) only if structural change.
+5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only test files changed, only .prizm files changed, bug fixes to existing features (bugs are incomplete features being refined — no new module/interface created, no doc update needed).
+6. If new directory with 3+ source files appears and matches no module: create L1 immediately, add to MODULE_INDEX, defer L2.
+7. Append entries to changelog.prizm using format: `- YYYY-MM-DD | <module-path> | <verb>: <description>`
+8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 3KB -> move details to L2. L2 > 5KB -> split or archive.
+9. Stage updated .prizm files via `git add .prizm-docs/`
+
+OUTPUT: List of updated/created/skipped docs with reasons.
+
+### prizmkit.doc.status
+
+Check freshness of all .prizm docs.
+
+PRECONDITION: .prizm-docs/ exists with root.prizm.
+
+STEPS:
+1. Read root.prizm UPDATED timestamp.
+2. Count commits since that timestamp via `git log --since="<timestamp>" --oneline | wc -l`.
+3. For each L1/L2 doc, compare UPDATED timestamp against latest git modification of source files in that module via `git log -1 --format="%ai" -- <module-path>/`.
+4. Classify each doc as: FRESH (updated after latest source change), STALE (source changed since last update), MISSING (module exists but no .prizm doc).
+5. Flag any docs exceeding size limits.
+
+OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | LAST_UPDATED | SOURCE_LAST_MODIFIED.
+
+### prizmkit.doc.rebuild <module-path>
+
+Regenerate docs for a specific module from scratch.
+
+PRECONDITION: .prizm-docs/ exists. Module path is valid.
+
+STEPS:
+1. Delete existing L1 and all L2 docs for the specified module.
+2. Re-scan the module directory for files, interfaces, dependencies, subdirectories.
+3. Generate fresh L1 doc with full module analysis.
+4. Generate L2 docs for all sub-modules immediately (unlike init, rebuild generates L2 right away to capture current state).
+5. Update MODULE_INDEX in root.prizm with new file counts and pointers.
+6. Append rebuild entry to changelog.prizm: `- YYYY-MM-DD | <module-path> | refactor: rebuilt module documentation from scratch`
+7. Validate regenerated docs against size limits and format rules.
+
+OUTPUT: Regenerated doc summary with before/after comparison.
+
+### prizmkit.doc.validate
+
+Check format compliance and consistency of all .prizm docs.
+
+PRECONDITION: .prizm-docs/ exists.
+
+STEPS:
+1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules.
+2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 3KB, L2 <= 5KB. Report files exceeding limits with current size.
+3. POINTER CHECK: Verify all arrow (->) references resolve to existing .prizm files. Report broken pointers.
+4. TIMESTAMP CHECK: Verify all docs have UPDATED field. Flag docs with UPDATED older than 30 days as potentially stale.
+5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, INTERFACES, DEPENDENCIES. Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES.
+6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context.
+7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
+
+OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.
+
+### prizmkit.doc.migrate
+
+Convert existing documentation to .prizm-docs/ format.
+
+PRECONDITION: Existing docs/ or docs/AI_CONTEXT/ directory with documentation files. No .prizm-docs/ directory (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, detailed module info -> L2 docs.
+4. CONVERT prose content to KEY: value format. Strip markdown formatting, tables, diagrams. Condense explanatory text into single-line values.
+5. GENERATE .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.
+
+## Progressive Loading Protocol
+
+When working in a project with .prizm-docs/:
+
+- ON SESSION START: Always read .prizm-docs/root.prizm (L0). This is the project map.
+- ON TASK: Read L1 docs for relevant modules referenced in MODULE_INDEX.
+- ON FILE EDIT: Read L2 doc before modifying files. Check TRAPS and DECISIONS sections.
+- ON DEEP READ: If you need deep understanding of a module without modifying it, generate L2 if it doesn't exist.
+- NEVER load all .prizm docs at once. Progressive loading saves tokens.
+- BUDGET: Typical task should consume 3000-5000 tokens of Prizm docs total.
+
+## Auto-Update Protocol
+
+- BEFORE EVERY COMMIT: Update affected .prizm-docs/ files per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 7.
+- The UserPromptSubmit hook will remind you automatically when commit intent is detected.
+- If hook is not active, you MUST still follow the update protocol manually.
+- NEVER rewrite entire .prizm files. Only update affected sections.
+
+## RULES Hierarchy
+
+- root.prizm RULES are authoritative and apply project-wide.
+- L1/L2 RULES only supplement root.prizm with module-specific exceptions.
+- If L1/L2 RULES contradict root.prizm RULES, root.prizm takes precedence.