Ai/local

AGENTS.md

@@ -1,47 +1,27 @@
-# Ralph Agent Instructions
-
-## Overview
-
-Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.
-
-## Commands
-
-```bash
-# Run the flowchart dev server
-cd flowchart && npm run dev
-
-# Build the flowchart
-cd flowchart && npm run build
-
-# Run Ralph with Amp (default)
-./ralph.sh [max_iterations]
-
-# Run Ralph with Claude Code
-./ralph.sh --tool claude [max_iterations]
-```
-
-## 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
-- `flowchart/` - Interactive React Flow diagram explaining how Ralph works
-
-## Flowchart
-
-The `flowchart/` directory contains an interactive visualization built with React Flow. It's designed for presentations - click through to reveal each step with animations.
-
-To run locally:
-```bash
-cd flowchart
-npm install
-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`
-- Stories should be small enough to complete in one context window
-- Always update AGENTS.md with discovered patterns for future iterations
+# Python Agent Logic (Lean Mode)
+
+## 1. Python Environment
+- VirtualEnv: `.venv/bin/activate`
+- Type Checking: `mypy .`
+- Testing: `pytest`
+
+## 2. Iteration Rules
+1. Read `prd.json` & `AGENTS.md`.
+2. Check `git log -n 10`.
+3. Execute ONE task from `prd.json` (Priority-based).
+4. Update `progress.txt` (Human Audit) & `prd.json` (State).
+5. If tests fail: Fix or document blocker in `AGENTS.md` and EXIT.
+
+## 3. Discovered Patterns (The "Brain")
+- Alembic migrations require `alembic.ini` configuration file with `script_location = db/migrations` and `prepend_path = .`
+- When running Alembic from `orchestrator/`, the env.py must add the repo root (parent of orchestrator/) to sys.path for imports
+- Use `sa.Enum("value1", "value2", ..., name="typename")` in migration files instead of `sa.Enum("typename", name="typename")` to avoid duplicate enum creation
+- PostgreSQL JSONB type must be imported from `sqlalchemy.dialects.postgresql` (not `sqlalchemy`) - use `from sqlalchemy.dialects.postgresql import JSONB`
+- Alembic async migrations require `greenlet` library - install with `pip install greenlet`
+- Alembic async migrations with asyncpg require `psycopg2-binary` - install with `pip install psycopg2-binary`
+
+## 4. Aider Review (Mandatory Post-Implementation Gate)
+- Run `./scripts/ralph/aider_review.sh` **after** implementation, **before** step 4.
+- Apply *all* critical fixes Aider suggests.
+- If Aider reports a reusable pattern (e.g., anti-pattern), add it here.
+- If Aider finds a blocker you cannot fix: document in this file and EXIT (no commit).

CLAUDE.md

@@ -1,104 +1,75 @@
-# Ralph Agent Instructions
+# Master Agent Loop (Hybrid Mode)
 
-You are an autonomous coding agent working on a software project.
+You are an autonomous coding agent operating in a "Fresh Context" loop. Every iteration begins with zero chat memory; you must reconstruct your understanding from the codebase and designated state files.
 
-## Your Task
+## 1. Memory and State Files
 
-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`
+You only have access to these persistent files to understand the project:
 
-## Progress Report Format
+* **`prd.json`**: The source of truth for task status and priority.
+* **`AGENTS.md`**: A curated, high-density library of discovered patterns and "gotchas" (<500 lines).
+* **`progress.txt`**: A chronological audit log for humans. **Append to this, but do not rely on it for context**.
+* **Git History**: Use `git log` to see what was actually changed recently.
 
-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")
----
-```
+## 2. The Iteration Workflow
 
-The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+### Step 1: Initialize (Read State)
 
-## Consolidate Patterns
+Read the following to understand the current situation, keeping your total reading budget under **30k tokens**:
 
-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
+```bash
+cat prd.json
+cat scripts/ralph/AGENTS.md
+git log --oneline -15
 ```
 
-Only add patterns that are **general and reusable**, not story-specific details.
+### Step 2: Select ONE Task
 
-## Update CLAUDE.md Files
+From `prd.json`, identify the highest priority story where `passes: false`. Select based on:
 
-Before committing, check if any edited files have learnings worth preserving in nearby CLAUDE.md files:
+* **Blockers**: Does this task prevent others from starting?
+* **Value**: Is this a core feature?
+* **Independence**: Can it be finished and tested in one go?
 
-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
+### Step 3: Implementation & Quality Gates
 
-**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"
+Work on **exactly one story**. You must follow existing patterns found in `AGENTS.md`.
 
-**Do NOT add:**
-- Story-specific implementation details
-- Temporary debugging notes
-- Information already in progress.txt
+Before committing, you must pass:
 
-Only update CLAUDE.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+1. **Typechecks**: `cd orchestrator && mypy . --ignore-missing-imports` or equivalent  
+2. **Tests**: `cd orchestrator && pytest tests/ -x` or equivalent  
+3. **Aider Review**: Run `./scripts/ralph/aider-review.sh`  
+   - Apply *all* critical fixes Aider suggests  
+   - If Aider finds no critical issues, proceed  
+   - If `SKIP_AIDER_REVIEW=1` is set, skip this step entirely  
+   - If Aider reports a blocker you cannot fix, document it in `scripts/ralph/AGENTS.md` and exit without committing  
+4. **Manual Verification**: If behaviour changed, verify against acceptance criteria  
 
-## Quality Requirements
+### Step 4: Update Documentation & Logs
 
-- 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
+1. **Update `prd.json**`: Set `passes: true` for the completed story.
+2. **Curate `scripts/ralph/AGENTS.md`**: If you learned a **reusable** pattern (e.g., "Always use X for Y"), add it here. Delete obsolete info.
+3. **Audit `progress.txt**`: Append a brief summary of your work for the human supervisor:
+* **What**: Story ID and Title.
+* **Changes**: Files modified.
+* **Learnings**: Any critical context for the next iteration.
 
-## 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
+### Step 5: Commit & Exit
 
-If no browser tools are available, note in your progress report that manual browser verification is needed.
+```bash
+git add -A
+git commit -m "feat(STORY-ID): Brief description"
 
-## 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).
+**If all stories in `prd.json` are complete:** Reply with `<promise>COMPLETE</promise>`.
+**Otherwise:** Simply exit. The loop will restart with a fresh context.
 
-## Important
+## 3. Critical Constraints
 
-- Work on ONE story per iteration
-- Commit frequently
-- Keep CI green
-- Read the Codebase Patterns section in progress.txt before starting
+* **No "Memory"**: Never refer to "previous sessions." If it isn't in the files or git, it didn't happen.
+* **One Task, One Commit**: Do not drift into secondary tasks. Finish the selected story, then exit.
+* **Don't Commit Broken Code**: If tests fail and you cannot fix them, document the blocker in `scripts/ralph/AGENTS.md` and exit without committing.

aider-review.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Skip entirely if requested
+if [ "${SKIP_AIDER_REVIEW:-0}" = "1" ]; then
+  echo "⏭️  SKIP_AIDER_REVIEW=1 — skipping aider review step"
+  exit 0
+fi
+
+# Fallback defaults for safety
+: "${LLM_API_BASE:=http://localhost:8080/v1}"
+: "${LLM_API_KEY:=dummy}"
+
+# Verify server is alive before blocking the loop
+if ! curl -sf --max-time 5 "$LLM_API_BASE/models" > /dev/null; then
+  echo -e "\033[33m⚠️  LLM server not responding at $LLM_API_BASE — skipping aider review\033[0m"
+  echo "   Set SKIP_AIDER_REVIEW=1 to suppress this warning"
+  exit 0
+fi
+
+echo "🔍 Running Aider review via $LLM_API_BASE"
+
+aider \
+  --model qwen3-coder-next \
+  --openai-api-base "$LLM_API_BASE" \
+  --openai-api-key "$LLM_API_KEY" \
+  --yes \
+  --no-auto-commit \
+  --message "Review the git diff since the last commit. Focus on:
+- Correctness against PRD
+- Test coverage & quality
+- Type safety & anti-patterns
+- Consistency with patterns in AGENTS.md
+
+Return:
+1. Critical issues (must fix)
+2. Optional improvements
+3. New patterns to add to AGENTS.md"

ralph.sh

@@ -43,20 +43,19 @@ LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
 if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
   CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
   LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
-  
+
   if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
     # Archive the previous run
     DATE=$(date +%Y-%m-%d)
     # Strip "ralph/" prefix from branch name for folder
     FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
     ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
-
     echo "Archiving previous run: $LAST_BRANCH"
     mkdir -p "$ARCHIVE_FOLDER"
     [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
     [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
     echo "   Archived to: $ARCHIVE_FOLDER"
-    
+
     # Reset progress file for new run
     echo "# Ralph Progress Log" > "$PROGRESS_FILE"
     echo "Started: $(date)" >> "$PROGRESS_FILE"
@@ -94,15 +93,15 @@ for i in $(seq 1 $MAX_ITERATIONS); do
     # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output
     OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true
   fi
-  
+
   # Check for completion signal
   if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
     echo ""
     echo "Ralph completed all tasks!"
     echo "Completed at iteration $i of $MAX_ITERATIONS"
     exit 0
   fi
-  
+
   echo "Iteration $i complete. Continuing..."
   sleep 2
 done