ralphinator 1.0.0

package/ralphs/verifier-ralph.md

@@ -0,0 +1,82 @@
+# Step 6: Verify and Finalize Target
+
+You are in Step 6 of a legacy code cleanup workflow. Execute this task immediately without asking for confirmation.
+
+## Your Task (Execute Now)
+
+1. Read CURRENT_TARGET.md to understand what was cleaned
+2. Read REFACTORING_LOG.md to see all changes made
+3. Read CHARACTERIZATION_TESTS.md to see test coverage added
+4. Run full test suite to verify everything passes
+5. Use Playwright MCP to verify UI behavior if the target involves UI components
+6. Review the cleaned code for quality
+
+## Verification Checklist:
+
+### Tests
+- [ ] All characterization tests pass
+- [ ] All existing tests still pass
+- [ ] No test was deleted or weakened
+- [ ] Test coverage is adequate for the cleaned area
+
+### Code Quality
+- [ ] Dependencies are properly broken/injected
+- [ ] Code is more readable than before
+- [ ] No new code smells introduced
+- [ ] Changes follow project conventions
+
+### Behavior Review
+- [ ] Do the observed behaviors make sense?
+- [ ] Are there any behaviors that seem like bugs rather than features?
+- [ ] Any suspicious patterns (e.g., silent error swallowing, race conditions, security issues)?
+- [ ] Does the code do what it claims to do?
+
+### UI Verification (if applicable)
+Use Playwright MCP to:
+- [ ] Verify the UI still renders correctly
+- [ ] Test key user interactions work as before
+- [ ] Check for visual regressions
+- [ ] Confirm navigation and state changes behave correctly
+
+If you identify concerning behaviors, create **CONCERNS.md** documenting:
+- What behavior seems wrong
+- Why it's concerning
+- Suggested investigation or fix (for future iterations)
+
+Note: Concerns don't block verification - they're observations for future cleanup targets.
+
+### Documentation
+- [ ] REFACTORING_LOG.md accurately reflects changes
+- [ ] Any necessary code comments added
+- [ ] README updated if public API changed
+
+## After Verification:
+
+1. Add the completed target to CLEANED_TARGETS.md with:
+   - What was cleaned
+   - Summary of improvements
+   - Number of characterization tests added
+   - Key refactorings performed
+
+2. Clean up workflow files:
+   - Delete CURRENT_TARGET.md
+   - Delete BEHAVIOR.md
+   - Delete CHARACTERIZATION_TESTS.md
+   - Delete REFACTORING_LOG.md
+   - Delete TARGET_COMPLETE.md
+
+3. Create VERIFICATION_COMPLETE.md (empty file)
+
+## If Issues Found:
+
+If verification reveals problems:
+1. Document issues in ISSUES.md
+2. Do NOT delete workflow files
+3. Create NEEDS_REWORK.md with description of what's wrong
+4. The workflow will return to an earlier step
+
+## Important:
+- Be thorough - this is the quality gate
+- Don't approve incomplete work
+- The goal is sustainable improvement, not perfection
+- Do NOT ask for confirmation - execute immediately and create the output file

package/src/build.js

@@ -0,0 +1,162 @@
+import {
+  logInfo,
+  logSuccess,
+  logError,
+  logStep,
+  fileExists,
+  fileNotEmpty,
+  removeFile,
+  ensureFile,
+  validateEnvironment,
+  invokeRalph,
+  sleep,
+} from './utils.js';
+
+async function executeStep1() {
+  logStep('STEP 1: Generate Story or Check Project Completion');
+  logInfo('CEO Ralph deciding: Project done? Or what story next?');
+
+  removeFile('STORY_COMPLETE.md');
+  await invokeRalph('ceo-ralph');
+
+  if (fileExists('PROJECT_COMPLETE.md')) {
+    logSuccess('Project marked as complete!');
+  } else if (fileExists('NEXT_STORY.md')) {
+    logSuccess('Next story generated');
+  } else {
+    logError('Step 1 failed');
+    process.exit(1);
+  }
+}
+
+async function executeStep2() {
+  logStep('STEP 2: Break Down User Story into Use Cases');
+  logInfo('Business Analyst Ralph making use cases!');
+
+  await invokeRalph('business-analyst-ralph');
+
+  if (fileExists('NEXT_USE_CASES.md') && !fileExists('NEXT_STORY.md')) {
+    logSuccess('Use cases generated');
+  } else {
+    logError('Step 2 failed');
+    process.exit(1);
+  }
+}
+
+async function executeStep3() {
+  logStep('STEP 3: Select Next Use Case');
+  logInfo('Product Owner Ralph picking which use case to do!');
+
+  await invokeRalph('product-owner-ralph');
+
+  if (!fileExists('NEXT_USE_CASES.md')) {
+    logSuccess('All use cases complete! Moving to refactoring.');
+  } else if (fileExists('CURRENT_USE_CASE.md')) {
+    logSuccess('Use case selected');
+  } else {
+    logError('Step 3 failed');
+    process.exit(1);
+  }
+}
+
+async function executeStep3_5() {
+  logStep('STEP 3.5: Implement One Task');
+  logInfo('Developer Ralph coding! ONE small thing!');
+
+  await invokeRalph('developer-ralph');
+
+  if (!fileExists('CURRENT_USE_CASE.md')) {
+    logSuccess('Use case completed');
+  } else {
+    logSuccess('Task completed');
+  }
+}
+
+async function executeStep4() {
+  logStep('STEP 4: Refactoring');
+  logInfo('Code Reviewer Ralph looking at code!');
+
+  ensureFile('REFACTORING.md');
+  await invokeRalph('code-reviewer-ralph');
+
+  if (!fileExists('REFACTORING.md')) {
+    logSuccess('Refactoring complete');
+  } else {
+    logSuccess('Refactoring iteration complete');
+  }
+}
+
+async function executeStep5() {
+  logStep('STEP 5: Story Completion Notification');
+  logInfo('Project Manager Ralph sending update!');
+
+  await invokeRalph('project-manager-ralph');
+
+  if (fileExists('STORY_COMPLETE.md')) {
+    logSuccess('Notification sent');
+  } else {
+    logError('Step 5 failed');
+    process.exit(1);
+  }
+}
+
+export async function runBuildWorkflow(options) {
+  logInfo('Starting Ralph Wiggum Software Corporation!');
+  logInfo('Me build software! One small task at a time!');
+  logInfo(`Topic: ${options.topic}`);
+  console.log();
+
+  validateEnvironment('PROMPT.md');
+
+  ensureFile('IMPLEMENTED_STORIES.md', '# Implemented User Stories\n');
+  ensureFile('IMPLEMENTED_CASES.md', '# Implemented Use Cases\n');
+
+  const maxIterations = parseInt(options.maxIterations, 10);
+  let iteration = 0;
+
+  while (true) {
+    iteration++;
+    logInfo(`=== Iteration ${iteration} ===`);
+
+    if (iteration > maxIterations) {
+      logError('Maximum iterations reached');
+      process.exit(1);
+    }
+
+    if (fileExists('PROJECT_COMPLETE.md')) {
+      logSuccess('Project complete! Ralph Wiggum Software Corporation successful!');
+      break;
+    }
+
+    if (fileExists('CURRENT_USE_CASE.md')) {
+      await executeStep3_5();
+    } else if (fileExists('REFACTORING.md')) {
+      await executeStep4();
+    } else if (fileNotEmpty('NEXT_USE_CASES.md')) {
+      await executeStep3();
+    } else if (fileExists('NEXT_USE_CASES.md') && !fileNotEmpty('NEXT_USE_CASES.md')) {
+      removeFile('NEXT_USE_CASES.md');
+      await executeStep4();
+    } else if (fileExists('NEXT_STORY.md')) {
+      await executeStep2();
+    } else if (
+      fileExists('STORY_COMPLETE.md') ||
+      (!fileExists('NEXT_STORY.md') &&
+        !fileExists('NEXT_USE_CASES.md') &&
+        !fileExists('REFACTORING_COMPLETE.md') &&
+        !fileExists('CURRENT_USE_CASE.md') &&
+        !fileExists('REFACTORING.md'))
+    ) {
+      await executeStep1();
+    } else if (fileExists('REFACTORING_COMPLETE.md')) {
+      await executeStep5();
+    } else {
+      logError('Unexpected state');
+      process.exit(1);
+    }
+
+    await sleep(1000);
+  }
+
+  logSuccess(`Ralph finished after ${iteration} iterations!`);
+}

package/src/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { select, input } from '@inquirer/prompts';
+import { runBuildWorkflow } from './build.js';
+import { runFixWorkflow } from './fix.js';
+
+console.log();
+console.log('🔧 Ralph Wiggum Software Corporation');
+console.log('   "Me build software! One small task at a time!"');
+console.log();
+
+async function main() {
+  const workflow = await select({
+    message: 'What would you like to do?',
+    choices: [
+      { name: 'Build new software (requires PROMPT.md)', value: 'build' },
+      { name: 'Fix legacy code (requires LEGACY_PROMPT.md)', value: 'fix' },
+    ],
+  });
+
+  let topic = process.env.NTFY_TOPIC;
+  if (!topic) {
+    topic = await input({
+      message: 'Enter your ntfy.sh topic for notifications:',
+      validate: (value) => value.length > 0 || 'Topic is required',
+    });
+  }
+
+  const maxIterations = await input({
+    message: 'Maximum iterations:',
+    default: '1000',
+  });
+
+  const options = { topic, maxIterations };
+
+  if (workflow === 'build') {
+    await runBuildWorkflow(options);
+  } else {
+    await runFixWorkflow(options);
+  }
+}
+
+main().catch((err) => {
+  if (err.name === 'ExitPromptError') {
+    console.log('\nGoodbye!');
+    process.exit(0);
+  }
+  console.error(err);
+  process.exit(1);
+});

package/src/fix.js

@@ -0,0 +1,177 @@
+import {
+  logInfo,
+  logSuccess,
+  logError,
+  logStep,
+  fileExists,
+  removeFile,
+  ensureFile,
+  validateEnvironment,
+  invokeRalph,
+  sleep,
+} from './utils.js';
+
+async function executeSurveyor() {
+  logStep('SURVEYOR RALPH: Me look at code! Me find messy parts!');
+  removeFile('CHRONICLE_COMPLETE.md');
+  await invokeRalph('surveyor-ralph');
+
+  if (fileExists('CLEANUP_COMPLETE.md')) {
+    logSuccess('All cleanup complete!');
+  } else if (fileExists('NEXT_TARGET.md')) {
+    logSuccess('Next target identified');
+  } else {
+    logError('Surveyor Ralph failed');
+    process.exit(1);
+  }
+}
+
+async function executeArchaeologist() {
+  logStep('ARCHAEOLOGIST RALPH: Me dig into code! Me understand what it does!');
+  await invokeRalph('archaeologist-ralph');
+
+  if (
+    (fileExists('TRIVIAL_FIX.md') || fileExists('BEHAVIOR.md')) &&
+    fileExists('CURRENT_TARGET.md') &&
+    !fileExists('NEXT_TARGET.md')
+  ) {
+    logSuccess('Behavior documented');
+  } else {
+    logError('Archaeologist Ralph failed');
+    process.exit(1);
+  }
+}
+
+async function executeTestWriter() {
+  logStep('TEST WRITER RALPH: Me write ONE test! Me capture behavior!');
+  await invokeRalph('test-writer-ralph');
+
+  if (fileExists('TESTS_COMPLETE.md')) {
+    logSuccess('Characterization tests complete');
+  } else {
+    logSuccess('Characterization test written');
+  }
+}
+
+async function executeSeamFinder() {
+  logStep('SEAM FINDER RALPH: Me find seams! Me plan how to break dependencies!');
+  await invokeRalph('seam-finder-ralph');
+
+  if (fileExists('SEAM_PLAN.md') && !fileExists('TESTS_COMPLETE.md')) {
+    logSuccess('Seam plan created');
+  } else {
+    logError('Seam Finder Ralph failed');
+    process.exit(1);
+  }
+}
+
+async function executeArchitect() {
+  logStep('ARCHITECT RALPH: Me look at big picture!');
+  await invokeRalph('architect-ralph');
+
+  if (fileExists('ARCHITECTURE_PLAN.md') || fileExists('REFACTORING_APPROVED.md')) {
+    logSuccess('Architectural review complete');
+  } else {
+    logError('Architect Ralph failed');
+    process.exit(1);
+  }
+}
+
+async function executeSurgeon() {
+  logStep('SURGEON RALPH: Me make ONE tiny change! Me run tests! Me commit!');
+  await invokeRalph('surgeon-ralph');
+
+  if (fileExists('TARGET_COMPLETE.md')) {
+    logSuccess('Target cleanup complete');
+  } else {
+    logSuccess('Refactoring step completed');
+  }
+}
+
+async function executeVerifier() {
+  logStep('VERIFIER RALPH: Me check everything! Me make sure it good!');
+  await invokeRalph('verifier-ralph');
+
+  if (fileExists('VERIFICATION_COMPLETE.md')) {
+    logSuccess('Verification passed');
+  } else if (fileExists('NEEDS_REWORK.md')) {
+    logInfo('Rework needed - returning to earlier step');
+  } else {
+    logError('Verifier Ralph failed');
+    process.exit(1);
+  }
+}
+
+async function executeChronicler() {
+  logStep('CHRONICLER RALPH: Me write down what happened! Me tell everyone!');
+  await invokeRalph('chronicler-ralph');
+
+  if (fileExists('CHRONICLE_COMPLETE.md')) {
+    logSuccess('Chronicle complete');
+  } else {
+    logError('Chronicler Ralph failed');
+    process.exit(1);
+  }
+}
+
+export async function runFixWorkflow(options) {
+  logInfo('Starting Ralph Wiggum Legacy Code Cleanup!');
+  logInfo('Me make old code better! With tests first!');
+  logInfo(`Topic: ${options.topic}`);
+  console.log();
+
+  validateEnvironment('LEGACY_PROMPT.md');
+  ensureFile('CLEANED_TARGETS.md', '# Cleaned Targets\n');
+
+  const maxIterations = parseInt(options.maxIterations, 10);
+  let iteration = 0;
+
+  while (true) {
+    iteration++;
+    logInfo(`=== Iteration ${iteration} ===`);
+
+    if (iteration > maxIterations) {
+      logError('Maximum iterations reached');
+      process.exit(1);
+    }
+
+    if (fileExists('CLEANUP_COMPLETE.md')) {
+      logSuccess('Legacy cleanup complete! Me made old code better!');
+      break;
+    }
+
+    if (fileExists('NEEDS_REWORK.md')) {
+      removeFile('NEEDS_REWORK.md');
+      removeFile('TARGET_COMPLETE.md');
+      removeFile('SEAM_PLAN.md');
+      removeFile('ARCHITECTURE_PLAN.md');
+      removeFile('REFACTORING_APPROVED.md');
+      await executeTestWriter();
+    } else if (fileExists('VERIFICATION_COMPLETE.md')) {
+      await executeChronicler();
+    } else if (fileExists('TARGET_COMPLETE.md')) {
+      await executeVerifier();
+    } else if (fileExists('TRIVIAL_FIX.md') && fileExists('CURRENT_TARGET.md')) {
+      await executeSurgeon();
+    } else if (fileExists('ARCHITECTURE_PLAN.md') || fileExists('REFACTORING_APPROVED.md')) {
+      await executeSurgeon();
+    } else if (fileExists('SEAM_PLAN.md')) {
+      await executeArchitect();
+    } else if (fileExists('TESTS_COMPLETE.md')) {
+      await executeSeamFinder();
+    } else if (fileExists('BEHAVIOR.md') && fileExists('CURRENT_TARGET.md')) {
+      await executeTestWriter();
+    } else if (fileExists('NEXT_TARGET.md')) {
+      await executeArchaeologist();
+    } else if (fileExists('CHRONICLE_COMPLETE.md') || !fileExists('CURRENT_TARGET.md')) {
+      await executeSurveyor();
+    } else {
+      logError('Unexpected state');
+      process.exit(1);
+    }
+
+    await sleep(1000);
+  }
+
+  logSuccess(`Ralph cleaned legacy code after ${iteration} iterations!`);
+}

package/src/utils.js

@@ -0,0 +1,122 @@
+import { existsSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { execSync, spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const RALPHS_DIR = join(__dirname, '..', 'ralphs');
+
+// Colors
+const colors = {
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  reset: '\x1b[0m',
+};
+
+export function logInfo(msg) {
+  console.log(`${colors.blue}[INFO]${colors.reset} ${msg}`);
+}
+
+export function logSuccess(msg) {
+  console.log(`${colors.green}[SUCCESS]${colors.reset} ${msg}`);
+}
+
+export function logError(msg) {
+  console.error(`${colors.red}[ERROR]${colors.reset} ${msg}`);
+}
+
+export function logStep(msg) {
+  console.log();
+  console.log(`${colors.green}=======================================================${colors.reset}`);
+  console.log(`${colors.green}${msg}${colors.reset}`);
+  console.log(`${colors.green}=======================================================${colors.reset}`);
+  console.log();
+}
+
+export function fileExists(path) {
+  return existsSync(path);
+}
+
+export function fileNotEmpty(path) {
+  if (!existsSync(path)) return false;
+  const stats = statSync(path);
+  return stats.size > 0;
+}
+
+export function removeFile(path) {
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export function ensureFile(path, content = '') {
+  if (!existsSync(path)) {
+    writeFileSync(path, content);
+  }
+}
+
+export function validateEnvironment(requiredPrompt) {
+  logInfo('Validating environment...');
+
+  try {
+    execSync('which claude', { stdio: 'ignore' });
+  } catch {
+    logError('Claude Code is not installed or not in PATH');
+    logError('Install with: npm install -g @anthropic-ai/claude-code');
+    process.exit(1);
+  }
+
+  if (!existsSync('.git')) {
+    logError('Not a git repository. Please run "git init" first.');
+    process.exit(1);
+  }
+
+  try {
+    execSync('git config user.name', { stdio: 'ignore' });
+    execSync('git config user.email', { stdio: 'ignore' });
+  } catch {
+    logError('Git user.name and user.email must be configured');
+    process.exit(1);
+  }
+
+  if (!existsSync(requiredPrompt)) {
+    logError(`${requiredPrompt} not found`);
+    process.exit(1);
+  }
+
+  logSuccess('Environment validation complete');
+}
+
+export function invokeRalph(ralphName) {
+  const promptPath = join(RALPHS_DIR, `${ralphName}.md`);
+
+  if (!existsSync(promptPath)) {
+    logError(`Ralph prompt not found: ${promptPath}`);
+    process.exit(1);
+  }
+
+  logInfo(`Invoking Claude Code for ${ralphName}...`);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn('claude', ['-p', '--dangerously-skip-permissions', promptPath], {
+      stdio: 'inherit',
+      shell: true,
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Claude exited with code ${code}`));
+      }
+    });
+
+    child.on('error', reject);
+  });
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}