Execute a single Ralph iteration - implement one user story autonomously. Use for manual mode where you want maximum control and fresh context per story. Triggers on: ralph iterate, execute one story, run single iteration, manual ralph.
Execute ONE Ralph iteration - implement a single user story completely, then stop.
This is the manual mode skill. Use this when you want:
For faster execution with batches, use jpralph-auto instead.
prd.json (in project root)progress.txt (check Codebase Patterns section first)branchName. If not, check it out or create from main.passes: falsefeat: [Story ID] - [Story Title]passes: true for the completed storyprogress.txtAPPEND to progress.txt (never replace, always append):
## [Date/Time] - [Story ID]
Chat: [Current chat ID or description]
- What was implemented
- Files changed
- **Learnings for future iterations:**
- Patterns discovered (e.g., "this codebase uses X for Y")
- Gotchas encountered (e.g., "don't forget to update Z when changing W")
- Useful context (e.g., "the evaluation panel is in component X")
---
The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
If you discover a reusable pattern that future iterations should know, add it to the ## Codebase Patterns section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
## Codebase Patterns
- Example: Use `sql<number>` template for aggregations
- Example: Always use `IF NOT EXISTS` for migrations
- Example: Export types from actions.ts for UI components
Only add patterns that are general and reusable, not story-specific details.
Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
Examples of good AGENTS.md additions:
Do NOT add:
Only update AGENTS.md if you have genuinely reusable knowledge that would help future work in that directory.
For any story that changes UI, you MUST verify it works in the browser:
A frontend story is NOT complete until browser verification passes.
After completing a user story, check if ALL stories have passes: true.
If ALL stories are complete and passing, reply with: <promise>COMPLETE</promise>
If there are still stories with passes: false, end your response with:
<promise>DONE</promise>
This signals that this iteration is complete, but more work remains. The user should create a NEW CHAT for the next iteration.
<promise>DONE</promise> when this story is complete<promise>COMPLETE</promise> only if ALL stories are doneWhen you output <promise>DONE</promise>, also provide clear guidance:
Story US-XXX complete! ✅
Remaining stories: [count]
Next story: US-YYY - [title]
To continue:
1. Create a NEW CHAT (for fresh context)
2. Load the jpralph-iterate skill
3. The agent will pick up the next story automatically
This helps the user know exactly what to do next.