prizmkit 1.0.127 → 1.0.129

package/bin/create-prizmkit.js

@@ -36,7 +36,7 @@ program
   .option('--no-pipeline', 'Disable dev-pipeline')
   .option('--rules <preset>', 'Rules preset: recommended, minimal, or none', 'recommended')
   .option('--ai-cli <command>', 'AI CLI executable command (e.g. cbc, claude, claude-internal)')
-  .option('--external-skills <names>', 'Comma-separated external skill names to install (e.g. find-skill,uiuxpromax)')
+  .option('--external-skills <names>', 'Comma-separated external skill names to install (e.g. find-skills,impeccable)')
   .option('--non-interactive', 'Skip interactive prompts (requires --platform)')
   .option('--dry-run', 'Show what would be created without making changes')
   .action(async (directory = '.', options) => {

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.127",
-  "bundledAt": "2026-03-28T02:54:00.694Z",
-  "bundledFrom": "23e9a2d"
+  "frameworkVersion": "1.0.129",
+  "bundledAt": "2026-03-28T07:10:32.799Z",
+  "bundledFrom": "f90a704"
 }

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

@@ -0,0 +1,113 @@
+# 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

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

@@ -88,6 +88,27 @@ except: pass
     export PRIZMKIT_PLATFORM="$PLATFORM"
 }
 
+# prizm_detect_subagents <session_log>
+#
+# Scan session log for subagent spawns and log the result.
+# Uses grep -q for early exit on first match.
+# Requires: USE_STREAM_JSON (from detect_stream_json_support)
+prizm_detect_subagents() {
+    local session_log="$1"
+    [[ -f "$session_log" ]] || return 0
+
+    local has_subagent=false
+    if [[ "$USE_STREAM_JSON" == "true" ]]; then
+        grep -q '"name"[[:space:]]*:[[:space:]]*"Agent"' "$session_log" 2>/dev/null && has_subagent=true
+    else
+        grep -qE '(Tool: Agent|"tool":\s*"Agent"|tool_use.*Agent|subagent_type)' "$session_log" 2>/dev/null && has_subagent=true
+    fi
+
+    if [[ "$has_subagent" == true ]]; then
+        log_info "Subagent calls detected in session"
+    fi
+}
+
 # Common dependency check (jq + python3 + optional CLI in PATH)
 # Args:
 #   $1 - cli command (optional)

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

@@ -215,7 +215,7 @@ spawn_and_wait_session() {
             if [[ -n "$dirty_files" ]]; then
                 log_info "Auto-committing remaining session artifacts..."
                 git -C "$project_root" add -A 2>/dev/null || true
-                git -C "$project_root" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                git -C "$project_root" commit --no-verify --amend --no-edit 2>/dev/null \
                     || git -C "$project_root" commit --no-verify -m "chore($bug_id): include remaining session artifacts" 2>/dev/null \
                     || true
             fi
@@ -224,6 +224,9 @@ spawn_and_wait_session() {
 
     log_info "Session result: $session_status"
 
+    # Subagent detection
+    prizm_detect_subagents "$session_log"
+
     # Update bug status
     python3 "$SCRIPTS_DIR/update-bug-status.py" \
         --bug-list "$bug_list" \

package/bundled/dev-pipeline/run.sh

@@ -216,7 +216,7 @@ spawn_and_wait_session() {
             uncommitted=$(git -C "$project_root" status --porcelain 2>/dev/null | head -1 || true)
             if [[ -n "$uncommitted" ]]; then
                 log_warn "Session exited cleanly but produced no commits (uncommitted changes found) — auto-committing..."
-                git -C "$project_root" add -u 2>/dev/null || true
+                git -C "$project_root" add -A 2>/dev/null || true
                 if git -C "$project_root" commit --no-verify -m "chore($feature_id): auto-commit session work" 2>/dev/null; then
                     log_info "Auto-commit succeeded"
                     session_status="success"
@@ -239,8 +239,8 @@ spawn_and_wait_session() {
             dirty_files=$(git -C "$project_root" status --porcelain 2>/dev/null || true)
             if [[ -n "$dirty_files" ]]; then
                 log_info "Auto-committing remaining session artifacts..."
-                git -C "$project_root" add -u 2>/dev/null || true
-                git -C "$project_root" commit --no-verify --amend --no-edit -a 2>/dev/null \
+                git -C "$project_root" add -A 2>/dev/null || true
+                git -C "$project_root" commit --no-verify --amend --no-edit 2>/dev/null \
                     || git -C "$project_root" commit --no-verify -m "chore($feature_id): include remaining session artifacts" 2>/dev/null \
                     || true
             fi
@@ -249,6 +249,9 @@ spawn_and_wait_session() {
 
     log_info "Session result: $session_status"
 
+    # Subagent detection
+    prizm_detect_subagents "$session_log"
+
     # Write lightweight session summary for post-session inspection
     local feature_slug
     feature_slug=$(python3 -c "

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

@@ -285,11 +285,13 @@ def process_conditional_blocks(content, resume_phase):
     return content
 
 
-def process_mode_blocks(content, pipeline_mode, init_done, critic_enabled=False):
-    """Process pipeline mode, init, and critic conditional blocks.
+def process_mode_blocks(content, pipeline_mode, init_done, critic_enabled=False,
+                        browser_interaction=False):
+    """Process pipeline mode, init, critic, and browser conditional blocks.
 
     Keeps the block matching the current mode, removes the others.
     Handles {{IF_CRITIC_ENABLED}} / {{END_IF_CRITIC_ENABLED}} blocks.
+    Handles {{IF_BROWSER_INTERACTION}} / {{END_IF_BROWSER_INTERACTION}} blocks.
     """
     # Handle lite/standard/full blocks
     modes = ["lite", "standard", "full"]
@@ -339,6 +341,18 @@ def process_mode_blocks(content, pipeline_mode, init_done, critic_enabled=False)
         pattern = re.escape(critic_open) + r".*?" + re.escape(critic_close) + r"\n?"
         content = re.sub(pattern, "", content, flags=re.DOTALL)
 
+    # Browser interaction blocks
+    browser_open = "{{IF_BROWSER_INTERACTION}}"
+    browser_close = "{{END_IF_BROWSER_INTERACTION}}"
+    if browser_interaction:
+        content = content.replace(browser_open + "\n", "")
+        content = content.replace(browser_open, "")
+        content = content.replace(browser_close + "\n", "")
+        content = content.replace(browser_close, "")
+    else:
+        pattern = re.escape(browser_open) + r".*?" + re.escape(browser_close) + r"\n?"
+        content = re.sub(pattern, "", content, flags=re.DOTALL)
+
     return content
 
 
@@ -517,6 +531,31 @@ def build_replacements(args, feature, features, global_context, script_dir):
         )
         critic_enabled = False
 
+    # Browser interaction - extract from feature if present and playwright-cli available
+    browser_interaction = feature.get("browser_interaction")
+    browser_enabled = False
+    browser_url = ""
+    browser_setup_command = ""
+    browser_verify_steps = ""
+
+    browser_verify_env = os.environ.get("BROWSER_VERIFY", "").lower()
+    if browser_verify_env == "false":
+        browser_interaction = None
+
+    if browser_interaction and isinstance(browser_interaction, dict):
+        browser_url = browser_interaction.get("url", "")
+        if browser_url:
+            browser_enabled = True
+            browser_setup_command = browser_interaction.get("setup_command", "# no setup needed")
+            steps = browser_interaction.get("verify_steps", [])
+            if steps:
+                browser_verify_steps = "\n".join(
+                    "   # Step {}: {}".format(i + 1, step)
+                    for i, step in enumerate(steps)
+                )
+            else:
+                browser_verify_steps = "   # (no specific verify steps — just open and screenshot)"
+
     replacements = {
         "{{RUN_ID}}": args.run_id,
         "{{SESSION_ID}}": args.session_id,
@@ -552,21 +591,25 @@ def build_replacements(args, feature, features, global_context, script_dir):
         "{{HAS_SPEC}}": "true" if artifacts["has_spec"] else "false",
         "{{HAS_PLAN}}": "true" if artifacts["has_plan"] else "false",
         "{{ARTIFACTS_COMPLETE}}": "true" if artifacts["all_complete"] else "false",
+        "{{BROWSER_URL}}": browser_url,
+        "{{BROWSER_SETUP_COMMAND}}": browser_setup_command,
+        "{{BROWSER_VERIFY_STEPS}}": browser_verify_steps,
     }
 
-    return replacements, effective_resume
+    return replacements, effective_resume, browser_enabled
 
 
-def render_template(template_content, replacements, resume_phase):
+def render_template(template_content, replacements, resume_phase, browser_enabled=False):
     """Render the template by processing conditionals and replacing placeholders."""
     # Step 1: Process fresh_start/resume conditional blocks
     content = process_conditional_blocks(template_content, resume_phase)
 
-    # Step 2: Process mode, init, and critic conditional blocks
+    # Step 2: Process mode, init, critic, and browser conditional blocks
     pipeline_mode = replacements.get("{{PIPELINE_MODE}}", "standard")
     init_done = replacements.get("{{INIT_DONE}}", "false") == "true"
     critic_enabled = replacements.get("{{CRITIC_ENABLED}}", "false") == "true"
-    content = process_mode_blocks(content, pipeline_mode, init_done, critic_enabled)
+    content = process_mode_blocks(content, pipeline_mode, init_done, critic_enabled,
+                                  browser_enabled)
 
     # Step 3: Replace all {{PLACEHOLDER}} variables
     for placeholder, value in replacements.items():
@@ -661,7 +704,7 @@ def main():
         global_context = {}
 
     # Build replacements
-    replacements, effective_resume = build_replacements(
+    replacements, effective_resume, browser_enabled = build_replacements(
         args, feature, features, global_context, script_dir
     )
 
@@ -670,7 +713,7 @@ def main():
 
     # Render the template
     rendered = render_template(
-        template_content, replacements, effective_resume
+        template_content, replacements, effective_resume, browser_enabled
     )
 
     # Write the output

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

@@ -161,6 +161,63 @@ Files changed/created: [list]
 Key decisions: [list]
 ```
 
+{{IF_BROWSER_INTERACTION}}
+### Phase 3.5: Browser Verification (playwright-cli)
+
+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.
+   {{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`:
+   ```
+   ## Browser Verification
+   URL: {{BROWSER_URL}}
+   Steps executed: [list]
+   Screenshot: [path]
+   Result: PASS / FAIL (reason)
+   ```
+
+If any step fails, log the failure and continue to Phase 4. Do NOT retry browser verification.
+{{END_IF_BROWSER_INTERACTION}}
+
 ### Phase 4: Architecture Sync & Commit (SINGLE COMMIT)
 
 **4a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):

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

@@ -275,6 +275,63 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 **CP-3**: Tests pass, verdict is not NEEDS_FIXES.
 
+{{IF_BROWSER_INTERACTION}}
+### Phase 5.5: Browser Verification (playwright-cli)
+
+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.
+   {{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`:
+   ```
+   ## Browser Verification
+   URL: {{BROWSER_URL}}
+   Steps executed: [list]
+   Screenshot: [path]
+   Result: PASS / FAIL (reason)
+   ```
+
+If any step fails, log the failure and continue to Phase 6. Do NOT retry browser verification.
+{{END_IF_BROWSER_INTERACTION}}
+
 ### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)
 
 **6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):

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

@@ -375,6 +375,63 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '#
 
 **CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
 
+{{IF_BROWSER_INTERACTION}}
+### Phase 5.5: Browser Verification (playwright-cli)
+
+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.
+   {{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`:
+   ```
+   ## Browser Verification
+   URL: {{BROWSER_URL}}
+   Steps executed: [list]
+   Screenshot: [path]
+   Result: PASS / FAIL (reason)
+   ```
+
+If any step fails, log the failure and continue to Phase 6. Do NOT retry browser verification.
+{{END_IF_BROWSER_INTERACTION}}
+
 
 ### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
 

package/bundled/dev-pipeline/templates/feature-list-schema.json

@@ -111,6 +111,33 @@
             "type": "integer",
             "description": "Number of parallel critic agents. 1 = single critic, 3 = multi-critic voting. Default: 1.",
             "enum": [1, 3]
+          },
+          "browser_interaction": {
+            "type": "object",
+            "description": "Browser verification config for features with UI. Requires playwright-cli. Pipeline uses this to verify UI behavior after implementation.",
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "URL to open for verification (e.g. http://localhost:3000/login)"
+              },
+              "setup_command": {
+                "type": "string",
+                "description": "Command to start the dev server before verification (e.g. npm run dev)"
+              },
+              "verify_steps": {
+                "type": "array",
+                "description": "Ordered playwright-cli commands to execute for verification",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "screenshot": {
+                "type": "boolean",
+                "description": "Capture screenshot after verification steps. Default: true.",
+                "default": true
+              }
+            },
+            "required": ["url"]
           }
         }
       }

package/bundled/skills/_metadata.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.126",
+  "version": "1.0.129",
   "skills": {
     "prizm-kit": {
       "description": "Full-lifecycle dev toolkit. Covers spec-driven development, Prizm context docs, code quality, debugging, deployment, and knowledge management.",
@@ -328,12 +328,15 @@
         ]
       },
       {
-        "name": "ui-ux-pro-max",
-        "description": "UI/UX design review and suggestions",
-        "repo": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill",
+        "name": "impeccable",
+        "description": "Production-grade UI/UX design skills (21 skills: frontend-design, adapt, animate, polish, etc.)",
+        "repo": "pbakaus/impeccable",
+        "installAll": true,
         "tags": [
           "design",
-          "frontend"
+          "frontend",
+          "ui",
+          "ux"
         ]
       }
     ]

package/bundled/skills/app-planner/SKILL.md

@@ -132,9 +132,11 @@ Execute the selected scenario workflow in conversation mode with mandatory check
 ### Interactive Phases
 1. clarify business goal and scope
    1.1 confirm deliverable intent (→ Intent Confirmation)
+   1.2 **requirement clarification** — apply `/prizmkit-clarify` principles: for ANY unclear aspect of the user's vision, goals, target users, or scope, ask questions one at a time until you fully understand. No limit on rounds or number of questions. Do not proceed to Phase 2 with unresolved ambiguities.
 2. confirm constraints and tech assumptions
 3. propose feature set with dependencies
 4. refine descriptions and acceptance criteria
+   4.1 **per-feature clarification** — for each feature, if the description, acceptance criteria, or scope is vague or could be interpreted multiple ways, ask the user to clarify before finalizing. Continue until every feature has unambiguous, implementation-ready details.
 5. verify DAG/order/priorities
 6. build or append `feature-list.json`
 7. ask whether to enable adversarial critic review for high/critical features
@@ -244,6 +246,52 @@ 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
+
+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")
+
+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
+
 ## Output Rules
 
 `feature-list.json` must satisfy:
@@ -256,6 +304,7 @@ AI: "Ready to proceed to dev-pipeline."
 - `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
 - `critic` field is optional (boolean). If user requested adversarial critic review during planning, set `"critic": true` for relevant features. Omitting defaults to `false`.
 - `critic_count` field is optional (integer, 1 or 3). If omitted, defaults to 1 (single critic). Set to 3 for multi-critic voting mode on critical features.
+- `browser_interaction` field is optional (object). If user opted for browser verification during planning, set for features with UI behavior. Requires `playwright-cli` to be installed.
 - **descriptions must be implementation-ready** — minimum 15 words (error), recommended 30/50/80 words for low/medium/high complexity (warning). See `planning-guide.md` §4 for what to include.
 
 ## Next-Step Execution Policy (after planning)

package/bundled/skills/bug-planner/SKILL.md

@@ -44,6 +44,7 @@ Launch the interactive bug planning process through 4 phases.
 1. **Identify project**: Read project name and description from existing `feature-list.json` or ask user
 2. **Identify tech stack**: Read from `.prizmkit/config.json` `tech_stack` (preferred), then `feature-list.json` global_context, then `.prizm-docs/root.prizm`. Only ask user if none of these sources provide tech stack info.
 3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
+4. **Clarify context** — apply `/prizmkit-clarify` principles: if the project context, affected systems, or bug scope is unclear, ask questions one at a time until you fully understand the environment. No limit on rounds or number of questions.
 
 Output: `project_name`, `project_description`, `global_context` fields populated.
 
@@ -116,6 +117,8 @@ ALERT: Error rate spike: 500 errors/min on /api/login endpoint
 - Verification type (suggest `automated` by default, ask user)
 - Acceptance criteria (auto-suggest based on description, user can edit)
 
+**Per-bug clarification** — apply `/prizmkit-clarify` principles: if the bug's root cause, reproduction steps, expected behavior, or scope is unclear from the provided information, ask focused questions until the bug is fully understood. Do not finalize a bug entry with ambiguous details. No limit on the number of questions per bug.
+
 **Multiple bugs per session**: After each bug, ask "Any more bugs to add? (yes/no)"
 
 ### Phase 3: Prioritization & Review