# sammintah/ralph architecture

> Architecture diagram of the GitHub repository sammintah/ralph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sammintah/ralph
- Repository: https://github.com/sammintah/ralph

## Overview

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`](https://github.com/sammintah/ralph/blob/main/ralph.sh) (ralph.sh), [`flowchart/src/App.tsx`](https://github.com/sammintah/ralph/blob/main/flowchart/src/App.tsx) (Flowchart UI), [`skills/prd/SKILL.md`](https://github.com/sammintah/ralph/blob/main/skills/prd/SKILL.md) (PRD skill), [`skills/ralph/SKILL.md`](https://github.com/sammintah/ralph/blob/main/skills/ralph/SKILL.md) (Ralph skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent loop"]
  node_ralph_sh["ralph.sh<br/>orchestrator<br/>[ralph.sh]"]
  node_target_repo[("Target repo<br/>workspace")]
  node_quality_gate{{"Checks<br/>validation gate"}}
end

subgraph group_authoring["PRD pipeline"]
  node_prd_md["PRD markdown<br/>spec doc"]
  node_skill_prd["PRD skill<br/>instruction pack<br/>[SKILL.md]"]
  node_skill_ralph["Ralph skill<br/>converter skill<br/>[SKILL.md]"]
  node_prd_schema["Backlog schema<br/>example contract<br/>[prd.json.example]"]
end

subgraph group_memory["Repo memory"]
  node_progress_log["progress.txt<br/>run log"]
  node_agents_md["AGENTS.md<br/>memory notes<br/>[AGENTS.md]"]
  node_git_history[("Git history<br/>state ledger")]
end

subgraph group_execution["Model backends"]
  node_amp_cli["Amp CLI<br/>model runtime"]
  node_claude_code["Claude Code<br/>model runtime<br/>[CLAUDE.md]"]
  node_prompt_md["Amp prompt<br/>prompt template<br/>[prompt.md]"]
  node_claude_md["Claude prompt<br/>prompt template<br/>[CLAUDE.md]"]
end

subgraph group_ui["Flowchart UI"]
  node_flowchart_app["Flowchart UI<br/>react frontend<br/>[App.tsx]"]
  node_flowchart_build["Build config<br/>frontend config<br/>[package.json]"]
end

subgraph group_delivery["Publishing"]
  node_deploy_workflow["Deploy workflow<br/>ci pipeline<br/>[deploy.yml]"]
end

node_prd_md -->|"author with"| node_skill_prd
node_skill_prd -->|"handoff"| node_skill_ralph
node_skill_ralph -->|"emit format"| node_prd_schema
node_prd_schema -->|"input contract"| node_ralph_sh
node_ralph_sh -->|"edit"| node_target_repo
node_ralph_sh -->|"invoke"| node_amp_cli
node_ralph_sh -->|"invoke"| node_claude_code
node_amp_cli -->|"guided by"| node_prompt_md
node_claude_code -->|"guided by"| node_claude_md
node_ralph_sh -->|"run"| node_quality_gate
node_quality_gate -->|"pass commits"| node_git_history
node_ralph_sh -->|"append"| node_progress_log
node_ralph_sh -->|"update"| node_agents_md
node_progress_log -->|"resume"| node_ralph_sh
node_agents_md -->|"inform"| node_ralph_sh
node_flowchart_build -->|"builds"| node_flowchart_app
node_flowchart_app -->|"publish via"| node_deploy_workflow
node_deploy_workflow -->|"deploys"| node_flowchart_app
node_ralph_sh -.->|"visualized by"| node_flowchart_app

click node_skill_prd "https://github.com/sammintah/ralph/blob/main/skills/prd/SKILL.md"
click node_skill_ralph "https://github.com/sammintah/ralph/blob/main/skills/ralph/SKILL.md"
click node_prd_schema "https://github.com/sammintah/ralph/blob/main/prd.json.example"
click node_ralph_sh "https://github.com/sammintah/ralph/blob/main/ralph.sh"
click node_agents_md "https://github.com/sammintah/ralph/blob/main/AGENTS.md"
click node_claude_code "https://github.com/sammintah/ralph/blob/main/CLAUDE.md"
click node_prompt_md "https://github.com/sammintah/ralph/blob/main/prompt.md"
click node_claude_md "https://github.com/sammintah/ralph/blob/main/CLAUDE.md"
click node_flowchart_app "https://github.com/sammintah/ralph/blob/main/flowchart/src/App.tsx"
click node_flowchart_build "https://github.com/sammintah/ralph/blob/main/flowchart/package.json"
click node_deploy_workflow "https://github.com/sammintah/ralph/blob/main/.github/workflows/deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ralph_sh,node_target_repo,node_quality_gate toneBlue
class node_prd_md,node_skill_prd,node_skill_ralph,node_prd_schema toneAmber
class node_progress_log,node_agents_md,node_git_history toneMint
class node_amp_cli,node_claude_code,node_prompt_md,node_claude_md toneRose
class node_flowchart_app,node_flowchart_build toneIndigo
class node_deploy_workflow toneTeal
```

## Components

### Agent loop

File-backed control plane for iterative coding and validation.

- [ralph.sh](https://github.com/sammintah/ralph/blob/main/ralph.sh): orchestrator · Main control plane: selects stories, invokes models, runs checks, and commits progress. · `ralph.sh`
- **Target repo**: workspace · External git repository that receives the agent-driven code changes.
- **Checks**: validation gate · Typecheck/test gate that blocks failed iterations from being committed.

### PRD pipeline

Human PRD writing and conversion into structured task data.

- **PRD markdown**: spec doc · Human-authored requirements source used to seed the task loop.
- [PRD skill](https://github.com/sammintah/ralph/blob/main/skills/prd/SKILL.md): instruction pack · Guides PRD authoring and structure for downstream automation. · `skills/prd/SKILL.md`
- [Ralph skill](https://github.com/sammintah/ralph/blob/main/skills/ralph/SKILL.md): converter skill · Converts a PRD into the structured backlog consumed by the loop. · `skills/ralph/SKILL.md`
- [Backlog schema](https://github.com/sammintah/ralph/blob/main/prd.json.example): example contract · Reference format for the structured story list and pass status. · `prd.json.example`

### Repo memory

Persistent state carried across fresh model runs.

- **progress.txt**: run log · Append-only notes and learnings carried forward between iterations.
- [AGENTS.md](https://github.com/sammintah/ralph/blob/main/AGENTS.md): memory notes · Repository-convention notes that later agents can discover automatically. · `AGENTS.md`
- **Git history**: state ledger · Completed iteration outputs captured as commits in version control.

### Model backends

External AI tools invoked by the loop.

- **Amp CLI**: model runtime · One supported external coding backend, launched fresh each iteration.
- [Claude Code](https://github.com/sammintah/ralph/blob/main/CLAUDE.md): model runtime · Alternative external coding backend launched with clean context each run. · `CLAUDE.md`
- [Amp prompt](https://github.com/sammintah/ralph/blob/main/prompt.md): prompt template · Prompt template shaping Amp-backed execution sessions. · `prompt.md`
- [Claude prompt](https://github.com/sammintah/ralph/blob/main/CLAUDE.md): prompt template · Prompt template shaping Claude Code sessions. · `CLAUDE.md`

### Flowchart UI

Separate browser frontend for visualizing the process.

- [Flowchart UI](https://github.com/sammintah/ralph/blob/main/flowchart/src/App.tsx): react frontend · Vite + React app that visualizes Ralph’s process as a separate subsystem. · `flowchart/src/App.tsx`
- [Build config](https://github.com/sammintah/ralph/blob/main/flowchart/package.json): frontend config · Frontend entry and build setup for the visualization app. · `flowchart/package.json`

### Publishing

Static deployment path for the flowchart app.

- [Deploy workflow](https://github.com/sammintah/ralph/blob/main/.github/workflows/deploy.yml): ci pipeline · Publishes the flowchart frontend through GitHub Actions. · `.github/workflows/deploy.yml`

## Connections

- 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.
