ralphi-init

name	ralphi-init
description	Scans a project and sets up ralphi loop configuration. Use when asked to initialize ralphi, set up a ralphi project, configure a project for AI-driven development, or run /ralphi-init.

Ralphi Init

Agentically scan a project to detect its language, framework, commands, and conventions, then generate all configuration needed for the ralphi loop.

What Gets Created

File	Purpose
.ralphi/config.yaml	Ralph loop configuration (commands, rules, engine)
AGENTS.md	Project conventions for the AI engine
prek.toml or .git/hooks/pre-commit	Pre-commit hook running ralphi check
.gitignore updates	Ignore ralph working files

Workflow

Follow these steps in order. Be conversational — confirm findings with the user before writing files.

Step 1: Scan the Project

Read these files to understand the project (skip any that don't exist):

Project overview:

• README.md, README.rst, README.txt, or similar

Package manifests (detect language):

• package.json → Node.js / TypeScript / JavaScript
• Cargo.toml → Rust
• go.mod → Go
• pyproject.toml, setup.py, requirements.txt → Python
• Gemfile → Ruby
• pom.xml → Java (Maven)
• build.gradle, build.gradle.kts → Java/Kotlin (Gradle)

Build and quality configs:

• tsconfig.json, .eslintrc*, vitest.config.*, jest.config.*
• ruff.toml, mypy.ini, .flake8
• golangci.yml, .golangci.yml
• clippy.toml, rustfmt.toml
• .prettierrc*, .editorconfig

CI configuration:

• .github/workflows/ directory listing
• .gitlab-ci.yml

Existing agent guidance:

• AGENTS.md
• CLAUDE.md, claude.md
• .cursorrules, .windsurfrules

Directory structure:

• Top-level directory listing
• src/ listing (if it exists)

If no package manifest is found, ask the user: "I couldn't detect a package manifest. What language and framework is this project using?"

Step 2: Determine Quality Commands

Based on the package manifest, detect the commands for test, lint, build, and typecheck.

Node.js / TypeScript / JavaScript

Read package.json and examine the scripts section:

1. Look for a composite command first (e.g., check:all, check, validate, ci). Read what it actually runs — if it combines test + lint + build, prefer it.
2. For individual commands:
   • test: test, test:unit, test:all
   • lint: lint, lint:fix, lint:check
   • build: build, compile
   • typecheck: typecheck, type-check, tsc, or if none exists and TypeScript is present, use npx tsc --noEmit
3. Actually read the script values to understand what they do. A script named test that runs echo "no tests" is not a real test command.

Python

Read pyproject.toml for tool configurations:

• test: pytest (if pytest is in dependencies or [tool.pytest] exists)
• lint: ruff check . (if ruff configured), else flake8 .
• typecheck: mypy . (if mypy is in dependencies or [tool.mypy] exists)
• format: black . or ruff format .

Go

• test: go test ./...
• lint: golangci-lint run (if .golangci.yml exists)
• build: go build ./...

Rust

• test: cargo test
• lint: cargo clippy
• build: cargo build
• format: cargo fmt --check

Ruby

• test: bundle exec rspec or bundle exec rails test
• lint: bundle exec rubocop

Java/Kotlin

• Maven: mvn test, mvn package
• Gradle: ./gradlew test, ./gradlew build

Shell/Bash

• lint: shellcheck <script-files>

Step 3: Determine Project Rules

Analyze the codebase to discover conventions:

1. Testing framework: What test runner is used? (vitest, jest, pytest, go test, cargo test, rspec)
2. Code style: Is there a formatter config? (prettier, black, rustfmt, gofmt)
3. Framework patterns: Are there patterns specific to the framework? (e.g., "use server actions not API routes" for Next.js App Router)
4. Existing guidance: Prefer AGENTS.md if present. If CLAUDE.md or other agent guidance files exist, extract useful rules but keep AGENTS.md as the canonical source.
5. Import style: ES modules vs CommonJS? Absolute vs relative imports?
6. Type strictness: Is strict: true in tsconfig? Is mypy in strict mode?

Compile 3-8 concise rules. Each rule should be a single actionable sentence.

Step 4: Present Findings and Confirm

Use the ralphi_ask_user_question tool to gather confirmation and preferences interactively. For example:

{
  "questions": [
    {
      "id": "extra_rules",
      "prompt": "Any additional project conventions to enforce?",
      "type": "multi",
      "options": ["Strict TypeScript", "No default exports", "Prefer named imports"],
      "allowOther": true
    }
  ]
}

Also show the user what was detected in a clear format:

## Detected Configuration

**Project:** my-project
**Language:** TypeScript
**Framework:** Next.js

### Commands
  ✓ test:      npm run test
  ✓ lint:      npm run lint
  ✓ build:     npm run build
  ✓ typecheck: npm run type-check

### Proposed Rules
  1. Use vitest for testing
  2. Follow existing patterns in src/
  3. Use strict TypeScript (strict: true)

Ask the user to confirm or edit commands and rules before proceeding.

Step 5: Generate .ralphi/config.yaml

Create the config file with this structure:

# ralphi configuration
# Auto-generated — edit as needed

project:
  name: "project-name"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm run test"
  lint: "npm run lint"
  build: "npm run build"
  typecheck: "npm run type-check"

rules:
  - "use vitest for testing"
  - "follow existing patterns"

boundaries:
  never_touch:
    - "*.lock"
    - ".env*"

engine: "pi"
max_retries: 3

Notes:

• project.name should be the directory name (kebab-case)
• Only include framework if one was detected
• Only include commands that were confirmed — comment out or omit undetected ones
• engine is always pi (ralphi is a Pi-native extension)
• boundaries.never_touch always includes *.lock and .env*

Step 6: Generate AGENTS.md (canonical)

Use AGENTS.md as the canonical guidance file for the project.

Before writing: Check if AGENTS.md already exists. If it does, show the user the existing content and ask whether to overwrite, merge, or skip.

Always write/merge content into AGENTS.md.

The file should contain:

1. Project overview (1-2 sentences): What the project is and what it does
2. Quick start commands: How to install, build, test, lint, typecheck
3. Quality check instructions: Emphasize running checks after every change
4. Key conventions: The rules discovered in Step 3
5. Directory structure: Brief guide to the top-level layout
6. Testing patterns: Framework, where tests live, how to write them

Keep it concise and practical. This file is read by AI agents, not humans — focus on actionable instructions, not prose.

Example structure:

# Project Name

Brief description of what this project does.

## Commands

After ANY code change, run:
\`\`\`bash
npm run check:all
\`\`\`

Individual commands:
- `npm run test` — Run tests
- `npm run lint` — Lint code
- `npm run build` — Build (includes type checking)

## Conventions

- Use vitest for testing
- Follow existing patterns in src/
- ...

## Directory Structure

\`\`\`
project/
├── src/         # Source code
├── tests/       # Test files
└── ...
\`\`\`

Step 7: Set Up Pre-commit Hook

The pre-commit hook should run ralphi check, which executes the quality commands from the config.

Option A — prek (preferred):

Generate prek.toml at the project root:

[[repos]]
repo = "local"
hooks = [
  {
    id = "ralphi-check",
    name = "ralphi check",
    language = "system",
    entry = "ralphi check",
    always_run = true,
    pass_filenames = false,
  },
]

Then check if prek is available by running command -v prek. If available, run prek install.

Option B — Direct git hook (fallback):

If prek is not available, create .git/hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail
ralphi check

Make it executable with chmod +x .git/hooks/pre-commit.

Important: If .git/hooks/pre-commit already exists, ask the user before overwriting.

Step 8: Update .gitignore

Append the following entries to .gitignore if they're not already present:

# ralphi
.ralphi/*
!.ralphi/config.yaml

Read the existing .gitignore first and only add entries that are missing. Do not duplicate entries.

Notes

• ralphi check is the command that runs quality checks from the config. It is called by the pre-commit hook to ensure code quality before commits.
• Ralphi is Pi-native. No external engine skill installation is required for init.
• The config file is intentionally simple YAML — users should feel comfortable editing it by hand.