How sammintah/ralph works
1. This repository is a tooling/repo-for-an-agent-loop, not an application feature codebase. Its core purpose is to automate iterative AI-driven coding against another git repository using a PRD-driven task list.
2. The root orchestration layer is centered on ralph.sh. That script is the control plane: it creates/uses a feature branch, selects the next incomplete story from prd.json, invokes an AI coding tool, runs checks, commits successful work, and repeats for a bounded number of iterations.
3. The AI execution boundary is external. Ralph can run either Amp CLI or Claude Code. Each iteration starts a fresh model instance with clean context, so the loop depends on persisted state rather than conversational memory.
4. The task/state model is file-based:
- prd.json is the authoritative backlog of stories and passes status.
- progress.txt is append-only running context/learnings.
- git history captures completed iteration outputs.
- AGENTS.md files are updated with discovered conventions and gotchas so later agents can pick them up automatically.
5. There is a clear documentation-to-execution pipeline:
- A PRD is authored in markdown using the skills/prd workflow.
- The Ralph skill in skills/ralph converts that PRD into structured prd.json.
- ralph.sh consumes prd.json to drive the implementation loop.
This separation keeps requirements authoring, task structuring, and execution distinct.
6. The repository includes prompt templates for the two supported toolchains:
- prompt.md for Amp
- CLAUDE.md for Claude Code
These are part of the execution boundary and shape how each fresh agent instance behaves.
7. The skills/ directory is a second integration surface. It packages reusable instructions for AI tools, enabling the PRD-generation and PRD-to-JSON conversion steps to be used across projects, not just inside this repo.
8. The flowchart/ directory is a separate frontend subsystem used to visualize Ralph’s process. Based on the file tree, it is a Vite + TypeScript + React app with its own package.json, index.html, src/, and build config. It is architecturally independent from the shell-based orchestration layer.
9. The data flow for the main system is:
PRD markdown → structured prd.json → one story selected per iteration → AI tool edits target repo → quality checks run → commit on success → prd.json and progress.txt updated → next iteration.
That loop is the central behavior to diagram.
10. The quality gate is part of the control loop, not an afterthought. The README says Ralph runs typecheck/tests before committing, so the system depends on feedback loops to prevent error accumulation across iterations.
11. prd.json.example acts as the schema/reference artifact for the structured backlog format. It is useful as the contract between the PRD authoring step and the automated loop.
12. .github/workflows/deploy.yml suggests a CI/CD publishing path for the flowchart site, likely building and deploying the static frontend to GitHub Pages or a similar host. That deployment path is separate from the agent loop itself.
13. For an architecture diagram, the most important boundaries are:
- human-authored PRD generation
- task-serialization into prd.json
- the iterative AI coding loop
- repo-local memory via files and git
- the optional browser-based flowchart UI
- the deployment pipeline for the UI
14. In short, Ralph is a file-backed, git-aware agent orchestrator with two external model backends and a separate visualization frontend. The repository’s architecture is mostly about coordination, persistence, and iteration control rather than business logic.
Main entry points: ralph.sh ralph.sh · App.tsx Flowchart UI · prd/SKILL.md PRD skill · ralph/SKILL.md Ralph skill
Components 17
Agent loop
File-backed control plane for iterative coding and validation.
- ralph.sh · Main control plane: selects stories, invokes models, runs checks, and commits progress.
ralph.sh - Target repo · External git repository that receives the agent-driven code changes.
- Checks · Typecheck/test gate that blocks failed iterations from being committed.
PRD pipeline
Human PRD writing and conversion into structured task data.
- PRD markdown · Human-authored requirements source used to seed the task loop.
- PRD skill · Guides PRD authoring and structure for downstream automation.
skills/prd/SKILL.md - Ralph skill · Converts a PRD into the structured backlog consumed by the loop.
skills/ralph/SKILL.md - Backlog schema · Reference format for the structured story list and pass status.
prd.json.example
Repo memory
Persistent state carried across fresh model runs.
- progress.txt · Append-only notes and learnings carried forward between iterations.
- AGENTS.md · Repository-convention notes that later agents can discover automatically.
AGENTS.md - Git history · Completed iteration outputs captured as commits in version control.
Model backends
External AI tools invoked by the loop.
- Amp CLI · One supported external coding backend, launched fresh each iteration.
- Claude Code · Alternative external coding backend launched with clean context each run.
CLAUDE.md - Amp prompt · Prompt template shaping Amp-backed execution sessions.
prompt.md - Claude prompt · Prompt template shaping Claude Code sessions.
CLAUDE.md
Flowchart UI
Separate browser frontend for visualizing the process.
- Flowchart UI · Vite + React app that visualizes Ralph’s process as a separate subsystem.
flowchart/src/App.tsx - Build config · Frontend entry and build setup for the visualization app.
flowchart/package.json
Publishing
Static deployment path for the flowchart app.
- Deploy workflow · Publishes the flowchart frontend through GitHub Actions.
.github/workflows/deploy.yml
Connections 19
- PRD markdown → PRD skill: author with · PRDs are written using the PRD skill workflow.
- PRD skill → Ralph skill: handoff · The authored PRD is then prepared for structured conversion.
- Ralph skill → Backlog schema: emit format · The conversion step targets the structured backlog contract.
- Backlog schema → ralph.sh: input contract · ralph.sh consumes the structured task file shape.
- ralph.sh → Target repo: edit · The orchestrator applies changes in the target repository workspace.
- ralph.sh → Amp CLI: invoke · One execution backend supported by the loop.
- ralph.sh → Claude Code: invoke · Alternative execution backend supported by the loop.
- Amp CLI → Amp prompt: guided by · Amp runs are shaped by the prompt template.
- Claude Code → Claude prompt: guided by · Claude runs are shaped by the Claude prompt template.
- ralph.sh → Checks: run · Checks are executed before successful work is committed.
- Checks → Git history: pass commits · Successful iterations are captured in git history.
- ralph.sh → progress.txt: append · Learnings and context are persisted between fresh runs.
- ralph.sh → AGENTS.md: update · Discovered conventions are written for future agents.
- progress.txt → ralph.sh: resume · Later iterations read accumulated context back into the loop.
- AGENTS.md → ralph.sh: inform · Shared repo conventions influence subsequent iterations.
- Build config → Flowchart UI: builds · Frontend config supports the React visualization app.
- Flowchart UI → Deploy workflow: publish via · The UI is shipped through the CI deployment path.
- Deploy workflow → Flowchart UI: deploys · The workflow publishes the frontend artifact.
- ralph.sh → Flowchart UI: visualized by · The process can be represented in the separate frontend subsystem.