sddify

sddify is a lightweight Specification Driven Development (SDD) tool that helps you maintain and iterate on specification files across your project. It automatically discovers specification files and processes them using AI providers.

Installation

Install globally:

npm install -g sddify

Or use with npx (no installation required):

npx sddify

Initialization

Before using sddify, you need to initialize a configuration file in your project. This creates an sddify.json file with default settings.

Quick Start

Run the init command from your project root:

sddify init

The init command guides you through configuring your project and creates an sddify.json file with the default settings below:

{
  "provider": "cursor",
  "model": "claude-3.5-sonnet"
}

After initialization, you can edit sddify.json to customize the provider, model, and other settings according to your needs.

Usage

Run the tool from your project directory:

sddify

Or with npx:

npx sddify

This will find all spec.md files in your project and process them using the configured AI provider.

CLI Options

sddify supports several command-line options:

Main Command Options

• -f, --force: Force processing even if no changes are detected (bypasses lock file checks)
• -d, --dry-run: Show what would be processed without actually processing files
• -v, --verbose: Enable verbose output for debugging
• -c, --config <path>: Specify a custom path to the configuration file (default: sddify.json)
• -w, --watch: Watch for changes to specification files and process them automatically

Examples

# Watch mode - automatically process specs when they change
sddify --watch

# Dry run to see what would be processed
sddify --dry-run

# Force processing all specs regardless of changes
sddify --force

# Use a custom config file
sddify --config ./custom-config.json

# Verbose output for debugging
sddify --verbose

Configuration

Create an sddify.json file in your project root with the following structure:

{
  "provider": "claude",
  "model": "opus-4.5",
  "specFileNames": ["spec.md", "rules.md"],
  "railguards": [
    "Never modify files outside of ${currentFolder}",
    "Always use TypeScript for new files"
  ]
}

Configuration Fields

• provider (required): The AI provider to use for processing specifications
  • Supported values: claude, cursor, codex
• model (required): The model identifier to use with the provider
  • Example: opus-4.5, opus, etc.
• specFileNames (optional): An array of file names to discover as specification files
  • Default: ["spec.md"] if not specified
  • Allows projects to use multiple specification file names or custom naming conventions
  • Example: ["spec.md", "requirements.md"]
• railguards (optional): An array of additional constraints and guidelines added to the AI prompt
  • These are merged with default railguards (which include: never change specification files, be concise, never ask questions)
  • Supports ${currentFolder} placeholder that gets replaced with the actual folder path
  • Useful for enforcing project-specific rules and constraints
  • Example: ["Never modify files outside of ${currentFolder}", "Always use TypeScript for new files"]

Specification Files

Create spec.md files in any directory of your project to define requirements. The tool will automatically discover and process all spec.md files.

If you'd like to organize your specifications across several files, set the specFileNames property—for example, you might use the "complex" preset:
["STACK.md", "ARCHITECTURE.md", "STRUCTURE.md", "CONVENTIONS.md", "TESTING.md", "INTEGRATIONS.md", "CONCERNS.md"].

Example Project Structure

A typical project using spec.md files is organized in a way that makes collaboration and understanding requirements simple. You start with a main spec.md file at the root of your project—think of this as the "big picture" guideline for your whole codebase.

As your project grows, you might want to add more specific details or requirements for certain areas—like for a particular folder, feature, or component. That's where nested spec.md files come in handy! You can put a spec.md in any subfolder (for example, inside src/pages/ or components/). Each of these nested files can have its own set of instructions, rules, or goals, tailored just for that part of the project.

This setup helps everyone on your team:

• Keep specs organized and relevant by putting them right where they're needed
• Make big projects easier to understand by breaking down requirements into smaller, focused pieces
• Collaborate smoothly, since it's clear what each part of your project is supposed to do

In short: every time you add a new spec.md deeper in your folders, you're adding helpful instructions just for that spot—building up a clear, friendly map of requirements as your project grows!

project-root/
├── sddify.json           # Configuration file
├── spec.md               # Root specification
├── src/
│   └── pages/
│       └── spec.md       # Nested specification
└── components/
    └── spec.md           # Another specification

Providers

sddify supports multiple AI providers:

• Claude: Requires the claude CLI tool to be installed
• Cursor: Requires the cursor CLI tool to be installed
• Codex: Coming soon

License

MIT