vralphy

CLI tool implementing the Ralph Playbook methodology with engine flexibility (Claude/OpenCode), model selection, and autonomous development loops.

What is the Ralph Methodology?

Ralph is an autonomous AI development methodology where an AI agent:

1. Plans - Studies specs, analyzes codebase, creates implementation plans
2. Builds - Implements features using parallel subagents, runs tests, commits changes
3. Loops - Repeats until all tasks complete or iteration limit reached

The methodology emphasizes:

• Parallel execution - 500+ subagents for searches/reads, specialized agents for reasoning
• Autonomous operation - Agent makes decisions, runs tests, commits without human intervention
• Specification-driven - Work defined in specs/*.md files
• Operational context - Lightweight AGENTS.md keeps build/test commands accessible
• Incremental progress - IMPLEMENTATION_PLAN.md tracks remaining work across loops

Comprehensive Documentation

vralphy includes LLM-friendly documentation in the docs/ directory (bundled with the package):

• docs/README.md - Documentation overview
• docs/METHODOLOGY.md - Deep dive into Ralph methodology
• docs/COMMANDS.md - Complete command reference
• docs/DESIGN.md - Design principles and architecture
• docs/WORKFLOWS.md - Common workflows and patterns
• docs/EXAMPLES.md - Real-world usage examples

LLM Discovery Standard

vralphy includes an llms.txt file following the llms.txt standard for AI agent discovery. This markdown file provides a structured overview of vralphy's capabilities, making it easy for LLMs to understand and use the tool when working in projects.

This documentation is designed to help both humans and LLMs understand and use vralphy effectively.

Installation

npm install -g vralphy

Or use directly with npx:

npx vralphy init

Quick Start

1. Initialize a project:

   cd your-project
   vralphy init

   This creates:

   • specs/ - Feature specifications directory
   • .vralphy/AGENTS.md - AI-generated operational guide (build/test commands)
   • .vralphy/prompts/ - Prompt templates (plan.md, build.md, spec.md)
   • IMPLEMENTATION_PLAN.md - Task tracking

   AI-Powered Init: When an AI engine (claude/opencode/codex) is available, vralphy init uses AI to analyze your project and generate a smart, project-specific .vralphy/AGENTS.md. Falls back to template-based generation if no engine is found.

   Note: The AGENTS.md in .vralphy/ is vralphy's internal operational guide. It won't collide with your project's root AGENTS.md used by Claude/OpenCode/Codex.

2. Create specifications:

   vralphy spec authentication

   Interactive conversation to define requirements, saves to specs/authentication.md

3. Run planning phase:

   vralphy plan 3

   Agent analyzes specs and codebase, creates/updates IMPLEMENTATION_PLAN.md

4. Run build phase:

   vralphy build 10

   Agent autonomously implements features, runs tests, commits changes

Commands

Core Commands

vralphy build [iterations]   # Build mode (default: unlimited)
vralphy plan [iterations]    # Plan mode
vralphy spec [topic]         # Interactive spec creation
vralphy init                 # Initialize project (AI-powered)
vralphy cleanup              # Remove vralphy from project

Init Command Options

vralphy init                      # AI-powered init (default)
vralphy init --no-ai              # Skip AI, use template fallback
vralphy init --approve            # Review AGENTS.md before saving
vralphy init --engine codex       # Use specific engine for AI generation
vralphy init --from /path/to/dir  # Initialize from different directory

Cleanup Command Options

vralphy cleanup                   # Remove vralphy files (prompts for confirmation)
vralphy cleanup --force           # Skip confirmation prompt
vralphy cleanup --remove-specs    # Also remove specs/ directory
vralphy cleanup --from /path      # Clean up different directory

What gets removed:

• .vralphy/ - All vralphy configuration and prompts
• IMPLEMENTATION_PLAN.md - Task tracking file
• specs/ - Only if --remove-specs flag is used (kept by default)

Utility Commands

vralphy engines              # List available engines (claude/opencode)
vralphy skills               # List loaded skills
vralphy agents               # List available agents

Global Flags

--engine <engine>            # claude, opencode, or codex (default: claude)
--planning-model <model>     # Primary model: opus, sonnet, haiku (default: opus)
--executor-model <model>     # Executor model for subagents (default: sonnet)
--reasoning-effort <level>   # Reasoning effort (OpenCode/Codex: minimal/low/medium/high/xhigh/max)
--skills <path>              # Skills directory (default: auto-detect)
--agents <path>              # Agents directory (default: auto-detect)
--config <path>              # Config file (default: .vralphy/config.json)
--verbose                    # Verbose output
--dry-run                    # Show what would execute without running

Note: The --reasoning-effort parameter works with OpenCode and Codex engines. Claude CLI does not support this parameter yet (feature pending).

How It Works

1. Project Structure

your-project/
├── .vralphy/
│   ├── AGENTS.md             # vralphy's operational guide (~60 lines max)
│   └── prompts/              # vralphy prompt templates
│       ├── plan.md
│       ├── build.md
│       └── spec.md
├── .claude/                  # Claude engine's native location (if using Claude)
│   ├── skills/               # Skills loaded on-demand
│   └── agents/               # Agents spawned on-demand
├── specs/                    # Feature specifications
│   ├── authentication.md
│   └── api-endpoints.md
├── AGENTS.md                 # (Optional) Your project's AGENTS.md for Claude/OpenCode
└── IMPLEMENTATION_PLAN.md    # Current task list

Key principle: vralphy stores only its prompts in .vralphy/. Skills and agents come from the engine's native location (.claude/, .opencode/, etc.).

2. The Loop

Planning Phase (vralphy plan):

• Studies all specs/*.md files with parallel subagents
• Analyzes existing codebase
• Compares implementation against specs
• Creates/updates IMPLEMENTATION_PLAN.md with prioritized tasks
• Does NOT write code

Build Phase (vralphy build):

• Reads IMPLEMENTATION_PLAN.md and picks highest priority task
• Searches codebase to understand current state
• Implements functionality using parallel subagents
• Runs tests after changes
• Updates IMPLEMENTATION_PLAN.md with findings
• Commits and pushes changes
• Repeats until done or iteration limit reached

Spec Phase (vralphy spec):

• Interactive requirement gathering (Claude only)
• Agent asks clarifying questions using AskUserQuestion
• Generates comprehensive spec document
• Saves to specs/<topic>.md

3. Engine Abstraction

vralphy supports multiple AI engines:

Claude Engine (default):

vralphy --engine claude --planning-model opus build

OpenCode Engine:

vralphy --engine opencode build

Codex Engine:

vralphy --engine codex build

Engines auto-detected on startup. Install claude, opencode, or codex CLI tools.

4. Model Selection

Two-tier model system:

• Primary (Thinking): Complex reasoning, orchestration (default: opus)
• Executor (Subagents): Parallel tasks, file operations (default: sonnet)

Model Aliases by Engine

Claude (default):

• opus → claude-opus-4-5-20250514
• sonnet → claude-sonnet-4-20250514
• haiku → claude-haiku-3-5-20241022

OpenCode (OpenAI models):

• gpt-4o → gpt-4o
• gpt-4 → gpt-4-turbo
• o1 → o1 (reasoning model)
• o1-mini → o1-mini (reasoning model)
• o1-preview → o1-preview

Codex (DeepSeek models):

• deepseek-chat → deepseek-chat
• deepseek-r1 → deepseek-r1 (reasoning model)

Using Reasoning Models

Some models have built-in reasoning capabilities (o1 series, DeepSeek R1). These can be used for complex planning:

# Use o1 for planning with OpenCode
vralphy --engine opencode --planning-model o1 plan 3

# Use DeepSeek R1 for planning with Codex
vralphy --engine codex --planning-model deepseek-r1 plan 3

# Standard Claude for building
vralphy --engine claude --planning-model opus --executor-model sonnet build

Full Model IDs

You can also use full model IDs directly:

vralphy --planning-model claude-opus-4-5-20250514 build
vralphy --planning-model gpt-4o build
vralphy --planning-model deepseek-r1 build

5. Skills & Agents (Lazy Loading)

Context is precious. vralphy does NOT preload all skills/agents into prompts. Instead, the agent discovers and loads them on-demand from the engine's native locations:

| Engine | Skills Location | Agents Location | |----------|---------------------|---------------------| | Claude | .claude/skills/ | .claude/agents/ | | OpenCode | .opencode/skills/ | .opencode/agents/ | | Codex | .codex/skills/ | .codex/agents/ |

When the agent loads a skill:

• Current task requires domain-specific knowledge
• A spec explicitly references a framework with a matching skill
• After failing twice at something - checks if a skill could help

When the agent spawns an agent:

• Task requires deep focused expertise (security audit, architecture review)
• Needs a second opinion on a complex decision
• Parallel work that benefits from isolation

Skill format (.claude/skills/react-patterns.md):

---
name: react-patterns
description: React best practices
triggers:
  - "React component"
  - "useState"
---

# React Patterns
[knowledge content]

Agent format (.claude/agents/code-reviewer.md):

---
name: code-reviewer
description: Reviews code for bugs
model: sonnet
---

You are a code review specialist...

List what's available:

vralphy skills    # Shows skills in engine-native location
vralphy agents    # Shows agents in engine-native location

Configuration

Three ways to configure (priority order):

1. CLI Flags

vralphy --engine claude --planning-model opus --executor-model sonnet build

2. Environment Variables

export VRALPHY_ENGINE=claude
export VRALPHY_PLANNING_MODEL=opus
export VRALPHY_EXECUTOR_MODEL=sonnet
vralphy build

3. Config File

{
  "engine": "claude",
  "planningModel": "opus",
  "executorModel": "sonnet",
  "skillsDir": ".claude/skills",
  "agentsDir": "agents"
}

Save as .vralphy/config.json (preferred, non-invasive).

Legacy location vralphy.config.json in project root is still supported for backwards compatibility.

Examples

Example 1: New Feature

# Define the feature
vralphy spec user-authentication

# Plan implementation
vralphy plan 2

# Build it
vralphy build 20

# Check progress
cat IMPLEMENTATION_PLAN.md

Example 2: Existing Project

# Initialize (detects package.json, extracts commands)
vralphy init

# Create specs for missing features
vralphy spec api-rate-limiting
vralphy spec error-handling

# Run planning
vralphy plan 5

# Execute build loop
vralphy build

Example 3: Dry Run

# See what would execute without running
vralphy --dry-run build 1

# Shows the prompt that would be sent to the engine

Why vralphy?

Traditional Development

• Human writes spec → human codes → human tests → human debugs → repeat

With Ralph + vralphy

• Human writes spec → vralphy plans → vralphy codes → vralphy tests → vralphy commits → repeat

You focus on what to build (specs), vralphy handles how to build it.

Best Practices

1. Keep .vralphy/AGENTS.md Lean

• Max ~60 lines
• Only operational commands (build, test, lint)
• No verbose explanations or history
• Status updates belong in IMPLEMENTATION_PLAN.md
• This is vralphy's internal guide, separate from your project's root AGENTS.md

2. Write Clear Specs

• One feature per spec file
• Include acceptance criteria
• List edge cases
• Document dependencies

3. Start with Planning

• Always run vralphy plan before vralphy build
• Review IMPLEMENTATION_PLAN.md before executing
• Adjust iterations based on task complexity

4. Use Dry Run

• Test prompts with --dry-run first
• Verify model selection is appropriate
• Check that skills/agents load correctly

5. Iteration Management

• Start with small iteration counts (5-10)
• Monitor progress via commits
• Increase as you gain confidence

Troubleshooting

"Access token expired"

npm login
# or set token in ~/.npmrc:
echo "//registry.npmjs.org/:_authToken=npm_YOUR_TOKEN" > ~/.npmrc

"No engines found"

Install Claude or OpenCode CLI:

npm install -g @anthropic-ai/claude-code
# or
npm install -g opencode

"Skills not loading"

Check directory structure:

vralphy --verbose skills
# Shows search path and loaded skills

Model validation warnings

As of v0.7.1, vralphy uses advisory validation instead of blocking errors:

• Warning shown: Model not found in cache or cache unavailable
• Execution continues: Engine CLI validates the model
• Autonomous-friendly: Cache hiccups won't stop execution
• If the model is truly invalid, the engine will report the error

Slow or busy models

As of v0.7.1, vralphy removes aggressive timeouts:

• Patient execution: No 60-second timeout on model responses
• Better for autonomous: System waits for slow/queued models
• Engine-controlled: Each engine manages its own timeout logic
• If something truly hangs, use Ctrl+C to interrupt

Loop stuck

• Check IMPLEMENTATION_PLAN.md for circular tasks
• Review recent commits for issues
• Reduce iteration count and debug manually

Development

git clone https://github.com/yourusername/vralphy.git
cd vralphy
npm install
npm run build
npm test

Run locally:

./bin/vralphy.js --help

Contributing

vralphy was built by Ralph (autonomous AI) using its own methodology. Contributions should follow the same pattern:

1. Create spec in specs/
2. Run planning phase
3. Run build phase
4. Submit PR with generated code

License

MIT

Links

• npm package
• Ralph Methodology (placeholder - add real link if exists)

Built with ❤️ by AI, for developers who want AI to do the heavy lifting.