@ralph-orchestrator/ralph-cli 2.0.7 → 2.0.9

package/README.md

@@ -2,11 +2,11 @@
 
 [![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/release.yml?branch=main&label=CI)](https://github.com/mikeyobrien/ralph-orchestrator/actions)
+[![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)
 
 
-A hat-based multi-agent orchestration framework that keeps AI agents in a loop until the task is done.
+A hat-based orchestration framework that keeps Ralph in a loop until the task is done.
 
 > "Me fail English? That's unpossible!" - Ralph Wiggum
 
@@ -32,9 +32,22 @@ v1.0.0 was ralphed into existence with little oversight and guidance. v2.0.0 is
 
 ## What is Ralph?
 
-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.
+Ralph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous iteration.
 
-> "The orchestrator is a thin coordination layer, not a platform. Agents are smart; let them do the work."
+> "The orchestrator is a thin coordination layer, not a platform. Ralph is smart; let Ralph do the work."
+
+### Two Modes of Operation
+
+Ralph supports two orchestration styles:
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| **Traditional** | Simple loop — Ralph iterates until done | Quick tasks, simple automation, minimal config |
+| **Hat-Based** | Ralph can wear many hats — specialized personas coordinate through events | Complex workflows, multi-step processes, role separation |
+
+**Traditional mode** is the original Ralph Wiggum approach: start a loop, let it run until it outputs the completion promise. No roles, no events, just iteration.
+
+**Hat-based mode** adds structure: specialized personas coordinate through events. You define the roles that fit your workflow — reviewers, testers, documenters, whatever makes sense. Presets provide ready-made patterns like TDD or spec-driven development.
 
 ### The Ralph Tenets
 
@@ -49,12 +62,12 @@ 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
+- **Multi-Backend Support** — Works with Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, and OpenCode
+- **Hat System** — Specialized Ralph 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)
+- **Interactive TUI** — Real-time terminal UI for monitoring Ralph's activity (experimental)
 - **Session Recording** — Record and replay sessions for debugging and testing (experimental)
 
 ## Installation
@@ -68,6 +81,8 @@ See [AGENTS.md](AGENTS.md) for the full philosophy.
   - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
   - [Codex](https://github.com/openai/codex)
   - [Amp](https://github.com/sourcegraph/amp)
+  - [Copilot CLI](https://docs.github.com/copilot) (`npm install -g @github/copilot`)
+  - [OpenCode](https://opencode.ai/) (`curl -fsSL https://opencode.ai/install | bash`)
 
 ### Via npm (Recommended)
 
@@ -79,6 +94,12 @@ npm install -g @ralph-orchestrator/ralph-cli
 npx @ralph-orchestrator/ralph-cli --version
 ```
 
+### Via Homebrew (macOS)
+
+```bash
+brew install ralph-orchestrator
+```
+
 ### Via Cargo
 
 ```bash
@@ -131,10 +152,10 @@ The v1 Python version is no longer maintained. See [v1.2.3](https://github.com/m
 ### 1. Initialize a Project
 
 ```bash
-# Minimal config for Claude (recommended)
+# Traditional mode — simple loop, no hats (recommended for getting started)
 ralph init --backend claude
 
-# Use a preset workflow
+# Hat-based mode — use a preset workflow with specialized personas
 ralph init --preset tdd-red-green
 
 # Combine preset with different backend
@@ -144,7 +165,7 @@ ralph init --preset spec-driven --backend kiro
 ralph init --list-presets
 ```
 
-This creates `ralph.yml` in your current directory.
+This creates `ralph.yml` in your current directory. Without a preset, you get traditional mode (no hats). With a preset, you get hat-based orchestration.
 
 ### 2. Define Your Task
 
@@ -188,22 +209,73 @@ ralph resume
 ralph run --dry-run
 ```
 
+### Alternative: SOP-Driven Sessions
+
+For standalone planning and task generation (without Ralph's event loop), use these commands:
+
+```bash
+# Start an interactive PDD planning session
+ralph plan                           # SOP prompts for input
+ralph plan "build a REST API"        # Provide idea inline
+ralph plan --backend kiro "my idea"  # Use specific backend
+
+# Generate code task files from descriptions
+ralph task                           # SOP prompts for input
+ralph task "add authentication"      # From description
+ralph task specs/feature/plan.md     # From PDD plan file
+```
+
+These commands spawn an interactive AI session with bundled SOPs — perfect for one-off planning without configuring a full workflow.
+
 ## Configuration
 
 Ralph uses a YAML configuration file (`ralph.yml` by default).
 
-### Minimal Configuration
+### Traditional Mode (No Hats)
+
+The simplest configuration — just a loop that runs until completion:
+
+```yaml
+# ralph.yml — Traditional mode
+cli:
+  backend: "claude"
+
+event_loop:
+  completion_promise: "LOOP_COMPLETE"
+  max_iterations: 100
+```
+
+This runs Ralph in a loop. No hats, no events, no role switching. Ralph iterates until it outputs `LOOP_COMPLETE` or hits the iteration limit.
+
+### Hat-Based Mode (Specialized Personas)
+
+> Ralph can wear many hats.
+
+Add a `hats` section to enable role-based orchestration. Hats subscribe to events (triggers) and publish events when done:
 
 ```yaml
-# ralph.yml
+# ralph.yml — Hat-based mode (example structure)
 cli:
   backend: "claude"
 
 event_loop:
   completion_promise: "LOOP_COMPLETE"
   max_iterations: 100
+  starting_event: "task.start"
+
+hats:
+  my_hat:
+    name: "🎯 My Hat"
+    triggers: ["task.start"]        # Events that activate this hat
+    publishes: ["work.done"]        # Events this hat can emit
+    instructions: |
+      Your instructions here...
 ```
 
+With hats, Ralph publishes a starting event, which triggers the matching hat. That hat does its work and publishes an event, potentially triggering other hats. This event-driven handoff continues until completion.
+
+> **Tip:** Use `ralph init --preset <name>` to get pre-configured hat workflows. See [Presets](#presets) for ready-made patterns like TDD, spec-driven development, and more.
+
 ### Full Configuration Reference
 
 ```yaml
@@ -217,7 +289,7 @@ event_loop:
 
 # CLI backend settings
 cli:
-  backend: "claude"                     # claude, kiro, gemini, codex, amp, custom
+  backend: "claude"                     # claude, kiro, gemini, codex, amp, copilot, opencode, custom
   prompt_mode: "arg"                    # arg (CLI argument) or stdin
   experimental_tui: false               # Enable TUI mode support
 
@@ -311,7 +383,7 @@ ralph init --preset debug --force
 
 ### Hats
 
-Hats are specialized agent personas. Each hat has:
+Hats are specialized Ralph personas. Each hat has:
 
 - **Triggers**: Events that activate this hat
 - **Publishes**: Events this hat can emit
@@ -348,6 +420,8 @@ tests: pass, lint: pass, typecheck: pass
 |---------|-------------|
 | `ralph run` | Run the orchestration loop (default) |
 | `ralph resume` | Resume from existing scratchpad |
+| `ralph plan` | Start an interactive PDD planning session |
+| `ralph task` | Start an interactive code-task-generator session |
 | `ralph events` | View event history |
 | `ralph init` | Initialize configuration file |
 | `ralph clean` | Clean up `.agent/` directory |
@@ -380,11 +454,25 @@ tests: pass, lint: pass, typecheck: pass
 
 | Option | Description |
 |--------|-------------|
-| `--backend <NAME>` | Backend: `claude`, `kiro`, `gemini`, `codex`, `amp` |
+| `--backend <NAME>` | Backend: `claude`, `kiro`, `gemini`, `codex`, `amp`, `copilot`, `opencode` |
 | `--preset <NAME>` | Use preset configuration |
 | `--list-presets` | List available presets |
 | `--force` | Overwrite existing config |
 
+### `ralph plan` Options
+
+| Option | Description |
+|--------|-------------|
+| `<IDEA>` | Optional rough idea to develop (SOP prompts if not provided) |
+| `-b, --backend <BACKEND>` | Backend to use (overrides config and auto-detection) |
+
+### `ralph task` Options
+
+| Option | Description |
+|--------|-------------|
+| `<INPUT>` | Optional description text or path to PDD plan file |
+| `-b, --backend <BACKEND>` | Backend to use (overrides config and auto-detection) |
+
 ## Architecture
 
 Ralph is organized as a Cargo workspace with six crates:

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@ralph-orchestrator/ralph-cli",
-      "version": "2.0.7"
+      "version": "2.0.9"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -515,5 +515,5 @@
     }
   },
   "requires": true,
-  "version": "2.0.7"
+  "version": "2.0.9"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.0.7",
+  "artifactDownloadUrl": "https://github.com/mikeyobrien/ralph-orchestrator/releases/download/v2.0.9",
   "bin": {
     "ralph": "run-ralph.js"
   },
@@ -62,7 +62,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.0.7",
+  "version": "2.0.9",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"