/ralph-loop-kiro-specs

name: ralph-loop-kiro-specs
description: >-
  Automated iterative agent runner for spec-based development in Kiro. Wraps kiro-cli in a
  self-correcting bash loop that picks up tasks from a Kiro spec, implements them one at a time,
  verifies against exit criteria, and accumulates corrections and codebase patterns across iterations.
  Use this skill when the user mentions "ralph loop", "ralph", "spec loop", "iterative spec runner",
  "run my spec tasks automatically", "kiro spec automation", "self-correcting agent loop",
  "implement spec tasks in a loop", "run kiro-cli in a loop", "automated task implementation",
  or wants to drive a Kiro spec to completion through repeated agent iterations. Also use when the
  user wants to set up, configure, troubleshoot, or understand the Ralph Loop workflow — including
  progress tracking, corrections, codebase patterns, timing logs, and the summary dashboard.
metadata:
  author: ft.ia.br
  version: "1.0"
  date: 2026-04-28
  license: Apache-2.0
  original_project: https://github.com/mreferre/ralph-loop-kiro-specs
  original_author: mreferre
  category: code-scaffolding-and-templates

Ralph Loop for Kiro Specs

An automated, iterative agent runner that drives spec-based development in [Kiro](https://kiro.dev). It wraps `kiro-cli` in a bash loop, feeding it a carefully engineered prompt that turns Kiro into a disciplined, self-correcting implementation agent — one that picks up tasks from a spec, implements them, verifies its own work, and learns from its mistakes across iterations.

> **Attribution:** Based on [ralph-loop-kiro-specs](https://github.com/mreferre/ralph-loop-kiro-specs) by [mreferre](https://github.com/mreferre), licensed under Apache License 2.0.

When to Use

• Automate implementation of Kiro spec tasks through repeated agent iterations
• Drive a spec from start to finish without manual prompt-by-prompt interaction
• Set up the Ralph Loop in a new project
• Troubleshoot a stuck or failed Ralph Loop run
• Understand how progress tracking, corrections, and codebase patterns work
• Generate or interpret the summary dashboard after completion

Prerequisites

| Requirement | Details | |---|---| | Kiro CLI | `kiro-cli` must be installed and on `PATH` ([kiro.dev/cli](https://kiro.dev/cli/)) | | Kiro IDE | [kiro.dev](https://kiro.dev/) installed | | Bash | Standard bash shell | | Kiro Specs | A project with specs under `.kiro/specs/<specs_name>/` containing at least `requirements.md`, `design.md`, and `tasks.md` |

How It Works

Ralph runs a loop where each iteration sends a prompt to `kiro-cli`. The prompt instructs the agent to follow a strict six-phase cycle:

The Six Phases

1. **Load Context** — Read steering files (`product.md`, `structure.md`, `tech.md`) and the target spec (`requirements.md`, `design.md`, `tasks.md`, `progress.md`). Take stock of available tools. 2. **Pick ONE Task** — Find the lowest-numbered incomplete top-level task. Record start time. Never pick more than one task per iteration. 3. **Understand Before Implementing** — Read relevant source files, study existing patterns, re-read the Corrections and Codebase Patterns sections from `progress.md`, and apply every relevant correction proactively. 4. **Implement** — Implement the task and all subtasks in order. Run typechecks and tests. If something fails: fix it, write a correction immediately if a future iteration could hit the same problem, and move on. After 5 failed attempts, mark the task `[F]` and log an unresolved blocker. 5. **Verify Exit Criteria** — Re-read exit criteria from `requirements.md` and design constraints from `design.md`. Confirm each is satisfied before marking complete. 6. **Update Tracking** — Mark the task `[X]` in `tasks.md`, append a progress entry to `progress.md`, add new codebase patterns, do a final correction sweep, and record timing to `specs_time.md`.

The Self-Correction System

The Corrections section at the top of `progress.md` is a flat lookup table of mistakes and their fixes. Every iteration reads it before doing any work and must never repeat a listed mistake. Corrections are written immediately when errors happen — not at the end of the task.

Format:

- ❌ `python manage.py migrate` → ✅ `python3 manage.py migrate` (system has no `python` alias)
- ❌ Running tests with `npm test` → ✅ `npm run test:unit` (project uses separate test scripts)
- ❌ UNRESOLVED: [description of issue that couldn't be fixed after 5 attempts]

Codebase Patterns

Ralph accumulates conventions discovered during implementation — file naming, import patterns, error handling, testing commands, etc. Only patterns actually encountered are recorded, not speculative ones.

Completion and Summary Dashboard

When all tasks are marked `[X]`, Ralph generates a self-contained `summary.html` in the spec directory with:

• **Top pane**: spec name, status indicator (green/red), total elapsed time, task count, date range
• **Left pane**: collapsible task tree with hover tooltips showing progress details
• **Right pane**: timing table with per-task start/end times and durations

Project Structure

The user's project should look like this before running Ralph:

your-project/
├── ralph-loop-kiro-specs-prompt.md    # The Ralph agent prompt template
├── ralph-loop-kiro-specs-script.sh    # The loop runner script
└── .kiro/
    ├── steering/
    │   ├── product.md                 # What the product is
    │   ├── structure.md               # Project structure conventions
    │   └── tech.md                    # Tech stack and tooling
    └── specs/
        └── <specs_name>/
            ├── requirements.md        # Requirements and exit criteria
            ├── design.md              # Architecture and design decisions
            ├── tasks.md               # Task checklist
            ├── progress.md            # Auto-created: corrections, patterns, progress log
            ├── specs_time.md          # Auto-created: per-task tim