BrowserSkill

# MISSION: Scaffold "BrowserSkill" Production Architecture
You are an expert Senior Staff Software Architect and Full-Stack Engineer. Your mission is to scaffold and implement a production-grade, highly reliable, and modular codebase following the proven architecture of **BrowserSkill**.
---
## 1. PROJECT SPECIFICATIONS & BENCHMARK
- **Reference Architecture**: BrowserSkill
- **What It Does**: BrowserSkill, from Tencent, lets AI agents work inside the user's real, logged-in Chrome or Edge browser. A Rust bsk CLI/daemon and a TypeScript extension read pages, fill forms, capture screenshots and debug network requests in a visible Agent Window.
- **Domain & Category**: Browser Automation Bridge for AI Agents
- **Production Scale**: 6-20 people
- **Development Mode**: CLASSIC
- **Architectural Rationale**: The agent keeps the browser's real login state and the user can watch and take over, because the design pairs a small native Rust daemon (callable from any agent's shell) with a WXT extension, instead of running a separate headless browser. A shared protocol crate keeps both sides in sync.
- **Live Website Reference**: https://github.com/Tencent/BrowserSkill
- **Source Repository**: https://github.com/Tencent/BrowserSkill
---
## 2. PRODUCTION TECH STACK
- **Full Stack Array**: Rust, TypeScript, Tokio, React, Tailwind CSS, WXT, Vitest, pnpm, GitHub Actions
- **Primary Language(s)**: TypeScript, Rust, JavaScript, PowerShell
- **License of the reference repo**: MIT
- **Frontend**: React — React 19 UI for the Chrome/Edge extension popup and task views in apps/extension; WXT — Web-extension framework that builds, zips and runs the Chromium extension in dev; Tailwind CSS — Styling for the extension and the shared packages/ui component library (Tailwind 4); TypeScript — Language for the extension, the VOM page model, i18n and the DeepSeek Harness plugin
- **Backend & APIs**: Rust — The bsk CLI and background daemon (crates/bsk-cli) that agents call from the shell; Tokio — Async runtime for the daemon's WebSocket link to the extension and its local HTTP server; JSON-RPC — Wire protocol between CLI and extension, typed in crates/bsk-protocol with generated JSON Schemas
- **Infrastructure & deploy**: pnpm — Workspace manager for apps/* and packages/* alongside the Cargo workspace; Vitest — Unit tests for the extension, VOM, i18n and the DSH plugin; GitHub Actions — CI plus separate release workflows for the CLI, the extension and the DSH plugin
- **Tooling, testing & ops**: DeepSeek Harness plugin — packages/dsh-plugin-browserskill exposes browser_* tools natively to DeepSeek Harness agents
---
## 3. KEY ARCHITECTURAL DECISIONS (audited from https://github.com/Tencent/BrowserSkill @ 147727a)
1. **A native Rust daemon plus a browser extension, not a headless browser**: crates/bsk-cli ships a single bsk binary that runs a background daemon; the WXT extension in apps/extension connects to it over WebSocket and acts inside the user's real, logged-in Chrome or Edge profile, so agents reuse existing sessions instead of launching Playwright or Puppeteer.
2. **Protocol types live in their own crate with generated JSON Schemas**: crates/bsk-protocol defines the JSON-RPC frames and tool payloads with serde and schemars; the root cli:build script runs its dump-schema binary first so the TypeScript side is built against the same schema.
3. **Agent-agnostic via a shell CLI plus installable skill bundles**: Any shell-capable agent drives the browser through bsk commands, and bsk install-skill writes the matching skill for each harness; scripts/check-skill-bundles.mjs and check-crate-skill.mjs keep the bundled skill text in sync with the crate.
4. **Tasks run in a separate visible Agent Window**: Per the README, tasks open in their own visible window and only borrow an existing tab when told to, so the user can keep working and step in for logins or verification. Recoverable session starts and browser profiles are covered in docs/.
5. **Polyglot monorepo with one version across Cargo and npm**: Cargo.toml pins workspace version 0.3.1, which the extension and DSH plugin package.json files also use. scripts/release.mjs and render-version-json.mjs drive the three release workflows (release-cli, release-extension, release-dsh-plugin).
---
## 4. NON-NEGOTIABLE ARCHITECTURAL GUARDRAILS
1. **Monorepo & Modular Separation**:
   - Structure as a Turborepo monorepo with strict package boundaries:
     - `apps/web`: Application UI, routing, layouts, and server endpoints.
     - `packages/ui`: Shared design tokens, CSS variables, and Radix UI primitive components.
     - `packages/db`: Database schemas, client singleton, declarative migrations, and seed scripts.
     - `packages/config`: Shared TypeScript, ESLint, and build configurations.
2. **Strict Type Safety & Zero `any` Policy**:
   - Enable `strict: true`, `noImplicitAny: true`, and `strictNullChecks: true`.
   - Validate ALL external inputs, API request bodies, and query parameters with **Zod** schemas before execution.
3. **Frontend & Rendering Guidelines**:
   - Utilize Vite 6 with TanStack Router for fully type-safe routing. Manage server state and caching via TanStack Query v5 with optimistic UI updates.
4. **Design System & Aesthetics**:
   - Keep every color, radius, shadow and font in a single token file (CSS variables) and consume tokens everywhere; never hardcode hex values in components.
   - Prefer crisp 1px borders and one subtle shadow scale over blurry default shadows. Pair one sans-serif for body/headings with one monospace for tags, badges, metrics, and code.
5. **Data Layer & Reliability**:
   - Write declarative schema definitions with foreign keys, composite indexes on queried filters, and automated timestamp triggers.
   - Use connection pooling and prepared statements for serverless database execution.
---
## 5. STEP-BY-STEP SCAFFOLDING ROADMAP
- **Phase 1: Workspace & Root Config**: Initialize package manager, monorepo configuration (`turbo.json`, `tsconfig.base.json`, `package.json`).
- **Phase 2: Database Schema & Client**: Set up the data layer: client, connection pool, models, and migration scripts.
- **Phase 3: Design Tokens & UI Primitives**: Build accessible `Button`, `Input`, `Card`, `Badge`, and layout wrappers inside `packages/ui`.
- **Phase 4: Core Application Routes & Handlers**: Implement primary authentication, user session handling, and application routes.
- **Phase 5: Quality Assurance & Build Verification**: Run `tsc --noEmit`, ESLint, Prettier, and smoke test suites to ensure zero compilation or runtime errors.
---
## 6. EXECUTION INSTRUCTIONS
1. Review all specifications, architectural guardrails, and stack choices above.
2. Present the full monorepo directory tree structure.
3. Systematically generate the complete, production-ready codebase according to the 5-phase roadmap above — starting with the root workspace setup, followed by the database schema, UI design system package, and full-stack application routes until the repository is fully scaffolded and ready to run.