vralphy 0.3.0 → 0.3.1

package/README.md

@@ -28,6 +28,10 @@ vralphy includes **LLM-friendly documentation** in the `docs/` directory (bundle
 - **[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

package/llms.txt

@@ -0,0 +1,104 @@
+# vralphy
+
+> vralphy is a CLI tool implementing the Ralph Playbook - an autonomous AI development methodology where AI agents plan, build, test, and commit code changes with minimal human intervention. It works with multiple AI engines (Claude, OpenCode, Codex) and emphasizes specification-driven development, parallel execution, and incremental progress.
+
+## Core Documentation
+
+- [README](README.md): Quick start, installation, and overview
+- [Methodology](docs/METHODOLOGY.md): Deep dive into the Ralph Playbook methodology - three phases (spec, plan, build), loops, design principles, and autonomous operation patterns
+- [Commands](docs/COMMANDS.md): Complete command reference with all options, flags, examples, and use cases for init, spec, plan, build, cleanup, and utility commands
+- [Design Principles](docs/DESIGN.md): Architecture, design decisions, engine abstraction, model tiering, parallelism strategies, and extensibility patterns
+- [Workflows](docs/WORKFLOWS.md): 10 common workflows including new feature development, bug fixes, refactoring, adding to existing projects, and collaborative development
+- [Examples](docs/EXAMPLES.md): 10 real-world examples across different scenarios - REST APIs, React components, CLI tools, database migrations, testing, and microservices
+
+## Key Concepts
+
+The Ralph methodology consists of three phases:
+
+1. **Specification Phase** (`vralphy spec`): Interactive conversation with AI to define requirements, capture edge cases, and document acceptance criteria
+2. **Planning Phase** (`vralphy plan`): AI analyzes codebase with 500+ parallel subagents, compares against specs, and creates prioritized implementation plan
+3. **Build Phase** (`vralphy build`): AI autonomously implements features, runs tests, commits changes, and updates plan - loops until complete
+
+## Project Structure
+
+After initialization, vralphy creates:
+
+- `.vralphy/AGENTS.md`: AI-generated operational guide (build/test/run commands) - max 60 lines, project-specific
+- `.vralphy/prompts/`: Customizable prompt templates (plan.md, build.md, spec.md)
+- `specs/`: Feature specifications written by humans defining WHAT to build
+- `IMPLEMENTATION_PLAN.md`: Living task list updated by AI showing what's left to do
+
+## Commands Quick Reference
+
+- `vralphy init`: Initialize project with AI-generated operational guide
+- `vralphy spec <topic>`: Create specification through interactive conversation
+- `vralphy plan [iterations]`: Analyze codebase and create implementation plan
+- `vralphy build [iterations]`: Autonomously implement features with tests
+- `vralphy cleanup`: Remove vralphy from project
+- `vralphy engines`: List available AI engines
+- `vralphy --help`: Show all commands and options
+
+## Design Philosophy
+
+- **Separation of Concerns**: specs/ defines WHAT, .vralphy/AGENTS.md defines HOW, IMPLEMENTATION_PLAN.md tracks what's left
+- **Non-Invasive**: All vralphy files in .vralphy/ directory - no collision with existing AGENTS.md for Claude/OpenCode
+- **Engine Abstraction**: Works with Claude, OpenCode, or Codex - auto-detects available engines
+- **Model Tiering**: Expensive models (opus) for reasoning, cheap models (sonnet) for execution
+- **Massive Parallelism**: 500+ subagents for reading, 1 agent for building/testing
+- **Test-Driven**: Never commits without passing tests - autonomous but safe
+- **Incremental**: Small focused commits, frequent updates to plan
+
+## Typical Workflow
+
+1. Initialize: `vralphy init` (creates .vralphy/, specs/, plan)
+2. Define feature: `vralphy spec authentication` (interactive conversation)
+3. Plan: `vralphy plan 3` (AI analyzes and creates implementation plan)
+4. Build: `vralphy build 20` (AI implements, tests, commits autonomously)
+5. Verify: Check `IMPLEMENTATION_PLAN.md` for remaining work
+6. Iterate: Repeat steps 3-5 until complete
+
+## Installation
+
+```bash
+npm install -g vralphy
+```
+
+Requires Node.js 18+ and at least one AI engine installed (claude, opencode, or codex).
+
+## Configuration
+
+Three ways to configure (priority: CLI flags > env vars > config file):
+
+- CLI: `vralphy --engine claude --model opus --executor sonnet`
+- Environment: `VRALPHY_ENGINE=claude VRALPHY_MODEL=opus`
+- Config: Create `vralphy.config.json` in project root
+
+## Optional Resources
+
+- [GitHub Repository](https://github.com/vadimcomanescu/vralphy): Source code, issues, contributions
+- [npm Package](https://www.npmjs.com/package/vralphy): Package registry page
+- [Changelog](https://github.com/vadimcomanescu/vralphy/releases): Version history and release notes
+
+## Use Cases
+
+vralphy is particularly effective for:
+
+- Building REST APIs and microservices from specifications
+- Adding comprehensive test coverage to existing codebases
+- Refactoring and code quality improvements
+- Creating component libraries and design systems
+- Database migrations and schema changes
+- CLI tool development
+- Documentation generation
+- Bug fixes and feature additions
+- Prototyping and MVP development
+
+## Time Savings
+
+Typical time savings compared to manual development:
+
+- New features: 70-80% faster
+- Bug fixes: 80-90% faster
+- Adding tests: 80-85% faster
+- Refactoring: 60-70% faster
+- Documentation: 75-85% faster

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vralphy",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "CLI tool implementing the Ralph Playbook methodology with engine flexibility",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
     "dist",
     "bin",
     "docs",
+    "llms.txt",
     "README.md"
   ],
   "scripts": {