prizmkit 1.0.148 → 1.0.150

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.148",
-  "bundledAt": "2026-03-31T16:37:46.664Z",
-  "bundledFrom": "b56218a"
+  "frameworkVersion": "1.0.150",
+  "bundledAt": "2026-03-31T17:59:38.986Z",
+  "bundledFrom": "51bf160"
 }

package/bundled/adapters/claude/command-adapter.js

@@ -11,7 +11,7 @@
 
 import { parseFrontmatter, buildMarkdown } from '../shared/frontmatter.js';
 import { COMMANDS_DIR } from './paths.js';
-import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { existsSync, mkdirSync, cpSync, readdirSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'path';
 
@@ -100,11 +100,13 @@ export function convertSkillToCommand(skillContent, skillName) {
  */
 export async function installCommand(corePath, targetRoot) {
   const skillName = path.basename(corePath);
-  const hasAssets = existsSync(path.join(corePath, 'assets'));
-  const hasScripts = existsSync(path.join(corePath, 'scripts'));
-  const hasRules = existsSync(path.join(corePath, 'rules'));
 
-  if (hasAssets || hasScripts || hasRules) {
+  // Discover all subdirectories in the skill
+  const subdirs = existsSync(corePath)
+    ? readdirSync(corePath, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)
+    : [];
+
+  if (subdirs.length > 0) {
     // Use directory structure for commands with resources
     const targetDir = path.join(targetRoot, COMMANDS_DIR, skillName);
     mkdirSync(targetDir, { recursive: true });
@@ -117,12 +119,9 @@ export async function installCommand(corePath, targetRoot) {
       await writeFile(path.join(targetDir, `${skillName}.md`), converted);
     }
 
-    // Copy assets and scripts
-    for (const subdir of ['scripts', 'assets', 'rules']) {
-      const srcSubdir = path.join(corePath, subdir);
-      if (existsSync(srcSubdir)) {
-        cpSync(srcSubdir, path.join(targetDir, subdir), { recursive: true });
-      }
+    // Copy all subdirectories
+    for (const subdir of subdirs) {
+      cpSync(path.join(corePath, subdir), path.join(targetDir, subdir), { recursive: true });
     }
   } else {
     // Single file command

package/bundled/skills/_metadata.json

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

@@ -58,23 +58,21 @@ Do NOT use this skill when the user only wants to run the pipeline (`dev-pipelin
 
 ## Resource Loading Rules (Mandatory)
 
-`SKILL_DIR` definition:
-- `SKILL_DIR` is the absolute path of this skill directory.
 1. **Choose scenario reference before planning**:
-   - New app → read `references/new-app-planning.md`
-   - Existing app incremental features → read `references/incremental-feature-planning.md`
+   - New app → read `${SKILL_DIR}/references/new-app-planning.md`
+   - Existing app incremental features → read `${SKILL_DIR}/references/incremental-feature-planning.md`
 
 2. **Use shared quality examples as needed**:
-   - read `assets/planning-guide.md` for decomposition and acceptance criteria patterns
+   - read `${SKILL_DIR}/assets/planning-guide.md` for decomposition and acceptance criteria patterns
 
 3. **Load on-demand references when triggered**:
-   - Validation errors or interrupted session → read `references/error-recovery.md`
-   - Architecture decisions emerged → read `references/architecture-decisions.md`
-   - Browser interaction fields needed → read `references/browser-interaction.md`
+   - Validation errors or interrupted session → read `${SKILL_DIR}/references/error-recovery.md`
+   - Architecture decisions emerged → read `${SKILL_DIR}/references/architecture-decisions.md`
+   - Browser interaction fields needed → read `${SKILL_DIR}/references/browser-interaction.md`
 
 4. **Brainstorm deep-dive** — If the user chooses to continue discussing or exploring ideas before finalizing features (e.g., during Intent Confirmation the user selects "just explore ideas", or at any point says "let's discuss more" / "I want to think through this"):
-   → read `references/brainstorm-guide.md` and follow its four-phase structured ideation process (Assess Clarity → Understand → Explore Approaches → Capture Design)
-   → During Phase C (Explore Approaches), also read `references/red-team-checklist.md` for adversarial critique of each approach
+   → read `${SKILL_DIR}/references/brainstorm-guide.md` and follow its four-phase structured ideation process (Assess Clarity → Understand → Explore Approaches → Capture Design)
+   → During Phase C (Explore Approaches), also read `${SKILL_DIR}/references/red-team-checklist.md` for adversarial critique of each approach
    → When brainstorm Phase D produces a "Capture Design" summary, use it as the Vision Summary (fulfilling CP-AP-2) and proceed to Phase 2 (constraints and tech assumptions)
 
 5. **Frontend / UI design check** — Evaluate during Phase 2 (constraints and tech assumptions), after tech stack is confirmed. If the project has a frontend framework:
@@ -82,17 +80,17 @@ Do NOT use this skill when the user only wants to run the pipeline (`dev-pipelin
    → Also search the active CLI's project instruction file (`CLAUDE.md` / `CODEBUDDY.md`) for keywords: "UI", "UX", "design system", "style guide", "theme", "typography", "color palette"
    → If unified design guidance is found → use it as constraint for feature descriptions
    → If NO unified design guidance found → ask user: "项目中未找到统一的 UI/UX 设计规范。是否需要在特性规划前先建立一套 UI/UX 设计方向？(No unified UI/UX design system found. Would you like to establish one before feature planning?)"
-   → If yes → read `references/frontend-design-guide.md` and conduct a design direction session. Capture the result in the project instruction file (with user consent).
+   → If yes → read `${SKILL_DIR}/references/frontend-design-guide.md` and conduct a design direction session. Capture the result in the project instruction file (with user consent).
    → If no → proceed without; individual features may still define their own UI approach.
 
 6. **Project conventions check** — After Intent Confirmation (CP-AP-0), before brainstorm or Phase 1 vision work. This runs regardless of session goal (produce or explore):
    → Read `.prizmkit/project-conventions.json` if it exists
    → If the file exists but cannot be parsed as valid JSON → warn user ("conventions file is corrupted, will re-ask all questions"), treat all conventions as unanswered
-   → Cross-reference with `references/project-conventions.md` for the full question list
+   → Cross-reference with `${SKILL_DIR}/references/project-conventions.md` for the full question list
    → For any convention with a `null` or missing value → batch all unanswered questions into a single prompt to the user
    → Save answers to `.prizmkit/project-conventions.json` (create `.prizmkit/` directory if needed — this is an allowed writable output)
    → If all conventions are already answered → skip silently, do not re-ask
-   → Use convention answers as context when writing feature descriptions and proposing features (see `references/project-conventions.md` §How Conventions Are Used)
+   → Use convention answers as context when writing feature descriptions and proposing features (see `${SKILL_DIR}/references/project-conventions.md` §How Conventions Are Used)
 
 7. **Always validate output via script**:
    - run:
@@ -134,7 +132,7 @@ Classify user intent first:
 Use when user starts from idea/blank slate or asks for initial end-to-end plan.
 
 Actions:
-1. Load `references/new-app-planning.md`
+1. Load `${SKILL_DIR}/references/new-app-planning.md`
 2. Run interactive planning phases
 3. Generate initial `feature-list.json`
 
@@ -142,7 +140,7 @@ Actions:
 Use when user already has app/code/plan and asks to add or adjust features.
 
 Actions:
-1. Load `references/incremental-feature-planning.md`
+1. Load `${SKILL_DIR}/references/incremental-feature-planning.md`
 2. Read existing `feature-list.json` first (if missing, ask whether to start new plan)
 3. Append features with next sequential `F-NNN` IDs
 4. Preserve style/language/detail consistency with existing plan
@@ -159,7 +157,7 @@ After scenario routing, immediately confirm the user's deliverable intent:
    - **"Produce feature-list.json"** → Continue to Core Workflow. Set session goal = `produce`.
    - **"Just explore ideas"** → Enter **Exploration Mode**:
      - Run project conventions check first (CP-AP-1) — same as produce mode
-     - Load `references/brainstorm-guide.md` and follow its structured ideation process (Phases A-D)
+     - Load `${SKILL_DIR}/references/brainstorm-guide.md` and follow its structured ideation process (Phases A-D)
      - Brainstorm Phase D output serves as the Vision Summary (CP-AP-2)
      - Continue with Phase 2 (constraints — including frontend design check CP-AP-3 if applicable), then Phases 3-5 normally
      - At Phase 5 completion, re-ask: "Ideas are taking shape. Ready to generate `feature-list.json` now?"
@@ -206,11 +204,11 @@ Note: Checkpoint numbers (CP-AP-N) are sequential identifiers for the gate, NOT
 | **CP-AP-6** | `feature-list.json` Generated | Schema validates, all required keys present | 6-7 |
 | **CP-AP-7** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 8 |
 
-**Resume Detection**: If existing artifacts are found, read `references/error-recovery.md` §Resume Support for checkpoint-based resumption.
+**Resume Detection**: If existing artifacts are found, read `${SKILL_DIR}/references/error-recovery.md` §Resume Support for checkpoint-based resumption.
 
 ## Architecture Decision Capture
 
-After Phase 5, if framework-shaping architecture decisions emerged during planning (tech stack, communication patterns, data model strategies — not individual feature details), read `references/architecture-decisions.md` and follow the capture flow. Most sessions will NOT produce architecture decisions — only capture when genuinely impactful.
+After Phase 5, if framework-shaping architecture decisions emerged during planning (tech stack, communication patterns, data model strategies — not individual feature details), read `${SKILL_DIR}/references/architecture-decisions.md` and follow the capture flow. Most sessions will NOT produce architecture decisions — only capture when genuinely impactful.
 
 ## Fast Path — Incremental Shortcuts
 
@@ -270,7 +268,7 @@ A feature is **exempt** when ANY of these are true:
 
 ### Default Behavior (Phase 4.2)
 
-1. **Auto-generate** `browser_interaction` for ALL qualifying features. Read `references/browser-interaction.md` for the object format and field rules.
+1. **Auto-generate** `browser_interaction` for ALL qualifying features. Read `${SKILL_DIR}/references/browser-interaction.md` for the object format and field rules.
 2. **Present a summary** to the user showing which features received `browser_interaction`:
    > "以下 N 个前端特性已自动添加 browser_interaction 用于 Playwright 自动验证：F-002, F-004, F-007。如需移除某个特性的浏览器验证，请告知。"
 3. **User can opt-OUT** specific features — remove the field for declined features.
@@ -371,7 +369,7 @@ When launcher is available, do not prioritize raw scripts.
 
 ## Error Recovery & Resume
 
-If validation fails or a session is interrupted → read `references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
+If validation fails or a session is interrupted → read `${SKILL_DIR}/references/error-recovery.md` for the full error type table, decision tree, retry logic, and checkpoint-based resume support.
 
 Key behaviors:
 - Warnings only → proceed with user approval

package/bundled/skills/app-planner/references/architecture-decisions.md

@@ -0,0 +1,48 @@
+# Architecture Decision Capture
+
+During planning, key **framework-level** architectural decisions may emerge. When they do, capture them in the project instruction file so all future AI sessions have this context.
+
+## What Qualifies (ALL must apply)
+
+Only capture decisions that are **framework-shaping** — NOT individual feature details. Qualifying categories:
+
+| Category | Examples |
+|----------|----------|
+| Tech stack choices | PostgreSQL over MongoDB, React over Vue, Node.js runtime |
+| Communication patterns | REST vs GraphQL, WebSocket vs SSE vs polling |
+| Architectural patterns | Monorepo, microservices, monolith, event-driven |
+| Data model strategies | Relational vs document, event sourcing, CQRS |
+| Security architecture | JWT vs session, OAuth provider, RBAC model |
+
+**Do NOT capture**: individual feature implementation details, UI component choices, specific API endpoint designs, or anything scoped to a single feature.
+
+**This is conditional** — most planning sessions will NOT produce architecture decisions. Only capture when genuinely impactful decisions are made during the discussion.
+
+## When to Capture
+
+After Phase 5 (DAG verification), before Phase 6 (JSON generation). At this point decisions are settled.
+
+## How to Capture
+
+1. **Detect platform** — determine which project instruction file to update:
+   - `.claude/` directory exists → append to `CLAUDE.md`
+   - `.codebuddy/` directory exists → append to `CODEBUDDY.md`
+   - Both exist → append to both
+   - Neither exists → skip (no project instruction file)
+
+2. **Check for existing section** — read the target file and look for `### Architecture Decisions` heading:
+   - If heading exists → append new entries below it (avoid duplicates with existing entries)
+   - If heading does not exist → create it at the end of the file
+
+3. **Format** — one line per decision, no feature IDs:
+   ```markdown
+   ### Architecture Decisions
+   - WebSocket for real-time: sub-second latency required for collaboration features
+   - PostgreSQL: relational data model with complex queries, ACID compliance needed
+   - Monorepo structure: shared types between frontend and backend
+   ```
+
+4. **User confirmation** — before writing, show the collected decisions and ask:
+   > "These architecture decisions were identified during planning. Record them to [CLAUDE.md / CODEBUDDY.md]? (Y/n)"
+
+   If user declines, skip without further prompting.

package/bundled/skills/app-planner/references/brainstorm-guide.md

@@ -0,0 +1,101 @@
+# Brainstorm Guide — Structured Ideation Before Implementation
+
+> Separate WHAT from HOW. Explore the problem space before committing to a solution.
+
+This guide provides the structured brainstorming framework used in Phase 1 of the workflow.
+The AI facilitates this process as a **design collaborator**, not a builder.
+
+## Four Phases
+
+### Phase A: Assess Clarity
+
+Evaluate the user's initial goal statement:
+
+- **Clear** — Specific and actionable (e.g., "add JWT auth to the API")
+- **Vague** — Direction exists but needs narrowing (e.g., "improve security")
+- **Exploring** — No firm goal yet, just a direction (e.g., "something with auth")
+
+If **vague** or **exploring**, ask follow-up questions to sharpen the goal.
+Do NOT proceed until there is a concrete, testable problem statement (one sentence).
+
+### Phase B: Understand the Idea
+
+Answer these questions (use codebase exploration as needed):
+
+1. **What problem does this solve?** — State the pain point in concrete terms.
+2. **Who benefits?** — End users, developers, operators?
+3. **What exists today?** — Current state, prior art in the codebase, adjacent systems.
+4. **What constraints matter?** — Performance, compatibility, security, timeline.
+
+Non-functional requirements to explicitly clarify or propose defaults for:
+- Performance expectations
+- Scale (users, data, traffic)
+- Security or privacy constraints
+- Reliability / availability needs
+- Maintenance and ownership expectations
+
+If the user is unsure on any point, propose reasonable defaults and clearly mark them as **assumptions**.
+
+Summarize findings before moving on. If anything is unclear, ask.
+
+### Phase C: Explore Approaches
+
+Generate **2-3 distinct approaches**. For each:
+
+- **Name** — Short label (e.g., "JWT middleware", "OAuth proxy")
+- **How it works** — 2-3 sentences
+- **Pros** — What it gets right
+- **Cons** — What it gets wrong or defers
+- **Effort** — Rough scope (small / medium / large)
+
+#### Adversarial Critique (Red Team)
+
+Before asking the user to choose, stress-test each approach using the red team checklist
+(`references/red-team-checklist.md`):
+
+1. What breaks first?
+2. What's the hidden cost?
+3. What assumption is wrong?
+4. Who disagrees?
+
+Mark any approach that fails 2+ red team questions as **HIGH RISK**.
+If all approaches fail, generate a hybrid addressing the weaknesses.
+
+Present the comparison and let the user pick an approach or request a hybrid.
+
+### Phase D: Capture Design
+
+Produce a structured summary:
+
+```markdown
+## Problem Statement
+[One sentence, testable]
+
+## Approaches Considered
+[2-3 approaches with pros/cons/effort]
+
+## Selected Approach
+[User's choice + rationale]
+
+## Assumptions
+[All assumptions explicitly listed]
+
+## Open Questions
+[Unresolved items, if any]
+
+## Key Decisions
+[What was decided and why — alternatives and rationale]
+```
+
+This summary becomes the input for the next phase (specification or planning).
+
+---
+
+## Rules
+
+- Ask as many questions as needed — no rushing
+- One topic at a time for complex clarifications
+- Prefer multiple-choice questions when possible
+- Assumptions must be explicit, never silent
+- YAGNI ruthlessly — avoid premature complexity
+- Do NOT implement, code, or modify behavior during brainstorming

package/bundled/skills/app-planner/references/browser-interaction.md

@@ -0,0 +1,34 @@
+# Browser Interaction Planning
+
+For web apps with UI, features that involve user-facing pages or interactive flows can optionally include a `browser_interaction` field. This enables the dev-pipeline to verify UI behavior automatically using `playwright-cli` after implementation.
+
+## How to Capture
+
+During Phase 4 (refine descriptions and acceptance criteria), for qualifying features ask:
+
+> "This feature has UI behavior. Want to add browser verification so the pipeline can auto-check it after implementation? (Y/n)"
+
+If yes, generate the `browser_interaction` object:
+
+```json
+{
+  "browser_interaction": {
+    "url": "http://localhost:3000/login",
+    "setup_command": "npm run dev",
+    "verify_steps": [
+      "snapshot",
+      "click <ref> — click login button",
+      "fill <ref> 'test@example.com' — enter email",
+      "screenshot"
+    ],
+    "screenshot": true
+  }
+}
+```
+
+## Field Rules
+
+- `url` is required — the page URL to verify
+- `setup_command` is optional — command to start dev server (omit if already running)
+- `verify_steps` are descriptive placeholders — the actual `ref` IDs are resolved at runtime by `playwright-cli snapshot`. Use natural language descriptions (e.g., "click login button") that the pipeline agent will map to real refs.
+- `screenshot` defaults to `true` — capture final state for human review

package/bundled/skills/app-planner/references/error-recovery.md

@@ -0,0 +1,109 @@
+# Error Recovery & Resume Support
+
+Structured error handling for validation failures, interrupted sessions, and checkpoint-based resumption.
+
+## Validation Failures
+
+When `python3 scripts/validate-and-generate.py validate --input <file> --mode <mode>` returns errors:
+
+### Parse validation output
+Script returns JSON with `"valid": false`, `"errors": [...]`, `"warnings": [...]`
+
+### Decision Tree
+
+**if `error_count == 0` (warnings only):**
+- Proceed with user approval
+- Show warnings and ask: "Continue? (Y/n)"
+
+**elif `error_count > 0` (critical errors):**
+
+Group errors by type and apply targeted fixes:
+
+| Error Type | Symptom | Fix Offered | Auto-Fix? |
+|-----------|---------|------------|-----------|
+| **Schema mismatch** | `$schema` invalid, missing `app_name`, wrong `features` type | "Set `$schema` to `dev-pipeline-feature-list-v1`, `app_name` to string" | Yes |
+| **Feature ID issues** | Invalid format (not `F-NNN`), duplicate IDs, undefined refs | "Suggest corrected IDs, show duplicates" | Yes |
+| **Dependency errors** | Circular dependency, undefined target features | "Show cycle chain (e.g., `F-003 → F-005 → F-003`), suggest break point" | No |
+| **Missing fields** | Feature missing required keys (title, description, AC) | "List each feature + missing keys, guide patch" | Partial |
+| **Insufficient AC** | Feature has <2 acceptance criteria | "Show feature, suggest AC examples" | No |
+| **Invalid values** | complexity not in [low/medium/high], status not pending | "Show field, valid values" | Yes |
+
+### Execution
+
+```
+For auto-fixable errors:
+  1. Show summary: "Found N schema/ID/format issues"
+  2. Offer: auto-fix? (Y/n)
+  3. Apply fix → regenerate file
+  4. Re-run validation
+  5. If new errors → loop (max 2 more attempts)
+
+For manual fixes (dependencies, AC content):
+  1. Show concise prompt: "Edit line X-Y in feature-list.json"
+  2. Wait for user action
+  3. Retry validation (max 2 more attempts)
+
+if all_retries_exceeded:
+  → Escalate: "After 3 attempts, validation still fails.
+              (a) Review file manually, OR
+              (b) Restart planning from Phase 1"
+```
+
+## Resume Support
+
+App-planner sessions can be resumed from the last completed checkpoint without losing context.
+
+### Detection Logic
+
+Check for artifact files in working directory:
+
+| Artifacts Found | Last Completed Checkpoint | Next Phase | Resume Action |
+|-----------------|--------------------------|-----------|----------------|
+| None | (new session) | Phase 1: Vision | Start fresh planning |
+| `feature-list.json` exists | CP-AP-6 (file generated) | Phase 7: Final validation | Offer to validate or extend |
+| `feature-list.json` + validation passed | CP-AP-7 (validation pass) | Handoff: dev-pipeline | Offer: execute pipeline now |
+| Partial state (incomplete file) | CP-AP-2 or CP-AP-4 | Next phase after last checkpoint | Resume interactive planning |
+| User restarts mid-session | User says "restart" | Return to Phase 1 Vision, or load previous checkpoint if requested |
+| Max validation retries exceeded | 3 failed validation loops | Offer: (a) manual review, (b) restart from Phase 1 |
+
+### Resume Command (Project Structure)
+
+For projects using `.prizmkit/` structure:
+
+```bash
+# Explicit resume (if file is not in current directory):
+app-planner --resume-from <path-to-existing-feature-list.json>
+```
+
+AI detects existing file → suggests:
+```
+"Existing plan found with N features, M newly added.
+Resume incremental planning? (Y/n)"
+```
+
+### Incremental Mode Abort
+
+If in Incremental mode but existing `feature-list.json` not found:
+- Ask: "Start new plan or provide existing file?"
+- If new plan chosen → switch to Route A (New App Planning)
+- If existing file uploaded → continue Route B
+
+### Artifact Path Convention
+
+**CRITICAL PATH RULE**: `feature-list.json` MUST be written to the project root directory
+(same level as `package.json` / `.git`).
+
+Before writing, verify: `ls package.json .git 2>/dev/null` — if these exist in the current
+directory, you are at the project root. NEVER write to `dev-pipeline/` or any subdirectory.
+
+After writing, verify: `ls -la feature-list.json` from project root.
+
+```
+<project-root>/
+  ├── feature-list.json              # Primary output (always here, at project root)
+  └── .prizmkit/planning/            # Optional organization for backups
+      ├── feature-list.validated.json    # Checkpoint backup after CP-AP-7
+      └── <ISO-timestamp>.backup.json    # Optional incremental backups
+```
+
+The pipeline reads `feature-list.json` from the project root by default. If the user specifies a custom path, the launcher accepts it as an argument.

package/bundled/skills/app-planner/references/frontend-design-guide.md

@@ -0,0 +1,71 @@
+# Frontend Design Guide — High-Quality UI Implementation
+
+> Create distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics.
+
+**App-planner context**: In the planning phase, use this guide to establish **design direction decisions** (aesthetic tone, typography approach, color strategy, layout philosophy). Do NOT produce CSS, code, or implementation artifacts — capture the design direction as decisions in the project instruction file (`CLAUDE.md` / `CODEBUDDY.md`). Downstream implementation skills will consume these decisions when building features.
+
+Load this guide **only when the feature involves frontend/UI work**. Skip for backend-only or infrastructure features.
+
+## Context Gathering (Required Before Design)
+
+Before any UI design work, gather:
+- **Target audience**: Who uses this product and in what context?
+- **Use cases**: What jobs are they trying to get done?
+- **Brand personality/tone**: How should the interface feel?
+
+You cannot infer this from codebase alone — ask the user.
+
+## Design Direction
+
+Commit to a **bold** aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an intentional aesthetic — minimalist, editorial, brutalist, organic, luxury, playful, retro-futuristic, industrial, art deco, etc.
+- **Differentiation**: What makes this unforgettable?
+
+## Typography
+
+- Choose distinctive fonts. Pair a display font with a refined body font.
+- Use a modular type scale with fluid sizing (`clamp()`)
+- Vary font weights and sizes for clear visual hierarchy
+- Avoid overused fonts: Inter, Roboto, Arial, Open Sans, system defaults
+- Avoid monospace as lazy shorthand for "technical" vibes
+
+## Color & Theme
+
+- Use modern CSS color functions (oklch, color-mix, light-dark)
+- Tint neutrals toward brand hue for subconscious cohesion
+- Avoid: pure black (#000) or pure white (#fff) — always tint
+- Avoid: the AI palette (cyan-on-dark, purple-to-blue gradients, neon accents on dark)
+- Avoid: gradient text for "impact", default dark mode with glowing accents
+
+## Layout & Space
+
+- Create visual rhythm through varied spacing — not uniform padding
+- Use fluid spacing with `clamp()` that breathes on larger screens
+- Embrace asymmetry and unexpected compositions
+- Avoid: wrapping everything in cards, nesting cards, identical card grids
+- Avoid: centering everything, uniform spacing
+
+## Motion
+
+- Focus on high-impact moments: one well-orchestrated page load > scattered micro-interactions
+- Use exponential easing for natural deceleration
+- Use `transform` and `opacity` only — avoid animating layout properties
+- Avoid: bounce/elastic easing, excessive animations
+
+## Interaction
+
+- Use progressive disclosure — start simple, reveal complexity through interaction
+- Design empty states that teach the interface
+- Use optimistic UI — update immediately, sync later
+- Avoid: making every button primary, redundant headers
+
+## Responsive
+
+- Use container queries (`@container`) for component-level responsiveness
+- Adapt the interface for different contexts, don't just shrink it
+- Never hide critical functionality on mobile
+
+## The AI Slop Test
+
+If you showed this interface to someone and said "AI made this", would they believe you immediately? If yes, redesign. A distinctive interface should make someone ask "how was this made?" not "which AI made this?"

package/bundled/skills/app-planner/references/incremental-feature-planning.md

@@ -0,0 +1,112 @@
+# Incremental Feature Planning Reference
+
+Use this reference when the user adds features to an existing app/plan.
+
+## Pre-Checks
+
+1. Read existing `feature-list.json`.
+2. Determine current max ID and continue from next `F-NNN`.
+3. **Detect existing writing style** (see §Style Detection below).
+4. Preserve compatibility with existing dependency structure.
+5. **Project conventions** — handled by the main SKILL.md flow (rule #6) before incremental planning begins. No additional action needed here; conventions are loaded automatically.
+
+If `feature-list.json` is missing, ask whether to initialize a new plan.
+
+## Style Detection (Automatic)
+
+Before drafting new features, analyze existing plan to preserve consistency:
+
+1. **Language Detection**
+   - Scan `title` and `description` fields
+   - If >70% English titles → default to English
+   - If >70% Chinese titles → suggest Chinese (or allow bilingual)
+
+2. **Description Density**
+   - Calculate avg word count per description
+   - If avg <30 words → draft concise descriptions
+   - If avg 30-80 words → draft standard detail
+   - If avg >80 words → draft detailed descriptions
+
+3. **Acceptance Criteria Patterns**
+   - Count avg AC per feature
+   - Identify dominant format (Given/When/Then Gherkin, BDD, or loose)
+   - Draft new AC in same format
+
+4. **Complexity Distribution**
+   - Count low/medium/high distribution in existing features
+   - Alert if new features deviate significantly (>20 percentile points)
+   - Suggest rebalancing if needed
+
+### Style Consistency Prompt
+
+If new features deviate significantly from detected style:
+
+```
+"Your new features use avg X words/description, but existing features use Y.
+Current ratio: low:M%, medium:N%, high:O%.
+Adjust new features to match? (Y/n)"
+```
+
+Accept user choice, then adjust draft accordingly before JSON generation.
+
+## Incremental Planning Flow
+
+### Step 1: Clarify Increment Scope
+Capture:
+- business objective of the new increment
+- affected existing modules/features
+- timeline or priority constraints
+
+### Step 2: Impact Mapping
+For each candidate feature, identify:
+- upstream dependencies
+- downstream impacts
+- risk hotspots (auth, data migration, API compatibility)
+
+### Step 3: Append Features
+Append new items only (do not rewrite old validated features unless user asks).
+
+For each new feature:
+- assign next ID
+- set `status: "pending"`
+- link dependencies to existing IDs where needed
+- keep title in English
+- **write rich descriptions** (see `planning-guide.md` §4):
+  - minimum 15 words (validation error below this)
+  - recommended: 30+ words (low), 50+ words (medium), 80+ words (high complexity)
+  - include: what to build, key behaviors, integration points, data model, error/edge cases
+
+### Step 4: Rebalance Priority
+Allow priority updates for both old and new features if user requests reprioritization.
+Keep dependency correctness as first constraint.
+
+### Step 5: Validate
+Run:
+```bash
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json --mode incremental
+```
+
+Fix and re-run until pass.
+
+## Merge/Rewrite Rules
+
+- Default: append only
+- Rewrite existing features only when user explicitly asks
+- Never break valid IDs/references
+- Never set new features to `in_progress` or `completed`
+
+## Practical Prompts
+
+Use concise prompts during interaction:
+- "What is the goal of this increment? Which user problem is the priority?"
+- "Which existing Feature IDs do these new features depend on?"
+- "Do you want to reprioritize at the same time, or just append to the current sequence?"
+
+## Final Delivery Checklist
+
+- [ ] Existing file read before edits
+- [ ] New IDs continue sequence
+- [ ] Existing style preserved
+- [ ] Dependency graph still DAG
+- [ ] Validation passes
+- [ ] Next step recommendation follows priority: launcher → daemon → run.sh

package/bundled/skills/app-planner/references/new-app-planning.md

@@ -0,0 +1,85 @@
+# New App Planning Reference
+
+Use this reference when the user is planning a product from scratch.
+
+## Phase Guide
+
+### Phase 1: Vision
+Capture:
+- problem statement
+- target users
+- core value proposition
+- non-goals (what to exclude from MVP)
+
+### Phase 2: Stack Defaults
+If user has no preference, propose defaults aligned with project conventions:
+- Frontend: Next.js + TypeScript
+- Backend: Express/Nest (choose one and stay consistent)
+- DB: PostgreSQL
+- ORM: Prisma
+- Test: unit + e2e baseline
+
+If `.prizmkit/config.json` exists, prioritize its settings.
+
+### Phase 3: MVP Features
+Rules:
+- Include foundational setup feature first
+- Aim 5-12 features for MVP
+- Keep each feature implementable in one pipeline unit unless clearly too large
+
+For each feature define:
+- `id`
+- `title`
+- `description`
+- `priority` — string: `"high"`, `"medium"`, or `"low"` (never numeric)
+- `estimated_complexity`
+- `dependencies`
+- `acceptance_criteria`
+- `status: "pending"`
+- `browser_interaction` (optional — for UI features, see §Browser Interaction Planning in SKILL.md)
+
+### Phase 4: Dependency & Priority
+Check:
+- no cycles
+- all dependency targets exist
+- order is executable
+- priorities align with delivery value and risk
+
+### Phase 5: Granularity
+Split into `sub_features` when:
+- scope crosses too many modules
+- acceptance criteria are excessive
+- complexity is high and uncertainty is high
+
+### Phase 6: Generate + Validate
+1. Write `feature-list.json`.
+2. Run:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input feature-list.json --mode new
+   ```
+3. Fix all errors, then re-run.
+
+## Quality Rules
+
+- Keep titles concise and English
+- Make descriptions implementation-oriented (clear boundaries, interfaces, behavior)
+- **Description depth by complexity:**
+  - **Low complexity**: ≥30 words — what to build, key behavior, which files/modules are affected
+  - **Medium complexity**: ≥50 words — add integration points, data model overview, error handling approach
+  - **High complexity**: ≥80 words — add architecture decisions, performance considerations, security implications, migration strategy if applicable
+- **Description must cover** (adapt per feature):
+  1. **What**: concrete deliverable (API endpoints, UI components, data models)
+  2. **How it integrates**: which existing modules/services it connects to
+  3. **Key behaviors**: business rules, validation rules, state transitions
+  4. **Data model**: entities, relationships, key fields (when applicable)
+  5. **Error/edge cases**: what happens on failure, empty states, limits
+- Write testable acceptance criteria (at least 3; prefer 5+ for medium/high)
+- Keep dependency graph simple and explicit
+
+## Final Delivery Checklist
+
+- [ ] User confirmed MVP scope
+- [ ] IDs are sequential
+- [ ] `status` initialized to `pending`
+- [ ] Validation passes
+- [ ] Next step recommendation follows priority: launcher → daemon → run.sh

package/bundled/skills/app-planner/references/project-conventions.md

@@ -0,0 +1,93 @@
+# Project Conventions — First-Run Setup Questions
+
+> Capture project-wide norms once, reuse across all planning sessions.
+
+These questions establish foundational conventions that affect every feature. They should be asked **once** during the first `app-planner` session and persisted to `.prizmkit/project-conventions.json` so subsequent sessions skip them.
+
+## Persistence
+
+- **File**: `.prizmkit/project-conventions.json`
+- **Read on startup**: If the file exists and a convention has a non-null value, skip that question.
+- **Write after asking**: Save answers immediately after the user responds.
+- **Shared**: Other skills (`prizmkit-init`, `dev-pipeline`) may also read this file.
+
+## Convention Questions
+
+Ask only unanswered conventions. Group related questions together in a single prompt when possible.
+
+### 1. UI Display Language
+
+**Key**: `ui_language`
+
+> "What is the primary language for the application's user interface? (e.g., English, 中文, 日本語, etc.)"
+
+**Follow-up if applicable**: If the user specifies a non-English language, confirm whether all UI text (buttons, labels, error messages, tooltips) should be in that language.
+
+### 2. Multi-Language Support (i18n)
+
+**Key**: `i18n_enabled`, `i18n_languages`
+
+> "Does the application need multi-language support (i18n)?"
+
+- If **yes** → ask: "Which languages should be supported? List all target languages."
+- If **no** → set `i18n_enabled: false`, skip `i18n_languages`.
+
+**Impact on planning**: If i18n is enabled, add an infrastructure feature for i18n setup (framework, translation file structure, language switcher) early in the dependency graph.
+
+### 3. Date, Time & Currency Formats
+
+**Key**: `date_format`, `timezone_strategy`, `currency`
+
+> "What are your preferences for date/time and currency display?"
+
+Sub-questions (ask as a group):
+- **Date format**: "Preferred date display format?" (e.g., `YYYY-MM-DD`, `MM/DD/YYYY`, `DD/MM/YYYY`, locale-auto)
+- **Timezone strategy**: "How should the app handle timezones?" (e.g., UTC storage + local display, user-selected timezone, server timezone only)
+- **Currency**: "If the app handles money, which currency format?" (e.g., USD `$1,234.56`, CNY `¥1,234.56`, EUR `€1.234,56`, or N/A if no monetary values)
+
+If the user says "not applicable" for currency, set `currency: null`.
+
+### 4. Code & Git Language Conventions
+
+**Key**: `code_comment_language`, `git_commit_language`
+
+> "What language should be used for code comments and git commit messages?"
+
+Options to present:
+- **Code comments**: English / Chinese / Match UI language / Mixed
+- **Git commit messages**: English / Chinese / Match code comments
+
+**Default suggestion**: English for both (widely accessible, compatible with open-source contribution).
+
+## JSON Schema
+
+```json
+{
+  "ui_language": "English",
+  "i18n_enabled": false,
+  "i18n_languages": [],
+  "date_format": "YYYY-MM-DD",
+  "timezone_strategy": "utc_storage_local_display",
+  "currency": null,
+  "code_comment_language": "English",
+  "git_commit_language": "English"
+}
+```
+
+## How Conventions Are Used
+
+Conventions are **AI context** — they inform your behavior during planning but are NOT written into `feature-list.json` `global_context` fields. Specifically:
+
+- `ui_language` → Write feature descriptions and acceptance criteria in a way that acknowledges the target UI language (e.g., mention CJK text handling if Chinese, RTL layout if Arabic)
+- `i18n_enabled` → If true, consider proposing an i18n infrastructure feature early in the dependency graph; ensure feature descriptions mention translation-ready patterns
+- `date_format`, `timezone_strategy` → When features involve date/time display or storage, reference the chosen convention in feature descriptions
+- `currency` → When features involve monetary values, reference the currency convention in descriptions
+- `code_comment_language` → Inform the language used in code-related examples within feature descriptions
+- `git_commit_language` → Inform pipeline and workflow language expectations
+
+## Rules
+
+- **Ask at most once per convention** — if answered, never re-ask unless user invokes a reset.
+- **No blocking** — if the user skips a question ("I'll decide later"), set value to `null` and move on. The question will be re-asked next session.
+- **Respect existing config** — if `.prizmkit/config.json` already has equivalent fields (e.g., `tech_stack.language`), do not duplicate. Only ask questions not covered by existing config.
+- **Minimal interruption** — batch all unanswered questions into a single interaction round, not one-by-one.

package/bundled/skills/app-planner/references/red-team-checklist.md

@@ -0,0 +1,40 @@
+# Red Team Checklist for Ideation
+
+Use these questions to stress-test approaches during brainstorm Phase C.
+
+## Structural Questions
+
+1. **What breaks first?** — Identify the weakest link under stress (load, concurrency, edge cases, adversarial input). If you can't name a specific failure mode, the approach is under-specified.
+
+2. **What's the hidden cost?** — Every approach has costs beyond implementation time: maintenance burden, cognitive load for new contributors, infrastructure requirements, monitoring needs, migration complexity.
+
+3. **What assumption is wrong?** — List the unstated assumptions. Which one, if false, invalidates the approach? Common false assumptions: "the API won't change", "data fits in memory", "users will read the docs", "this library is maintained".
+
+4. **Who disagrees?** — Steel-man the opposing view. A performance engineer and a UX designer will critique the same approach differently. What does the most skeptical qualified person say?
+
+## Scoring
+
+| Red Team Failures | Classification |
+|-------------------|---------------|
+| 0 | Strong approach |
+| 1 | Viable with mitigation |
+| 2+ | HIGH RISK — needs rethinking or mitigation plan |
+
+## When All Approaches Are HIGH RISK
+
+If every approach fails 2+ questions, the problem statement may be wrong. Consider:
+- Is the goal too broad? Split it.
+- Is there a constraint you haven't stated? Surface it.
+- Generate a hybrid approach that addresses the specific red team failures.
+
+## Common False Assumptions
+
+| Assumption | Why It Fails |
+|-----------|-------------|
+| "The API won't change" | External APIs change without notice; pin versions and add contract tests |
+| "Data fits in memory" | Works in dev, breaks in prod when dataset grows 10x |
+| "Users will read the docs" | They won't; make the happy path obvious and errors informative |
+| "This library is maintained" | Check commit history; many popular libraries are effectively abandoned |
+| "We can refactor later" | Technical debt compounds; later never comes without explicit scheduling |
+| "Performance doesn't matter yet" | Architecture decisions that ignore performance are expensive to fix |
+| "The team will adopt it" | New tools need champions, training, and visible wins to gain traction |

package/bundled/skills/recovery-workflow/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "skill_name": "recovery-workflow",
+  "notes": "These test cases require pipeline state setup. Each has a setup_script that creates the necessary mock state before the skill is invoked. Due to the interactive nature and state-dependency of this skill, automated evaluation is limited — qualitative review is primary.",
+  "evals": [
+    {
+      "id": 1,
+      "name": "scenario-a-mid-implementation",
+      "prompt": "F-003 的 session 超时了，工作区里已经写了大部分代码了，帮我恢复一下",
+      "expected_output": "Should detect existing spec.md, plan.md with partial task completion, code changes in worktree. Should recommend 'Smart Resume' (continue_implementation). Should present clear recovery report showing what was found and what remains.",
+      "setup_description": "Create feature-list.json with F-003, .prizmkit/specs/003-*/spec.md and plan.md (3/5 tasks checked), some source files modified, pipeline state showing 'failed'.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "scenario-b-plan-only",
+      "prompt": "我看到 F-001 有 spec 和 plan 但是还没开始写代码，帮我从 plan 开始执行",
+      "expected_output": "Should detect spec.md and plan.md exist but no code changes. Should recommend 'Start Implementation'. Should read existing plan and begin implementing from task 1.",
+      "setup_description": "Create feature-list.json with F-001, .prizmkit/specs/001-*/spec.md and plan.md (0/4 tasks checked), no code changes, pipeline state showing 'failed' at early phase.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "name": "scenario-a-nearly-complete",
+      "prompt": "recover F-005. Token limit exceeded but I think the code is mostly done, tests should be passing",
+      "expected_output": "Should detect all plan tasks completed, code changes present, tests passing. Should recommend 'Review & Commit Only'. Should proceed to code review and commit without re-implementing.",
+      "setup_description": "Create feature-list.json with F-005, full spec.md and plan.md (all tasks checked), source files complete and tests passing, pipeline state showing 'failed' with token limit error.",
+      "files": []
+    }
+  ]
+}

package/package.json

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

package/src/scaffold.js

@@ -156,11 +156,11 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
       if (!frontmatter.name) frontmatter.name = skillName;
       await fs.writeFile(path.join(targetDir, 'SKILL.md'), buildMarkdown(frontmatter, body));
 
-      // 复制 assets/ 和 scripts/
-      for (const subdir of ['assets', 'scripts']) {
-        const srcSubdir = path.join(corePath, subdir);
-        if (await fs.pathExists(srcSubdir)) {
-          await fs.copy(srcSubdir, path.join(targetDir, subdir));
+      // 复制所有子目录（assets/, scripts/, references/ 等）
+      const cbEntries = await fs.readdir(corePath, { withFileTypes: true });
+      for (const entry of cbEntries) {
+        if (entry.isDirectory()) {
+          await fs.copy(path.join(corePath, entry.name), path.join(targetDir, entry.name));
         }
       }
 
@@ -170,8 +170,9 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
       const content = await fs.readFile(skillMdPath, 'utf8');
       const converted = convertSkillToCommand(content, skillName);
 
-      const hasAssets = await fs.pathExists(path.join(corePath, 'assets'));
-      const hasScripts = await fs.pathExists(path.join(corePath, 'scripts'));
+      // Discover all subdirectories in the skill
+      const clEntries = await fs.readdir(corePath, { withFileTypes: true });
+      const skillSubdirs = clEntries.filter(e => e.isDirectory()).map(e => e.name);
 
       // Always write the command file at the flat level (.claude/commands/skillName.md)
       // so Claude Code shows it as /skillName (not /skillName:skillName).
@@ -184,16 +185,13 @@ export async function installSkills(platform, skills, projectRoot, dryRun) {
       await fs.ensureDir(commandsDir);
       await fs.writeFile(path.join(commandsDir, `${skillName}.md`), converted);
 
-      if (hasAssets || hasScripts) {
-        // Place assets/scripts outside .claude/commands/ to prevent Claude Code
+      if (skillSubdirs.length > 0) {
+        // Place subdirectories outside .claude/commands/ to prevent Claude Code
         // from registering them as slash commands (e.g. /skillName:assets:file).
         const assetTargetDir = path.join(projectRoot, '.claude', 'command-assets', skillName);
         await fs.ensureDir(assetTargetDir);
-        for (const subdir of ['assets', 'scripts']) {
-          const srcSubdir = path.join(corePath, subdir);
-          if (await fs.pathExists(srcSubdir)) {
-            await fs.copy(srcSubdir, path.join(assetTargetDir, subdir));
-          }
+        for (const subdir of skillSubdirs) {
+          await fs.copy(path.join(corePath, subdir), path.join(assetTargetDir, subdir));
         }
       }
       console.log(chalk.green(`      ✓ .claude/commands/${skillName}.md`));