@ralph-orchestrator/ralph-cli 0.0.1 → 2.0.5

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ralph Orchestrator Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,477 @@
-# @ralph-orchestrator/ralph-cli
+# Ralph Orchestrator
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Rust](https://img.shields.io/badge/rust-1.75+-orange)](https://www.rust-lang.org/)
+[![Build](https://img.shields.io/github/actions/workflow/status/mikeyobrien/ralph-orchestrator/ci.yml?branch=main&label=CI)](https://github.com/mikeyobrien/ralph-orchestrator/actions)
+[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+A hat-based multi-agent orchestration framework that keeps AI agents in a loop until the task is done.
 
-## Purpose
+> "Me fail English? That's unpossible!" - Ralph Wiggum
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ralph-orchestrator/ralph-cli`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+**Alpha Notice:** Ralph Orchestrator is under active development. It works today, but expect rough edges and breaking changes between releases.
 
-## What is OIDC Trusted Publishing?
+v1.0.0 was ralphed into existence with little oversight and guidance. v2.0.0 is a simpler, more-structured implementation. Looking for the old version? See [v1.2.3](https://github.com/mikeyobrien/ralph-orchestrator/tree/v1.2.3). 
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Table of Contents
 
-## Setup Instructions
+- [What is Ralph?](#what-is-ralph)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Presets](#presets)
+- [Key Concepts](#key-concepts)
+- [CLI Reference](#cli-reference)
+- [Architecture](#architecture)
+- [Building & Testing](#building--testing)
+- [Contributing](#contributing)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
 
-To properly configure OIDC trusted publishing for this package:
+## What is Ralph?
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+Ralph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous AI agent iteration. Unlike simple loops, Ralph v2 introduces **hat-based orchestration**: specialized agent roles that coordinate through events.
 
-## DO NOT USE THIS PACKAGE
+> "The orchestrator is a thin coordination layer, not a platform. Agents are smart; let them do the work."
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+### The Ralph Tenets
 
-## More Information
+1. **Fresh Context Is Reliability** — Each iteration clears context. Re-read specs, plan, code every cycle.
+2. **Backpressure Over Prescription** — Don't prescribe how; create gates that reject bad work.
+3. **The Plan Is Disposable** — Regeneration costs one planning loop. Cheap.
+4. **Disk Is State, Git Is Memory** — Files are the handoff mechanism.
+5. **Steer With Signals, Not Scripts** — Add signs, not scripts.
+6. **Let Ralph Ralph** — Sit *on* the loop, not *in* it.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+See [AGENTS.md](AGENTS.md) for the full philosophy.
+
+## Features
+
+- **Multi-Backend Support** — Works with Claude Code, Kiro, Gemini CLI, Codex, and Amp
+- **Hat System** — Specialized agent personas with distinct behaviors
+- **Event-Driven Coordination** — Hats communicate through typed events with glob pattern matching
+- **Backpressure Enforcement** — Gates that reject incomplete work (tests, lint, typecheck)
+- **Presets Library** — 20+ pre-configured workflows for common development patterns
+- **Interactive TUI** — Real-time terminal UI for monitoring agent activity (experimental)
+- **Session Recording** — Record and replay sessions for debugging and testing (experimental)
+
+## Installation
+
+### Prerequisites
+
+- [Rust](https://rustup.rs/) 1.75+
+- At least one AI CLI:
+  - [Claude Code](https://github.com/anthropics/claude-code) (recommended)
+  - [Kiro](https://kiro.dev/)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+  - [Codex](https://github.com/openai/codex)
+  - [Amp](https://github.com/sourcegraph/amp)
+
+### Via npm (Recommended)
+
+```bash
+# Install globally
+npm install -g @ralph-orchestrator/ralph
+
+# Or run directly with npx
+npx @ralph-orchestrator/ralph --version
+```
+
+### Via Cargo
+
+```bash
+cargo install ralph-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/mikeyobrien/ralph-orchestrator.git
+cd ralph-orchestrator
+cargo build --release
+
+# Add to PATH
+export PATH="$PATH:$(pwd)/target/release"
+
+# Or create symlink
+sudo ln -s $(pwd)/target/release/ralph /usr/local/bin/ralph
+```
+
+### Verify Installation
+
+```bash
+ralph --version
+ralph --help
+```
+
+### Migrating from v1 (Python)
+
+If you have the old Python-based Ralph v1 installed, uninstall it first to avoid conflicts:
+
+```bash
+# If installed via pip
+pip uninstall ralph-orchestrator
+
+# If installed via pipx
+pipx uninstall ralph-orchestrator
+
+# If installed via uv
+uv tool uninstall ralph-orchestrator
+
+# Verify removal
+which ralph  # Should return nothing or point to new Rust version
+```
+
+The v1 Python version is no longer maintained. See [v1.2.3](https://github.com/mikeyobrien/ralph-orchestrator/tree/v1.2.3) for historical reference.
+
+## Quick Start
+
+### 1. Initialize a Project
+
+```bash
+# Minimal config for Claude (recommended)
+ralph init --backend claude
+
+# Use a preset workflow
+ralph init --preset tdd-red-green
+
+# Combine preset with different backend
+ralph init --preset spec-driven --backend kiro
+
+# See all available presets
+ralph init --list-presets
+```
+
+This creates `ralph.yml` in your current directory.
+
+### 2. Define Your Task
+
+**Option A:** Create a `PROMPT.md` file:
+
+```bash
+cat > PROMPT.md << 'EOF'
+Build a REST API with the following endpoints:
+- POST /users - Create a new user
+- GET /users/:id - Get user by ID
+- PUT /users/:id - Update user
+- DELETE /users/:id - Delete user
+
+Use Express.js with TypeScript. Include input validation
+and proper error handling.
+EOF
+```
+
+**Option B:** Pass inline prompt when running:
+
+```bash
+ralph run -p "Add input validation to the user API endpoints"
+```
+
+### 3. Run Ralph
+
+```bash
+# Autonomous mode (headless, default)
+ralph run
+
+# With inline prompt
+ralph run -p "Implement the login endpoint with JWT authentication"
+
+# Interactive TUI mode (experimental)
+ralph run -i
+
+# Resume interrupted session
+ralph resume
+
+# Dry run (show what would execute)
+ralph run --dry-run
+```
+
+## Configuration
+
+Ralph uses a YAML configuration file (`ralph.yml` by default).
+
+### Minimal Configuration
+
+```yaml
+# ralph.yml
+cli:
+  backend: "claude"
+
+event_loop:
+  completion_promise: "LOOP_COMPLETE"
+  max_iterations: 100
+```
+
+### Full Configuration Reference
+
+```yaml
+# Event loop settings
+event_loop:
+  completion_promise: "LOOP_COMPLETE"  # Output that signals completion
+  max_iterations: 100                   # Maximum orchestration loops
+  max_runtime_seconds: 14400            # 4 hours max runtime
+  idle_timeout_secs: 1800               # 30 min idle timeout
+  starting_event: "task.start"          # First event published
+
+# CLI backend settings
+cli:
+  backend: "claude"                     # claude, kiro, gemini, codex, amp, custom
+  prompt_mode: "arg"                    # arg (CLI argument) or stdin
+  experimental_tui: false               # Enable TUI mode support
+
+# Core behaviors (always injected into prompts)
+core:
+  scratchpad: ".agent/scratchpad.md"    # Shared memory across iterations
+  specs_dir: "./specs/"                 # Directory for specifications
+  guardrails:                           # Rules injected into every prompt
+    - "Fresh context each iteration - scratchpad is memory"
+    - "Don't assume 'not implemented' - search first"
+    - "Backpressure is law - tests/typecheck/lint must pass"
+
+# Custom hats (omit to use default planner/builder)
+hats:
+  my_hat:
+    name: "My Hat Name"                 # Display name
+    triggers: ["some.event"]            # Events that activate this hat
+    publishes: ["other.event"]          # Events this hat can emit
+    instructions: |                     # Prompt instructions
+      What this hat should do...
+```
+
+
+## Presets
+
+Presets are pre-configured workflows for common development patterns.
+
+### Development Workflows
+
+| Preset | Pattern | Description |
+|--------|---------|-------------|
+| `feature` | Planner-Builder | Standard feature development |
+| `feature-minimal` | Single hat | Minimal feature development |
+| `tdd-red-green` | Test-Implement-Refactor | TDD with red-green-refactor cycle |
+| `spec-driven` | Spec-Build-Verify | Specification-first development |
+| `refactor` | Analyze-Plan-Execute | Code refactoring workflow |
+
+### Debugging & Investigation
+
+| Preset | Pattern | Description |
+|--------|---------|-------------|
+| `debug` | Investigate-Fix-Verify | Bug investigation and fixing |
+| `incident-response` | Triage-Fix-Postmortem | Production incident handling |
+| `code-archaeology` | Explore-Document-Present | Legacy code understanding |
+
+### Review & Quality
+
+| Preset | Pattern | Description |
+|--------|---------|-------------|
+| `review` | Analyze-Critique-Suggest | Code review workflow |
+| `pr-review` | Multi-Perspective | PR review with specialized reviewers |
+| `adversarial-review` | Critic-Defender | Devil's advocate review style |
+
+### Documentation
+
+| Preset | Pattern | Description |
+|--------|---------|-------------|
+| `docs` | Write-Review-Publish | Documentation writing |
+| `documentation-first` | Doc-Implement-Sync | Doc-first development |
+
+### Specialized
+
+| Preset | Pattern | Description |
+|--------|---------|-------------|
+| `api-design` | Design-Implement-Document | API-first development |
+| `migration-safety` | Analyze-Migrate-Verify | Safe code migrations |
+| `performance-optimization` | Profile-Optimize-Benchmark | Performance tuning |
+| `scientific-method` | Hypothesis-Experiment-Conclude | Experimental approach |
+| `mob-programming` | Rotate roles | Simulated mob programming |
+| `socratic-learning` | Question-Answer-Synthesize | Learning through dialogue |
+| `research` | Gather-Analyze-Synthesize | Research and analysis |
+| `gap-analysis` | Current-Target-Plan | Gap identification |
+
+### Using Presets
+
+```bash
+# List all available presets
+ralph init --list-presets
+
+# Initialize with a preset
+ralph init --preset tdd-red-green
+
+# Use preset with different backend
+ralph init --preset spec-driven --backend gemini
+
+# Override existing config
+ralph init --preset debug --force
+```
+
+## Key Concepts
+
+### Hats
+
+Hats are specialized agent personas. Each hat has:
+
+- **Triggers**: Events that activate this hat
+- **Publishes**: Events this hat can emit
+- **Instructions**: Prompt injected when hat is active
+
+View event history:
+
+```bash
+ralph events
+```
+
+### Scratchpad
+
+All hats share `.agent/scratchpad.md` — persistent memory across iterations. This enables hats to build on previous work rather than starting fresh.
+
+The scratchpad is the primary mechanism for:
+- Task tracking (with `[ ]`, `[x]`, `[~]` markers)
+- Context preservation between iterations
+- Handoff between hats
+
+### Backpressure
+
+Ralph enforces quality gates through backpressure. When a builder publishes `build.done`, it must include evidence:
+
+```
+tests: pass, lint: pass, typecheck: pass
+```
+
+## CLI Reference
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `ralph run` | Run the orchestration loop (default) |
+| `ralph resume` | Resume from existing scratchpad |
+| `ralph events` | View event history |
+| `ralph init` | Initialize configuration file |
+| `ralph clean` | Clean up `.agent/` directory |
+| `ralph emit` | Emit an event to the event log |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `-c, --config <FILE>` | Config file path (default: `ralph.yml`) |
+| `-v, --verbose` | Verbose output |
+| `--color <MODE>` | Color output: `auto`, `always`, `never` |
+
+### `ralph run` Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --prompt <TEXT>` | Inline prompt text |
+| `-P, --prompt-file <FILE>` | Prompt file path |
+| `--max-iterations <N>` | Override max iterations |
+| `--completion-promise <TEXT>` | Override completion trigger |
+| `--dry-run` | Show what would execute |
+| `-i, --interactive` | Enable TUI mode (experimental) |
+| `-a, --autonomous` | Force headless mode |
+| `--idle-timeout <SECS>` | TUI idle timeout (default: 30) |
+| `--record-session <FILE>` | Record session to JSONL |
+| `-q, --quiet` | Suppress output (for CI) |
+
+### `ralph init` Options
+
+| Option | Description |
+|--------|-------------|
+| `--backend <NAME>` | Backend: `claude`, `kiro`, `gemini`, `codex`, `amp` |
+| `--preset <NAME>` | Use preset configuration |
+| `--list-presets` | List available presets |
+| `--force` | Overwrite existing config |
+
+## Architecture
+
+Ralph is organized as a Cargo workspace with six crates:
+
+| Crate | Purpose |
+|-------|---------|
+| `ralph-proto` | Protocol types: Event, Hat, Topic, Error |
+| `ralph-core` | Business logic: EventLoop, HatRegistry, Config |
+| `ralph-adapters` | CLI backend integrations (Claude, Kiro, Gemini, etc.) |
+| `ralph-tui` | Terminal UI with ratatui |
+| `ralph-cli` | Binary entry point and CLI parsing |
+| `ralph-bench` | Benchmarking harness (dev-only) |
+
+## Building & Testing
+
+### Build
+
+```bash
+cargo build           # Debug build
+cargo build --release # Release build
+```
+
+### Test
+
+```bash
+# Run all tests (includes smoke tests with JSONL replay)
+cargo test
+
+# Run smoke tests specifically
+cargo test -p ralph-core smoke_runner
+
+# Run Kiro-specific smoke tests
+cargo test -p ralph-core kiro
+```
+
+### Smoke Tests
+
+Smoke tests use recorded JSONL fixtures instead of live API calls — fast, free, and deterministic.
+
+**Fixture locations:**
+- `crates/ralph-core/tests/fixtures/basic_session.jsonl` — Claude CLI session
+- `crates/ralph-core/tests/fixtures/kiro/` — Kiro CLI sessions
+
+**Recording new fixtures:**
+
+```bash
+# Record a session
+ralph run -c ralph.yml --record-session session.jsonl -p "your prompt"
+
+# Or capture raw CLI output
+claude -p "your prompt" 2>&1 | tee output.txt
+```
+
+### Linting
+
+```bash
+cargo clippy --all-targets --all-features
+cargo fmt --check
+```
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Write tests for new functionality
+4. Ensure `cargo test` passes
+5. Run `cargo clippy` and `cargo fmt`
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+See [AGENTS.md](AGENTS.md) for development philosophy and conventions.
+
+## License
+
+MIT License — See [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- **[Geoffrey Huntley](https://ghuntley.com/ralph/)** — Creator of the Ralph Wiggum technique
+- **[Harper Reed](https://harper.blog/)** — Spec-driven development methodology
+- **[Strands Agent SOPs](https://github.com/strands-agents/agent-sop)** — Natural language workflows that enable AI agents to perform complex, multi-step tasks with consistency and reliability. 
+- **[ratatui](https://ratatui.rs/)** — Terminal UI framework
+- **[portable-pty](https://crates.io/crates/portable-pty)** — Cross-platform PTY support
 
 ---
 
-**Maintained for OIDC setup purposes only**
+*"I'm learnding!" - Ralph Wiggum*