prizmkit 1.0.135 → 1.0.137

package/bundled/VERSION.json

@@ -1,5 +1,5 @@
 {
-  "frameworkVersion": "1.0.135",
-  "bundledAt": "2026-03-28T13:09:04.448Z",
-  "bundledFrom": "661d63b"
+  "frameworkVersion": "1.0.137",
+  "bundledAt": "2026-03-28T13:49:17.127Z",
+  "bundledFrom": "1cfc8e2"
 }

package/bundled/skills/_metadata.json

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

@@ -153,6 +153,7 @@ Execute the selected scenario workflow in conversation mode with mandatory check
 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.
+   4.2 **browser interaction evaluation** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. For each feature with UI-related acceptance criteria, you MUST ask the user whether to add `browser_interaction`. Do NOT skip or defer this step.
 5. verify DAG/order/priorities
 6. build or append `feature-list.json`
 7. ask whether to enable adversarial critic review for high/critical features
@@ -169,6 +170,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | **CP-AP-1** | Vision Summary | Goal/users/differentiators confirmed by user | 1-2 |
 | **CP-AP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
 | **CP-AP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 6 |
+| **CP-AP-3.2** | Browser Interaction Evaluated | For each feature with UI acceptance criteria: user was asked about browser verification | 4 |
 | **CP-AP-3.5** | Critic Decision | User decided on critic review for high/critical features | 7 |
 | **CP-AP-4** | `feature-list.json` Generated | Schema validates, all required keys present | 6-7 |
 | **CP-AP-5** | Final Validation Pass | Python script returns `"valid": true` with zero errors | 8 |
@@ -222,13 +224,34 @@ AI: "Ready to proceed to dev-pipeline."
 
 ## Browser Interaction Planning
 
-For features with user-visible UI (pages, forms, modals), optionally add `browser_interaction` for automated playwright-cli verification in the pipeline.
+For fullstack/frontend projects, evaluate each feature for automated browser verification via `browser_interaction`. This is a **mandatory evaluation step** (Phase 4.2), not an optional suggestion.
 
-**Suggest when**: web frontend + user-visible UI + acceptance criteria reference visual/interactive behavior.
-**Do NOT suggest for**: backend-only, config/setup, or non-UI features.
+### Auto-Detection Rule
 
-During Phase 4, ask qualifying features: "Want to add browser verification? (Y/n)"
-If yes → read `references/browser-interaction.md` for the `browser_interaction` object format and field rules.
+A feature **qualifies** for browser interaction evaluation when ALL of these are true:
+1. `global_context.frontend_framework` exists (project has a frontend)
+2. The feature's `acceptance_criteria` contain UI-related keywords: click, button, modal, page, form, display, navigate, tab, input, opens, shows, renders, visible, redirect, download, upload, preview, select, toggle, dropdown, popup, toast, menu
+
+A feature is **exempt** when ANY of these are true:
+- It is backend-only (API endpoints, database migrations, no UI criteria)
+- It is config/setup/infrastructure
+- It has `status: "completed"` (already implemented)
+
+### Mandatory Prompt (Phase 4.2)
+
+For EACH qualifying feature, you MUST ask:
+
+> "Feature {F-XXX} has UI behavior in its acceptance criteria. Add browser verification so the pipeline can auto-check it after implementation? (Y/n)"
+
+- If **yes** → read `references/browser-interaction.md` for the `browser_interaction` object format and field rules. Generate the field for this feature.
+- If **no** → record the decision and move on. No field is added.
+- If **user says no to all** → skip remaining features (batch decline). Record that user declined browser verification globally.
+
+**You must NOT skip this prompt for qualifying features.** The checkpoint CP-AP-3.2 verifies this step was completed.
+
+### When NOT to evaluate
+
+**Do NOT prompt for**: backend-only features, config/setup features, or non-UI features. These are automatically exempt — no user prompt needed.
 
 ## Output Rules
 

package/bundled/skills/app-planner/scripts/validate-and-generate.py

@@ -41,6 +41,14 @@ VALID_PLANNING_MODES = {"new", "incremental"}
 FEATURE_ID_RE = re.compile(r"^F-\d{3}(-[A-Z])?$")
 SUB_FEATURE_ID_RE = re.compile(r"^F-\d{3}-[A-Z]$")
 
+# Keywords in acceptance criteria that indicate UI/browser interaction behavior.
+UI_KEYWORDS_RE = re.compile(
+    r"\b(click|button|modal|page|form|display|navigate|tab|input|opens|shows|"
+    r"renders|visible|redirect|download|upload|preview|select|toggle|dropdown|"
+    r"popup|toast|menu)\b",
+    re.IGNORECASE,
+)
+
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -333,6 +341,23 @@ def validate_feature_list(data, planning_mode="new"):
             errors.append(
                 "{}: 'critic_count' must be 1 or 3, got {}".format(label, critic_count)
             )
+
+        # -- Browser interaction check (warning for frontend features) --
+        has_frontend = bool(
+            data.get("global_context", {}).get("frontend_framework")
+        )
+        if has_frontend and feat.get("status") != "completed":
+            criteria = feat.get("acceptance_criteria", [])
+            criteria_text = " ".join(
+                c for c in criteria if isinstance(c, str)
+            )
+            if UI_KEYWORDS_RE.search(criteria_text):
+                if feat.get("browser_interaction") is None:
+                    warnings.append(
+                        "{}: has UI acceptance criteria but no browser_interaction "
+                        "field. Consider adding browser verification.".format(label)
+                    )
+
         if isinstance(subs, list):
             for sidx, sub in enumerate(subs):
                 sub_label = "{}->sub_features[{}]".format(label, sidx)

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

@@ -9,16 +9,11 @@ Launch the autonomous bug fix pipeline from within an AI CLI conversation. Suppo
 
 ### Execution Mode
 
-**Default: Foreground mode** via `dev-pipeline/run-bugfix.sh run` — this provides visible output and direct error feedback. Use `launch-bugfix-daemon.sh` only when the user explicitly requests background execution.
+Three execution modes are available. The user chooses one before configuring other options:
 
-Foreground `run-bugfix.sh` is preferred because:
-- Immediate visibility of errors and progress
-- No orphaned processes if something goes wrong
-- Session summary artifacts are written reliably
-
-Use daemon mode (`launch-bugfix-daemon.sh`) only when:
-- User explicitly requests background/detached execution
-- Pipeline must survive AI CLI session closure
+1. **Foreground** (recommended) — `dev-pipeline/run-bugfix.sh run`. Visible output, direct error feedback, no orphaned processes.
+2. **Background daemon** — `dev-pipeline/launch-bugfix-daemon.sh`. Runs fully detached, survives AI CLI session closure.
+3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
 
 **Background mode documentation**: When the user chooses background/daemon mode, record the choice and PID in `.prizmkit/bugfix-pipeline-run.log` (append-only) with timestamp, so the decision is traceable:
 ```
@@ -111,19 +106,25 @@ Detect user intent from their message, then follow the corresponding workflow:
      --action status 2>/dev/null
    ```
 
-4. **Present all runtime options**: Show the user a complete options summary before launching. Present each option with its default, so the user can confirm or override.
+4. **Ask execution mode** (first user decision):
+
+   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.
 
-   **Runtime Options:**
+5. **Present configuration options**: After execution mode is chosen, show the remaining options with defaults. Ask the user to confirm or override.
+
+   **Configuration Options:**
 
    | Option | Default | Description |
    |--------|---------|-------------|
-   | **Execution mode** | Foreground | (1) Foreground — visible output (2) Background daemon — survives session closure (3) Manual — show commands only |
    | **Verbose logging** | On | Detailed AI session logs including tool calls and subagent activity |
    | **Max retries** | 3 | Max retry attempts per failed bug |
    | **Session timeout** | None | Per-bug timeout in seconds (e.g. `3600` = 1 hour) |
    | **Bug filter** | All | Run specific bugs: `B-001:B-005` (range), `B-001,B-003` (list), or mixed `B-001,B-005:B-010` |
 
-   Default to Foreground + Verbose On if user doesn't specify.
+   Default Verbose On.
 
    **Environment variable mapping** (for natural language → env var translation):
 
@@ -136,19 +137,18 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Example presentation to user:
    ```
-   Bugfix pipeline will process N bugs with these settings:
-   - Execution:   Foreground (recommended)
+   Bugfix pipeline will process N bugs in Foreground mode:
    - Verbose:     On (subagent detection enabled)
    - Max retries: 3
    - Timeout:     none
    - Bugs:        all (by severity order)
 
-   Want to change any options, or launch with these defaults?
+   Want to change any options, or proceed with these defaults?
    ```
 
-   **Execution mode details:**
+6. **Show final command**: Assemble the complete command from execution mode + confirmed configuration, and present it to the user.
 
-   **Foreground (recommended)**: Pipeline runs in the current session via `run-bugfix.sh run`. Provides visible output and direct error feedback.
+   **Foreground command:**
    ```bash
    VERBOSE=1 dev-pipeline/run-bugfix.sh run bug-fix-list.json
    ```
@@ -158,7 +158,7 @@ Detect user intent from their message, then follow the corresponding workflow:
      dev-pipeline/run-bugfix.sh run bug-fix-list.json
    ```
 
-   **Background daemon**: Pipeline runs fully detached via `launch-bugfix-daemon.sh`. Survives session closure. Use only when user explicitly requests background execution.
+   **Background daemon command:**
    ```bash
    dev-pipeline/launch-bugfix-daemon.sh start bug-fix-list.json --env "VERBOSE=1"
    ```
@@ -168,9 +168,9 @@ Detect user intent from their message, then follow the corresponding workflow:
      --env "VERBOSE=1 MAX_RETRIES=5"
    ```
 
-   **Manual — show commands**: Display the exact commands the user can run themselves. Print commands and stop. Do not execute anything.
+   **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 7.
    ```
-   # To run in foreground (recommended):
+   # To run in foreground:
    VERBOSE=1 dev-pipeline/run-bugfix.sh run bug-fix-list.json
 
    # To run in background (detached):
@@ -180,11 +180,13 @@ Detect user intent from their message, then follow the corresponding workflow:
    dev-pipeline/run-bugfix.sh status bug-fix-list.json
    ```
 
-5. **Ask user to confirm**: "Ready to launch the bugfix pipeline with the above settings?"
+7. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 6):
+
+   Ask: "Ready to launch the bugfix pipeline with the above command?"
 
-6. **Launch** with the assembled command from step 4.
+   After user confirms, execute the command from step 6.
 
-7. **Post-launch** (depends on execution mode):
+8. **Post-launch** (depends on execution mode):
 
    **If foreground**: Pipeline runs to completion in the terminal. After it finishes:
    - Summarize results: total bugs, fixed, failed, skipped

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

@@ -9,16 +9,11 @@ Launch the autonomous development pipeline from within an AI CLI conversation. T
 
 ### Execution Mode
 
-**Default: Foreground mode** via `dev-pipeline/run.sh run` — this provides visible output and direct error feedback. Use `launch-daemon.sh` only when the user explicitly requests background execution (e.g., "run in background", "detached mode").
+Three execution modes are available. The user chooses one before configuring other options:
 
-Foreground `run.sh` is preferred because:
-- Immediate visibility of errors and progress
-- No orphaned processes if something goes wrong
-- Session summary artifacts are written reliably
-
-Use daemon mode (`launch-daemon.sh`) only when:
-- User explicitly requests background/detached execution
-- Pipeline must survive AI CLI session closure
+1. **Foreground** (recommended) — `dev-pipeline/run.sh run`. Visible output, direct error feedback, no orphaned processes.
+2. **Background daemon** — `dev-pipeline/launch-daemon.sh`. Runs fully detached, survives AI CLI session closure.
+3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
 
 ### When to Use
 
@@ -108,13 +103,19 @@ Detect user intent from their message, then follow the corresponding workflow:
      --action status 2>/dev/null
    ```
 
-4. **Present all runtime options**: Show the user a complete options summary before launching. Present each option with its default, so the user can confirm or override.
+4. **Ask execution mode** (first user decision):
+
+   Present the three modes and ask the user to choose:
+   - **(1) Foreground** (recommended) — pipeline runs in the current session via `run.sh run`. Visible output and direct error feedback.
+   - **(2) Background daemon** — pipeline runs fully detached via `launch-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.
 
-   **Runtime Options:**
+5. **Present configuration options**: After execution mode is chosen, show the remaining options with defaults. Ask the user to confirm or override.
+
+   **Configuration Options:**
 
    | Option | Default | Description |
    |--------|---------|-------------|
-   | **Execution mode** | Foreground | (1) Foreground — visible output (2) Background daemon — survives session closure (3) Manual — show commands only |
    | **Critic review** | Off | Adversarial review after planning & implementation. Increases time ~5-10 min/feature |
    | **Verbose logging** | On | Detailed AI session logs including tool calls and subagent activity |
    | **Max retries** | 3 | Max retry attempts per failed feature |
@@ -122,7 +123,7 @@ Detect user intent from their message, then follow the corresponding workflow:
    | **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.
+   Default Verbose On. Default Critic to Off unless features have `estimated_complexity: "high"` or above.
 
    **Environment variable mapping** (for natural language → env var translation):
 
@@ -138,20 +139,19 @@ Detect user intent from their message, then follow the corresponding workflow:
 
    Example presentation to user:
    ```
-   Pipeline will process N features with these settings:
-   - Execution:   Foreground (recommended)
+   Pipeline will process N features in Foreground mode:
    - Critic:      Off
    - Verbose:     On (subagent detection enabled)
    - Max retries: 3
    - Timeout:     none
    - Features:    all
 
-   Want to change any options, or launch with these defaults?
+   Want to change any options, or proceed with these defaults?
    ```
 
-   **Execution mode details:**
+6. **Show final command**: Assemble the complete command from execution mode + confirmed configuration, and present it to the user.
 
-   **Foreground (recommended)**: Pipeline runs in the current session via `run.sh run`. Provides visible output and direct error feedback.
+   **Foreground command:**
    ```bash
    VERBOSE=1 dev-pipeline/run.sh run feature-list.json
    ```
@@ -161,7 +161,7 @@ Detect user intent from their message, then follow the corresponding workflow:
      dev-pipeline/run.sh run feature-list.json --features F-001:F-005
    ```
 
-   **Background daemon**: Pipeline runs fully detached via `launch-daemon.sh`. Survives session closure. Use only when user explicitly requests background execution.
+   **Background daemon command:**
    ```bash
    dev-pipeline/launch-daemon.sh start feature-list.json --env "VERBOSE=1"
    ```
@@ -171,9 +171,9 @@ Detect user intent from their message, then follow the corresponding workflow:
      --env "VERBOSE=1 ENABLE_CRITIC=true MAX_RETRIES=5"
    ```
 
-   **Manual — show commands**: Display the exact commands the user can run themselves. Print commands and stop. Do not execute anything.
+   **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 7.
    ```
-   # To run in foreground (recommended):
+   # To run in foreground:
    VERBOSE=1 dev-pipeline/run.sh run feature-list.json
 
    # To run in background (detached):
@@ -183,11 +183,13 @@ Detect user intent from their message, then follow the corresponding workflow:
    dev-pipeline/run.sh status feature-list.json
    ```
 
-5. **Ask user to confirm**: "Ready to launch the pipeline with the above settings?"
+7. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 6):
+
+   Ask: "Ready to launch the pipeline with the above command?"
 
-6. **Launch** with the assembled command from step 4.
+   After user confirms, execute the command from step 6.
 
-7. **Post-launch** (depends on execution mode):
+8. **Post-launch** (depends on execution mode):
 
    **If foreground**: Pipeline runs to completion in the terminal. After it finishes:
    - Summarize results: total features, succeeded, failed, skipped

package/package.json

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

package/src/manifest.js

@@ -55,6 +55,7 @@ export async function writeManifest(projectRoot, data) {
  * @param {boolean} params.team - whether team config was installed
  * @param {string} [params.aiCli] - AI CLI command
  * @param {string} [params.rulesPreset] - rules preset name
+ * @param {string[]} [params.extras] - installed extras (e.g. ['playwright-cli'])
  * @returns {Object} manifest
  */
 export function buildManifest({
@@ -68,6 +69,7 @@ export function buildManifest({
   team,
   aiCli,
   rulesPreset,
+  extras,
 }) {
   const now = new Date().toISOString();
   return {
@@ -87,6 +89,7 @@ export function buildManifest({
       agents: [...agents],
       rules: [...rules],
       pipeline: pipeline ? [...pipeline] : [],
+      extras: extras ? [...extras] : [],
       other: [platform === 'claude' ? 'CLAUDE.md' : platform === 'codebuddy' ? 'CODEBUDDY.md' : 'CLAUDE.md'],
     },
   };

package/src/scaffold.js

@@ -676,6 +676,7 @@ export async function installPipeline(projectRoot, dryRun, { forceOverwrite = fa
  */
 export async function installGitignore(projectRoot, options, dryRun) {
   const targetPath = path.join(projectRoot, '.gitignore');
+  const templateContent = generateGitignore({ pipeline: options.pipeline });
 
   if (dryRun) {
     console.log(chalk.gray(`      [dry-run] .gitignore`));
@@ -683,12 +684,22 @@ export async function installGitignore(projectRoot, options, dryRun) {
   }
 
   if (await fs.pathExists(targetPath)) {
-    console.log(chalk.yellow(`      ⚠ .gitignore 已存在，跳过`));
-    return;
+    // 合并模式：追加缺失条目
+    const existing = await fs.readFile(targetPath, 'utf-8');
+    const existingLines = new Set(existing.split('\n').map(l => l.trim()));
+    const templateLines = templateContent.split('\n').map(l => l.trim()).filter(Boolean);
+    const missing = templateLines.filter(line => !existingLines.has(line) && !line.startsWith('#'));
+
+    if (missing.length > 0) {
+      const separator = existing.endsWith('\n') ? '' : '\n';
+      await fs.appendFile(targetPath, separator + '\n# PrizmKit\n' + missing.join('\n') + '\n');
+      console.log(chalk.green(`      ✓ .gitignore (added ${missing.length} entries)`));
+    } else {
+      console.log(chalk.green('      ✓ .gitignore (up-to-date)'));
+    }
   } else {
-    const content = generateGitignore({ pipeline: options.pipeline });
-    await fs.writeFile(targetPath, content);
-    console.log(chalk.green(`      ✓ .gitignore`));
+    await fs.writeFile(targetPath, templateContent);
+    console.log(chalk.green('      ✓ .gitignore'));
   }
 }
 
@@ -733,6 +744,21 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
   }
 }
 
+// ============================================================
+// Extras 注册表
+// ============================================================
+
+/**
+ * 外部工具注册表。upgrade.js 遍历此表来安装/更新外部工具。
+ * 新增工具只需：1) 写 installXxx 函数  2) 加一行到此表
+ */
+export const EXTRAS_REGISTRY = {
+  'playwright-cli': {
+    label: '浏览器交互工具',
+    install: installPlaywrightCli,
+  },
+};
+
 // ============================================================
 // 主安装函数
 // ============================================================
@@ -846,9 +872,11 @@ export async function scaffold(config) {
     }
   }
 
-  // 10. Playwright CLI (optional)
+  // 10. Extras (external tools via registry)
+  const activeExtras = [];
   if (playwrightCli) {
-    console.log(chalk.blue('    浏览器交互工具:'));
+    activeExtras.push('playwright-cli');
+    console.log(chalk.blue(`    ${EXTRAS_REGISTRY['playwright-cli'].label}:`));
     await installPlaywrightCli(projectRoot, dryRun);
     console.log('');
   }
@@ -894,6 +922,7 @@ export async function scaffold(config) {
       team,
       aiCli,
       rulesPreset: rulesPresetName,
+      extras: activeExtras,
     });
     await writeManifest(projectRoot, manifest);
     console.log(chalk.green('      ✓ .prizmkit/manifest.json'));

package/src/upgrade.js

@@ -30,6 +30,7 @@ import {
   installGitignore,
   installProjectMemory,
   resolvePipelineFileList,
+  EXTRAS_REGISTRY,
 } from './scaffold.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -244,6 +245,13 @@ export async function runUpgrade(directory, options = {}) {
   // Resolve pipeline file list from source (for manifest diff)
   const newPipelineFiles = pipeline ? resolvePipelineFileList() : [];
 
+  // Resolve extras: merge old manifest extras + default extras for old manifests without the field
+  const extrasToInstall = [...new Set([
+    ...(oldManifest?.files?.extras || []),
+    // Old manifests without extras field: default to all registered extras
+    ...(!oldManifest?.files?.extras ? Object.keys(EXTRAS_REGISTRY) : []),
+  ])].filter(name => EXTRAS_REGISTRY[name]);  // only keep extras that still exist in registry
+
   // 4. Build new manifest and compute diff
   const newManifest = buildManifest({
     version: pkg.version,
@@ -256,6 +264,7 @@ export async function runUpgrade(directory, options = {}) {
     team,
     aiCli,
     rulesPreset,
+    extras: extrasToInstall,
   });
 
   // Preserve original installedAt
@@ -360,6 +369,17 @@ export async function runUpgrade(directory, options = {}) {
     console.log('');
   }
 
+  // Extras (external tools via registry)
+  if (extrasToInstall.length > 0) {
+    for (const extraName of extrasToInstall) {
+      const entry = EXTRAS_REGISTRY[extraName];
+      if (!entry) continue;
+      console.log(chalk.blue(`    ${entry.label}:`));
+      await entry.install(projectRoot, dryRun);
+      console.log('');
+    }
+  }
+
   // Git hook
   console.log(chalk.blue('    Git Hook:'));
   await installGitHook(projectRoot, dryRun);