prizmkit 1.0.131 → 1.0.133

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.131",
-  "bundledAt": "2026-03-28T07:24:10.796Z",
-  "bundledFrom": "b143c05"
+  "frameworkVersion": "1.0.133",
+  "bundledAt": "2026-03-28T10:09:48.381Z",
+  "bundledFrom": "242cd4e"
 }

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

@@ -166,47 +166,12 @@ Key decisions: [list]
 
 Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
 
-**Before starting**: Run these commands to learn available playwright-cli commands and usage:
-```bash
-playwright-cli --help
-```
-For detailed help on a specific command:
-```bash
-playwright-cli --help <command>   # e.g. playwright-cli --help snapshot
-```
-Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format and workflow patterns.
-
-1. **Start dev server** (if `setup_command` is specified):
-   ```bash
-   {{BROWSER_SETUP_COMMAND}} &
-   DEV_SERVER_PID=$!
-   sleep 5  # wait for server to start
-   ```
-
-2. **Open browser and navigate**:
-   ```bash
-   playwright-cli open {{BROWSER_URL}}
-   ```
-
-3. **Take snapshot and execute verify steps**:
-   ```bash
-   playwright-cli snapshot
-   ```
-   Read the snapshot file to identify element refs. Then execute each verify step by mapping the descriptive step to actual refs from the snapshot.
+1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
+2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-
-4. **Capture final screenshot**:
-   ```bash
-   playwright-cli screenshot
-   ```
-
-5. **Close browser and cleanup**:
-   ```bash
-   playwright-cli close
-   kill $DEV_SERVER_PID 2>/dev/null || true
-   ```
-
-6. **Log results** — append to `context-snapshot.md`:
+3. Take a final screenshot for evidence.
+4. Close browser and stop dev server.
+5. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
@@ -215,7 +180,7 @@ Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format
    Result: PASS / FAIL (reason)
    ```
 
-If any step fails, log the failure and continue to Phase 4. Do NOT retry browser verification.
+If any step fails, log the failure and continue. Do NOT retry browser verification.
 {{END_IF_BROWSER_INTERACTION}}
 
 ### Phase 4: Architecture Sync & Commit (SINGLE COMMIT)

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

@@ -280,47 +280,12 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
 
-**Before starting**: Run these commands to learn available playwright-cli commands and usage:
-```bash
-playwright-cli --help
-```
-For detailed help on a specific command:
-```bash
-playwright-cli --help <command>   # e.g. playwright-cli --help snapshot
-```
-Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format and workflow patterns.
-
-1. **Start dev server** (if `setup_command` is specified):
-   ```bash
-   {{BROWSER_SETUP_COMMAND}} &
-   DEV_SERVER_PID=$!
-   sleep 5  # wait for server to start
-   ```
-
-2. **Open browser and navigate**:
-   ```bash
-   playwright-cli open {{BROWSER_URL}}
-   ```
-
-3. **Take snapshot and execute verify steps**:
-   ```bash
-   playwright-cli snapshot
-   ```
-   Read the snapshot file to identify element refs. Then execute each verify step by mapping the descriptive step to actual refs from the snapshot.
+1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
+2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-
-4. **Capture final screenshot**:
-   ```bash
-   playwright-cli screenshot
-   ```
-
-5. **Close browser and cleanup**:
-   ```bash
-   playwright-cli close
-   kill $DEV_SERVER_PID 2>/dev/null || true
-   ```
-
-6. **Log results** — append to `context-snapshot.md`:
+3. Take a final screenshot for evidence.
+4. Close browser and stop dev server.
+5. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
@@ -329,7 +294,7 @@ Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format
    Result: PASS / FAIL (reason)
    ```
 
-If any step fails, log the failure and continue to Phase 6. Do NOT retry browser verification.
+If any step fails, log the failure and continue. Do NOT retry browser verification.
 {{END_IF_BROWSER_INTERACTION}}
 
 ### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)

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

@@ -380,47 +380,12 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 Verify UI behavior using `playwright-cli` before committing. This phase is best-effort — failures are logged but do NOT block the commit.
 
-**Before starting**: Run these commands to learn available playwright-cli commands and usage:
-```bash
-playwright-cli --help
-```
-For detailed help on a specific command:
-```bash
-playwright-cli --help <command>   # e.g. playwright-cli --help snapshot
-```
-Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format and workflow patterns.
-
-1. **Start dev server** (if `setup_command` is specified):
-   ```bash
-   {{BROWSER_SETUP_COMMAND}} &
-   DEV_SERVER_PID=$!
-   sleep 5  # wait for server to start
-   ```
-
-2. **Open browser and navigate**:
-   ```bash
-   playwright-cli open {{BROWSER_URL}}
-   ```
-
-3. **Take snapshot and execute verify steps**:
-   ```bash
-   playwright-cli snapshot
-   ```
-   Read the snapshot file to identify element refs. Then execute each verify step by mapping the descriptive step to actual refs from the snapshot.
+1. Start dev server if needed: `{{BROWSER_SETUP_COMMAND}}`
+2. Use `playwright-cli` to open `{{BROWSER_URL}}`, then verify:
    {{BROWSER_VERIFY_STEPS}}
-
-4. **Capture final screenshot**:
-   ```bash
-   playwright-cli screenshot
-   ```
-
-5. **Close browser and cleanup**:
-   ```bash
-   playwright-cli close
-   kill $DEV_SERVER_PID 2>/dev/null || true
-   ```
-
-6. **Log results** — append to `context-snapshot.md`:
+3. Take a final screenshot for evidence.
+4. Close browser and stop dev server.
+5. Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
    URL: {{BROWSER_URL}}
@@ -429,7 +394,7 @@ Also read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format
    Result: PASS / FAIL (reason)
    ```
 
-If any step fails, log the failure and continue to Phase 6. Do NOT retry browser verification.
+If any step fails, log the failure and continue. Do NOT retry browser verification.
 {{END_IF_BROWSER_INTERACTION}}
 
 

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.131",
+  "version": "1.0.133",
   "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,20 @@ Plan deliverable features for dev-pipeline in two modes:
 
 Always produce a validated `feature-list.json` that conforms to `dev-pipeline-feature-list`.
 
+## Invocation Commitment (Hard Rule)
+
+**When the user invokes `/app-planner`, you MUST execute the app-planner workflow.** You must NEVER:
+- Decide on the user's behalf that the task "doesn't need app-planner"
+- Skip app-planner to jump directly to spec/plan/implement or any other skill
+- Bypass the interactive phases because you judge the task to be "simple" or "obvious"
+
+If you believe the task is better suited for a different workflow (e.g., fast path via `/prizmkit-plan`), you MUST:
+1. **Explain why** you think a different path is more appropriate
+2. **Ask the user explicitly** whether they want to switch or continue with app-planner
+3. **Only switch if the user confirms** — otherwise proceed with app-planner as invoked
+
+The user chose this skill intentionally. Respect that choice.
+
 ## Scope Boundary (Hard Rule)
 
 **This skill is PLANNING ONLY.** You must NEVER:
@@ -39,10 +53,7 @@ Trigger this skill for requests like:
 - "Prepare feature-list.json", "Prepare dev-pipeline input"
 - "Reprioritize features", "Split features"
 
-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
+Do NOT use this skill when the user only wants to run the pipeline (`dev-pipeline-launcher`), is debugging/refactoring, or wants to write source code directly.
 
 ## Resource Loading Rules (Mandatory)
 
@@ -55,13 +66,18 @@ Do NOT use this skill when:
 2. **Use shared quality examples as needed**:
    - read `assets/planning-guide.md` for decomposition and acceptance criteria patterns
 
-3. **Always validate output via script**:
+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`
+
+4. **Always validate output via script**:
    - run:
      ```bash
      python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input <output-path> --mode <new|incremental>
      ```
 
-4. **Use script output as source of truth**:
+5. **Use script output as source of truth**:
    - if validation fails, fix and re-run until pass
 
 ## Prerequisites
@@ -157,56 +173,11 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | **CP-AP-4** | `feature-list.json` Generated | Schema validates, all required keys present | 6-7 |
 | **CP-AP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 8 |
 
-**Resume Detection**: See §Resume Support for checkpoint-based resumption.
+**Resume Detection**: If existing artifacts are found, read `references/error-recovery.md` §Resume Support for checkpoint-based resumption.
 
 ## 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.
+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.
 
 ## Fast Path — Incremental Shortcuts
 
@@ -222,11 +193,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis to accelerate
 
 ### Fast Path Workflow
 1. Read existing `feature-list.json` and confirm scope
-2. Generate next sequential feature IDs
-3. Draft features (title + description + acceptance_criteria + dependencies)
-4. Run validation script immediately
-5. If valid → summarize and recommend next step
-6. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+2. **User confirmation (mandatory)** — Tell the user: "This qualifies for fast-path (simple incremental addition). Skip detailed Phase 2-3 analysis and draft directly? Or use full workflow?" Only proceed with fast path if user confirms.
+3. Generate next sequential feature IDs
+4. Draft features (title + description + acceptance_criteria + dependencies)
+5. Run validation script immediately
+6. If valid → summarize and recommend next step
+7. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
 
 ### When NOT to Use Fast Path
 - New app planning (always use full workflow)
@@ -238,59 +210,25 @@ For simple incremental planning, skip detailed Phase 2-3 analysis to accelerate
 ### Example Fast Path Session
 ```
 User: "Add email verification to existing user module."
-AI: [Detects incremental mode] 
+AI: [Detects incremental mode]
 AI: [Checks existing plan: found 8 features, user module exists]
 AI: [Qualifies for fast path: 1 feature, low complexity, ≤2 deps]
-AI: "Fast path available. Drafting F-009..."
+AI: "This qualifies for fast-path. Skip detailed analysis and draft directly? Or use full workflow?"
+User: "Fast path is fine."
+AI: "Drafting F-009..."
 AI: [Validates immediately]
 AI: "Ready to proceed to dev-pipeline."
 ```
 
 ## 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.
-
-### When to Suggest
+For features with user-visible UI (pages, forms, modals), optionally add `browser_interaction` for automated playwright-cli verification in the pipeline.
 
-Suggest `browser_interaction` when ALL of these apply:
-- The app has a web frontend (detected from tech stack or `global_context`)
-- The feature produces user-visible UI (pages, forms, modals, navigation flows)
-- The acceptance criteria reference visual/interactive behavior (e.g., "user sees...", "clicking X shows Y")
+**Suggest when**: web frontend + user-visible UI + acceptance criteria reference visual/interactive behavior.
+**Do NOT suggest for**: backend-only, config/setup, or non-UI features.
 
-Do NOT suggest for:
-- Backend-only features (APIs, database, services)
-- Config/setup/scaffolding features
-- Features where UI is not the primary deliverable
-
-### 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
-  }
-}
-```
-
-**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
+During Phase 4, ask qualifying features: "Want to add browser verification? (Y/n)"
+If yes → read `references/browser-interaction.md` for the `browser_interaction` object format and field rules.
 
 ## Output Rules
 
@@ -325,166 +263,15 @@ Recommend these three options in this strict order:
 
 When launcher is available, do not prioritize raw scripts.
 
-## Error Recovery
-
-Structured error handling for interrupted sessions and validation failures.
-
-### 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"
-```
-
-### Interrupted Planning Resume
-
-| Scenario | Detection | Action |
-|----------|-----------|--------|
-| Partial `feature-list.json` exists | File found in working dir | Read file, show summary, ask: "Resume from checkpoint or restart?" |
-| Checkpoint CP-AP-4 passed | File generates valid schema | Offer: "Jump to Phase 7 (final validation)" |
-| Checkpoint CP-AP-5 passed | Full validation passes | Offer: "Feature plan complete, proceed to dev-pipeline" |
-| 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 |
-
-### 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
-
-## Incremental Feature Planning — Style Matching
-
-When appending features to an existing plan, preserve style and detail level automatically.
-
-### Style Detection (Automatic)
-
-Before drafting new features, analyze existing plan:
-
-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 Phase 6 (JSON generation).
-
-## 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-4 (file generated) | Phase 7: Final validation | Offer to validate or extend |
-| `feature-list.json` + validation passed | CP-AP-5 (validation pass) | Handoff: dev-pipeline | Offer: execute pipeline now |
-| Partial state (incomplete file) | CP-AP-2 or CP-AP-3 | Next phase after last checkpoint | Resume interactive planning |
-
-### 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)"
-```
-
-### 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-5
-      └── <ISO-timestamp>.backup.json    # Optional incremental backups
-```
+## Error Recovery & Resume
 
-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.
+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.
 
-Maintainer note: evaluation workflow moved to `assets/evaluation-guide.md`.
+Key behaviors:
+- Warnings only → proceed with user approval
+- Critical errors → group by type, auto-fix where possible, max 3 total attempts
+- Interrupted session → detect checkpoint from existing artifacts, offer resume or restart
+- `feature-list.json` MUST be written to project root (same level as `package.json` / `.git`)
 
 ## Session Exit Gate
 

package/bundled/skills/dev-pipeline-launcher/SKILL.md

@@ -324,39 +324,16 @@ After pipeline completion, if features have `browser_interaction` fields and `pl
 
 2. **Ask user**: "N features have browser verification configured. Run playwright-cli verification now? (Y/n)"
 
-3. **If yes**, first learn the available commands:
-   ```bash
-   playwright-cli --help
-   ```
-   Then read `dev-pipeline/assets/playwright-cli-reference.md` for snapshot format and workflow patterns. For each qualifying feature:
-   ```bash
-   # Start dev server if setup_command is specified
-   # (run in background, wait for port to be ready)
-
-   # Open browser and navigate
-   playwright-cli open <url>
-
-   # Take initial snapshot
-   playwright-cli snapshot
-
-   # Execute verify_steps (if specified) — these are descriptive;
-   # map them to actual refs from the snapshot
-   # e.g., "click login button" → find button ref in snapshot → playwright-cli click <ref>
-
-   # Take final screenshot
-   playwright-cli screenshot
-
-   # Close browser
-   playwright-cli close
-   ```
+3. **If yes**, for each qualifying feature:
+   - Start dev server if `setup_command` is specified
+   - Use `playwright-cli` to open the URL, execute `verify_steps`, and take a screenshot
+   - Close browser and stop dev server
 
 4. **Report results**:
    - For each feature: URL opened, steps executed, screenshot path
-   - If any step fails (element not found, page error): flag as verification failure
+   - If any step fails: flag as verification failure
    - Screenshots are saved to `.playwright-cli/` for user review
 
-5. **Cleanup**: Stop any dev servers started by `setup_command`
-
 **Important**: Browser verification is best-effort — failures here do NOT change the feature's pipeline status. They serve as visual confirmation aids for the user.
 
 ---
@@ -373,7 +350,7 @@ After pipeline completion, if features have `browser_interaction` fields and `pl
 | Launch failed (process died immediately) | Show last 20 lines of log: `tail -20 dev-pipeline/state/pipeline-daemon.log` |
 | Feature stuck/blocked | Use `retry-feature.sh <F-XXX>` to retry; use `reset-feature.sh <F-XXX> --clean --run` for fresh start |
 | All features blocked/failed | Show status, suggest daemon-safe recovery: `dev-pipeline/reset-feature.sh <F-XXX> --clean --run feature-list.json` |
-| `playwright-cli` not installed | Browser verification skipped (non-blocking). Suggest: `npm install -g @playwright/cli@latest` |
+| `playwright-cli` not installed | Browser verification skipped (non-blocking). Suggest: `npm install -g @playwright/cli@latest && playwright-cli install --skills` |
 | Permission denied on script | Run `chmod +x dev-pipeline/launch-daemon.sh dev-pipeline/run.sh` |
 
 ### Integration Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prizmkit",
-  "version": "1.0.131",
+  "version": "1.0.133",
   "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

@@ -697,7 +697,7 @@ export async function installGitignore(projectRoot, options, dryRun) {
 // ============================================================
 
 /**
- * 安装 playwright-cli（全局 npm 包 + workspace 初始化）
+ * 安装 playwright-cli（全局 npm 包 + AI agent skills）
  * 用于浏览器交互验证（browser_interaction 功能）
  */
 export async function installPlaywrightCli(projectRoot, dryRun) {
@@ -723,12 +723,13 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
     }
   }
 
-  // Initialize workspace
+  // Install AI agent skills (official SKILL.md + references, auto-detects system browser)
   try {
-    execSync('playwright-cli install', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
-    console.log(chalk.green('      ✓ playwright-cli workspace initialized'));
+    execSync('playwright-cli install --skills', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
+    console.log(chalk.green('      ✓ playwright-cli skills installed'));
   } catch (e) {
-    console.log(chalk.yellow(`      ⚠ playwright-cli workspace init skipped: ${e.message}`));
+    console.log(chalk.yellow(`      ⚠ Skills install skipped: ${e.message}`));
+    console.log(chalk.yellow('      ⚠ Run manually: playwright-cli install --skills'));
   }
 }
 

package/bundled/dev-pipeline/assets/playwright-cli-reference.md

@@ -1,113 +0,0 @@
-# playwright-cli Quick Reference (for AI Agents)
-
-Token-efficient browser automation tool. State is saved to `.playwright-cli/` on disk — only file paths are returned, not page content.
-
-## Core Workflow
-
-```
-playwright-cli open <url>        # open browser + navigate (returns snapshot path)
-playwright-cli snapshot          # capture page state → .yml file with element refs (e.g. ref=e15)
-playwright-cli click <ref>       # click element by ref from snapshot
-playwright-cli fill <ref> <text> # fill text into input/textarea by ref
-playwright-cli type <text>       # type text into active element
-playwright-cli press <key>       # press key: Enter, Tab, Escape, ArrowDown, etc.
-playwright-cli screenshot        # capture viewport → .png file
-playwright-cli close             # close browser
-```
-
-## Reading Snapshots
-
-After `open` or `snapshot`, read the `.yml` file. Each element has a `ref=eXX`:
-
-```yaml
-- navigation "Main" [ref=e4]:
-    - link "Docs" [ref=e11] [cursor=pointer]:
-        - /url: /docs/intro
-    - button "Login" [ref=e14] [cursor=pointer]
-    - searchbox "Search" [ref=e20]
-```
-
-Use refs in subsequent commands: `playwright-cli click e14`, `playwright-cli fill e20 "query"`.
-
-**Important**: Refs change after navigation — always `snapshot` after clicking a link.
-
-## Additional Commands
-
-```
-# Navigation
-goto <url>                  # navigate without reopening browser
-go-back / go-forward        # browser history
-reload                      # reload page
-
-# Form interaction
-select <ref> <value>        # select dropdown option
-check <ref> / uncheck <ref> # checkbox/radio
-upload <file>               # file upload
-dblclick <ref>              # double click
-hover <ref>                 # hover over element
-drag <startRef> <endRef>    # drag and drop
-
-# Tabs
-tab-list                    # list all open tabs
-tab-new [url]               # open new tab
-tab-select <index>          # switch to tab by index
-tab-close [index]           # close tab
-
-# JavaScript
-eval <expression>           # evaluate JS on page (e.g. eval "document.title")
-eval <expression> <ref>     # evaluate JS on specific element
-
-# Session management
-list                        # list browser sessions
-close-all                   # close all browsers
--s=<name> <command>         # target specific session (for multiple browsers)
-
-# DevTools
-console                     # list console messages
-network                     # list network requests
-screenshot [ref]            # screenshot specific element (not just viewport)
-
-# Storage / Auth
-state-save [file]           # save cookies + localStorage (for auth reuse)
-state-load <file>           # restore saved state
-```
-
-## Typical Verification Flow
-
-```bash
-# 1. Start dev server (if needed)
-npm run dev &
-sleep 5
-
-# 2. Open and get initial snapshot
-playwright-cli open http://localhost:3000
-# → reads .playwright-cli/page-*.yml for element refs
-
-# 3. Interact — map acceptance criteria to actions
-playwright-cli snapshot
-# read the .yml, find the target element ref
-playwright-cli click e14          # e.g. click "Login" button
-playwright-cli fill e20 "admin"   # e.g. fill username
-playwright-cli fill e22 "pass"    # e.g. fill password
-playwright-cli click e25          # e.g. click "Submit"
-
-# 4. Verify result
-playwright-cli snapshot
-# read the new .yml — check if expected elements exist
-# e.g. look for "Welcome" heading, dashboard nav, etc.
-
-# 5. Screenshot for human review
-playwright-cli screenshot
-
-# 6. Cleanup
-playwright-cli close
-```
-
-## Tips for AI Agents
-
-- **Always snapshot before interacting** — you need refs, and they change after navigation
-- **Read the .yml file** to find the right ref — don't guess ref numbers
-- **One command at a time** — each command returns immediately, check result before next
-- **Failures are non-blocking** — if an element isn't found, log it and continue
-- **Screenshots are evidence** — take one after each major verification step
-- `.playwright-cli/` artifacts are gitignored — they're ephemeral