vralphy 0.1.2 → 0.3.0

package/docs/METHODOLOGY.md

@@ -0,0 +1,390 @@
+# Ralph Methodology
+
+The Ralph Playbook is an **autonomous AI development methodology** that enables AI agents to plan, implement, test, and deploy software with minimal human intervention.
+
+## Core Philosophy
+
+**Humans define WHAT to build. AI determines HOW to build it.**
+
+- Humans write specifications describing features and requirements
+- AI analyzes the codebase, plans the implementation, writes code, runs tests, and commits changes
+- The loop continues until all specifications are implemented or iteration limits are reached
+
+## Three Phases
+
+### 1. Specification Phase (`vralphy spec`)
+
+**Purpose**: Capture requirements through interactive conversation
+
+**How it works**:
+1. AI asks clarifying questions about the feature
+2. User provides answers and context
+3. AI generates a complete specification document
+4. Spec is saved to `specs/<topic>.md`
+
+**Example**:
+```bash
+vralphy spec user-authentication
+
+# AI might ask:
+# - What authentication methods? (password, OAuth, SSO)
+# - Session management approach? (JWT, cookies, server-side)
+# - Password requirements?
+# - Two-factor authentication?
+
+# Output: specs/user-authentication.md
+```
+
+**Specification Format**:
+```markdown
+# Feature Name
+
+## Overview
+[Brief description]
+
+## Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Edge Cases
+[List edge cases]
+
+## Dependencies
+[List dependencies]
+```
+
+### 2. Planning Phase (`vralphy plan`)
+
+**Purpose**: Analyze codebase and create implementation plan
+
+**How it works**:
+1. AI reads `.vralphy/AGENTS.md` to understand build/test commands
+2. AI studies all `specs/*.md` files using parallel subagents (up to 250)
+3. AI analyzes existing codebase using parallel subagents (up to 500)
+4. AI compares implementation against specifications
+5. AI creates/updates `IMPLEMENTATION_PLAN.md` with prioritized tasks
+6. **No code is written** - planning only
+
+**Key Features**:
+- **Parallel execution**: Uses hundreds of subagents for fast analysis
+- **Incremental**: Updates existing plan rather than starting from scratch
+- **Priority-based**: Tasks sorted by importance and dependencies
+- **Gap analysis**: Identifies missing functionality, TODOs, placeholders
+
+**Example**:
+```bash
+vralphy plan 3  # Run 3 planning iterations
+
+# AI will:
+# 1. Read all specs
+# 2. Scan codebase
+# 3. Identify gaps
+# 4. Update IMPLEMENTATION_PLAN.md
+```
+
+**Output** (`IMPLEMENTATION_PLAN.md`):
+```markdown
+# Implementation Plan
+
+## High Priority
+- [ ] Implement user registration endpoint
+- [ ] Add password hashing with bcrypt
+- [ ] Create user database schema
+
+## Medium Priority
+- [ ] Add email verification
+- [ ] Implement password reset flow
+
+## Low Priority
+- [ ] Add OAuth providers
+```
+
+### 3. Build Phase (`vralphy build`)
+
+**Purpose**: Implement functionality autonomously
+
+**How it works**:
+1. AI reads `.vralphy/AGENTS.md` for operational commands
+2. AI reads `IMPLEMENTATION_PLAN.md` to pick the highest priority task
+3. AI searches codebase to understand current state
+4. AI implements functionality using parallel subagents
+5. AI runs tests after changes
+6. AI updates `IMPLEMENTATION_PLAN.md` with findings
+7. AI commits changes with descriptive message
+8. Loop repeats until done or iteration limit reached
+
+**Key Features**:
+- **Autonomous**: Makes decisions without human input
+- **Test-driven**: Runs tests after each change
+- **Git integration**: Commits and pushes automatically
+- **Self-documenting**: Updates `.vralphy/AGENTS.md` when learning new commands
+- **Incremental progress**: Small, focused commits
+
+**Example**:
+```bash
+vralphy build 10  # Run 10 build iterations
+
+# Each iteration:
+# 1. Pick task from IMPLEMENTATION_PLAN.md
+# 2. Search codebase
+# 3. Write code
+# 4. Run tests
+# 5. If tests pass: commit + push
+# 6. If tests fail: debug and retry
+# 7. Update IMPLEMENTATION_PLAN.md
+```
+
+## The Loop
+
+The Ralph methodology is designed to loop:
+
+```
+┌─────────────────────────────────────┐
+│ 1. Human writes specifications     │
+│    (specs/*.md)                     │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 2. AI analyzes and plans            │
+│    vralphy plan                     │
+│    → Updates IMPLEMENTATION_PLAN.md │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 3. AI implements and tests          │
+│    vralphy build                    │
+│    → Writes code                    │
+│    → Runs tests                     │
+│    → Commits changes                │
+└────────────┬────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────┐
+│ 4. Check progress                   │
+│    - All specs implemented? DONE    │
+│    - More work needed? Go to step 2 │
+└─────────────────────────────────────┘
+```
+
+## Operational Context
+
+**Problem**: AI agents need to know how to build, test, and run your project.
+
+**Solution**: `.vralphy/AGENTS.md` - A lightweight operational guide (max 60 lines)
+
+**Contents**:
+- Build commands (e.g., `npm run build`)
+- Test commands (e.g., `npm test`)
+- Lint/typecheck commands
+- Dev server commands
+- Project-specific patterns
+
+**AI-Generated**: When you run `vralphy init`, AI analyzes your project and generates this file automatically.
+
+**Example** (`.vralphy/AGENTS.md`):
+```markdown
+## Build & Run
+- Build: `npm run build`
+- Dev: `npm run dev`
+
+## Validation
+- Tests: `npm test`
+- Typecheck: `tsc --noEmit`
+- Lint: `npm run lint`
+
+## Tech Stack
+- Node.js + TypeScript
+- Vitest for testing
+- ESLint for linting
+
+## Codebase Patterns
+- Source files in src/
+- Tests colocated with source (*.test.ts)
+- Use named exports
+```
+
+## Parallel Execution
+
+Ralph emphasizes **massive parallelism** for performance:
+
+**Planning Phase**:
+- 250 parallel subagents for reading specs
+- 500 parallel subagents for searching codebase
+- 1 reasoning agent (opus) for analysis
+
+**Build Phase**:
+- 500 parallel subagents for searches/reads
+- 1 subagent for build/test (sequential)
+- Reasoning agent (opus) for complex decisions
+
+**Why?**: Reading files is IO-bound and can be parallelized. Building/testing must be sequential.
+
+## Design Principles
+
+### 1. Specification-Driven
+
+Everything starts with specifications. AI doesn't guess what to build - it reads specs.
+
+### 2. Autonomous Operation
+
+Once started, AI makes decisions independently:
+- What to implement next
+- How to implement it
+- When tests pass (commit) or fail (debug)
+- When to update documentation
+
+### 3. Incremental Progress
+
+Small, focused changes:
+- One feature/fix per commit
+- Run tests after each change
+- Update plan after each iteration
+- Commit frequently
+
+### 4. Context is Precious
+
+Keep operational docs lean:
+- `.vralphy/AGENTS.md`: Max 60 lines
+- Focus on commands, not explanations
+- No changelogs or history
+- Status updates go in `IMPLEMENTATION_PLAN.md`
+
+### 5. Non-Invasive
+
+vralphy doesn't interfere with existing tools:
+- `.vralphy/` directory for all vralphy files
+- `.vralphy/AGENTS.md` for vralphy's operational guide
+- Root `AGENTS.md` remains yours for Claude/OpenCode
+
+## Model Selection
+
+Two-tier model system:
+
+**Primary (Thinking)**:
+- Model: opus (default)
+- Purpose: Complex reasoning, orchestration, decisions
+- Use: Planning, debugging, architecture
+
+**Executor (Subagents)**:
+- Model: sonnet (default)
+- Purpose: Parallel tasks, file operations
+- Use: Reading files, searching code, simple edits
+
+**Why?**: Opus is expensive but smart. Sonnet is cheap and fast. Use each where appropriate.
+
+## Engine Abstraction
+
+vralphy works with multiple AI engines:
+
+| Engine   | Provider  | CLI Command |
+|----------|-----------|-------------|
+| claude   | Anthropic | `claude`    |
+| opencode | OpenAI    | `opencode`  |
+| codex    | Custom    | `codex`     |
+
+**Auto-detection**: vralphy detects available engines on startup.
+
+**Flexibility**: Switch engines with `--engine` flag.
+
+## Lazy Loading
+
+**Problem**: Loading all skills/agents into context wastes tokens.
+
+**Solution**: Load on-demand when needed.
+
+**How it works**:
+1. Agent encounters a task requiring domain knowledge
+2. Agent checks if a skill exists (e.g., `.claude/skills/react.md`)
+3. Agent loads only the relevant skill
+4. Agent uses knowledge to complete task
+
+**Skill triggers**: Define when to load
+```markdown
+---
+name: react-patterns
+triggers:
+  - "React component"
+  - "useState"
+  - "useEffect"
+---
+```
+
+## Success Criteria
+
+A Ralph loop is successful when:
+
+1. **All specs implemented**: Every requirement has passing tests
+2. **Clean codebase**: No TODOs, placeholders, or skipped tests
+3. **Tests passing**: All unit, integration, and e2e tests pass
+4. **Documented**: `.vralphy/AGENTS.md` reflects current state
+5. **Committed**: All changes committed to git with clear messages
+
+## Common Patterns
+
+### New Feature Flow
+
+```bash
+# 1. Define what to build
+vralphy spec new-feature
+
+# 2. Plan how to build it
+vralphy plan 2
+
+# 3. Build it
+vralphy build 20
+
+# 4. Check progress
+cat IMPLEMENTATION_PLAN.md
+```
+
+### Bug Fix Flow
+
+```bash
+# 1. Add bug to IMPLEMENTATION_PLAN.md
+echo "- [ ] Fix: Authentication fails for email with +" >> IMPLEMENTATION_PLAN.md
+
+# 2. Let AI fix it
+vralphy build 5
+```
+
+### Refactoring Flow
+
+```bash
+# 1. Create refactoring spec
+vralphy spec refactor-auth-module
+
+# 2. Plan the refactoring
+vralphy plan 3
+
+# 3. Execute refactoring
+vralphy build 15
+```
+
+## Anti-Patterns
+
+**❌ Don't**: Write code manually during a Ralph loop
+**✅ Do**: Let AI complete the current loop, then intervene
+
+**❌ Don't**: Edit `.vralphy/AGENTS.md` with status updates
+**✅ Do**: Keep it operational only; status goes in `IMPLEMENTATION_PLAN.md`
+
+**❌ Don't**: Run `vralphy build` without planning first
+**✅ Do**: Always run `vralphy plan` before `vralphy build`
+
+**❌ Don't**: Write vague specs like "add authentication"
+**✅ Do**: Use `vralphy spec` for interactive, detailed specs
+
+**❌ Don't**: Set iteration counts too high (e.g., 1000)
+**✅ Do**: Start small (5-10), verify, then increase
+
+## Further Reading
+
+- [COMMANDS.md](./COMMANDS.md) - Complete command reference
+- [WORKFLOWS.md](./WORKFLOWS.md) - Common workflows
+- [DESIGN.md](./DESIGN.md) - Architecture and design decisions

package/docs/README.md

@@ -0,0 +1,110 @@
+# vralphy Documentation
+
+**Version-specific documentation for the installed vralphy package**
+
+This directory contains comprehensive documentation for vralphy, designed to help both humans and LLMs understand the tool, its methodology, and how to use it effectively.
+
+## What is vralphy?
+
+vralphy is a CLI tool that implements the **Ralph Playbook** - an autonomous AI development methodology where AI agents plan, build, test, and commit code changes with minimal human intervention.
+
+## Quick Navigation
+
+- **[METHODOLOGY.md](./METHODOLOGY.md)** - Deep dive into the Ralph methodology
+- **[COMMANDS.md](./COMMANDS.md)** - Complete command reference with examples
+- **[DESIGN.md](./DESIGN.md)** - Design principles and architecture
+- **[WORKFLOWS.md](./WORKFLOWS.md)** - Common workflows and patterns
+- **[EXAMPLES.md](./EXAMPLES.md)** - Real-world usage examples
+
+## Quick Start
+
+```bash
+# Initialize vralphy in your project
+vralphy init
+
+# This creates:
+# - .vralphy/AGENTS.md      (operational guide for build/test commands)
+# - .vralphy/prompts/       (customizable prompt templates)
+# - specs/                  (feature specifications directory)
+# - IMPLEMENTATION_PLAN.md  (task tracking)
+
+# Create a specification
+vralphy spec authentication
+
+# Run planning phase
+vralphy plan 3
+
+# Run build phase
+vralphy build 10
+```
+
+## Key Concepts
+
+### 1. Separation of Concerns
+
+- **specs/** - What to build (requirements)
+- **.vralphy/AGENTS.md** - How to build (commands)
+- **IMPLEMENTATION_PLAN.md** - What's left to do (tasks)
+
+### 2. AI-Powered Operations
+
+vralphy uses AI engines (claude/opencode/codex) to:
+- Analyze your project structure
+- Generate project-specific operational guides
+- Plan implementation strategies
+- Write and test code autonomously
+
+### 3. Non-Invasive Design
+
+- `.vralphy/AGENTS.md` - vralphy's internal guide
+- Root `AGENTS.md` - Your project's guide for other tools
+- No collision with existing AI tooling
+
+## Engine Support
+
+vralphy works with multiple AI engines:
+
+- **Claude** (default) - Anthropic's Claude CLI
+- **OpenCode** - OpenAI's code assistant
+- **Codex** - Alternative AI engine
+
+Engines are auto-detected. Install at least one:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+## File Locations
+
+After initialization, vralphy uses:
+
+```
+.vralphy/
+├── AGENTS.md           # Operational guide (build/test/run commands)
+└── prompts/
+    ├── plan.md         # Planning phase prompt template
+    ├── build.md        # Build phase prompt template
+    └── spec.md         # Spec creation prompt template
+```
+
+## Documentation Philosophy
+
+This documentation is designed to be:
+
+1. **LLM-Friendly** - Easy for AI assistants to parse and understand
+2. **Complete** - Covers all features and concepts
+3. **Practical** - Includes real examples and workflows
+4. **Version-Specific** - Matches the installed vralphy version
+
+## Getting Help
+
+- Read the detailed docs in this directory
+- Run `vralphy <command> --help` for command-specific help
+- Visit: https://github.com/vadimcomanescu/vralphy
+- Report issues: https://github.com/vadimcomanescu/vralphy/issues
+
+## Next Steps
+
+1. Read [METHODOLOGY.md](./METHODOLOGY.md) to understand the Ralph approach
+2. Browse [COMMANDS.md](./COMMANDS.md) for complete command reference
+3. Check [WORKFLOWS.md](./WORKFLOWS.md) for common usage patterns