Ralph Loop for Kiro Specs
The Problem
Section titled “The Problem”You designed the spec in Kiro IDE — requirements, design, tasks, everything structured. Now you need to implement it. Task by task, prompt by prompt, manually reviewing each output. With 15 tasks, that’s 15 cycles of copying a prompt, pasting it in the terminal, checking the result, fixing the error, trying again.
And when the agent makes the same mistake on task 8 that it already made on task 3? You fix it again. And again on task 12.
The Solution
Section titled “The Solution”Ralph Loop takes the specs you created in Kiro IDE and executes them automatically via kiro-cli. One command, and it implements task by task until done — or until you tell it to stop.
The difference: Ralph learns from its own mistakes. If task 3 discovers the project uses npm run test:unit instead of npm test, task 4 already knows that before it starts. Corrections are logged immediately and re-read on every iteration.
Based on ralph-loop-kiro-specs by mreferre, licensed under Apache License 2.0.
When to Use
Section titled “When to Use”- Specs ready in Kiro IDE that need to be implemented via CLI
- Projects with many tasks where manual execution is repetitive
- Specs where the agent needs to respect existing codebase patterns
- Situations where errors repeat across tasks and you want the agent to stop making them
Installation
Section titled “Installation”npx skills add https://gitlab.com/fabriciotelles/skills -s ralph-loop-kiro-specsHow It Works
Section titled “How It Works”One command starts the loop. Each iteration implements exactly one task — never more, never less.
graph LR
A[1. Load Context] --> B[2. Pick ONE Task]
B --> C[3. Understand]
C --> D[4. Implement]
D --> E[5. Verify Exit Criteria]
E --> F[6. Update Tracking]
F -->|Tasks remain| B
F -->|All complete| G[Generate Dashboard]
What happens in each iteration
Section titled “What happens in each iteration”- Load Context — Reads README, docs, steering files, and the full spec
- Pick ONE Task — Finds the next incomplete task. One at a time, no shortcuts
- Understand — Reads existing code, studies patterns, and re-reads all accumulated corrections
- Implement — Implements the task and subtasks. If something fails, logs the correction immediately
- Verify — Confirms each exit criterion before marking as complete
- Track — Marks
[X], records progress, discovered patterns, and time spent
The self-correction system
Section titled “The self-correction system”Every error becomes an entry in progress.md:
- ❌ `npm test` → ✅ `npm run test:unit` (project uses separate test scripts)- ❌ import without extension → ✅ `from 'lib/index.js'` (ESM requires explicit extension)The next iteration reads this list before touching any code. Errors don’t repeat.
At the end: a dashboard
Section titled “At the end: a dashboard”When all tasks are complete, Ralph generates a self-contained summary.html with overall status, a collapsible task tree with hover details, and a per-task timing table.
./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>| Argument | Description |
|---|---|
max_iterations | Maximum iterations. Set to at least the number of tasks + buffer for retries. |
specs_name | Name of the spec directory under .kiro/specs/ |
# Implement the "auth-feature" spec in up to 15 iterations./ralph-loop-kiro-specs-script.sh 15 auth-featureYou choose between automatic mode (tasks run without pausing) or manual mode (pauses between each task for review).