ralph-borg

ralph-borg

Spec-driven development with parallel agent orchestration for Claude Code.

"Resistance is futile. Your specs will be assimilated."

Vision

Anyone with Claude Code + an empty repo + a SPEC.md can go from idea to implemented features using parallel agent orchestration.

Prerequisites

Required:

• Git repository - Your project must be a git repo (git init)
• Claude Code CLI - Installed and working
• Bash 4.0+ and Git 2.0+
• gh CLI (optional) - For creating pull requests

If you don't have a git repo yet:

mkdir my-project && cd my-project
git init

Installation

Option 1: Via Claude Code Marketplace (Recommended)

# Add the marketplace
/plugin marketplace add kiitsun-e/ralph-borg

# Install the plugin
/plugin install ralph-borg

Scripts are automatically available within Claude Code sessions. To run borg commands directly in your terminal, run /ralph-borg:borg-setup and follow the instructions.

Updating

To get the latest version:

/plugin marketplace update ralph-borg
/plugin update ralph-borg

Option 2: Manual Installation

Clone the repository:

git clone https://github.com/kiitsun-e/ralph-borg ~/.claude/plugins/ralph-borg

Use the plugin with Claude Code:

claude --plugin-dir ~/.claude/plugins/ralph-borg

Scripts are automatically added to PATH within Claude Code sessions. For terminal usage, run /ralph-borg:borg-setup.

Option 3: Development Mode

For local development, use the --plugin-dir flag:

claude --plugin-dir /path/to/ralph-borg

Quick Start

# 1. Initialize your project for spec-driven development
/ralph-borg:init my-project

# 2. Edit specs/SPEC.md to describe your product vision
# (manually edit the file)

# 3. Create a detailed feature spec via interview
/ralph-borg:feature user-auth

# 4. Implement the feature with parallel agents
/ralph-borg:implement user-auth

# 5. Check progress
/ralph-borg:status

# 6. Review and merge changes
borg diff user-auth
borg merge user-auth --pr

User Workflows

Workflow A: Full Scaffolding (New Projects)

For users starting from scratch:

# Create and initialize project
mkdir my-app && cd my-app && git init

# Full scaffolding
/ralph-borg:init my-app        # Creates specs/, SPEC.md, CLAUDE.md
# Edit specs/SPEC.md with your vision
/ralph-borg:feature auth       # Interview -> specs/auth.md
/ralph-borg:implement auth     # Build with parallel agents

Workflow B: Bring Your Own Spec (Proactive Planners)

For users who prefer to create their own specifications:

# You already have a git repo with your own specs/SPEC.md
# Just initialize borg for parallel agent orchestration
borg init .

# Extract features from YOUR spec via interview
/ralph-borg:feature user-auth

# Implement
/ralph-borg:implement user-auth

What goes in your SPEC.md:

• Product vision and goals
• Feature descriptions
• Technical stack preferences
• Constraints and non-goals

Workflow C: Implementation Only

For users with existing specs who just want orchestration:

# You have specs/feature.implementation.md already
borg init .
borg-ralph loop my-feature specs/my-feature.implementation.md

Entry Points Summary

You have...	Start with...
Empty repo	/ralph-borg:init
Your own SPEC.md	borg init . then /ralph-borg:feature
Feature specs (.md)	/ralph-borg:implement
Implementation plans (.implementation.md)	borg-ralph loop directly

Commands

/ralph-borg:init

Initialize a spec-ready project structure.

/ralph-borg:init [project-name]

Creates:

• specs/SPEC.md - Product vision and requirements (source of truth)
• specs/README.md - Index and workflow guide
• CLAUDE.md - Project instructions

/ralph-borg:feature

Create a feature specification through interactive interview.

/ralph-borg:feature <feature-name>

Produces:

• specs/<feature-name>.md - What to build
• specs/<feature-name>.implementation.md - How to build it (phases)

/ralph-borg:implement

Run the borg-ralph loop to implement a feature.

/ralph-borg:implement <feature-name>

This spawns isolated agents (one per phase) that work in parallel branches.

/ralph-borg:status

Show progress of all feature implementations.

/ralph-borg:status
/ralph-borg:status <feature-name>  # Detailed view

/ralph-borg:borg-setup

Display instructions for adding borg scripts to your terminal PATH.

/ralph-borg:borg-setup

Use this if you want to run borg or borg-ralph commands directly in your terminal (outside of Claude Code).

How It Works