convez.ai
AgenteAutomaçãoIntermediário
armarquez

Ralph Scaffold

armarquez/ralph-scaffold

Scaffold para agentes IA autônomos executarem loops de coding estruturados

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework agnóstico para implementar o Ralph loop — metodologia de agente IA autônomo para coding. Integra-se com Claude Code, OpenHands, Amp e qualquer CLI de agent, fornecendo orquestração de tarefas, execução de testes e circuit breakers automáticos.

Instalação

$npx convez-ai armarquez/ralph-scaffold

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automatizar desenvolvimento de features com agentes IA
  • Orquestrar múltiplas iterações de coding com circuit breakers
  • Integrar agentes IA em pipelines CI/CD de projetos existentes

Veredito

Solução técnica madura para instrumentar agentes IA em loops de desenvolvimento. Reduz fricção ao integrar Claude Code e similares em projetos reais, com gestão de estado e proteções contra loops infinitos.

README

A tradução para o português deste README ainda está na fila.

ralph-scaffold

A tool-agnostic scaffold for the Ralph loop — the autonomous AI coding agent methodology. Drop it into any project and hand it to Claude Code, OpenHands, Amp, or any agent CLI.

What is this?

The Ralph loop is a structured approach to autonomous coding: the agent reads a task list, implements one task at a time, runs tests, commits, and repeats. ralph-scaffold gives you:

  • task_runner.py — reads/writes prd.json state: next task, mark complete, mark blocked
  • ralph.py — loop runner: calls your agent CLI, checks progress, enforces circuit breakers
  • pre-commit hook — blocks commits when tests fail
  • PROMPT.md / AGENTS.md — agent-readable context templates
  • just onboard <path> — one command to scaffold a project and get a setup checklist

Prerequisites

  • mise — manages Python, uv, and just (install once: curl https://mise.run | sh)
  • just — installed automatically via mise install
  • Python 3.12+ — installed automatically via mise install
  • uv — installed automatically via mise install
  • A git repo to install into
  • An agent CLI (Claude Code, OpenHands, Amp, etc.)

Quickstart

Step 1 — Clone and install tools:

git clone https://github.com/armarquez/ralph-scaffold
cd ralph-scaffold
mise install        # installs Python 3.12, uv, and just
just install        # syncs dev deps and wires the pre-commit hook

Step 2 — Onboard your project:

just onboard /path/to/your-project

This copies the scaffold files and prints a checklist of what to fill in next. Run just setup /path/to/your-project any time to reprint the checklist.

Step 3 — Fill in the templates and run:

Follow the checklist from Step 2, then:

cd /path/to/your-project
just status     # verify task list loaded correctly
just ralph      # dry-run to preview what the loop would call
just loop       # start the loop (calls your agent until all tasks pass)

File Reference

PathPurpose
install.shEntry point: copies scaffold into target project
scaffold/scripts/ralph.pyLoop runner — calls agent, checks exit gate, circuit breaker
scaffold/scripts/task_runner.pyprd.json state machine
scaffold/hooks/pre-commitGit hook: runs just check or .ralphrc.json test_cmd
scaffold/.ralph/PROMPT.mdAgent instructions template
scaffold/.ralph/AGENTS.mdBuild/test/lint commands template
scaffold/prd.json.exampleAnnotated prd.json template
scaffold/justfile.examplejustfile template with EDIT THIS markers
scaffold/.mise.toml.example.mise.toml template with tool pins
prd.jsonThis repo's own task list (self-hosting example)
.ralph/This repo's own filled-in agent context

How the Loop Works

flowchart TD
    A[ralph.py starts] --> B[read .ralphrc.json]
    B --> C[task_runner.py next]
    C --> D{done?}
    D -- yes --> E[exit 0]
    D -- no --> F[shell out to agent_cmd]
    F --> G[check git diff]
    G --> H[append progress.txt]
    H --> I{circuit breaker?}
    I -- tripped --> J[exit 2]
    I -- ok --> K{max_loops?}
    K -- hit --> J
    K -- ok --> C
  • Circuit breaker opens after N loops with no file changes (no_progress_threshold) or N loops with the same error output (same_error_threshold).
  • Exit gate is checked each loop via task_runner.py next. When all non-optional tasks have passes: true, it returns {"done": true} and the loop exits cleanly.

Contributing

  1. Fork the repo
  2. Run mise install to get Python, uv, and just
  3. Run just install to install dev deps and wire the pre-commit hook
  4. Work through TASKS.md top-to-bottom
  5. Run just check before every commit
  6. Open a PR against main
Ver o original no GitHub

Bom para

Relacionados