| name | loop-prompt-writer |
| description | Write effective prompts for iterative research and Ralph Loop projects. Covers both simple projects (GOAL.md only) and advanced projects (custom role prompts for Builder/Reviewer/Architect). Use when: (1) Writing GOAL.md - "write a goal", "create a prompt", "set up a Ralph project", "write completion criteria", (2) Customizing role prompts - "customize builder prompt", "modify reviewer instructions", "add architectural constraints", "customize role workflow", (3) User mentions "Ralph Wiggum", "Ralph Loop", "iterative development", "bootstrap prompt", "endless loop". Provides templates for GOAL.md and role prompts (BUILDER.md, REVIEWER.md, ARCHITECT.md) with placeholder-based customization.
|
Loop Prompt Writer
Write prompts for iterative systems that self-improve through repeated execution.
Quick Start: GOAL.md
Ralph Loop separates the goal (project-specific) from the workflow (generic prompts).
Ask these questions to write GOAL.md:
- What are you building? (name + one-line description)
- What's the concrete goal? (measurable target)
- When is it "done"? (completion criteria)
Project Structure
project/
├── GOAL.md # Project-specific (EDIT THIS)
├── CLAUDE.md # Development rules
├── config.json # Configuration
└── .project/
└── prompts/ # Role prompts (CAN BE CUSTOMIZED)
├── BUILDER.md # Builder workflow
├── REVIEWER.md # Reviewer instructions
└── ARCHITECT.md # Architect instructions
Key insight: Most projects only need to edit GOAL.md. The default role prompts in .project/prompts/ are generic and reference GOAL.md.
Advanced: For complex projects with specific requirements (e.g., architectural constraints, mandatory code review steps, reference documentation), you can customize the role prompts. See "Customizing Role Prompts" below.
GOAL.md Required Sections
| Section | Purpose |
|---|
| Objective | What we're building (one paragraph) |
| Completion Criteria | Checkboxes that must ALL be true |
| Acceptance Tests | How to verify the project is done |
Optional Sections (by type)
| Type | Add Sections |
|---|
| code | Commands, APIs, Toolchain, Dependencies |
| research | Sources, Techniques, Search Terms |
| creative | Story, Characters, World-building, Style |
| security | Attack Vectors, References, Benchmarks |
Building the Prompt
For detailed step-by-step instructions, see building-prompts.md.
Quick Overview
| Step | What | Why |
|---|
| 1. Header | Endless iterative build pattern | Sets the iteration mindset |
| 2. The Goal | What + constraints + test | Destination, not prescription |
| 3. Architecture | Two-phase or bootstrap patterns (optional) | Only when approach matters |
| 4. Core Principles | 3-5 non-negotiable rules | Guardrails for iteration |
| 5. Project Structure | File organization | Orient the AI |
| 6. The Loop | 6-line cycle definition | Clear iteration steps |
| 7. Critical Questions | 3-5 hard project-specific questions | Prevent checkbox-without-work |
| 8. State File | JSON progress tracking | Machine-parseable state |
| 9. Priority Order | Ordered work phases | What to build when |
| 10. Success Criteria | Completion checkboxes | When is it done? |
| 11. Completion | Signal file creation | How to mark complete |
Anti-Patterns to Avoid
| Anti-Pattern | Why It Fails | Fix |
|---|
| Vague goals | Agent doesn't know when done | Measurable targets |
| Vague checklist items | Checks box without doing work | Specific, measurable criteria |
| No scale questions | System breaks at volume | Add "Does this scale to X?" |
| Empty structure accepted | Boxes checked, content missing | Require populated content |
| No termination | Runs forever | Add promise tag requirement |
| Comments not code | "Do X" vs actual algorithm | Require explicit code/algorithm |
| Long prompts (>200 lines) | Hard to follow | Split into CLAUDE.md rules |
| Too many priorities | Nothing gets done | 4-5 max, ordered |
| Over-specification | AI can't adapt, prompt too rigid | Goal + constraints, not implementation |
| Prescriptive structure | Locks AI into one approach | Let AI discover through iteration |
Quick Reference
Examples (filled-in prompts)
Copy and customize these:
Templates (with placeholders)
Abstract patterns to adapt:
Minimal GOAL.md Template
For simple projects, only edit GOAL.md:
# Project Goal
## Objective
{Brief description of what this project should do when complete}
## Completion Criteria
All of the following must be true for the project to be considered complete:
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3}
## Acceptance Tests
How to verify the project is complete:
1. {Test step 1}
2. {Test step 2}
The generic builder prompt in .project/prompts/BUILDER.md reads this GOAL.md and handles the iteration workflow.
Customizing Role Prompts (Advanced)
For projects with specific architectural requirements, mandatory review steps, or reference documentation, you can customize the role prompts in .project/prompts/.
When to Customize
| Customize If... | Examples |
|---|
| Architectural constraints | "Must use specific patterns", "Provider-agnostic design required" |
| Reference documentation | Links to specs, schemas, API docs that roles should consult |
| Mandatory first steps | "Must review existing code first", "Must read security guidelines" |
| Custom review criteria | Specific checks beyond code working |
| Project-specific workflow | Different iteration process, special state files |
Role Prompt Templates
See assets/role-templates/ for customizable examples:
Placeholders to customize:
{INSERT_PROJECT_SPECIFIC_PRINCIPLES} - Your non-negotiable requirements{INSERT_REFERENCE_DOCS_TABLE} - Links to specs, schemas, API docs{INSERT_FIRST_ITERATION_REQUIREMENTS} - Mandatory first steps (if any){INSERT_ADDITIONAL_STATE_FILES} - Extra state files to read{INSERT_ADDITIONAL_QUALITY_STANDARDS} - Project-specific quality standards{INSERT_ADDITIONAL_REVIEW_STEPS} - Custom review process steps{INSERT_CUSTOM_CRITERIA} - Additional architect review criteria{INSERT_CUSTOM_PASS_FAIL_CRITERIA} - Extra pass/fail rules
Copy these to .project/prompts/ and customize the placeholders for your project.
