
ralph-borg
Spec-driven development with parallel agent orchestration
- version
- 0.2.6
Install
/plugin install ralph-borg@ralph-borgRun it inside Claude Code after adding the marketplace with /plugin marketplace add kiitsun-e/ralph-borg.
Contents
Discovered from sourceSkills 1
Spec Workflow Skill
A generalized skill for conducting feature specification interviews and generating implementation plans.
Overview
This skill guides the creation of feature specifications through a structured interview process. It produces two artifacts:
- A feature spec (
<feature>.md) describing what to build - An implementation plan (
<feature>.implementation.md) with phased execution steps
Input Context
Before starting, gather context from:
SPEC.md- Product vision and high-level featuresCLAUDE.md- Project-specific instructions and patterns- Project config files (
package.json,Cargo.toml,go.mod, etc.) - Existing code structure and patterns
Interview Process
Phase 1: Problem Definition
Ask the user:
- "What problem does this feature solve?"
- "Who is the primary user of this feature?"
- "What's the current workaround (if any)?"
Phase 2: User Stories
Ask the user:
- "Walk me through the main user workflow"
- "Are there different user types with different needs?"
- "What edge cases should we consider?"
Phase 3: Scope Definition
Ask the user:
- "What's the minimum viable version (v1)?"
- "What's explicitly out of scope?"
- "Are there any hard constraints (time, tech, etc.)?"
Phase 4: Technical Context
Ask the user:
- "What existing code or APIs does this depend on?"
- "Any preferred libraries or patterns?"
- "Are there security or performance requirements?"
Phase 5: Success Criteria
Ask the user:
- "How will we know this feature is complete?"
- "What tests should pass?"
- "Any metrics to track?"
Output: Feature Spec
Generate specs/<feature-name>.md:
# Feature: <Feature Name>
## Overview
<2-3 sentence description of the feature>
## Problem Statement
<What problem this solves and for whom>
## User Stories
### <User Type 1>
- As a <user>, I want to <action> so that <benefit>
- ...
### <User Type 2> (if applicable)
- ...
## Functional Requirements
1. <Requirement 1>
2. <Requirement 2>
3. ...
## Non-Functional Requirements (if any)
- Performance: <requirements>
- Security: <requirements>
- ...
## Out of Scope
- <Item 1>
- <Item 2>
## Dependencies
- <Existing code/APIs required>
- <External services>
## Success Criteria
- [ ] <Criterion 1>
- [ ] <Criterion 2>
- ...
Output: Implementation Plan
Generate specs/<feature-name>.implementation.md:
# Implementation: <Feature Name>
## Overview
This document outlines the phased implementation of <feature name>.
---
## Phase 1: <Phase Title>
**Objective:** <What this phase accomplishes>
### Tasks
- [ ] <Task 1>
- [ ] <Task 2>
- [ ] <Task 3>
### Success Criteria
- <How to verify this phase is complete>
---
## Phase 2: <Phase Title>
**Objective:** <What this phase accomplishes>
### Tasks
- [ ] <Task 1>
- [ ] <Task 2>
### Success Criteria
- <How to verify this phase is complete>
---
(Continue for each phase...)
---
## Verification
Final checks before feature is complete:
- [ ] All phases completed
- [ ] Tests passing
- [ ] Documentation updated
- [ ] Code reviewed
Phase Design Guidelines
When creating phases:
-
Keep phases small: Each phase should be completable by a single agent in one session (typically 10-30 minutes of work)
-
Make phases independent: Where possible, phases should not depend on later phases being complete
-
Front-load foundations: Put setup, config, and infrastructure in early phases
-
Isolate risky work: Put experimental or uncertain work in its own phase
-
End with integration: Final phase should wire everything together and verify
-
Typical phase count: Most features have 3-6 phases
Example Phase Breakdown
For a "user authentication" feature:
Phase 1: Database & Models
- Create users table migration
- Create User model with validation
- Add password hashing
Phase 2: Registration Flow
- Create registration endpoint
- Add input validation
- Return user on success
Phase 3: Login Flow
- Create login endpoint
- Verify credentials
- Return JWT token
Phase 4: Authentication Middleware
- Create auth middleware
- Verify JWT tokens
- Attach user to request
Phase 5: Integration & Testing
- Add protected route examples
- Write integration tests
- Update API documentation
Project Type Detection
Auto-detect project type to customize recommendations:
| File | Project Type | Suggestions |
|---|---|---|
package.json | Node.js/TypeScript | Express patterns, Jest tests |
Cargo.toml | Rust | Actix/Axum patterns, cargo test |
go.mod | Go | Standard library, go test |
pyproject.toml | Python | FastAPI/Django, pytest |
Gemfile | Ruby | Rails patterns, RSpec |
Interview Tips
- Keep questions conversational, not interrogative
- Summarize understanding before moving to next phase
- Offer reasonable defaults based on context
- Note uncertainties to address in implementation
- Don't over-engineer v1; note future enhancements separately
Commands 5
/borg-setup
Display instructions for adding the ralph-borg scripts to your terminal PATH.
Usage
/ralph-borg:borg-setup
What This Command Does
Outputs the shell configuration needed to run borg commands directly from your terminal.
Instructions
When this command is invoked:
Step 1: Detect Plugin Path
The plugin install path is available via $CLAUDE_PLUGIN_ROOT. Use this to construct the scripts path.
Step 2: Output Setup Instructions
Output the following instructions to the user:
To use borg commands in your terminal, add this line to your shell profile:
For ~/.zshrc (macOS default):
export PATH="$HOME/.claude/plugins/ralph-borg/scripts:$PATH"
For ~/.bashrc (Linux/older macOS):
export PATH="$HOME/.claude/plugins/ralph-borg/scripts:$PATH"
Then apply the changes:
source ~/.zshrc # or source ~/.bashrc
After setup, you can run:
borg --help # Show available commands
borg status # Check worktree status
borg merge <name> # Merge completed feature
Step 3: Verify Current Session
Also mention that within the current Claude Code session, the PATH is already configured via the SessionStart hook, so Claude can run borg commands. This setup is only needed for the user's terminal outside of Claude Code.
Notes
- The SessionStart hook handles PATH configuration within Claude Code sessions
- This command is for users who want to run
borgcommands directly in their terminal - Common use case: running
borg statusorborg mergeafter implementation completes
/feature
Create a detailed feature specification through an interactive interview process.
Usage
/ralph-borg:feature <feature-name> [options]
Arguments
feature-name(required): Name of the feature to spec (e.g.,user-auth,payment-flow)
Options
--skip-interview: Skip interview, use SPEC.md context only--template <path>: Use custom implementation template
What This Command Does
- Reads context from
specs/SPEC.mdif it exists - Conducts an interview to understand the feature requirements
- Creates
specs/<feature-name>.mdwith feature specification - Creates
specs/<feature-name>.implementation.mdwith phased implementation plan
Instructions
When this command is invoked:
Step 1: Validate Feature Name
- Feature name should be kebab-case (e.g.,
user-auth, notuserAuth) - Check if
specs/<feature-name>.mdalready exists; if so, ask to overwrite or rename
Step 2: Gather Context
Read the following files for context:
specs/SPEC.md- Product vision and overview (source of truth)specs/README.md- Index of all specificationsCLAUDE.md- Project-specific instructionspackage.json/Cargo.toml/go.mod- Detect project type
Step 3: Conduct Feature Interview
Use the spec-workflow skill to interview the user about:
- Purpose: What problem does this feature solve?
- User Stories: Who uses it and how?
- Scope: What's in/out of scope for v1?
- Dependencies: What existing code/APIs does it need?
- Technical Approach: Preferred patterns, libraries, or constraints?
- Success Criteria: How do we know it's done?
Step 4: Generate Feature Spec
Create specs/<feature-name>.md with:
- Feature overview
- User stories
- Functional requirements
- Non-functional requirements (if any)
- Out of scope items
- Dependencies
Step 5: Generate Implementation Plan
Create specs/<feature-name>.implementation.md with:
- Phased implementation approach
- Each phase has:
- Clear objective
- Specific tasks with checkboxes
[ ] - Success criteria
- Phases should be small (completable in one agent session)
- Typically 3-6 phases per feature
Step 6: Output Summary
Feature spec created!
Files:
- specs/<feature-name>.md (feature specification)
- specs/<feature-name>.implementation.md (implementation phases)
Next steps:
Run /ralph-borg:implement <feature-name> to start implementation
Or run directly:
borg-ralph loop <feature-name> specs/<feature-name>.implementation.md
Example Interview Flow
/ralph-borg:feature user-auth
> What problem does this feature solve?
Users need to log in to access protected resources.
> Who uses it and what's their workflow?
End users: sign up, log in, log out, password reset
Admins: view user list, disable accounts
> What's in scope for v1? What's explicitly out?
In: Basic email/password auth, JWT tokens, protected routes
Out: OAuth providers, 2FA, admin panel
> Any technical constraints or preferences?
Use existing Express app, store in PostgreSQL, bcrypt for passwords
> How will we know it's complete?
- Users can sign up and log in
- Protected routes reject unauthenticated requests
- Tokens expire and refresh correctly
Error Handling
- If no feature name provided, prompt for one
- If specs/SPEC.md doesn't exist, suggest running
/ralph-borg:initfirst - If interview is interrupted, save partial progress
/implement
IMPORTANT: This command launches the borg-ralph orchestration script. Do NOT implement the feature yourself. Run the shell commands below to spawn isolated agents that will do the implementation.
Usage
/ralph-borg:implement <feature-name>
The feature name is: $ARGUMENTS
What To Do
Step 1: Validate spec files exist
Check that both files exist:
specs/$ARGUMENTS.mdspecs/$ARGUMENTS.implementation.md
If missing, tell the user to run /ralph-borg:feature $ARGUMENTS first.
Step 2: Initialize borg (if needed)
Run this command to check borg status:
borg status 2>&1 || echo "NOT_INITIALIZED"
If output contains "NOT_INITIALIZED" or "not initialized", run:
borg init .
Step 3: Launch borg-ralph loop
DO NOT implement the feature yourself. Instead, run this exact command:
borg-ralph loop $ARGUMENTS specs/$ARGUMENTS.implementation.md
Note: The first argument is the slot name (same as feature name), the second is the implementation plan path.
This will:
- Spawn isolated Claude Code agents (one per phase)
- Each agent works in its own git branch
- Checkboxes get updated automatically as phases complete
- You'll see progress output in the terminal
Step 4: Report the result
After borg-ralph completes (or if it fails), tell the user:
borg-ralph loop finished.
To check status: borg status
To view changes: borg diff $ARGUMENTS
To merge locally: borg merge $ARGUMENTS
To create PR: borg merge $ARGUMENTS --pr
Key Point
You are an orchestrator, not an implementer. Your job is to run the borg-ralph script which will spawn other agents to do the actual coding work. Do not read the implementation spec and start coding - that's what the spawned agents will do.
/init
Initialize a spec-ready project structure for spec-driven development.
Usage
/ralph-borg:init [project-name]
Arguments
project-name(optional): Name for the project. Defaults to the current directory name.
What This Command Does
- Creates
specs/directory for specifications - Creates
specs/SPEC.md- product vision and requirements (source of truth) - Creates
specs/README.md- index and workflow guide - Creates/updates
CLAUDE.mdwith ralph-borg workflow instructions - Initializes git repository if not already present
- Initializes borg workspace by running
borg init .
Instructions
When this command is invoked:
Step 1: Check Prerequisites
Check if we're in a git repository. If not, offer to initialize one.
Step 2: Create specs/ Directory
Create the specs/ directory if it doesn't exist.
Step 3: Create specs/SPEC.md
If specs/SPEC.md doesn't exist, create it from the template at skills/spec-workflow/templates/SPEC.template.md.
Replace {{PROJECT_NAME}} with the provided project name or directory name.
Step 4: Create specs/README.md
Create specs/README.md as an index file with the following content:
# Specifications
Index of specification documents for {{PROJECT_NAME}}.
## Base Specification
| Document | Description | Status |
|----------|-------------|--------|
| [SPEC.md](./SPEC.md) | Complete product specification covering vision, features, technical architecture, and roadmap | Living document |
## Feature Specs
*Feature-specific specifications will be added here as they're created.*
| Document | Feature | Status |
|----------|---------|--------|
| | | |
## Implementation Plans
*Step-by-step implementation guides that reference their parent spec.*
| Document | Spec |
|----------|------|
| | |
## How This Works
- **SPEC.md** is the source of truth for product vision and requirements
- Feature specs are created when implementing specific sections of SPEC.md
- Each feature spec references its parent section in SPEC.md
## Spec Workflow
### The Refinement Flow
SPEC.md (explores options) ↓ Feature Spec (makes opinionated choices) ↓ Implementation Plan (phased tasks) ↓ Implementation (builds it) ↓ Update CLAUDE.md + SPEC.md (reflect reality)
### Document Roles
| Document | Purpose | Technology Stance |
|----------|---------|-------------------|
| **SPEC.md** | Product vision, explores options | Lists alternatives, doesn't mandate |
| **Feature specs** | Implementation plan for specific feature | **Opinionated** - makes specific choices |
| **CLAUDE.md** | Agent guidance for working in codebase | Reflects what's actually built |
### Why This Matters
- **SPEC.md** stays flexible for future features
- **Feature specs** make decisions so implementation can proceed without ambiguity
- **CLAUDE.md** must reflect reality or it misleads the agent
### Adding a New Feature Spec
1. Run `/ralph-borg:feature <name>` to create via interview, OR
2. Create manually: `specs/<feature-name>.md` and `specs/<feature-name>.implementation.md`
3. Add an entry to the Feature Specs table above
4. Update status as work progresses: `Draft` → `In Progress` → `Complete`
### After Implementation
When a feature is built:
1. Update **CLAUDE.md** with patterns, file locations, and working guidance
2. Update feature spec status to `Complete`
Step 5: Create/Update CLAUDE.md
Create or update CLAUDE.md with the following content:
# CLAUDE.md
## What This Is
{{PROJECT_NAME}} - [brief description].
## Commands
```bash
# Add your project commands here
Spec Workflow
This project uses spec-driven development.
- specs/SPEC.md - Source of truth for product vision and requirements
- specs/README.md - Index of all specifications
- specs/.md - Feature specifications
- specs/.implementation.md - Phased implementation plans
Working from Implementation Plans
When working from an implementation plan (.implementation.md files):
- Before starting: read the implementation plan to understand scope
- After completing each checkbox item: immediately update the plan by changing
- [ ]to- [x] - This keeps progress visible and prevents duplicate work across sessions
Available Commands
/ralph-borg:feature <name>- Create feature spec via interview/ralph-borg:implement <name>- Run implementation loop with parallel agents/ralph-borg:status- Show all feature progress
### Step 6: Initialize Borg Workspace
Run this command to initialize the borg multi-agent system:
```bash
borg init .
This sets up the isolated agent workspace and stores the current repo path so branches can be pushed back when features complete.
If borg is not found, inform the user:
borg command not found. Run /ralph-borg:borg-setup to configure your terminal PATH.
Step 7: Output Summary
After completing setup, output:
Spec-ready project initialized!
Created:
- specs/SPEC.md (edit this to define your product)
- specs/README.md (index and workflow guide)
- CLAUDE.md (project instructions)
Next steps:
1. Edit specs/SPEC.md to describe your product vision
2. Run /ralph-borg:feature <name> to spec out your first feature
3. Run /ralph-borg:implement <name> to build it with parallel agents
Error Handling
- If specs/SPEC.md already exists, skip creation and inform the user
- If specs/ already exists, skip directory creation
- If CLAUDE.md exists, append ralph-borg section if not already present
/status
Show the progress of all feature implementations.
Usage
/ralph-borg:status [feature-name]
Arguments
feature-name(optional): Show detailed status for a specific feature
What This Command Does
- Scans
specs/directory for implementation files - Parses phase checkboxes to determine progress
- Checks borg status for running agents
- Displays formatted status report
Instructions
When this command is invoked:
Step 1: Scan for Features
Find all files matching specs/*.implementation.md.
For each file, extract:
- Feature name (from filename)
- Total phases (count of
## Phaseheaders) - Completed phases (count of
[x]checkboxes) - Pending phases (count of
[ ]checkboxes)
Step 2: Check Running Agents
Run borg status to check for active agents.
Match running agents to features by branch name (borg/<feature-name>).
Step 3: Format Status Report
Display a status table:
Feature Status
==============
Feature Progress Status Branch
------- -------- ------ ------
user-auth [####--] 5/7 phases borg/user-auth (running)
payment-flow [######] 4/4 phases borg/payment-flow (complete)
notifications [------] 0/3 phases (not started)
Legend:
# = completed phase
- = pending phase
Summary:
Total features: 3
Complete: 1
In progress: 1
Not started: 1
Step 4: Detailed View (specific feature)
If a feature name is provided, show detailed status:
Feature: user-auth
==================
Spec: specs/user-auth.md
Implementation: specs/user-auth.implementation.md
Branch: borg/user-auth
Status: In Progress (5/7 phases)
Phases:
[x] Phase 1: Set up database schema
[x] Phase 2: Create user model
[x] Phase 3: Implement registration endpoint
[x] Phase 4: Implement login endpoint
[x] Phase 5: Add JWT token generation
[ ] Phase 6: Implement token refresh
[ ] Phase 7: Add protected route middleware
Agent Status: Running (PID 12345)
Current Cost: $0.42
Elapsed Time: 8m 32s
Commands:
borg logs user-auth # View agent output
borg diff user-auth # See changes so far
borg status --watch # Monitor in real-time
Step 5: Show Next Actions
At the end of the status report, suggest next actions:
Next actions:
/ralph-borg:implement notifications # Start pending feature
borg merge payment-flow --pr # Merge complete feature
Error Handling
- If no implementation files found, suggest running
/ralph-borg:initand/ralph-borg:feature - If specs/ directory doesn't exist, show helpful setup message
- If borg is not initialized, note that status is from spec files only
Hooks 1
Sponsors
Details
- Marketplace
- kiitsun-e/ralph-borg
- Category
- Community