Spec-Driven DevOps

AI-orchestrated development framework with 16 specialized roles and an Agent-to-Agent (A2A) architecture 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.

v2 adds a typed A2A layer: a central orchestrator that routes tasks to specialized agents (Claude Code for generative work, Codex for security/review) through configurable pipelines with contract enforcement.

npx spec-driven-devops --claude

What's New in v2

• Central Orchestrator — routes tasks to the right agent based on type
• Typed Contracts — AgentTask / AgentResult envelopes with runtime validation
• Task Classifier — rule-based classification (security, review, generate, refactor)
• Pipeline Engine — sequential, parallel, and conditional agent chains with context passing
• Result Aggregator — merge multi-agent outputs with conflict reconciliation
• Error Handling — retry, reroute, partial results, structured error types
• TypeScript — full codebase ported to strict TypeScript

Migrating from v1

v1 commands and workflows work identically — the A2A layer is additive. No breaking changes to the slash command interface. Install the alpha alongside v1:

npx spec-driven-devops@alpha --claude

v1 remains available: npx spec-driven-devops@1.3.1

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

A2A Architecture

The v2 orchestrator sits between specs and agents. Instead of a single AI processing everything, tasks are classified, routed to the best agent, and results are aggregated.

                    ┌─────────────────────┐
                    │    Spec / Input      │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │     Classifier       │
                    │  (security? review?  │
                    │   generate? refactor?)│
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │    Orchestrator      │
                    │  (route, retry,      │
                    │   validate contracts)│
                    └───┬─────────────┬───┘
                        │             │
              ┌─────────▼───┐   ┌─────▼─────────┐
              │ Claude Code  │   │    Codex       │
              │ (generative) │   │ (security/     │
              │              │   │  review)       │
              └──────┬──────┘   └───────┬───────┘
                     │                  │
                    ┌▼──────────────────▼┐
                    │    Aggregator       │
                    │  (merge, reconcile, │
                    │   flag conflicts)   │
                    └────────────────────┘

Task Classification

Contracts

Every task and result is typed and validated at agent boundaries:

interface AgentTask {
  id: string;
  type: "security" | "review" | "generate" | "refactor";
  spec: Record<string, unknown>;
  context?: Record<string, unknown>;
  successCriteria: string[];
}

interface AgentResult {
  taskId: string;
  agent: "codex" | "claude-code";
  status: "success" | "partial" | "failed";
  output: Record<string, unknown>;
  flags?: string[];
  confidence?: number;
}

Programmatic Usage

const { Orchestrator } = require("spec-driven-devops/dist/orchestrator");
const { StubAgent } = require("spec-driven-devops/dist/agents");

const orch = new Orchestrator();
orch.registerAgent(new StubAgent("claude-code"));
orch.registerAgent(new StubAgent("codex"));

const results = await orch.run({
  tasks: [
    { type: "generate", description: "Scaffold a REST API" },
    { type: "security", description: "Audit dependencies for CVEs" },
    { type: "review", description: "Review code quality" },
  ],
});

console.log(results);
// [
//   { taskId: "...", agent: "claude-code", status: "success", ... },
//   { taskId: "...", agent: "codex", status: "success", ... },
//   { taskId: "...", agent: "codex", status: "success", ... },
// ]

Pipeline Chains

Build multi-step agent pipelines with the chain builder:

const { Pipeline, chain } = require("spec-driven-devops/dist/pipeline");
const { StubAgent } = require("spec-driven-devops/dist/agents");

const agents = new Map();
agents.set("claude-code", new StubAgent("claude-code"));
agents.set("codex", new StubAgent("codex"));

const steps = chain()
  .step("generate", "claude-code", { description: "scaffold API" })
  .step("review", "codex", { description: "review generated code" })
  .onFlag("needs-regen", "refactor", "claude-code", { description: "fix review findings" })
  .build();

const pipeline = new Pipeline(steps, agents);
const results = await pipeline.execute();
// Step 2 receives step 1's output as context.
// Step 3 only runs if step 2 flags "needs-regen".

Custom Classification Rules

const { Classifier } = require("spec-driven-devops/dist/classifier");

const classifier = new Classifier();

classifier.addRule({
  name: "ml-training",
  patterns: [/\b(train|fine-tune|model\s*training)\b/i],
  type: "generate",
  priority: 5,  // lower = higher priority
});

const result = classifier.classify("Train a new ML model");
// { type: "generate", confidence: 0.85, matchedRule: "ml-training", ambiguous: false }

Real Agent Adapters

Replace stubs with real CLI adapters:

const { ClaudeCodeAdapter, CodexAdapter, AgentRegistry } = require("spec-driven-devops/dist/agents");

const registry = new AgentRegistry();
registry.register(new ClaudeCodeAdapter({ timeout: 60_000 }));
registry.register(new CodexAdapter({ timeout: 60_000 }));

// Check availability
const status = await registry.checkAvailability();
// { "claude-code": true, "codex": false }

Result Aggregation

const { Aggregator } = require("spec-driven-devops/dist/pipeline");

const aggregator = new Aggregator({ strategy: "merge" }); // or "override", "flag-and-return"
const final = aggregator.aggregate(results);
// {
//   status: "success",
//   mergedOutput: { ... },
//   agentContributions: [{ agent: "claude-code", taskId: "...", status: "success" }, ...],
//   flags: [],
//   warnings: [],
// }

Error Handling

const { ErrorHandler, AgentTimeoutError } = require("spec-driven-devops/dist/errors");

const handler = new ErrorHandler({ maxRetries: 3, allowPartialResults: true });

// On agent timeout
const decision = handler.handle(new AgentTimeoutError("codex", "task-1", 5000), "task-1");
// { action: "retry", detail: "Timeout on agent \"codex\" — retrying (1/3)" }

The 16 Roles

Design Phase

Planning Phase

Implementation Phase

Testing Phase

Deployment Phase

Anytime

Utility Commands

Dependency Graph

  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)

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!

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)

{
  "model_profile": "balanced",
  "model_overrides": {
    "stage-manager": "opus"
  },
  "workflow": {
    "auto_advance": false,
    "fresh_sessions": true,
    "parallel_stages": true
  },
  "git": {
    "branching_strategy": "stage",
    "stage_branch_template": "sdd/stage-{stage}-{slug}"
  }
}

Multi-Runtime Support

The installer converts command formats, tool names, and permission models automatically.

Project Structure (v2)

spec-driven-devops/
├── src/                            # TypeScript source (v2)
│   ├── contracts/                  # AgentTask / AgentResult types + validators
│   ├── orchestrator/               # Central orchestrator, router, decomposer
│   ├── classifier/                 # Task classification engine
│   ├── agents/                     # Agent adapters (Claude Code, Codex, stub)
│   ├── pipeline/                   # Chain builder, context, aggregator
│   ├── errors/                     # Error types + handler
│   ├── lib/                        # Core engine (roles, graph, state, config)
│   └── cli.ts                      # CLI dispatcher
├── dist/                           # Compiled CJS output
├── commands/sdd/                   # 19 slash command definitions
├── hooks/src/                      # Claude Code hooks (statusline, context monitor)
├── sdd/                            # Internals (workflows, templates, references)
├── tests/                          # 427+ tests
└── package.json

Testing

npm test

Runs 427+ assertions across 15 test suites covering contracts, orchestrator, classifier, agents, pipeline, aggregation, errors, core engine, and end-to-end integration.

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