vralphy 0.2.0 → 0.3.1

package/README.md

@@ -17,6 +17,23 @@ The methodology emphasizes:
 - **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

package/docs/COMMANDS.md

@@ -0,0 +1,613 @@
+# Command Reference
+
+Complete reference for all vralphy commands with examples, options, and use cases.
+
+## Command Overview
+
+| Command | Purpose | Phase |
+|---------|---------|-------|
+| `init` | Initialize vralphy in a project | Setup |
+| `spec` | Create feature specifications | Requirements |
+| `plan` | Analyze and create implementation plan | Planning |
+| `build` | Implement features autonomously | Implementation |
+| `cleanup` | Remove vralphy from project | Cleanup |
+| `engines` | List available AI engines | Utility |
+| `skills` | List available skills | Utility |
+| `agents` | List available agents | Utility |
+
+---
+
+## `vralphy init`
+
+Initialize a project for vralphy by creating required files and directories.
+
+### Behavior
+
+**With AI** (default when engine available):
+1. Detects available AI engines (claude/opencode/codex)
+2. Gathers project context (package.json, existing docs, src/ structure)
+3. AI generates project-specific `.vralphy/AGENTS.md`
+4. Creates scaffold (specs/, prompts/, IMPLEMENTATION_PLAN.md)
+
+**Without AI** (fallback):
+1. Detects build system (node/rust/go/python)
+2. Extracts commands from package.json/Cargo.toml/go.mod
+3. Generates template-based `.vralphy/AGENTS.md`
+4. Creates scaffold
+
+### Options
+
+```bash
+vralphy init                      # AI-powered (default)
+vralphy init --no-ai              # Skip AI, use template
+vralphy init --approve            # Review AGENTS.md before saving
+vralphy init --engine <name>      # Use specific engine (claude|opencode|codex)
+vralphy init --from <path>        # Initialize different directory
+```
+
+### Examples
+
+**Basic initialization**:
+```bash
+cd your-project
+vralphy init
+```
+
+**Review before saving**:
+```bash
+vralphy init --approve
+# Shows preview of AGENTS.md
+# Prompts: "Save this AGENTS.md? [y/N]"
+```
+
+**Force template mode**:
+```bash
+vralphy init --no-ai
+# Skips AI generation
+# Uses template-based approach
+```
+
+**Use specific engine**:
+```bash
+vralphy init --engine codex
+# Uses codex instead of auto-detected engine
+```
+
+### What Gets Created
+
+```
+.vralphy/
+├── AGENTS.md           # Operational guide (AI-generated or template)
+└── prompts/
+    ├── plan.md         # Planning phase prompt
+    ├── build.md        # Build phase prompt
+    └── spec.md         # Spec creation prompt
+
+specs/                  # Empty directory for specifications
+
+IMPLEMENTATION_PLAN.md  # Initial task list
+```
+
+### When to Use
+
+- **New project**: Starting vralphy in a new project
+- **Existing project**: Adding vralphy to existing project
+- **Re-initialize**: After cleanup, to start fresh
+
+---
+
+## `vralphy spec [topic]`
+
+Create feature specifications through interactive conversation with AI.
+
+### Behavior
+
+1. AI asks clarifying questions about the feature
+2. User provides answers
+3. AI generates comprehensive specification
+4. Spec saved to `specs/<topic>.md`
+
+**Note**: Only works with interactive engines (claude). Non-interactive engines will show an error.
+
+### Options
+
+```bash
+vralphy spec <topic>              # Interactive spec creation
+```
+
+### Examples
+
+**Create authentication spec**:
+```bash
+vralphy spec authentication
+
+# AI asks:
+# - Authentication method? (JWT, session, OAuth)
+# - User model fields?
+# - Password requirements?
+# - Two-factor authentication?
+
+# Output: specs/authentication.md
+```
+
+**Create API spec**:
+```bash
+vralphy spec api-rate-limiting
+
+# AI asks about:
+# - Rate limit tiers
+# - Time windows
+# - Response headers
+# - Override mechanisms
+
+# Output: specs/api-rate-limiting.md
+```
+
+### Specification Format
+
+Generated specs follow this structure:
+
+```markdown
+# Feature Name
+
+## Overview
+Brief description of the feature
+
+## Requirements
+- [ ] Functional requirement 1
+- [ ] Functional requirement 2
+
+## Acceptance Criteria
+- [ ] Testable criterion 1
+- [ ] Testable criterion 2
+
+## Edge Cases
+- Edge case 1
+- Edge case 2
+
+## Dependencies
+- Dependency 1
+- Dependency 2
+```
+
+### When to Use
+
+- **Before planning**: Define requirements before implementation
+- **Complex features**: Features needing clarification
+- **Team alignment**: Document agreed-upon behavior
+
+---
+
+## `vralphy plan [iterations]`
+
+Analyze codebase and create/update implementation plan.
+
+### Behavior
+
+1. Reads `.vralphy/AGENTS.md` for operational commands
+2. Studies all `specs/*.md` with parallel subagents (up to 250)
+3. Analyzes existing codebase with parallel subagents (up to 500)
+4. Compares implementation against specifications
+5. Creates/updates `IMPLEMENTATION_PLAN.md` with prioritized tasks
+6. **Does not write code** - planning only
+
+### Options
+
+```bash
+vralphy plan [iterations]         # Default: unlimited
+```
+
+### Examples
+
+**Single planning iteration**:
+```bash
+vralphy plan 1
+# Quick analysis and plan update
+```
+
+**Deep planning session**:
+```bash
+vralphy plan 5
+# Thorough analysis over 5 iterations
+# Each iteration refines the plan
+```
+
+**Continuous planning**:
+```bash
+vralphy plan
+# Runs until complete or interrupted
+```
+
+### What It Does
+
+**Scans for**:
+- Missing functionality from specs
+- TODO comments in code
+- Placeholder implementations
+- Skipped or flaky tests
+- Inconsistent patterns
+- Technical debt
+
+**Outputs**:
+- Prioritized task list
+- Dependency relationships
+- Implementation strategy
+- Gap analysis
+
+### When to Use
+
+- **Before building**: Always plan before implementing
+- **After spec changes**: Re-plan when specs are updated
+- **Progress check**: Verify current implementation status
+- **New team members**: Understand what needs to be done
+
+---
+
+## `vralphy build [iterations]`
+
+Implement functionality autonomously with testing and commits.
+
+### Behavior
+
+1. Reads `.vralphy/AGENTS.md` for commands
+2. Reads `IMPLEMENTATION_PLAN.md` for tasks
+3. Picks highest priority task
+4. Searches codebase to understand current state
+5. Implements functionality using parallel subagents
+6. Runs tests after changes
+7. If tests pass: commits and pushes
+8. If tests fail: debugs and retries
+9. Updates `IMPLEMENTATION_PLAN.md`
+10. Repeats until done or iteration limit reached
+
+### Options
+
+```bash
+vralphy build [iterations]        # Default: unlimited
+```
+
+### Examples
+
+**Short build session**:
+```bash
+vralphy build 5
+# Implement up to 5 tasks
+# Good for testing or small features
+```
+
+**Standard build session**:
+```bash
+vralphy build 20
+# Implement up to 20 tasks
+# Good for medium features
+```
+
+**Continuous build**:
+```bash
+vralphy build
+# Runs until IMPLEMENTATION_PLAN.md is empty
+# or until interrupted
+```
+
+### What It Does
+
+**Per iteration**:
+1. Pick task from plan
+2. Search codebase (500 parallel subagents)
+3. Write/modify code
+4. Run tests (1 sequential subagent)
+5. Commit if tests pass
+6. Update plan
+7. Git push
+
+**Commits automatically**:
+- Descriptive commit messages
+- Small, focused changes
+- One feature/fix per commit
+
+### Safety Features
+
+- Tests must pass before committing
+- Updates plan after each change
+- Updates `.vralphy/AGENTS.md` when learning new commands
+- Can be interrupted safely (Ctrl+C)
+
+### When to Use
+
+- **After planning**: Always plan first
+- **Feature implementation**: Build new functionality
+- **Bug fixes**: Fix issues in IMPLEMENTATION_PLAN.md
+- **Refactoring**: Systematic code improvements
+
+---
+
+## `vralphy cleanup`
+
+Remove vralphy from a project.
+
+### Behavior
+
+1. Checks if vralphy is initialized (`.vralphy/` exists)
+2. Shows what will be removed
+3. Prompts for confirmation (unless `--force`)
+4. Removes vralphy files and directories
+5. Reports what was removed/kept/not-found
+
+### Options
+
+```bash
+vralphy cleanup                   # Interactive with confirmation
+vralphy cleanup --force           # Skip confirmation
+vralphy cleanup --remove-specs    # Also remove specs/
+vralphy cleanup --from <path>     # Clean different directory
+```
+
+### Examples
+
+**Standard cleanup**:
+```bash
+vralphy cleanup
+
+# Shows:
+# The following will be removed:
+#   - .vralphy/
+#   - IMPLEMENTATION_PLAN.md
+# The following will be kept:
+#   - specs/ (use --remove-specs to delete)
+# Proceed with cleanup? [y/N]
+```
+
+**Force cleanup**:
+```bash
+vralphy cleanup --force
+# No confirmation prompt
+# Removes immediately
+```
+
+**Complete cleanup**:
+```bash
+vralphy cleanup --remove-specs --force
+# Removes everything including specs/
+# No confirmation
+```
+
+### What Gets Removed
+
+**Always removed**:
+- `.vralphy/` - All vralphy config and prompts
+- `IMPLEMENTATION_PLAN.md` - Task list
+
+**Kept by default**:
+- `specs/` - Your specifications (use `--remove-specs` to delete)
+
+**Never removed**:
+- Your source code
+- Git history
+- Other project files
+
+### When to Use
+
+- **Switching tools**: Moving to a different workflow
+- **Fresh start**: Re-initialize from scratch
+- **Project cleanup**: Removing unused tools
+- **Testing**: Clean between test runs
+
+---
+
+## `vralphy engines`
+
+List available AI engines on your system.
+
+### Behavior
+
+Checks for installed engine CLIs:
+- `claude` command (Anthropic)
+- `opencode` command (OpenAI)
+- `codex` command (Custom)
+
+### Examples
+
+```bash
+vralphy engines
+
+# Output:
+# Available engines:
+#   - claude
+#   - opencode
+```
+
+**No engines installed**:
+```bash
+vralphy engines
+
+# Output:
+# Available engines:
+#   (none found - install claude or opencode CLI)
+```
+
+### When to Use
+
+- **Troubleshooting**: Verify engine installation
+- **Multi-engine setup**: Check which engines are available
+- **Documentation**: Before running init/plan/build
+
+---
+
+## `vralphy skills`
+
+List available skills for the current engine.
+
+### Behavior
+
+1. Detects current engine
+2. Looks in engine-specific skills directory
+3. Lists all `.md` files with frontmatter
+
+**Skill locations**:
+- Claude: `.claude/skills/`
+- OpenCode: `.opencode/skills/`
+- Codex: `.codex/skills/`
+
+### Examples
+
+```bash
+vralphy skills
+
+# Output:
+# Available skills:
+#   - react-patterns: React best practices
+#   - security-audit: Security review patterns
+#   - api-design: RESTful API guidelines
+```
+
+### When to Use
+
+- **Discovery**: See what domain knowledge is available
+- **Planning**: Before starting complex features
+- **Documentation**: Understanding available resources
+
+---
+
+## `vralphy agents`
+
+List available specialized agents for the current engine.
+
+### Behavior
+
+1. Detects current engine
+2. Looks in engine-specific agents directory
+3. Lists all `.md` files with frontmatter
+
+**Agent locations**:
+- Claude: `.claude/agents/`
+- OpenCode: `.opencode/agents/`
+- Codex: `.codex/agents/`
+
+### Examples
+
+```bash
+vralphy agents
+
+# Output:
+# Available agents:
+#   - code-reviewer (sonnet): Reviews code for bugs
+#   - architect (opus): Designs system architecture
+#   - tester (sonnet): Writes comprehensive tests
+```
+
+### When to Use
+
+- **Discovery**: See what specialized help is available
+- **Planning**: Before starting complex features
+- **Delegation**: Understanding what can be delegated
+
+---
+
+## Global Flags
+
+These flags work with all commands:
+
+```bash
+--engine <engine>       # Select engine (claude|opencode|codex)
+--model <model>         # Primary model (opus|sonnet|haiku)
+--executor <model>      # Executor model for subagents
+--skills <path>         # Custom skills directory
+--agents <path>         # Custom agents directory
+--config <path>         # Custom config file
+--verbose               # Verbose output
+--dry-run               # Show what would execute (no changes)
+```
+
+### Examples
+
+**Use specific engine**:
+```bash
+vralphy --engine codex build 10
+```
+
+**Use haiku for speed**:
+```bash
+vralphy --model haiku --executor haiku build 20
+```
+
+**Dry run to preview**:
+```bash
+vralphy --dry-run build 1
+# Shows the prompt that would be sent
+# Does not execute
+```
+
+**Verbose for debugging**:
+```bash
+vralphy --verbose plan 2
+# Shows detailed execution information
+```
+
+---
+
+## Exit Codes
+
+vralphy uses standard exit codes:
+
+- `0` - Success
+- `1` - General error (command failed)
+- `130` - Interrupted (Ctrl+C)
+
+---
+
+## Environment Variables
+
+Configure vralphy with environment variables:
+
+```bash
+VRALPHY_ENGINE=claude       # Default engine
+VRALPHY_MODEL=opus          # Default primary model
+VRALPHY_EXECUTOR=sonnet     # Default executor model
+```
+
+Example:
+```bash
+export VRALPHY_ENGINE=codex
+export VRALPHY_MODEL=opus
+vralphy build 10
+```
+
+---
+
+## Configuration File
+
+Create `vralphy.config.json` in project root:
+
+```json
+{
+  "engine": "claude",
+  "model": "opus",
+  "executor": "sonnet",
+  "skillsDir": ".claude/skills",
+  "agentsDir": ".claude/agents"
+}
+```
+
+**Priority**: CLI flags > Environment variables > Config file > Defaults
+
+---
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Start new project | `vralphy init` |
+| Define feature | `vralphy spec <name>` |
+| Plan work | `vralphy plan 3` |
+| Implement | `vralphy build 20` |
+| Check engines | `vralphy engines` |
+| Remove vralphy | `vralphy cleanup` |
+| Get help | `vralphy <cmd> --help` |
+
+---
+
+## Next Steps
+
+- Read [METHODOLOGY.md](./METHODOLOGY.md) for the Ralph approach
+- Check [WORKFLOWS.md](./WORKFLOWS.md) for common patterns
+- See [EXAMPLES.md](./EXAMPLES.md) for real-world usage