real-prototypes-skill 0.1.2 → 1.0.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/bin/cli.js

@@ -13,10 +13,54 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const https = require('https');
 
 const VERSION = require('../package.json').version;
 const SKILL_NAME = 'real-prototypes-skill';
 
+/**
+ * Check for newer version on npm and notify user
+ */
+function checkForUpdates() {
+  return new Promise((resolve) => {
+    const req = https.get(
+      `https://registry.npmjs.org/${SKILL_NAME}/latest`,
+      { timeout: 3000 },
+      (res) => {
+        let data = '';
+        res.on('data', chunk => data += chunk);
+        res.on('end', () => {
+          try {
+            const latest = JSON.parse(data).version;
+            if (latest && latest !== VERSION) {
+              const current = VERSION.split('.').map(Number);
+              const remote = latest.split('.').map(Number);
+
+              // Check if remote is newer
+              const isNewer = remote[0] > current[0] ||
+                (remote[0] === current[0] && remote[1] > current[1]) ||
+                (remote[0] === current[0] && remote[1] === current[1] && remote[2] > current[2]);
+
+              if (isNewer) {
+                console.log(`
+\x1b[33m╔═══════════════════════════════════════════════════════════╗
+║  UPDATE AVAILABLE: ${VERSION} → ${latest.padEnd(43)}║
+║                                                           ║
+║  Run: npx ${SKILL_NAME}@latest --force            ║
+╚═══════════════════════════════════════════════════════════╝\x1b[0m
+`);
+              }
+            }
+          } catch (e) { /* ignore parse errors */ }
+          resolve();
+        });
+      }
+    );
+    req.on('error', () => resolve());
+    req.on('timeout', () => { req.destroy(); resolve(); });
+  });
+}
+
 function log(message, type = 'info') {
   const styles = {
     info: '\x1b[36m→\x1b[0m',
@@ -171,6 +215,16 @@ function install(options) {
 
   log(`Skill installed to ${targetDir}`, 'success');
 
+  // 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');
@@ -227,7 +281,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
@@ -302,18 +357,25 @@ function parseArgs(args) {
 }
 
 // Main
-const args = process.argv.slice(2);
-const options = parseArgs(args);
-
-switch (options.command) {
-  case 'install':
-    install(options);
-    break;
-  case 'uninstall':
-    uninstall(options);
-    break;
-  case 'help':
-  default:
-    showHelp();
-    break;
+async function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  // Check for updates (non-blocking, 3s timeout)
+  await checkForUpdates();
+
+  switch (options.command) {
+    case 'install':
+      install(options);
+      break;
+    case 'uninstall':
+      uninstall(options);
+      break;
+    case 'help':
+    default:
+      showHelp();
+      break;
+  }
 }
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "real-prototypes-skill",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "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,6 +30,7 @@
     ".claude/skills/real-prototypes-skill/",
     ".claude/skills/agent-browser-skill/",
     ".env.example",
+    "CLAUDE.md.example",
     "README.md",
     "LICENSE"
   ],

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

@@ -1,259 +0,0 @@
-# Installation Guide
-
-Quick guide to install the Platform Prototype Skill in your Claude Code setup.
-
----
-
-## 🚀 Method 1: Global Installation (Recommended)
-
-Install the skill globally so it's available in all your Claude Code projects.
-
-### Step 1: Navigate to Claude Skills Directory
-
-```bash
-cd ~/.claude/skills
-```
-
-If the directory doesn't exist, create it:
-```bash
-mkdir -p ~/.claude/skills
-cd ~/.claude/skills
-```
-
-### Step 2: Clone This Repository
-
-```bash
-git clone https://github.com/kaidhar/real-prototypes-skill.git
-```
-
-### Step 3: Verify Installation
-
-```bash
-# List the skill directory
-ls -la real-prototypes-skill
-
-# You should see SKILL.md, README.md, cli.js, etc.
-```
-
-### Step 4: Restart Claude Code
-
-```bash
-# Exit Claude Code if running
-# Then restart it in any project
-cd ~/your-project
-claude-code
-```
-
-### Step 5: Test the Skill
-
-Tell Claude:
-```
-Use the real-prototypes-skill to capture design from amazon.in
-```
-
-Claude should recognize and invoke the skill!
-
----
-
-## 📁 Method 2: Project-Specific Installation
-
-Install the skill only for a specific project.
-
-### Step 1: Navigate to Your Project
-
-```bash
-cd your-project
-```
-
-### Step 2: Create Skills Directory
-
-```bash
-mkdir -p .claude/skills
-cd .claude/skills
-```
-
-### Step 3: Clone the Repository
-
-```bash
-git clone https://github.com/kaidhar/real-prototypes-skill.git
-```
-
-Or add as a submodule:
-```bash
-git submodule add https://github.com/kaidhar/real-prototypes-skill.git
-```
-
-### Step 4: Restart Claude Code in This Project
-
-```bash
-cd ../..  # Back to project root
-claude-code
-```
-
----
-
-## ✅ Verify Installation
-
-### Check if Skill is Loaded
-
-```bash
-# In Claude Code, type:
-/help
-```
-
-Look for `real-prototypes-skill` in the list of available skills.
-
-### Test Run
-
-Tell Claude:
-```
-I want to create a prototype that matches Amazon's design.
-Can you use the real-prototypes-skill?
-```
-
-If Claude responds that it's using the skill, you're all set! ✅
-
----
-
-## 🔧 Troubleshooting
-
-### "Skill not found"
-
-**Problem**: Claude doesn't recognize the skill.
-
-**Solution**:
-1. Check the installation path:
-   ```bash
-   ls ~/.claude/skills/real-prototypes-skill/SKILL.md
-   ```
-2. Ensure `SKILL.md` exists (this is what Claude reads)
-3. Restart Claude Code completely
-
-### "agent-browser-skill not found"
-
-**Problem**: The platform skill depends on `agent-browser-skill`.
-
-**Solution**: Install the browser automation skill:
-```bash
-cd ~/.claude/skills
-git clone https://github.com/anthropics/agent-browser-skill.git
-```
-
-### "Permission denied"
-
-**Problem**: Can't write to `~/.claude/skills/`.
-
-**Solution**: Create the directory with proper permissions:
-```bash
-mkdir -p ~/.claude/skills
-chmod 755 ~/.claude/skills
-```
-
-### "Git clone failed"
-
-**Problem**: Repository doesn't exist or network issue.
-
-**Solution**:
-1. Check if you're using the correct GitHub URL
-2. Try with HTTPS instead of SSH:
-   ```bash
-   git clone https://github.com/kaidhar/real-prototypes-skill.git
-   ```
-3. Check your network connection
-
----
-
-## 🔄 Updating the Skill
-
-### Global Installation Update
-
-```bash
-cd ~/.claude/skills/real-prototypes-skill
-git pull origin main
-```
-
-### Project-Specific Update
-
-```bash
-cd your-project/.claude/skills/real-prototypes-skill
-git pull origin main
-```
-
-### Submodule Update
-
-```bash
-cd your-project
-git submodule update --remote .claude/skills/real-prototypes-skill
-```
-
----
-
-## 🗑️ Uninstalling
-
-### Remove Global Installation
-
-```bash
-rm -rf ~/.claude/skills/real-prototypes-skill
-```
-
-### Remove Project-Specific Installation
-
-```bash
-cd your-project
-rm -rf .claude/skills/real-prototypes-skill
-```
-
-### Remove Submodule
-
-```bash
-cd your-project
-git submodule deinit .claude/skills/real-prototypes-skill
-git rm .claude/skills/real-prototypes-skill
-rm -rf .git/modules/.claude/skills/real-prototypes-skill
-```
-
----
-
-## 📦 Dependencies
-
-Make sure you have these installed:
-
-### Required
-- **Claude Code CLI** - [Install from claude.ai/code](https://claude.ai/code)
-- **Node.js 18+** - [Download from nodejs.org](https://nodejs.org/)
-- **npm or pnpm** - Comes with Node.js
-
-### Check Versions
-
-```bash
-# Check Claude Code
-claude --version
-
-# Check Node.js
-node --version
-
-# Check npm
-npm --version
-```
-
----
-
-## 🎓 Next Steps
-
-After installation:
-
-1. **Read the README** - `cat ~/.claude/skills/real-prototypes-skill/README.md`
-2. **Try the examples** - Check out the Amazon chatbot example
-3. **Build your first prototype** - Follow the usage guide in README.md
-
----
-
-## 💬 Getting Help
-
-- **GitHub Issues**: [Report a problem](https://github.com/kaidhar/real-prototypes-skill/issues)
-- **Discussions**: [Ask questions](https://github.com/kaidhar/real-prototypes-skill/discussions)
-- **Documentation**: [Read SKILL.md](./SKILL.md)
-
----
-
-Happy prototyping! 🎨