prizmkit 1.0.45 → 1.0.66

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-init"
-description: "Project takeover and bootstrap. Scans any project, generates Prizm docs, configures hooks. Use 'prizmkit.init' to start. (project)"
+description: "Project takeover and bootstrap. Scans any project, generates Prizm docs, configures hooks. Use this skill whenever a user opens a new project for the first time, says 'initialize', 'set up PrizmKit', 'take over this project', 'bootstrap', 'scan this codebase', 'init', or when .prizm-docs/ doesn't exist yet. Also use when PrizmKit was just installed via npx but not yet initialized. (project)"
 ---
 
 # PrizmKit Init
@@ -11,11 +11,20 @@ Project takeover and bootstrap skill. Scans any project (brownfield or greenfiel
 - 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
+- After `npx prizmkit install` when project has no `.prizm-docs/`
 
-### Commands
+### When NOT to Use
+- `.prizm-docs/` already exists and is up to date → use `/prizmkit-prizm-docs` (Update) instead
+- User just wants to update stale docs → use `/prizmkit-prizm-docs` (Update or Rebuild)
+- User wants to start a feature → skip init if already initialized, go to `/prizmkit-specify`
 
-#### prizmkit.init
-Full project initialization.
+### Error Handling
+- If `.prizm-docs/` already exists: ask user if they want to reinitialize (overwrites) or update (preserves)
+- If no source files found in any directory: fall back to greenfield mode
+- If platform cannot be detected: ask user explicitly which platform(s) to configure
+- If `${SKILL_DIR}/../../../assets/project-memory-template.md` is missing: generate inline PrizmKit section instead of failing
+
+## Execution Steps
 
 **PLATFORM DETECTION (before anything else):**
 1. Check for platform indicators in the current environment:
@@ -34,89 +43,48 @@ 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 using a TWO-TIER model — do NOT flatten:
+2. Map directory structure using a TWO-TIER model — flat structures lose the nesting relationships that AI needs to navigate the codebase:
    - TOP-LEVEL modules: directories directly under project root that contain source files or sub-directories with source files (e.g. `dev-pipeline/`, `src/`, `internal/`)
    - SUB-MODULES: directories INSIDE a top-level module (e.g. `dev-pipeline/scripts/`, `dev-pipeline/lib/`)
-   - A sub-module is NEVER treated as a top-level module, even if it has many files
+   - A sub-module maps to `.prizm-docs/<M>/<S>.prizm`, never to `.prizm-docs/<S>.prizm` — flattening would create ambiguous paths when two modules have identically-named sub-modules
    - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `.claude/`, `.codebuddy/`, `.prizmkit/`, `.prizm-docs/`
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
 5. Count source files per directory
 
 **Step 2: Prizm Documentation Generation**
-2a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm, passing the two-tier module structure from Step 1:
+Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Step 1:
   - Create `.prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizm-docs/<top-level>/`)
-  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing ONLY top-level modules
+  - Generate `root.prizm` (L0) with project meta and MODULE_INDEX listing only top-level modules
   - Generate L1 docs for top-level modules at `.prizm-docs/<M>.prizm` and for sub-modules at `.prizm-docs/<M>/<S>.prizm`
   - Create `changelog.prizm`
-  - Skip L2 (lazy generation)
-
-2b. If project has existing `docs/AI_CONTEXT/`: suggest running `prizmkit.doc.migrate`
+  - Skip L2 (lazy generation) — L2 is generated on first file modification, saving tokens upfront
 
 **Step 3: PrizmKit Workspace Initialization**
 3a. Create `.prizmkit/` directory:
   - `.prizmkit/config.json` (adoption_mode, speckit_hooks_enabled, platform)
   - `.prizmkit/specs/` (empty)
 
-**Step 4: Hook & Settings Configuration (Platform-Specific)**
-
-**If platform is CodeBuddy (or both):**
-4a-cb. Read or create `.codebuddy/settings.json`
-4b-cb. Add UserPromptSubmit hook from `${SKILL_DIR}/../../../assets/hooks/prizm-commit-hook.json`
-4c-cb. Preserve any existing hooks
-
-**If platform is Claude Code (or both):**
-4a-cl. Read or create `.claude/settings.json`
-4b-cl. Add `permissions` and `allowedTools` entries if needed
-4c-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)
-  ```
-4d-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
-  ```
-4e-cl. Preserve any existing Claude settings and rules
-
-**Step 5: Project Memory Update (Platform-Specific)**
-
-**If platform is CodeBuddy (or both):**
-5a-cb. Read existing `CODEBUDDY.md` (or create if missing)
-5b-cb. Append PrizmKit section from `${SKILL_DIR}/../../../assets/codebuddy-md-template.md`
-5c-cb. Do not duplicate if already present
-
-**If platform is Claude Code (or both):**
-5a-cl. Read existing `CLAUDE.md` (or create if missing)
-5b-cl. Append PrizmKit section from `${SKILL_DIR}/../../../assets/claude-md-template.md`
-5c-cl. Adjust command references to use `/command-name` format (not `prizmkit.xxx`)
-5d-cl. Do not duplicate if already present
+**Step 4: Hook & Settings Configuration**
+
+4a. Read or create platform settings file (`.codebuddy/settings.json` or `.claude/settings.json`)
+4b. Add UserPromptSubmit and PostToolUse hooks for automatic prizm-docs reminders
+4c. For Claude Code: also add `permissions` entries and `.claude/rules/` for documentation enforcement:
+  - `.claude/rules/prizm-documentation.md` (glob-scoped source file rules)
+  - `.claude/rules/prizm-commit-workflow.md` (commit workflow enforcement)
+4d. Preserve any existing hooks and settings — never overwrite user's custom configuration
+
+**Step 5: Project Memory Update**
+
+5a. Read existing project memory file (`CODEBUDDY.md` or `CLAUDE.md`) or create if missing
+5b. Append PrizmKit section from `${SKILL_DIR}/../../../assets/project-memory-template.md`
+5c. Do not duplicate if PrizmKit section already present
 
 **Step 6: Report**
 Output summary: platform detected, tech stack detected, modules discovered, L1 docs generated, platform-specific configuration applied, next recommended steps.
 
 Include platform-specific guidance:
-- CodeBuddy: "Use `prizmkit.specify` to start your first feature"
+- CodeBuddy: "Use `/prizmkit-specify` to start your first feature"
 - Claude Code: "Use `/prizmkit-specify` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
@@ -137,7 +105,7 @@ User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "
 
 | Concept | CodeBuddy | Claude Code |
 |---------|-----------|-------------|
-| Command invocation | `prizmkit.xxx` | `/prizmkit-xxx` |
+| 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/` |
@@ -145,4 +113,27 @@ User can change mode in `.prizmkit/config.json`: `"adoption_mode": "passive" | "
 | Rules | hooks in settings.json | `.claude/rules/*.md` |
 | CLI command | `cbc` | `claude` |
 
+## Example
+
+**Brownfield init on a Node.js project:**
+```
+$ /prizmkit-init
+
+Platform detected: Claude Code
+Tech stack: TypeScript, Node.js, Express
+Mode: Brownfield (154 source files found)
+
+Modules discovered:
+  src/routes/     → .prizm-docs/routes.prizm (12 files)
+  src/models/     → .prizm-docs/models.prizm (8 files)
+  src/services/   → .prizm-docs/services.prizm (15 files)
+  src/middleware/  → .prizm-docs/middleware.prizm (5 files)
+
+Generated: root.prizm + 4 L1 docs + changelog.prizm
+Configured: .claude/rules/ (2 files), hooks in settings.json
+Updated: CLAUDE.md with PrizmKit section
+
+Next: Use /prizmkit-specify to start your first feature
+```
+
 IMPORTANT: Use `${SKILL_DIR}` placeholder for all path references. Never hardcode absolute paths.

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

@@ -1,26 +1,38 @@
 ---
 name: "prizmkit-plan"
-description: "Generate technical implementation plan and executable task breakdown from feature spec. Produces plan.md with architecture, data model, API contracts, and a Tasks section. Invoke after 'specify' when ready to plan. (project)"
+description: "Generate technical implementation plan and executable task breakdown from feature spec. Produces plan.md with architecture, data model, API contracts, and a Tasks section. Use this skill whenever the user wants to design how a feature will be built, break work into tasks, or think through architecture. Trigger on: 'plan', 'architect', 'how to build', 'design', 'break it down', 'break this into tasks', 'create tasks', 'implementation strategy', 'how should we implement'. Always use after /prizmkit-specify and before /prizmkit-implement. (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, risk assessment, and an executable Tasks section.
 
-## Commands
+### When to Use
+- After `/prizmkit-specify` when ready to plan the implementation
+- User says "plan", "architect", "how to build", "design", "break it down", "create tasks"
+- Before `/prizmkit-implement` to create the task breakdown
+- When user wants to understand the full implementation approach before coding
 
-### prizmkit.plan
+### When NOT to Use
+- No input document exists yet (no spec.md, no refactor-analysis.md, no fix-plan.md) → run `/prizmkit-specify` or the appropriate upstream skill first
+- Simple bug fix or config change → use fast path (`/prizmkit-plan` with simplified output → `/prizmkit-implement` → `/prizmkit-committer`)
+- User just wants to explore/research → answer directly, no plan artifact needed
 
-Create a technical implementation plan and task breakdown for a specified feature.
+**PRECONDITION (multi-mode):**
+- **Feature mode** (default): `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists. If spec.md is missing, prompt the user: "No spec found — want me to run /prizmkit-specify first?"
+- **Refactor mode**: `refactor-analysis.md` exists in `.prizmkit/refactor/<refactor-slug>/`. Use refactor-analysis.md as the input document in place of spec.md. Output plan.md to the same `.prizmkit/refactor/<refactor-slug>/` directory, NOT to `.prizmkit/specs/`.
+- **Bugfix mode**: Bug description provided by caller or `fix-plan.md` exists in `.prizmkit/bugfix/<BUG_ID>/`. Output plan.md to the same directory.
+- **Auto-detect**: If the calling workflow passes an explicit artifact directory, use that. Otherwise check which input document type exists.
 
-**PRECONDITION:** `spec.md` exists in `.prizmkit/specs/###-feature-name/`, `.prizm-docs/root.prizm` exists
-
-**STEPS:**
+## Execution Steps
 
 **Phase 0 — Research:**
-1. Read `spec.md` for feature requirements
+1. Read the input document for requirements:
+   - **Feature mode**: Read `spec.md` for feature requirements
+   - **Refactor mode**: Read `refactor-analysis.md` for refactoring goals, scope boundary, and baseline tests
+   - **Bugfix mode**: Read bug description / `fix-plan.md` for reproduction steps and expected fix
 2. Load project context (use first available source):
-   - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read it for all context (Section 3 'Prizm Context' for docs, Section 4 'Existing Source Files' for code). Do NOT re-read `.prizm-docs/` or individual source files.
+   - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read it for all context (Section 3 'Prizm Context' for docs, Section 4 'Existing Source Files' for code). The context-snapshot consolidates dozens of individual files into one read, saving significant tokens.
    - Otherwise → read `.prizm-docs/root.prizm` and 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
@@ -34,8 +46,8 @@ Create a technical implementation plan and task breakdown for a specified featur
    - 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
+6. Cross-check plan against spec: every user story should map to plan components — unmapped stories mean the plan has coverage gaps that will surface during implementation
+7. Check alignment with project rules from `.prizm-docs/root.prizm` RULES section — violating project rules causes CRITICAL findings in the analyze phase
 
 **Phase 2 — Task Generation:**
 8. Ask user for implementation strategy (or infer from context): MVP-first / Incremental / Parallel
@@ -44,19 +56,40 @@ Create a technical implementation plan and task breakdown for a specified featur
    - Each task: `- [ ] [T-NNN] [P?] [US?] Description — file: path/to/file`
    - `[P]` marker for tasks that can run in parallel within their phase
    - Checkpoint tasks between phases for validation
-10. Verify: every user story maps to at least one task; every task references a target file path
+10. Verify coverage and traceability:
+    - Every user story maps to at least one task — orphan stories become orphan features
+    - Every task references a target file path — pathless tasks leave implementers guessing where to write code
+    - Risk assessment includes at least one risk with mitigation — helps the implementer prepare for known challenges
 11. Output: `plan.md` path, summary of design decisions, and task count
 
-**KEY RULES:**
-- Every user story in spec.md MUST have a corresponding component AND 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
-- Task IDs use zero-padded numbering: `[T-001]`, `[T-010]`, `[T-100]`
-- Every task MUST reference a target file path
-- Each user story section MUST be independently testable
+**Task ID Conventions:**
+- Task IDs use zero-padded numbering: `[T-001]`, `[T-010]`, `[T-100]` — this ensures consistent sorting and visual alignment
+- Each user story section should be independently testable — this enables incremental verification during implementation
+
+**HANDOFF:** `/prizmkit-analyze` or `/prizmkit-implement`
+
+## Example
+
+**Input:** spec.md for "User Avatar Upload" feature
 
-**HANDOFF:** `prizmkit.analyze` or `prizmkit.implement`
+**Output:** plan.md excerpt:
+```markdown
+## Architecture Approach
+Extend existing user profile module. Add S3 integration for file storage.
+Reuse existing auth middleware for upload endpoint protection.
+
+## Tasks
+
+### Phase 1: Data Layer (T-010~T-019)
+- [ ] [T-010] [US-1] Add avatar_url field to User model — file: src/models/user.ts
+- [ ] [T-011] [US-1] Create S3 upload utility — file: src/lib/s3.ts
+- [ ] [T-012] CP: Data layer checkpoint — run migrations + unit tests
+
+### Phase 2: API [P] (T-100~T-109)
+- [ ] [T-100] [P] [US-1] POST /api/avatar upload endpoint — file: src/routes/avatar.ts
+- [ ] [T-101] [P] [US-2] DELETE /api/avatar endpoint — file: src/routes/avatar.ts
+- [ ] [T-102] CP: API checkpoint — integration tests pass
+```
 
 ## Template
 
@@ -64,5 +97,9 @@ 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, and Tasks section)
+Output directory depends on mode:
+- **Feature mode**: `.prizmkit/specs/###-feature-name/plan.md`
+- **Refactor mode**: `.prizmkit/refactor/<refactor-slug>/plan.md`
+- **Bugfix mode**: `.prizmkit/bugfix/<BUG_ID>/plan.md`
+
+The plan.md includes architecture, component design, data model, interface design, testing strategy, risk assessment, and Tasks section.

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

@@ -1,15 +1,42 @@
 ---
 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."
+description: "Project documentation specification and standard for AI-optimized progressive context loading. Defines the .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 .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-SPEC.md
 
-## Commands
+## Intent Routing
 
-### prizmkit.doc.init
+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 .prizm-docs/ structure (init, rebuild, migrate) | Incremental updates to existing .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 from work done |
+
+**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 .prizm-docs/ for the current project.
 
@@ -17,27 +44,27 @@ 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 in TWO tiers — DO NOT FLATTEN the directory hierarchy:
+2. Discover modules in TWO tiers — flat structures lose nesting relationships, and when two modules share an identically-named sub-module (e.g., `utils/`), flattening creates ambiguous paths:
    - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that contain 3+ source files OR contain sub-directories with 3+ source files. These go into MODULE_INDEX.
-   - SUB-MODULES: directories INSIDE a top-level module that contain 3+ source files. These are NOT top-level modules — they are listed in the parent L1 doc's SUBDIRS section only.
-   - HIERARCHY RULE: if directory X lives inside top-level module M, it maps to .prizm-docs/<M>/<X>.prizm — NEVER to .prizm-docs/<X>.prizm.
+   - SUB-MODULES: directories INSIDE a top-level module that contain 3+ source files. Listed in the parent L1 doc's SUBDIRS section only.
+   - HIERARCHY RULE: directory X inside top-level module M maps to .prizm-docs/<M>/<X>.prizm, never to .prizm-docs/<X>.prizm.
    - Exclude vendor/, node_modules/, .git/, build/, dist/, __pycache__/, target/, bin/. If top-level module count > 30, ask user for include/exclude patterns.
-3. Create .prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizm-docs/<M>/. NEVER place a sub-module's .prizm file at the .prizm-docs/ root.
-4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX listing ONLY top-level modules with arrow pointers to .prizm-docs/<M>.prizm, RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, and PATTERNS. Sub-modules must NOT appear in MODULE_INDEX. Set PRIZM_VERSION: 2, UPDATED: today's date. Max 4KB.
+3. Create .prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizm-docs/<M>/.
+4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX listing only top-level modules with arrow pointers to .prizm-docs/<M>.prizm (sub-modules stay out of MODULE_INDEX to keep L0 compact and within the 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, and PATTERNS. Set PRIZM_VERSION: 2, UPDATED: today's date. Max 4KB.
 5. Generate L1 .prizm files for ALL modules (top-level and sub-modules), each at its correct mirrored path:
    - Top-level module M → write .prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
    - Sub-module S inside M → write .prizm-docs/<M>/<S>.prizm
    Each L1 includes MODULE (full relative path), FILES count, RESPONSIBILITY, SUBDIRS with pointers (for top-level only), 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).
+6. Skip L2 docs during init — L2 is created lazily on first file modification or when AI needs deep understanding (ON_DEEP_READ trigger). This saves significant upfront token cost on large projects.
 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.
+8. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 11.
+9. Append Prizm protocol section to project memory file (CODEBUDDY.md or CLAUDE.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
+## Operation: Update
 
 Update .prizm-docs/ to reflect recent code changes.
 
@@ -56,7 +83,7 @@ STEPS:
 
 OUTPUT: List of updated/created/skipped docs with reasons.
 
-### prizmkit.doc.status
+## Operation: Status
 
 Check freshness of all .prizm docs.
 
@@ -71,9 +98,9 @@ STEPS:
 
 OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | LAST_UPDATED | SOURCE_LAST_MODIFIED.
 
-### prizmkit.doc.rebuild <module-path>
+## Operation: Rebuild
 
-Regenerate docs for a specific module from scratch.
+Regenerate docs for a specific module from scratch. Requires a module path argument.
 
 PRECONDITION: .prizm-docs/ exists. Module path is valid.
 
@@ -88,7 +115,7 @@ STEPS:
 
 OUTPUT: Regenerated doc summary with before/after comparison.
 
-### prizmkit.doc.validate
+## Operation: Validate
 
 Check format compliance and consistency of all .prizm docs.
 
@@ -105,7 +132,7 @@ STEPS:
 
 OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.
 
-### prizmkit.doc.migrate
+## Operation: Migrate
 
 Convert existing documentation to .prizm-docs/ format.
 
@@ -122,6 +149,13 @@ STEPS:
 
 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, archive CHANGELOG entries older than 90 days.
+- **No git history available**: Fall back to filesystem timestamps for freshness checks; warn user that accuracy may be reduced.
+
 ## Progressive Loading Protocol
 
 When working in a project with .prizm-docs/:
@@ -135,9 +169,9 @@ When working in a project with .prizm-docs/:
 
 ## Auto-Update Protocol
 
-- BEFORE EVERY COMMIT: Update affected .prizm-docs/ files per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 7.
+- BEFORE EVERY COMMIT: Run `/prizmkit-retrospective` which is the **sole maintainer** of .prizm-docs/. It handles both structural sync and knowledge injection.
 - 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.
+- `/prizmkit-committer` does NOT update .prizm-docs/ — it only commits what is already staged.
 - NEVER rewrite entire .prizm files. Only update affected sections.
 
 ## RULES Hierarchy
@@ -145,3 +179,24 @@ When working in a project with .prizm-docs/:
 - 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.
+
+## Examples
+
+**Init output (Node.js project):**
+```
+Generated .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
+  changelog.prizm — initial entry
+```
+
+**Update after adding new API endpoint:**
+```
+Changed: src/routes/avatar.ts (A), src/models/user.ts (M)
+Updated: .prizm-docs/routes.prizm — added avatar.ts to KEY_FILES, new POST /api/avatar interface
+Updated: .prizm-docs/models.prizm — updated User interface with avatar_url field
+Skipped: .prizm-docs/services.prizm — no changes in services module
+Appended: changelog.prizm — "2026-03-18 | routes | add: avatar upload endpoint"
+```

package/bundled/skills/prizmkit-prizm-docs/assets/PRIZM-SPEC.md

@@ -294,7 +294,7 @@ FOR any source file at path P:
   1. Walk up directory tree to find the first ancestor D where .prizm-docs/<D>.prizm exists
   2. That file is the L1 doc for this source file
   3. If P is inside a subdirectory S of D, check if .prizm-docs/<D>/<S>.prizm exists for L2
-  4. If no .prizm doc found, the module is undocumented (may need prizmkit.doc.update)
+  4. If no .prizm doc found, the module is undocumented (may need prizmkit-prizm-docs Update operation)
 
 ---
 
@@ -345,7 +345,7 @@ BUDGET: Typical task should consume 3000-5000 tokens of prizm docs total
 
 ## 7.1 Trigger
 
-WHEN: Before every commit (detected automatically via hook, or manually via prizmkit.doc.update)
+WHEN: Before every commit (detected automatically via hook, or manually via prizmkit-prizm-docs Update operation)
 GOAL: Keep prizm docs synchronized with source code
 
 ## 7.2 Update Decision Logic
@@ -441,7 +441,7 @@ NEVER: Rewrite entire .prizm files on update (modify only affected sections)
 
 ## 9.1 Algorithm
 
-COMMAND: prizmkit.doc.init
+OPERATION: Init (invoked via prizmkit-prizm-docs skill)
 PRECONDITION: No .prizm-docs/ directory exists (or user confirms overwrite)
 
 ALGORITHM: prizm_init
@@ -575,18 +575,18 @@ ON_DEEP_READ trigger:
 
 The Prizm skill is defined at: ${SKILL_DIR}/SKILL.md
 
-COMMANDS:
+OPERATIONS (all invoked via the prizmkit-prizm-docs skill):
 
-  prizmkit.doc.init       - Bootstrap .prizm-docs/ for a new project (Section 9)
-  prizmkit.doc.update     - Sync docs with code changes (Section 7)
-  prizmkit.doc.status     - Check freshness of all docs
-  prizmkit.doc.rebuild    - Regenerate docs for a specific module
-  prizmkit.doc.validate   - Check format compliance and consistency (Section 10.2)
-  prizmkit.doc.migrate    - Convert existing docs to .prizm-docs/ format (Section 10.3)
+  Init       - Bootstrap .prizm-docs/ for a new project (Section 9)
+  Update     - Sync docs with code changes (Section 7)
+  Status     - Check freshness of all docs
+  Rebuild    - Regenerate docs for a specific module
+  Validate   - Check format compliance and consistency (Section 10.2)
+  Migrate    - Convert existing docs to .prizm-docs/ format (Section 10.3)
 
-## 10.2 prizmkit.doc.validate
+## 10.2 Validate Operation
 
-COMMAND: prizmkit.doc.validate
+OPERATION: Validate (invoked via prizmkit-prizm-docs skill)
 PRECONDITION: .prizm-docs/ directory exists
 
 ALGORITHM: prizm_validate
@@ -640,9 +640,9 @@ STEPS:
 
 OUTPUT: Validation report with PASS/FAIL per check category, issue list with file paths and line references, suggested fixes for common problems.
 
-## 10.3 prizmkit.doc.migrate
+## 10.3 Migrate Operation
 
-COMMAND: prizmkit.doc.migrate
+OPERATION: Migrate (invoked via prizmkit-prizm-docs skill)
 PRECONDITION: Existing documentation (docs/, docs/AI_CONTEXT/, README.md, ARCHITECTURE.md, etc.). No .prizm-docs/ directory (or user confirms overwrite).
 
 ALGORITHM: prizm_migrate
@@ -713,7 +713,7 @@ JSON:
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_DOC_UPDATE_REQUIRED: Before committing, you MUST update .prizm-docs/ per Prizm auto-update protocol. Steps: 1) Run git diff --cached --name-status. 2) Map changed files to modules via root.prizm MODULE_INDEX. 3) Read and update affected .prizm files (only changed sections). 4) Append to changelog.prizm. 5) Stage .prizm files with git add .prizm-docs/. 6) Then proceed with commit. RULES: Never rewrite entire .prizm files. Never add prose. Only update affected sections.'"
+            "command": "echo 'PRIZMKIT_MEMORY_MAINTENANCE_REQUIRED: Before committing, you MUST run /prizmkit-retrospective to maintain .prizm-docs/ project memory. It handles both structural sync (KEY_FILES, INTERFACES, DEPENDENCIES) and knowledge injection (TRAPS, RULES, DECISIONS). After retrospective completes, proceed with /prizmkit-committer for the actual git commit.'"
           }
         ]
       }
@@ -749,7 +749,7 @@ The core requirement is: before any commit operation, AI must update affected .p
 
 ## 12.1 Template Section
 
-Append the following to any project's CODEBUDDY.md during prizmkit.doc.init:
+Append the following to any project's CODEBUDDY.md during Init operation:
 
 TEXT:
 
@@ -835,8 +835,8 @@ FILES:
 This is enough to give AI a project overview and track changes.
 L1 and L2 docs can be added incrementally as AI works in specific areas.
 
-BOOTSTRAP_COMMAND:
-  prizmkit.doc.init
+BOOTSTRAP:
+  Invoke prizmkit-prizm-docs skill (Init operation)
 
 Or manually create these two files following the templates in Section 3.
 
@@ -854,8 +854,8 @@ V1 (2026-03-02): Initial specification
 
 V2 (2026-03-02): Enhanced specification
 - Added ON_DEEP_READ trigger for L2 generation (L2 created during deep analysis, not just modifications)
-- Added prizmkit.doc.validate command for format compliance and consistency checking
-- Added prizmkit.doc.migrate command for converting existing docs to .prizm-docs/ format
+- Added Validate operation for format compliance and consistency checking
+- Added Migrate operation for converting existing docs to .prizm-docs/ format
 - Added RULES hierarchy: root.prizm RULES authoritative, L1/L2 supplement only with module-specific exceptions
 - Added Section 16: Conflict Resolution for multi-person collaboration merge strategies
 - Added Section 17: Version Migration for upgrading between spec versions
@@ -916,7 +916,7 @@ ALGORITHM: prizm_merge_conflict
 
 ## 16.4 Prevention
 
-BEST_PRACTICE: Run prizmkit.doc.update immediately before committing to minimize drift
+BEST_PRACTICE: Run prizmkit-prizm-docs Update operation immediately before committing to minimize drift
 BEST_PRACTICE: Keep .prizm doc changes small and focused (section-level, not file-level rewrites)
 BEST_PRACTICE: Coordinate on MODULE_INDEX changes (adding/removing modules) to avoid structural conflicts
 
@@ -932,7 +932,7 @@ MIGRATION_TRIGGER: AI detects PRIZM_VERSION in root.prizm and applies migration
 
 ## 17.2 V1 to V2 Migration
 
-COMMAND: Automatic on first prizmkit.doc.update or prizmkit.doc.validate after spec upgrade
+TRIGGER: Automatic on first prizmkit-prizm-docs Update or Validate operation after spec upgrade
 
 ALGORITHM: prizm_migrate_v1_to_v2
 
@@ -947,7 +947,7 @@ ALGORITHM: prizm_migrate_v1_to_v2
    FLAG: Any L1/L2 RULES that contradict root.prizm RULES for manual review
 
 3. VALIDATE:
-   Run full prizmkit.doc.validate
+   Run full Validate operation
    REPORT: Migration results and any issues found
 
 4. UPDATE_CHANGELOG: