tim/SlipItIn
1
0
Fork 0
Code Pull Requests 1 Actions 1 Packages Releases Wiki Activity

Neue Skills, Referenzen & OpenWiki-Doku integriert

Browse Source 
Umfangreiche Erweiterung der Skill-Bibliothek: Neue Skills für Humanisierung (Englisch/PT-BR), Design-Validierung, AI-SEO und Coolify-Deployment inkl. Regelwerke, Presets, Pattern-Referenzen, Testfälle und Automatisierungsskripte. Zusätzliche Skills für Revenue-Centric Design, Pier Cloud, OKF, Lebenslauf- und LinkedIn-Optimierung sowie zahlreiche Referenzdateien, Checklisten und YAML/JSON/Markdown-Templates. Einführung einer vollständigen OpenWiki-Dokumentation mit Architektur-, Domain- und Workflow-Beschreibungen, zentralem Index und automatisierten Updates. Modularer Aufbau, restriktive Lizenzen und umfassende Qualitäts- und Evaluationsmechanismen für alle neuen Inhalte.
This commit is contained in:
Tim Krampitz
2026-07-26 14:00:58 +02:00
parent 070727d5cd
commit 01046b01e4
202 changed files with 31290 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
.github/skills/ralph-loop-kiro-specs/SKILL.md vendored Normal file
View File

@@ -0,0 +1,200 @@
---
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 timing
└── summary.html # Auto-generated on completion: visual dashboard
```
## Setup Instructions
To set up Ralph Loop in a project:
1. Copy the script and prompt template to the project root:
- `ralph-loop-kiro-specs-script.sh` — the loop runner (bundled in this skill under `scripts/`)
- `ralph-loop-kiro-specs-prompt.md` — the agent prompt template (bundled under `references/`)
2. Make the script executable: `chmod +x ralph-loop-kiro-specs-script.sh`
3. Ensure the project has Kiro specs set up under `.kiro/specs/<specs_name>/` with at least `requirements.md`, `design.md`, and `tasks.md`
4. Ensure steering files exist under `.kiro/steering/` (`product.md`, `structure.md`, `tech.md`) — these significantly improve output quality
## Usage
```bash
./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>
```
| Argument | Description |
|---|---|
| `max_iterations` | Maximum number of loop iterations (positive integer). Each iteration implements one task. Set to at least the number of tasks plus a buffer for retries. |
| `specs_name` | Name of the spec directory under `.kiro/specs/`. Must already exist with the required files. |
### Example
```bash
# Run up to 15 iterations on the "auth-feature" spec
./ralph-loop-kiro-specs-script.sh 15 auth-feature
```
### Iteration Modes
The script asks at startup whether to run automatically or manually:
- **Automatic** — Tasks run back-to-back without pausing. Good for well-defined specs.
- **Manual** — Pauses after each iteration for review. Good for new or unfamiliar specs.
## Troubleshooting
### Ralph gets stuck on a task (marked `[F]`)
Fix the issue manually, update `tasks.md` to unmark the task, and re-run. The corrections from the failed attempt will still be in `progress.md` for the next iteration to learn from.
### Max iterations reached without completion
Increase `max_iterations` and re-run. Ralph will pick up where it left off since it reads `tasks.md` to find the next incomplete task.
### Agent implements more than one task per iteration
This violates the core constraint. Check that you're using the unmodified prompt template. The prompt has a critical constraint section at the top that enforces one-task-per-iteration.
### Steering files are missing
Ralph works without them but produces better results with context. Create `.kiro/steering/product.md`, `structure.md`, and `tech.md` with descriptions of your product, project structure, and tech stack.
## Quality Checklist
Before running Ralph Loop, verify:
- [ ] `kiro-cli` is installed and available on `PATH`
- [ ] Spec directory exists under `.kiro/specs/<specs_name>/`
- [ ] `requirements.md` has numbered requirements with exit criteria
- [ ] `design.md` has architecture and design decisions
- [ ] `tasks.md` has a numbered task checklist with subtasks
- [ ] Steering files exist under `.kiro/steering/` (recommended)
- [ ] `max_iterations` is set to at least the number of tasks + buffer
- [ ] The prompt template (`ralph-loop-kiro-specs-prompt.md`) is in the project root
- [ ] The script (`ralph-loop-kiro-specs-script.sh`) is executable
## Bundled Resources
| Resource | Path | Description |
|---|---|---|
| Runner script | `scripts/ralph-loop-kiro-specs-script.sh` | The bash loop that drives iterations. Copy to project root. |
| Prompt template | `references/ralph-loop-kiro-specs-prompt.md` | The agent prompt template. Copy to project root. |
Read the prompt template when you need to understand the detailed phase instructions, correction format, codebase pattern categories, or the summary dashboard specification.
## License
This skill is based on [ralph-loop-kiro-specs](https://github.com/mreferre/ralph-loop-kiro-specs) by [mreferre](https://github.com/mreferre), licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
```
Copyright [mreferre]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

246
.github/skills/ralph-loop-kiro-specs/references/ralph-loop-kiro-specs-prompt.md vendored Normal file
View File

@@ -0,0 +1,246 @@
# Ralph Agent Instructions
> 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.
## ⛔ CRITICAL CONSTRAINT — READ THIS FIRST
You must implement exactly ONE top-level task per invocation. This is non-negotiable.
- ONE top-level task means: a single root-level item (e.g., `1.`, `2.`, `3.`) and all of its subtasks (e.g., `2.1`, `2.2`, `2.3`).
- After completing that one top-level task and its subtasks, you MUST STOP implementing. Do not continue to the next top-level task. Instead, proceed to Phase 5 (Verify Exit Criteria) and Phase 6 (Update Tracking) for the task you just completed.
- Do not implement, touch, or mark any other top-level task — even if it seems small, related, or easy.
- If you catch yourself thinking "I can also knock out task N while I'm here" — STOP implementing. That is exactly the behavior this rule prohibits. Move on to verification and tracking for your one task.
- Violating this constraint invalidates the entire run.
## Phase 1: Load Context
Read the following files to understand the project. Skip any that don't exist.
1. `README.md` — read the project README for high-level context about the project's purpose, setup, and conventions
2. `docs/` folder — if it exists, scan for any additional documentation, ADRs, or context relevant to the spec
3. `.kiro/steering/product.md` — what the product is
4. `.kiro/steering/structure.md` — project structure conventions
5. `.kiro/steering/tech.md` — tech stack and tooling
6. `.kiro/specs/SPECS_NAME/requirements.md` — requirements and exit criteria
7. `.kiro/specs/SPECS_NAME/design.md` — architecture and design decisions
8. `.kiro/specs/SPECS_NAME/tasks.md` — the task list to implement
9. `.kiro/specs/SPECS_NAME/progress.md` — **read the top sections (Corrections and Codebase Patterns) FIRST and internalize them before doing anything else**, then review past progress entries
## Tool Awareness
After loading context, take stock of what tools are available to you in this environment (e.g., MCP servers, CLI utilities, linters, formatters, test runners, build tools). You are not required to use any of them — but knowing what's available may inform better decisions during implementation and verification. Use your judgment: if a tool would genuinely help with the current task, use it. If not, don't force it.
## Phase 2: Pick ONE Task
Capture the task start time by running these two shell commands and saving their output:
```bash
date '+%Y-%m-%d %H:%M:%S'
date +%s
```
The first gives you the human-readable start timestamp for the time log. The second gives you the epoch seconds — you will need both later in Phase 6 to compute elapsed time accurately.
1. Find the lowest-numbered **top-level** task in `tasks.md` that is NOT marked with `[X]`. A top-level task is one at the root indentation level (e.g., `- [ ] 1.`, `- [ ] 2.`). Subtasks nested under a top-level task (e.g., `1.1`, `1.2`) are NOT independent tasks — they are part of their parent and will be implemented together with it.
2. Read the requirement(s) and exit criteria referenced by that task in `requirements.md`
3. Read the relevant design details in `design.md`
4. Do NOT pick more than one top-level task. You implement exactly one top-level task (including all of its subtasks) per invocation. You must NOT mark any other top-level task as complete — only the one you pick here.
## Phase 3: Understand Before Implementing
Before writing any code:
1. Read the existing source files that are relevant to the task
2. Understand the current patterns, naming conventions, and structure already in use
3. **Re-read the Corrections section** at the top of `progress.md` with your chosen task in mind. Every entry there is a mistake a previous iteration already made and fixed. Do not repeat them. Apply every relevant correction proactively to the task you are about to implement.
4. Re-read the Codebase Patterns section in `progress.md` with your chosen task in mind — follow any patterns relevant to this task
## Phase 4: Implement
1. Implement the task and all its subtasks in their specified order
2. Follow the project's existing conventions and patterns
3. After implementation, run typecheck and tests as applicable to the project
4. If a command fails or a test breaks:
a. Fix the issue
b. **Immediately ask yourself: "Could a future iteration hit this same problem?"** If yes, add it to the Corrections section at the top of `progress.md` RIGHT NOW, before continuing. Do not wait until the end.
c. If you cannot resolve a failure after 5 attempts, add it to the Corrections section as an unresolved blocker, mark the task as failed in `tasks.md` (e.g., `[F]`), and move on to Phase 6 to record what happened. Do NOT mark the task with `[X]`.
5. **STOP CHECK:** You have now finished implementing your one top-level task. Do NOT proceed to implement any other top-level task. Go directly to Phase 5.
## Phase 5: Verify Exit Criteria
Before marking the task complete:
1. Re-read the exit criteria from `requirements.md` for this task and confirm each one is satisfied.
2. Re-read the relevant design details from `design.md` and confirm the implementation conforms to the specified architecture, patterns, and constraints.
3. If any exit criteria or design constraints are not met, go back and address them.
## Phase 6: Update Tracking
1. In `tasks.md`, mark ONLY the single task you just completed (and its direct subtasks) with `[X]`. **Do NOT mark any other tasks as complete.** When editing `tasks.md`, use a surgical edit (e.g., find-and-replace on the specific task line) rather than rewriting the entire file. If you rewrite the file, you MUST preserve the exact checkbox state (`[ ]` or `[X]`) of every task you did NOT work on. Double-check the file after editing to confirm no other tasks were accidentally marked.
2. Append a progress entry to `progress.md` (see format below)
3. If you discovered a reusable codebase pattern, add it to the Codebase Patterns section in `progress.md`
4. Final sweep: if you hit ANY error during this task that you haven't already added to Corrections, add it now. If you followed Phase 4 step 4b faithfully, this step should be a no-op.
5. Capture the task end time by running these two shell commands:
```bash
date '+%Y-%m-%d %H:%M:%S'
date +%s
```
The first gives you the human-readable end timestamp. The second gives you the epoch seconds.
Compute elapsed time by subtracting the start epoch (captured in Phase 2) from the end epoch:
```bash
echo $(( END_EPOCH - START_EPOCH ))
```
Convert the result to `Xm Ys` format (e.g., if the difference is 754 seconds → `12m 34s`).
Append a row to `SPECS_NAME/specs_time.md` in this format:
```
| [Task ID] | [Start time] | [End time] | [Elapsed time] |
```
Use `YYYY-MM-DD HH:MM:SS` for timestamps and `Xm Ys` for elapsed time.
## Progress Entry Format
Append to the bottom of `progress.md`:
```
## [Date] - [Task ID]: [Brief description]
- What was implemented
- Files changed
- Tools used (list any non-default tools you chose to use and why, e.g., "Used MCP linter to validate schema — caught a missing required field")
- Patterns discovered (list here; if reusable, must also be added to the Codebase Patterns section)
- Corrections added (list here; must already exist in the Corrections section — if not, add them there now)
---
```
Note: The Corrections and Codebase Patterns sections at the top of the file are the canonical reference. Progress entries provide a chronological record and should cross-reference what was added to those sections, not replace them.
## Corrections
Maintain a `# Corrections` section at the VERY TOP of `progress.md`, above Codebase Patterns. This is a flat lookup table of mistakes that have already been made and their fixes. Every iteration must read this section before doing any work, and must never repeat a listed mistake.
Each entry follows this format — short, scannable, no prose:
```
- ❌ `python manage.py migrate` → ✅ `python3 manage.py migrate` (system has no `python` alias)
- ❌ `import { foo } from 'lib'` → ✅ `import { foo } from 'lib/index.js'` (ESM requires explicit extensions)
- ❌ Creating migration without IF NOT EXISTS → ✅ Always use IF NOT EXISTS (prevents re-run failures)
- ❌ Running tests with `npm test` → ✅ `npm run test:unit` (project uses separate test scripts)
- ❌ UNRESOLVED: [description of issue that couldn't be fixed after 3 attempts]
```
**When to write a correction:** Any time you encounter an error, a failed command, a wrong assumption, or a workaround — anything where your first attempt was wrong and you had to adjust. Write it immediately when it happens, not at the end of the task.
**What makes a good correction:**
- Wrong CLI command or binary name
- Missing flags, env vars, or config needed for a command to work
- Import path or module resolution issues
- API or library usage that differs from what you assumed
- File paths or naming conventions you got wrong
- Build/test/lint commands that need specific arguments
- Platform-specific gotchas (OS, runtime version, etc.)
- Any assumption that turned out to be false
## Codebase Patterns
Maintain a `# Codebase Patterns` section in `progress.md`, immediately below the Corrections section. These patterns are critical — they prevent future iterations from repeating mistakes or deviating from established conventions.
Only record patterns you actually encounter or use during implementation. The categories below are a reference for what kinds of patterns to watch for — do not try to fill them all out proactively:
**Project Structure & Modules**
- File/folder naming conventions (kebab-case, PascalCase, etc.)
- Where new files of each type should go (components, services, utils, handlers, etc.)
- Module/package organization (barrel exports, index files, __init__.py, mod.rs, etc.)
- Monorepo structure (which packages depend on which, shared libs)
**Language & Type System**
- Preferred language idioms (e.g., guard clauses vs nested ifs, early returns)
- Type annotation style (interfaces vs types in TS, type hints in Python, generics usage)
- Null/optional handling (Optional<T>, Maybe, nullable types, Result/Either patterns)
- Enum patterns (string enums, const objects, sealed classes)
- Async patterns (async/await, Promises, Futures, goroutines, channels)
**Error Handling**
- Custom error classes/types and hierarchy
- How errors propagate (thrown exceptions, Result types, error codes, middleware)
- Logging conventions (structured logging, log levels, which logger library)
- User-facing vs internal error messages
**Data & State**
- Database migration conventions (IF NOT EXISTS, up/down migrations, naming)
- ORM/query patterns (repository pattern, active record, raw queries)
- State management approach (Redux, Zustand, Vuex, signals, MobX, context, providers)
- Data validation (schemas, decorators, guard functions, where validation lives)
- Serialization/deserialization patterns (DTOs, transformers, codable, serde)
- Caching strategy (what's cached, TTLs, invalidation approach)
**API & Communication**
- API style (REST, GraphQL, gRPC, tRPC) and conventions (route naming, versioning)
- Request/response shapes and envelope patterns
- Authentication/authorization patterns (middleware, guards, decorators, policies)
- Client-server contract (shared types, generated clients, OpenAPI)
- Event/message patterns (pub/sub, event bus, message queues, webhooks)
**Frontend & UI**
- Component structure (functional vs class, composition patterns, slots/children)
- Styling approach (CSS modules, Tailwind, styled-components, SCSS, utility classes)
- Form handling (controlled/uncontrolled, form libraries, validation)
- Routing patterns (file-based, config-based, nested routes, guards)
- Accessibility patterns the project follows (ARIA usage, focus management, semantic HTML)
- Internationalization approach (i18n library, key naming, where translations live)
**Backend & Infrastructure**
- Dependency injection approach (constructor injection, containers, providers)
- Middleware/interceptor patterns and ordering
- Background job/worker patterns
- Configuration management (env vars, config files, secrets handling)
- Database connection and transaction patterns
**Testing**
- Test file location and naming (co-located, __tests__, .spec vs .test)
- Test setup/teardown patterns (fixtures, factories, builders, seeds, mocks)
- Mocking approach (which libraries, what gets mocked, test doubles)
- Assertion style (expect, assert, should)
- How to run tests (commands, flags, environment variables needed)
- Integration/E2E test conventions
**Build & Tooling**
- Build commands and flags that work
- Environment-specific gotchas (env vars, feature flags, platform differences)
- Linting/formatting commands and any suppressions in use
- Code generation steps (protobuf, GraphQL codegen, ORM models, OpenAPI)
## Stop Condition
After completing your one task, check if ALL tasks in `tasks.md` are marked `[X]`.
If all tasks are complete:
1. Build an HTML page at `.kiro/specs/SPECS_NAME/summary.html` that presents a readable, multi-pane summary of the entire spec implementation. The page should be a single self-contained HTML file (inline CSS and JS, no external dependencies). The page should be styled against the https://kiro.dev web site. Structure it as follows:
**Page title:**
- Use "Ralph Loop for Kiro Specs" as the static page title (in `<title>` and as the main heading).
**Top pane — Global Summary:**
- Display the spec name (SPECS_NAME) prominently as a field in this pane.
- Show a visual status indicator: green if all tasks are marked `[X]` (fully implemented), red if any tasks are marked `[F]` or unchecked (partial/failed).
- If green: show the total elapsed time for the entire flow (sum of all task durations from `specs_time.md`), the number of tasks completed, and the date range (first task start to last task end).
- If red: show how many tasks completed vs total, which tasks failed or remain incomplete, and any unresolved corrections from `progress.md`.
- Show counts for files changed, corrections logged, and patterns discovered — but display only the counts as summary numbers. The full details of corrections and patterns should be hidden behind collapsible `<details>/<summary>` elements that the user can expand if they want to dig in. Keep the default state collapsed.
**Left pane — Task Tree:**
- Render the task list from `tasks.md` as a collapsible tree. Top-level tasks are tree nodes; subtasks are nested children.
- Each node should be expandable/collapsible (click to toggle). It should be explicit if a tree node has children or not.
- On mouse hover over any task or subtask, show a tooltip or popover with the relevant progress details from `progress.md` for that task: what was implemented, files changed, tools used, patterns discovered, and corrections added. Match tasks to progress entries by task ID.
- Use visual indicators for task status: `[X]` = completed, `[F]` = failed, unchecked = incomplete.
**Right pane — Timing:**
- Render the timing data from `specs_time.md` as an HTML table (task ID, start time, end time, elapsed time).
**Styling:**
- Clean, modern CSS. Use a side-by-side layout (e.g., flexbox) with the task tree taking roughly 60% width and the timing table taking 40%.
- The tooltip/popover should be readable and not clip off-screen.
2. Reply with:
```
<promise>COMPLETE</promise>
```
If tasks remain, end normally after completing your one task.

128
.github/skills/ralph-loop-kiro-specs/scripts/ralph-loop-kiro-specs-script.sh vendored Normal file
View File

@@ -0,0 +1,128 @@
#!/bin/bash
set -e
# Ralph Loop for Kiro Specs — Runner Script
# Based on https://github.com/mreferre/ralph-loop-kiro-specs
# Licensed under Apache License 2.0
#
# Usage: ./ralph-loop-kiro-specs-script.sh <max_iterations> <specs_name>
# ── Color & style codes ──
RED='\033[1;31m'
GREEN='\033[1;32m'
YELLOW='\033[1;33m'
BLUE='\033[1;34m'
CYAN='\033[1;36m'
MAGENTA='\033[1;35m'
BOLD='\033[1m'
DIM='\033[2m'
NC='\033[0m' # No Color
MAX_ITERATIONS=${1:-10}
SPECS_NAME=${2:-}
if [ -z "$SPECS_NAME" ]; then
echo -e "${RED}❌ Usage: $0 <max_iterations> <specs_name>${NC}" >&2
exit 1
fi
# Validate MAX_ITERATIONS is a positive integer
if ! [[ "$MAX_ITERATIONS" =~ ^[1-9][0-9]*$ ]]; then
echo -e "${RED}❌ Error: <max_iterations> must be a positive integer, got '${BOLD}$MAX_ITERATIONS${RED}'${NC}" >&2
exit 1
fi
# Validate SPECS_NAME is a non-empty string (no whitespace-only)
if ! [[ "$SPECS_NAME" =~ [^[:space:]] ]]; then
echo -e "${RED}❌ Error: <specs_name> must be a non-empty string${NC}" >&2
exit 1
fi
SCRIPT_DIR="$(cd "$(dirname \
"${BASH_SOURCE[0]}")" && pwd)"
# Set the specs directory path based on the provided specs name
SPECS_DIR="$SCRIPT_DIR/.kiro/specs/$SPECS_NAME"
# Check if the specs directory exists, exit with error if not found
if [ ! -d "$SPECS_DIR" ]; then
echo -e "${RED}❌ Error: No specs named '${BOLD}$SPECS_NAME${RED}' found in this project${NC}" >&2
exit 1
fi
# Initialize progress log file if it doesn't exist
if [ ! -f "$SPECS_DIR/progress.md" ]; then
echo "# Progress Log for spec: $SPECS_NAME" \
> "$SPECS_DIR/progress.md"
echo -e "${DIM}📝 Created progress.md${NC}"
fi
# Initialize time log file if it doesn't exist
TIME_LOG="$SPECS_DIR/specs_time.md"
if [ ! -f "$TIME_LOG" ]; then
echo "# Time Log for spec: $SPECS_NAME" > "$TIME_LOG"
echo -e "${DIM}📝 Created specs_time.md${NC}"
fi
# Load the prompt template and substitute the specs name placeholder
PROMPT=$(sed "s/SPECS_NAME/$SPECS_NAME/g" \
"$SCRIPT_DIR/ralph-loop-kiro-specs-prompt.md")
echo ""
echo -e "${MAGENTA}══════════════════════════════════════${NC}"
echo -e " 🚀 ${BOLD}Starting Ralph${NC}"
echo -e " ${DIM}spec:${NC} ${CYAN}$SPECS_NAME${NC}"
echo -e " ${DIM}iterations:${NC} ${CYAN}$MAX_ITERATIONS${NC}"
echo -e "${MAGENTA}══════════════════════════════════════${NC}"
echo ""
# Ask user for iteration mode
read -r -p "$(echo -e "${YELLOW}🔄 Iterate automatically through tasks? (y/n):${NC} ")" AUTO_MODE
case "$AUTO_MODE" in
[yY]|[yY][eE][sS])
AUTO_MODE=true
echo -e " ${GREEN}✔ Auto-pilot enabled${NC}"
;;
*)
AUTO_MODE=false
echo -e " ${BLUE}✔ Manual mode — you'll confirm each iteration${NC}"
;;
esac
echo ""
echo -e "${CYAN}─── 📋 Prompt ───────────────────────────${NC}"
echo "$PROMPT"
echo -e "${CYAN}──────────────────────────────────────────${NC}"
echo ""
read -r -p "$(echo -e "${YELLOW}👀 Review the prompt above. Press Enter to launch the Ralph loop...${NC} ")"
echo ""
for i in $(seq 1 $MAX_ITERATIONS); do
echo -e "${BLUE}═══════════════════════════════════════${NC}"
echo -e " 🔁 ${BOLD}Iteration ${CYAN}$i${NC}${BOLD} / ${DIM}$MAX_ITERATIONS${NC}"
echo -e "${BLUE}═══════════════════════════════════════${NC}"
OUTPUT=$(echo "$PROMPT" \
| kiro-cli chat --trust-all-tools --no-interactive 2>&1 \
| tee /dev/stderr) || true
if echo "$OUTPUT" | \
grep -q "<promise>COMPLETE</promise>"
then
echo ""
echo -e "${GREEN}══════════════════════════════════════${NC}"
echo -e " ✅ ${BOLD}All tasks complete!${NC}"
echo -e "${GREEN}══════════════════════════════════════${NC}"
exit 0
fi
if [ "$AUTO_MODE" = false ]; then
echo ""
read -r -p "$(echo -e "${YELLOW}⏸️ Iteration $i done. Press Enter to continue...${NC} ")"
fi
done
echo ""
echo -e "${RED}══════════════════════════════════════${NC}"
echo -e " ⚠️ ${BOLD}Max iterations reached${NC} ${DIM}($MAX_ITERATIONS)${NC}"
echo -e "${RED}══════════════════════════════════════${NC}"
exit 1