# Ralph Loop Setup

> >

- **Type:** Skill
- **Install:** `agentstack add skill-carinyaparc-skills-ralph-loop-setup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [carinyaparc](https://agentstack.voostack.com/s/carinyaparc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [carinyaparc](https://github.com/carinyaparc)
- **Source:** https://github.com/carinyaparc/skills/tree/main/skills/ralph-loop-setup

## Install

```sh
agentstack add skill-carinyaparc-skills-ralph-loop-setup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ralph loop setup

Resolve configuration and seed the loop files. **Never start the loop.** Setup
ends with a summary and an instruction to run `/ralph-loop start`.

Writing is done by `scripts/seed-ralph-loop.sh`, not by hand. Your job is to
resolve values and call it. Hand-authoring the loop file reintroduces the
unsubstituted-placeholder failure the script exists to prevent: a stray
`{{MAX_ITERATIONS}}` in the frontmatter fails the hook's numeric validation and
silently deletes the loop.

## Interview

Ask only what you cannot resolve yourself. Use structured questions, not prose.

1. **Preset.** If not given:
   - `engineering-delivery` — drive an epic through implement, review,
     validate, and merge request, one task per iteration.
   - `ad-hoc` — repeat a single prompt until it is done.
   - `custom` — define your own steps.

2. **Target.** The epic slug or ID for engineering delivery; the task prompt
   for ad-hoc; the step list for custom.

3. **Budgets.** Max iterations. Default 50, but for engineering delivery
   propose `tasks × 6 + 10`, since a 12-task epic will not fit in 50.

4. **Completion promise.** Propose a default and confirm it. For an epic, the
   slug upper-snake-cased with `_COMPLETE`.

5. **Environment.** Only for presets that need it, per
   [references/environment-resolution.md](references/environment-resolution.md).

## Workflow

### 1. Resolve the agent

`CLAUDE_PLUGIN_ROOT` set means `claude`; `CURSOR_PROJECT_DIR` set means
`cursor`. This determines the base directory (`.claude/loop` or
`.cursor/loop`). There is no pointer file and no `--ralph-dir` flag.

### 2. Resolve the preset inputs

**engineering-delivery**

- Resolve `{epic}` per
  [delivery-conventions.md](../tasks/references/delivery-conventions.md):
  a slug, an epic ID resolved via the backlog row, or a path.
- Locate `tasks.md` and `design.md`. Fail loudly, naming the missing file, if
  either is absent.
- Derive a dependency-safe task order: topological by declared dependencies,
  stable by document order on ties. Render as
  `N. {TASK_ID} —  (depends on: )`.
- Resolve the branch. Report the expected branch; never create or switch one.
- Resolve validation commands, tracker actions, and UI signals per
  [references/environment-resolution.md](references/environment-resolution.md).

**ad-hoc**

Write the task prompt to a file and pass `--prompt-file`. Apply
[../ralph-loop/references/prompt-authoring.md](../ralph-loop/references/prompt-authoring.md):
explicit completion criteria, a verification step each iteration, and an
escape hatch for being stuck.

**custom**

Write the step definitions to a file and pass `--steps-file`. Each step needs a
name, what to do, and which step comes next. See
[../ralph-loop/references/preset-authoring.md](../ralph-loop/references/preset-authoring.md).

### 3. Seed

Call the script. Every template value goes through `--set`:

```bash
scripts/seed-ralph-loop.sh \
  --agent claude \
  --preset engineering-delivery \
  --run-id "{epic}-$(date -u +%Y%m%d-%H%M%S)" \
  --max-iterations 70 \
  --completion-promise CHECKOUT_FOUNDATION_COMPLETE \
  --session-id "$SESSION_ID" \
  --set EPIC=checkout-foundation \
  --set BRANCH=feat/checkout-foundation \
  --set TASKS_PATH=docs/work/checkout-foundation/tasks.md \
  --set DESIGN_PATH=docs/work/checkout-foundation/design.md \
  --set FIRST_ITEM=CHK01-01 \
  --set "WORK_SEQUENCE=$(cat sequence.txt)" \
  --set "GOAL=..." --set "DONE_CRITERIA=..." --set "PRESET_CONTEXT=..."
```

Run with `--dry-run` first when anything is uncertain. The script refuses to
overwrite a loop past iteration 1 without `--force`, and exits non-zero on any
unresolved placeholder.

### 4. Report

Files written, resolved configuration, expected branch, and "Run
`/ralph-loop start` to begin." Nothing else.

## Policies

- MUST NOT execute loop steps or launch sub-agents. Setup only writes files.
- MUST NOT create or switch git branches.
- MUST NOT hand-author `active.md`, `loop-state.md`, or `context.md`.
- MUST fail loudly, naming the file, when a required source is missing.
- MUST NOT invent a task order that ignores declared dependencies.

## Anti-patterns

- Writing the loop file directly instead of calling the seed script.
- Starting the loop after seeding it.
- Guessing at validation commands rather than resolving them from the repo.
- Setting a completion promise the loop has no way to verify.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [carinyaparc](https://github.com/carinyaparc)
- **Source:** [carinyaparc/skills](https://github.com/carinyaparc/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-carinyaparc-skills-ralph-loop-setup
- Seller: https://agentstack.voostack.com/s/carinyaparc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.