Ralph

Ralph Wiggum - Autonomous Agent Loop

A workflow pattern for extended autonomous work sessions where the agent iterates through tasks until completion.

When to Use

• PRD-driven development: Work through a product requirements document task by task
• Migration tasks: "Migrate all Jest tests to Vitest" - agent works until done
• Batch operations: Process multiple files/components with the same pattern
• Away-from-keyboard work: Let the agent work autonomously while you're away

When NOT to Use

• Simple single-step tasks (just do them directly)
• Tasks requiring frequent human decisions
• Exploratory work where the goal isn't clear
• Critical production changes (requires human oversight)

Quick Start

Invoke the workflow with:

/ralph Migrate all Jest tests to Vitest --prd PRD.md

Or manually follow the loop pattern below.

The Loop Pattern

┌─────────────────────────────────────────────────┐
│  1. Read PRD/task list + progress.txt           │
│  2. Pick highest-priority incomplete task       │
│  3. Implement ONE feature only                  │
│  4. Run feedback: test → typecheck → lint       │
│  5. If pass → commit + update progress.txt      │
│  6. If all done → output <promise>COMPLETE      │
│  7. Otherwise → repeat from step 1              │
└─────────────────────────────────────────────────┘

Using LSP Tools (Experimental)

OpenCode provides LSP tools for code intelligence.

Available Operations

// Understand file structure before editing
lsp({
  operation: "documentSymbol",
  filePath: "src/auth.ts",
  line: 1,
  character: 1,
});

// Find where a symbol is defined
lsp({
  operation: "goToDefinition",
  filePath: "src/auth.ts",
  line: 42,
  character: 10,
});

// Find all usages of a symbol (impact analysis)
lsp({
  operation: "findReferences",
  filePath: "src/auth.ts",
  line: 42,
  character: 10,
});

// Get type info and documentation
lsp({ operation: "hover", filePath: "src/auth.ts", line: 42, character: 10 });

// Find implementations of interface/abstract
lsp({
  operation: "goToImplementation",
  filePath: "src/types.ts",
  line: 15,
  character: 10,
});

// Search symbols across entire workspace
lsp({
  operation: "workspaceSymbol",
  filePath: "src/index.ts",
  line: 1,
  character: 1,
});

// Call hierarchy analysis
lsp({
  operation: "prepareCallHierarchy",
  filePath: "src/api.ts",
  line: 20,
  character: 5,
});
lsp({
  operation: "incomingCalls",
  filePath: "src/api.ts",
  line: 20,
  character: 5,
});
lsp({
  operation: "outgoingCalls",
  filePath: "src/api.ts",
  line: 20,
  character: 5,
});

LSP-First Workflow

Before editing ANY file in the loop:

1. Read the file
2. Use documentSymbol to understand structure
3. Use findReferences to check impact
4. Use hover for type info
5. THEN make edits

This prevents breaking changes and ensures you understand the code before modifying it.

Smart Language Detection

OpenCode auto-detects languages via LSP based on file extensions. Use this to determine the project type:

Primary Detection (File Extensions)

Secondary Detection (Lock Files → Package Manager)

Validation Commands by Language

# TypeScript/JavaScript (Bun)
bun test && bun run typecheck && bun run lint

# TypeScript/JavaScript (npm)
npm test && npm run typecheck && npm run lint

# TypeScript/JavaScript (Deno)
deno test && deno check . && deno lint

# Python
pytest && ruff check . && mypy .

# Rust
cargo test && cargo check && cargo clippy --all-targets

# Go
go test ./... && go vet ./... && golangci-lint run

# Ruby
bundle exec rspec && bundle exec rubocop

# PHP
composer test && composer phpstan && composer phpcs

# Swift
swift test && swift build

# Elixir
mix test && mix credo && mix dialyzer

# Dart
dart test && dart analyze

# Java (Maven)
mvn test && mvn compile && mvn checkstyle:check

# Java (Gradle)
./gradlew test && ./gradlew check

# C# (.NET)
dotnet test && dotnet build && dotnet format --verify-no-changes

Required Files

PRD File (Recommended)

Create a PRD.md with clear task list:

# Migration PRD

## Tasks

- [ ] Convert test-utils.test.js
- [ ] Convert api.test.js
- [ ] Update CI config
- [ ] Remove Jest dependencies

Progress File (Agent-maintained)

Agent creates/updates progress.txt:

# Progress Log

## Session Started: 2026-01-10

### Project: TypeScript with Bun

### Commands: bun test | bun run typecheck | bun run lint

### Completed Tasks

- [x] test-utils.test.js - migrated, 12 tests passing
- [x] api.test.js - migrated, 8 tests passing

### Notes for Next Iteration

- CI config needs Vitest runner update

Completion Signal

The loop ends when agent outputs:

<promise>COMPLETE</promise>

Best Practices

1. Use LSP for detection: Check file extensions, not just lock files
2. Small steps: ONE feature per iteration (prevents context rot)
3. Quality gates: Test, typecheck, lint MUST pass before commit
4. Prioritize risk: Hard tasks first, easy wins last
5. Track progress: Update progress.txt every iteration
6. Explicit scope: Vague tasks loop forever
7. Graceful fallbacks: If a command doesn't exist, skip and note it

Troubleshooting