OpenSpec vs. the Specification Framework Landscape: Why DevOps Needs AI-Native Specs
🇩🇪 Auf Deutsch lesen~18 min read
openspecdevopsspecification-frameworksopenapiadrsai-agentschange-managementinfrastructure-as-code
Back openDesk Edu for a sovereign, open-source education — every vote counts.
Vote nowSave products you love by clicking the heart icon.
A purpose-built Ansible skeleton designed for AI agent workflow — declarative infrastructure management where agents understand the conventions before making changes.
Every DevOps team maintains specifications. API contracts, architecture decision records, design documents, runbooks, change proposals. The question is not whether you spec — it's whether your specs survive contact with reality.
Most specification frameworks were designed for human-to-human communication. They assume a reader who can infer intent from prose, fill in gaps from context, and navigate cross-references intuitively. That assumption breaks down when the primary consumer of your specs is no longer human.
We are entering an era where AI agents write, review, and deploy code alongside humans. The specification frameworks we choose determine whether those agents work with us or against us.
This article compares six approaches to specification and change management — including OpenSpec, the AI-native framework used in this project — across practical DevOps dimensions: agent-friendliness, CI/CD integration, documentation drift, and operational overhead.
Before comparing individual frameworks, it helps to understand what a specification framework actually provides:
Every framework addresses a subset of this pipeline. The difference is where they place the automation boundary — what they encode in machine-readable formats versus what they leave to human interpretation.
| Framework | Primary Format | Consumer | Scope | AI-Native? |
|---|---|---|---|---|
| OpenAPI/Swagger | YAML/JSON | Tools + Humans | API contracts | Partial |
| AsyncAPI | YAML/JSON | Tools + Humans | Event contracts | Partial |
| ADRs | Markdown | Humans | Architecture decisions | No |
| RFC Process | Markdown | Humans (team) | Design proposals | No |
| BDD/Gherkin | Plain text (Gherkin) | Tests + Humans | Behavior specs | Yes (structured) |
| Spec Kit | Markdown + Slash commands | AI Agents + Humans | Agent-driven SDD workflow | Yes (native) |
| OpenSpec | Markdown + CLI | AI Agents + Humans | Full change lifecycle | Yes (native) |
| GitHub Issues/Projects | UI + Markdown | Humans | Task tracking | No |
| JIRA + Confluence | UI + Rich text | Humans (org) | Project management | No |
OpenAPI is the most successful specification framework in DevOps. It defined a machine-readable contract format for REST APIs that generates documentation, client SDKs, server stubs, and test harnesses from a single source of truth.
Where it shines:
Where it falls short for modern DevOps:
# It does NOT tell you HOW to change it safely
paths:
/deployments:
get:
summary: List deployments
responses:
"200":
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Deployment"
OpenAPI is essential infrastructure. But it is a contract format, not a change management framework. It solves the interface problem and leaves the engineering process untouched.
AsyncAPI extends the contract-first model to event-driven architectures — Kafka topics, RabbitMQ queues, WebSocket channels, MQTT brokers.
What it does well:
Same fundamental limitation as OpenAPI: AsyncAPI describes the event surface — not the process that produced it. You know what Kafka topics exist, but you have no artifact trail of why they were added, what alternatives were considered, or whether the implementation matches the intended design.
Both OpenAPI and AsyncAPI suffer from the same DevOps gap: the spec lives separately from the change process that created it, and the two inevitably diverge.
Architecture Decision Records (ADRs) are a beautifully simple pattern: a short Markdown file per architecture decision, stored in the repository alongside the code. Originally proposed by Michael Nygard in 2011.
adr/
├── 001-use-postgresql-for-primary-storage.md
├── 002-adopt-kubernetes-for-orchestration.md
├── 003-use-redis-for-session-caching.md
└── 004-migrate-to-opensearch-for-logging.md
Each ADR follows a template: Context → Decision → Consequences. The format is intentionally minimal — prose-based, designed for humans to write and read.
Where ADRs excel:
Where they break down:
ADRs are valuable documentation. They are not a framework for driving change.
Behavior-Driven Development with Gherkin (Given/When/Then) is the closest predecessor to what OpenSpec attempts. It defines executable specifications that double as documentation and acceptance tests.
Feature: Deployment Rollback
Scenario: Rollback on health check failure
Given a deployment with 3 replicas
When the health check fails for 2 replicas
Then the orchestrator initiates a rollback
And the previous revision is restored within 60 seconds
BDD's genuine strengths:
Why BDD isn't enough for DevOps change management:
BDD occupies a useful niche: spec-as-test for specific behaviors. It does not replace a change management framework.
The RFC (Request For Comments) process, popularized by the IETF and adopted by React, Rust, Python, and Kubernetes, is the gold standard for collaborative design. A proposed change is documented in a structured template, discussed by the community, refined through review cycles, and either accepted or rejected.
rfcs/
├── text/
│ ├── 0000-template.md
│ ├── 0001-new-rfc-process.md
│ ├── 0002-adopt-openspec.md
│ └── 0003-spec-first-change-management.md
What makes RFCs powerful:
The DevOps gap with RFCs:
The RFC process produces excellent design artifacts. But the bridge from "RFC accepted" to "code deployed" is entirely manual.
Most DevOps teams default to GitHub Issues for change tracking and Pull Requests for code review. This is the path of least resistance — it ships quickly and requires no additional tooling.
What it gets right:
What it gets wrong for systematic change management:
GitHub Issues + PRs is a communication platform that teams repurpose into a workflow. It works for small teams with good discipline. It scales poorly.
Spec Kit, released by GitHub in 2025 and already boasting over 120,000 stars, brings Spec-Driven Development (SDD) to AI coding agents. Unlike OpenAPI or AsyncAPI which describe interfaces, or ADRs which record decisions, Spec Kit provides an executable workflow that AI agents can follow from specification through implementation — the closest existing approach to what OpenSpec attempts at the change management level.
The Spec Kit workflow:
Every feature follows a structured pipeline executed via agent slash commands:
| Command | Purpose |
|---|---|
/speckit.constitution | Establish project principles and development guidelines |
/speckit.specify | Define what to build (requirements and user stories) |
/speckit.clarify | Identify and resolve ambiguities before planning |
/speckit.plan | Create a technical implementation plan with tech stack choices |
/speckit.checklist | Generate quality checklists to validate requirements |
/speckit.tasks | Break the plan into actionable, ordered implementation tasks |
/speckit.analyze | Validate cross-artifact consistency before implementation |
/speckit.implement | Execute all tasks against the codebase |
/speckit.converge | Verify completeness and generate tasks for any remaining gaps |
Each command produces structured Markdown artifacts — SPEC.md, PLAN.md, TASKS.md, CHECKLIST.md — that feed deterministically into the next phase. The result is a repeatable, agent-guided development loop that closes the gap between "what should we build" and "it is built."
Where Spec Kit excels:
specify init command wires the integration.How Spec Kit compares to OpenSpec:
The two share a core philosophy — structured, agent-readable specifications — but target different parts of the engineering lifecycle:
| Dimension | Spec Kit | OpenSpec |
|---|---|---|
| Scope | Feature-level SDD workflow | Full change lifecycle (proposal → archive) |
| Primary interface | Slash commands (/speckit.*) via agent chat | CLI (openspec / /opsx-*) |
| Lifecycle phases | Spec → Plan → Tasks → Implement → Converge | Proposal → Design → Specs → Tasks → Implement → Delta → Archive |
| Upfront design | Minimal (constitution + specify) | Required (proposal + design artifacts) |
| Delta tracking | Implicit (converge detects gaps) | Explicit (delta specs synced to main specs) |
| Archive | Not a core primitive | Timestamped archive directory per change |
| Ecosystem | 105+ extensions, 22 presets, bundles | Built-in skills, CLI-driven orchestration |
| Team scale | Solo to small team | Structured teams with AI agents |
Spec Kit is the right choice when you want a lightweight, agent-friendly workflow that takes you from specification to implementation quickly — ideal for feature development in small teams. OpenSpec adds more structure upfront (proposal review, design artifacts, formal delta tracking) that becomes valuable as compliance requirements, team size, or change complexity increases. The tools are complementary: some teams use Spec Kit for rapid feature work and OpenSpec for infrastructure changes that require full traceability through proposal, design, and archive.
OpenSpec enters this landscape as a framework designed explicitly for the AI agent era. It combines the structured artifact approach of RFCs, the traceability of ADRs, the executability of BDD, and adds something none of these have: a machine-enforceable change lifecycle that AI agents can follow autonomously.
Every change in OpenSpec follows a defined artifact dependency chain:
1. AI agent as first-class consumer
Every artifact in an OpenSpec change has a defined schema, known output paths, and explicit dependencies. The CLI exposes machine-readable instructions (openspec instructions <artifact-id> --json) that tell an AI agent exactly what to create, what template to follow, and what context to read.
This is fundamentally different from a Markdown RFC or an ADR. The agent does not need to infer what a "good" proposal looks like — the schema defines it. The agent does not need to figure out which files to create — the CLI resolves the paths. The agent does not need to guess what artifacts are needed next — the dependency graph says so.
# Agent asks: "What do I need to create next?"
openspec instructions design --change "add-metrics-pipeline" --json
# Response: structured, actionable, unambiguous
{
"artifact": "design",
"template": "...",
"dependencies": ["proposal"],
"resolvedOutputPath": ".openspec/changes/add-metrics-pipeline/design.md",
"context": "..."
}
2. Full change lifecycle, not a fragment
OpenAPI gives you the API contract. ADRs give you the decision log. BDD gives you the acceptance tests. OpenSpec gives you the entire chain from proposal to archive, with each artifact's outputs feeding into the next.
This means an AI agent can:
No other framework provides this full lifecycle in a machine-enforceable format.
3. Delta specs as a primitive
When implementation reveals that the spec was wrong or incomplete, OpenSpec captures the delta — what actually changed versus what was planned. These delta specs can be synced back to the main specification, keeping the spec alive rather than letting it fossilize.
This solves the documentation drift problem that plagues every other framework. The spec does not sit on a shelf — it evolves with the implementation, and the deltas provide an audit trail of every divergence.
4. Archive is part of the workflow, not an afterthought
Every completed change is moved to an archive directory with a date prefix. The change becomes a historical record, not a forgotten directory. This matters for compliance, post-mortems, and training AI agents on past patterns.
OpenSpec is not a replacement for every specification tool. It has real trade-offs:
| Dimension | OpenSpec | Traditional Approaches |
|---|---|---|
| Setup overhead | Requires CLI, schema initialization | ADR: one file. Issues: zero setup |
| Learning curve | Artifact lifecycle must be learned | Everyone knows how to write Markdown |
| Tooling maturity | Emerging ecosystem | OpenAPI: decade+ of tooling |
| Human readability | Structured artifacts, less narrative | RFCs: natural prose, easy to read |
| Scope | Engineering change management | OpenAPI: API contracts only |
| Team size suitability | Best with AI agents or structured teams | ADRs: works for 2-person teams too |
OpenSpec adds structure overhead. For a solo developer fixing a typo, a GitHub issue is more appropriate. For a multi-step infrastructure change involving provisioning, deployment, configuration, and verification — especially when AI agents are executing the work — the structure is not overhead, it's leverage.
To make the comparison concrete, consider a realistic DevOps scenario: adding a Prometheus metrics pipeline with custom application metrics to a production service.
| Phase | OpenAPI | ADR | BDD | RFC | Issues/PRs | OpenSpec |
|---|---|---|---|---|---|---|
| Proposal | N/A | N/A | N/A | RFC #0032 | Issue "add metrics" | proposal.md |
| Design | N/A | ADR-005 "use Prometheus" | N/A | Included in RFC | PR description | design.md |
| Specs | /metrics endpoint def | N/A | Given/When/Then scenarios | N/A | N/A | specs/metrics/spec.md |
| Tasks | N/A | N/A | N/A | N/A | Issue checklist | tasks.md |
| Implement | Manual | Manual | Manual | Manual | PR | /opsx-apply |
| Verify | Schema valid? | N/A | Cucumber pass? | N/A | CI checks | Agent checks + CI |
| Trace | N/A (no link) | N/A (no link) | N/A (separate) | N/A (separate) | Issue ↔ PR link | Full artifact chain |
| Archive | N/A | N/A | N/A | Closed RFC | Closed issue | Timestamped archive |
In the OpenSpec workflow, a single agent can traverse the entire lifecycle. In every other approach, there are manual handoffs, information loss between phases, and no automated verification that the implementation matches the intent.
The right tool depends on who consumes the specification and what you need it to enforce.
Use Spec Kit when:
Use OpenSpec when:
Use OpenAPI/AsyncAPI when:
Use ADRs when:
Use BDD/Gherkin when:
Use RFCs when:
Use Issues/PRs when:
The specification frameworks most DevOps teams use today were designed for a world where humans write code, humans review code, and humans deploy code. That world is ending.
When AI agents participate in the engineering lifecycle — proposing changes, writing implementation code, verifying requirements, generating tests — the specification framework becomes the control plane for agent behavior. A free-form RFC or an unstructured GitHub issue gives an agent ambiguous instructions. A structured OpenSpec artifact with a defined schema, resolved output paths, and explicit dependencies gives an agent deterministic guidance.
This does not mean OpenSpec replaces every other tool. This project uses OpenAPI for its Stripe integration contract, ADRs for architecture decisions, and OpenSpec for managing changes. They serve different layers of the specification stack.
But for the change management layer — the part of the workflow that connects "we should do this" to "it is deployed and verified" — the existing tools leave a gap that AI-native agents cannot cross without human hand-holding. OpenSpec fills that gap by making the entire lifecycle machine-enforceable.
The frameworks that win in the DevOps era will not be the ones with the most features or the prettiest documentation generators. They will be the ones that AI agents can follow without human interpretation.
This article is part of the DevOps Infrastructure series on tobias-weiss.org. The OpenSpec framework is developed as part of the OpenCode project and is used to manage all changes on this site.