Spec-driven development with parallel agent orchestration

version
0.2.6

Install

/plugin install ralph-borg@ralph-borg

Run it inside Claude Code after adding the marketplace with /plugin marketplace add kiitsun-e/ralph-borg.

Contents

Discovered from source

Skills 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:

  1. A feature spec (<feature>.md) describing what to build
  2. An implementation plan (<feature>.implementation.md) with phased execution steps

Input Context

Before starting, gather context from:

  • SPEC.md - Product vision and high-level features
  • CLAUDE.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:

  1. Keep phases small: Each phase should be completable by a single agent in one session (typically 10-30 minutes of work)

  2. Make phases independent: Where possible, phases should not depend on later phases being complete

  3. Front-load foundations: Put setup, config, and infrastructure in early phases

  4. Isolate risky work: Put experimental or uncertain work in its own phase

  5. End with integration: Final phase should wire everything together and verify

  6. 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:

FileProject TypeSuggestions
package.jsonNode.js/TypeScriptExpress patterns, Jest tests
Cargo.tomlRustActix/Axum patterns, cargo test
go.modGoStandard library, go test
pyproject.tomlPythonFastAPI/Django, pytest
GemfileRubyRails 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 borg commands directly in their terminal
  • Common use case: running borg status or borg merge after 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

  1. Reads context from specs/SPEC.md if it exists
  2. Conducts an interview to understand the feature requirements
  3. Creates specs/<feature-name>.md with feature specification
  4. Creates specs/<feature-name>.implementation.md with phased implementation plan

Instructions

When this command is invoked:

Step 1: Validate Feature Name

  • Feature name should be kebab-case (e.g., user-auth, not userAuth)
  • Check if specs/<feature-name>.md already 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 specifications
  • CLAUDE.md - Project-specific instructions
  • package.json / Cargo.toml / go.mod - Detect project type

Step 3: Conduct Feature Interview

Use the spec-workflow skill to interview the user about:

  1. Purpose: What problem does this feature solve?
  2. User Stories: Who uses it and how?
  3. Scope: What's in/out of scope for v1?
  4. Dependencies: What existing code/APIs does it need?
  5. Technical Approach: Preferred patterns, libraries, or constraints?
  6. 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:init first
  • 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.md
  • specs/$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

  1. Creates specs/ directory for specifications
  2. Creates specs/SPEC.md - product vision and requirements (source of truth)
  3. Creates specs/README.md - index and workflow guide
  4. Creates/updates CLAUDE.md with ralph-borg workflow instructions
  5. Initializes git repository if not already present
  6. 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):

  1. Before starting: read the implementation plan to understand scope
  2. After completing each checkbox item: immediately update the plan by changing - [ ] to - [x]
  3. 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

  1. Scans specs/ directory for implementation files
  2. Parses phase checkboxes to determine progress
  3. Checks borg status for running agents
  4. 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 ## Phase headers)
  • 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:init and /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

Sponsors

Details

Marketplace
kiitsun-e/ralph-borg
Category
Community