Spec-Driven DevOps

AI-orchestrated development framework with 16 specialized roles for Claude Code, OpenCode, Gemini CLI, and Codex.

Spec-Driven DevOps turns a rough idea into a deployed, tested, documented project through a dependency-driven pipeline of AI roles — each with a focused responsibility, the right model for the job, and automatic handoffs to the next step.

npx spec-driven-devops --claude

How It Works

Instead of one giant prompt, SDD breaks development into 16 specialized roles organized in a dependency graph. Each role produces specific outputs that feed into the next. The workflow auto-chains — when one role finishes, the next one starts automatically.

/sdd:start
  ├─ New Project ──→ Vision → Architect → Planner → Builder → Tester → Deployer → SRE
  │                    ↘ Designer ↗
  └─ Existing ─────→ Retrofit → Planner → Builder → Tester → Deployer → SRE

                     Parallel/optional at any time after build:
                       ├─ Handoff Tester
                       ├─ Technical Writer
                       └─ Security Auditor

Dashed lines = optional or parallel. Solid lines = required dependency.

Quick Start

Install

# Claude Code
npx spec-driven-devops --claude

# OpenCode
npx spec-driven-devops --opencode

# Gemini CLI
npx spec-driven-devops --gemini

# Codex CLI
npx spec-driven-devops --codex

# All runtimes
npx spec-driven-devops --all

Run

Open your AI coding tool and start the workflow:

/sdd:start

That's it. The framework asks if you're building something new or enhancing an existing project, initializes tracking, and auto-chains through the roles.

Skip Ahead

Already have a vision doc or architecture plan? Jump to any point:

/sdd:start --from architect    # Skip vision, start at architecture
/sdd:start --from plan         # Skip to planning (assumes architecture exists)
/sdd:start --from build        # Skip to building (assumes plan exists)
/sdd:start existing --from plan  # Existing project, skip retrofit

The 16 Roles

Design Phase

Planning Phase

Implementation Phase

Testing Phase

Deployment Phase

Anytime

Utility Commands

Dependency Graph

The dependency engine handles two workflow paths, OR dependencies, role replacement, and parallel execution.

  New Project Path                    Existing Project Path
  ──────────────────                  ─────────────────────
  Vision Assistant (optional)         Retrofit Planner
        │                               (replaces VA + LA)
        ▼                                     │
  Lead Architect ◄── UI/UX Designer           │
        │              (optional,             │
        │               parallel)             │
        ▼                                     │
  Project Planner ◄──────────────────────────┘
        │
        ▼
  Stage Manager
        │
        ├──────→ Project Tester ──→ Project Deployer ──→ SRE
        │
        ├─ ─ ─→ Handoff Tester     (parallel, optional)
        ├─ ─ ─→ Technical Writer    (parallel, optional)
        └─ ─ ─→ Security Auditor    (parallel, optional)

  Event-triggered:
        Stage Manager ─ ─ ─→ Merge Manager    (on merge conflict)
        Project Planner ─ ─→ Feature Manager   (on feature request)

Key Mechanics

• OR dependencies: Project Planner requires lead-architect | retrofit-planner — either one satisfies the dependency
• Role replacement: Retrofit Planner replaces Vision Assistant + Lead Architect for existing projects
• Path filtering: New projects see VA/LA/UXD; existing projects see RP. Common roles appear on both paths
• Event-triggered roles: Merge Manager activates on merge conflicts; Feature Manager activates on feature requests
• Parallel execution: Stage Manager supports multiple instances for independent stages

Auto-Chaining

When a role completes, the workflow automatically continues:

  Role completes
       │
       ▼
  Check dependency graph for available next roles
       │
       ├─ 1 role available ──→ Auto-invoke next role
       ├─ Multiple available ─→ Ask user which to start first ──→ Auto-invoke
       └─ None available ─────→ Workflow complete!

You don't manually type /sdd:build after /sdd:plan finishes — it just happens. The entire pipeline from /sdd:start to /sdd:sre can run with minimal user intervention.

Model Profiles

Each role is assigned a model based on the complexity of its task. Three profiles control the cost/capability tradeoff:

Bold = recommended default (balanced profile). Override per-role in sdd-output/config.json:

{
  "model_profile": "balanced",
  "model_overrides": {
    "stage-manager": "opus"
  }
}

Configuration

Three-tier config resolution (each layer overrides the previous):

1. Hardcoded defaults — sensible baseline
2. User config — ~/.sdd/defaults.json (applies to all projects)
3. Project config — sdd-output/config.json (per-project)

Key Settings

{
  "model_profile": "balanced",
  "model_overrides": {},
  "workflow": {
    "auto_chain": true,
    "parallel_stages": true
  },
  "git": {
    "branching": "stage",
    "auto_commit": true,
    "commit_prefix": "sdd:"
  },
  "gates": {
    "require_tests": true,
    "require_review": false
  }
}

State Tracking

Every project gets a sdd-output/STATE.md with machine-readable fields:

**Path:** New Project
**Current Phase:** 3 - Implementation
**Status:** In Progress
**Active Roles:** stage-manager

## Role Checklist
- [x] Vision Assistant
- [x] Lead Architect
- [x] Project Planner
- [ ] Stage Manager
- [ ] Project Tester
- [ ] Project Deployer
- [ ] SRE

The **Field:** value pattern is both human-readable and regex-extractable. YAML frontmatter is auto-synced on every write for tooling integration.

Multi-Runtime Support

Spec-Driven DevOps installs natively on four AI coding platforms:

The installer automatically converts command formats, tool names, and permission models for each runtime. The same 16-role workflow runs identically across all platforms — useful for comparing model performance.

Project Structure

spec-driven-devops/
├── bin/
│   └── install.js              # Multi-runtime installer
├── commands/
│   └── sdd/                    # 19 slash command files
│       ├── start.md
│       ├── vision.md
│       ├── architect.md
│       └── ...
├── hooks/
│   └── src/
│       ├── sdd-statusline.js    # Progress bar in status line
│       ├── sdd-context-monitor.js   # Context window warnings
│       └── sdd-session-start.js # Auto-detect SDD projects
├── sdd/                        # Internals (copied to runtime config dir)
│   ├── bin/
│   │   ├── sdd-tools.cjs       # CLI dispatcher
│   │   └── lib/
│   │       ├── core.cjs        # Model profiles, output helpers
│   │       ├── roles.cjs       # 16 role definitions
│   │       ├── graph.cjs       # Dependency engine
│   │       ├── state.cjs       # STATE.md operations
│   │       ├── config.cjs      # 3-tier config resolution
│   │       └── init.cjs        # Compound context-loading commands
│   ├── workflows/              # Execution workflows
│   ├── references/             # Dependency graph, model profiles
│   ├── templates/              # 12 output templates
│   └── agents/                 # Sub-agent definitions
├── tests/                      # 110 unit tests
├── scripts/
│   ├── run-tests.cjs
│   └── build-hooks.js
└── package.json

CLI Tools

The sdd-tools.cjs dispatcher provides programmatic access for commands and hooks:

# State management
sdd-tools state load               # Load STATE.md
sdd-tools state get <field>        # Get a field value
sdd-tools state update <field> <value>
sdd-tools state complete-role <id> --output <path>

# Dependency graph
sdd-tools graph status             # Full graph visualization
sdd-tools graph next               # Available next roles
sdd-tools graph can-run <role-id>  # Check if a role can run

# Configuration
sdd-tools config get <key>         # Dot notation: model_profile, git.branching
sdd-tools config set <key> <value>

# Initialization
sdd-tools init start               # Check for existing project
sdd-tools init run-role <role-id>  # Validate deps, load context
sdd-tools init build [stage-num]   # Load stage build context

Testing

npm test

Runs 110 assertions across 4 test suites:

• roles — Role registry, lookups, path filtering, replacement, triggers
• graph — Dependency resolution, OR/AND deps, workflow progression
• config — Deep merge, dot notation access, 3-tier resolution
• state — Field extraction, frontmatter sync, role completion

Uninstall

npx spec-driven-devops --claude --uninstall

Removes all commands, internals, hooks, and statusline config. Your project's sdd-output/ directory is untouched.

License

MIT