vralphy 0.8.0

package/README.md

@@ -0,0 +1,512 @@
+# 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](./docs/README.md)** - Documentation overview
+- **[docs/METHODOLOGY.md](./docs/METHODOLOGY.md)** - Deep dive into Ralph methodology
+- **[docs/COMMANDS.md](./docs/COMMANDS.md)** - Complete command reference
+- **[docs/DESIGN.md](./docs/DESIGN.md)** - Design principles and architecture
+- **[docs/WORKFLOWS.md](./docs/WORKFLOWS.md)** - Common workflows and patterns
+- **[docs/EXAMPLES.md](./docs/EXAMPLES.md)** - Real-world usage examples
+
+### LLM Discovery Standard
+
+vralphy includes an **[llms.txt](./llms.txt)** file following the [llms.txt standard](https://llmstxt.org/) 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
+
+### Core Commands
+
+```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
+```
+
+### Init Command Options
+
+```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
+```
+
+### Cleanup Command Options
+
+```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)
+
+### Utility Commands
+
+```bash
+vralphy engines              # List available engines (claude/opencode)
+vralphy skills               # List loaded skills
+vralphy agents               # List available agents
+```
+
+### Global Flags
+
+```bash
+--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):
+```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.
+
+### 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:
+
+```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
+```
+
+### 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`):
+```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):
+
+### 1. CLI Flags
+```bash
+vralphy --engine claude --planning-model opus --executor-model sonnet build
+```
+
+### 2. Environment Variables
+```bash
+export VRALPHY_ENGINE=claude
+export VRALPHY_PLANNING_MODEL=opus
+export VRALPHY_EXECUTOR_MODEL=sonnet
+vralphy build
+```
+
+### 3. Config File
+```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
+
+### Example 1: New Feature
+
+```bash
+# 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
+
+```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
+```
+
+### Example 3: Dry Run
+
+```bash
+# 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"
+```bash
+npm login
+# or set token in ~/.npmrc:
+echo "//registry.npmjs.org/:_authToken=npm_YOUR_TOKEN" > ~/.npmrc
+```
+
+### "No engines found"
+Install Claude or OpenCode CLI:
+```bash
+npm install -g @anthropic-ai/claude-code
+# or
+npm install -g opencode
+```
+
+### "Skills not loading"
+Check directory structure:
+```bash
+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
+
+```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](https://www.npmjs.com/package/vralphy)
+- [Ralph Methodology](https://ralphloop.com) _(placeholder - add real link if exists)_
+
+---
+
+**Built with ❤️ by AI, for developers who want AI to do the heavy lifting.**

package/bin/vralphy.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/index.js';

package/dist/commands/build.d.ts

@@ -0,0 +1,9 @@
+import { VralphyConfig } from '../lib/config.js';
+export interface BuildOptions {
+    iterations?: number;
+}
+/**
+ * Execute build mode
+ */
+export declare function buildCommand(config: VralphyConfig, options: BuildOptions): Promise<void>;
+//# sourceMappingURL=build.d.ts.map

package/dist/commands/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAQjD,MAAM,WAAW,YAAY;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAoL9F"}

package/dist/commands/build.js

@@ -0,0 +1,176 @@
+import { existsSync } from 'fs';
+import { basename } from 'path';
+import { getEngine } from '../lib/engines/index.js';
+import { CodexEngine } from '../lib/engines/codex.js';
+import { loadPrompt, interpolatePrompt, getDefaultBuildPrompt } from '../lib/prompts.js';
+import { sendSlack, sessionStartMessage, iterationEndMessage, sessionEndMessage, iterationErrorMessage, planCompletedMessage } from '../lib/slack.js';
+import { loadPlanSnapshot } from '../lib/plan.js';
+import { initEventLogger, logEvent, generateSessionId } from '../lib/events.js';
+/**
+ * Execute build mode
+ */
+export async function buildCommand(config, options) {
+    const engine = getEngine(config.engine);
+    if (!(await engine.isAvailable())) {
+        throw new Error(`Engine '${config.engine}' is not available. Please install it first.`);
+    }
+    // Configure Codex-specific settings if using Codex engine
+    if (config.engine === 'codex' && engine instanceof CodexEngine) {
+        engine.configure({
+            maxAgents: config.codex?.maxAgents,
+            workerTimeout: config.codex?.workerTimeout,
+        });
+    }
+    const maxIterations = options.iterations ?? 0;
+    let iteration = 0;
+    const project = basename(process.cwd());
+    const sessionId = generateSessionId();
+    initEventLogger(sessionId, project);
+    const webhookUrl = config.slackWebhook;
+    const sessionStart = Date.now();
+    console.log(`Starting build mode with ${config.engine} engine`);
+    console.log(`Planning Model: ${config.planningModel}, Executor Model: ${config.executorModel}`);
+    if (config.engine === 'codex') {
+        console.log(`Max agents: ${config.codex?.maxAgents ?? 8}, Worker timeout: ${config.codex?.workerTimeout ?? 300}s`);
+    }
+    console.log(`Max iterations: ${maxIterations || 'unlimited'}`);
+    // Snapshot initial plan state for completion detection
+    const initialPlan = await loadPlanSnapshot();
+    let planCompletionNotified = false;
+    if (initialPlan) {
+        console.log(`Plan: ${initialPlan.completedTasks}/${initialPlan.totalTasks} tasks complete`);
+    }
+    // Log and notify session start
+    logEvent({
+        type: 'session.start',
+        command: 'build',
+        engine: config.engine,
+        planningModel: config.planningModel,
+        executorModel: config.executorModel,
+        maxIterations,
+        planSnapshot: initialPlan ? {
+            totalTasks: initialPlan.totalTasks,
+            completedTasks: initialPlan.completedTasks,
+        } : undefined,
+    });
+    if (webhookUrl) {
+        sendSlack(webhookUrl, sessionStartMessage(project, 'build', maxIterations, config.engine, config.planningModel));
+    }
+    // Prompt locations in order of preference (engine-specific first)
+    const promptPaths = [
+        `.vralphy/prompts/${config.engine}/build.md`, // Engine-specific location
+        '.vralphy/prompts/build.md', // Generic new location
+        'PROMPT_build.md', // Legacy location (backwards compat)
+    ];
+    let success = true;
+    try {
+        while (true) {
+            if (maxIterations > 0 && iteration >= maxIterations) {
+                console.log(`Reached max iterations (${maxIterations})`);
+                break;
+            }
+            const iterationStart = Date.now();
+            console.log(`\n=== Iteration ${iteration + 1} ===\n`);
+            let prompt;
+            const promptContext = {
+                planningModel: config.planningModel,
+                executorModel: config.executorModel,
+                engine: config.engine,
+                maxAgents: config.codex?.maxAgents,
+                workerTimeout: config.codex?.workerTimeout,
+            };
+            // Find first existing prompt file
+            const existingPromptPath = promptPaths.find(p => existsSync(p));
+            if (existingPromptPath) {
+                prompt = await loadPrompt(existingPromptPath, promptContext);
+            }
+            else {
+                // Use engine-specific default prompt
+                const defaultPrompt = getDefaultBuildPrompt(config.engine);
+                prompt = interpolatePrompt(defaultPrompt, promptContext);
+            }
+            if (config.dryRun) {
+                console.log('--- DRY RUN: Would execute prompt ---');
+                console.log(prompt.slice(0, 500) + '...');
+                console.log('--- END DRY RUN ---');
+                break;
+            }
+            try {
+                // Engine handles output to terminal
+                for await (const chunk of engine.execute(prompt, {
+                    planningModel: config.planningModel,
+                    executorModel: config.executorModel,
+                    headless: true,
+                    skipPermissions: true,
+                    verbose: config.verbose,
+                    reasoningEffort: config.reasoningEffort,
+                })) {
+                    if (chunk.type === 'error') {
+                        console.error('Error:', chunk.error);
+                    }
+                }
+            }
+            catch (e) {
+                const errorMsg = e instanceof Error ? e.message : String(e);
+                console.error('Execution failed:', e);
+                // Log and notify error
+                logEvent({
+                    type: 'iteration.error',
+                    iteration: iteration + 1,
+                    maxIterations,
+                    error: errorMsg,
+                });
+                if (webhookUrl) {
+                    sendSlack(webhookUrl, iterationErrorMessage(project, iteration + 1, maxIterations, errorMsg));
+                }
+                success = false;
+                throw e;
+            }
+            iteration++;
+            // Log and notify iteration end
+            const iterationDuration = Date.now() - iterationStart;
+            logEvent({
+                type: 'iteration.end',
+                iteration,
+                maxIterations,
+                durationMs: iterationDuration,
+            });
+            if (webhookUrl) {
+                sendSlack(webhookUrl, iterationEndMessage(project, iteration, maxIterations, iterationDuration));
+            }
+            // Check for plan completion
+            if (initialPlan && initialPlan.incompleteTasks > 0 && !planCompletionNotified) {
+                const currentPlan = await loadPlanSnapshot();
+                if (currentPlan && currentPlan.incompleteTasks === 0) {
+                    planCompletionNotified = true;
+                    const duration = Date.now() - sessionStart;
+                    console.log(`\n🎉 Plan completed! All ${currentPlan.totalTasks} tasks done.\n`);
+                    logEvent({
+                        type: 'plan.completed',
+                        totalTasks: currentPlan.totalTasks,
+                        iteration,
+                        durationMs: duration,
+                    });
+                    if (webhookUrl) {
+                        sendSlack(webhookUrl, planCompletedMessage(project, currentPlan.totalTasks, iteration, duration));
+                    }
+                }
+            }
+        }
+    }
+    finally {
+        // Log and notify session end
+        const totalDuration = Date.now() - sessionStart;
+        logEvent({
+            type: 'session.end',
+            success,
+            iterationsCompleted: iteration,
+            durationMs: totalDuration,
+        });
+        if (webhookUrl) {
+            sendSlack(webhookUrl, sessionEndMessage(project, iteration, totalDuration, success));
+        }
+    }
+    console.log(`\nBuild complete after ${iteration} iteration(s)`);
+}
+//# sourceMappingURL=build.js.map