opencode-ralph-loop-cli 0.1.0

# opencode-ralph-loop-cli — Full Documentation Context

> This file aggregates documentation for LLM context windows.
> Generated from: README.md, docs/HOW_TO_USE.md, docs/COOKBOOK.md, INTEGRATIONS.md (AI Agent section)

---

# === SECTION: README.md ===

# opencode-ralph-loop-cli

> "One command scaffolds the complete OpenCode Ralph Loop plugin setup."

## What is it?
- Generates the complete `.opencode/` structure in a single deterministic command
- Embeds six canonical template files as static bytes — zero network calls at runtime
- Verifies idempotency via SHA-256: unchanged files are never overwritten
- Supports JSON and NDJSON output for agent-driven pipelines
- Tracks installed files via `.manifest.json` for clean removal via `uninstall`
- Diagnoses environment dependencies via the `doctor` subcommand

## Why?
- Go from zero to a working Ralph Loop in under 10 seconds on any platform
- Deterministic output guarantees identical bytes on every run and every machine
- Machine-readable JSON contract parses cleanly with `jq` without extra configuration
- Conflict detection prevents accidental data loss before `--force` is required

## Superpowers for AI Agents

| Agent | Integration Type | Min Version |
|-------|-----------------|-------------|
| Claude Code | Native CLI subprocess | latest |
| Codex (OpenAI) | Shell tool call | latest |
| Gemini CLI | Shell tool call | latest |
| Opencode | Native plugin host | latest |
| Cursor | Terminal tool | latest |
| Windsurf | Terminal tool | latest |
| VS Code Copilot | Task runner | latest |
| GitHub Copilot | Shell tool call | latest |
| Google Antigravity | Shell tool call | latest |
| Zed AI | Terminal tool | latest |
| Aider | Shell command | latest |
| Jules | Shell tool call | latest |
| Kilo Code | Shell tool call | latest |
| Roo Code | Shell tool call | latest |
| Cline | Shell tool call | latest |
| Continue | Shell tool call | latest |
| Factory AI | Shell tool call | latest |
| Augment Code | Shell tool call | latest |
| Minimax AI | Shell tool call | latest |
| Z.ai | Shell tool call | latest |
| JetBrains AI Assistant | Terminal tool | latest |

- Deterministic stdout enables agents to parse output reliably without heuristics
- Typed exit codes allow agents to branch on conflict, drift, or I/O errors precisely
- JSON contract (`--output json`) provides a stable schema consumable by any agent
- Zero runtime dependencies eliminate environment setup friction for agent workflows
- Idempotency guarantees safe re-execution inside loops and retry pipelines
- Single cross-platform binary removes interpreter or runtime requirements

## Quick Start

```bash
cargo install opencode-ralph-loop-cli
opencode-ralph-loop-cli init
cd .opencode && bun install
```

## Commands

### init
- `--path <DIR>` target directory, default is current working directory
- `--force` overwrite files that differ from the embedded templates
- `--dry-run` simulate without writing anything to disk
- `--plugin-version <VER>` override the embedded `@opencode-ai/plugin` version
- `--no-package-json` skip `package.json` generation
- `--no-gitignore` skip `.gitignore` generation
- `--no-manifest` skip `.manifest.json` generation
- `--output <FORMAT>` output format: `text`, `json`, `ndjson`, `quiet`

### check
- `--path <DIR>` directory to audit against embedded templates
- `--strict` fail at the first drift detected (exit code 5)
- `--exit-zero` force exit code 0 regardless of drift found
- `--output <FORMAT>` output format: `text`, `json`, `ndjson`, `quiet`

### uninstall
- `--path <DIR>` target directory to remove scaffold from
- `--dry-run` simulate removal without deleting any files
- `--force` proceed even if `.manifest.json` is missing
- `--keep-state` preserve `ralph-loop.local.md` during removal

### list
- Lists all six embedded templates with SHA-256 hash and byte count

### doctor
- Checks `bun`, `node`, and `opencode` presence in PATH
- Reports manifest validity and per-file integrity against embedded hashes

### completions
- `completions <shell>` generates completion script for bash, zsh, fish, powershell, or elvish

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `OPENCODE_RALPH_LOOP_CLI_OUTPUT` | Default output format | `text` |
| `OPENCODE_RALPH_LOOP_CLI_FORCE` | Enable force mode | unset |
| `OPENCODE_RALPH_LOOP_CLI_PLUGIN_VERSION` | Override plugin version | `1.4.7` |
| `OPENCODE_RALPH_LOOP_CLI_CONFIG` | Path to alternative config file | XDG default |
| `NO_COLOR` | Disable ANSI colors (community standard) | unset |
| `RUST_LOG` | Tracing log filter for verbose diagnostics | unset |

## Exit Codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Generic runtime error |
| `2` | Invalid CLI argument or usage |
| `3` | File conflict without `--force` |
| `4` | I/O error or permission denied |
| `5` | Drift detected in `--strict` mode |
| `6` | Manifest missing or corrupted |
| `7` | Config file parse error |
| `130` | Interrupted by SIGINT |

## Integration Patterns
- Inspect only drifted files: `opencode-ralph-loop-cli check --output json | jq '.files[] | select(.action != "skipped")'`
- Fail CI on any drift: `opencode-ralph-loop-cli check --strict --output quiet`
- Automate in GitHub Actions: add `opencode-ralph-loop-cli check --strict` as a workflow step after checkout
- Use in Makefile: `init: opencode-ralph-loop-cli init --dry-run && opencode-ralph-loop-cli init`
- Force reinit in reset scripts: `opencode-ralph-loop-cli uninstall --force && opencode-ralph-loop-cli init --force`
- Stream NDJSON events to a log aggregator: `opencode-ralph-loop-cli init --output ndjson | tee init.log`

## Troubleshooting

### Conflict without --force (exit 3)
- A file in `.opencode/` was modified since the last `init`
- Run `opencode-ralph-loop-cli check` to inspect which files differ
- Use `--force` to overwrite with the canonical template content

### Manifest missing or corrupted (exit 6)
- `.opencode/.manifest.json` is absent or contains invalid JSON
- Run `opencode-ralph-loop-cli init` to regenerate the manifest
- Use `opencode-ralph-loop-cli uninstall --force` to skip the manifest check

### I/O error or permission denied (exit 4)
- The target directory does not exist or lacks write permission
- Create the directory first, then retry
- Verify with `opencode-ralph-loop-cli init --path <DIR> --dry-run`

### doctor reports bun not found
- Install Bun from `bun.sh` and confirm it is in your PATH
- Alternatively use `node` and `npm install` inside `.opencode/`

### JSON output contains unexpected text
- Use `--output json` explicitly and validate with `jq '.'`
- Confirm `--verbose` is NOT set — verbose output goes to stderr only

---

# === SECTION: docs/HOW_TO_USE.md ===

# How to Use opencode-ralph-loop-cli

> Follow this guide to have a working OpenCode Ralph Loop setup in under 60 seconds.

## Prerequisites
### Requirements — What You Need Before Starting
- Rust 1.85 or later installed via rustup
- `bun` or `node` available in your PATH for the plugin runtime
- `opencode` binary available (optional for scaffolding, required for running)

## Core Commands
### init — Generate .opencode/ Structure
- Generates six canonical templates in `.opencode/` in one command
- Use `--dry-run` to preview all actions before writing any files
- Use `--force` to overwrite files that differ from the embedded templates
- Use `--output json` to get structured output for automated pipelines
- Use `--plugin-version <VER>` to pin a specific `@opencode-ai/plugin` version

```bash
opencode-ralph-loop-cli init --path /my/project
opencode-ralph-loop-cli init --dry-run
opencode-ralph-loop-cli init --force --output json
```

### check — Detect Configuration Drift
- Compares installed files against embedded templates using SHA-256
- Exit code 0 means all files match the canonical templates
- Exit code 5 means drift detected when using `--strict` mode
- Use `--output json` to get per-file drift details for pipeline automation

```bash
opencode-ralph-loop-cli check
opencode-ralph-loop-cli check --strict
opencode-ralph-loop-cli check --output json --exit-zero | jq '.files[] | select(.action == "modified")'
```

### list — Show Embedded Templates
- Lists all six embedded templates with their SHA-256 hashes and byte sizes
- Useful to verify which version of each template is bundled in the installed binary

```bash
opencode-ralph-loop-cli list
```

### doctor — Diagnose Environment
- Checks `bun`, `node`, and `opencode` presence in PATH
- Reports manifest validity and per-file integrity
- Use `--output json` for structured output in CI health checks

```bash
opencode-ralph-loop-cli doctor
opencode-ralph-loop-cli doctor --output json
```

### uninstall — Remove Scaffold Cleanly
- Removes only manifest-tracked files, preserving untracked files
- Use `--dry-run` to preview which files would be removed
- Use `--keep-state` to preserve `ralph-loop.local.md` during removal

```bash
opencode-ralph-loop-cli uninstall --dry-run
opencode-ralph-loop-cli uninstall --keep-state
```

### completions — Shell Autocompletion
- Generates completion scripts for bash, zsh, fish, powershell, elvish
- Source the script in your shell profile for permanent autocompletion

```bash
opencode-ralph-loop-cli completions bash >> ~/.bashrc
opencode-ralph-loop-cli completions zsh >> ~/.zshrc
```

## Advanced Patterns
### Pattern 1 — Safe Init Workflow with Dry Run
```bash
opencode-ralph-loop-cli init --dry-run
opencode-ralph-loop-cli init
```

### Pattern 2 — Continuous Integration Drift Detection with JSON
```bash
opencode-ralph-loop-cli check --output json --exit-zero \
  | jq '.files[] | select(.action != "skipped")'
```

### Pattern 3 — Force Overwrite of Modified Templates
```bash
opencode-ralph-loop-cli init --force --output json | jq '.summary'
```

### Pattern 4 — Strict Mode for CI Fail-Fast
```bash
opencode-ralph-loop-cli check --strict || echo "Drift detected, aborting CI"
```

### Pattern 5 — NDJSON Streaming for Log Ingestion
```bash
opencode-ralph-loop-cli check --output ndjson | tee drift-report.ndjson
```

## Integration with AI Agents
### Agents — Claude Code and Codex Examples
- Claude Code can invoke the CLI via Bash tool subprocess
- Codex and other agents invoke via shell commands in their execution environment
- Use `--output json` for structured output that agents can parse reliably

```bash
# Claude Code example (Bash tool)
opencode-ralph-loop-cli check --output json --exit-zero
# Parse with: | jq '.files[] | select(.action == "modified") | .path'

# CI environment (GitHub Actions)
opencode-ralph-loop-cli check --strict
```

## Common Errors
### Error — Exit Code 3 (Conflict without --force)
- Cause: a file in `.opencode/` was modified since last `init`
- Solution: run `opencode-ralph-loop-cli check` to see which files differ, then use `--force`

### Error — Exit Code 4 (I/O error)
- Cause: target directory does not exist or has no write permission
- Solution: create the target directory first, verify permissions

### Error — Exit Code 5 (Drift in strict mode)
- Cause: `--strict` flag exits at first drifted file
- Solution: run without `--strict` for full report, then decide whether to force

### Error — Exit Code 6 (Manifest missing)
- Cause: `.opencode/.manifest.json` is absent or corrupted
- Solution: run `opencode-ralph-loop-cli init` to regenerate the manifest

---

# === SECTION: docs/COOKBOOK.md ===

# Cookbook — opencode-ralph-loop-cli

> "Practical recipes for every workflow, from CI pipelines to AI agent orchestration."

## Recipe Index
- Recipe 1 — How to scaffold .opencode/ in a new project
- Recipe 2 — How to detect configuration drift in CI
- Recipe 3 — How to force-overwrite modified templates
- Recipe 4 — How to simulate init without writing files
- Recipe 5 — How to use JSON output in shell scripts
- Recipe 6 — How to pipe check output to jq for automation
- Recipe 7 — How to uninstall cleanly while preserving local state
- Recipe 8 — How to run doctor to verify environment readiness
- Recipe 9 — How to generate shell completions for zsh
- Recipe 10 — How to override the plugin version on init
- Recipe 11 — How to use init in Docker without bun
- Recipe 12 — How to check files with strict mode for CI fail-fast
- Recipe 13 — How to list all embedded templates and their hashes
- Recipe 14 — How to use NDJSON output for streaming log ingestion
- Recipe 15 — How to integrate with a Makefile for project automation

### Recipe 1 — How to scaffold .opencode/ in a new project
#### Problem
- Starting a new project requires consistent AI agent configuration
- Manually copying templates leads to drift and inconsistency
#### Solution
```bash
opencode-ralph-loop-cli init
```
#### Explanation
- Detects the current directory as the project root automatically
- Creates `.opencode/` with `plugins/` and `commands/` subdirectories
- Embeds `ralph.ts`, `ralph-loop.md`, `cancel-ralph.md`, and `ralph-help.md`
- Exits with code 0 on success, 4 on I/O failure, 6 on manifest error
#### Variants
- `opencode-ralph-loop-cli init --output json` — emit structured JSON result
- `opencode-ralph-loop-cli init --dry-run` — preview actions without writing files

### Recipe 2 — How to detect configuration drift in CI
#### Problem
- Templates evolve and local copies fall out of sync with upstream
- Silent drift breaks AI agent behavior without obvious error messages
#### Solution
```bash
opencode-ralph-loop-cli check
```
#### Explanation
- Compares each local template against the embedded canonical version
- Reports files that differ, are missing, or have unexpected content
- Exits with code 0 when all files match, non-zero when drift is detected
- Works without network access — all comparisons are against embedded bytes
#### Variants
- `opencode-ralph-loop-cli check --output json` — machine-readable drift report
- `opencode-ralph-loop-cli check --strict` — exit 5 on any drift, ideal for fail-fast

### Recipe 3 — How to force-overwrite modified templates
#### Solution
```bash
opencode-ralph-loop-cli init --force
```
#### Explanation
- Overwrites all existing template files with embedded canonical versions
- Does not delete files that are not managed by the tool
- Use `--dry-run` first to preview what will be overwritten

### Recipe 4 — How to simulate init without writing files
#### Solution
```bash
opencode-ralph-loop-cli init --dry-run
```
#### Explanation
- Performs all validation and planning steps without touching the filesystem
- Exits with the same codes that a real run would produce
- Combine with `--output json` for structured preview output

### Recipe 5 — How to use JSON output in shell scripts
#### Solution
```bash
result=$(opencode-ralph-loop-cli check --output json)
status=$(echo "$result" | jaq -r '.status')
if [ "$status" = "ok" ]; then
  echo "Templates are in sync"
else
  echo "Drift detected"
fi
```
#### Explanation
- Pass `--output json` to any command to receive machine-readable output
- The top-level `.status` field is always `"ok"` or `"error"` for easy branching
- All commands support `--output json` consistently across subcommands

### Recipe 6 — How to pipe check output to jq for automation
#### Solution
```bash
opencode-ralph-loop-cli check --output json \
  | jaq '.files[] | select(.status != "ok") | .path'
```
#### Explanation
- The `.files` array contains one entry per managed template file
- Each entry has `.path`, `.status`, and `.hash` fields
- Filter with `jaq` to select only drifted or missing files

### Recipe 7 — How to uninstall cleanly while preserving local state
#### Solution
```bash
opencode-ralph-loop-cli uninstall
```
#### Explanation
- Removes only the files and directories that were created by `init`
- Preserves any files added manually after the initial scaffold
- Exits with code 0 on success, 4 on I/O failure

### Recipe 8 — How to run doctor to verify environment readiness
#### Solution
```bash
opencode-ralph-loop-cli doctor
```
#### Explanation
- Checks that all required runtime tools are installed and on `PATH`
- Verifies `bun` version meets the minimum required for plugin installation
- Exits with code 0 when all checks pass, 1 when any check fails

### Recipe 9 — How to generate shell completions for zsh
#### Solution
```bash
opencode-ralph-loop-cli completions zsh > ~/.zsh/completions/_opencode-ralph-loop-cli
source ~/.zshrc
```
#### Explanation
- Emits a zsh completion script to stdout for redirection
- Regenerate the file after upgrading to pick up new flags
- Completions cover all subcommands, flags, and output format values

### Recipe 10 — How to override the plugin version on init
#### Solution
```bash
opencode-ralph-loop-cli init --plugin-version 0.1.0
```
#### Explanation
- Replaces the default embedded version string in `package.json`
- Use exact version strings following semantic versioning format
- Exits with code 6 when the version string is malformed

### Recipe 11 — How to use init in Docker without bun
#### Solution
```dockerfile
FROM rust:1.85-alpine AS builder
RUN cargo install opencode-ralph-loop-cli
RUN opencode-ralph-loop-cli init --skip-install
```
#### Explanation
- Pass `--skip-install` to scaffold templates without running `bun install`
- Run `bun install` in a separate stage or at container startup time

### Recipe 12 — How to check files with strict mode for CI fail-fast
#### Solution
```bash
opencode-ralph-loop-cli check --strict
```
#### Explanation
- Exits with code 5 on the first drift detected instead of continuing
- Add to pre-commit hooks or CI gate steps for immediate feedback
- Faster than full check when the goal is simply pass or fail

### Recipe 13 — How to list all embedded templates and their hashes
#### Solution
```bash
opencode-ralph-loop-cli list
```
#### Explanation
- Prints each managed template path with its embedded SHA-256 hash
- No filesystem access required — hashes are computed at compile time

### Recipe 14 — How to use NDJSON output for streaming log ingestion
#### Solution
```bash
opencode-ralph-loop-cli check --output ndjson | vector --config vector.toml
```
#### Explanation
- Each event is emitted as a single JSON object on its own line
- Compatible with Loki, Fluentd, Vector, and any NDJSON-compatible tool
- No buffering occurs — each file result is emitted as it is processed

### Recipe 15 — How to integrate with a Makefile for project automation
#### Solution
```makefile
.PHONY: setup check-drift reset-templates clean-ai

setup:
	opencode-ralph-loop-cli init

check-drift:
	opencode-ralph-loop-cli check --strict

reset-templates:
	opencode-ralph-loop-cli init --force

clean-ai:
	opencode-ralph-loop-cli uninstall
```
#### Explanation
- Define `setup` to scaffold `.opencode/` on first clone
- Define `check-drift` to enforce template integrity in CI pipelines
- Add `check-drift` as a dependency of your `test` or `ci` target

---

# === SECTION: INTEGRATIONS.md ===

# Integrations — opencode-ralph-loop-cli (AI Agent Integrations)

> "From shell scripts to Kubernetes CronJobs — integrations for every workflow."

## AI Agent Integrations

### Claude Code
- Add `opencode-ralph-loop-cli init` to the project setup section of `CLAUDE.md`
- Use `check --strict` as a pre-session gate to verify template integrity
- Exit code 0 confirms the environment is ready for AI-assisted development

```bash
# CLAUDE.md setup step
opencode-ralph-loop-cli doctor && opencode-ralph-loop-cli init
```

### Codex (OpenAI)
- Add `init` to the Codex workspace bootstrap script that runs before sessions
- Use `check --output json` to feed drift status into Codex context

```bash
# Codex bootstrap
opencode-ralph-loop-cli init --skip-install
opencode-ralph-loop-cli check --output json
```

### Gemini CLI
- Add `init` to the `.gemini/` project setup hook that runs on workspace open
- The `--output quiet` flag keeps Gemini CLI context clean of tool output

```bash
# Gemini setup hook
opencode-ralph-loop-cli init --skip-install
opencode-ralph-loop-cli check --strict --output quiet
```

### Opencode
- Place `check --strict` in the Opencode pre-session hook configuration
- Opencode reads exit codes natively — use 0 for pass, non-zero for block

```bash
# Opencode pre-session hook
opencode-ralph-loop-cli check --strict
```

### Cursor
- Add `opencode-ralph-loop-cli init` to the setup instructions in `.cursorrules`
- Use `--output json` so Cursor can parse drift status programmatically

```
# .cursorrules setup block
Run: opencode-ralph-loop-cli init
Verify: opencode-ralph-loop-cli check --strict --output quiet
```

### Windsurf
- Add `init` to the Windsurf workspace onboarding rules file
- Windsurf agent reads exit codes — non-zero blocks session continuation

```bash
# Windsurf onboarding
opencode-ralph-loop-cli doctor && opencode-ralph-loop-cli init
```

### VS Code Copilot
- Add `init` to `.vscode/tasks.json` as a `preLaunchTask` for the workspace

```json
{
  "label": "Setup AI Templates",
  "type": "shell",
  "command": "opencode-ralph-loop-cli init",
  "group": "build",
  "presentation": { "reveal": "always" }
}
```

### GitHub Copilot
- Add `check --strict` to the CI workflow before any Copilot-assisted steps

```yaml
- name: Verify AI Templates
  run: opencode-ralph-loop-cli check --strict
```

### GitHub Actions Full Workflow

```yaml
name: Verify AI Templates

on:
  push:
    branches: [main]
  pull_request:

jobs:
  template-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: 1.85

      - name: Install opencode-ralph-loop-cli
        run: cargo install opencode-ralph-loop-cli

      - name: Verify doctor
        run: opencode-ralph-loop-cli doctor

      - name: Check template drift
        run: opencode-ralph-loop-cli check --strict --output json
```

### Aider
- Add `init` call to the `.aider.conf.yml` startup commands section

```yaml
# .aider.conf.yml
auto-commits: false
message: |
  Run: opencode-ralph-loop-cli init --skip-install
```

### Cline
- Add `init` to the `.clinerules` setup block that runs on workspace open
- Cline reads exit codes to determine whether to proceed with AI tasks

```
# .clinerules setup block
Run: opencode-ralph-loop-cli init --skip-install
Gate: opencode-ralph-loop-cli check --strict --output quiet
```

### Continue
- Add `init` to the Continue context provider setup script
- Continue can use JSON output fields to conditionally include context snippets

```bash
# Continue setup
opencode-ralph-loop-cli init
opencode-ralph-loop-cli list --output json
```

### Docker Multi-Stage Build

```dockerfile
FROM rust:1.85-slim AS tool-builder
RUN cargo install opencode-ralph-loop-cli

FROM node:20-slim AS template-setup
COPY --from=tool-builder /usr/local/cargo/bin/opencode-ralph-loop-cli /usr/local/bin/
WORKDIR /app
COPY . .
RUN opencode-ralph-loop-cli init
RUN cd .opencode && npm install

FROM node:20-slim AS final
WORKDIR /app
COPY --from=template-setup /app .
```