prizmkit 1.1.3 → 1.1.5

package/bundled/dev-pipeline/templates/sections/checkpoint-system.md

@@ -0,0 +1,36 @@
+## Workflow Checkpoint System
+
+A checkpoint file tracks your progress through this workflow:
+
+**Path**: `{{CHECKPOINT_PATH}}`
+
+### Rules
+
+1. **Before each skill**: Read `workflow-checkpoint.json`, verify the previous step has `status: "completed"` or `status: "skipped"`. If it is still `"pending"` or `"in_progress"`, you MUST complete it first before moving on.
+
+2. **Starting a skill**: Update the current step to `status: "in_progress"`.
+
+3. **After each skill completes**: Update the current step to `status: "completed"`. Then immediately re-read the file to verify the JSON is valid. If the read fails, re-write the file with correct JSON.
+
+4. **On failure**: Set the step to `status: "failed"` and continue to the next step if possible, or halt and write failure-log.md.
+
+5. **On session exit**: The checkpoint file reflects your actual progress. Do NOT manually set future steps to "completed".
+
+### Checkpoint Update Pattern
+
+After completing each skill:
+
+1. Read `{{CHECKPOINT_PATH}}`
+2. Update the current step `"status": "completed"`
+3. Update the next step `"status": "in_progress"`
+4. Write the updated JSON back to `{{CHECKPOINT_PATH}}`
+5. Verify: `python3 -c "import json; json.load(open('{{CHECKPOINT_PATH}}'))"` — if this fails, re-write
+
+### Resume Behavior
+
+**Checkpoint is the primary source of truth for resume.** On retry sessions:
+
+1. Read `workflow-checkpoint.json` — steps already `"completed"` or `"skipped"` are skipped
+2. Start from the first `"pending"` or `"in_progress"` step
+3. If `failure-log.md` exists, read it for diagnostic context (why the previous session failed, what approach to try differently) — but do NOT use it to determine which step to resume from
+4. If `workflow-checkpoint.json` is missing or corrupted, fall back to `failure-log.md` + the resume phase as the legacy mechanism

package/bundled/dev-pipeline/templates/sections/failure-log-check.md

@@ -1,4 +1,4 @@
-**Check for previous failure log:**
+**Check for previous failure log** (diagnostic context only — do NOT use to determine resume point):
 ```bash
 cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
 ```
@@ -6,3 +6,4 @@ If failure-log.md exists:
 - Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
 - Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during the commit phase retrospective
 - Do NOT delete failure-log.md until this session completes all phases and commits successfully
+- **Note**: The resume point is determined by `workflow-checkpoint.json`, not by failure-log.md

package/bundled/dev-pipeline/templates/sections/phase-analyze-agent.md

@@ -14,3 +14,6 @@ Wait for Reviewer to return.
 - If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in plan.md. Then re-run analyze (max 1 round).
 
 **CP-2**: No CRITICAL issues.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-analyze` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-analyze-full.md

@@ -14,3 +14,6 @@ Wait for Reviewer to return.
 - If CRITICAL issues found: fix them yourself — read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full project context. Fix ONLY the listed CRITICAL issues in spec.md/plan.md. Then re-run analyze (max 1 round).
 
 **CP-2**: No CRITICAL issues.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-analyze` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md

@@ -30,3 +30,6 @@ You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without
    ```
 
 If verification fails, log the failure details but continue to commit. Failures do NOT block the commit, but you MUST attempt verification and MUST clean up the dev server.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `browser-verification` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-commit-full.md

@@ -34,3 +34,6 @@ This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT
 git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+
+
+**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-commit.md

@@ -24,3 +24,6 @@ This single commit includes: feature code + tests + .prizm-docs/ updates. Do NOT
 git status --short
 ```
 Working tree MUST be clean after this step. If any feature-related files remain, stage them into the SAME commit via `git add <file> && git commit --amend --no-edit`, do NOT create a separate commit.
+
+
+**Checkpoint update**: After `/prizmkit-retrospective` completes, update `workflow-checkpoint.json` — set step `prizmkit-retrospective` to `"completed"`. After `/prizmkit-committer` completes, set step `prizmkit-committer` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-agent-suffix.md

@@ -12,3 +12,6 @@
 
      ### Known TRAPS (from .prizm-docs/)
      - <trap entries extracted from L1/L2 docs>
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-context-snapshot-lite-suffix.md

@@ -1,3 +1,6 @@
    - **Section 3 — Prizm Context**: content of root.prizm and relevant L1/L2 docs
    - **Section 4 — Existing Source Files**: **full verbatim content** of each related file in fenced code blocks (with `### path/to/file` heading and line count). Include ALL files needed for implementation and review — downstream phases read this section instead of re-reading individual source files
    - **Section 5 — Existing Tests**: full content of related test files as code block
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-critic-code.md

@@ -20,3 +20,6 @@ Wait for Critic to return.
 - Read challenge-report.md. For items marked CRITICAL/HIGH: spawn Dev to fix, then proceed to Review.
 
 **CP-3.5**: Code challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-code-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-critic-plan-full.md

@@ -42,3 +42,6 @@ After all critics return, read all 3 reports:
 - Max 1 plan revision round.
 
 **CP-2.5**: Plan challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-critic-plan.md

@@ -21,3 +21,6 @@ Wait for Critic to return.
 - Max 1 plan revision round.
 
 **CP-2.5**: Plan challenges reviewed and resolved.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `critic-plan-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-deploy-verification.md

@@ -34,3 +34,6 @@ Deploy verification does NOT block the commit, but you MUST attempt it.
 4. Record smoke test results in `## Deploy Verification` section
 
 If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `deploy-verification` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-implement-agent.md

@@ -19,3 +19,6 @@ After Dev agent returns, verify the Implementation Log was written:
 grep -q "## Implementation Log" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
 If GATE:MISSING — send message to Dev (re-spawn if needed): "Write the '## Implementation Log' section to context-snapshot.md before I can proceed to review. Include: files changed/created, key decisions, deviations from plan, notable discoveries."
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-implement-full.md

@@ -32,3 +32,6 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
 3. Max 2 recovery retries. After 2 failures, orchestrator implements remaining tasks directly.
 
 All tasks `[x]`, tests pass.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-implement-lite.md

@@ -30,3 +30,6 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 4. If any criterion is not met, fix it now (max 2 fix rounds)
 
 **CP-2**: All acceptance criteria met, all tests pass.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-implement` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-plan-agent.md

@@ -15,3 +15,6 @@ Before proceeding past CP-1, verify:
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
 **CP-1**: plan.md exists with Tasks section.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-plan-lite.md

@@ -14,3 +14,6 @@ Before proceeding past CP-1:
 3. Resolve all uncertain DB design decisions before writing Tasks — document choices in plan.md
 
 **CP-1**: plan.md exists with Tasks section.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-plan` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-review-agent.md

@@ -21,3 +21,6 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 - If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in snapshot), re-run Review (max 3 rounds)
 
 **CP-3**: Tests pass, verdict is not NEEDS_FIXES.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-review-full.md

@@ -23,3 +23,6 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
   Then re-run Review (max 3 rounds).
 
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-code-review` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md

@@ -80,3 +80,6 @@ Before proceeding past CP-1, verify:
 4. If a DB design decision genuinely cannot be resolved from existing code alone, document the assumption made and flag it in the Implementation Log for user review.
 
 **CP-1**: Both spec.md and plan.md exist.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `context-snapshot-and-plan` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase0-init.md

@@ -2,3 +2,6 @@
 - Run `/prizmkit-init` (invoke the prizmkit-init skill)
 - Run `python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEATURE_ID}} --feature-slug {{FEATURE_SLUG}}`
 - **CP-0**: Verify `.prizm-docs/root.prizm`, `.prizmkit/config.json` exist
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `prizmkit-init` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/phase0-test-baseline.md

@@ -10,3 +10,6 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 Save the list of **pre-existing failing tests** (if any) as `BASELINE_FAILURES`. These are known failures that existed before this session — Dev must NOT be blamed for them, but must list them in COMPLETION_SIGNAL.
 
 > **Test Output Rule**: Always capture test output to a temp file (`tee /tmp/test-out.txt`). Then grep the file instead of re-running the suite.
+
+
+**Checkpoint update**: Update `workflow-checkpoint.json` — set step `test-baseline` to `"completed"`.

package/bundled/dev-pipeline/templates/sections/resume-header.md

@@ -1,2 +1,5 @@
 ### Resume from Phase {{RESUME_PHASE}}
-Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, skip context building and use it directly.
+
+**Primary**: Read `{{CHECKPOINT_PATH}}` — find the first step with `"pending"` or `"in_progress"` status and resume from there. Steps already `"completed"` or `"skipped"` must NOT be re-executed.
+
+**Fallback**: If `workflow-checkpoint.json` is missing or corrupted, check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, skip context building and use it directly.

package/bundled/rules/prizm/prizm-commit-workflow.md

@@ -8,3 +8,4 @@ Before any git commit in this project:
 3. Bug fixes use `fix()` prefix, not `feat()`
 4. Bug fixes run retrospective with structural sync only (Job 1)
 5. Use `/prizmkit-committer` command for the pure commit workflow
+6. After commit, `/prizmkit-committer` generates `session-summary.md` (lightweight cross-session handoff, not committed to git)

package/bundled/rules/prizm/prizm-documentation.md

@@ -18,19 +18,20 @@ WHEN TO UPDATE .prizm-docs/:
 - Before modifying any source file, read `.prizm-docs/root.prizm` if it exists to understand project structure.
 
 FORMAT RULES (enforced by pre-commit hook — violations block commit):
-- ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, UPDATED:, etc.
+- ALL CAPS section headers: MODULE:, FILES:, RESPONSIBILITY:, etc.
 - KEY: value pairs and dash-prefixed lists only
 - PROHIBITED: prose paragraphs, markdown headers (##/###), code blocks (```), emoji, ASCII art
+- No UPDATED timestamps — git is the authoritative source for temporal information
 - This format is designed for AI token efficiency, not human readability. Do not add human-friendly formatting.
 
 SIZE LIMITS (hard — pre-commit hook blocks commits exceeding these):
 - L0 root.prizm: 4KB max
-- L1 module.prizm: 3KB max
+- L1 module.prizm: 4KB max
 - L2 detail.prizm: 5KB max
 
 SIZE OVERFLOW HANDLING:
-- L0 approaching 4KB: consolidate MODULE_INDEX, keep only top-5 RULES, remove PATTERNS detail
-- L1 approaching 3KB: move implementation details to L2, keep only INTERFACES signatures
+- L0 approaching 4KB: if MODULE_INDEX has > 15 entries, convert to MODULE_GROUPS format (group by domain). Otherwise consolidate descriptions, keep only top-5 RULES, remove PATTERNS detail.
+- L1 approaching 4KB: trim KEY_FILES descriptions, ensure RULES <= 3 entries, move detail to L2
 - L2 approaching 5KB: archive CHANGELOG entries older than 90 days to changelog-archive.prizm
 - NEVER exceed hard limits — pre-commit hook will block the commit
 
@@ -40,26 +41,24 @@ L0 root.prizm:
 - PRIZM_VERSION
 - PROJECT
 - LANG
-- MODULE_INDEX (with -> pointers to L1 files)
+- MODULE_INDEX or MODULE_GROUPS (with -> pointers to L1 files)
 - RULES (top-level project rules)
-- UPDATED
 
-L1 module.prizm:
+L1 module.prizm (structural index only):
 - MODULE
 - FILES
 - RESPONSIBILITY
-- INTERFACES (public/exported only)
 - DEPENDENCIES
-- UPDATED
+- L1 does NOT contain: INTERFACES, DATA_FLOW, TRAPS, DECISIONS (those belong in L2)
 
 L2 detail.prizm:
 - MODULE
 - FILES
 - KEY_FILES
 - DEPENDENCIES
-- TRAPS
+- INTERFACES
+- TRAPS (with severity prefix: [CRITICAL], [HIGH], or [LOW])
 - CHANGELOG
-- UPDATED
 
 L2 GENERATION TEMPLATE (use when AI first touches a sub-module with no L2 doc):
 
@@ -71,10 +70,11 @@ KEY_FILES:
 DEPENDENCIES:
 - uses: <lib>: <why>
 - imports: <module>: <what>
+INTERFACES:
+- <exported function/class>: <signature and purpose>
 TRAPS:
-- <gotcha, race condition, or non-obvious coupling>
+- [LOW] <gotcha, race condition, or non-obvious coupling> | FIX: <approach>
 CHANGELOG:
-- <YYYY-MM-DD> | add: initial L2 documentation
-UPDATED: <YYYY-MM-DD>
+- root | add: initial L2 documentation
 
-TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules.
+TRAPS is critical — always record gotchas, race conditions, non-obvious behavior, and surprising coupling between modules. Every TRAP must have a severity prefix ([CRITICAL], [HIGH], or [LOW]).

package/bundled/rules/prizm/prizm-progressive-loading.md

@@ -4,7 +4,8 @@ description: "PrizmKit progressive context loading protocol"
 
 This project uses PrizmKit's progressive loading protocol:
 - ON SESSION START: Read `.prizm-docs/root.prizm` (L0 — project map)
-- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules
+- ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
+- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules. If MODULE_INDEX entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task description against tags to prioritize which modules' L1 to load first. If root.prizm uses MODULE_GROUPS, identify the relevant domain first, then load L1 only for modules in that domain.
 - ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying
 - NEVER load all .prizm docs at once
 - Arrow notation (->) in .prizm files indicates load pointers

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.3",
+  "version": "1.1.5",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",

package/bundled/skills/prizm-kit/assets/project-memory-template.md

@@ -5,7 +5,8 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 
 ### Progressive Loading Protocol
 - ON SESSION START: Always read `.prizm-docs/root.prizm` first (L0 — project map)
-- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules referenced in MODULE_INDEX
+- ON RESUME (feature/bugfix directory has session-summary.md): Read session-summary.md first for prior context, then load only L1/L2 for modules mentioned in it
+- ON TASK: Read L1 (`.prizm-docs/<module>.prizm`) for relevant modules referenced in MODULE_INDEX or MODULE_GROUPS. If entries have keyword tags (e.g., `[login, jwt, oauth]`), match user's task against tags to prioritize which modules to load.
 - ON FILE EDIT: Read L2 (`.prizm-docs/<module>/<submodule>.prizm`) before modifying files. Pay attention to TRAPS and DECISIONS.
 - NEVER load all .prizm docs at once. Load only what is needed for the current task.
 
@@ -16,9 +17,10 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
 
 ### Doc Format Rules
 - All `.prizm` files use KEY: value format, not prose
-- Size limits: L0 = 4KB, L1 = 3KB, L2 = 5KB
+- Size limits: L0 = 4KB, L1 = 4KB, L2 = 5KB
 - Arrow notation (->) indicates load pointers to other .prizm docs
 - DECISIONS and CHANGELOG are append-only (never delete entries)
+- No date/time fields — git is the authoritative source for temporal info
 
 ### Creating New L2 Docs
 - When you first modify files in a sub-module that has no L2 doc:

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

@@ -61,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-implement/SKILL.md

@@ -29,8 +29,9 @@ description: "Execute plan.md tasks with TDD approach. Respects task ordering an
      - **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

package/bundled/skills/prizmkit-implement/references/deploy-guide-protocol.md

@@ -0,0 +1,69 @@
+# Deploy Guide Update Protocol
+
+When dependency manifests change during implementation, update `deploy_guide.md` at the project root.
+
+## Detection
+
+1. 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
+   ```
+2. If no manifest files changed → skip this step entirely
+3. 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
+   ```
+
+## Recording
+
+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
+
+## Final Step
+
+Stage the file: `git add deploy_guide.md`

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

@@ -71,7 +71,8 @@ BROWNFIELD WORKFLOW (existing project):
 **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

package/bundled/skills/prizmkit-init/references/config-schema.md

@@ -0,0 +1,64 @@
+# config.json Schema — Tech Stack Fields
+
+## 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)
+
+## Field Definitions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `adoption_mode` | string | `"passive"` \| `"advisory"` \| `"active"` |
+| `platform` | string | `"codebuddy"` \| `"claude"` \| `"both"` |
+| `tech_stack` | object | Detected or user-provided tech stack |
+| `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
+
+## Examples
+
+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
+  }
+}
+```
+
+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
+  }
+}
+```

package/bundled/skills/prizmkit-init/references/tech-stack-catalog.md

@@ -0,0 +1,13 @@
+# Tech Stack Detection — Field Catalog
+
+Adaptive field list — only include fields that apply to the project being scanned.
+
+- **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`

package/bundled/skills/prizmkit-init/references/update-supplement.md

@@ -0,0 +1,9 @@
+# Update Supplement — Post-Merge Gap-Fill Procedure
+
+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.

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

@@ -0,0 +1,56 @@
+# Feature: [FEATURE_TITLE]
+
+## Overview
+[One paragraph describing the feature purpose and business value]
+
+## User Stories
+
+### US1: [Story Title]
+**As a** [role]
+**I want** [capability]
+**So that** [benefit]
+
+**Acceptance Criteria:**
+- [ ] Given [context], When [action], Then [expected result]
+
+## Scope
+
+### In Scope
+- [Item 1]
+
+### Out of Scope
+- [Item 1]
+
+## Dependencies
+- [Dependency 1]: [Why needed]
+
+## Data Model (if feature involves database changes)
+
+### Existing Schema Reference
+<!-- Read existing schema/model files BEFORE designing new tables. Document observed conventions here. -->
+- Tables reviewed: [list existing tables related to this feature]
+- Naming convention: [snake_case/camelCase — match existing]
+- ID strategy: [UUID/auto-increment — match existing]
+- Timestamp pattern: [created_at/updated_at — match existing]
+- Soft delete: [yes/no, field name — match existing]
+
+### New/Modified Entities
+| Entity | Type (new/modify) | Key Fields | Relationships | Constraints |
+|--------|-------------------|------------|---------------|-------------|
+| [entity_name] | new | [field: type] | [FK to existing_table] | [NOT NULL, UNIQUE, etc.] |
+
+### Open Data Model Questions
+<!-- All questions here MUST be resolved before /prizmkit-plan generates Tasks -->
+- [NEEDS CLARIFICATION] [Any uncertain data model decisions — field types, nullability, relationships]
+
+## Constraints
+- [Constraint 1]
+
+## Clarifications
+[NEEDS CLARIFICATION]: [Ambiguous item]
+
+## Review Checklist
+- [ ] All user stories have acceptance criteria
+- [ ] Scope boundaries are clearly defined
+- [ ] Dependencies are identified
+- [ ] No implementation details (WHAT not HOW)