prizmkit 1.0.120 → 1.0.122

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.120",
-  "bundledAt": "2026-03-27T15:05:19.685Z",
-  "bundledFrom": "ff48c06"
+  "frameworkVersion": "1.0.122",
+  "bundledAt": "2026-03-27T16:12:14.647Z",
+  "bundledFrom": "69c231a"
 }

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

@@ -129,6 +129,14 @@ ls .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
 
 If either missing, write them yourself:
 - `plan.md`: architecture — components, interfaces, data flow, files to create/modify, testing approach, and a Tasks section with `[ ]` checkboxes ordered by dependency
+
+**Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
+Before proceeding past CP-1, verify:
+1. Plan.md Data Model section references existing schema/model files (scan for `*.prisma`, `*.sql`, `migrations/`, `models/`, `*.entity.*` files; read them if not already in context-snapshot)
+2. All new tables/fields follow existing naming conventions, ID strategy, timestamp patterns, and constraint style
+3. No `[NEEDS CLARIFICATION]` remains in Data Model section — resolve by reading existing code and making a conservative choice that matches existing patterns. Document the resolution in plan.md.
+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.
 
 ### Phase 3: Implement — Dev Subagent

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.120",
+  "version": "1.0.122",
   "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

@@ -11,6 +11,26 @@ Plan deliverable features for dev-pipeline in two modes:
 
 Always produce a validated `feature-list.json` that conforms to `dev-pipeline-feature-list`.
 
+## Scope Boundary (Hard Rule)
+
+**This skill is PLANNING ONLY.** You must NEVER:
+- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
+- Create project scaffolding, directories, or boilerplate
+- Run build/install/test commands (npm init, pip install, etc.)
+- Execute any implementation action beyond writing `feature-list.json`
+
+**Your ONLY writable outputs are:**
+1. `feature-list.json` (project root)
+2. Architecture decisions appended to `CLAUDE.md` / `CODEBUDDY.md` (with user consent, see §Architecture Decision Capture)
+3. Draft backups in `.prizmkit/planning/`
+
+**After planning is complete**, you MUST:
+1. Present the summary and recommended next step
+2. **Ask the user explicitly** whether they want to proceed to execution
+3. If the user agrees → recommend invoking `dev-pipeline-launcher` or running `run.sh` (do NOT execute it yourself)
+4. If the user wants to adjust → continue refining `feature-list.json`
+5. **NEVER auto-execute** the pipeline, launcher, or any implementation step
+
 ## When to Use
 
 Trigger this skill for requests like:
@@ -22,6 +42,7 @@ Trigger this skill for requests like:
 Do NOT use this skill when:
 - user only wants to run pipeline now (invoke `dev-pipeline-launcher`)
 - user is debugging/refactoring unrelated to feature planning
+- user wants to write or modify source code directly
 
 ## Resource Loading Rules (Mandatory)
 

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

@@ -107,6 +107,14 @@ Focus on high-signal findings. Limit to **50 findings total**; aggregate remaind
 - Task ordering contradictions (e.g., integration tasks before foundational setup without dependency note)
 - Conflicting requirements (e.g., one requires REST while other specifies GraphQL)
 
+#### G. Database Design Consistency (when plan.md has Data Model section)
+- New entity/field naming inconsistent with existing schema conventions documented in "Existing Schema Audit"
+- Missing constraints (NOT NULL, UNIQUE, FK, INDEX) on fields where existing similar tables define them
+- Unresolved `[NEEDS CLARIFICATION]` in Data Model section → **CRITICAL** (must be resolved before implementation)
+- Style Conformance Checklist items unchecked → **HIGH** (design not verified against existing conventions)
+- New tables with no foreign key relationship to any existing table (orphan table warning — may indicate missing business logic)
+- Missing migration strategy for schema changes that affect existing data
+
 ### Step 5: Severity Assignment
 
 Use this heuristic to prioritize findings:

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

@@ -23,6 +23,7 @@ Interactive requirement clarification that resolves ambiguities in feature speci
 1. Read `spec.md` from `.prizmkit/specs/###-feature-name/`
 2. Scan for `[NEEDS CLARIFICATION]` markers and underspecified areas
 3. Categorize ambiguities by dimension and prioritize — address the ones that would most affect architecture and data model first, since those are hardest to change later:
+   - Data model (what entities, relationships, constraints?) — **highest priority when DB changes are involved**: field types, nullability, naming conventions, relationships, and constraint patterns must all be resolved before plan finalization. Unresolved DB design decisions during implementation lead to expensive rework.
    - Functional scope (what does it do?)
    - Data model (what entities, relationships?)
    - UX flow (what does the user see?)

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

@@ -46,7 +46,54 @@ Execute implementation by following the task breakdown in plan.md. Respects task
    f. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
 5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
 6. After all tasks: run full test suite
-7. Output implementation summary with pass/fail status
+7. **Deploy guide update** (only when new frameworks/tools were added):
+   - Check if any dependency manifests were modified in this session:
+     ```bash
+     git diff --name-only HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null
+     ```
+   - If no manifest files changed → skip this step entirely
+   - If manifest files changed, scan for **newly added** dependencies (not version bumps):
+     ```bash
+     git diff -U0 HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null | grep '^\+' | grep -v '^\+\+\+' | head -30
+     ```
+   - For each genuinely new framework/tool, record in `deploy_guide.md` at project root:
+
+     | Field | Description | Source |
+     |-------|-------------|--------|
+     | **Name** | Framework/tool name | Package name from manifest |
+     | **Version** | Installed version or constraint | Version spec from manifest |
+     | **Purpose** | Why it was introduced | You just added it — you know why |
+     | **Install Command** | How to install locally | Standard install command for the ecosystem |
+     | **Key Config** | Config files or env vars needed | Config files you just created/modified |
+     | **Notes** | Setup gotchas, required services | Docker services, manual steps, env vars |
+
+   - Template for `deploy_guide.md`:
+     ```markdown
+     # Deploy Guide
+
+     > Auto-maintained by PrizmKit. Manual edits are preserved.
+     > Last updated: YYYY-MM-DD
+
+     ## Frameworks & Tools
+
+     ### <Framework Name>
+
+     - **Version**: <version constraint>
+     - **Purpose**: <why this framework is used>
+     - **Install**:
+       ```bash
+       <install command>
+       ```
+     - **Key Config**:
+       - `<config file or env var>`: <description>
+     - **Notes**:
+       - <any setup gotchas, required external services, manual steps>
+     ```
+
+   - **Update rules**: create file if absent; append new sections if file exists; update version if framework already documented; preserve manually added content; keep entries sorted alphabetically
+   - **Filter out**: patch version bumps of existing deps, dev-only tools needing no setup (linters, formatters), transitive/lock-file-only changes
+   - Stage the file: `git add deploy_guide.md`
+8. Output implementation summary with pass/fail status
 
 ## Task Format in plan.md
 
@@ -85,4 +132,5 @@ If a session is interrupted mid-implementation:
 
 - Code files created/modified as specified in plan.md Tasks section
 - `plan.md` Tasks section updated with completion markers `[x]`
+- `deploy_guide.md` created/updated (only when new frameworks/tools were added)
 - Implementation summary output to conversation

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

@@ -46,6 +46,12 @@ Generate a comprehensive technical implementation plan from a feature specificat
    - Architecture approach (how feature fits into existing structure)
    - Component design (new/modified components)
    - Data model changes (new entities, modified schemas)
+   - **Database design gate** (when feature involves DB changes):
+     1. Read ALL existing schema/migration/model files to understand current conventions (naming, constraints, relationships, ID strategy, timestamps)
+     2. Ensure new schema follows existing patterns — do NOT introduce new conventions unless explicitly justified
+     3. Verify every new table/field has: purpose, type, constraints, and relationship to existing entities
+     4. If any data model decision is uncertain → mark as `[NEEDS CLARIFICATION]` and resolve via `/prizmkit-clarify` BEFORE generating the Tasks section
+     5. **RULE**: The Tasks section MUST NOT be generated until all `[NEEDS CLARIFICATION]` items in Data Model are resolved. Unresolved DB design leads to implementation rework that is expensive to fix after code is written.
    - Interface design (API endpoints, request/response formats, module interfaces)
    - Integration points (external services, internal modules)
    - Testing strategy (unit, integration, e2e)

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

@@ -12,7 +12,34 @@
 - [Component]: [What changes and why]
 
 ## Data Model
-[Entity definitions, schemas, and relationships — include all details here]
+<!-- Skip this section if the feature does not involve database changes -->
+<!-- IMPORTANT: Read existing schema/model files BEFORE designing new tables -->
+
+### Existing Schema Audit
+<!-- List existing tables/models reviewed. Note observed conventions. -->
+- Tables reviewed: [list tables examined]
+- Naming convention: [snake_case/camelCase — document what existing schema uses]
+- ID strategy: [UUID/auto-increment/CUID — match existing]
+- Timestamp fields: [created_at/updated_at pattern — match existing]
+- Soft delete: [yes/no, field name if applicable]
+- Constraint patterns: [NOT NULL defaults, UNIQUE patterns, index conventions]
+
+### Schema Changes
+| Entity | Type | Fields | Constraints | Relationships | Migration Notes |
+|--------|------|--------|-------------|---------------|-----------------|
+| [name] | new/modify | [field: type, ...] | [NOT NULL, UNIQUE, INDEX, ...] | [FK → existing_table(id)] | [migration strategy] |
+
+### Style Conformance Checklist
+- [ ] Table/column naming matches existing conventions
+- [ ] ID strategy consistent with existing tables
+- [ ] Timestamp fields follow existing patterns
+- [ ] Foreign key constraints and indexes defined
+- [ ] Soft delete strategy matches existing pattern (if applicable)
+- [ ] All fields have explicit nullability (NOT NULL or nullable)
+
+### Unresolved Questions
+<!-- NONE — all DB design questions must be resolved before proceeding to Tasks -->
+<!-- If any remain, run /prizmkit-clarify to resolve them first -->
 
 ## Interface Design
 [API endpoints, request/response formats, module interfaces — include all details here]
@@ -32,7 +59,8 @@
 
 ## Pre-Implementation Gates
 - [ ] Spec coverage: all user stories mapped to components
-- [ ] Data model reviewed
+- [ ] Data model reviewed — existing schema conventions documented and followed
+- [ ] All Data Model `[NEEDS CLARIFICATION]` items resolved (mandatory for DB features)
 - [ ] API contracts defined
 - [ ] Testing approach agreed
 

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

@@ -1,6 +1,6 @@
 ---
 name: "prizmkit-retrospective"
-description: "Incremental .prizm-docs/ maintainer + deploy guide generator. Performs three jobs: (1) structural sync — update .prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizm-docs/, (3) deploy guide — detect new frameworks/tools and record setup instructions to deploy_guide.md. All project knowledge lives in .prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
+description: "Incremental .prizm-docs/ maintainer. Performs two jobs: (1) structural sync — update .prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizm-docs/. All project knowledge lives in .prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective
@@ -11,11 +11,10 @@ All project knowledge is maintained in a single store:
 |-------|----------|---------|---------|
 | **Architecture Index** | `.prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES, DECISIONS | AI quickly locates code structure, interfaces, known pitfalls, and key design decisions |
 
-**This skill performs three jobs in one pass:**
+**This skill performs two jobs in one pass:**
 
 1. **Structural Sync** — reflect what changed in code → `.prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
 2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizm-docs/`. All knowledge is consolidated in `.prizm-docs/`.
-3. **Deploy Guide** — detect new frameworks/tools and record setup instructions → `deploy_guide.md`
 
 No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing development. For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
 
@@ -151,132 +150,6 @@ When writing TRAPS:
 
 ---
 
-## Job 3: Deploy Guide Maintenance (`deploy_guide.md`)
-
-When new frameworks or tools that require **manual setup steps** are introduced, record them in `deploy_guide.md` at the project root. This ensures installation, configuration, and deployment knowledge is systematically documented for the team.
-
-### When to Run Job 3
-
-Run this job **only when new frameworks/tools are detected** in the current changeset. Skip entirely if no new framework was introduced.
-
-### Step 3-1: Detect New Frameworks
-
-From the `git diff --cached` (or `git diff`) output already collected in Job 1, check for newly added entries in dependency manifest files:
-
-```bash
-# Check for newly added dependencies in common manifest files
-git diff --cached -U0 -- 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
-```
-
-**Trigger conditions** (ANY match → proceed to Step 3-2):
-- New dependency added to `package.json` (dependencies/devDependencies)
-- New package in `requirements.txt`, `pyproject.toml`, `Pipfile`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`
-- New service in `docker-compose*.yml` (e.g., database, cache, message queue)
-- New `Dockerfile` created or base image changed
-- New system tool in `.tool-versions`, `.nvmrc`, `.python-version`
-- New CI/CD configuration file added (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`)
-
-**Filter out** (do NOT record):
-- Patch version bumps of existing dependencies (e.g., `1.2.3` → `1.2.4`)
-- Dev-only tools that need no manual setup (linters, formatters, type checkers)
-- Transitive dependencies (lock file changes without manifest changes)
-
-### Step 3-2: Record Framework Info
-
-For each detected new framework/tool, gather the following information from the code changes and dependency files:
-
-| 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 | Infer from code usage, feature context, or commit message |
-| **Install Command** | How to install locally | Standard install command for the ecosystem |
-| **Key Config** | Config files or env vars needed | Scan for new config files, `.env` entries, or env references in code |
-| **Notes** | Setup gotchas, required services, manual steps | Infer from Dockerfile, docker-compose, README references, or TRAPS |
-
-### Step 3-3: Update `deploy_guide.md`
-
-Write or append to `deploy_guide.md` at the project root using this template:
-
-```markdown
-# Deploy Guide
-
-> Auto-maintained by PrizmKit retrospective. 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**:
-- If `deploy_guide.md` does not exist → create it with the header and first framework entry
-- If `deploy_guide.md` exists → check if the framework already has a section (match by `### <Name>` heading). If yes, update version and any changed config. If no, append a new section.
-- Preserve any manually added content (sections not matching the template are left untouched)
-- Keep entries sorted alphabetically by framework name within `## Frameworks & Tools`
-
-**Stage the file**:
-```bash
-git add deploy_guide.md
-```
-
-### Example
-
-After adding PostgreSQL via docker-compose and Prisma ORM to a Node.js project:
-
-```markdown
-# Deploy Guide
-
-> Auto-maintained by PrizmKit retrospective. Manual edits are preserved.
-> Last updated: 2026-03-27
-
-## Frameworks & Tools
-
-### PostgreSQL
-
-- **Version**: 16
-- **Purpose**: Primary relational database for user data, orders, and product catalog
-- **Install**:
-  ```bash
-  docker compose up -d postgres
-  ```
-- **Key Config**:
-  - `DATABASE_URL` (env): PostgreSQL connection string, format `postgresql://user:pass@host:5432/dbname`
-  - `docker-compose.yml`: Service `postgres` with volume `pgdata`
-- **Notes**:
-  - Requires Docker running locally
-  - Run `npx prisma migrate deploy` after first start to initialize schema
-
-### Prisma
-
-- **Version**: ^5.20.0
-- **Purpose**: ORM for type-safe database access and schema migrations
-- **Install**:
-  ```bash
-  npm install prisma @prisma/client
-  npx prisma generate
-  ```
-- **Key Config**:
-  - `prisma/schema.prisma`: Database schema definition
-  - `DATABASE_URL` (env): Shared with PostgreSQL connection
-- **Notes**:
-  - After schema changes: `npx prisma migrate dev --name <description>`
-  - Generate client after pull: `npx prisma generate`
-```
-
----
-
 ## Final: Changelog + Stage
 
 **3a.** Append to `.prizm-docs/changelog.prizm`:
@@ -287,8 +160,6 @@ After adding PostgreSQL via docker-compose and Prisma ORM to a Node.js project:
 **3b.** Stage all doc changes:
 ```bash
 git add .prizm-docs/
-# Stage deploy guide if it was created/updated
-git add deploy_guide.md 2>/dev/null || true
 ```
 
 **3c.** Handoff:
@@ -318,5 +189,4 @@ The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show change
 
 - `.prizm-docs/*.prizm` — Structurally synced + TRAPS/RULES/DECISIONS enriched
 - `.prizm-docs/changelog.prizm` — Appended entries
-- `deploy_guide.md` — New framework/tool setup instructions (only when new frameworks detected)
-- All `.prizm-docs/` changes and `deploy_guide.md` staged via `git add`
+- All `.prizm-docs/` changes staged via `git add`

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

@@ -39,11 +39,21 @@ Create structured feature specifications from natural language descriptions. Thi
    - Scope boundaries (In scope / Out of scope)
    - Dependencies and constraints
    - `[NEEDS CLARIFICATION]` markers for ambiguous items (max 3)
-7. Run internal quality validation loop (max 3 iterations):
+7. **Database design detection**: If the feature involves data persistence (new entities, new fields, schema changes), add a `## Data Model` section to spec.md (see template):
+   - Scan for existing database schema files to understand current conventions:
+     ```bash
+     find . -maxdepth 4 -type f \( -name "*.prisma" -o -name "*.sql" -o -path "*/migrations/*" -o -path "*/models/*" -o -name "schema.*" -o -name "*.entity.*" \) -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' | head -20
+     ```
+   - Read existing schema/model files to extract conventions: naming style (snake_case vs camelCase), ID strategy (UUID vs auto-increment), timestamp patterns, soft-delete approach, constraint patterns, relationship patterns
+   - Document in spec.md Data Model section: existing schema reference, new entities needed, relationships to existing tables
+   - Mark uncertain fields or relationships with `[NEEDS CLARIFICATION]` — these MUST be resolved before planning
+   - **RULE**: Never design new tables in isolation — always reference existing schema to maintain style consistency
+8. Run internal quality validation loop (max 3 iterations):
    - Check: All user stories have acceptance criteria?
    - Check: Scope boundaries clearly defined?
    - Check: No more than 3 `[NEEDS CLARIFICATION]` markers?
-8. Output: `spec.md` path and summary
+   - Check: If Data Model section exists, are existing schema conventions documented?
+9. Output: `spec.md` path and summary
 
 ## Writing Principles
 

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

@@ -24,6 +24,25 @@
 ## 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]
 

package/package.json

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