prizmkit 1.0.19 → 1.0.21

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.19",
-  "bundledAt": "2026-03-15T15:17:35.921Z",
-  "bundledFrom": "7fb7d0a"
+  "frameworkVersion": "1.0.21",
+  "bundledAt": "2026-03-15T16:24:08.378Z",
+  "bundledFrom": "db1bf04"
 }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.19",
+  "version": "1.0.21",
   "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/prizmkit-init/SKILL.md

@@ -34,16 +34,20 @@ BROWNFIELD WORKFLOW (existing project):
 
 **Step 1: Project Scanning**
 1. Detect tech stack from build files (`package.json`, `requirements.txt`, `go.mod`, `pom.xml`, `Cargo.toml`, etc.)
-2. Map directory structure — identify source directories, test directories, config files
+2. Map directory structure using a TWO-TIER model — do NOT flatten:
+   - 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
+   - 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:
-  - Create `.prizm-docs/` directory structure
-  - Generate `root.prizm` (L0) with project meta and module index
-  - Generate L1 docs for all discovered modules
+2a. Invoke prizmkit-prizm-docs `prizmkit.doc.init` algorithm, 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 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)
 

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

@@ -17,10 +17,17 @@ PRECONDITION: No .prizm-docs/ directory exists, or user confirms overwrite.
 
 STEPS:
 1. Detect project type by scanning for build system files (go.mod, package.json, requirements.txt, Cargo.toml, pom.xml, *.csproj). Identify primary language, framework, build command, test command, and entry points.
-2. Discover modules by finding directories with 3+ source files. Recognize common patterns (controllers/, services/, models/, components/, hooks/, utils/, lib/, pkg/, internal/, cmd/, api/, routes/, middleware/). Exclude vendor/, node_modules/, .git/, build/, dist/, __pycache__/, target/, bin/. If module count > 30, ask user for include/exclude patterns.
-3. Create .prizm-docs/ directory structure mirroring the source tree.
-4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with arrow pointers, RULES extracted from CODEBUDDY.md/README/linter configs, and PATTERNS. Set PRIZM_VERSION: 2, UPDATED: today's date. Max 4KB.
-5. Generate L1 .prizm files for each discovered module. Each L1 includes MODULE, FILES count, RESPONSIBILITY, SUBDIRS with pointers, KEY_FILES (5-10 most important), INTERFACES (public/exported only), DEPENDENCIES (imports, imported-by, external), RULES, DATA_FLOW. Max 3KB each.
+2. Discover modules in TWO tiers — DO NOT FLATTEN the directory hierarchy:
+   - 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.
+   - 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.
+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).
 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.

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

@@ -468,33 +468,62 @@ STEPS:
    - Java: *Application.java, Main.java
 
 2. DISCOVER_MODULES:
-   SCAN source directories:
-   - Find directories containing 3+ source files of the primary language
-   - Recognize common patterns: controllers/, services/, models/, components/, hooks/, utils/, lib/, pkg/, internal/, cmd/, api/, routes/, middleware/
-   - Each qualifying directory = one module candidate
+   SCAN source directories, preserving the tree structure (DO NOT FLATTEN):
+
+   a. IDENTIFY TOP-LEVEL modules: directories directly under project root (or directly under src/ for src-based layouts) that either:
+      - Contain 3+ source files of the primary language, OR
+      - Contain sub-directories that each have 3+ source files
+      RESULT: top_modules = [dev-pipeline, src, internal, app, ...]
+
+   b. IDENTIFY SUB-MODULES: for each top-level module M, find directories INSIDE M that contain 3+ source files
+      RESULT: sub_modules[M] = [scripts, lib, templates, ...]  (relative names, not full paths)
+
+   c. HIERARCHY RULE: if directory X lives inside top-level module M, X is a sub-module of M — NOT a separate top-level module.
+      WRONG: dev-pipeline/scripts/ treated as top-level module -> .prizm-docs/scripts.prizm
+      CORRECT: dev-pipeline/scripts/ is a sub-module of dev-pipeline -> .prizm-docs/dev-pipeline/scripts.prizm
+
+   d. MODULE_INDEX in root.prizm lists ONLY top-level modules from step 2a.
+      Sub-modules appear in their parent's L1 doc SUBDIRS section, not in MODULE_INDEX.
+
    - EXCLUDE: vendor/, node_modules/, .git/, build/, dist/, __pycache__/, target/, bin/
-   IF module count > 30: ASK user for include/exclude patterns
+   IF top-level module count > 30: ASK user for include/exclude patterns
 
 3. CREATE_DIRECTORY_STRUCTURE:
    Create .prizm-docs/ directory
-   Create subdirectories mirroring source module tree
+   For each top-level module M that has sub-modules: create .prizm-docs/<M>/ directory
+   RULE: .prizm-docs/ directory tree must mirror the source directory tree exactly
+   EXAMPLE:
+     source: dev-pipeline/scripts/  -> prizm: .prizm-docs/dev-pipeline/scripts.prizm
+     source: dev-pipeline/lib/      -> prizm: .prizm-docs/dev-pipeline/lib.prizm
+     source: dev-pipeline/          -> prizm: .prizm-docs/dev-pipeline.prizm
+   NEVER create .prizm-docs/scripts.prizm for a directory that lives at dev-pipeline/scripts/
 
 4. GENERATE_ROOT (L0):
    Fill: PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY from step 1
-   Build: MODULE_INDEX from step 2 (one entry per module with file count and pointer)
-   Extract: RULES from existing CODEBUDDY.md, README, .editorconfig, linter configs
+   Build: MODULE_INDEX — list ONLY top-level modules from step 2a, one entry per module with pointer to .prizm-docs/<M>.prizm
+   NEVER list sub-modules in MODULE_INDEX (sub-modules are navigated via L1 SUBDIRS pointers)
+   Extract: RULES from existing CODEBUDDY.md, CLAUDE.md, README, .editorconfig, linter configs
    Extract: PATTERNS from common code patterns observed in step 2
    Set: PRIZM_VERSION: 2, UPDATED: today's date
 
 5. GENERATE_L1_DOCS:
-   FOR EACH module in MODULE_INDEX:
-     SCAN module directory:
-     - Count all source files
+   FOR EACH top-level module M in MODULE_INDEX:
+     SCAN M directory:
+     - Count all source files (direct files only, not recursive)
      - Identify exported/public interfaces (language-specific: exported funcs in Go, export in JS/TS, public in Java, pub in Rust)
      - Trace import/require/use statements for DEPENDENCIES
-     - Identify subdirectories for SUBDIRS
+     - List sub-modules from step 2b in SUBDIRS with pointers: .prizm-docs/<M>/<sub>.prizm
      - Identify 5-10 most important files for KEY_FILES
-     WRITE: .prizm-docs/<mirrored-path>.prizm
+     WRITE: .prizm-docs/<M>.prizm
+
+   FOR EACH sub-module S of top-level module M:
+     SCAN M/S directory:
+     - Count all source files in S
+     - Identify exported/public interfaces within S
+     - Trace dependencies within S
+     - Identify key files in S
+     WRITE: .prizm-docs/<M>/<S>.prizm
+     NOTE: This is still an L1 doc (module index level), written at the mirrored sub-path
 
 6. SKIP_L2:
    DO NOT generate L2 docs during initialization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
   "type": "module",
   "bin": {