ralphblaster-agent 0.1.1

package/src/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "ralph",
+  "version": "1.0.0",
+  "description": "Ralph PRD converter skill - converts markdown PRDs to structured JSON for autonomous agent execution",
+  "author": {
+    "name": "Wildfront LLC",
+    "email": "support@wildfront.io"
+  }
+}

package/src/claude-plugin/README.md

@@ -0,0 +1,42 @@
+# Ralph Plugin for Claude Code
+
+This plugin provides the `/ralph` skill for converting markdown PRDs into structured JSON format for the Ralph autonomous agent system.
+
+## What it does
+
+The `/ralph` skill:
+- Converts Product Requirements Documents (PRDs) from markdown to JSON
+- Structures features into appropriately-sized user stories
+- Orders stories by dependency (database → backend → UI)
+- Ensures acceptance criteria are verifiable
+- Generates branch names in kebab-case format
+
+## Installation
+
+This plugin is automatically installed when you install the `ralph blaster` npm package:
+
+```bash
+npm install -g ralphblaster
+```
+
+The plugin will be installed to: `~/.claude/plugins/local/ralph/`
+
+## Usage
+
+Use the `/ralph` skill in Claude Code:
+
+```bash
+claude /ralph < your-prd.md
+```
+
+Or pipe PRD content directly:
+
+```bash
+cat prd.md | claude /ralph
+```
+
+The skill will generate a `prd.json` file in the current directory.
+
+## License
+
+MIT

package/src/claude-plugin/skills/ralph/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: ralphblaster
+description: "Convert PRDs to prd.json format for the RalphBlasterBlaster autonomous agent system. Use when you have an existing PRD and need to convert it to RalphBlasterBlaster's JSON format. Triggers on: convert this prd, turn this into ralphblaster format, create prd.json from this, ralphblaster json."
+---
+
+# RalphBlasterBlaster PRD Converter
+
+Converts existing PRDs to the prd.json format that RalphBlasterBlaster uses for autonomous execution.
+
+---
+
+## The Job
+
+Take a PRD (markdown file or text) and convert it to `prd.json` format.
+
+**CRITICAL: You MUST use the Write tool to create the prd.json file.** The user will specify the exact file path where you should write the file. Do not just output the JSON - you must actually create the file using the Write tool.
+
+---
+
+## Output Format
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralphblaster/[feature-name-kebab-case]",
+  "description": "[Feature description from PRD title/intro]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Criterion 1",
+        "Criterion 2",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+---
+
+## Story Size: The Number One Rule
+
+**Each story must be completable in ONE RalphBlaster iteration (one context window).**
+
+RalphBlaster spawns a fresh Amp instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.
+
+### Right-sized stories:
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+- Add a filter dropdown to a list
+
+### Too big (split these):
+- "Build the entire dashboard" - Split into: schema, queries, UI components, filters
+- "Add authentication" - Split into: schema, middleware, login UI, session handling
+- "Refactor the API" - Split into one story per endpoint or pattern
+
+**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.
+
+---
+
+## Story Ordering: Dependencies First
+
+Stories execute in priority order. Earlier stories must not depend on later ones.
+
+**Correct order:**
+1. Schema/database changes (migrations)
+2. Server actions / backend logic
+3. UI components that use the backend
+4. Dashboard/summary views that aggregate data
+
+**Wrong order:**
+1. UI component (depends on schema that does not exist yet)
+2. Schema change
+
+---
+
+## Acceptance Criteria: Must Be Verifiable
+
+Each criterion must be something RalphBlaster can CHECK, not something vague.
+
+### Good criteria (verifiable):
+- "Add `status` column to tasks table with default 'pending'"
+- "Filter dropdown has options: All, Active, Completed"
+- "Clicking delete shows confirmation dialog"
+- "Typecheck passes"
+- "Tests pass"
+
+### Bad criteria (vague):
+- "Works correctly"
+- "User can do X easily"
+- "Good UX"
+- "Handles edge cases"
+
+### Always include as final criterion:
+```
+"Typecheck passes"
+```
+
+For stories with testable logic, also include:
+```
+"Tests pass"
+```
+
+### For stories that change UI, also include:
+```
+"Verify in browser using dev-browser skill"
+```
+
+Frontend stories are NOT complete until visually verified. RalphBlaster will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.
+
+---
+
+## Conversion Rules
+
+1. **Each user story becomes one JSON entry**
+2. **IDs**: Sequential (US-001, US-002, etc.)
+3. **Priority**: Based on dependency order, then document order
+4. **All stories**: `passes: false` and empty `notes`
+5. **branchName**: Derive from feature name, kebab-case, prefixed with `ralphblaster/`
+6. **Always add**: "Typecheck passes" to every story's acceptance criteria
+
+---
+
+## Splitting Large PRDs
+
+If a PRD has big features, split them:
+
+**Original:**
+> "Add user notification system"
+
+**Split into:**
+1. US-001: Add notifications table to database
+2. US-002: Create notification service for sending notifications
+3. US-003: Add notification bell icon to header
+4. US-004: Create notification dropdown panel
+5. US-005: Add mark-as-read functionality
+6. US-006: Add notification preferences page
+
+Each is one focused change that can be completed and verified independently.
+
+---
+
+## Example
+
+**Input PRD:**
+```markdown
+# Task Status Feature
+
+Add ability to mark tasks with different statuses.
+
+## Requirements
+- Toggle between pending/in-progress/done on task list
+- Filter list by status
+- Show status badge on each task
+- Persist status in database
+```
+
+**Output prd.json:**
+```json
+{
+  "project": "TaskApp",
+  "branchName": "ralphblaster/task-status",
+  "description": "Task Status Feature - Track task progress with status indicators",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add status field to tasks table",
+      "description": "As a developer, I need to store task status in the database.",
+      "acceptanceCriteria": [
+        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
+        "Generate and run migration successfully",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    },
+    {
+      "id": "US-002",
+      "title": "Display status badge on task cards",
+      "description": "As a user, I want to see task status at a glance.",
+      "acceptanceCriteria": [
+        "Each task card shows colored status badge",
+        "Badge colors: gray=pending, blue=in_progress, green=done",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": ""
+    },
+    {
+      "id": "US-003",
+      "title": "Add status toggle to task list rows",
+      "description": "As a user, I want to change task status directly from the list.",
+      "acceptanceCriteria": [
+        "Each row has status dropdown or toggle",
+        "Changing status saves immediately",
+        "UI updates without page refresh",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": false,
+      "notes": ""
+    },
+    {
+      "id": "US-004",
+      "title": "Filter tasks by status",
+      "description": "As a user, I want to filter the list to see only certain statuses.",
+      "acceptanceCriteria": [
+        "Filter dropdown: All | Pending | In Progress | Done",
+        "Filter persists in URL params",
+        "Typecheck passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+---
+
+## Archiving Previous Runs
+
+**Before writing a new prd.json, check if there is an existing one from a different feature:**
+
+1. Read the current `prd.json` if it exists
+2. Check if `branchName` differs from the new feature's branch name
+3. If different AND `progress.txt` has content beyond the header:
+   - Create archive folder: `archive/YYYY-MM-DD-feature-name/`
+   - Copy current `prd.json` and `progress.txt` to archive
+   - Reset `progress.txt` with fresh header
+
+**The ralph.sh script handles this automatically** when you run it, but if you are manually updating prd.json between runs, archive first.
+
+---
+
+## Checklist Before Saving
+
+Before writing prd.json, verify:
+
+- [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first)
+- [ ] Each story is completable in one iteration (small enough)
+- [ ] Stories are ordered by dependency (schema to backend to UI)
+- [ ] Every story has "Typecheck passes" as criterion
+- [ ] UI stories have "Verify in browser using dev-browser skill" as criterion
+- [ ] Acceptance criteria are verifiable (not vague)
+- [ ] No story depends on a later story

package/src/commands/add-project.js

@@ -0,0 +1,257 @@
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const ApiClient = require('../api-client');
+const logger = require('../logger');
+
+/**
+ * AddProject Command
+ * Registers the current directory as a RalphBlaster project via API
+ */
+class AddProjectCommand {
+  constructor() {
+    this.cwd = process.cwd();
+    this.apiClient = new ApiClient();
+  }
+
+  /**
+   * Run the add-project command
+   */
+  async run() {
+    try {
+      logger.info('Registering project with RalphBlaster...');
+
+      // Detect project name
+      const projectName = await this.detectProjectName();
+      logger.debug(`Detected project name: ${projectName}`);
+
+      // Create project via API
+      const project = await this.createProject(this.cwd, projectName);
+
+      // Display success message
+      this.displaySuccess(project);
+
+      process.exit(0);
+    } catch (error) {
+      this.handleError(error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Detect project name from various sources
+   * Priority: 1. Git remote, 2. package.json, 3. Directory name
+   */
+  async detectProjectName() {
+    // Try git remote first
+    try {
+      const gitRemoteName = this.getGitRemoteName();
+      if (gitRemoteName) {
+        logger.debug('Using project name from Git remote');
+        return gitRemoteName;
+      }
+    } catch (error) {
+      logger.debug('Could not detect Git remote name:', error.message);
+    }
+
+    // Try package.json
+    try {
+      const packageJsonName = this.getPackageJsonName();
+      if (packageJsonName) {
+        logger.debug('Using project name from package.json');
+        return packageJsonName;
+      }
+    } catch (error) {
+      logger.debug('Could not read package.json:', error.message);
+    }
+
+    // Fallback to directory name
+    logger.debug('Using directory name as project name');
+    return this.getDirectoryName();
+  }
+
+  /**
+   * Get project name from Git remote URL
+   * Example: https://github.com/user/repo.git -> "repo"
+   */
+  getGitRemoteName() {
+    try {
+      const remote = execSync('git config --get remote.origin.url', {
+        cwd: this.cwd,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+
+      if (!remote) {
+        return null;
+      }
+
+      // Extract repo name from URL
+      // Handles: https://github.com/user/repo.git, git@github.com:user/repo.git
+      const match = remote.match(/\/([^\/]+?)(\.git)?$/);
+      return match ? match[1] : null;
+    } catch (error) {
+      // Git not initialized or no remote configured
+      return null;
+    }
+  }
+
+  /**
+   * Get project name from package.json
+   */
+  getPackageJsonName() {
+    const packageJsonPath = path.join(this.cwd, 'package.json');
+
+    if (!fs.existsSync(packageJsonPath)) {
+      return null;
+    }
+
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.name || null;
+  }
+
+  /**
+   * Get project name from directory name
+   */
+  getDirectoryName() {
+    return path.basename(this.cwd);
+  }
+
+  /**
+   * Create project via API
+   */
+  async createProject(systemPath, name) {
+    try {
+      logger.info(`Creating project: ${name}`);
+
+      const response = await this.apiClient.requestWithFallback('post', '/projects', {
+        system_path: systemPath,
+        name: name
+      });
+
+      if (response.data && response.data.success) {
+        return response.data.project;
+      }
+
+      throw new Error('Unexpected response format from API');
+    } catch (error) {
+      // Re-throw with more context
+      if (error.response) {
+        const status = error.response.status;
+        const errorMessage = error.response.data?.error || error.message;
+
+        if (status === 401) {
+          throw new Error('Invalid API token. Please run "ralphblaster init" first.');
+        } else if (status === 403) {
+          throw new Error('API token lacks "rb_agent" permission. Please generate a new agent token.');
+        } else if (status === 422) {
+          throw new Error(`Validation error: ${errorMessage}`);
+        } else {
+          throw new Error(`API error (${status}): ${errorMessage}`);
+        }
+      } else if (error.request) {
+        throw new Error(`Could not connect to RalphBlaster API at ${this.apiClient.client.defaults.baseURL}`);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  /**
+   * Display success message
+   */
+  displaySuccess(project) {
+    const iconEmoji = this.getIconEmoji(project.icon);
+
+    logger.info('Project registered successfully!', {
+      name: project.name,
+      path: project.system_path,
+      icon: iconEmoji,
+      color: this.formatColorName(project.color)
+    });
+
+    console.log('');
+    console.log('Next step:');
+    console.log('  Start the agent: ralphblaster');
+    console.log('');
+    console.log('The agent will poll for tasks assigned to this project.');
+  }
+
+  /**
+   * Convert icon name to emoji
+   */
+  getIconEmoji(icon) {
+    // If it's already an emoji, return it
+    if (icon && icon.match(/[\u{1F300}-\u{1F9FF}]/u)) {
+      return icon;
+    }
+
+    // Map Heroicon names to emojis
+    const iconMap = {
+      'folder': '📁',
+      'rocket': '🚀',
+      'beaker': '🧪',
+      'globe-alt': '🌍',
+      'device-phone-mobile': '📱',
+      'chart-bar': '📊',
+      'code': '💻',
+      'academic-cap': '🎓',
+      'light-bulb': '💡',
+      'megaphone': '📣',
+      'briefcase': '💼',
+      'cube': '🎲',
+      'puzzle-piece': '🧩',
+      'sparkles': '✨',
+      'fire': '🔥',
+      'star': '⭐',
+      'heart': '❤️',
+      'bolt': '⚡',
+      'shield': '🛡️',
+      'cloud': '☁️'
+    };
+
+    return iconMap[icon] || '📁';
+  }
+
+  /**
+   * Format color name for display
+   */
+  formatColorName(color) {
+    if (!color) return 'Blue';
+
+    // If it's a hex color, return as-is
+    if (color.startsWith('#')) {
+      return color;
+    }
+
+    // Convert snake_case to Title Case
+    return color
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  /**
+   * Handle errors with helpful messages
+   */
+  handleError(error) {
+    logger.error(`Failed to register project: ${error.message}`);
+
+    // Provide helpful guidance based on error type
+    if (error.message.includes('run "ralphblaster init"')) {
+      console.error('');
+      console.error('Please initialize RalphBlaster first:');
+      console.error('  ralphblaster init --token=your_token_here');
+      console.error('');
+    } else if (error.message.includes('Could not connect')) {
+      console.error('');
+      console.error('Please check:');
+      console.error('  1. Your internet connection');
+      console.error('  2. RalphBlaster API URL is correct');
+      console.error('  3. No firewall is blocking the connection');
+      console.error('');
+    }
+  }
+}
+
+module.exports = AddProjectCommand;

package/src/commands/init.js

@@ -0,0 +1,79 @@
+const ConfigFileManager = require('../config-file-manager');
+const logger = require('../logger');
+
+/**
+ * Init Command
+ * Saves RalphBlaster credentials to ~/.ralphblasterrc
+ */
+class InitCommand {
+  constructor() {
+    this.configFileManager = new ConfigFileManager();
+  }
+
+  /**
+   * Run the init command
+   */
+  async run() {
+    try {
+      logger.info('Initializing RalphBlaster credentials...');
+
+      // Get token from environment variable
+      const token = process.env.RALPHBLASTER_API_TOKEN;
+      if (!token) {
+        throw new Error('No API token provided. Please set RALPHBLASTER_API_TOKEN or pass --token=...');
+      }
+
+      // Get API URL from environment or use default
+      const apiUrl = process.env.RALPHBLASTER_API_URL || 'https://hq.ralphblaster.com';
+
+      // Save credentials to ~/.ralphblasterrc
+      this.configFileManager.update({
+        apiToken: token,
+        apiUrl: apiUrl
+      });
+
+      // Display success message
+      this.displaySuccess(apiUrl);
+
+      process.exit(0);
+    } catch (error) {
+      this.handleError(error);
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Display success message
+   */
+  displaySuccess(apiUrl) {
+    logger.info('Credentials saved successfully!');
+    logger.info(`API URL: ${apiUrl}`);
+    logger.info('Config saved to ~/.ralphblasterrc');
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. cd into your project directory');
+    console.log('  2. Run: ralphblaster add-project');
+    console.log('  3. Then start the agent: ralphblaster');
+  }
+
+  /**
+   * Handle errors with helpful messages
+   */
+  handleError(error) {
+    logger.error(`Failed to save credentials: ${error.message}`);
+
+    // Provide helpful guidance
+    if (error.message.includes('API token')) {
+      console.error('');
+      console.error('Please provide your API token:');
+      console.error('  ralphblaster init --token=your_token_here');
+      console.error('');
+      console.error('Or set environment variable:');
+      console.error('  export RALPHBLASTER_API_TOKEN="your_token_here"');
+      console.error('  ralphblaster init');
+      console.error('');
+    }
+  }
+}
+
+module.exports = InitCommand;