Spec-Driven Development — Maquina

A Claude Code plugin for Rails-focused spec-driven development. Shape a feature into a structured spec, break it into tasks, and hand it off to Claude Code for implementation — with a progress file that survives across sessions.

What Is This?

A Claude Code agent that turns rough feature ideas into implementation-ready specs:

• Plans your product from existing MVP documentation (mission, roadmap, tech stack)
• Shapes feature specs through targeted discovery questions
• Writes formal specifications with user stories, acceptance criteria, and scope boundaries
• Breaks each spec into ordered, self-contained tasks
• Discovers coding standards and tribal knowledge already present in the codebase
• Tracks progress in a YAML file so any session can resume where the last one stopped

The goal: features built to spec instead of code thrown together, with a paper trail you can point Claude at later.

The Workflow

Steps 1–2 are one-time setup. Steps 3–6 repeat per feature. You can also drive the workflow with natural language — the agent responds to “shape a spec for comments” or “what’s next?” without requiring the slash commands.

Quick Start

1. Add the Marketplace

/plugin marketplace add maquina-app/rails-claude-code

2. Install the Plugin

/plugin install spec-driven-development@maquina

3. Initialize in Your Project

> /sdd-init

The agent creates the sdd/ directory, a progress file, and the folder structure the rest of the workflow depends on.

4. Plan the Product

> /sdd-plan

If MVP Creator documentation already exists in the project, the agent reuses it. Otherwise it asks you the product-planning questions directly.

5. Shape Your First Feature

> /sdd-shape user authentication

The agent asks the clarifying questions, writes requirements, and produces a spec ready for task breakdown.

Slash Commands

What You’ll Get

Each feature lives in its own folder under sdd/specs/:

sdd/
├── progress.yml                  # Workflow state across sessions
├── product/
│   ├── mission.md                # Product vision
│   ├── roadmap.md                # Feature priorities
│   └── tech-stack.md             # Technology choices
├── standards/                    # Coding standards discovered in your code
│   ├── global/
│   ├── backend/
│   └── frontend/
└── specs/
    └── 2026-04-16-user-auth/
        ├── planning/
        │   ├── requirements.md   # Gathered requirements
        │   └── visuals/          # Mockups, wireframes (optional)
        ├── spec.md               # Formal specification
        └── tasks.md              # Ordered task breakdown

Specs are self-contained: once shaped, Claude can execute them without needing to replay the conversation that produced them.

Usage Examples

Start From an Existing MVP

> /sdd-plan

If you ran MVP Creator earlier, the agent pulls directly from business-plan.md and technical-guide.md instead of asking the same questions again.

Shape a Feature From an Idea

> I want to add comments to posts

The agent asks for scope, user roles, moderation rules, and related code — then writes requirements and a spec.

Break a Spec Into Tasks

> /sdd-tasks for the user-auth spec

Produces grouped tasks (database layer, models, controllers, views, tests) with acceptance criteria.

Resume After a Break

> /sdd-status

Reads progress.yml and reports exactly where you left off — no context-replay needed.

Capture Tribal Knowledge

> /sdd-discover-standards

The agent scans your codebase for recurring patterns (naming conventions, controller structure, test style) and writes them into sdd/standards/ so future specs align with your existing code.

Package Contents

spec-driven-development/
├── agents/spec-driven-development.md   # Main agent
├── README.md                            # Full documentation
├── QUICKSTART.md                        # Quick reference
├── commands/                            # 6 slash commands
│   ├── sdd-init.md
│   ├── sdd-plan.md
│   ├── sdd-shape.md
│   ├── sdd-tasks.md
│   ├── sdd-status.md
│   └── sdd-discover-standards.md
├── scripts/
│   ├── init_sdd.sh                      # Bootstrap SDD structure
│   ├── new_spec.sh                      # Create a new spec folder
│   └── status.sh                        # Show progress
├── references/
│   ├── rails-standards.md               # Rails conventions
│   ├── hotwire-patterns.md              # Turbo/Stimulus patterns
│   └── document-templates.md            # Spec templates
└── templates/
    ├── standard-template.md             # Spec template
    └── progress.yml                     # Progress-tracking file

Team Installation

Add to your project’s .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "maquina": {
      "source": {
        "source": "github",
        "repo": "maquina-app/rails-claude-code"
      }
    }
  },
  "enabledPlugins": [
    "spec-driven-development@maquina"
  ]
}

Commit sdd/ alongside your code. Every teammate — human or AI — picks up the same plan, specs, and standards.

Next Steps