brains-cli 0.1.0

package/.claude/skills/founder/SKILL.md

@@ -0,0 +1,316 @@
+You are building Brains.io — an npm CLI tool that is the "npm for AI agents." Users install, run, and publish AI-powered developer agents called "Brains" from their terminal. Each Brain is a specialized AI agent with a unique system prompt, personality, methodology, and expertise.
+Project Overview
+What it is: A globally installable npm CLI (npm install -g brains-cli) that lets developers:
+
+Browse a registry of AI agent "Brains" (like an app store in the terminal)
+Install Brains to ~/.brains/
+Run Brains interactively — they ask questions, then generate real code/projects/reviews
+Stack multiple Brains together for complex tasks
+Create and publish their own Brains
+
+Tech stack:
+
+Node.js CLI (CommonJS, Node 16+)
+Commander.js for command parsing
+Inquirer.js for interactive prompts
+Chalk 4.x, Ora 5.x, Boxen 5.x, cli-table3 for terminal UI
+Figlet + gradient-string for the banner
+Anthropic Claude API (@anthropic-ai/sdk) for AI generation
+Local file system (~/.brains/) for installed brain storage
+
+Project Structure
+brains-cli/
+├── bin/
+│   └── brains.js                  # CLI entry point, shebang, commander setup
+├── src/
+│   ├── registry.js                # Brain definitions (id, name, category, systemPrompt, etc.)
+│   ├── config.js                  # Global config management (~/.brains/config.json)
+│   ├── api.js                     # Claude API wrapper (streaming, conversation management)
+│   ├── utils/
+│   │   ├── ui.js                  # Terminal UI helpers (banner, tables, colors, spinners)
+│   │   ├── files.js               # File generation utilities (write project trees)
+│   │   └── template.js            # Template engine for code generation
+│   └── commands/
+│       ├── explore.js             # Browse brains with interactive TUI
+│       ├── install.js             # Download and save brain to ~/.brains/
+│       ├── run.js                 # Execute a brain (THE CORE — calls Claude API)
+│       ├── list.js                # Show installed brains
+│       ├── create.js              # Scaffold a new brain (interactive wizard)
+│       └── publish.js             # Publish brain to registry
+├── package.json
+├── README.md
+└── .env.example                   # ANTHROPIC_API_KEY=sk-ant-...
+Commands to Implement
+1. brains explore
+Interactive terminal browser for the brain registry.
+
+Shows a styled table of all available brains
+Filter by category: brains explore -c builder
+Search: brains explore -s "nextjs"
+Select a brain to see full details (description, capabilities, reviews, price)
+Option to install directly from explore view
+Categories: builder, role, reviewer, domain (each with its own color)
+
+2. brains install <brain-id>
+Downloads a brain and saves it locally.
+
+Validates brain exists in registry
+Shows price (or "Free")
+Animated installation progress (ora spinners)
+Saves brain config to ~/.brains/<brain-id>/brain.json
+Saves human-readable docs to ~/.brains/<brain-id>/BRAIN.md
+Tracks installation in ~/.brains/installed.json
+Prevents duplicate installs
+
+3. brains run <brain-id> ⭐ THIS IS THE CORE FEATURE
+This is where the magic happens. When a user runs a brain, the CLI:
+Step 1 — Checks installation. If not installed, offers to install.
+Step 2 — Loads the brain's system prompt from ~/.brains/<brain-id>/brain.json.
+Step 3 — Runs the brain's interview (defined questions from the brain config). Uses Inquirer.js to ask each question conversationally.
+Step 4 — Calls the Claude API with:
+
+The brain's system prompt as the system parameter
+The user's answers formatted as context
+For builder brains: instructions to generate a complete project
+For reviewer brains: the code/files to review (read from cwd)
+For role/domain brains: enter a conversational REPL loop
+
+Step 5 — Handles the response:
+
+Builder brains: Parse Claude's response, extract code blocks, write files to disk, show the project tree, give next-steps instructions
+Reviewer brains: Read files from cwd, send to Claude for review, display the formatted review report with severity levels (🔴🟡🟢📝)
+Role brains: Enter a REPL loop where the user can keep chatting with the brain, maintaining conversation history
+Domain brains: Same as role — conversational REPL with the domain expert
+
+Brain stacking: brains run mvp --with stripe supabase
+
+Load system prompts from all specified brains
+Merge them into a combined system prompt with clear sections
+Run as a single agent with combined expertise
+
+Claude API integration:
+javascriptconst Anthropic = require('@anthropic-ai/sdk');
+
+// Initialize (reads ANTHROPIC_API_KEY from env or ~/.brains/config.json)
+const client = new Anthropic();
+
+// Stream responses for real-time output
+const stream = await client.messages.stream({
+  model: 'claude-sonnet-4-20250514',
+  max_tokens: 8096,
+  system: brain.systemPrompt, // The brain's personality
+  messages: conversationHistory,
+});
+
+// Stream to terminal with nice formatting
+for await (const event of stream) {
+  if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+    process.stdout.write(event.delta.text);
+  }
+}
+4. brains list
+Shows installed brains in a formatted table with name, category, version, install date.
+5. brains create [name]
+Interactive wizard to create a new brain:
+
+Ask for name, description, category, stack, price
+Open $EDITOR for the system prompt
+Scaffold brain.json, BRAIN.md, README.md in a new directory
+Provide instructions for testing and publishing
+
+6. brains publish
+Reads brain.json from cwd, validates, and "publishes" (for now, just validates and shows success — real registry comes later).
+7. brains config
+Manage settings:
+
+brains config set api_key <key> — save Anthropic API key
+brains config set model <model> — set preferred model
+brains config get api_key — show current key (masked)
+
+Brain Registry
+Define these 11 brains in src/registry.js. Each brain MUST have:
+javascript{
+  id: 'resume',                    // Unique slug
+  name: 'Resume Builder',         // Display name
+  category: 'builder',            // builder | role | reviewer | domain
+  shortDesc: '...',               // One-liner for tables
+  description: '...',             // Full description
+  capabilities: ['...'],          // What it can do
+  stack: ['Next.js', '...'],      // Technologies
+  price: 0,                       // 0 = free
+  rating: 4.9,
+  installs: 24500,
+  tags: ['resume', '...'],
+  usage: 'brains run resume',     // Example command
+  systemPrompt: `...`,            // THE CORE — detailed system prompt
+  questions: [                    // Interview questions
+    { key: 'name', question: 'What is your name?' },
+  ],
+}
+Builder Brains (3):
+
+resume — FREE — Builds a complete Next.js resume/portfolio site. Asks about experience, skills, projects, theme preference. Generates full project with components, styles, SEO.
+mvp — $9.99 — Turns a product idea into a full-stack MVP. Asks about the idea, audience, features, auth needs. Generates Next.js + Prisma + auth + landing page + dashboard.
+landing — FREE — Generates high-converting landing pages. Asks about product, benefits, tone. Generates hero, features, social proof, pricing, FAQ sections.
+
+Role Brains (3):
+4. frontend — $4.99 — Senior frontend engineer. Thinks in components, a11y, performance. Conversational REPL mode.
+5. backend — $4.99 — Backend architect. Designs APIs, schemas, auth flows. Conversational REPL mode.
+6. architect — $9.99 — System architect. Creates Mermaid diagrams, ADRs, trade-off analysis. Conversational REPL mode.
+Reviewer Brains (2):
+7. reviewer — FREE — Deep code review. Reads files from cwd, outputs 🔴🟡🟢📝 categorized feedback.
+8. security — $4.99 — Security auditor. OWASP Top 10, auth audit, injection detection, dependency scanning.
+Domain Brains (3):
+9. nextjs — FREE — Next.js 14+ expert. App Router, RSC, caching, middleware. Conversational REPL.
+10. supabase — $4.99 — Supabase expert. RLS, auth, edge functions, real-time.
+11. stripe — $4.99 — Stripe payments expert. Checkout, subscriptions, webhooks, billing.
+System Prompt Guidelines
+Each brain's system prompt should be detailed and specific (200-500 words). Include:
+
+Identity: "You are the [Name] Brain. You are a [role] with [X] years of experience."
+Personality: How it communicates (direct, conversational, formal, etc.)
+Methodology: Step-by-step workflow it follows
+Principles: Core rules and preferences
+Output format: How it structures its responses
+Tech preferences: Specific technologies and patterns it favors
+
+The REPL Loop (for role/domain brains)
+After the initial context questions, role and domain brains enter a conversational loop:
+┌─────────────────────────────────────────────────────
+│  🧠 Frontend Engineer — role
+│  Stack: React, Next.js, TypeScript, Tailwind CSS
+└─────────────────────────────────────────────────────
+
+  You: Build me a data table component with sorting and pagination
+
+  [Frontend Engineer]: I'll design this as a composable component...
+  (streams Claude's response in real-time)
+
+  You: Can you add virtual scrolling for large datasets?
+
+  [Frontend Engineer]: Great idea. Here's how I'd approach that...
+
+  You: exit
+  
+  Session ended. Conversation saved to ~/.brains/sessions/frontend-1709...json
+Implementation:
+
+Use inquirer or readline for the input loop
+Maintain full conversation history in memory
+Send entire history with each API call
+Stream responses to terminal in real-time
+Save session transcript on exit
+Support exit, quit, clear (reset history), save commands
+
+Builder Brain File Generation
+When a builder brain generates a project, Claude's response will contain code blocks. The CLI should:
+
+Parse the response for code blocks with file paths (e.g., ````typescript:app/page.tsx`)
+Create the directory structure
+Write each file
+Show a tree view of what was generated
+Provide next-steps commands
+
+The system prompt for builder brains should instruct Claude to format output as:
+FILE: app/layout.tsx
+\`\`\`typescript
+// file contents here
+\`\`\`
+
+FILE: app/page.tsx
+\`\`\`typescript
+// file contents here
+\`\`\`
+Then the CLI parses this and writes the files.
+Reviewer Brain File Reading
+When running a reviewer brain:
+
+Scan the current directory for source files (respect .gitignore)
+Read file contents (limit to reasonable size — skip node_modules, .git, binaries)
+Send file contents to Claude with the reviewer system prompt
+Display the formatted review
+
+javascript// Pseudo-code for file collection
+const files = glob.sync('**/*.{ts,tsx,js,jsx,py,go,rs}', {
+  ignore: ['node_modules/**', '.git/**', 'dist/**', 'build/**'],
+  cwd: process.cwd(),
+});
+
+// Send to Claude
+const messages = [{
+  role: 'user',
+  content: `Review the following codebase:\n\n${files.map(f => 
+    `### ${f}\n\`\`\`\n${fs.readFileSync(f, 'utf-8')}\n\`\`\``
+  ).join('\n\n')}\n\nFocus: ${answers.focus || 'general review'}`
+}];
+Config Management
+Store config at ~/.brains/config.json:
+json{
+  "api_key": "sk-ant-...",
+  "model": "claude-sonnet-4-20250514",
+  "default_dir": ".",
+  "theme": "dark",
+  "telemetry": false
+}
+API key resolution order:
+
+ANTHROPIC_API_KEY environment variable
+~/.brains/config.json → api_key
+Prompt user to enter it (and offer to save)
+
+Terminal UI Design
+
+Banner: Figlet "brains.io" with gradient (purple → pink)
+Colors: Purple (#7B2FFF) for accents, Pink (#FF3366) for builders, Blue (#00AAFF) for reviewers, Green (#00CC88) for domain, White for text
+Spinners: ora with dots12 spinner, magenta color
+Tables: cli-table3 with dim borders, bold headers
+Success: Green checkmark ✓
+Error: Red cross ✗
+Info: Purple arrow →
+
+Error Handling
+
+If no API key is set when running brains run, prompt user to enter one
+If API call fails, show friendly error with retry option
+If brain is not found, suggest similar brains
+If network is unavailable, show offline message
+Rate limit handling with exponential backoff
+
+Testing the Build
+After building, I should be able to:
+bash# From the project root
+node bin/brains.js --help          # Shows all commands
+node bin/brains.js explore         # Interactive browser
+node bin/brains.js install resume  # Install a brain
+node bin/brains.js run resume      # Run it (needs API key)
+node bin/brains.js list            # See installed brains
+node bin/brains.js create          # Create a new brain
+Important Notes
+
+Use CommonJS (require), not ESM — chalk 4.x, ora 5.x, boxen 5.x are the last CommonJS versions
+All file operations should be sync for simplicity (this is a CLI, not a server)
+The Claude API streaming is the only async operation that matters
+Always gracefully handle Ctrl+C (clean up spinners, save state)
+Make the terminal output BEAUTIFUL — this is a product, not a script
+Every brain's system prompt should be thoughtful and detailed — these are the product
+Use process.env.ANTHROPIC_API_KEY or ~/.brains/config.json for the API key
+Default model should be claude-sonnet-4-20250514
+Add .env.example with ANTHROPIC_API_KEY=your-key-here
+
+What to Build Now
+Build the complete, working CLI. Start with:
+
+Project setup (package.json, bin entry, directory structure)
+UI utilities (banner, colors, tables, spinners)
+Brain registry (all 11 brains with full system prompts)
+Config management (API key, model preferences)
+Claude API wrapper (streaming, conversation management)
+All 6 commands (explore, install, run, list, create, publish)
+The config command for API key management
+File parser for builder brain output
+File reader for reviewer brains
+REPL loop for role/domain brains
+README.md
+.env.example
+
+Make it production-grade. Make it beautiful. Make it work.

package/README.md

@@ -0,0 +1,190 @@
+# 🧠 Brains.io
+
+> **Install the world's greatest brains.** AI-powered dev agents you can browse, install, and run from your terminal.
+
+Brains are intelligent, conversational AI agents that act as specialized team members. Unlike dumb templates or scaffolders, Brains **talk to you**, understand your context, and generate production-grade output tailored to your specific needs.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g brains-cli
+
+# Explore available brains
+brains explore
+
+# Install a brain
+brains install resume
+
+# Run it
+brains run resume
+```
+
+## What are Brains?
+
+A Brain is an AI agent with a specific personality, methodology, and expertise. Think of it as hiring a world-class specialist for any dev task — but they live in your terminal.
+
+### 🔨 Builder Brains — Generate entire projects
+
+| Brain | Description | Price |
+|-------|-------------|-------|
+| `resume` | Build a stunning developer resume/portfolio site | Free |
+| `mvp` | Turn a product idea into a full-stack MVP | $9.99 |
+| `landing` | Generate high-converting landing pages | Free |
+
+### 👤 Role Brains — Act as team members
+
+| Brain | Description | Price |
+|-------|-------------|-------|
+| `frontend` | Senior frontend engineer (React, Next.js, a11y) | $4.99 |
+| `backend` | Backend architect (APIs, databases, infra) | $4.99 |
+| `architect` | System design, diagrams, and technical decisions | $9.99 |
+
+### 🔍 Reviewer Brains — Analyze & improve code
+
+| Brain | Description | Price |
+|-------|-------------|-------|
+| `reviewer` | Deep, senior-level code review | Free |
+| `security` | Find vulnerabilities and harden your app | $4.99 |
+
+### ⚡ Domain Brains — Deep tech expertise
+
+| Brain | Description | Price |
+|-------|-------------|-------|
+| `nextjs` | Next.js 14+ expert (App Router, RSC, etc.) | Free |
+| `supabase` | Supabase expert (auth, RLS, edge functions) | $4.99 |
+| `stripe` | Payments, subscriptions, webhooks | $4.99 |
+
+## Commands
+
+### `brains explore`
+
+Browse and discover available Brains with an interactive terminal UI.
+
+```bash
+brains explore                    # Browse all
+brains explore -c builder        # Filter by category
+brains explore -s "nextjs"       # Search
+```
+
+### `brains install <brain>`
+
+Download and configure a Brain.
+
+```bash
+brains install resume             # Install resume builder
+brains install mvp                # Install MVP generator
+brains i reviewer                 # Short alias
+```
+
+### `brains run <brain>`
+
+Activate a Brain in conversational mode.
+
+```bash
+brains run resume                 # Start resume builder
+brains run reviewer               # Review current project
+brains run mvp --with stripe supabase  # Stack multiple brains
+```
+
+### `brains list`
+
+Show all installed Brains.
+
+```bash
+brains list                       # or: brains ls
+```
+
+### `brains create [name]`
+
+Author a new Brain from scratch.
+
+```bash
+brains create my-brain
+brains create --template builder  # Start from a template
+```
+
+### `brains publish`
+
+Publish your Brain to the Brains.io registry.
+
+```bash
+cd my-brain/
+brains publish                    # Public
+brains publish --private          # Private (team only)
+```
+
+## Brain Stacking
+
+Combine multiple Brains for complex tasks:
+
+```bash
+# Build an MVP with Stripe payments and Supabase backend
+brains run mvp --with stripe supabase
+
+# Review code with security focus
+brains run reviewer --with security
+```
+
+## Creating Your Own Brain
+
+Every Brain is defined by three files:
+
+```
+my-brain/
+├── brain.json      ← Configuration (name, category, capabilities, price)
+├── BRAIN.md        ← System prompt & documentation
+└── README.md       ← Public readme for the registry
+```
+
+The **system prompt** in `BRAIN.md` is the core of your Brain. It defines:
+- **Personality** — How the brain communicates
+- **Methodology** — Step-by-step workflow
+- **Principles** — Rules and best practices
+- **Output format** — How results are structured
+
+```bash
+# Scaffold a new brain
+brains create my-brain
+
+# Edit the system prompt
+$EDITOR my-brain/BRAIN.md
+
+# Test locally
+brains run my-brain
+
+# Publish to registry
+cd my-brain && brains publish
+```
+
+## Architecture
+
+```
+~/.brains/                        ← Global brains directory
+├── installed.json                ← Registry of installed brains
+├── resume/
+│   ├── brain.json                ← Brain config + system prompt
+│   └── BRAIN.md                  ← Human-readable docs
+├── reviewer/
+│   ├── brain.json
+│   └── BRAIN.md
+└── ...
+```
+
+## Pricing
+
+| Tier | Price | Includes |
+|------|-------|----------|
+| Free | $0 | 4 free brains (resume, landing, reviewer, nextjs) |
+| Pro | $20/mo | All brains + brain stacking + priority |
+| Enterprise | Custom | Private registry + team management |
+
+Brain creators set their own prices. Platform takes 20%.
+
+## Contributing
+
+Want to contribute a Brain to the registry? See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+MIT © Brains.io

package/bin/brains.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { program } = require('commander');
+const { version } = require('../package.json');
+const { explore } = require('../src/commands/explore');
+const { install } = require('../src/commands/install');
+const { run } = require('../src/commands/run');
+const { list } = require('../src/commands/list');
+const { create } = require('../src/commands/create');
+const { publish } = require('../src/commands/publish');
+const { showBanner } = require('../src/utils/ui');
+
+showBanner();
+
+program
+  .name('brains')
+  .description('🧠 Brains.io — AI-powered dev agents. Build, review, architect, and ship.')
+  .version(version, '-v, --version');
+
+// ─── Explore: Browse the Brain registry ───
+program
+  .command('explore')
+  .description('Browse and discover available Brains')
+  .option('-c, --category <category>', 'Filter by category (builder, role, reviewer, domain)')
+  .option('-s, --search <query>', 'Search brains by name or keyword')
+  .action(explore);
+
+// ─── Install: Download a Brain ───
+program
+  .command('install <brain>')
+  .alias('i')
+  .description('Install a Brain (e.g., brains install resume)')
+  .option('--global', 'Install globally for use in any project')
+  .action(install);
+
+// ─── Run: Execute a Brain ───
+program
+  .command('run <brain>')
+  .alias('r')
+  .description('Run an installed Brain in conversational mode')
+  .option('-w, --with <brains...>', 'Stack multiple brains together')
+  .option('-d, --dir <directory>', 'Target directory (default: current)')
+  .option('--no-interactive', 'Run without interactive prompts')
+  .action(run);
+
+// ─── List: Show installed Brains ───
+program
+  .command('list')
+  .alias('ls')
+  .description('List all installed Brains')
+  .action(list);
+
+// ─── Create: Author a new Brain ───
+program
+  .command('create [name]')
+  .description('Create a new Brain from scratch')
+  .option('-t, --template <template>', 'Start from a template (builder, role, reviewer, domain)')
+  .action(create);
+
+// ─── Publish: Share your Brain ───
+program
+  .command('publish')
+  .description('Publish your Brain to the Brains.io registry')
+  .option('--private', 'Publish as a private Brain')
+  .action(publish);
+
+program.parse(process.argv);
+
+// If no args, show help
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "brains-cli",
+  "version": "0.1.0",
+  "description": "🧠 Brains.io — Install AI-powered dev agents. Build, review, architect, and ship with one command.",
+  "main": "src/index.js",
+  "bin": {
+    "brains": "./bin/brains.js"
+  },
+  "scripts": {
+    "start": "node bin/brains.js",
+    "test": "node bin/brains.js --help"
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "brains",
+    "agents",
+    "claude",
+    "developer-tools",
+    "scaffolding",
+    "code-review",
+    "ai-agents"
+  ],
+  "author": "Brains.io",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "inquirer": "^8.2.6",
+    "ora": "^5.4.1",
+    "boxen": "^5.1.2",
+    "cli-table3": "^0.6.3",
+    "figlet": "^1.7.0",
+    "gradient-string": "^2.0.2"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brains-io/brains-cli"
+  }
+}