prizmkit 1.1.1 → 1.1.4

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

@@ -1,14 +1,10 @@
 ---
 name: "prizmkit-committer"
-description: "Pure git commit workflow with safety checks. Stages files, analyzes diff, generates Conventional Commits message, and commits. Does NOT modify .prizm-docs/ — architecture sync is handled by /prizmkit-retrospective before this skill is invoked. Trigger on: 'commit', 'submit', 'finish', 'done', 'ship it', 'save my work'. (project)"
+description: "Pure git commit workflow with safety checks. Stages files, generates Conventional Commits message, and commits. Does NOT modify .prizm-docs/ — run /prizmkit-retrospective first. Trigger on: 'commit', 'submit', 'finish', 'done', 'ship it'. (project)"
 ---
 
 # PrizmKit Committer
 
-Pure git commit workflow. Analyzes changes, generates a Conventional Commits message, performs safety checks, and commits.
-
-**This skill is a pure git commit tool. It does NOT modify any project files — no `.prizm-docs/`, no source code.** It only reads diffs, generates a commit message, and commits. For feature/refactor workflows, run `/prizmkit-retrospective` (and optionally `/prizmkit-deploy` if new infrastructure was introduced) before this skill. For bug fixes, skip retrospective and deploy entirely.
-
 ### When to Use
 - User says "commit", "submit", "finish", "done with this task", "ship it"
 - After `/prizmkit-retrospective` has finished architecture sync
@@ -24,7 +20,7 @@ Pure git commit workflow. Analyzes changes, generates a Conventional Commits mes
 
 ### Workflow
 
-Follow these steps STRICTLY in order:
+Follow these steps in order — skipping or reordering can stage sensitive files or commit without proper verification:
 
 #### Step 1: Status Check
 ```bash
@@ -33,8 +29,8 @@ git status
 - If "nothing to commit, working tree clean": inform user and stop
 - If there are changes: proceed
 
-#### Step 2: Condense Commit
-By consulting the primary agent or based on the existing context, condense this commit message.
+#### Step 2: Generate Commit Message
+Analyze the staged diff and context (spec title, plan summary, review verdict) to generate a concise Conventional Commits message. The message should capture the *what* and *why* of the change.
 
 #### Step 3: Update CHANGELOG.md
 If CHANGELOG.md exists in the project root, append an entry following Keep a Changelog format under the `[Unreleased]` section. Match the existing style in the file.
@@ -65,6 +61,34 @@ git status
 ```
 - If "nothing to commit, working tree clean": commit verified successfully, proceed
 
+#### Step 5.5: Generate Session Summary (for cross-session recovery)
+
+After a successful commit, generate a lightweight handoff file for future sessions. Locate the artifact directory (`.prizmkit/specs/<feature-dir>/` for features, `.prizmkit/refactor/<slug>/` for refactors, `.prizmkit/bugfix/<id>/` for bugfixes) by checking which `plan.md` was used in this workflow.
+
+If an artifact directory with `plan.md` is found, write `session-summary.md` in that directory:
+
+```markdown
+# Session Summary
+## Completed Tasks
+<list task IDs and one-line descriptions from plan.md [x] items>
+
+## Files Changed
+<list from `git diff HEAD~1 --name-only` of the commit just made>
+
+## Key Decisions
+<1-3 bullet points of non-obvious design choices made this session, referencing DECISIONS in .prizm-docs/ if applicable>
+
+## Active TRAPS
+<any CRITICAL or HIGH TRAPS relevant to the changed files, copied from .prizm-docs/ L2>
+
+## Remaining Work
+<list unchecked [ ] task IDs from plan.md, or "None — feature complete" if all done>
+```
+
+Keep this file under 1.5KB. If no artifact directory with `plan.md` can be identified (e.g., ad-hoc commit), skip this step.
+
+**Lifecycle**: `session-summary.md` is a local cross-session artifact — do NOT commit it to git. It exists only on disk for the next session to read. Overwrite any existing `session-summary.md` from a previous session — this file reflects only the most recent commit's state. In pipeline mode, this file will remain as an untracked file after commit; the pipeline runner should ignore it (it is not a sign of incomplete work).
+
 #### Step 6: Optional Push
 Ask user: "Push to remote?"
 - Yes: `git push`

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

@@ -1,14 +1,10 @@
 ---
 name: "prizmkit-deploy"
-description: "Generate or update deployment documentation based on project state and deploy strategy. Produces DEPLOY.md with local dev setup, testing, production deployment, and rollback procedures. Fully autonomous — no user interaction required. Use after /prizmkit-retrospective and before /prizmkit-committer. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'generate deploy', 'update deploy'. (project)"
+description: "Generate or update DEPLOY.md with local dev setup, testing, production deployment, and rollback procedures. Fully autonomous. Use after /prizmkit-retrospective, before /prizmkit-committer. Trigger on: 'deploy docs', 'deployment guide', 'how to deploy', 'DEPLOY.md'. (project)"
 ---
 
 # PrizmKit Deploy
 
-Generate or update deployment documentation by scanning the project's actual state and reading the deployment strategy from `.prizmkit/config.json`. Produces a `DEPLOY.md` at the project root covering local development, testing, production deployment, and rollback.
-
-**This skill generates documentation — it does NOT execute any deployment operations.**
-
 ### When to Use
 - After `/prizmkit-retrospective` and before `/prizmkit-committer` to complete documentation before commit
 - After a batch of features has been implemented and reviewed

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

@@ -1,12 +1,10 @@
 ---
 name: "prizmkit-implement"
-description: "Execute implementation following plan.md tasks. Respects task ordering, dependencies, and TDD approach. Marks tasks complete as they finish. Use this skill whenever you're ready to write code for a planned feature, or for fast-path changes where the user describes a simple fix directly. Trigger on: 'implement', 'build', 'code it', 'start coding', 'develop', 'write the code'. (project)"
+description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan (or /prizmkit-analyze). Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
 ---
 
 # PrizmKit Implement
 
-Execute implementation by following the task breakdown in plan.md. Respects task ordering, dependency constraints, and applies a TDD approach where applicable. Marks each task complete as it finishes.
-
 ### When to Use
 - After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
 - User says "implement", "build", "code it", "start coding", "develop"
@@ -31,8 +29,9 @@ Execute implementation by following the task breakdown in plan.md. Respects task
      - **Feature mode**: read `spec.md` in the same directory
      - **Refactor mode**: read `refactor-analysis.md` in the same directory — pay special attention to Scope Boundary (do not implement changes outside scope) and Baseline Tests (all must still pass)
      - **Bugfix mode**: read `fix-plan.md` in the same directory
-2. Load project context — use the most efficient source available:
+2. Load project context — use the most efficient source available (check in this order):
    - If `context-snapshot.md` exists in the feature directory → read it. Section 3 has Prizm docs + TRAPS. Section 4 has File Manifest (Tier-2/3) or full source (Tier-1). Read source files on-demand as directed by the manifest.
+   - Else if `session-summary.md` exists in the feature directory → read it for quick context recovery (completed tasks, key decisions, active TRAPS). Then load only the L1/L2 docs for modules listed in "Files Changed" — skip unrelated modules.
    - Otherwise → **self-service context fallback**:
      1. Read **architecture index**: `.prizm-docs/root.prizm` and relevant L1/L2 for affected modules. Pay special attention to TRAPS and DECISIONS.
      2. Scan needed source files
@@ -49,53 +48,8 @@ Execute implementation by following the task breakdown in plan.md. Respects task
    f. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
 5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
 6. After all tasks: run full test suite
-7. **Deploy guide update** (only when new frameworks/tools were added):
-   - Check if any dependency manifests were modified in this session:
-     ```bash
-     git diff --name-only HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null
-     ```
-   - If no manifest files changed → skip this step entirely
-   - If manifest files changed, scan for **newly added** dependencies (not version bumps):
-     ```bash
-     git diff -U0 HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null | grep '^\+' | grep -v '^\+\+\+' | head -30
-     ```
-   - For each genuinely new framework/tool, record in `deploy_guide.md` at project root:
-
-     | Field | Description | Source |
-     |-------|-------------|--------|
-     | **Name** | Framework/tool name | Package name from manifest |
-     | **Version** | Installed version or constraint | Version spec from manifest |
-     | **Purpose** | Why it was introduced | You just added it — you know why |
-     | **Install Command** | How to install locally | Standard install command for the ecosystem |
-     | **Key Config** | Config files or env vars needed | Config files you just created/modified |
-     | **Notes** | Setup gotchas, required services | Docker services, manual steps, env vars |
-
-   - Template for `deploy_guide.md`:
-     ```markdown
-     # Deploy Guide
-
-     > Auto-maintained by PrizmKit. Manual edits are preserved.
-     > Last updated: YYYY-MM-DD
-
-     ## Frameworks & Tools
-
-     ### <Framework Name>
-
-     - **Version**: <version constraint>
-     - **Purpose**: <why this framework is used>
-     - **Install**:
-       ```bash
-       <install command>
-       ```
-     - **Key Config**:
-       - `<config file or env var>`: <description>
-     - **Notes**:
-       - <any setup gotchas, required external services, manual steps>
-     ```
-
-   - **Update rules**: create file if absent; append new sections if file exists; update version if framework already documented; preserve manually added content; keep entries sorted alphabetically
-   - **Filter out**: patch version bumps of existing deps, dev-only tools needing no setup (linters, formatters), transitive/lock-file-only changes
-   - Stage the file: `git add deploy_guide.md`
+7. **Deploy guide update** — only when dependency manifests (package.json, requirements.txt, etc.) changed during this task.
+      → Read `${SKILL_DIR}/references/deploy-guide-protocol.md` and follow its protocol.
 8. Output implementation summary with pass/fail status
 
 ## Task Format in plan.md

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

@@ -63,23 +63,16 @@ BROWNFIELD WORKFLOW (existing project):
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
 5. Count source files per directory
-6. Detect detailed tech stack (adaptive — only include fields that apply to this project):
-   - **Language & Runtime**: e.g. TypeScript + Node.js 20, Python 3.11, Go 1.22
-   - **Frontend framework** (if applicable): React, Vue.js, Angular, Next.js, Svelte, etc.
-   - **Frontend styling** (if applicable): Tailwind CSS, SCSS, Styled Components, Material UI, etc.
-   - **Backend framework** (if applicable): Express.js, FastAPI, Django, NestJS, Gin, etc.
-   - **Database** (if applicable): PostgreSQL, MySQL, MongoDB, Redis, SQLite — detected from deps or `docker-compose.yml`
-   - **ORM** (if applicable): Prisma, Drizzle, TypeORM, SQLAlchemy, Mongoose, etc.
-   - **Bundler** (if applicable): Vite, Webpack, esbuild, Rollup, Turborepo
-   - **Testing**: Vitest, Jest, pytest, Go test, etc.
-   - **Project type** (inferred): `frontend` | `backend` | `fullstack` | `library` | `cli` | `monorepo`
+6. Detect detailed tech stack (adaptive — only include fields that apply):
+   → Read `${SKILL_DIR}/references/tech-stack-catalog.md` for the full field catalog.
 
    **IMPORTANT**: Not all projects have all fields. A pure backend API will have no `frontend_framework` or `frontend_styling`. A library may have no database. Only record what is actually detected — never generate empty or placeholder values.
 
 **Step 2: Prizm Documentation Generation**
 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. If module count > 15, use MODULE_GROUPS format instead (group by functional domain).
+  - For each module entry in MODULE_INDEX/MODULE_GROUPS, include keyword tags extracted from the module's source files — scan for: exported symbols, imported packages, domain terms in file/directory names. Format: `- module-name [tag1, tag2, tag3]: ...`. Tags help AI match user intent to relevant 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) — L2 is generated on first file modification, saving tokens upfront
@@ -90,55 +83,7 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - `.prizmkit/specs/` (empty)
 
 3b. Write detected tech stack to `.prizmkit/config.json`:
-
-   **Merge strategy** (handles re-init without losing user edits):
-   - Read existing `config.json` if present
-   - If `tech_stack` field exists AND `_auto_detected` is `false` or absent:
-     → **SKIP** — user has manually configured tech stack, preserve their settings
-   - If `tech_stack` field exists AND `_auto_detected` is `true`:
-     → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result)
-   - If `tech_stack` field does NOT exist:
-     → **WRITE** full detected tech stack with `"_auto_detected": true`
-   - Only include fields that were actually detected (no empty/null values)
-
-   Example config.json after init (fullstack project):
-   ```json
-   {
-     "adoption_mode": "passive",
-     "platform": "claude",
-     "tech_stack": {
-       "language": "TypeScript",
-       "runtime": "Node.js 20",
-       "frontend_framework": "React",
-       "frontend_styling": "Tailwind CSS",
-       "backend_framework": "Express.js",
-       "database": "PostgreSQL",
-       "orm": "Prisma",
-       "testing": "Vitest",
-       "bundler": "Vite",
-       "project_type": "fullstack",
-       "_auto_detected": true
-     }
-   }
-   ```
-
-   Example config.json after init (pure Python backend):
-   ```json
-   {
-     "adoption_mode": "passive",
-     "platform": "claude",
-     "tech_stack": {
-       "language": "Python",
-       "runtime": "Python >=3.11",
-       "backend_framework": "FastAPI",
-       "database": "PostgreSQL",
-       "orm": "SQLAlchemy",
-       "testing": "pytest",
-       "project_type": "backend",
-       "_auto_detected": true
-     }
-   }
-   ```
+   → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
 **Step 4: Hook & Settings Configuration**
 
@@ -165,16 +110,7 @@ Tech stack detected:
   Project type: fullstack
 ```
 
-For a pure backend Python project, the report would show:
-```
-Tech stack detected:
-  Language:     Python
-  Runtime:      Python >=3.11
-  Backend:      FastAPI
-  Database:     PostgreSQL (SQLAlchemy)
-  Testing:      pytest
-  Project type: backend
-```
+Adapt fields to match project type — only show detected fields.
 
 Saved to: `.prizmkit/config.json` → `tech_stack` field
 
@@ -243,12 +179,7 @@ Next: Use /prizmkit-plan to start your first feature
 ```
 
 UPDATE SUPPLEMENT (runs after tech stack merge in Update mode):
-
-1. **Module scan**: Re-scan project directories using the same TWO-TIER model from Step 1. Compare discovered modules against existing MODULE_INDEX in root.prizm.
-2. **Missing L1 check**: For any discovered module with no corresponding L1 `.prizm` doc → create L1 immediately and add to MODULE_INDEX.
-3. **Missing L2 check**: For any module/sub-module that has source files with meaningful logic but no L2 `.prizm` doc → create L2 using the L2 GENERATION TEMPLATE. Judgment call: skip trivial wrapper directories or single-config modules.
-4. **Stale L1 check**: For existing L1 docs, verify FILES count and KEY_FILES are still accurate. Update if source directory contents have changed significantly.
-5. **Report**: Include in the Update report: modules added, L1 docs created, L2 docs created, stale docs refreshed.
+→ Read `${SKILL_DIR}/references/update-supplement.md` for the 5-step gap-fill procedure.
 
 **Re-init after PrizmKit upgrade (existing config preserved):**
 ```
@@ -270,5 +201,3 @@ Documentation gap-fill:
 
 Merged into .prizmkit/config.json (2 fields updated, user overrides preserved)
 ```
-
-IMPORTANT: Use `${SKILL_DIR}` placeholder for all path references. Never hardcode absolute paths.

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

@@ -1,12 +1,10 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan features in one step. Transforms natural language into structured spec.md, then generates plan.md with architecture and executable tasks. Use this skill whenever the user wants to define a feature, write requirements, design implementation, or break work into tasks. Trigger on: 'specify', 'plan', 'new feature', 'I want to add...', 'I want to build...', 'architect', 'design', 'break it down', 'create tasks', 'how to build', 'let's add', 'feature idea'. Always use before /prizmkit-implement. Skip specify phase for bug fixes or simple refactors. (project)"
+description: "Specify and plan features: natural language → spec.md → plan.md with architecture and executable tasks. Supports feature, refactor, and bugfix modes. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new feature', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
 ---
 
 # PrizmKit Plan
 
-Define WHAT to build, then design HOW to build it — in one continuous flow. Phase 0 produces `spec.md` (requirements), Phase 1-2 produce `plan.md` (architecture + tasks).
-
 ### When to Use
 - New feature — user says "specify", "plan", "new feature", "I want to add..."
 - Before `/prizmkit-implement` — to create the spec + task breakdown
@@ -99,15 +97,6 @@ If no input document exists, prompt user to describe the feature (triggers Phase
 
 **HANDOFF:** `/prizmkit-implement`
 
-## Handling Vague Inputs
-
-When the user's description is vague:
-1. Extract what IS clear and write it into the spec
-2. Mark ambiguous parts with `[NEEDS CLARIFICATION]` + recommended default
-3. Auto-clarification (Phase 0, step 9) resolves interactively before planning
-
-Never block progress — always produce a usable spec, even with open questions.
-
 ## Example
 
 **Input:** "I want users to upload avatars"

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

@@ -52,6 +52,8 @@ STEPS:
    - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/. If total 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>/.
 4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, PATTERNS, and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No UPDATED timestamp — git tracks modification times.
+   - If module count > 15: use MODULE_GROUPS format instead of MODULE_INDEX — group modules by functional domain (3-8 domains, inferred from directory structure and module responsibilities). See PRIZM-SPEC for MODULE_GROUPS format.
+   - For each module entry, auto-generate 3-6 keyword tags by scanning the module's key source files for: exported function/class names, imported library names, domain-specific terms in file/directory names. Add tags in square brackets after the module name (e.g., `- auth [login, session, jwt]: ...`). Tags are optional but recommended for projects with 10+ modules.
 5. Generate L1 .prizm files (structural index only) for ALL 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
@@ -72,9 +74,9 @@ 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 — this includes checking for modules that have source files but no L2 doc.
-2. Map changed files to modules by matching against MODULE_INDEX in root.prizm. Group changes by module.
+2. Map changed files to modules by matching against MODULE_INDEX or MODULE_GROUPS in root.prizm. Group changes by module.
 3. Classify each change: A (added) -> new KEY_FILES entries. D (deleted) -> remove entries, update counts. M (modified) -> check dependency changes. R (renamed) -> update all path references.
-4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, CHANGELOG), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times.
+4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, CHANGELOG), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX or MODULE_GROUPS counts, CROSS_CUTTING) only if structural change. No UPDATED timestamps — git tracks modification times.
 5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only .prizm files changed. DO NOT skip test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
 6. If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA) and matches no existing module: create L1 immediately, add to MODULE_INDEX. If the current diff includes Added or Modified source files in this module → also create L2 immediately using the L2 GENERATION TEMPLATE. Otherwise defer L2.
 6a. **L2 gap check** (runs during full rescan mode only — when no git changes detected): For each existing module in MODULE_INDEX, check if L2 doc exists. If L2 is missing and the module has source files with meaningful logic (not trivial config/wrapper) → create L2 using the L2 GENERATION TEMPLATE. This ensures Update fills documentation gaps left by previous sessions.
@@ -110,7 +112,7 @@ STEPS:
 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.
+5. Update MODULE_INDEX (or MODULE_GROUPS) in root.prizm with new file counts and pointers. Re-evaluate grouping: if total module count > 15 and currently using MODULE_INDEX, convert to MODULE_GROUPS. Regenerate keyword tags for rebuilt modules.
 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.
 
@@ -124,12 +126,13 @@ 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. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
-2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 3KB, L2 <= 5KB. Report files exceeding limits with current size.
+2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 4KB, 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. STALENESS CHECK: Compare git modification time of each .prizm file against source directory. Flag docs where source was modified more recently.
-5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
+5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX or MODULE_GROUPS). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
 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.
+8. TRAPS STALENESS CHECK: For each L2 doc where TRAPS section has more than 8 entries, verify that TRAPS include staleness metadata (`STALE_IF:` or `REF:` fields). Flag TRAPS without any staleness metadata as `NEEDS_METADATA` — these are not auto-removed, but flagged for the next `/prizmkit-retrospective` to enrich with `STALE_IF:` globs or `REF:` hashes.
 
 OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.
 
@@ -157,29 +160,11 @@ OUTPUT: Migration report with list of source docs processed, generated .prizm fi
 - **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/:
-
-- 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. If L2 does not exist and you are creating/modifying significant source files in this module → generate L2 using the L2 GENERATION TEMPLATE before proceeding.
-- 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: Run `/prizmkit-retrospective` which is the **sole maintainer** of .prizm-docs/. It handles structural sync and TRAPS/RULES/DECISIONS injection to `.prizm-docs/`.
-- The UserPromptSubmit hook will remind you automatically when commit intent is detected.
-- `/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
-
-- 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.
+### Key Protocols (reference)
+For detailed protocol specifications, see PRIZM-SPEC:
+- Progressive Loading: Section 6.1
+- Auto-Update: Section 7.1
+- RULES hierarchy: Section 3.1
 
 ## Examples
 

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

@@ -8,6 +8,27 @@ LICENSE: MIT
 
 ---
 
+## Table of Contents
+
+1. Overview (L32–49)
+2. Architecture (L50–127)
+3. Document Format Specification (L128–308)
+4. Format Conventions (L309–321)
+5. Path Mapping Rules (L322–351)
+6. Progressive Loading Protocol (L352–411)
+7. Auto-Update Protocol (L412–491)
+8. Anti-Patterns (L492–511)
+9. Initialization Procedure (L512–646)
+10. Skill Definition (L647–768)
+11. Hook Configuration (L769–823)
+12. Language-Specific Initialization Hints (L824–857)
+13. Minimal Viable Prizm (L858–875)
+14. Version History (L876–920)
+15. Conflict Resolution (L921–978)
+16. Version Migration (L979–1087)
+
+---
+
 # SECTION 1: OVERVIEW
 
 WHAT: Prizm is a self-maintaining documentation system where AI reads, generates, updates, and loads project context progressively.
@@ -161,6 +182,36 @@ CONSTRAINTS:
 - No prose paragraphs
 - root.prizm RULES are AUTHORITATIVE: they override any conflicting L1/L2 RULES
 
+### MODULE_GROUPS (alternative to MODULE_INDEX for projects with 15+ modules)
+
+When MODULE_INDEX would exceed 15 entries, replace it with MODULE_GROUPS to stay within the 4KB limit. Group modules by functional domain:
+
+  MODULE_GROUPS:
+    <domain-name>:
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+    <domain-name>:
+      - <module>: <file-count> files. <one-line description>. -> .prizm-docs/<module>.prizm
+
+CONSTRAINTS for MODULE_GROUPS:
+- Exactly ONE of MODULE_INDEX or MODULE_GROUPS must be present in root.prizm (not both)
+- Domain names: lowercase, descriptive (e.g., api, frontend, infrastructure, shared, data)
+- 3-8 domains is the ideal range
+- Each module appears in exactly one domain
+- Every entry must have an arrow pointer (->), same as MODULE_INDEX
+- AI should load the relevant domain's modules when working on a task, not all domains
+
+### Optional Keyword Tags (applies to both MODULE_INDEX and MODULE_GROUPS)
+
+Entries may include keyword tags for AI intent matching:
+
+  MODULE_INDEX:
+    - auth [login, session, jwt, oauth]: 12 files. Authentication and authorization. -> .prizm-docs/auth.prizm
+    - payments [stripe, billing, subscription]: 8 files. Payment processing. -> .prizm-docs/payments.prizm
+    - users: 6 files. User management. -> .prizm-docs/users.prizm
+
+Tags are optional, enclosed in square brackets after the module name. They contain lowercase keywords that describe the module's domain concepts. AI matches user requirement descriptions against tags to identify relevant modules before loading L1. Tags are auto-generated during Init from module source content (function names, imports, domain terms) and refined during Rebuild.
+
 ## 3.2 L1: module.prizm (Structural Index)
 
 TEMPLATE:
@@ -561,7 +612,7 @@ STEPS:
 
 4. GENERATE_ROOT (L0):
    Fill: PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY from step 1
-   Build: MODULE_INDEX — list modules at the depth needed for efficient navigation, with arrow pointers
+   Build: MODULE_INDEX (or MODULE_GROUPS if 15+ modules — see Section 3.1) — list modules at the depth needed for efficient navigation, with arrow pointers
    Extract: RULES from existing README, .editorconfig, linter configs
    Extract: PATTERNS from common code patterns observed in step 2
    Extract: CROSS_CUTTING — identify patterns/constraints that span 2+ modules