ralph

What this skill does

# Ralph — Autonomous Coding Loop

An autonomous coding loop where Claude executes one task per iteration with a fresh context window. The spec and implementation plan are the single source of truth — not conversation history. Context rot is structurally impossible.

## Core Principle

Each loop iteration is a clean `claude -p` invocation. The loop script dynamically assembles each iteration's prompt from ONLY the spec sections and codebase files that task declares it needs. Context waste is zero.

## Planning Phase Workflow

You are in the planning phase. Your job is to help the user go from an idea to a complete spec and implementation plan, ready for autonomous execution.

### Step 0: Load Planning Framework

Load the planning questions framework:
@references/planning-questions.md

### Step 1: Brain-Dump Capture

Ask questions from the framework ONE AT A TIME. Skip questions the user already answered. Use multiple choice when possible. Goal: understand what they're building, current codebase state, what "done" looks like, constraints.

### Step 2: Bidirectional Questioning

After you understand the project, share your assumptions as a numbered list. Explicitly invite the user to correct them AND to ask you questions back. This surfaces hidden assumptions — the #1 source of bugs in autonomous execution.

Say: "Now I'll share what I'm assuming. Tell me where I'm wrong, and then ask ME any questions about what I'll be building."

### Step 3: Generate Spec

Load the spec template:
@references/spec-template.md

Generate `docs/ralph/SPEC.md` following the template. Present it to the user section by section. The user MUST review and approve every section. They own this file.

Rules:
- Section names are lowercase kebab-style (used as identifiers in task frontmatter)
- Each section under 50 lines
- `goal` and `constraints` are almost always needed
- Domain sections are project-specific — use what fits

Create the directory structure:
```bash
mkdir -p docs/ralph/tasks docs/ralph/logs
```

Write the spec file to `docs/ralph/SPEC.md`.

### Step 4: Generate Plan

Load the plan template:
@references/plan-template.md

Generate `docs/ralph/PLAN.md` (lightweight checkbox index) and individual task files in `docs/ralph/tasks/NN-kebab-title.md`.

For each task file, include YAML frontmatter with:
- `spec-sections`: Which SPEC.md sections this task needs (array of section heading names)
- `codebase-files`: Which existing project files Claude needs to see (array of paths)

Present the plan to the user. They must approve the task list, ordering, and per-task context declarations.

### Step 5: Context-Aware Validation

The iteration protocol that Claude reads each loop iteration is defined in:
@references/iteration-protocol.md

For each task, estimate context load:
- Sum the line counts of declared spec sections + declared codebase files + task body + iteration protocol (~60 lines)
- Flag any task estimated to exceed ~1500 lines of combined input
- Suggest decomposition for oversized tasks

### Step 6: Handoff

Tell the user:

> "Your spec and plan are ready in `docs/ralph/`. To launch the autonomous loop, run `/ralph start`."

Do NOT launch the loop yourself. The `/ralph start` command handles that.

## Important Constraints

- **Human owns the spec.** Draft it, present it, let them edit. Never auto-finalize.
- **One question at a time.** Don't overwhelm during brain-dump capture.
- **Lean artifacts.** Every byte in the spec and plan is read every iteration. Bloat degrades performance.
- **Tasks must be atomic.** Each task completable in one context window. When in doubt, split.
- **Filesystem-first state.** All state persists through files. Nothing relies on conversation history.