prizmkit 1.1.47 → 1.1.49

package/bundled/skills/bug-planner/scripts/validate-bug-list.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
 """
-Validate .prizmkit/plans/bug-fix-list.json against the PrizmKit bug-fix-list schema.
+Validate and generate .prizmkit/plans/bug-fix-list.json files
+for the dev-pipeline system.
+
+Commands:
+  validate    Validate an existing bug-fix-list.json
+  generate    Validate a draft JSON and generate final bug-fix-list.json with defaults
 
 Usage:
-    python3 validate-bug-list.py [.prizmkit/plans/bug-fix-list.json] [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py validate .prizmkit/plans/bug-fix-list.json [--feature-list .prizmkit/plans/feature-list.json]
+  python3 validate-bug-list.py generate --input draft.json --output .prizmkit/plans/bug-fix-list.json
 
 Exit codes:
-    0 = valid
-    1 = validation errors found
-    2 = file not found or JSON parse error
+  0 = valid / generated
+  1 = validation errors found
+  2 = file not found or JSON parse error
+
+Python 3.6+ required. No external dependencies.
 """
 
+import argparse
 import json
 import sys
 import os
 import re
+from datetime import datetime, timezone
 
 VALID_SEVERITIES = {"critical", "high", "medium", "low"}
 VALID_SOURCE_TYPES = {"stack_trace", "user_report", "failed_test", "log_pattern", "monitoring_alert"}
@@ -24,129 +34,289 @@ BUG_ID_PATTERN = re.compile(r"^B-\d{3}$")
 SCHEMA_VERSION = "dev-pipeline-bug-fix-list-v1"
 
 
-def validate(bug_list_path, feature_list_path=None):
-    errors = []
-    warnings = []
+def _err(msg):
+    """Print an error message to stderr."""
+    print("ERROR: {}".format(msg), file=sys.stderr)
+
+
+def _warn(msg):
+    """Print a warning message to stderr."""
+    print("WARN: {}".format(msg), file=sys.stderr)
+
 
-    # Load bug-fix-list.json
+def _info(msg):
+    """Print an informational message to stderr."""
+    print("INFO: {}".format(msg), file=sys.stderr)
+
+
+def _load_json(path):
+    """Load and return parsed JSON from a file. Returns (data, error_string)."""
+    if not os.path.isfile(path):
+        return None, "File not found: {}".format(path)
     try:
-        with open(bug_list_path) as f:
+        with open(path, "r", encoding="utf-8") as f:
             data = json.load(f)
-    except FileNotFoundError:
-        print(f"ERROR: File not found: {bug_list_path}", file=sys.stderr)
-        return 2
+        return data, None
     except json.JSONDecodeError as e:
-        print(f"ERROR: Invalid JSON in {bug_list_path}: {e}", file=sys.stderr)
-        return 2
+        return None, "Invalid JSON in {}: {}".format(path, e)
+    except Exception as e:
+        return None, "Cannot read {}: {}".format(path, e)
 
-    # Load feature-list.json (optional, for cross-reference)
-    feature_ids = set()
-    if feature_list_path:
-        try:
-            with open(feature_list_path) as f:
-                fl_data = json.load(f)
-            feature_ids = {f.get("id") for f in fl_data.get("features", [])}
-        except (FileNotFoundError, json.JSONDecodeError):
-            warnings.append(f"Could not load feature-list.json at {feature_list_path}")
+
+def _write_json(path, data):
+    """Write data as pretty-printed JSON to path. Creates parent dirs if needed."""
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def validate(data, feature_ids=None):
+    """Validate a parsed bug-fix-list data structure.
+
+    Returns a dict with keys: valid, errors, warnings, stats.
+    """
+    errors = []
+    warnings = []
 
     # Top-level required fields
     if "$schema" not in data:
         errors.append("Missing required field: $schema")
     elif data["$schema"] != SCHEMA_VERSION:
-        errors.append(f"Invalid $schema: expected '{SCHEMA_VERSION}', got '{data['$schema']}'")
+        errors.append("Invalid $schema: expected '{}', got '{}'".format(SCHEMA_VERSION, data["$schema"]))
 
     if not data.get("project_name"):
         errors.append("Missing or empty required field: project_name")
 
     bugs = data.get("bugs", [])
-    if not bugs:
+    if not bugs or not isinstance(bugs, list):
         errors.append("Missing or empty required field: bugs")
+        return {
+            "valid": False,
+            "errors": errors,
+            "warnings": warnings,
+            "stats": {"total_bugs": 0, "severity_distribution": {}},
+        }
 
     # Per-bug validation
     seen_ids = set()
-    seen_priorities = set()
+    severity_counts = {}
 
     for i, bug in enumerate(bugs):
-        prefix = f"bugs[{i}]"
+        prefix = "bugs[{}]".format(i)
 
         # Required fields
         bug_id = bug.get("id", "")
         if not bug_id:
-            errors.append(f"{prefix}: missing required field 'id'")
+            errors.append("{}: missing required field 'id'".format(prefix))
         elif not BUG_ID_PATTERN.match(bug_id):
-            errors.append(f"{prefix}: id '{bug_id}' does not match pattern B-NNN")
+            errors.append("{}: id '{}' does not match pattern B-NNN".format(prefix, bug_id))
 
         if bug_id in seen_ids:
-            errors.append(f"{prefix}: duplicate bug id '{bug_id}'")
+            errors.append("{}: duplicate bug id '{}'".format(prefix, bug_id))
         seen_ids.add(bug_id)
 
         if not bug.get("title"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'title'")
+            errors.append("{} ({}): missing required field 'title'".format(prefix, bug_id))
 
         if not bug.get("description"):
-            errors.append(f"{prefix} ({bug_id}): missing required field 'description'")
+            errors.append("{} ({}): missing required field 'description'".format(prefix, bug_id))
 
         severity = bug.get("severity", "")
         if severity not in VALID_SEVERITIES:
-            errors.append(f"{prefix} ({bug_id}): invalid severity '{severity}' — must be one of {VALID_SEVERITIES}")
+            errors.append("{} ({}): invalid severity '{}' — must be one of {}".format(
+                prefix, bug_id, severity, sorted(VALID_SEVERITIES)))
+        else:
+            severity_counts[severity] = severity_counts.get(severity, 0) + 1
 
         # error_source
         error_source = bug.get("error_source", {})
         source_type = error_source.get("type", "") if isinstance(error_source, dict) else ""
         if source_type not in VALID_SOURCE_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid error_source.type '{source_type}' — must be one of {VALID_SOURCE_TYPES}")
+            errors.append("{} ({}): invalid error_source.type '{}' — must be one of {}".format(
+                prefix, bug_id, source_type, sorted(VALID_SOURCE_TYPES)))
 
         # verification_type
         vtype = bug.get("verification_type", "")
         if vtype not in VALID_VERIFICATION_TYPES:
-            errors.append(f"{prefix} ({bug_id}): invalid verification_type '{vtype}' — must be one of {VALID_VERIFICATION_TYPES}")
+            errors.append("{} ({}): invalid verification_type '{}' — must be one of {}".format(
+                prefix, bug_id, vtype, sorted(VALID_VERIFICATION_TYPES)))
 
         # acceptance_criteria
         ac = bug.get("acceptance_criteria", [])
         if not ac or not isinstance(ac, list):
-            errors.append(f"{prefix} ({bug_id}): missing or empty acceptance_criteria array")
+            errors.append("{} ({}): missing or empty acceptance_criteria array".format(prefix, bug_id))
 
         # status
         status = bug.get("status", "")
         if status not in VALID_STATUSES:
-            errors.append(f"{prefix} ({bug_id}): invalid status '{status}' — must be one of {VALID_STATUSES}")
+            errors.append("{} ({}): invalid status '{}' — must be one of {}".format(
+                prefix, bug_id, status, sorted(VALID_STATUSES)))
 
         # Priority validation (optional field)
         priority = bug.get("priority")
         if priority is not None:
             if priority not in ("high", "medium", "low"):
-                errors.append(f"{prefix} ({bug_id}): invalid priority '{priority}' — must be one of 'high', 'medium', 'low'")
+                errors.append("{} ({}): invalid priority '{}' — must be one of 'high', 'medium', 'low'".format(
+                    prefix, bug_id, priority))
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+        "warnings": warnings,
+        "stats": {
+            "total_bugs": len(bugs),
+            "severity_distribution": severity_counts,
+        },
+    }
+
+
+def cmd_validate(args):
+    """Handle the 'validate' command."""
+    bug_list = args.input
+    feature_list = args.feature_list
+
+    data, load_err = _load_json(bug_list)
+    if load_err:
+        _err(load_err)
+        return 2
+
+    # Load feature-list.json (optional, for cross-reference)
+    if feature_list:
+        fl_data, fl_err = _load_json(feature_list)
+        if not fl_data:
+            _warn("Could not load feature-list.json at {}: {}".format(feature_list, fl_err))
+
+    result = validate(data)
 
+    # Print results to stdout
+    print(json.dumps(result, indent=2, ensure_ascii=False))
 
-    # Output results
-    if errors:
-        print(f"VALIDATION FAILED — {len(errors)} error(s), {len(warnings)} warning(s)\n")
-        for e in errors:
-            print(f"  ERROR: {e}")
-        for w in warnings:
-            print(f"  WARN:  {w}")
+    if result["valid"]:
+        bug_count = result["stats"]["total_bugs"]
+        sev = result["stats"]["severity_distribution"]
+        sev_str = ", ".join("{}={}".format(k, v) for k, v in sorted(sev.items()))
+        _info("VALIDATION PASSED — {} bugs ({})".format(bug_count, sev_str))
+        return 0
+    else:
+        _err("VALIDATION FAILED — {} error(s), {} warning(s)".format(
+            len(result["errors"]), len(result["warnings"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        for w in result["warnings"]:
+            _warn("  WARN: {}".format(w))
         return 1
+
+
+def cmd_generate(args):
+    """Handle the 'generate' command.
+
+    Loads a draft JSON (produced by AI), fills in defaults, validates,
+    and writes the final bug-fix-list.json.
+    """
+    # Load draft (supports stdin via '-')
+    if args.input == "-":
+        try:
+            data = json.load(sys.stdin)
+        except json.JSONDecodeError as exc:
+            _err("Invalid JSON from stdin: {}".format(exc))
+            return 2
     else:
-        bug_count = len(bugs)
-        severity_counts = {}
-        for b in bugs:
-            s = b.get("severity", "unknown")
-            severity_counts[s] = severity_counts.get(s, 0) + 1
-        sev_str = ", ".join(f"{k}={v}" for k, v in sorted(severity_counts.items()))
-        print(f"VALIDATION PASSED — {bug_count} bugs ({sev_str})")
-        if warnings:
-            for w in warnings:
-                print(f"  WARN:  {w}")
+        data, load_err = _load_json(args.input)
+        if load_err:
+            _err(load_err)
+            return 2
+
+    # Fill in defaults
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    data.setdefault("$schema", SCHEMA_VERSION)
+    data.setdefault("created_at", now)
+    data.setdefault("created_by", "bug-planner")
+
+    # Set default status for bugs without one
+    for bug in data.get("bugs", []):
+        bug.setdefault("status", "pending")
+
+    # Validate
+    result = validate(data)
+
+    # Output validation result
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+    if result["valid"]:
+        _write_json(args.output, data)
+        _info("Generated bug-fix-list written to {}".format(args.output))
         return 0
+    else:
+        _err("Validation failed with {} error(s)".format(len(result["errors"])))
+        for e in result["errors"]:
+            _err("  ERROR: {}".format(e))
+        return 1
 
 
-if __name__ == "__main__":
-    bug_list = sys.argv[1] if len(sys.argv) > 1 else ".prizmkit/plans/bug-fix-list.json"
-    feature_list = None
+def main():
+    # Backward compatibility: if first arg is a file path (not a subcommand),
+    # treat it as 'validate' command
+    if len(sys.argv) > 1 and not sys.argv[1].startswith("-") and sys.argv[1] not in ("validate", "generate"):
+        sys.argv.insert(1, "validate")
+
+    parser = argparse.ArgumentParser(
+        description="Validate and generate .prizmkit/plans/bug-fix-list.json files.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json\n"
+            "  %(prog)s validate .prizmkit/plans/bug-fix-list.json --feature-list .prizmkit/plans/feature-list.json\n"
+            "  %(prog)s generate --input draft.json --output .prizmkit/plans/bug-fix-list.json\n"
+        ),
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # -- validate --
+    p_validate = subparsers.add_parser(
+        "validate",
+        help="Validate an existing bug-fix-list.json",
+    )
+    p_validate.add_argument(
+        "input", help="Path to bug-fix-list.json"
+    )
+    p_validate.add_argument(
+        "--feature-list", default=None, help="Path to feature-list.json for cross-reference"
+    )
 
-    if "--feature-list" in sys.argv:
-        idx = sys.argv.index("--feature-list")
-        if idx + 1 < len(sys.argv):
-            feature_list = sys.argv[idx + 1]
+    # -- generate --
+    p_generate = subparsers.add_parser(
+        "generate",
+        help="Validate a draft and generate final bug-fix-list.json with defaults",
+    )
+    p_generate.add_argument(
+        "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
+    )
+    p_generate.add_argument(
+        "--output", required=True, help="Path to write final bug-fix-list.json"
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 2
 
-    sys.exit(validate(bug_list, feature_list))
+    dispatch = {
+        "validate": cmd_validate,
+        "generate": cmd_generate,
+    }
+
+    handler = dispatch.get(args.command)
+    if handler is None:
+        _err("Unknown command: {}".format(args.command))
+        return 2
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -112,23 +112,30 @@ Detect user intent from their message, then follow the corresponding workflow:
      --action status 2>/dev/null
    ```
 
-4. **Ask execution mode** (first user decision):
+4. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call):
 
-   Present the three modes and ask the user to choose:
-   - **(1) Foreground** (recommended) — pipeline runs in the current session via `run-bugfix.sh run`. Visible output and direct error feedback.
-   - **(2) Background daemon** — pipeline runs fully detached via `launch-bugfix-daemon.sh`. Survives AI CLI session closure.
-   - **(3) Manual** — display the final assembled commands only. Do not execute anything. User runs them on their own.
+   ⛔ **This MUST be its own standalone `AskUserQuestion` call.** Do NOT combine execution mode with step 5 config questions. The execution mode question is asked ALONE, user responds, THEN you proceed to step 5.
 
-5. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 6. Do NOT skip this step or merge it with step 6.
+   Use `AskUserQuestion` with exactly 1 question:
 
-   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the questions below and WAIT for the user's response. You MUST NOT:
+   **Question 1 — Execution mode** (multiSelect: false):
+   - Foreground (Recommended) — pipeline runs in the current session via `run-bugfix.sh run`. Visible output and direct error feedback.
+   - Background daemon — pipeline runs fully detached via `launch-bugfix-daemon.sh`. Survives AI CLI session closure.
+   - Manual — display the final assembled commands only. Do not execute anything. User runs them on their own.
+
+   ⚠️ STOP HERE and wait for user response before continuing to step 5.
+
+5. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 4. You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 6.
+
+   ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the 4 questions below and WAIT for the user's response. You MUST NOT:
+   - Combine step 4 and step 5 into one `AskUserQuestion` call (this is the most common violation — execution mode MUST be asked separately in step 4)
    - Skip this step and jump to the next step
    - Merge this step and the next step into one response
    - Assume default values and show the command without asking
    - Show the command as text and ask "ready?" without presenting the options
-   If you find yourself writing the final command before the user has answered these questions, STOP — you are violating this rule.
+   If you find yourself writing the final command before the user has answered these 4 questions, STOP — you are violating this rule.
 
-   Use `AskUserQuestion` to present the following configuration choices. Each question is a separate selectable option:
+   Use `AskUserQuestion` to present ALL 4 configuration choices (the full 4-question budget goes to config, NOT shared with execution mode):
 
    **Question 1 — Verbose logging** (multiSelect: false):
    - On (default) — Detailed AI session logs including tool calls and subagent activity

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

@@ -129,23 +129,30 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    If `global_context.database` is absent and no features mention database keywords, the script skips DB checks automatically.
 
-5. **Ask execution mode** (first user decision):
+5. **Ask execution mode** (first user decision — SEPARATE `AskUserQuestion` call):
 
-   Present the three modes and ask the user to choose:
-   - **(1) Foreground** (recommended) — pipeline runs in the current session via `run-feature.sh run`. Visible output and direct error feedback.
-   - **(2) Background daemon** — pipeline runs fully detached via `launch-feature-daemon.sh`. Survives AI CLI session closure.
-   - **(3) Manual** — display the final assembled commands only. Do not execute anything. User runs them on their own.
+   ⛔ **This MUST be its own standalone `AskUserQuestion` call.** Do NOT combine execution mode with step 6 config questions. The execution mode question is asked ALONE, user responds, THEN you proceed to step 6.
 
-6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7. Do NOT skip this step or merge it with step 7.
+   Use `AskUserQuestion` with exactly 1 question:
+
+   **Question 1 — Execution mode** (multiSelect: false):
+   - Foreground (Recommended) — pipeline runs in the current session via `run-feature.sh run`. Visible output and direct error feedback.
+   - Background daemon — pipeline runs fully detached via `launch-feature-daemon.sh`. Survives AI CLI session closure.
+   - Manual — display the final assembled commands only. Do not execute anything. User runs them on their own.
+
+   ⚠️ STOP HERE and wait for user response before continuing to step 6.
+
+6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). This is a SEPARATE `AskUserQuestion` call from step 5. You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7.
 
    ⛔ **HARD STOP**: You MUST call `AskUserQuestion` with the 4 questions below and WAIT for the user's response. You MUST NOT:
+   - Combine step 5 and step 6 into one `AskUserQuestion` call (this is the most common violation — execution mode MUST be asked separately in step 5)
    - Skip this step and jump to step 7
    - Merge step 6 and step 7 into one response
    - Assume default values and show the command without asking
    - Show the command as text and ask "ready?" without presenting the options
-   If you find yourself writing the final command before the user has answered these questions, STOP — you are violating this rule.
+   If you find yourself writing the final command before the user has answered these 4 questions, STOP — you are violating this rule.
 
-   Use `AskUserQuestion` to present the following configuration choices. Each question is a separate selectable option:
+   Use `AskUserQuestion` to present ALL 4 configuration choices (the full 4-question budget goes to config, NOT shared with execution mode):
 
    **Question 1 — Critic review** (multiSelect: false):
    - Off (default) — Skip adversarial review
@@ -162,9 +169,7 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    **Question 4 — Advanced config?** (multiSelect: false):
    - No (default) — Use defaults for session timeout and failure behavior
-   - Yes — Configure session timeout and stop-on-failure options
-
-   Note: Due to the 4-question limit per `AskUserQuestion` call, Feature filter and Browser verify use their defaults (all features, auto-detect browser tools). If the user selects "Other" on any option, handle their custom input.
+   - Yes — Configure session timeout, stop-on-failure, and deploy-after-completion options
 
    Default Critic to Off unless features have `estimated_complexity: "high"` or above (in which case default to On).
 

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

@@ -263,9 +263,12 @@ For simple incremental planning, skip detailed Phase 2-3 analysis:
    **NEVER proceed without explicit user selection via `AskUserQuestion`. Do NOT render options as plain text — the user must be able to click/select.**
 3. Generate next sequential feature IDs
 4. Draft features (title + description + acceptance_criteria + dependencies)
-5. Run validation script immediately
+5. Write draft to `.prizmkit/plans/feature-list.draft.json`, then call the generate script:
+   ```bash
+   python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode incremental
+   ```
 6. If valid → summarize and recommend next step
-7. If invalid → apply fixes, re-validate (max 2 attempts, then escalate to full workflow)
+7. If invalid → apply fixes to the draft, re-run generate (max 2 attempts, then escalate to full workflow)
 
 ## Browser Interaction Planning
 
@@ -284,10 +287,11 @@ A feature is **exempt** when ANY true:
 
 ### Default Behavior (Phase 4.2)
 
-1. **Auto-generate** `browser_interaction` for ALL qualifying features. Read `${SKILL_DIR}/references/browser-interaction.md` for the object format, field rules, and `tool` selection guide.
-2. **Tool selection**: Default `tool` to `"auto"`. Override to `"opencli"` when the feature involves OAuth/SSO callbacks, third-party dashboard verification, or requires real login state. Override to `"playwright-cli"` when the feature is purely local UI (forms, components, routing).
-3. **Present a summary** to the user showing which features received `browser_interaction` (including the `tool` value).
-4. **User can opt-OUT** specific features or override the `tool` choice.
+1. **Ask user for browser tool preference (Mandatory)**: Before generating any `browser_interaction` fields, use `AskUserQuestion` to ask which browser verification tool to use as the project default. Read `${SKILL_DIR}/references/browser-interaction.md` §Browser Tool Selection for the exact question format and options (`auto`/`playwright-cli`/`opencli`). Do NOT skip this step or assume a default without asking.
+2. **Auto-generate** `browser_interaction` for ALL qualifying features. Read `${SKILL_DIR}/references/browser-interaction.md` for the object format, field rules, and per-feature `tool` override logic.
+3. **Tool assignment per feature**: Use the user's chosen default. Override to `"opencli"` when the feature involves OAuth/SSO callbacks, third-party dashboard verification, or requires real login state. Override to `"playwright-cli"` when the feature is purely local UI (forms, components, routing). If user chose `"auto"`, AI assigns per-feature based on these rules.
+4. **Present a summary** to the user showing which features received `browser_interaction` (including the `tool` value for each).
+5. **User can opt-OUT** specific features or override the `tool` choice.
 
 ## Output Rules
 
@@ -308,10 +312,13 @@ Key requirements:
   - `high` → **standard** (orchestrator + dev + reviewer, 3 agents)
   - `critical` → **full** (full team + critic agents, 5 agents). Use for: architectural changes touching 10+ files, cross-module refactoring with API surface changes, features requiring multi-critic voting
 
-Run the validation script after generation:
+**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
+1. Write a draft JSON to a temporary path (e.g., `.prizmkit/plans/feature-list.draft.json`)
+2. Call the generate script to validate and produce the final file:
 ```bash
-python3 ${SKILL_DIR}/scripts/validate-and-generate.py validate --input <output-path> --mode <new|incremental>
+python3 ${SKILL_DIR}/scripts/validate-and-generate.py generate --input .prizmkit/plans/feature-list.draft.json --output .prizmkit/plans/feature-list.json --mode <new|incremental>
 ```
+The script fills in defaults (`$schema`, `created_at`, `created_by`), validates all fields, and writes the final file only if validation passes. If validation fails, fix the draft and retry.
 
 ## Testing Defaults (Phase 8)
 
@@ -323,7 +330,7 @@ Set default testing-related fields for each feature. The user can opt out.
 | medium | `true` | `1` | Single critic review |
 | low | `false` | (omitted) | Skip critic |
 
-For frontend features with `browser_interaction`, browser verification is enabled by default. The `tool` field determines which browser tool is used (default: `auto` — AI chooses at runtime between `playwright-cli` and `opencli`).
+For frontend features with `browser_interaction`, browser verification is enabled by default. The `tool` field uses the user's choice from the mandatory browser tool question in Phase 4.2 (see §Browser Interaction Planning → Default Behavior).
 
 Present a consolidated testing summary table at Phase 8, then ask for confirmation.
 

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

@@ -1,6 +1,17 @@
 # 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.
+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 after implementation using the configured browser tool (`playwright-cli` or `opencli`).
+
+## Browser Tool Selection (Mandatory — Ask User)
+
+Before auto-generating `browser_interaction` for features, you MUST ask the user which browser tool to use as the project default via `AskUserQuestion`:
+
+**Question**: "Which browser verification tool should this project use by default?"
+- **Auto — AI chooses per feature (Recommended)** — `playwright-cli` for local UI, `opencli` for authenticated flows. AI decides per-feature at planning time.
+- **playwright-cli** — isolated browser instance, no login state. Best for local dev server, forms, components.
+- **opencli** — reuses Chrome's logged-in sessions via Browser Bridge. Best for OAuth, third-party dashboards, SSO.
+
+Store the user's choice as the project-level default. Individual features can still override (see Tool Selection per Feature below).
 
 ## How to Capture
 
@@ -11,6 +22,7 @@ For each qualifying feature, generate the `browser_interaction` object:
 ```json
 {
   "browser_interaction": {
+    "tool": "auto",
     "verify_steps": [
       "Verify login form renders with email and password fields",
       "Verify valid credentials redirect to dashboard",