[feat] Huge improvements: State-driven architecture, iterative stories, and automatic compaction

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash(git commit*)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const fs=require('fs');try{const p=JSON.parse(fs.readFileSync('scripts/ralph/prd.json','utf8'));const s=JSON.parse(fs.readFileSync('scripts/ralph/state.json','utf8'));if(!s.currentStory)process.exit(0);const story=p.userStories.find(u=>u.id===s.currentStory);if(story&&!story.passes){console.log('WARNING: story '+s.currentStory+' not yet marked passes:true in prd.json')}}catch(e){}\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('scripts/ralph/state.json','utf8'));const today=new Date().toISOString().slice(0,10);if(s.lastUpdated!==today){console.log('state.json not updated today ('+s.lastUpdated+' vs '+today+')');process.exit(2)}}catch(e){}\""
+          }
+        ]
+      }
+    ]
+  }
+}

.claudeignore

@@ -0,0 +1,28 @@
+# Archives (not relevant to agent work)
+archive/
+scripts/ralph/archive/
+
+# Flowchart source (visualization, not agent work)
+flowchart/
+
+# Binary/media files
+*.png
+*.jpg
+*.gif
+*.svg
+*.ico
+*.webp
+*.woff
+*.woff2
+*.ttf
+*.eot
+
+# Build artifacts
+node_modules/
+.next/
+dist/
+build/
+out/
+
+# Environment files
+.env*

.gitignore

@@ -1,13 +1,21 @@
 # Ralph working files (generated during runs)
-prd.json
-progress.txt
-.last-branch
+scripts/ralph/prd.json
+scripts/ralph/progress.md
+scripts/ralph/state.json
+scripts/ralph/.last-branch
 
 # Archive is optional to commit
-# archive/
+# scripts/ralph/archive/
 
 # OS files
 .DS_Store
 
-#Claude
-.claude/
+# Claude Code - only exclude local settings (shared settings.json with hooks is tracked)
+.claude/settings.local.json
+
+# Build artifacts
+node_modules/
+dist/
+build/
+.next/
+out/

AGENTS.md

@@ -14,18 +14,18 @@ cd flowchart && npm run dev
 cd flowchart && npm run build
 
 # Run Ralph with Amp (default)
-./ralph.sh [max_iterations]
+./scripts/ralph/ralph.sh [max_sessions]
 
 # Run Ralph with Claude Code
-./ralph.sh --tool claude [max_iterations]
+./scripts/ralph/ralph.sh --tool claude [max_sessions]
 ```
 
 ## Key Files
 
-- `ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`)
-- `prompt.md` - Instructions given to each AMP instance
--  `CLAUDE.md` - Instructions given to each Claude Code instance
-- `prd.json.example` - Example PRD format
+- `scripts/ralph/ralph.sh` - The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`)
+- `scripts/ralph/prompt.md` - Instructions given to each AMP instance
+- `scripts/ralph/CLAUDE.md` - Instructions given to each Claude Code instance
+- `scripts/ralph/prd.json.example` - Example PRD format
 - `flowchart/` - Interactive React Flow diagram explaining how Ralph works
 
 ## Flowchart
@@ -41,7 +41,7 @@ npm run dev
 
 ## Patterns
 
-- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context
-- Memory persists via git history, `progress.txt`, and `prd.json`
+- Each session spawns a fresh AI instance (Amp or Claude Code) with clean context
+- Memory persists via git history, `scripts/ralph/progress.md`, `scripts/ralph/prd.json`, and `scripts/ralph/state.json`
 - Stories should be small enough to complete in one context window
-- Always update AGENTS.md with discovered patterns for future iterations
+- Always update Institutional Memory in scripts/ralph/CLAUDE.md with discovered patterns for future sessions

CLAUDE.md

@@ -1,104 +1,2 @@
-# Ralph Agent Instructions
-
-You are an autonomous coding agent working on a software project.
-
-## Your Task
-
-1. Read the PRD at `prd.json` (in the same directory as this file)
-2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
-3. Check you're on the correct branch from PRD `branchName`. If not, check it out or create from main.
-4. Pick the **highest priority** user story where `passes: false`
-5. Implement that single user story
-6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
-7. Update CLAUDE.md files if you discover reusable patterns (see below)
-8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
-9. Update the PRD to set `passes: true` for the completed story
-10. Append your progress to `progress.txt`
-
-## Progress Report Format
-
-APPEND to progress.txt (never replace, always append):
-```
-## [Date/Time] - [Story ID]
-- What was implemented
-- Files changed
-- **Learnings for future iterations:**
-  - Patterns discovered (e.g., "this codebase uses X for Y")
-  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
-  - Useful context (e.g., "the evaluation panel is in component X")
----
-```
-
-The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
-
-## Consolidate Patterns
-
-If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
-
-```
-## Codebase Patterns
-- Example: Use `sql<number>` template for aggregations
-- Example: Always use `IF NOT EXISTS` for migrations
-- Example: Export types from actions.ts for UI components
-```
-
-Only add patterns that are **general and reusable**, not story-specific details.
-
-## Update CLAUDE.md Files
-
-Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files:
-
-1. **Identify directories with edited files** - Look at which directories you modified
-2. **Check for existing CLAUDE.md** - Look for CLAUDE.md in those directories or parent directories
-3. **Add valuable learnings** - If you discovered something future developers/agents should know:
-   - API patterns or conventions specific to that module
-   - Gotchas or non-obvious requirements
-   - Dependencies between files
-   - Testing approaches for that area
-   - Configuration or environment requirements
-
-**Examples of good CLAUDE.md additions:**
-- "When modifying X, also update Y to keep them in sync"
-- "This module uses pattern Z for all API calls"
-- "Tests require the dev server running on PORT 3000"
-- "Field names must match the template exactly"
-
-**Do NOT add:**
-- Story-specific implementation details
-- Temporary debugging notes
-- Information already in progress.txt
-
-Only update CLAUDE.md if you have **genuinely reusable knowledge** that would help future work in that directory.
-
-## Quality Requirements
-
-- ALL commits must pass your project's quality checks (typecheck, lint, test)
-- Do NOT commit broken code
-- Keep changes focused and minimal
-- Follow existing code patterns
-
-## Browser Testing (If Available)
-
-For any story that changes UI, verify it works in the browser if you have browser testing tools configured (e.g., via MCP):
-
-1. Navigate to the relevant page
-2. Verify the UI changes work as expected
-3. Take a screenshot if helpful for the progress log
-
-If no browser tools are available, note in your progress report that manual browser verification is needed.
-
-## Stop Condition
-
-After completing a user story, check if ALL stories have `passes: true`.
-
-If ALL stories are complete and passing, reply with:
-<promise>COMPLETE</promise>
-
-If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
-
-## Important
-
-- Work on ONE story per iteration
-- Commit frequently
-- Keep CI green
-- Read the Codebase Patterns section in progress.txt before starting
+## Ralph Agent
+When working on Ralph stories, read and follow `scripts/ralph/CLAUDE.md`.