Specification Driven Development tool
npm install sddifysddify 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.
Install globally:
``bash`
npm install -g sddify
Or use with npx (no installation required):
`bash`
npx sddify
Before using sddify, you need to initialize a configuration file in your project. This creates an sddify.json file with default settings.
Run the init command from your project root:
`bash`
sddify init
The init command guides you through configuring your project and creates an sddify.json file with the default settings below:
`json`
{
"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.
Run the tool from your project directory:
`bash`
sddify
Or with npx:
`bash`
npx sddify
This will find all spec.md files in your project and process them using the configured AI provider.
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 )-w, --watch
- : Watch for changes to specification files and process them automatically
#### Examples
`bashWatch mode - automatically process specs when they change
sddify --watch
Configuration
Create an
file in your project root with the following structure:`json
{
"provider": "claude",
"model": "opus-4.5",
"specFileNames": ["spec.md", "rules.md"],
"railguards": [
"Never modify files outside of ${currentFolder}",
"Always use TypeScript for new files"
]
}
`$3
-
(required): The AI provider to use for processing specifications
- Supported values: claude, cursor, codex
- (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"]
- (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
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"].$3
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
CLI tool to be installed
- Cursor: Requires the cursor` CLI tool to be installedMIT