ralph wiggum

The Problem

Software teams spend disproportionate time translating informal ideas into concrete specifications, then repeatedly iterating with AI assistants that lack a disciplined loop for self‑correction. The result is missed acceptance criteria, duplicated effort, and unpredictable hand‑off to production.

What This Does

Ralph Wiggum supplies a lightweight “plug‑and‑play” scaffold that lets an AI agent run a closed‑loop development cycle without manual orchestration.

• The template files (templates/constitution-template.md, templates/spec-template.md, templates/checklist-template.md) define a project constitution and a spec format that the AI can read and enforce.
• The Cursor slash‑command definitions (.cursor/commands/speckit.specify.md, .cursor/commands/speckit.implement.md) expose /speckit.specify and /speckit.implement commands to the user’s IDE.
• Two shell drivers – scripts/ralph-loop.sh (for Cursor) and scripts/codex-loop.sh (for OpenAI Codex CLI) – drive the autonomous loop: read a spec, invoke the AI model, evaluate acceptance criteria, and repeat until the criteria are satisfied.

The repository contains no compiled code; all logic lives in these shell scripts and markdown templates. The loop’s “blast radius” is confined to the filesystem (copying templates, writing a spec, committing changes) and to the external AI service invoked by the scripts.

How It Is Wired

Entry points

Control flow (Codex driver example)

1. codex-loop.sh parses command‑line options (--all).
2. It loops over spec files (presumed location .specify/specs/).
3. For each spec, it runs codex (the OpenAI CLI) with the prompt defined in codex-prompts/ralph-all.md.
4. The script captures the model’s output, writes it to the project, and runs a simple acceptance‑check (e.g., grep for a “DONE” marker).
5. If the check fails, the script re‑invokes the model, creating a deep‑nesting control structure (indentation depth 7, measured in static analysis).

External touchpoints

• Filesystem – creates .specify/memory/constitution.md and spec files, writes generated source code, and commits via git.
• AI service – the only network interaction, performed through the Codex CLI or Claude’s /ralph-loop endpoint.

No internal module imports exist; the repository consists solely of shell scripts and markdown, so there are no circular dependencies or internal call graphs to manage.

How To Use It

# 1. Clone the scaffold
git clone https://github.com/moses-y/ralph-wiggum
cd ralph-wiggum

# 2. Copy scaffold into the target project (example assumes you are in the target repo)
mkdir -p .specify/memory .specify/specs templates scripts .cursor/commands
cp templates/constitution-template.md .specify/memory/constitution.md
cp templates/spec-template.md templates/checklist-template.md .
cp .cursor/commands/speckit.* .cursor/commands/
cp scripts/ralph-loop.sh scripts/codex-loop.sh scripts/setup*.sh scripts/
chmod +x scripts/*.sh

Create a specification – in the target project, run the Cursor command or edit a markdown file under .specify/specs/ using the spec-template.md format.

Run the loop –

# For Cursor
./scripts/ralph-loop.sh

# For Codex CLI (all specs)
./scripts/codex-loop.sh --all

The script will iterate until the generated code satisfies the acceptance criteria defined in the spec.

Real‑World Use

A product team defines a new “OAuth login” feature in .specify/specs/oauth.md using the provided spec template. An AI assistant, triggered via /speckit.implement, runs codex-loop.sh, produces the authentication module, runs the built‑in checklist, and commits the result automatically. The team reviews the generated constitution.md to ensure policy compliance before merging.

Code Health & Issues

• Medium – Deep nesting – scripts/codex-loop.sh reaches a maximum indentation depth of 7, making the control flow hard to follow. Refactoring with early returns or extracting inner blocks would improve readability.
• Missing CI/CD – No .github/ workflows, Dockerfile, or other automation; tests exist (*_test.sh) but are not gated by a CI pipeline.
• No lockfile – No package-lock.json or equivalent, so reproducible dependency installation is not guaranteed.
• License – MIT license present (LICENSE).
• No committed secrets – Static scan found none.

The Bottom Line

Ralph Wiggum delivers a minimal, script‑driven framework that lets AI agents perform spec‑driven, autonomous coding cycles with Claude or Codex. It is easy to embed in any repository but currently lacks automated testing integration and suffers from a deeply nested shell script that hampers maintenance. Suitable for teams experimenting with AI‑augmented development who can accept the manual setup and are prepared to add CI and refactor the driver scripts for production use.