ralphy-openspec — Summary

ralphy-openspec (published as ralphy-spec) is an npm CLI tool and multi-tool command pack that combines OpenSpec spec-first planning with the Ralph Loop iterative execution pattern, providing a SQLite-backed run ledger, budget tracking, and slash commands for four AI tools (Cursor, Claude Code, OpenCode, and a standalone Ralph loop runner).

Problem it solves: OpenSpec provides structured specs but lacks persistence between AI sessions — when context windows exhaust or sessions disconnect, agents lose progress. The Ralph Loop retries a prompt until completion but has no spec governance. ralphy-spec wires them together: specs lock intent before execution, the loop retries until tests pass (outputting <promise>TASK_COMPLETE</promise>), and a SQLite database tracks run history, budget, and checkpoints across sessions.

Distinctive trait: The only framework in this batch with a real-time SQLite state database (ralphy-spec/state.db) that persists run state, task ledger, budget tracking, and backend transcripts across sessions and CLI invocations. Combined with the Ralph Loop's iterative execution model (continuous agent loop until task completion), this provides crash recovery and resume capability that no other framework in the batch offers.

Target audience: Developers who run long AI coding sessions that frequently time out or get interrupted, needing reliable resume-from-checkpoint behavior, and who want OpenSpec's spec discipline on top of the iterative execution model.

Production-readiness: v0.3.6, 186 stars (highest in the batch), 20 forks. Last commit January 2026. Multi-language README (English, Chinese, Korean, Japanese). Published as ralphy-spec on npm.

Relationship to seeds: Most similar to taskmaster-ai (file + database-backed task ledger, runs via CLI, spans multiple AI tools) but adds the Ralph Loop continuous execution model and OpenSpec spec governance. Like claude-flow (which uses SQLite + vector DB for memory), ralphy-spec uses SQLite for run state — but focuses on spec-driven task execution rather than distributed agent memory. Unlike openspec (the canonical seed), ralphy-spec has 4 slash commands instead of 11, and adds the critical run/loop execution layer that OpenSpec lacks.

ralphy-openspec — Overview

Origin

Created by wenqingyu. The package name is ralphy-spec (with a website at ralphy-spec.org). Published with four language READMEs (English, Chinese, Korean, Japanese). The repository name is ralphy-openspec on GitHub.

Credits

From the README:

"Built on the work of:

• Ralph Methodology by Geoffrey Huntley
• opencode-ralph-wiggum by @Th0rgal
• OpenSpec by Fission-AI"

Philosophy

The README articulates the combination:

"Spec-driven AI development with iterative execution. Combines OpenSpec + Ralph Loop for predictable AI-assisted coding."

The core problem table:

Ralph Loop concept

The Ralph Wiggum Loop: AI receives the same prompt repeatedly until task completion. Each iteration, it sees previous work in files and self-corrects. The <promise>TASK_COMPLETE</promise> output is the completion signal:

ralph "Follow AGENTS.md to implement add-api. Output <promise>TASK_COMPLETE</promise> when done." \
  --max-iterations 20

Multi-tool support

Unique in supporting all four major AI tools with both slash commands and an AGENTS.md fallback:

ralphy-openspec — Architecture

Distribution

• Type: npm package + command pack (multi-tool)
• Package name: ralphy-spec
• Version: 0.3.6
• Binary: ralphy-spec
• Language: TypeScript (Node.js)

Install

# Recommended
npx ralphy-spec init

# Global install
npm install -g ralphy-spec
ralphy-spec init

# With specific tools
ralphy-spec init --tools cursor,claude-code,opencode

Required runtime

• Node.js (implied by npm package)
• SQLite (via better-sqlite3 dependency)

Key dependencies

Repository structure

ralphy-openspec/
├── .claude/
│   └── commands/          ← 4 Claude Code slash commands
│       ├── ralphy-plan.md
│       ├── ralphy-implement.md
│       ├── ralphy-validate.md
│       └── ralphy-archive.md
├── .cursor/
│   └── prompts/           ← Same 4 commands for Cursor
├── .ralphy/               ← Legacy (migrated to ralphy-spec/)
├── AGENTS.md              ← OpenCode/natural language equivalent
├── bin/
│   └── ralphy-spec.js     ← Binary entry point
├── src/
│   ├── cli/               ← 9 CLI subcommands
│   │   ├── init.ts
│   │   ├── run.ts
│   │   ├── status.ts
│   │   ├── budget.ts
│   │   ├── checkpoint.ts
│   │   ├── report.ts
│   │   ├── tail.ts
│   │   ├── update.ts
│   │   └── validate.ts
│   ├── core/              ← Run engine, OpenSpec integration
│   ├── templates/         ← Prompt templates
│   └── utils/
├── openspec/              ← OpenSpec directory
├── ralphy-spec/           ← Runtime state directory
│   ├── state.db           ← SQLite run/task ledger
│   ├── STATUS.md          ← Live status snapshot
│   ├── TASKS.md           ← Task board view
│   ├── BUDGET.md          ← Budget breakdown
│   ├── runs/<runId>.md    ← Immutable run logs
│   ├── logs/<runId>/      ← Backend transcripts
│   ├── worktrees/         ← Git worktrees per task (when enabled)
│   └── tasks/<taskId>/   ← Per-task artifacts
│       ├── CONTEXT.md
│       ├── REPAIR.md
│       └── NOTES.md
└── package.json

Target AI tools

• Claude Code (.claude/commands/)
• Cursor (.cursor/prompts/)
• OpenCode (AGENTS.md)
• Ralph loop (@th0rgal/ralph-wiggum + AGENTS.md)

Backend authentication (for ralphy-spec run)

cursor agent login  # or CURSOR_API_KEY env var
ralphy-spec run --backend cursor

ralphy-openspec — Components

CLI binary: ralphy-spec

Subcommands (9):

Commands (4 per AI tool = 8 total files)

Commands are identical in intent, installed as:

• .claude/commands/ralphy-{plan,implement,validate,archive}.md (Claude Code)
• .cursor/prompts/ralphy-{plan,implement,validate,archive}.md (Cursor)
• AGENTS.md equivalent entries (OpenCode)

Skills

Count: 0 — Commands are Markdown files, not SKILL.md format.

Subagents

Count: 0

Hooks

Count: 0

MCP Servers

Count: 0

State files (runtime)

OpenSpec files (workflow)

ralphy-openspec — Uniqueness and Positioning

differs_from_seeds

Most similar to taskmaster-ai (file-based task ledger + multiple AI tools + CLI), but adds the Ralph Loop continuous execution model and SQLite state persistence. Like claude-flow (which uses SQLite + vector store), ralphy-spec uses SQLite for state — but focuses on sequential spec-driven task execution rather than distributed agent memory. Unlike the canonical openspec seed (which has 11 commands/skills but no loop engine), ralphy-spec has only 4 commands but adds the critical run/loop execution layer with crash recovery. The <promise>TASK_COMPLETE</promise> protocol is borrowed from opencode-ralph-wiggum — the only framework in the batch using this machine-parseable completion signal.

Positioning

• Niche: "OpenSpec + Ralph Loop for sessions that need crash recovery and budget tracking"
• Primary differentiator: Only framework in the batch with SQLite state database + continuous Ralph Loop execution
• Secondary differentiator: Budget tracking (ralphy-spec budget --json) — unique in the corpus
• Third differentiator: Multi-tool coverage (Cursor, Claude Code, OpenCode, standalone ralph) from one init command

Observable failure modes

1. Max iterations exhaustion: If the AI never outputs <promise>TASK_COMPLETE</promise> within --max-iterations, the run terminates without completion. No notification mechanism for this case.
2. Backend authentication fragility: cursor agent login is an undocumented Cursor API path that could break with Cursor updates.
3. SQLite state corruption: Crash during state.db write could corrupt the ledger. No explicit write-ahead logging or backup described.
4. No spec validation in plan: The /ralphy-plan command creates OpenSpec artifacts but does not call openspec validate to check schema compliance.
5. AGENTS.md as fallback: The OpenCode path relies on AGENTS.md being read by the agent — if the agent ignores AGENTS.md, there's no enforcement.

Explicit antipatterns

From /ralphy-implement:

• Declaring success without running tests
• Marking tasks complete before verification passes
• Starting implementation without reading all three context files (proposal.md, tasks.md, specs/)