prizmkit 1.0.128 → 1.0.130

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.128",
-  "bundledAt": "2026-03-28T06:01:48.243Z",
-  "bundledFrom": "ece8a06"
+  "frameworkVersion": "1.0.130",
+  "bundledAt": "2026-03-28T07:12:12.286Z",
+  "bundledFrom": "1fdcacb"
 }

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/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.128",
+  "version": "1.0.130",
   "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

@@ -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

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

@@ -57,10 +57,13 @@ Before any action, validate:
 2. **For start**: `feature-list.json` must exist in project root (or user-specified path)
 3. **Dependencies**: `jq`, `python3`, AI CLI (`cbc` or `claude`) must be in PATH
 4. **Python version**: Requires Python 3.8+ for dev-pipeline scripts
+5. **playwright-cli** (optional): If any feature has `browser_interaction` field, check `playwright-cli` is available
 
 Quick check:
 ```bash
 command -v jq && command -v python3 && (command -v cbc || command -v claude) && echo "All dependencies OK"
+# Optional: browser interaction support
+command -v playwright-cli && echo "playwright-cli OK" || echo "playwright-cli not found (browser verification will be skipped)"
 ```
 
 If `feature-list.json` is missing, inform user:
@@ -117,6 +120,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    | **Max retries** | 3 | Max retry attempts per failed feature |
    | **Session timeout** | None | Per-feature timeout in seconds (e.g. `3600` = 1 hour) |
    | **Feature filter** | All | Run specific features: `F-001:F-005` (range), `F-001,F-003` (list), or mixed `F-001,F-005:F-010` |
+   | **Browser verify** | Auto | Run playwright-cli verification for features with `browser_interaction`. Auto = run if playwright-cli installed and features have the field |
 
    Default to Foreground + Verbose On if user doesn't specify. Default Critic to Off unless features have `estimated_complexity: "high"` or above.
 
@@ -129,6 +133,8 @@ Detect user intent from their message, then follow the corresponding workflow:
    | "no verbose" / "quiet" | `VERBOSE=0` |
    | "heartbeat every 60s" | `HEARTBEAT_INTERVAL=60` |
    | "enable critic review" | `ENABLE_CRITIC=true` |
+   | "skip browser verify" | `BROWSER_VERIFY=false` |
+   | "enable browser verify" | `BROWSER_VERIFY=true` |
 
    Example presentation to user:
    ```
@@ -187,6 +193,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    - Summarize results: total features, succeeded, failed, skipped
    - If all succeeded: each feature session has already run `prizmkit-retrospective` internally. Ask user what's next.
    - If some failed: show failed feature IDs and suggest `retry-feature.sh <F-XXX>` or `reset-feature.sh <F-XXX> --clean --run`
+   - **Browser verification**: If any completed features have `browser_interaction` and `playwright-cli` is installed, offer to run browser verification (see §Post-Pipeline Browser Verification)
 
    **If background daemon**:
    1. Verify launch:
@@ -296,6 +303,64 @@ Notes:
 - `reset-feature.sh --clean --run` clears the feature state before retrying (fresh start).
 - Keep pipeline daemon mode for main run management (`launch-daemon.sh`).
 
+---
+
+#### Post-Pipeline Browser Verification
+
+After pipeline completion, if features have `browser_interaction` fields and `playwright-cli` is installed:
+
+1. **Check which features qualify**:
+   ```bash
+   python3 -c "
+   import json
+   with open('feature-list.json') as f:
+       data = json.load(f)
+   for feat in data.get('features', []):
+       bi = feat.get('browser_interaction')
+       if bi and feat.get('status') == 'completed':
+           print(f\"  {feat['id']}: {feat.get('title','')} → {bi['url']}\")
+   " 2>/dev/null
+   ```
+
+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
+   ```
+
+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
+   - 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.
+
+---
+
 ### Error Handling
 
 | Error | Action |
@@ -308,6 +373,7 @@ Notes:
 | 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` |
 | Permission denied on script | Run `chmod +x dev-pipeline/launch-daemon.sh dev-pipeline/run.sh` |
 
 ### Integration Notes

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

@@ -1,16 +1,17 @@
 ---
 name: "prizmkit-clarify"
-description: "Interactive requirement clarification. Resolves ambiguities in feature specs by asking sequential questions with recommended answers. Use when spec has unclear parts or you're unsure about requirements before planning. Use this skill whenever a spec has [NEEDS CLARIFICATION] markers, vague requirements, or the user wants to refine their feature definition before planning. Trigger on: 'clarify', 'refine spec', 'resolve ambiguities', 'spec has questions', 'unsure about requirements', 'spec is unclear'. (project)"
+description: "Interactive requirement clarification. Resolves ALL ambiguities in feature specs through unlimited rounds of questions until full understanding is reached. Use when spec has unclear parts, you're unsure about requirements, or before planning to ensure nothing is ambiguous. Trigger on: 'clarify', 'refine spec', 'resolve ambiguities', 'spec has questions', 'unsure about requirements', 'spec is unclear'. (project)"
 ---
 
 # PrizmKit Clarify
 
-Interactive requirement clarification that resolves ambiguities in feature specifications. Asks focused questions one at a time, updating the spec atomically after each answer.
+Exhaustive interactive requirement clarification. Resolves **every** ambiguity in a feature specification by asking questions one at a time — no limit on rounds or number of questions. The goal is **complete understanding**: do not stop until every unclear aspect is resolved and you are fully confident about the requirements.
 
 ### When to Use
 - After `/prizmkit-specify` when spec has `[NEEDS CLARIFICATION]` markers
 - User says "clarify", "resolve ambiguities", "refine spec"
 - Before `/prizmkit-plan` to ensure spec is unambiguous
+- Whenever you encounter any uncertainty about what the user wants — proactively ask rather than assume
 
 **PRECONDITION:**
 
@@ -21,21 +22,38 @@ Interactive requirement clarification that resolves ambiguities in feature speci
 ## Execution Steps
 
 1. Read `spec.md` from `.prizmkit/specs/###-feature-name/`
-2. Scan for `[NEEDS CLARIFICATION]` markers and underspecified areas
+2. Scan for ALL ambiguities — not just `[NEEDS CLARIFICATION]` markers but also:
+   - Vague terms without measurable criteria (e.g., "fast", "user-friendly", "secure")
+   - Missing edge cases that would affect implementation
+   - Implicit assumptions not stated explicitly
+   - Scope boundaries that could be interpreted multiple ways
+   - Data model gaps (entities, relationships, constraints undefined)
 3. Categorize ambiguities by dimension and prioritize — address the ones that would most affect architecture and data model first, since those are hardest to change later:
    - Data model (what entities, relationships, constraints?) — **highest priority when DB changes are involved**: field types, nullability, naming conventions, relationships, and constraint patterns must all be resolved before plan finalization. Unresolved DB design decisions during implementation lead to expensive rework.
    - Functional scope (what does it do?)
-   - Data model (what entities, relationships?)
    - UX flow (what does the user see?)
    - Error handling (what happens when things fail?)
    - Non-functional requirements (performance, security)
    - Edge cases, integration points, accessibility
-4. Ask questions one at a time (max 5 per session) — batch questions overwhelm users and produce lower-quality answers because they rush through without thinking deeply about each one
+4. Ask questions **one at a time** — batch questions overwhelm users and produce lower-quality answers because they rush through without thinking deeply about each one
 5. For each question: provide a recommended answer with rationale. The recommendation gives users a concrete starting point to accept, modify, or reject — this is much faster than open-ended questions
 6. After each answer: immediately update `spec.md` (not batched at the end). Atomic updates mean the spec is always in a consistent state, even if the session is interrupted
-7. Support early termination: user says "done" or "stop" — end immediately
-8. Remove resolved `[NEEDS CLARIFICATION]` markers
-9. After all questions resolved or user terminates: output summary of changes made
+7. Remove resolved `[NEEDS CLARIFICATION]` markers as they are addressed
+8. **Continue asking** — after each answer, re-evaluate the spec for remaining ambiguities. Each user answer may reveal new questions. Keep going until:
+   - All `[NEEDS CLARIFICATION]` markers are removed, AND
+   - No vague or underspecified areas remain, AND
+   - You are fully confident about the requirements
+9. Support early termination: user says "done", "stop", or "enough" — end immediately and summarize what was resolved vs what remains unclear
+10. After all questions resolved or user terminates: output summary of all changes made
+
+## No Limits Policy
+
+**There is NO cap on the number of questions or rounds.** Ask as many questions as needed to achieve complete understanding. A half-understood spec leads to wrong implementations, which cost far more than thorough clarification upfront.
+
+- If you've asked 10 questions and there are still ambiguities — keep asking
+- If the user's answer raises new questions — ask those too
+- If you realize a previously-resolved item needs revisiting because of new context — go back and ask again
+- Only stop when you genuinely have no more uncertainties, or the user explicitly terminates
 
 ## Example Session
 
@@ -54,11 +72,19 @@ File upload: accepts JPEG, PNG, PDF, SVG. Max size: 25MB per file.
 ```
 Remove `[NEEDS CLARIFICATION]` marker from §3.2.
 
+**Question 2** (new question triggered by user's answer):
+> You mentioned SVG files. SVGs can contain embedded scripts which pose XSS risks. Should uploaded SVGs be sanitized (strip `<script>` tags and event handlers), or should SVG upload be restricted to trusted users only?
+>
+> **Recommended answer:** Sanitize all SVG uploads by stripping scripts and event handlers. This allows all users to upload SVGs safely.
+
+*(Continue until all ambiguities are resolved...)*
+
 ## Guidelines
 
 - Keep questions at the WHAT/WHY level — do not introduce implementation details (HOW). The spec describes the problem space; implementation choices belong in plan.md
-- 5-question limit per session keeps clarification focused. If more questions remain, tell the user and suggest running clarify again after they've had time to think
 - If the user's answer contradicts an existing requirement, point out the conflict and ask which one should change
+- Group related follow-up questions naturally — if a user's answer opens 3 related sub-questions, ask the most impactful one first, then proceed to the others
+- If the user seems fatigued, acknowledge it: "I have N more questions. Want to continue now or come back later?" — but never silently stop with unresolved ambiguities
 
 **HANDOFF:** `/prizmkit-plan`
 

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

@@ -38,7 +38,7 @@ Create structured feature specifications from natural language descriptions. Thi
    - Acceptance criteria (Given/When/Then)
    - Scope boundaries (In scope / Out of scope)
    - Dependencies and constraints
-   - `[NEEDS CLARIFICATION]` markers for ambiguous items (max 3)
+   - `[NEEDS CLARIFICATION]` markers for all ambiguous items
 7. **Database design detection**: If the feature involves data persistence (new entities, new fields, schema changes), add a `## Data Model` section to spec.md (see template):
    - Scan for existing database schema files to understand current conventions:
      ```bash
@@ -51,7 +51,7 @@ Create structured feature specifications from natural language descriptions. Thi
 8. Run internal quality validation loop (max 3 iterations):
    - Check: All user stories have acceptance criteria?
    - Check: Scope boundaries clearly defined?
-   - Check: No more than 3 `[NEEDS CLARIFICATION]` markers?
+   - Check: All `[NEEDS CLARIFICATION]` markers have recommended defaults?
    - Check: If Data Model section exists, are existing schema conventions documented?
 9. Output: `spec.md` path and summary
 
@@ -60,7 +60,7 @@ Create structured feature specifications from natural language descriptions. Thi
 - **Focus on WHAT and WHY, never HOW** — the spec describes the problem space; implementation choices belong in plan.md. Mixing in tech stack details couples the spec to a specific solution and makes it harder to explore alternatives during planning.
 - **Every user story needs acceptance criteria** in Given/When/Then format — without them, the implementer has no way to verify the feature works correctly, and the code reviewer has no baseline to check against.
 - **Scope boundaries must be explicit** — without "Out of scope" boundaries, implementers tend to gold-plate features with capabilities nobody asked for, wasting time and adding complexity.
-- **Max 3 `[NEEDS CLARIFICATION]` markers** — more than 3 means the feature idea isn't mature enough to spec. Suggest the user think through the concept further and return, or use `/prizmkit-clarify` to resolve them interactively.
+- **Mark all unclear areas with `[NEEDS CLARIFICATION]`** — do not limit the number of markers. Every genuine ambiguity should be surfaced. After spec generation, suggest running `/prizmkit-clarify` to resolve them all interactively.
 - **Feature numbers are zero-padded to 3 digits** (e.g., `001`, `012`) with a `-MMDD` timestamp suffix — ensures consistent sorting and prevents collisions when multiple sessions run concurrently.
 
 ## Handling Vague Inputs

package/package.json

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

package/src/gitignore-template.js

@@ -30,6 +30,12 @@ export function generateGitignore(options = {}) {
     );
   }
 
+  lines.push(
+    '# Playwright CLI 快照和截图',
+    '.playwright-cli/',
+    '',
+  );
+
   lines.push(
     '# ===========================',
     '# Common',

package/src/index.js

@@ -67,6 +67,7 @@ export async function runScaffold(directory, options) {
       skills: options.skills || 'full',
       team: options.team !== false,
       pipeline: options.pipeline !== false,
+      playwrightCli: options.playwrightCli !== false,
       rules: options.rules || 'recommended',
       aiCli: options.aiCli || '',
       externalSkills: options.externalSkills ? options.externalSkills.split(',').map(s => s.trim()).filter(Boolean) : [],
@@ -202,6 +203,12 @@ export async function runScaffold(directory, options) {
       default: true,
     });
 
+    // 4.5. Playwright CLI (browser interaction support)
+    const playwrightCli = await confirm({
+      message: '安装浏览器交互工具 (playwright-cli)? 支持 UI 自动验证',
+      default: true,
+    });
+
     // 5. Rules 预设
     const rulesPreset = await select({
       message: '安装 AI 行为规则 (rules):',
@@ -227,6 +234,7 @@ export async function runScaffold(directory, options) {
     console.log(`    技能:       ${chalk.cyan(suiteLabel)}`);
     console.log(`    团队模式:   ${team ? chalk.green('启用') : chalk.gray('禁用')}`);
     console.log(`    流水线:     ${pipeline ? chalk.green('启用') : chalk.gray('禁用')}`);
+    console.log(`    浏览器工具: ${playwrightCli ? chalk.green('启用') : chalk.gray('禁用')}`);
     console.log(`    规则:       ${chalk.cyan(rulesPreset)}`);
     if (aiCli) console.log(`    AI CLI:     ${chalk.cyan(aiCli)}`);
     if (selectedExternalSkills.length > 0) console.log(`    外部技能:   ${chalk.cyan(selectedExternalSkills.join(', '))}`);
@@ -249,6 +257,7 @@ export async function runScaffold(directory, options) {
       skills: skillSuite,
       team,
       pipeline,
+      playwrightCli,
       rules: rulesPreset,
       aiCli: aiCli || '',
       externalSkills: selectedExternalSkills,

package/src/scaffold.js

@@ -10,9 +10,10 @@
 import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'path';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { execSync } from 'child_process';
 import {
   loadMetadata,
   getSkillsDir,
@@ -691,6 +692,46 @@ export async function installGitignore(projectRoot, options, dryRun) {
   }
 }
 
+// ============================================================
+// Playwright CLI 安装
+// ============================================================
+
+/**
+ * 安装 playwright-cli（全局 npm 包 + workspace 初始化）
+ * 用于浏览器交互验证（browser_interaction 功能）
+ */
+export async function installPlaywrightCli(projectRoot, dryRun) {
+  if (dryRun) {
+    console.log(chalk.gray('      [dry-run] @playwright/cli (global install + workspace init)'));
+    return;
+  }
+
+  // Check if already installed
+  try {
+    execSync('playwright-cli --version', { stdio: 'pipe' });
+    console.log(chalk.green('      ✓ playwright-cli (already installed)'));
+  } catch {
+    // Not installed, install it
+    try {
+      console.log(chalk.blue('      ⏳ Installing @playwright/cli globally...'));
+      execSync('npm install -g @playwright/cli@latest', { stdio: 'pipe', timeout: 120000 });
+      console.log(chalk.green('      ✓ @playwright/cli installed globally'));
+    } catch (e) {
+      console.log(chalk.yellow(`      ⚠ @playwright/cli install failed: ${e.message}`));
+      console.log(chalk.yellow('      ⚠ Run manually: npm install -g @playwright/cli@latest'));
+      return;
+    }
+  }
+
+  // Initialize workspace
+  try {
+    execSync('playwright-cli install', { cwd: projectRoot, stdio: 'pipe', timeout: 60000 });
+    console.log(chalk.green('      ✓ playwright-cli workspace initialized'));
+  } catch (e) {
+    console.log(chalk.yellow(`      ⚠ playwright-cli workspace init skipped: ${e.message}`));
+  }
+}
+
 // ============================================================
 // 主安装函数
 // ============================================================
@@ -705,11 +746,12 @@ export async function installGitignore(projectRoot, options, dryRun) {
  * @param {string} [config.rules] - Rules preset: 'recommended' | 'minimal' | 'none'
  * @param {string} [config.aiCli] - AI CLI 可执行命令（写入 .prizmkit/config.json）
  * @param {string[]} [config.externalSkills] - 要安装的外部 skill 名称列表
+ * @param {boolean} [config.playwrightCli] - 是否安装 playwright-cli
  * @param {string} config.projectRoot - 目标项目根目录
  * @param {boolean} config.dryRun - 是否为预览模式
  */
 export async function scaffold(config) {
-  const { platform, skills, team, pipeline, rules, aiCli, externalSkills, projectRoot, dryRun } = config;
+  const { platform, skills, team, pipeline, rules, aiCli, externalSkills, playwrightCli, projectRoot, dryRun } = config;
   const platforms = platform === 'both' ? ['codebuddy', 'claude'] : [platform];
 
   if (dryRun) {
@@ -803,7 +845,14 @@ export async function scaffold(config) {
     }
   }
 
-  // 10. Clean up stray .codebuddy/ directory left by third-party tools (e.g. npx skills)
+  // 10. Playwright CLI (optional)
+  if (playwrightCli) {
+    console.log(chalk.blue('    浏览器交互工具:'));
+    await installPlaywrightCli(projectRoot, dryRun);
+    console.log('');
+  }
+
+  // 11. Clean up stray .codebuddy/ directory left by third-party tools (e.g. npx skills)
   // when installing for Claude Code only. CodeBuddy files should never appear in a
   // claude-only install.
   if (!dryRun && !platforms.includes('codebuddy')) {
@@ -890,6 +939,7 @@ export async function scaffold(config) {
     console.log(chalk.gray(`    平台: ${platforms.map(p => p === 'codebuddy' ? 'CodeBuddy' : 'Claude Code').join(' + ')}`));
     console.log(chalk.gray(`    团队: ${team ? '已启用' : '未启用'}`));
     console.log(chalk.gray(`    流水线: ${pipeline ? '已安装' : '未安装'}`));
+    console.log(chalk.gray(`    浏览器工具: ${playwrightCli ? '已安装 (playwright-cli)' : '未安装'}`));
     console.log(chalk.gray(`    规则: ${rules || 'recommended'}`));
     if (aiCli) console.log(chalk.gray(`    AI CLI: ${aiCli}`));
     console.log('');