ralph-scaffold 1.0.0

package/bin/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// The source 'scripts' directory inside the package
+const sourceDir = path.resolve(__dirname, '../scripts');
+// The destination 'scripts' directory in the user's project
+const targetDir = path.resolve(process.cwd(), 'scripts');
+console.log(`\nYou can read ralph-usage-guide.md for more info.`)
+console.log(`\n🚀 Scaffolding Ralph scripts...`);
+
+try {
+  if (!fs.existsSync(sourceDir)) {
+    console.error(`Error: Source directory not found at ${sourceDir}`);
+    process.exit(1);
+  }
+
+  // Use fs.cpSync if available (Node.js 16.7.0+), otherwise fallback or manually copy
+  // Since we want to be broadly compatible, let's just implement a simple recursive copy
+  // or use fs.cpSync if it is available. Use cpSync for simplicity as it covers 'recursive'.
+  if (fs.cpSync) {
+      fs.cpSync(sourceDir, targetDir, { recursive: true });
+  } else {
+      // Fallback for older Node versions
+       copyRecursiveSync(sourceDir, targetDir); 
+  }
+
+  console.log(`✅ 'scripts/ralph' has been created in ${process.cwd()}`);
+  
+  // Make the shell script executable
+  const scriptPath = path.join(targetDir, 'ralph', 'ralph.sh');
+  if (fs.existsSync(scriptPath)) {
+      try {
+          fs.chmodSync(scriptPath, '755');
+      } catch (e) {
+         console.warn(`⚠️  Warning: Could not make ${scriptPath} executable. You may need to run 'chmod +x ${scriptPath}' manually.`);
+      }
+  }
+
+  console.log(`\nYou can now use the Ralph scripts in your workflow.`);
+  
+} catch (err) {
+  console.error('❌ Error scaffolding files:', err);
+  process.exit(1);
+}
+
+function copyRecursiveSync(src, dest) {
+  const exists = fs.existsSync(src);
+  const stats = exists && fs.statSync(src);
+  const isDirectory = exists && stats.isDirectory();
+
+  if (isDirectory) {
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(dest, { recursive: true });
+    }
+    fs.readdirSync(src).forEach((childItemName) => {
+      copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
+    });
+  } else {
+    fs.copyFileSync(src, dest);
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "ralph-scaffold",
+  "version": "1.0.0",
+  "description": "scripts to get you started using Ralph workflow",
+  "keywords": [
+    "ralph"
+  ],
+  "homepage": "https://github.com/rickvian/ralph-scaffold#readme",
+  "bugs": {
+    "url": "https://github.com/rickvian/ralph-scaffold/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rickvian/ralph-scaffold.git"
+  },
+  "license": "MIT",
+  "author": "Rcikvian",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "ralph-scaffold": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "scripts"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/scripts/ralph/prd.json

@@ -0,0 +1,17 @@
+{
+  "branchName": "ralph/feature",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add login form",
+      "acceptanceCriteria": [
+        "Email/password fields",
+        "Validates email format",
+        "typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}

package/scripts/ralph/prompt.md

@@ -0,0 +1,44 @@
+# Ralph Agent Instructions
+
+## Your Task
+
+1. Read `scripts/ralph/prd.json`
+2. Read `scripts/ralph/progress.txt`
+   (check Codebase Patterns first)
+3. Check you're on the correct branch
+4. Pick highest priority story 
+   where `passes: false`
+5. Implement that ONE story
+6. Run typecheck and tests
+7. Update AGENTS.md files with learnings
+8. Commit: `feat: [ID] - [Title]`
+9. Update prd.json: `passes: true`
+10. Append learnings to progress.txt
+
+## Progress Format
+
+APPEND to progress.txt:
+
+## [Date] - [Story ID]
+- What was implemented
+- Files changed
+- **Learnings:**
+  - Patterns discovered
+  - Gotchas encountered
+---
+
+## Codebase Patterns
+
+Add reusable patterns to the TOP 
+of progress.txt:
+
+## Codebase Patterns
+- Migrations: Use IF NOT EXISTS
+- React: useRef<Timeout | null>(null)
+
+## Stop Condition
+
+If ALL stories pass, reply:
+<promise>COMPLETE</promise>
+
+Otherwise end normally.

package/scripts/ralph/ralph-usage-guide.md

@@ -0,0 +1,183 @@
+This ralph setup is based on https://x.com/ryancarson/status/2008548371712135632
+
+This is guide for human and AI agent should ignore this file.
+
+### How It Works
+A bash loop that:
+Pipes a prompt into your AI agent
+Agent picks the next story from prd.json
+Agent implements it
+Agent runs typecheck + tests
+Agent commits if passing
+Agent marks story done
+Agent logs learnings
+Loop repeats until done
+
+### Memory persists only through:
+Git commits
+progress.txt (learnings)
+prd.json (task status)
+
+
+```
+scripts/ralph/
+├── ralph.sh
+├── prompt.md
+├── prd.json
+└── progress.txt
+```
+
+## ralph.sh
+
+The loop:
+
+```bash
+#!/bin/bash
+set -e
+
+MAX_ITERATIONS=${1:-10}
+SCRIPT_DIR="$(cd "$(dirname \
+  "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "🚀 Starting Ralph"
+
+for i in $(seq 1 $MAX_ITERATIONS); do
+  echo "═══ Iteration $i ═══"
+  
+  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" \
+    | claude --dangerously-skip-permissions 2>&1 \
+    | tee /dev/stderr) || true
+  
+  if echo "$OUTPUT" | \
+    grep -q "<promise>COMPLETE</promise>"
+  then
+    echo "✅ Done!"
+    exit 0
+  fi
+  
+  sleep 2
+done
+
+echo "⚠️ Max iterations reached"
+exit 1
+```
+
+Make executable:
+
+```bash
+chmod +x scripts/ralph/ralph.sh
+```
+
+
+## prompt.md
+Instructions for each iteration:
+
+```markdown
+# Ralph Agent Instructions
+
+## Your Task
+
+1. Read `scripts/ralph/prd.json`
+2. Read `scripts/ralph/progress.txt`
+   (check Codebase Patterns first)
+3. Check you're on the correct branch
+4. Pick highest priority story 
+   where `passes: false`
+5. Implement that ONE story
+6. Run typecheck and tests
+7. Update AGENTS.md files with learnings
+8. Commit: `feat: [ID] - [Title]`
+9. Update prd.json: `passes: true`
+10. Append learnings to progress.txt
+
+## Progress Format
+
+APPEND to progress.txt:
+
+## [Date] - [Story ID]
+- What was implemented
+- Files changed
+- **Learnings:**
+  - Patterns discovered
+  - Gotchas encountered
+---
+
+## Codebase Patterns
+
+Add reusable patterns to the TOP 
+of progress.txt:
+
+## Codebase Patterns
+- Migrations: Use IF NOT EXISTS
+- React: useRef<Timeout | null>(null)
+
+## Stop Condition
+
+If ALL stories pass, reply:
+<promise>COMPLETE</promise>
+
+Otherwise end normally.
+```
+
+## prd.json
+Your task list:
+```json
+{
+  "branchName": "ralph/feature",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add login form",
+      "acceptanceCriteria": [
+        "Email/password fields",
+        "Validates email format",
+        "typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+Key fields:
+`branchName` — branch to use
+`priority` — lower = first
+`passes` — set true when done
+
+
+## progress.txt
+Start with context:
+
+```markdown
+# Ralph Progress Log
+Started: 2024-01-15
+
+## Codebase Patterns
+- Migrations: IF NOT EXISTS
+- Types: Export from actions.ts
+
+## Key Files
+- db/schema.ts
+- app/auth/actions.ts
+---
+```
+
+
+Ralph appends after each story.
+Patterns accumulate across iterations.
+
+## Running Ralph
+
+run the ralph script with 25 iterations
+
+```bash
+./scripts/ralph/ralph.sh 25
+```
+
+Ralph will:
+- Create the feature branch
+- Complete stories one by one
+- Commit after each
+- Stop when all pass

package/scripts/ralph/ralph.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+set -e
+
+MAX_ITERATIONS=${1:-10}
+SCRIPT_DIR="$(cd "$(dirname \
+  "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "🚀 Starting Ralph"
+
+for i in $(seq 1 $MAX_ITERATIONS); do
+  echo "═══ Iteration $i ═══"
+  
+  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" \
+    | amp --dangerously-allow-all 2>&1 \
+    | tee /dev/stderr) || true
+  
+  if echo "$OUTPUT" | \
+    grep -q "<promise>COMPLETE</promise>"
+  then
+    echo "✅ Done!"
+    exit 0
+  fi
+  
+  sleep 2
+done
+
+echo "⚠️ Max iterations reached"
+exit 1