---
name: ralph-init
description: "Bootstrap Ralph autonomous agent infrastructure in a new project. Sets up ralph.sh, CLAUDE.md, git hooks, backlog, .devcontainer, .gitignore, and skills. Triggers on: ralph init, bootstrap ralph, setup ralph, init ralph, initialize ralph."
---

# Ralph Project Bootstrapper

Set up Ralph autonomous agent infrastructure in an existing git repository.

All template files are in the `templates/` directory next to this SKILL.md. Read each template, customize as needed, and write to the target project.

**Important:** Do NOT start implementing features or creating tasks. Just set up the infrastructure.

---

## Step 1: Preflight Checks

```bash
git rev-parse --git-dir    # Must be a git repo
command -v backlog          # Must have backlog CLI
```

If `backlog` is missing: `npm install -g backlog.md`
If not a git repo: `git init -b main`

---

## Step 2: Clarifying Questions

Ask with lettered options for quick answers (e.g. "1A, 2C, 3B, 4A"):

```
1. What is your primary language/runtime?
   A. TypeScript / Node.js
   B. Python
   C. Go
   D. Other: [please specify]

2. What are your quality check commands?
   A. npm run build && npm run lint && npm test
   B. pytest && mypy . && ruff check .
   C. go build ./... && go vet ./... && go test ./...
   D. Other: [please specify]

3. Do you need the DevContainer (sandboxed execution with firewall)?
   A. Yes — I want isolated autonomous runs
   B. No — I'll run Ralph directly on my machine

4. Which AI tool will you use with Ralph?
   A. Claude Code
   B. Amp
   C. Both Claude Code and Amp
   D. opencode
```

---

## Step 3: Generate Files

**Skip any file that already exists** unless the user says `--force`. For skipped files, print `[skip] <file> already exists`.

### 3.1 `ralph.sh`
Read `templates/ralph.sh` → write to project root. Make executable (`chmod +x`).

### 3.2 `CLAUDE.md`
Read `templates/CLAUDE.md` → replace ALL `<FILL IN ...>` placeholders in `## Project-Specific` with actual values from the user's answers. Parse quality commands (Q2) into separate build, lint, and test entries.

**Language conventions:** If `templates/CLAUDE.conventions.<lang>.md` exists for the chosen language (e.g. `python`), read it and append its contents after the `### Conventions` section. This adds language-specific rules (package management, code style, etc.).

Write to project root.

### 3.3 `.git/hooks/post-commit`
Read `templates/post-commit` → write to `.git/hooks/post-commit`. Make executable (`chmod +x`). If hook already exists, warn user and ask before overwriting.

### 3.4 `.gitignore`
Append missing entries (don't duplicate existing lines):
```
# Ralph / Claude
.claude/
.DS_Store
```
Do NOT add `backlog/` — task files should be committed.

### 3.5 Backlog
Skip if `backlog/` directory already exists. Otherwise run non-interactively using the repo directory name as the project name:
```bash
backlog init <project-name> --defaults --agent-instructions none
```
Use `--agent-instructions none` because CLAUDE.md is already generated by this skill.

### 3.6 `.devcontainer/` (only if user said Yes to Q3)
Assemble the Dockerfile from base + language snippets, then write three files:

**Dockerfile assembly:** Read `templates/Dockerfile.base`. Replace `{{LANGUAGE_STAGE}}` with contents of `templates/Dockerfile.lang.<lang>` and `{{LANGUAGE_INSTALL}}` with contents of `templates/Dockerfile.install.<lang>`, where `<lang>` is one of: `node`, `python`, `go`. For "Other" languages, use `node` as the base and add a comment for the user to customize.

- Assembled Dockerfile → `.devcontainer/Dockerfile`
- `templates/devcontainer.json` → `.devcontainer/devcontainer.json` — update app label and port if specified
- `templates/init-firewall.sh` → `.devcontainer/init-firewall.sh`

### 3.7 `.claude/settings.local.json`
Read `templates/settings.local.json` → write to `.claude/settings.local.json`.

---

## Step 4: Summary

```
Ralph initialized successfully!

Files created:
  ralph.sh              - Main autonomous loop script (supports amp, claude, opencode)
  CLAUDE.md             - Agent instructions for Claude Code
  .git/hooks/post-commit - Commit hash tracking for tasks
  .gitignore            - Updated with Ralph entries
  backlog/              - Backlog initialized
  .claude/settings.local.json - Claude Code permissions
  .devcontainer/        - (if applicable) Sandboxed execution environment

Usage:
  ./ralph.sh --tool amp          # Run with Amp
  ./ralph.sh --tool claude       # Run with Claude Code
  ./ralph.sh --tool opencode     # Run with opencode

Error handling options:
  --on-error stop|continue|retry  # Error behavior (default: stop)
  --retry-count N                 # Retries for --on-error=retry (default: 2)
  --log-file path                 # Log errors to file

Next steps:
  1. Review and customize CLAUDE.md (especially ## Project-Specific)
  2. Create a PRD:  /ralph-prd
  3. Convert to tasks:  /ralph-backlog
  4. Run Ralph:  ./ralph.sh --tool claude
                 ./ralph.sh --tool opencode
```