shipspec-marketplace

ShipSpec Claude Code Plugin

Spec-driven development meets the Ralph Wiggum loop.

Two problems plague AI-assisted coding:

1. Vibe coding — Throwing prompts at Claude without structure. It makes plausible-sounding but wrong assumptions. The bigger the feature, the more it drifts.

2. Giving up too early — Claude does its best attempt, exits, and you're left debugging half-finished work.

ShipSpec solves both. Specs keep Claude grounded. Ralph loops keep Claude iterating until it's actually done.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     THE SPEC SIDE                           │
│                                                             │
│   Feature Idea                                              │
│        ↓                                                    │
│   PRD (what to build + numbered requirements)               │
│        ↓                                                    │
│   SDD (how to build it + architecture decisions)            │
│        ↓                                                    │
│   TASKS.json (ordered work + acceptance criteria)           │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    THE RALPH SIDE                           │
│                                                             │
│   while task_not_verified:                                  │
│       implement(task)                                       │
│       verify(acceptance_criteria)                           │
│       if failed: retry with feedback                        │
└─────────────────────────────────────────────────────────────┘

Together: Each task carries its requirements, design context, and verification criteria. The Ralph loop keeps running until those criteria pass. Claude can't drift because the spec is always there. It can't give up because the loop keeps it going.

Why ShipSpec?

Problem	Solution
Vibe coding makes Claude drift	Structured PRD with numbered requirements
Claude forgets original intent	Requirements linked to every task
Architecture decisions get contradicted	SDD documents design choices upfront
Claude gives up on first attempt	Ralph loops retry until verified

Features

• Conversational PRD Gathering: Structured interview to extract clear requirements
• Codebase-Aware Design: Technical designs grounded in your existing architecture
• Agent-Ready Tasks: Implementation tasks with detailed prompts for coding agents
• Built-in Verification: Each task is verified against acceptance criteria before moving on

Installation

/plugin marketplace add jsegov/shipspec-claude-code-plugin
/plugin install shipspec@shipspec-marketplace

Usage

Quick Start

# Start planning a new feature with a description (or run interactively)
/feature-planning "Add user authentication with OAuth2 and session management"
/feature-planning                  # prompts for description interactively

# Implement tasks one by one (or specify a task ID)
/implement-task user-auth-oauth2
/implement-task user-auth-oauth2 3  # implement specific task

Full Feature Planning Workflow

Run /feature-planning with a description to go through the complete planning workflow:

/feature-planning "Add user authentication with OAuth2 and session management"

The command auto-generates a directory name (e.g., user-auth-oauth2) and guides you through 7 phases:

1. Feature Description - Gather or confirm the feature description, auto-generate directory name

2. Setup - Creates .shipspec/planning/<generated-name>/ and extracts codebase context

3. Requirements Gathering - Interactive Q&A with the PRD Gatherer agent about:

   • The problem you're solving
   • Target users
   • Must-have vs nice-to-have features
   • Technical constraints

4. PRD Generation - Creates structured PRD with numbered requirements

   • Pauses for your review and approval

5. Technical Decisions - Interactive Q&A about:

   • Infrastructure preferences (databases, caching, queues)
   • Framework and library choices
   • Deployment and scaling considerations

6. SDD Generation - Creates technical design document with:

   • Architecture decisions
   • API specifications
   • Data models
   • Component designs
   • Pauses for your review and approval

7. Task Generation - Automatically creates implementation tasks with:

   • Story point estimates
   • Dependencies
   • Detailed agent prompts
   • Acceptance criteria

Output Structure

After completing the feature planning workflow:

.shipspec/planning/your-feature/
├── PRD.md       # Product Requirements Document
├── SDD.md       # Software Design Document
└── TASKS.md     # Implementation tasks with agent prompts