prizmkit 1.0.137 → 1.0.139

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.137",
-  "bundledAt": "2026-03-28T13:49:17.127Z",
-  "bundledFrom": "1cfc8e2"
+  "frameworkVersion": "1.0.139",
+  "bundledAt": "2026-03-28T16:00:11.932Z",
+  "bundledFrom": "ce5323e"
 }

package/bundled/dev-pipeline/lib/common.sh

@@ -90,22 +90,27 @@ except: pass
 
 # prizm_detect_subagents <session_log>
 #
-# Scan session log for subagent spawns and log the result.
-# Uses grep -q for early exit on first match.
+# Scan session log for subagent spawns, count them, and log the result.
+# Sets _SUBAGENT_COUNT to the number of Agent tool calls detected.
 # Requires: USE_STREAM_JSON (from detect_stream_json_support)
+_SUBAGENT_COUNT=0
 prizm_detect_subagents() {
     local session_log="$1"
+    _SUBAGENT_COUNT=0
     [[ -f "$session_log" ]] || return 0
 
-    local has_subagent=false
+    local count=0
     if [[ "$USE_STREAM_JSON" == "true" ]]; then
-        grep -q '"name"[[:space:]]*:[[:space:]]*"Agent"' "$session_log" 2>/dev/null && has_subagent=true
+        count=$(grep -c '"name"[[:space:]]*:[[:space:]]*"Agent"' "$session_log" 2>/dev/null || echo "0")
     else
-        grep -qE '(Tool: Agent|"tool":\s*"Agent"|tool_use.*Agent|subagent_type)' "$session_log" 2>/dev/null && has_subagent=true
+        count=$(grep -cE '(Tool: Agent|"tool":\s*"Agent"|tool_use.*Agent|subagent_type)' "$session_log" 2>/dev/null || echo "0")
     fi
 
-    if [[ "$has_subagent" == true ]]; then
-        log_info "Subagent calls detected in session"
+    _SUBAGENT_COUNT=$count
+    if [[ "$count" -gt 0 ]]; then
+        log_info "Subagent calls detected in session: $count"
+    else
+        log_info "Subagent calls detected in session: 0 (single-agent mode)"
     fi
 }
 

package/bundled/dev-pipeline/run-bugfix.sh

@@ -599,6 +599,7 @@ main() {
     fi
 
     local session_count=0
+    local total_subagent_calls=0
 
     while true; do
         # Find next bug to process
@@ -614,6 +615,7 @@ main() {
             log_success "════════════════════════════════════════════════════"
             log_success "  All bugs processed! Bug fix pipeline finished."
             log_success "  Total sessions: $session_count"
+            log_success "  Total subagent calls: $total_subagent_calls"
             log_success "════════════════════════════════════════════════════"
 
             # Merge dev branch back to original
@@ -672,6 +674,10 @@ main() {
             --state-dir "$STATE_DIR" \
             --output "$bootstrap_prompt" >/dev/null 2>&1
 
+        # Log agent configuration (bugfix always uses dual-agent: Orchestrator + Dev + Reviewer)
+        log_info "Pipeline mode: ${BOLD}standard${NC} (Dual Agent — Orchestrator + Dev + Reviewer)"
+        log_info "Agents: 3 (critic: disabled)"
+
         # Spawn session
         log_info "Spawning AI CLI session: $session_id"
         _SPAWN_RESULT=""
@@ -681,6 +687,7 @@ main() {
             "$bootstrap_prompt" "$session_dir" "$MAX_RETRIES" "$_ORIGINAL_BRANCH"
 
         session_count=$((session_count + 1))
+        total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))
 
         log_info "Pausing 5s before next bug..."
         sleep 5

package/bundled/dev-pipeline/run.sh

@@ -647,8 +647,11 @@ sys.exit(1)
         log_error "Failed to generate bootstrap prompt for $feature_id"
         return 1
     }
-    local feature_model
+    local feature_model pipeline_mode agent_count critic_enabled
     feature_model=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('model',''))" 2>/dev/null || echo "")
+    pipeline_mode=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('pipeline_mode','lite'))" 2>/dev/null || echo "lite")
+    agent_count=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('agent_count',1))" 2>/dev/null || echo "1")
+    critic_enabled=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('critic_enabled','false'))" 2>/dev/null || echo "false")
 
     # Dry-Run: Print info and exit
     if [[ "$dry_run" == true ]]; then
@@ -664,6 +667,8 @@ sys.exit(1)
         else
             log_info "Mode:          auto-detect (from complexity)"
         fi
+        log_info "Pipeline mode: $pipeline_mode"
+        log_info "Agents:        $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
         if [[ -n "$feature_model" ]]; then
             log_info "Feature Model: $feature_model"
         elif [[ -n "${MODEL:-}" ]]; then
@@ -707,6 +712,15 @@ sys.exit(1)
     if [[ -n "$mode_override" ]]; then
         log_info "Mode Override: $mode_override"
     fi
+    local _run_one_mode_desc
+    case "$pipeline_mode" in
+        lite)     _run_one_mode_desc="Tier 1 — Single Agent" ;;
+        standard) _run_one_mode_desc="Tier 2 — Orchestrator + Dev + Reviewer" ;;
+        full)     _run_one_mode_desc="Tier 3 — Full Team (+ Multi-Critic)" ;;
+        *)        _run_one_mode_desc="$pipeline_mode" ;;
+    esac
+    log_info "Pipeline mode: ${BOLD}$pipeline_mode${NC} ($_run_one_mode_desc)"
+    log_info "Agents: $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
     if [[ $SESSION_TIMEOUT -gt 0 ]]; then
         log_info "Session timeout: ${SESSION_TIMEOUT}s"
     else
@@ -881,6 +895,7 @@ main() {
 
     # Main processing loop
     local session_count=0
+    local total_subagent_calls=0
 
     while true; do
         # Check for stuck features
@@ -923,6 +938,7 @@ for f in data.get('stuck_features', []):
             log_success "════════════════════════════════════════════════════"
             log_success "  All features completed! Pipeline finished."
             log_success "  Total sessions: $session_count"
+            log_success "  Total subagent calls: $total_subagent_calls"
             log_success "════════════════════════════════════════════════════"
             break
         fi
@@ -999,8 +1015,22 @@ for f in data.get('stuck_features', []):
             log_error "Failed to generate bootstrap prompt for $feature_id"
             continue
         }
-        local feature_model
+        local feature_model pipeline_mode agent_count critic_enabled
         feature_model=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('model',''))" 2>/dev/null || echo "")
+        pipeline_mode=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('pipeline_mode','lite'))" 2>/dev/null || echo "lite")
+        agent_count=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('agent_count',1))" 2>/dev/null || echo "1")
+        critic_enabled=$(echo "$gen_output" | python3 -c "import json,sys; print(json.load(sys.stdin).get('critic_enabled','false'))" 2>/dev/null || echo "false")
+
+        # Log pipeline mode and agent configuration
+        local _mode_desc
+        case "$pipeline_mode" in
+            lite)     _mode_desc="Tier 1 — Single Agent" ;;
+            standard) _mode_desc="Tier 2 — Orchestrator + Dev + Reviewer" ;;
+            full)     _mode_desc="Tier 3 — Full Team (+ Multi-Critic)" ;;
+            *)        _mode_desc="$pipeline_mode" ;;
+        esac
+        log_info "Pipeline mode: ${BOLD}$pipeline_mode${NC} ($_mode_desc)"
+        log_info "Agents: $agent_count (critic: $([ "$critic_enabled" = "true" ] && echo "enabled" || echo "disabled"))"
 
         # Mark feature as in-progress before spawning session
         python3 "$SCRIPTS_DIR/update-feature-status.py" \
@@ -1042,6 +1072,7 @@ for f in data.get('stuck_features', []):
         fi
 
         session_count=$((session_count + 1))
+        total_subagent_calls=$((total_subagent_calls + _SUBAGENT_COUNT))
 
         # Brief pause before next iteration
         log_info "Pausing 5s before next feature..."

package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py

@@ -723,10 +723,22 @@ def main():
 
     # Success
     feature_model = feature.get("model", "")
+    pipeline_mode = replacements.get("{{PIPELINE_MODE}}", "lite")
+    critic_enabled = replacements.get("{{CRITIC_ENABLED}}", "false") == "true"
+    # Map mode to agent count for logging
+    # lite=1 (single agent), standard/full=3 (orchestrator + dev + reviewer)
+    mode_agent_counts = {"lite": 1, "standard": 3, "full": 3}
+    agent_count = mode_agent_counts.get(pipeline_mode, 1)
+    critic_count_val = int(replacements.get("{{CRITIC_COUNT}}", "1"))
+    if critic_enabled:
+        agent_count += critic_count_val
     output = {
         "success": True,
         "output_path": os.path.abspath(args.output),
         "model": feature_model,
+        "pipeline_mode": pipeline_mode,
+        "agent_count": agent_count,
+        "critic_enabled": "true" if critic_enabled else "false",
     }
     print(json.dumps(output, indent=2, ensure_ascii=False))
     sys.exit(0)

package/bundled/dev-pipeline/templates/bootstrap-tier1.md

@@ -130,7 +130,7 @@ grep -q '^/binary-name$' .gitignore || echo '/binary-name' >> .gitignore
 ```
 Never commit compiled binaries, build output, or generated artifacts.
 
-**Before starting**: detect the test command and record baseline:
+**3a.** Detect the test command and record baseline:
 ```bash
 # Try in order, use first that exits 0
 node --test tests/**/*.test.js 2>&1 | tail -3   # Node built-in
@@ -141,26 +141,22 @@ Record the working command as `TEST_CMD`. Then record baseline failures (if any)
 $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 ```
 
-For each task in plan.md Tasks section:
-1. Read the relevant section from `context-snapshot.md` (no need to re-read individual files)
-2. Write/edit the code
-3. Run tests after each task: `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20` — then grep `/tmp/test-out.txt` for failure details; never re-run just to apply a different filter
-4. Mark task `[x]` in plan.md Tasks section immediately
+**3b.** Run `/prizmkit-implement` — this handles the full implementation cycle:
+- Reads plan.md Tasks section from `.prizmkit/specs/{{FEATURE_SLUG}}/`
+- Reads context from `context-snapshot.md` (Prizm docs, TRAPS, file manifest)
+- Implements task-by-task with TDD, marking each `[x]` immediately
+- Creates/updates L2 `.prizm` docs when creating new modules or significantly modifying existing ones — AI selectively decides which modules warrant L2 based on complexity and importance
+- Runs tests using `TEST_CMD` after each task
+- Writes '## Implementation Log' to `context-snapshot.md`
 
-After all tasks complete:
-1. Run the full test suite to ensure nothing is broken
-2. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
-3. If any criterion is not met, fix it now (max 2 fix rounds)
+**3c.** After implement completes, verify:
+1. All tasks in plan.md are `[x]`
+2. Run the full test suite to ensure nothing is broken
+3. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
+4. If any criterion is not met, fix it now (max 2 fix rounds)
 
 **CP-2**: All acceptance criteria met, all tests pass.
 
-After verification, append to `context-snapshot.md`:
-```
-## Implementation Log
-Files changed/created: [list]
-Key decisions: [list]
-```
-
 {{IF_BROWSER_INTERACTION}}
 ### Phase 3.5: Browser Verification (playwright-cli)
 
@@ -188,7 +184,8 @@ If any step fails, log the failure and continue. Do NOT retry browser verificati
 **4a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
 1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
 2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
-3. Stage doc changes: `git add .prizm-docs/`
+3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
+4. Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **4b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -194,20 +194,13 @@ Wait for Critic to return.
 Spawn Dev subagent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false).
 
 Prompt:
-> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
->    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** Only read a source file directly if: (a) NOT in the manifest, (b) needing an implementation detail beyond the interface summary, or (c) needing a constant/enum/field-name value not captured in the interface column.
-> 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
-> 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
-> 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
->    - Files changed/created (with paths)
->    - Key implementation decisions and rationale
->    - Deviations from plan.md (if any)
->    - Notable discoveries (unexpected behavior, hidden dependencies, new TRAPS)
-> 6. Do NOT execute any git commands (no git add/commit/reset/push).
-> 7. If `<TEST_CMD>` shows failures, check against BASELINE_FAILURES=`<BASELINE_FAILURES>`. Failures present in the baseline are pre-existing — list them explicitly in your COMPLETION_SIGNAL.
+> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+> ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
+> 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Use `TEST_CMD=<TEST_CMD>` for testing. Baseline failures: `BASELINE_FAILURES=<BASELINE_FAILURES>`.
+> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 4. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 Wait for Dev to return. All tasks must be `[x]`, tests pass.
@@ -302,7 +295,8 @@ If any step fails, log the failure and continue. Do NOT retry browser verificati
 **6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):
 1. **Structural sync**: Use `git diff --cached --name-status` to locate changed modules, update KEY_FILES/INTERFACES/DEPENDENCIES/file counts in affected `.prizm-docs/` files
 2. **Architecture knowledge** (feature sessions only): Extract TRAPS/RULES/DECISIONS from completed work into `.prizm-docs/`
-3. Stage doc changes: `git add .prizm-docs/`
+3. **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
+4. Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 
 **6b.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -274,20 +274,13 @@ grep -c '^\- \[ \]' .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null || echo
 Spawn Dev agent (Agent tool, subagent_type="prizm-dev-team-dev", run_in_background=false).
 
 Prompt:
-> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}) using TDD.
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
->    **⚠️ DO NOT re-read source files that are already listed in Section 4 File Manifest.** The manifest already contains their key interfaces. Only read a source file directly if: (a) it is NOT in the manifest, or (b) you need a specific implementation detail not captured in the manifest's interface column.
-> 2. Read `plan.md` (including Tasks section) from `.prizmkit/specs/{{FEATURE_SLUG}}/`.
-> 3. Implement task-by-task. Mark each `[x]` in plan.md Tasks section **immediately** after completion (do NOT batch).
-> 4. Use `TEST_CMD=<TEST_CMD>` to run tests — do NOT explore alternative test commands. **When tests fail: run `$TEST_CMD 2>&1 | tee /tmp/test-out.txt` ONCE, then grep `/tmp/test-out.txt` for failure details. Never re-run the full suite just to apply a different filter.**
-> 5. After ALL tasks done, append '## Implementation Log' to context-snapshot.md with:
->    - Files changed/created (with paths)
->    - Key implementation decisions and rationale
->    - Deviations from plan.md (if any)
->    - Notable discoveries (unexpected behavior, hidden dependencies, new TRAPS)
-> 6. Do NOT execute any git commands (no git add/commit/reset/push).
-> 7. If `<TEST_CMD>` shows failures, check against BASELINE_FAILURES=`<BASELINE_FAILURES>`. Failures present in the baseline are pre-existing — list them explicitly in your COMPLETION_SIGNAL.
+> "Read {{DEV_SUBAGENT_PATH}}. Implement feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has Prizm Context (TRAPS/RULES), Section 4 has File Manifest with paths and interfaces.
+> ⚠️ DO NOT re-read source files already listed in Section 4 File Manifest unless you need implementation detail beyond the interface summary.
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` for full context.
+> 2. Run `/prizmkit-implement` to execute the tasks in plan.md. Use `TEST_CMD=<TEST_CMD>` for testing. Baseline failures: `BASELINE_FAILURES=<BASELINE_FAILURES>`.
+> 3. After implement completes, verify the '## Implementation Log' section was written to context-snapshot.md.
+> 4. Do NOT execute any git commands (no git add/commit/reset/push).
 > Do NOT exit until all tasks are [x] and the '## Implementation Log' section is written in context-snapshot.md."
 
 **Gate Check — Implementation Log**:
@@ -303,10 +296,8 @@ Wait for Dev to return. **If Dev times out before all tasks are `[x]`**:
    > "Read {{DEV_SUBAGENT_PATH}}. You are resuming implementation of feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
    > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — Section 4 has File Manifest, 'Implementation Log' (if present) shows what was already done.
    > 2. Run `git diff HEAD` to see actual code changes already made.
-   > 3. Read plan.md Tasks section — complete ONLY the remaining `[ ]` tasks. Do NOT redo completed `[x]` tasks.
-   > 4. Use `TEST_CMD=<TEST_CMD>` to run tests.
-   > 5. Append progress to '## Implementation Log' in context-snapshot.md.
-   > 6. Do NOT execute any git commands."
+   > 3. Run `/prizmkit-implement` to complete the remaining `[ ]` tasks. Use `TEST_CMD=<TEST_CMD>` for testing.
+   > 4. Do NOT execute any git commands."
 3. Max 2 recovery retries. After 2 failures, orchestrator implements remaining tasks directly.
 
 All tasks `[x]`, tests pass.
@@ -412,6 +403,7 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 **6b.** Run `/prizmkit-retrospective` (**before commit**, maintains `.prizm-docs/` architecture index):
 - **Structural sync**: update KEY_FILES/INTERFACES/DEPENDENCIES/file counts for changed modules
 - **Architecture knowledge** (feature sessions only): extract TRAPS, RULES, DECISIONS from completed work into `.prizm-docs/`
+- **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
 - Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
 - **For bug-fix sessions**: structural sync only, skip knowledge injection unless a genuinely new pitfall was discovered

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.137",
+  "version": "1.0.138",
   "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-implement/SKILL.md

@@ -39,7 +39,10 @@ Execute implementation by following the task breakdown in plan.md. Respects task
 3. Check if checkpoint tasks are complete before proceeding to next phase
 4. For each unchecked task in order:
    a. If task has `[P]` marker, it can run in parallel with other `[P]` tasks in the same group
-   b. Read L2 doc for target file's module (if exists) — TRAPS save you from repeating known mistakes
+   b. Read L2 doc for target file's module. TRAPS save you from repeating known mistakes.
+      - If L2 exists: check TRAPS and DECISIONS before modifying files.
+      - If L2 does not exist and this task creates a new module directory or adds significant source files: create L2 using the L2 GENERATION TEMPLATE (see PRIZM-SPEC). Seed KEY_FILES and DEPENDENCIES from the files being created. TRAPS and DECISIONS can be minimal initially — `/prizmkit-retrospective` will enrich them.
+      - Judgment call: not every directory needs L2. Create L2 when the module has meaningful logic, non-obvious coupling, or design decisions worth preserving. Skip for trivial wrapper directories or single-config modules.
    c. Apply TDD where applicable: write a failing test first, then implement until it passes. For UI components or configuration changes where unit tests don't apply, skip the test-first step.
    d. Mark task as `[x]` in `plan.md` Tasks section immediately — not batched at the end. Immediate marking means the plan always reflects true progress, even if the session is interrupted.
    e. After all tasks, append '## Implementation Log' to `context-snapshot.md` (if running in pipeline context): files changed/created, key decisions, notable discoveries.

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

@@ -76,7 +76,7 @@ STEPS:
 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.
 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, defer 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.
 7. Append entries to changelog.prizm using format: `- YYYY-MM-DD | <module-path> | <verb>: <description>`
 8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> split or archive.
 9. Stage updated .prizm files via `git add .prizm-docs/`
@@ -162,7 +162,7 @@ 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.
+- 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.

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

@@ -59,14 +59,16 @@ git diff --name-status
 
 **1d.** Update affected docs (bottom-up: L2 → L1 → L0):
 
-- **L2** (if exists): Update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS
+- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 using the L2 GENERATION TEMPLATE, then populate from source.
 - **L1**: Update FILES count, KEY_FILES (if major files added/removed), DEPENDENCIES (if module-level deps changed). **L1 does NOT contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS** — those belong in L2 only.
 - **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed).
 
 **1d-migrate.** Legacy TRAPS format migration (opportunistic):
 While updating an affected L1/L2 doc, if you encounter TRAPS entries **without** a severity prefix (e.g., `- foo | FIX: bar` instead of `- [LOW] foo | FIX: bar`), prepend `[LOW]` as a conservative default. This clears legacy format debt incrementally — only in files already being touched, never as a bulk operation.
 
-**1e.** If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA in PRIZM-SPEC Section 9.1 Step 2) and matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
+**1e.** If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA in PRIZM-SPEC Section 9.1 Step 2) and matches no existing module:
+1. Create L1 doc immediately, add to MODULE_INDEX.
+2. If the current diff includes Added or Modified source files with meaningful logic in this module → create L2 immediately using the L2 GENERATION TEMPLATE. Otherwise defer L2 to the next session that touches this module.
 
 **1f.** Enforce size limits:
 - L0 > 4KB → consolidate MODULE_INDEX
@@ -143,7 +145,7 @@ When writing TRAPS:
 **QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding?" If not, discard. Do not record trivially observable code patterns — the AI can read the code directly.
 
 **2c.** Inject into the correct `.prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file's corresponding section (TRAPS/DECISIONS/RULES belong in L2, not L1)
+- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file. If the target L2 does not exist, create it first using the L2 GENERATION TEMPLATE before injecting knowledge. (TRAPS/DECISIONS/RULES belong in L2, not L1.)
 - Project-level RULES/PATTERNS → `root.prizm`
 - Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
 

package/package.json

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

package/src/manifest.js

@@ -99,7 +99,7 @@ export function buildManifest({
  * Diff two manifests and return added/removed items.
  * @param {Object} oldManifest - previous manifest
  * @param {Object} newManifest - new manifest to compare against
- * @returns {Object} { skills: {added, removed}, agents: {added, removed}, rules: {added, removed} }
+ * @returns {Object} { skills: {added, removed}, agents: {added, removed}, rules: {added, removed}, pipeline: {added, removed}, extras: {added, removed} }
  */
 export function diffManifest(oldManifest, newManifest) {
   function diffArrays(oldArr, newArr) {
@@ -119,5 +119,6 @@ export function diffManifest(oldManifest, newManifest) {
       Array.isArray(oldManifest?.files?.pipeline) ? oldManifest.files.pipeline : [],
       Array.isArray(newManifest?.files?.pipeline) ? newManifest.files.pipeline : [],
     ),
+    extras: diffArrays(oldManifest?.files?.extras, newManifest?.files?.extras),
   };
 }

package/src/scaffold.js

@@ -692,7 +692,8 @@ export async function installGitignore(projectRoot, options, dryRun) {
 
     if (missing.length > 0) {
       const separator = existing.endsWith('\n') ? '' : '\n';
-      await fs.appendFile(targetPath, separator + '\n# PrizmKit\n' + missing.join('\n') + '\n');
+      const header = existingLines.has('# PrizmKit') ? '' : '# PrizmKit\n';
+      await fs.appendFile(targetPath, separator + '\n' + header + missing.join('\n') + '\n');
       console.log(chalk.green(`      ✓ .gitignore (added ${missing.length} entries)`));
     } else {
       console.log(chalk.green('      ✓ .gitignore (up-to-date)'));
@@ -894,15 +895,15 @@ export async function scaffold(config) {
     }
   }
 
-  // 11. Git pre-commit hook
+  // 12. Git pre-commit hook
   console.log(chalk.blue('    Git Hook:'));
   await installGitHook(projectRoot, dryRun);
 
-  // 12. PrizmKit scripts (always installed)
+  // 13. PrizmKit scripts (always installed)
   console.log(chalk.blue('    PrizmKit 脚本:'));
   await installPrizmkitScripts(projectRoot, dryRun);
 
-  // 13. Write installation manifest
+  // 14. Write installation manifest
   if (!dryRun) {
     const agentsDir = getAgentsDir();
     const agentFileNames = (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'));

package/src/upgrade.js

@@ -272,7 +272,7 @@ export async function runUpgrade(directory, options = {}) {
     newManifest.installedAt = oldManifest.installedAt;
   }
 
-  const diff = oldManifest ? diffManifest(oldManifest, newManifest) : { skills: { added: [], removed: [] }, agents: { added: [], removed: [] }, rules: { added: [], removed: [] }, pipeline: { added: [], removed: [] } };
+  const diff = oldManifest ? diffManifest(oldManifest, newManifest) : { skills: { added: [], removed: [] }, agents: { added: [], removed: [] }, rules: { added: [], removed: [] }, pipeline: { added: [], removed: [] }, extras: { added: [], removed: [] } };
 
   // 5. Display upgrade summary
   const oldVersion = oldManifest?.version || 'unknown';
@@ -282,8 +282,8 @@ export async function runUpgrade(directory, options = {}) {
   console.log(`    Suite: ${suite}`);
   console.log('');
 
-  const totalAdded = diff.skills.added.length + diff.agents.added.length + diff.rules.added.length + diff.pipeline.added.length;
-  const totalRemoved = diff.skills.removed.length + diff.agents.removed.length + diff.rules.removed.length + diff.pipeline.removed.length;
+  const totalAdded = diff.skills.added.length + diff.agents.added.length + diff.rules.added.length + diff.pipeline.added.length + diff.extras.added.length;
+  const totalRemoved = diff.skills.removed.length + diff.agents.removed.length + diff.rules.removed.length + diff.pipeline.removed.length + diff.extras.removed.length;
   const totalUpdated = newSkillList.length + newAgentFiles.length + newRuleFiles.length;
 
   if (diff.skills.added.length) console.log(chalk.green(`    + Skills added: ${diff.skills.added.join(', ')}`));
@@ -294,6 +294,8 @@ export async function runUpgrade(directory, options = {}) {
   if (diff.rules.removed.length) console.log(chalk.red(`    - Rules removed: ${diff.rules.removed.join(', ')}`));
   if (diff.pipeline.added.length) console.log(chalk.green(`    + Pipeline files added: ${diff.pipeline.added.length} file(s)`));
   if (diff.pipeline.removed.length) console.log(chalk.red(`    - Pipeline files removed: ${diff.pipeline.removed.length} file(s)`));
+  if (diff.extras.added.length) console.log(chalk.green(`    + Extras added: ${diff.extras.added.join(', ')}`));
+  if (diff.extras.removed.length) console.log(chalk.red(`    - Extras removed: ${diff.extras.removed.join(', ')}`));
 
   if (totalAdded === 0 && totalRemoved === 0 && oldVersion === pkg.version) {
     console.log(chalk.gray('    No changes detected. Re-installing all files to ensure consistency.'));