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 skill 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 | Step | Command | Output | |------|---------|--------| | 1. Initialize | `/sdd-init` | `sdd/` directory + `progress.yml` | | 2. Plan the product | `/sdd-plan` | `mission.md`, `roadmap.md`, `tech-stack.md` | | 3. Shape a feature | `/sdd-shape` | `planning/requirements.md` + formal `spec.md` | | 4. Break into tasks | `/sdd-tasks` | `tasks.md` with ordered task groups | | 5. Discover standards | `/sdd-discover-standards` | Extracted patterns in `standards/` | | 6. Check progress | `/sdd-status` | Current phase, completed items, next step | Steps 1–2 are one-time setup. Steps 3–6 repeat per feature. You can also drive the workflow with natural language — the skill responds to "shape a spec for comments" or "what's next?" without requiring the slash commands. --- ## Quick Start ### 1. Add the Marketplace ```bash /plugin marketplace add maquina-app/rails-claude-code ``` ### 2. Install the Plugin ```bash /plugin install spec-driven-development@maquina ``` ### 3. Initialize in Your Project ``` > /sdd-init ``` The skill 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 skill reuses it. Otherwise it asks you the product-planning questions directly. ### 5. Shape Your First Feature ``` > /sdd-shape user authentication ``` The skill asks the clarifying questions, writes requirements, and produces a spec ready for task breakdown. --- ## Slash Commands | Command | What It Does | |---------|-------------| | `/sdd-init` | Bootstrap the `sdd/` directory and `progress.yml` for a project | | `/sdd-plan` | Create mission, roadmap, and tech-stack documents from MVP docs or discovery | | `/sdd-shape` | Shape a feature into requirements and a formal spec | | `/sdd-tasks` | Generate an ordered task breakdown from a spec | | `/sdd-status` | Show current phase, completed steps, and next action | | `/sdd-discover-standards` | Extract coding patterns and tribal knowledge from the codebase | --- ## 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 skill 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 skill 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 skill 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/ ├── 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 ├── templates/ │ ├── standard-template.md # Spec template │ └── progress.yml # Progress-tracking file └── skills/spec-driven-development/ ├── SKILL.md # Main skill (routes to the slash commands) └── references/ ├── rails-standards.md # Rails conventions ├── hotwire-patterns.md # Turbo/Stimulus patterns └── document-templates.md # Spec templates ``` --- ## Team Installation Add to your project's `.claude/settings.json`: ```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

GitHub Repository

View source code and contribute.

MVP Creator

Upstream handoff: go from idea to MVP documentation.

Maquina UI Standards

Build the views described in your specs with consistent components.