prizmkit 1.0.115 → 1.0.118

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.115",
-  "bundledAt": "2026-03-26T08:40:28.718Z",
-  "bundledFrom": "0e9b475"
+  "frameworkVersion": "1.0.118",
+  "bundledAt": "2026-03-26T15:57:17.490Z",
+  "bundledFrom": "f6b1f2d"
 }

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

@@ -106,3 +106,30 @@ prizm_check_common_dependencies() {
         log_warn "Continuing anyway (will fail when spawning sessions)..."
     fi
 }
+
+# Ensure git is installed and the current directory is a git repository.
+# If git is missing, print install instructions and exit.
+# If not inside a git repo, run git init + initial commit automatically.
+prizm_ensure_git_repo() {
+    if ! command -v git &>/dev/null; then
+        log_error "git is required but not installed."
+        log_error "Install git:"
+        log_error "  macOS:   brew install git   or   xcode-select --install"
+        log_error "  Ubuntu:  sudo apt-get install git"
+        log_error "  Windows: https://git-scm.com/download/win"
+        exit 1
+    fi
+
+    if ! git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then
+        log_warn "Current directory is not a git repository."
+        log_info "Initializing git repository..."
+        git init -b main
+        # Create initial commit so branches and diffs work
+        git add -A
+        git commit --no-verify -m "chore: initial commit (auto-created by dev-pipeline)" || {
+            # If nothing to commit (empty project), create an empty initial commit
+            git commit --no-verify --allow-empty -m "chore: initial commit (auto-created by dev-pipeline)"
+        }
+        log_success "Git repository initialized with initial commit."
+    fi
+}

package/bundled/dev-pipeline/retry-bug.sh

@@ -164,6 +164,7 @@ sys.exit(1)
 # ============================================================
 
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ORIGINAL_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
 
 log_info "Cleaning $BUG_ID artifacts for full restart..."
 python3 "$SCRIPTS_DIR/update-bug-status.py" \
@@ -329,9 +330,7 @@ log_info "exit_code=$EXIT_CODE"
 
 # ── Determine session outcome from observable signals ──────────────
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
-    | sed 's@^refs/remotes/origin/@@') \
-    || DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
+DEFAULT_BRANCH="$ORIGINAL_BRANCH"
 
 if [[ $EXIT_CODE -eq 124 ]]; then
     log_warn "Session timed out after ${SESSION_TIMEOUT}s"

package/bundled/dev-pipeline/retry-feature.sh

@@ -149,6 +149,7 @@ sys.exit(1)
 # ============================================================
 
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ORIGINAL_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
 FEATURE_SLUG=$(FEATURE_ID="$FEATURE_ID" FEATURE_TITLE="$FEATURE_TITLE" python3 -c "
 import os, re
 fid = os.environ['FEATURE_ID'].replace('F-', '').replace('f-', '').zfill(3)
@@ -338,9 +339,7 @@ log_info "exit_code=$EXIT_CODE"
 
 # ── Determine session outcome from observable signals ──────────────
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null \
-    | sed 's@^refs/remotes/origin/@@') \
-    || DEFAULT_BRANCH=$(git -C "$PROJECT_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null | grep -E '^(main|master)$' || echo "main")
+DEFAULT_BRANCH="$ORIGINAL_BRANCH"
 
 if [[ $EXIT_CODE -eq 124 ]]; then
     log_warn "Session timed out after ${SESSION_TIMEOUT}s"

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

@@ -272,6 +272,7 @@ trap cleanup SIGINT SIGTERM
 
 check_dependencies() {
     prizm_check_common_dependencies "$CLI_CMD"
+    prizm_ensure_git_repo
 }
 
 run_log_cleanup() {

package/bundled/dev-pipeline/run.sh

@@ -357,6 +357,7 @@ trap cleanup SIGINT SIGTERM
 
 check_dependencies() {
     prizm_check_common_dependencies "$CLI_CMD"
+    prizm_ensure_git_repo
 }
 
 run_log_cleanup() {

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

@@ -91,7 +91,10 @@ If MISSING — build it now:
 2. Scan `src/` for files related to this feature; read each one
 3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
-   - **Section 2 — Project Structure**: output of relevant `ls src/` calls
+   - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
+     ```bash
+     find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     ```
    - **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

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

@@ -102,7 +102,10 @@ If MISSING — build it now:
 2. Scan `src/` for files related to this feature; read each one
 3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
-   - **Section 2 — Project Structure**: relevant `ls src/` output
+   - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
+     ```bash
+     find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     ```
    - **Section 3 — Prizm Context**: full content of root.prizm and relevant L1/L2 docs
    - **Section 4 — File Manifest**: For each file relevant to this feature, list: file path, why it's needed (modify/reference/test), key interface signatures (function names + params + return types). Do NOT include full file content — agents read files on-demand. Format:
      ### Files to Modify

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

@@ -180,7 +180,10 @@ If `EXISTING_CODE` is non-empty: your spec/plan/tasks must reflect this existing
 2. Scan `src/` for files related to this feature; read each one
 3. Write `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
    - **Section 1 — Feature Brief**: feature description + acceptance criteria (copy from above)
-   - **Section 2 — Project Structure**: relevant `ls src/` output
+   - **Section 2 — Project Structure**: run the following to get a visual directory tree, then paste output:
+     ```bash
+     find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     ```
    - **Section 3 — Prizm Context**: full content of root.prizm and relevant L1/L2 docs
    - **Section 4 — File Manifest**: For each file relevant to this feature, list: file path, why it's needed (modify/reference/test), key interface signatures (function names + params + return types). Do NOT include full file content — agents read files on-demand. Format:
      ### Files to Modify

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.115",
+  "version": "1.0.118",
   "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/app-planner/SKILL.md

@@ -49,6 +49,10 @@ Before questions, check optional context files (never block if absent):
 - `.prizm-docs/root.prizm` (architecture/project context)
 - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
 - existing `feature-list.json` (required for incremental mode)
+- If `.prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
+  ```bash
+  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+  ```
 
 **Tech stack auto-population from config.json:**
 - If `.prizmkit/config.json` contains a `tech_stack` object, use it to pre-fill `global_context` fields in the generated `feature-list.json`.
@@ -227,6 +231,7 @@ AI: "Ready to proceed to dev-pipeline."
 - new items default `status: "pending"`
 - English feature titles for stable slug generation
 - `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
+- **descriptions must be implementation-ready** — minimum 15 words (error), recommended 30/50/80 words for low/medium/high complexity (warning). See `planning-guide.md` §4 for what to include.
 
 ## Next-Step Execution Policy (after planning)
 

package/bundled/skills/app-planner/assets/planning-guide.md

@@ -174,7 +174,55 @@ F-010: Admin Dashboard (deps: F-006, F-007)
 
 ---
 
-## 4. Acceptance Criteria Writing Guide
+## 4. Feature Description Writing Guide
+
+Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess — producing worse code. Invest in rich descriptions upfront.
+
+### Minimum Word Counts
+
+| Complexity | Minimum Words | Warning Threshold |
+|------------|---------------|-------------------|
+| low        | 15            | 30                |
+| medium     | 15            | 50                |
+| high       | 15            | 80                |
+
+Below 15 words is a validation error. Below the threshold triggers a warning.
+
+### What to Include
+
+Every description should cover these aspects (adapt per feature type):
+
+1. **What to build** — concrete deliverables (API endpoints, UI pages/components, CLI commands, data models)
+2. **Key behaviors** — business rules, validation, state transitions, workflows
+3. **Integration points** — which existing modules, services, or APIs it connects to
+4. **Data model** — entities, relationships, key fields, storage approach (when applicable)
+5. **Error/edge cases** — failure modes, empty states, limits, unauthorized access
+
+### Good vs Bad Examples
+
+**Bad** (17 words — too thin):
+```
+"Build user authentication with login and registration. Support email/password and social login options."
+```
+
+**Good** (78 words — implementation-ready):
+```
+"Implement user authentication with email/password registration and login. Create a User model with fields: id, email (unique), password_hash, display_name, created_at, last_login. Build POST /api/auth/register (validate email format, enforce 8+ char password, check uniqueness, hash with bcrypt, return JWT), POST /api/auth/login (verify credentials, issue JWT with 7-day expiry), and GET /api/auth/me (return current user from JWT). Add auth middleware that validates JWT on protected routes. Handle errors: duplicate email (409), invalid credentials (401), expired token (401)."
+```
+
+**Bad** (12 words):
+```
+"Create the main dashboard page showing project overview and recent activity."
+```
+
+**Good** (65 words):
+```
+"Build a dashboard page at /dashboard as the post-login landing screen. Display: (1) summary cards showing total projects count, active tasks count, and recent activity count; (2) a recent activity feed listing the last 10 actions across all projects with timestamps; (3) a quick-access project list showing the 5 most recently updated projects. Fetch data via GET /api/dashboard/summary. Show loading skeleton on initial load, empty state when user has no projects."
+```
+
+---
+
+## 5. Acceptance Criteria Writing Guide
 
 Acceptance criteria define what "done" means for a feature. They should be specific, testable, and unambiguous.
 
@@ -215,7 +263,7 @@ Then [expected outcome]
 
 ---
 
-## 5. Complexity Estimation Guide
+## 6. Complexity Estimation Guide
 
 | Complexity | Characteristics | Typical Scope |
 |------------|----------------|---------------|
@@ -242,7 +290,7 @@ Consider splitting a feature if it exhibits any of the following:
 
 ---
 
-## 6. Dependency Graph Rules
+## 7. Dependency Graph Rules
 
 These rules ensure the feature dependency graph is valid and buildable.
 
@@ -270,7 +318,7 @@ These rules ensure the feature dependency graph is valid and buildable.
 
 ---
 
-## 7. Session Granularity Decision Rules
+## 8. Session Granularity Decision Rules
 
 Session granularity determines whether a feature is implemented in a single coding session or split across multiple sub-feature sessions.
 

package/bundled/skills/app-planner/scripts/validate-and-generate.py

@@ -229,6 +229,26 @@ def validate_feature_list(data, planning_mode="new"):
             if not isinstance(val, str) or not val.strip():
                 errors.append("{}: {} must be a non-empty string".format(label, key))
 
+        # -- Description depth check --
+        desc = feat.get("description", "")
+        if isinstance(desc, str) and desc.strip():
+            word_count = len(desc.split())
+            complexity = feat.get("estimated_complexity", "medium")
+            min_words = {"low": 30, "medium": 50, "high": 80}.get(complexity, 50)
+            if word_count < 15:
+                errors.append(
+                    "{}: description too short ({} words, minimum 15). "
+                    "Include: what to build, key behaviors, integration points, "
+                    "and data model overview.".format(label, word_count)
+                )
+            elif word_count < min_words:
+                warnings.append(
+                    "{}: description only {} words (recommend {}+ for {} complexity). "
+                    "Richer descriptions produce better pipeline results.".format(
+                        label, word_count, min_words, complexity
+                    )
+                )
+
         # -- Priority --
         priority = feat.get("priority")
         if isinstance(priority, int) and priority > 0:

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

@@ -49,6 +49,17 @@ BROWNFIELD WORKFLOW (existing project):
    - SUB-MODULES: directories INSIDE a top-level module (e.g. `src/routes/`, `src/models/`)
    - A sub-module maps to `.prizm-docs/<M>/<S>.prizm`, never to `.prizm-docs/<S>.prizm` — flattening would create ambiguous paths when two modules have identically-named sub-modules
    - Exclude: `.git/`, `node_modules/`, `vendor/`, `build/`, `dist/`, `__pycache__/`, `target/`, `bin/`, `.claude/`, `.codebuddy/`, `.prizmkit/`, `.prizm-docs/`, `dev-pipeline/`
+   - **Scan command** — run this to get a 2-level directory tree (excludes noise directories):
+     ```bash
+     find . -maxdepth 2 -type d \
+       -not -path '*/node_modules/*' -not -path '*/.git/*' \
+       -not -path '*/dist/*' -not -path '*/build/*' \
+       -not -path '*/__pycache__/*' -not -path '*/vendor/*' \
+       -not -path '*/.claude/*' -not -path '*/.codebuddy/*' \
+       -not -path '*/.prizmkit/*' -not -path '*/.prizm-docs/*' \
+       -not -path '*/dev-pipeline/*' -not -path '*/target/*' \
+       | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+     ```
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
 5. Count source files per directory

package/package.json

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