openralph 2.0.0 → 2.1.0

package/README.md

@@ -97,6 +97,16 @@ The agent never pushes—only commits—so you maintain review control.
 - [ghuntley.com/ralph](https://ghuntley.com/ralph/)
 - [lukeparker.dev/stop-chatting-with-ai-start-loops-ralph-driven-development](https://lukeparker.dev/stop-chatting-with-ai-start-loops-ralph-driven-development)
 
+### For LLM Agents
+
+When tasked by a user to set up or run Ralph:
+1. Run `ralph init` to create required files (`prd.json`, `.ralph-prompt.md`, `AGENTS.md`)
+2. Populate `prd.json` with tasks from the user's plan or requirements
+3. Add project-specific notes to `AGENTS.md` (build commands, pitfalls, conventions)
+4. Run `ralph` — the loop handles the rest
+
+Do NOT manually edit `.ralph-state.json` or `.ralph-lock`. Never `git push` — only commit.
+
 ---
 
 ## Usage
@@ -107,6 +117,7 @@ ralph --plan BACKLOG.json          # different PRD file
 ralph --progress progress.txt      # custom progress log
 ralph --model anthropic/claude-opus-4  # different model
 ralph --reset                      # remove generated files and state, then exit
+ralph --verbose                    # enable debug logging to file
 ralph init --from plan.md          # convert unstructured plan to PRD JSON
 ```
 
@@ -132,7 +143,8 @@ ralph init --from plan.md          # convert unstructured plan to PRD JSON
 | `--debug, -d` | `false` | Manual session creation |
 | `--yes` | `false` | Auto-confirm prompts |
 | `--auto-reset` | `true` | Auto-reset when no TTY prompt |
-| `--force` | `false` | Force acquire session lock |
+| `--force, -f` | `false` | Force acquire session lock |
+| `--verbose, -V` | `false` | Enable verbose debug logging to file |
 | `--fallback-agent` | (none) | Fallback agent mapping (format: `primary:fallback`) |
 
 ### Init Subcommand
@@ -218,6 +230,7 @@ CLI arguments override config file values.
 | `RALPH_PLAN` | Override plan file path |
 | `RALPH_PROGRESS` | Override progress log path |
 | `RALPH_SERVER` | Override OpenCode server URL |
+| `RALPH_LOG_DIR` | Override debug log directory |
 
 ### Safety & Reliability
 
@@ -237,48 +250,31 @@ CLI arguments override config file values.
 
 ## Writing PRDs
 
-Prefer PRD JSON with `passes` flags so Ralph can track scope and progress. Two formats are supported:
+PRD JSON uses `passes` flags so Ralph can track scope and progress. Two formats supported:
 
-**Plain array (user-created):**
-```json
-[
-  {
-    "category": "functional",
-    "description": "Create the CLI entry point",
-    "steps": [
-      "Run the CLI with --help",
-      "Verify the help output renders"
-    ],
-    "passes": false
-  }
-]
-```
+**Plain array** (user-created) or **wrapped format** (generated by `ralph init` with metadata).
 
-**Wrapped format (generated by `ralph init`):**
-```json
-{
-  "metadata": {
-    "generated": true,
-    "generator": "ralph-init",
-    "createdAt": "2025-01-13T00:00:00.000Z",
-    "sourceFile": "plan.md"
-  },
-  "items": [
-    {
-      "category": "functional",
-      "description": "Create the CLI entry point",
-      "passes": false
-    }
-  ]
-}
-```
+### Task Item Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | ✅ | Task description |
+| `passes` | ✅ | Whether complete |
+| `id` | ❌ | Custom ID (e.g., `"1.1.1"`) |
+| `category` | ❌ | Category (e.g., `functional`, `setup`) |
+| `steps` | ❌ | Verification steps |
+| `status` | ❌ | `pending` / `actionable` / `active` / `done` / `blocked` / `error` |
+| `effort` | ❌ | `XS` / `S` / `M` / `L` / `XL` |
+| `risk` | ❌ | `L` / `M` / `H` |
+
+**See [`prd.example.json`](prd.example.json) for a complete example with all fields.**
+
+### Tips
 
-**Tips:**
 - Small, isolated tasks — one commit each
 - Explicit verification steps
-- Set `passes` to true only when verified
-- 1000+ lines is normal; more detail = fewer hallucinations
-- Legacy markdown checkboxes work too, but `ralph init --from plan.md` is the upgrade path
+- Use `effort` and `risk` for prioritization (high-risk first)
+- Legacy markdown checkboxes work, but `ralph init --from plan.md` is the upgrade path
 
 ---
 
@@ -295,6 +291,7 @@ Prefer PRD JSON with `passes` flags so Ralph can track scope and progress. Two f
 | `.ralph-pause` | Created by `p` key to pause loop |
 | `.opencode/plugin/ralph-write-guardrail.ts` | Protects files from AI modification |
 | `AGENTS.md` | Project configuration for AI agents |
+| `~/.local/state/ralph/logs/*.log` | Debug and memory logs (when `--verbose` is enabled) |
 
 Add to `.gitignore`:
 ```

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "openralph",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Ralph Driven Development using OpenCode SDK and OpenTUI",
   "bin": {
     "ralph": "./bin/ralph"
   },
   "optionalDependencies": {
-    "openralph-darwin-arm64": "2.0.0",
-    "openralph-darwin-x64": "2.0.0",
-    "openralph-linux-arm64": "2.0.0",
-    "openralph-linux-x64": "2.0.0",
-    "openralph-windows-x64": "2.0.0"
+    "openralph-darwin-arm64": "2.1.0",
+    "openralph-darwin-x64": "2.1.0",
+    "openralph-linux-arm64": "2.1.0",
+    "openralph-linux-x64": "2.1.0",
+    "openralph-windows-x64": "2.1.0"
   },
   "repository": {
     "type": "git",