vralphy 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,401 @@
+# 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
+
+## 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
+   - `AGENTS.md` - Operational guide (build/test commands)
+   - `PROMPT_plan.md` - Planning mode prompt
+   - `PROMPT_build.md` - Build mode prompt
+   - `PROMPT_spec.md` - Spec creation prompt
+   - `loop.sh` - Bash orchestration script
+   - `IMPLEMENTATION_PLAN.md` - Task tracking
+
+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
+```
+
+### 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 or opencode (default: claude)
+--model <model>         # Primary model: opus, sonnet, haiku (default: opus)
+--executor <model>      # Executor model for subagents (default: sonnet)
+--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
+```
+
+## How It Works
+
+### 1. Project Structure
+
+```
+your-project/
+├── specs/                    # Feature specifications
+│   ├── authentication.md
+│   └── api-endpoints.md
+├── AGENTS.md                 # Operational guide (~60 lines max)
+├── IMPLEMENTATION_PLAN.md    # Current task list
+├── PROMPT_plan.md            # Planning prompt template
+├── PROMPT_build.md           # Build prompt template
+└── loop.sh                   # Orchestration script
+```
+
+### 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 --model opus build
+```
+
+**OpenCode Engine**:
+```bash
+vralphy --engine opencode build
+```
+
+Engines auto-detected on startup. Install `claude` or `opencode` 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:
+- `opus` → claude-opus-4-5-20251101
+- `sonnet` → claude-sonnet-4-20250514
+- `haiku` → claude-haiku-3-5
+
+```bash
+vralphy --model opus --executor sonnet build
+```
+
+### 5. Skills & Agents
+
+**Skills** are domain-specific knowledge loaded into prompts:
+
+```markdown
+<!-- .claude/skills/react-patterns.md -->
+---
+name: react-patterns
+description: React best practices
+triggers:
+  - "React component"
+  - "useState"
+---
+
+# React Patterns
+[knowledge content]
+```
+
+**Agents** are specialized subagents that can be spawned:
+
+```markdown
+<!-- agents/code-reviewer.md -->
+---
+name: code-reviewer
+description: Reviews code for bugs
+model: sonnet
+---
+
+You are a code review specialist...
+```
+
+List available skills/agents:
+```bash
+vralphy skills
+vralphy agents
+```
+
+## Configuration
+
+Three ways to configure (priority order):
+
+### 1. CLI Flags
+```bash
+vralphy --engine claude --model opus --executor sonnet build
+```
+
+### 2. Environment Variables
+```bash
+export VRALPHY_ENGINE=claude
+export VRALPHY_MODEL=opus
+export VRALPHY_EXECUTOR=sonnet
+vralphy build
+```
+
+### 3. Config File
+```json
+{
+  "engine": "claude",
+  "model": "opus",
+  "executor": "sonnet",
+  "skillsDir": ".claude/skills",
+  "agentsDir": "agents"
+}
+```
+
+Save as `vralphy.config.json` in project root.
+
+## 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: Using loop.sh (Direct)
+
+```bash
+# Plan mode: 3 iterations
+./loop.sh plan 3
+
+# Build mode: 10 iterations
+./loop.sh 10
+
+# Build mode: unlimited
+./loop.sh
+```
+
+### Example 4: 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 AGENTS.md Lean
+- **Max ~60 lines**
+- Only operational commands (build, test, lint)
+- No verbose explanations or history
+- Status updates belong in `IMPLEMENTATION_PLAN.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
+```
+
+### 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vralphy",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "CLI tool implementing the Ralph Playbook methodology with engine flexibility",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -27,8 +28,16 @@
     "ralph",
     "methodology"
   ],
-  "author": "",
+  "author": "Vadim Comanescu",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vadimcomanescu/vralphy.git"
+  },
+  "homepage": "https://github.com/vadimcomanescu/vralphy#readme",
+  "bugs": {
+    "url": "https://github.com/vadimcomanescu/vralphy/issues"
+  },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/node": "^20.10.0",