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

$3

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

``bash
npm install -g vralphy
`

Or use directly with npx:

`bash
npx vralphy init
`

Quick Start

1. Initialize a project:
`bash
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:
`bash
vralphy spec authentication
`

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

3. Run planning phase:
`bash
vralphy plan 3
`

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

4. Run build phase:
`bash
vralphy build 10
`

Agent autonomously implements features, runs tests, commits changes

Commands

$3

`bash
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
`

$3

`bash
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
`

$3

`bash
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)

$3

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

$3

`bash
--engine # claude, opencode, or codex (default: claude)
--planning-model # Primary model: opus, sonnet, haiku (default: opus)
--executor-model # Executor model for subagents (default: sonnet)
--reasoning-effort # Reasoning effort (OpenCode/Codex: minimal/low/medium/high/xhigh/max)
--skills # Skills directory (default: auto-detect)
--agents # Agents directory (default: auto-detect)
--config # 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

$3

`
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.).

$3

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/.md

$3

vralphy supports multiple AI engines:

Claude Engine (default):
`bash
vralphy --engine claude --planning-model opus build
`

OpenCode Engine:
`bash
vralphy --engine opencode build
`

Codex Engine:
`bash
vralphy --engine codex build
`

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

$3

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:

`bash


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:

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

$3

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):
`markdown
---
name: react-patterns
description: React best practices
triggers:
- "React component"
- "useState"
---

React Patterns


[knowledge content]
`

Agent format (.claude/agents/code-reviewer.md):
`markdown
---
name: code-reviewer
description: Reviews code for bugs
model: sonnet
---

You are a code review specialist...
`

List what's available:
`bash
vralphy skills # Shows skills in engine-native location
vralphy agents # Shows agents in engine-native location
`

Configuration

Three ways to configure (priority order):

$3


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

$3

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

$3

`json
{
"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

$3

`bash


Define the feature

vralphy spec user-authentication

Plan implementation

vralphy plan 2

Build it

vralphy build 20

Check progress

cat IMPLEMENTATION_PLAN.md
`

$3

`bash


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
`

$3

`bash


See what would execute without running

vralphy --dry-run build 1

Shows the prompt that would be sent to the engine

`

Why vralphy?

$3

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

$3

- 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

$3

- 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

$3

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

$3

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

$3

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

$3

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

Troubleshooting

$3

`bash
npm login

or set token in ~/.npmrc:

echo "//registry.npmjs.org/:_authToken=npm_YOUR_TOKEN" > ~/.npmrc
`

$3

Install Claude or OpenCode CLI:
`bash
npm install -g @anthropic-ai/claude-code

or

npm install -g opencode
`

$3

Check directory structure:
`bash
vralphy --verbose skills

Shows search path and loaded skills

`

$3

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

$3

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

$3

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

Development

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

Run locally:
`bash
./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.