prizmkit 1.0.45 → 1.0.58

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,31 @@
 ---
 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 spec.md exists yet → run `/prizmkit-specify` first
+- Simple bug fix or config change → use fast path, no plan needed
+- 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:** `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?"
 
-**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
 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 +39,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 +49,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
+
+**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
 
-**HANDOFF:** `prizmkit.analyze` or `prizmkit.implement`
+### 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
 

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

@@ -1,15 +1,28 @@
 ---
 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: "AI-only documentation framework for progressive context loading. Manages .prizm-docs/ with 3-level hierarchy (L0/L1/L2). Use this skill whenever docs need bootstrapping, syncing, checking, validating, rebuilding, or migrating. Trigger on: 'initialize docs', 'update docs', 'sync docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs are stale', 'prizm docs'. Also invoke as part of /prizmkit-init for first-time setup, or before /prizmkit-committer to ensure docs are fresh. (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" |
+
+---
+
+## Operation: Init
 
 Bootstrap .prizm-docs/ for the current project.
 
@@ -17,27 +30,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 +69,7 @@ STEPS:
 
 OUTPUT: List of updated/created/skipped docs with reasons.
 
-### prizmkit.doc.status
+## Operation: Status
 
 Check freshness of all .prizm docs.
 
@@ -71,9 +84,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 +101,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 +118,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 +135,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 +155,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 +165,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: