ralph-scaffold 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-scaffold",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "scripts to get you started using Ralph workflow",
   "keywords": [
     "ralph"
@@ -22,7 +22,8 @@
   },
   "files": [
     "bin",
-    "scripts"
+    "scripts",
+    "public"
   ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

package/readme.md

@@ -0,0 +1,193 @@
+<img src="public/ralph-scaffolder.jpg" alt="Ralph Scaffolder" />
+
+This ralph scaffolding script helps you quickly setup RALPH workflow
+based on https://x.com/ryancarson/status/2008548371712135632
+
+
+To scaffold ralph, just run this script within your project
+```bin
+npx ralph-scaffold
+```
+
+----
+
+
+### 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