real-prototypes-skill 0.1.3 → 1.0.2

package/.claude/skills/agent-browser-skill/SKILL.md

@@ -6,6 +6,23 @@ allowed-tools: Bash(agent-browser:*)
 
 # Browser Automation with agent-browser
 
+## Installation
+
+`agent-browser` is a **Vercel Labs npm package** for headless browser automation.
+
+```bash
+# Install globally
+npm install -g agent-browser
+
+# Download Chromium (required after npm install)
+agent-browser install
+
+# Verify installation
+agent-browser --version
+```
+
+**Repository:** https://github.com/vercel-labs/agent-browser
+
 ## Quick start
 
 ```bash

package/.claude/skills/real-prototypes-skill/SKILL.md

@@ -38,6 +38,38 @@ Enterprise-grade tool for capturing web platforms and generating pixel-perfect p
 
 ---
 
+## Prerequisites
+
+### Required: agent-browser
+This skill requires **agent-browser** for browser automation.
+
+`agent-browser` is a **Vercel Labs npm package** for headless browser automation.
+
+**Installation:**
+```bash
+# Install globally
+npm install -g agent-browser
+
+# Download Chromium (required after npm install)
+agent-browser install
+```
+
+**Verify installation:**
+```bash
+agent-browser --version
+```
+
+**Note:** The `npx real-prototypes-skill` installer will attempt to install agent-browser automatically.
+
+### Alternative: Manual Capture
+If you can't install `agent-browser`, you can still use this skill by:
+1. Manually taking screenshots and saving to `references/screenshots/`
+2. Manually saving HTML to `references/html/`
+3. Running `node cli.js extract-tokens` to generate design tokens from HTML
+4. Then using `generate`, `plan`, and other commands
+
+---
+
 ## 🏢 ENTERPRISE PIPELINE - MANDATORY FOR ALL PROTOTYPES
 
 **This pipeline MUST be followed. Validation gates will BLOCK generation if prerequisites are missing.**

package/.claude/skills/real-prototypes-skill/cli.js

@@ -16,6 +16,41 @@ const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 
+// Check for required dependencies
+function checkDependencies() {
+  const required = ['jsdom'];
+  const missing = [];
+
+  for (const dep of required) {
+    try {
+      require.resolve(dep);
+    } catch (e) {
+      missing.push(dep);
+    }
+  }
+
+  if (missing.length > 0) {
+    console.log(`
+\x1b[31m════════════════════════════════════════════════════════════\x1b[0m
+\x1b[31m  MISSING DEPENDENCIES\x1b[0m
+\x1b[31m════════════════════════════════════════════════════════════\x1b[0m
+
+The following required packages are not installed:
+  ${missing.join(', ')}
+
+\x1b[1mTo fix, run:\x1b[0m
+  cd ${__dirname} && npm install
+
+\x1b[1mOr reinstall the skill:\x1b[0m
+  npx real-prototypes-skill@latest --force
+`);
+    process.exit(1);
+  }
+}
+
+// Run dependency check before anything else
+checkDependencies();
+
 const SKILL_DIR = __dirname;
 const PROJECTS_DIR = path.resolve(SKILL_DIR, '../../../projects');
 const VERSION = '1.4.0';

package/.claude/skills/real-prototypes-skill/examples/CLAUDE.md.example

@@ -4,6 +4,22 @@ Copy this to your project's CLAUDE.md and fill in your platform details.
 
 ---
 
+## ⚠️ IMPORTANT: This Skill Extends EXISTING Platforms
+
+This skill is for **adding features to existing platforms**, NOT creating new designs.
+
+**Before generating any code:**
+1. You MUST have an existing platform to capture
+2. Run `capture` to get screenshots, HTML, and design tokens
+3. Only then can you generate prototype code
+
+**The CLI will BLOCK you if:**
+- You try to create a new project without `--force-create`
+- You try to generate code without captures
+- You try to generate a plan without captures
+
+---
+
 ## Platform Credentials
 
 ```
@@ -45,29 +61,33 @@ VIEWPORT_HEIGHT=1080
 WAIT_AFTER_LOAD=2000
 ```
 
-## Advanced Settings (Optional)
+## Workflow
 
-```
-# Maximum wait timeout (milliseconds)
-MAX_WAIT_TIMEOUT=10000
+```bash
+# 1. Create a new project (requires --force-create)
+node cli.js new --project my-app --force-create
+
+# 2. Capture the existing platform
+node cli.js capture --project my-app --url https://your-platform.com
+
+# 3. Check for existing prototype (if any)
+node cli.js detect --project my-app
 
-# Retry settings
-MAX_RETRIES=3
-TIMEOUT_RETRIES=2
-RETRY_DELAY_BASE=1000
+# 4. Generate implementation plan
+node cli.js plan --project my-app --feature "Add chatbot widget"
 
-# Validation thresholds
-MIN_SCREENSHOT_SIZE=102400
-MIN_HTML_SIZE=10240
-MIN_PAGE_HEIGHT=500
+# 5. Generate prototype guidance (shows paths and colors)
+node cli.js generate --project my-app
 
-# Exclude URL patterns from capture (comma-separated)
-# EXCLUDE_PATTERNS=/logout,/signout,/delete,/admin
+# 6. Validate colors after implementation
+node cli.js validate-colors --project my-app
 ```
 
 ## Usage Notes
 
-- The skill will read these values when running the capture phase
+- The skill will read credentials when running the capture phase
 - Credentials are only used locally for browser automation
 - Never commit this file to version control with real credentials
-- Add CLAUDE.md to your .gitignore
+- Add CLAUDE.md to your .gitignore if it contains credentials
+- ALL prototype files must be created in `projects/<project>/prototype/`
+- Use ONLY colors from `design-tokens.json` - no Tailwind defaults

package/CLAUDE.md.example

@@ -0,0 +1,93 @@
+# Real Prototypes - Example CLAUDE.md Configuration
+
+Copy this to your project's CLAUDE.md and fill in your platform details.
+
+---
+
+## ⚠️ IMPORTANT: This Skill Extends EXISTING Platforms
+
+This skill is for **adding features to existing platforms**, NOT creating new designs.
+
+**Before generating any code:**
+1. You MUST have an existing platform to capture
+2. Run `capture` to get screenshots, HTML, and design tokens
+3. Only then can you generate prototype code
+
+**The CLI will BLOCK you if:**
+- You try to create a new project without `--force-create`
+- You try to generate code without captures
+- You try to generate a plan without captures
+
+---
+
+## Platform Credentials
+
+```
+# Your platform's base URL (no trailing slash)
+PLATFORM_URL=https://app.example.com
+
+# Login credentials (if the platform requires authentication)
+PLATFORM_EMAIL=your-email@example.com
+PLATFORM_PASSWORD=your-secure-password
+```
+
+## Capture Settings
+
+```
+# Pages to capture
+# Option 1: Specify pages manually (comma-separated paths)
+PAGES_TO_CAPTURE=/dashboard,/settings,/profile,/users
+
+# Option 2: Auto-discover all pages
+# PAGES_TO_CAPTURE=auto
+
+# Option 3: Disable auto-capture (only capture specified pages)
+# PAGES_TO_CAPTURE=off
+
+# Capture mode
+# "full"   = capture all discovered pages up to MAX_PAGES
+# "manual" = only capture pages listed in PAGES_TO_CAPTURE
+CAPTURE_MODE=manual
+
+# Maximum pages to capture in auto/full mode
+MAX_PAGES=50
+
+# Viewport dimensions (pixels)
+VIEWPORT_WIDTH=1920
+VIEWPORT_HEIGHT=1080
+
+# Wait time after page load before capturing (milliseconds)
+# Increase this if pages have slow-loading content or animations
+WAIT_AFTER_LOAD=2000
+```
+
+## Workflow
+
+```bash
+# 1. Create a new project (requires --force-create)
+node cli.js new --project my-app --force-create
+
+# 2. Capture the existing platform
+node cli.js capture --project my-app --url https://your-platform.com
+
+# 3. Check for existing prototype (if any)
+node cli.js detect --project my-app
+
+# 4. Generate implementation plan
+node cli.js plan --project my-app --feature "Add chatbot widget"
+
+# 5. Generate prototype guidance (shows paths and colors)
+node cli.js generate --project my-app
+
+# 6. Validate colors after implementation
+node cli.js validate-colors --project my-app
+```
+
+## Usage Notes
+
+- The skill will read credentials when running the capture phase
+- Credentials are only used locally for browser automation
+- Never commit this file to version control with real credentials
+- Add CLAUDE.md to your .gitignore if it contains credentials
+- ALL prototype files must be created in `projects/<project>/prototype/`
+- Use ONLY colors from `design-tokens.json` - no Tailwind defaults

package/README.md

@@ -117,18 +117,32 @@ design. Include payment selection and order summary.
 
 ### Required
 
-- **Claude Code CLI** (v0.5.0+)
+- **agent-browser** - Vercel Labs browser automation package
   ```bash
-  # Install from https://claude.ai/code
-  npm install -g @anthropic-ai/claude-code
+  # Install globally
+  npm install -g agent-browser
+
+  # Download Chromium (required after npm install)
+  agent-browser install
+
+  # Verify installation
+  agent-browser --version
   ```
 
+  **Note:** The `npx real-prototypes-skill` installer will attempt to install agent-browser automatically.
+
 - **Node.js 18+**
   ```bash
   node --version  # Should be v18.0.0 or higher
   ```
 
-- **agent-browser-skill** (installed automatically with npx)
+### If You Can't Install agent-browser
+
+You can still use this skill with **manual capture**:
+1. Take screenshots manually and save to `references/screenshots/`
+2. Save HTML files to `references/html/`
+3. Run `node cli.js extract-tokens` to generate design tokens
+4. Then use `generate`, `plan`, and other commands
 
 ### Optional (Enhances Features)
 
@@ -377,12 +391,48 @@ npm run dev
 
 ## Troubleshooting
 
-### "agent-browser-skill not found"
+### "agent-browser not found"
+
+`agent-browser` is a **Vercel Labs npm package** that needs to be installed separately.
 
-The npx installer should install this automatically. If not:
+**Install agent-browser:**
 ```bash
-cd ~/.claude/skills
-git clone https://github.com/anthropics/agent-browser-skill.git
+# Install globally
+npm install -g agent-browser
+
+# Download Chromium (required after npm install)
+agent-browser install
+
+# Verify installation
+agent-browser --version
+```
+
+**Alternative - Manual capture workflow:**
+```bash
+# 1. Take screenshots manually, save to:
+projects/<name>/references/screenshots/
+
+# 2. Save HTML files to:
+projects/<name>/references/html/
+
+# 3. Extract design tokens from HTML:
+node cli.js extract-tokens --project <name>
+
+# 4. Continue with generate/plan commands
+node cli.js generate --project <name>
+```
+
+### "Missing dependencies (jsdom, etc.)"
+
+The skill requires dependencies to be installed:
+```bash
+cd .claude/skills/real-prototypes-skill
+npm install
+```
+
+Or reinstall the skill:
+```bash
+npx real-prototypes-skill@latest --force
 ```
 
 ### "Colors don't match the captured design"

package/bin/cli.js

@@ -215,6 +215,71 @@ function install(options) {
 
   log(`Skill installed to ${targetDir}`, 'success');
 
+  // Install dependencies in the skill directory
+  const skillPackageJson = {
+    "name": "real-prototypes-skill-deps",
+    "private": true,
+    "dependencies": {
+      "jsdom": "^27.4.0",
+      "@babel/parser": "^7.29.0",
+      "@babel/traverse": "^7.29.0",
+      "@babel/generator": "^7.29.0",
+      "class-variance-authority": "^0.7.1",
+      "clsx": "^2.1.1",
+      "tailwind-merge": "^3.4.0"
+    }
+  };
+
+  const skillPkgPath = path.join(targetDir, 'package.json');
+  fs.writeFileSync(skillPkgPath, JSON.stringify(skillPackageJson, null, 2));
+  log('Installing skill dependencies...', 'info');
+
+  try {
+    const { execSync } = require('child_process');
+    execSync('npm install --production', {
+      cwd: targetDir,
+      stdio: 'pipe'
+    });
+    log('Dependencies installed', 'success');
+  } catch (e) {
+    log('Warning: Could not auto-install dependencies', 'warning');
+    log(`Run manually: cd ${targetDir} && npm install`, 'info');
+  }
+
+  // Install agent-browser globally (required for browser automation)
+  log('Installing agent-browser (Vercel Labs browser automation)...', 'info');
+  try {
+    const { execSync } = require('child_process');
+    // Check if already installed
+    try {
+      execSync('agent-browser --version', { stdio: 'pipe' });
+      log('agent-browser already installed', 'success');
+    } catch {
+      // Not installed, install it
+      execSync('npm install -g agent-browser', { stdio: 'pipe' });
+      log('agent-browser installed globally', 'success');
+
+      // Download Chromium browser
+      log('Downloading Chromium for agent-browser...', 'info');
+      execSync('agent-browser install', { stdio: 'pipe' });
+      log('Chromium downloaded', 'success');
+    }
+  } catch (e) {
+    log('Warning: Could not install agent-browser automatically', 'warning');
+    log('Install manually: npm install -g agent-browser && agent-browser install', 'info');
+    log('Without agent-browser, you can still use manual capture mode', 'info');
+  }
+
+  // Copy CLAUDE.md.example to current directory if local install
+  if (!options.global) {
+    const exampleSource = path.join(path.dirname(__dirname), 'CLAUDE.md.example');
+    const exampleTarget = path.join(process.cwd(), 'CLAUDE.md.example');
+    if (fs.existsSync(exampleSource) && !fs.existsSync(exampleTarget)) {
+      fs.copyFileSync(exampleSource, exampleTarget);
+      log('CLAUDE.md.example copied to project root', 'success');
+    }
+  }
+
   // Also copy the agent-browser-skill if it exists and not already present
   const agentBrowserSource = path.join(path.dirname(skillSource), 'agent-browser-skill');
   const agentBrowserTarget = path.join(targetBase, 'agent-browser-skill');
@@ -271,7 +336,8 @@ function install(options) {
   ${targetDir}/QUICKSTART.md
 
 \x1b[1mExample Config:\x1b[0m
-  See .claude/skills/real-prototypes-skill/examples/CLAUDE.md.example for a complete configuration template.
+  See CLAUDE.md.example in the package root for a complete configuration template.
+  Or copy from: ${path.join(path.dirname(__dirname), 'CLAUDE.md.example')}
 
 \x1b[1mNeed Help?\x1b[0m
   https://github.com/kaidhar/real-prototypes-skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "real-prototypes-skill",
-  "version": "0.1.3",
+  "version": "1.0.2",
   "description": "Capture any web platform and generate pixel-perfect prototypes that match its design. A Claude Code skill for rapid feature prototyping.",
   "keywords": [
     "claude-code",
@@ -30,10 +30,14 @@
     ".claude/skills/real-prototypes-skill/",
     ".claude/skills/agent-browser-skill/",
     ".env.example",
+    "CLAUDE.md.example",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "release:patch": "npm version patch && npm publish && git push && git push --tags",
+    "release:minor": "npm version minor && npm publish && git push && git push --tags",
+    "release:major": "npm version major && npm publish && git push && git push --tags",
     "test:visual": "node scripts/visual-regression-test.js",
     "test:visual:ci": "node scripts/visual-regression-test.js --ci",
     "test:components": "node scripts/test-components.js --all",
@@ -47,6 +51,14 @@
     "playwright": "^1.58.0",
     "pngjs": "^7.0.0"
   },
+  "peerDependencies": {
+    "agent-browser": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "agent-browser": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@babel/generator": "^7.29.0",
     "@babel/parser": "^7.29.0",