prizmkit 1.1.53 → 1.1.55

package/bundled/skills/app-planner/references/rules/mobile/template.md

@@ -0,0 +1,175 @@
+# Mobile Rules — {{ project_name }}
+
+> This document was generated by the `mobile-rules` skill on {{ generated_at }}
+> Audience: All mobile developers + all AI coding assistants on this project
+>
+> **Usage**:
+> 1. All AI coding assistants must read this file before generating or modifying any mobile code
+> 2. This document takes precedence over "general best practices" in AI training data
+> 3. Code conflicting with this document must not be committed
+
+---
+
+## 0. TL;DR — Key Decisions at a Glance
+
+| Dimension | Decision |
+|-----------|----------|
+| Platform | {{ platform }} |
+| Min OS Version | {{ min_os_version }} |
+| Architecture Pattern | {{ architecture }} |
+| UI Framework | {{ ui_framework }} |
+| Navigation | {{ navigation }} |
+| State Management | {{ state_management }} |
+| Networking | {{ networking }} |
+| Local Persistence | {{ persistence }} |
+| Push Notifications | {{ push_notifications }} |
+| Background Tasks | {{ background_tasks }} |
+| Permissions Strategy | {{ permissions_strategy }} |
+| Test Coverage | {{ test_coverage }} |
+| Unit Test Framework | {{ unit_test_framework }} |
+| E2E Test Framework | {{ e2e_framework }} |
+| Distribution | {{ distribution }} |
+| Performance Target | {{ performance_target }} |
+| Accessibility Target | {{ a11y_target }} |
+
+---
+
+## 1. Project Structure
+
+{{ FIXED_RULES_STRUCTURE }}
+
+{{ tech_stack_rules }}
+
+---
+
+## 2. UI Development
+
+{{ FIXED_RULES_UI }}
+
+{{ ui_rules }}
+
+---
+
+## 3. Navigation & Deep Linking
+
+{{ FIXED_RULES_NAVIGATION }}
+
+{{ navigation_rules }}
+
+---
+
+## 4. State Management
+
+{{ FIXED_RULES_STATE }}
+
+{{ state_rules }}
+
+---
+
+## 5. Networking
+
+{{ FIXED_RULES_NETWORKING }}
+
+{{ networking_rules }}
+
+---
+
+## 6. Data Persistence
+
+{{ FIXED_RULES_PERSISTENCE }}
+
+{{ persistence_rules }}
+
+---
+
+## 7. Platform Features
+
+{{ FIXED_RULES_PLATFORM_FEATURES }}
+
+{{ platform_features_rules }}
+
+---
+
+## 8. Performance
+
+{{ FIXED_RULES_PERFORMANCE }}
+
+{{ performance_rules }}
+
+---
+
+## 9. Accessibility
+
+{{ FIXED_RULES_A11Y }}
+
+{{ a11y_rules }}
+
+---
+
+## 10. Security
+
+{{ FIXED_RULES_SECURITY }}
+
+---
+
+## 11. Testing
+
+{{ FIXED_RULES_TEST }}
+
+{{ test_rules }}
+
+---
+
+## 12. App Distribution
+
+{{ FIXED_RULES_DISTRIBUTION }}
+
+{{ distribution_rules }}
+
+---
+
+## 13. AI Vibecoding Behavior Constraints
+
+### 13.1 Baseline Constraints (project-agnostic, always active)
+
+{{ FIXED_RULES_AI_BASE }}
+
+### 13.2 Project-Specific Hard Constraints
+
+- **Adding dependencies**: {{ ai_dependency_rule }}
+- **Modifying shared code**: {{ ai_breaking_change_rule }}
+- **Platform-specific code**: {{ ai_platform_rule }}
+
+### 13.3 Mandatory Pre-Actions (before every code generation)
+
+AI must complete the following in order before generating or modifying any mobile code:
+
+1. Read this file (`mobile-rules.md`)
+2. Read existing files in the target feature's directory to confirm whether similar functionality already exists
+3. If modifying shared widgets/components/services, search all callers and assess platform impact
+4. If modifying navigation routes or deep link schemes, assess all entry points
+
+---
+
+## 14. Architecture
+
+{{ arch_rules }}
+
+---
+
+## Appendix A: Deny List (Quick Reference)
+
+> This appendix is auto-generated by AI in Phase 4 by extracting all forbidden entries from each section.
+
+{{ deny_list_summary }}
+
+## Appendix B: Recommended Libraries & Tools
+
+> This appendix is auto-generated by AI in Phase 4 to recommend the supporting ecosystem based on platform and framework choices.
+
+{{ recommended_libs }}
+
+---
+
+**Version**: v1.0 — Generated on {{ generated_at }}
+**Next review recommended**: before tech stack changes or platform migration

package/bundled/skills/prizm-kit/SKILL.md

@@ -18,7 +18,7 @@ Each task begins by reading context at two levels:
 
 **Application level** (read every session):
 - `.prizmkit/prizm-docs/root.prizm` — L0 project architecture index (modules, tech stack, conventions)
-- `.prizmkit/plans/project-brief.md` — user's product vision checklist (generated by app-planner)
+- `.prizmkit/plans/project-brief.md` — user's product vision checklist (generated during project initialization)
 - `.prizmkit/config.json` — tech stack config, deploy strategy
 
 **Task level** (read for the specific task):

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

@@ -90,9 +90,22 @@ BROWNFIELD WORKFLOW (existing project):
 
    **IMPORTANT**: Not all projects have all fields. A pure backend API will have no `frontend_framework` or `frontend_styling`. A library may have no database. Only record what is actually detected — never generate empty or placeholder values.
 
-**Phase 4.5: Infrastructure Quick Scan**
+**Phase 4.5: Layer Detection**
 
-Detect database and deployment signals, then ask 1-2 brief questions. This phase is **optional** — users can skip and configure later via `app-planner` or `/prizmkit-deploy`.
+After tech stack detection, determine which development layers exist in the project — these are code domains that may benefit from custom dev rules (frontend, backend, database, mobile). This is a quick detection step, not an interactive Q&A — rules can be configured later based on detected layers.
+
+1. Read `${SKILL_DIR}/references/rules/layer-detection.md` for the detection signal table and AI judgment guidelines.
+2. Scan the project against each signal, and supplement with your own judgment — the signal table is a guide, not exhaustive. If you see clear evidence of a layer not covered by the table, include it. If a signal matches but context is misleading, downgrade or ignore it:
+   - **frontend**: React/Vue/Angular/etc. in dependencies, or `src/components/` with UI files
+   - **backend**: Express/FastAPI/Gin/etc. in dependencies, or `routes/`/`controllers/` with server code
+   - **database**: Prisma/TypeORM/SQLAlchemy/etc. in dependencies, or `migrations/`/`prisma/` directory
+   - **mobile**: `pubspec.yaml` (Flutter), `react-native` in package.json, or simultaneous `ios/`+`android/` directories
+3. For mobile signals — if ambiguous (e.g., monorepo with web + ios/android dirs), use `AskUserQuestion` to confirm: "Mobile platform signals detected. Is this project a mobile app?" Options: "Yes, this is a mobile app" / "No, these are for another purpose".
+4. Assemble `detected_layers` array (e.g., `["frontend", "backend", "database"]`). If no layers detected (library/CLI project), array is empty.
+
+**Phase 4.6: Infrastructure Quick Scan**
+
+Detect database and deployment signals, then ask 1-2 brief questions. This phase is **optional** — users can skip and configure later.
 
 - **BROWNFIELD**: Auto-detect infrastructure signals from existing files, then ask 1-2 brief questions (pre-filled with detection results)
 - **GREENFIELD**: No auto-detection possible — ask the 2 brief questions directly (database need and deployment target)
@@ -136,7 +149,7 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
      #### Deployment
      - **Target**: [platform name or "undecided"]
      ```
-     → This is intentionally minimal (Quick Scan). Full conventions and deployment details will be added by app-planner or prizmkit-deploy later.
+     → This is intentionally minimal (Quick Scan). Full conventions and deployment details can be added later.
    - If user selects "Skip — decide later" for BOTH topics: write deferred marker instead:
      ```markdown
      ### Infrastructure
@@ -148,6 +161,20 @@ Detect database and deployment signals, then ask 1-2 brief questions. This phase
      <!-- database: deferred -->
      ```
 
+**Phase 4.7: Rules Quick Entry**
+
+After Infrastructure Quick Scan completes, check if `detected_layers` is non-empty (from Phase 4.5). If layers were detected, offer a lightweight entry point for rules configuration.
+
+1. If `detected_layers` is empty (library/CLI project) → skip this phase entirely, proceed to Phase 5.
+2. If layers detected, use `AskUserQuestion`:
+
+   **Question**: "Detected **{list detected layers}** code. Would you like to set up custom development rules for AI to follow? This helps AI generate code that matches your conventions."
+   - **Configure later (Recommended)** — Record layers and configure rules later
+   - **Skip entirely** — no custom rules, AI uses general best practices
+
+3. If user picked "Skip entirely" → clear `detected_layers` to empty array, proceed to Phase 5.
+4. If user picked "Configure later" → keep `detected_layers`, proceed to Phase 5. The layers will be written to config.json in Phase 6.
+
 **Phase 5: Prizm Documentation Generation**
 Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structure from Phase 4:
   - Create `.prizmkit/prizm-docs/` directory structure mirroring the source tree (sub-module dirs become subdirectories under `.prizmkit/prizm-docs/<top-level>/`)
@@ -166,6 +193,12 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
 6b. Write detected tech stack to `.prizmkit/config.json`:
    → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
+6c. Write `detected_layers` to `.prizmkit/config.json` (alongside `tech_stack`):
+   - Field: `"detected_layers": ["frontend", "backend"]` — the layers from Phase 4.5
+   - If user chose "Skip entirely" in Phase 4.7, write empty array `[]`
+   - For greenfield projects (Phase 4.5 skipped): write `[]` — no code layers to configure rules for yet; user can configure rules later when code exists
+   - This field indicates which development layers exist in the project and can be used to determine available rule configuration options.
+
 **Phase 7: Project Brief Generation**
 
 If action for project brief == skip, output "Project brief: skipped (exists)" and proceed to Phase 8 (Report).
@@ -225,11 +258,12 @@ Saved to: `.prizmkit/config.json` → `tech_stack` field
 Next step: "Use `/prizmkit-plan` to start your first feature"
 
 GREENFIELD WORKFLOW (new project):
-- Skip Phase 4 (no code to scan) — but ask the user about their intended tech stack:
+- Skip Phase 4 code scanning (no code to scan — Phase 4.5 Layer Detection and Phase 4.7 Rules Quick Entry are skipped; no layers to detect yet):
+  - Ask the user about their intended tech stack:
   - "What language/framework will you use?" (e.g. React + Node.js, Python + FastAPI, etc.)
   - Record answers in `config.json` `tech_stack` with `"_auto_detected": false` (user-provided, not auto-detected)
   - If user is unsure, skip tech_stack — it can be populated later on re-init after code exists
-- Phase 4.5: Run Infrastructure Quick Scan — in greenfield mode, no auto-detection is possible, so only ask the 2 brief questions (database need and deployment target). If user is unsure, skip — these can be configured later via `app-planner` or `/prizmkit-deploy`.
+- Phase 4.6: Run Infrastructure Quick Scan — in greenfield mode, no auto-detection is possible, so only ask the 2 brief questions (database need and deployment target). If user is unsure, skip — these can be configured later.
 - Phase 5: Create minimal `.prizmkit/prizm-docs/` with just `root.prizm` skeleton (populate TECH_STACK from user answers if provided)
 - Phase 7: Generate project brief (greenfield flow — ask user about project goals, see Phase 7 above)
 - Phases 6, 8: Same as brownfield (Phase 8 Report recommends `/prizmkit-plan` for first feature)
@@ -259,11 +293,18 @@ Tech stack detected:
   Bundler:      Vite
   Project type: fullstack
 
+Layer Detection:
+  Detected layers: frontend, backend, database (from dependency + directory signals)
+  → Stored for config.json
+
 Infrastructure Quick Scan:
   Database: PostgreSQL (Prisma) — detected from dependencies
   Deployment: Vercel — detected from vercel.json
   → Written to CLAUDE.md ### Infrastructure
 
+Rules Quick Entry:
+  Matched layers: frontend (React), backend (Express.js), database (Prisma) → keeping default rules
+
 Modules discovered:
   src/routes/     → .prizmkit/prizm-docs/routes.prizm (12 files)
   src/models/     → .prizmkit/prizm-docs/models.prizm (8 files)
@@ -274,7 +315,7 @@ Project brief: inferred from codebase → confirmed by user
   → .prizmkit/plans/project-brief.md
 
 Generated: root.prizm + 4 L1 docs + changelog.prizm
-Saved: .prizmkit/config.json (tech_stack recorded)
+Saved: .prizmkit/config.json (tech_stack + detected_layers recorded)
 
 Next: Use /prizmkit-plan to start your first feature
 ```

package/bundled/skills/prizmkit-init/references/config-schema.md

@@ -7,10 +7,11 @@ Handles re-init without losing user edits:
 - Read existing `config.json` if present
 - If `tech_stack` field exists AND `_auto_detected` is `false` or absent:
   → **SKIP** — user has manually configured tech stack, preserve their settings
+- Always update `detected_layers` with new layer detection results on every init run — layer detection is based on code that exists, not user preference. This ensures greenfield projects that later gain code get their `detected_layers` populated correctly. Note: the final value written is still determined by Phase 6c (e.g., if user chose "Skip entirely" in Phase 4.7, Phase 6c writes `[]` regardless of detection results).
 - If `tech_stack` field exists AND `_auto_detected` is `true`:
-  → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result)
+  → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result). Overwrite `detected_layers` with new layer detection results.
 - If `tech_stack` field does NOT exist:
-  → **WRITE** full detected tech stack with `"_auto_detected": true`
+  → **WRITE** full detected tech stack with `"_auto_detected": true`, and write `detected_layers` from layer detection
 - Only include fields that were actually detected (no empty/null values)
 
 ## Field Definitions
@@ -21,6 +22,7 @@ Handles re-init without losing user edits:
 | `platform` | string | `"codebuddy"` \| `"claude"` \| `"both"` |
 | `tech_stack` | object | Detected or user-provided tech stack |
 | `tech_stack._auto_detected` | boolean | `true` if auto-detected, `false` if user-provided |
+| `detected_layers` | string[] | Development layers detected in the project. Written by prizmkit-init Phase 4.5. Used to determine available rule configuration options. Values: `frontend` / `backend` / `database` / `mobile`. Empty array when no layers detected or user skipped rules. Always updated on every init run based on fresh code detection — not gated by `_auto_detected` (see Merge Strategy above). |
 
 ## Examples
 
@@ -29,6 +31,7 @@ Fullstack project:
 {
   "adoption_mode": "passive",
   "platform": "claude",
+  "detected_layers": ["frontend", "backend", "database"],
   "tech_stack": {
     "language": "TypeScript",
     "runtime": "Node.js 20",
@@ -59,6 +62,7 @@ Pure Python backend:
     "testing": "pytest",
     "project_type": "backend",
     "_auto_detected": true
-  }
+  },
+  "detected_layers": ["backend", "database"]
 }
 ```

package/bundled/skills/prizmkit-init/references/rules/layer-detection.md

@@ -0,0 +1,41 @@
+# Layer Detection — Signal Reference Table
+
+> Load this file in Phase 4.5 to determine which development layers exist in the project.
+> A "layer" means a distinct code domain that may benefit from custom dev rules.
+
+## Detection Signals
+
+> **This table is a reference guide, not an exhaustive checklist.** The signals below cover common frameworks and patterns, but the list cannot be complete — new frameworks emerge, projects use unconventional setups, and context matters more than any single string match. In addition to matching against these signals, **apply your own judgment**: if you see files, directories, or dependencies that clearly indicate a development layer (even if not listed below), include it. If a signal matches but context suggests it's misleading (e.g., a dependency present but not actually used as the primary tech), downgrade or ignore it. The goal is to accurately reflect what the project contains, not to mechanically match strings.
+
+| Layer | Signal Source | Detection Rule |
+|-------|--------------|----------------|
+| **frontend** | `package.json` dependencies | Contains `react`, `vue`, `angular`, `next`, `nuxt`, `svelte`, `solid-js`, `preact`, `remix`, `astro`, `qwik` |
+| **frontend** | `package.json` devDependencies | Contains `vite`, `webpack`, `parcel`, `turbo` |
+| **frontend** | Directory | `src/components/`, `pages/`, `app/` with `.tsx`/`.jsx`/`.vue` files |
+| **backend** | `package.json` dependencies | Contains `express`, `fastify`, `koa`, `hono`, `nest`, `next` (API routes) |
+| **backend** | `requirements.txt` / `pyproject.toml` | Contains `fastapi`, `django`, `flask`, `sanic`, `litestar` |
+| **backend** | `go.mod` | Contains `gin-gonic`, `echo`, `fiber`, `chi` |
+| **backend** | `pom.xml` / `build.gradle` | Contains `spring-boot`, `quarkus`, `micronaut`, `ktor` |
+| **backend** | Directory | `routes/`, `controllers/`, `handlers/`, `api/`, `internal/` with server code |
+| **database** | `package.json` dependencies | Contains `prisma`, `typeorm`, `sequelize`, `mongoose`, `knex`, `drizzle-orm`, `kysely` |
+| **database** | `requirements.txt` / `pyproject.toml` | Contains `sqlalchemy`, `django` (ORM), `pony`, `peewee`, `tortoise-orm` |
+| **database** | `go.mod` | Contains `gorm`, `sqlx`, `sqlc`, `ent`, `bun` |
+| **database** | Directory | `migrations/`, `prisma/`, `alembic/`, `db/`, `schema/` |
+| **database** | Environment | `.env*` contains `DATABASE_URL`, `DB_HOST`, `DB_NAME`, `MONGO_URI` |
+| **mobile** | File | `pubspec.yaml` exists (Flutter) |
+| **mobile** | `package.json` dependencies | Contains `react-native`, `expo` |
+| **mobile** | Directory | Both `ios/*.xcodeproj` + `android/build.gradle` exist simultaneously |
+
+## Mobile Confirmation
+
+When mobile signals are detected but ambiguous (e.g., a monorepo with web + mobile), use `AskUserQuestion`:
+
+> "Mobile platform signals detected (ios/ + android/ directories). Is this project
+> a mobile app, or are these directories for another purpose?"
+> Options: "Yes, this is a mobile app" / "No, these are for another purpose"
+
+## Output
+
+After detection (signals + your own judgment), assemble `detected_layers` array (e.g., `["frontend", "backend", "database"]`).
+Store in memory for Phase 6 config.json writing.
+If no layers detected (library/CLI project), array is empty.

package/package.json

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

package/src/index.js

@@ -69,6 +69,7 @@ export async function runScaffold(directory, options) {
       pipeline: options.pipeline !== false,
       playwrightCli: options.playwrightCli !== false,
       openCli: options.openCli !== false,
+      openCliAutoDownload: options.openCliAutoDownload !== false,
       rules: options.rules || 'recommended',
       aiCli: options.aiCli || '',
       externalSkills: options.externalSkills ? options.externalSkills.split(',').map(s => s.trim()).filter(Boolean) : [],
@@ -198,6 +199,14 @@ export async function runScaffold(directory, options) {
       default: true,
     });
 
+    let openCliAutoDownload = true;
+    if (openCli) {
+      openCliAutoDownload = await confirm({
+        message: '检测到 Chrome Browser Bridge 扩展缺失时，自动下载扩展包？\n  (仍需手动在 Chrome 中加载，但可省去下载解压步骤)',
+        default: true,
+      });
+    }
+
     // 5. Rules 预设
     const rulesPreset = await select({
       message: '安装 AI 行为规则 (rules):',
@@ -248,6 +257,7 @@ export async function runScaffold(directory, options) {
       pipeline,
       playwrightCli,
       openCli,
+      openCliAutoDownload,
       rules: rulesPreset,
       aiCli: aiCli || '',
       externalSkills: selectedExternalSkills,

package/src/scaffold.js

@@ -778,6 +778,27 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
     console.log(chalk.yellow(`      ⚠ Skills install skipped: ${e.message}`));
     console.log(chalk.yellow('      ⚠ Run manually: playwright-cli install --skills'));
   }
+
+  // Install Playwright browser binary (needed for E2E testing via prizmkit-test)
+  try {
+    const cacheDir = process.env.PLAYWRIGHT_BROWSERS_PATH
+      || path.join(process.env.HOME || process.env.USERPROFILE || '.',
+        process.platform === 'darwin' ? 'Library/Caches/ms-playwright'
+        : process.platform === 'win32' ? 'AppData/Local/ms-playwright'
+        : '.cache/ms-playwright');
+    const hasChromium = fs.pathExistsSync(cacheDir)
+      && fs.readdirSync(cacheDir).some(d => d.startsWith('chromium-'));
+    if (hasChromium) {
+      console.log(chalk.green('      ✓ Playwright Chromium (already installed)'));
+    } else {
+      console.log(chalk.blue('      ⏳ Installing Playwright Chromium (needed for E2E testing)...'));
+      execSync('npx --yes playwright install chromium', { stdio: 'pipe', timeout: 180000 });
+      console.log(chalk.green('      ✓ Playwright Chromium installed'));
+    }
+  } catch (e) {
+    console.log(chalk.yellow(`      ⚠ Playwright browser install skipped: ${e.message}`));
+    console.log(chalk.yellow('      ⚠ Run manually: npx playwright install chromium'));
+  }
 }
 
 // ============================================================
@@ -788,7 +809,7 @@ export async function installPlaywrightCli(projectRoot, dryRun) {
  * 安装 opencli（全局 npm 包）
  * 用于浏览器交互验证，复用 Chrome 已登录会话（OAuth/SSO/第三方集成）
  */
-export async function installOpenCli(projectRoot, dryRun) {
+export async function installOpenCli(projectRoot, dryRun, autoDownload = true) {
   if (dryRun) {
     console.log(chalk.gray('      [dry-run] @jackwener/opencli (global install)'));
     return;
@@ -811,10 +832,105 @@ export async function installOpenCli(projectRoot, dryRun) {
     }
   }
 
-  // Note: opencli requires Chrome + Browser Bridge extension for browser-backed commands.
-  // The extension must be installed manually — see: https://github.com/jackwener/opencli
-  console.log(chalk.gray('      ℹ OpenCLI requires Chrome + Browser Bridge extension for browser commands'));
-  console.log(chalk.gray('      ℹ Run "opencli doctor" to verify connectivity'));
+  // Verify opencli connectivity — Chrome Browser Bridge extension is a manual install
+  try {
+    const doctorOutput = execSync('opencli doctor 2>&1', { stdio: 'pipe', timeout: 15000 }).toString();
+    if (doctorOutput.includes('[MISSING] Extension') || doctorOutput.includes('[FAIL] Connectivity')) {
+      console.log(chalk.yellow('      ⚠ Chrome Browser Bridge extension is NOT connected'));
+
+      if (autoDownload) {
+        await downloadOpenCliExtension(projectRoot);
+      } else {
+        printOpenCliManualSteps();
+      }
+    } else {
+      console.log(chalk.green('      ✓ opencli connectivity verified'));
+    }
+  } catch {
+    // doctor command itself failed — already warned about install issues
+  }
+}
+
+// ============================================================
+// OpenCLI Extension 下载/指引
+// ============================================================
+
+/**
+ * 从 GitHub releases 下载并解压 opencli Chrome 扩展。
+ * 省去用户手动下载解压步骤，但仍需在 Chrome 中手动加载。
+ */
+async function downloadOpenCliExtension(projectRoot) {
+  const extDir = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.opencli', 'extension');
+
+  // Check if already downloaded
+  const manifestPath = path.join(extDir, 'manifest.json');
+  if (fs.pathExistsSync(manifestPath)) {
+    console.log(chalk.green(`      ✓ Extension already downloaded at ${extDir}`));
+    printOpenCliLoadSteps(extDir);
+    return;
+  }
+
+  try {
+    console.log(chalk.blue('      ⏳ Fetching latest extension release info...'));
+    const releaseJson = execSync(
+      'curl -sL https://api.github.com/repos/jackwener/OpenCLI/releases/latest',
+      { stdio: 'pipe', timeout: 30000 }
+    ).toString();
+    const release = JSON.parse(releaseJson);
+    const extAsset = release.assets?.find(a => a.name?.startsWith('opencli-extension-') && a.name?.endsWith('.zip'));
+
+    if (!extAsset) {
+      console.log(chalk.yellow('      ⚠ Could not find extension asset in latest release'));
+      printOpenCliManualSteps();
+      return;
+    }
+
+    console.log(chalk.blue(`      ⏳ Downloading ${extAsset.name}...`));
+    const tmpZip = path.join(extDir, '..', '.opencli-ext-tmp.zip');
+    await fs.ensureDir(path.dirname(tmpZip));
+    execSync(`curl -sL "${extAsset.browser_download_url}" -o "${tmpZip}"`, { stdio: 'pipe', timeout: 60000 });
+
+    // Extract (use unzip on macOS/Linux, tar on Windows fallback)
+    console.log(chalk.blue(`      ⏳ Extracting to ${extDir}...`));
+    await fs.ensureDir(extDir);
+    execSync(`unzip -o "${tmpZip}" -d "${extDir}"`, { stdio: 'pipe', timeout: 30000 });
+    await fs.remove(tmpZip);
+
+    console.log(chalk.green(`      ✓ Extension extracted to ${extDir}`));
+    printOpenCliLoadSteps(extDir);
+  } catch (e) {
+    console.log(chalk.yellow(`      ⚠ Extension download failed: ${e.message}`));
+    printOpenCliManualSteps();
+  }
+}
+
+/**
+ * 显示手动安装步骤（兜底路径）。
+ */
+function printOpenCliManualSteps() {
+  console.log(chalk.cyan('      ┌─────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('      │  To enable opencli browser control:                         │'));
+  console.log(chalk.cyan('      │  1. Download extension from:                                │'));
+  console.log(chalk.cyan('      │     https://github.com/jackwener/opencli/releases           │'));
+  console.log(chalk.cyan('      │  2. Unzip the extension file                                │'));
+  console.log(chalk.cyan('      │  3. Open chrome://extensions/ → Enable Developer Mode       │'));
+  console.log(chalk.cyan('      │  4. Click "Load unpacked" → select the extension folder     │'));
+  console.log(chalk.cyan('      │  5. Run "opencli doctor" to verify connectivity             │'));
+  console.log(chalk.cyan('      └─────────────────────────────────────────────────────────────┘'));
+}
+
+/**
+ * 显示加载已解压扩展的指引（已自动下载解压后）。
+ */
+function printOpenCliLoadSteps(extDir) {
+  console.log(chalk.yellow('      ⚠ Browser commands will NOT work until the extension is loaded in Chrome'));
+  console.log(chalk.cyan('      ┌─────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('      │  To complete setup:                                         │'));
+  console.log(chalk.cyan(`      │  1. Open chrome://extensions/ → Enable Developer Mode        │`));
+  console.log(chalk.cyan(`      │  2. Click "Load unpacked" → select:                          │`));
+  console.log(chalk.cyan(`      │     ${extDir}`));
+  console.log(chalk.cyan('      │  3. Run "opencli doctor" to verify connectivity             │'));
+  console.log(chalk.cyan('      └─────────────────────────────────────────────────────────────┘'));
 }
 
 // ============================================================
@@ -852,11 +968,12 @@ export const EXTRAS_REGISTRY = {
  * @param {string[]} [config.externalSkills] - 要安装的外部 skill 名称列表
  * @param {boolean} [config.playwrightCli] - 是否安装 playwright-cli
  * @param {boolean} [config.openCli] - 是否安装 opencli
+ * @param {boolean} [config.openCliAutoDownload] - opencli 扩展缺失时是否自动下载
  * @param {string} config.projectRoot - 目标项目根目录
  * @param {boolean} config.dryRun - 是否为预览模式
  */
 export async function scaffold(config) {
-  const { platform, skills, team, pipeline, rules, aiCli, externalSkills, playwrightCli, openCli, projectRoot, dryRun } = config;
+  const { platform, skills, team, pipeline, rules, aiCli, externalSkills, playwrightCli, openCli, openCliAutoDownload, projectRoot, dryRun } = config;
   const platforms = platform === 'both' ? ['codebuddy', 'claude'] : [platform];
 
   if (dryRun) {
@@ -961,7 +1078,7 @@ export async function scaffold(config) {
   if (openCli) {
     activeExtras.push('opencli');
     console.log(chalk.blue(`    ${EXTRAS_REGISTRY['opencli'].label}:`));
-    await installOpenCli(projectRoot, dryRun);
+    await installOpenCli(projectRoot, dryRun, openCliAutoDownload);
     console.log('');
   }