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

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:

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