Can Spec‑Driven Development with OpenSpec Transform AI‑Assisted Coding?

Introduction

Recent AI coding assistants can generate large code blocks from natural‑language prompts, but when requirements are scattered across chats or hidden in developers' heads, the generated code often diverges from the intended system behavior.

What is Spec‑Driven Development (SDD)?

SDD treats the specification —a structured, machine‑readable description of what a system should do, its boundaries, and invariants—as the single source of truth. Code, tests, and documentation are generated and validated against this spec, turning the architecture into an executable control plane rather than a mere suggestion.

In the AI era, this aligns well with a workflow where humans focus on expressing intent and constraints, while AI generates implementation artifacts and continuously validates them against the spec.

OpenSpec: A Lightweight SDD Workflow

OpenSpec is an open‑source framework (GitHub: https://github.com/Fission-AI/OpenSpec) that implements SDD without inventing a new DSL. Its core structure consists of two directories: openspec/specs/: Holds the current “facts” of the system, organized by domain, describing how the system actually works. openspec/changes/: Contains in‑progress changes, each as a folder with files such as proposal.md (why and what), design.md (how), tasks.md (implementation steps), and a specs/ sub‑folder for delta specs (what behavior is added/modified/removed).

When a change is completed, its delta specs are merged back into specs/ and the change folder is moved to changes/archive/, creating a traceable “spec evolution history”.

OPSX Core Concepts

OPSX refines OpenSpec into an “action‑oriented” workflow:

Fluid / Iterative : Instead of rigid phases (plan → implement → finish), developers can continuously refine specs and designs during implementation.

Easy : All files are plain Markdown or YAML, editable with any editor.

Brownfield‑first : Emphasizes incremental changes on existing systems using delta specs rather than rewriting full documentation.

The human writes intent and constraints into the spec files; AI consumes those files to generate code, documentation, and tests, keeping both parties aligned on an executable, verifiable specification.

Artifacts and Dependency Graph (DAG)

OPSX models each change as a set of artifacts defined in schema.yaml. A typical change includes: proposal.md: Intent (Why), scope (What), and high‑level approach (How). specs/**/*.md: Incremental behavior details (the actual requirements). design.md: Technical solution and architectural decisions. tasks.md: Concrete implementation steps.

These artifacts form a Directed Acyclic Graph (DAG) where each node declares its dependencies. The schema file explicitly lists which artifacts must exist before another can be generated.

artifacts:
- id: proposal
  generates: proposal.md
  requires: []
- id: specs
  generates: specs/**/*.md
  requires: [proposal]
- id: design
  generates: design.md
  requires: [proposal]
- id: tasks
  generates: tasks.md
  requires: [specs, design]

The DAG drives the state machine that determines whether an artifact is BLOCKED (dependencies missing), READY (all dependencies present), or DONE (its file exists).

File‑System State Machine

OPSX checks the file system to infer each artifact’s state. Commands such as /opsx:continue or /opsx:apply automatically select the next READY artifact, generate its content via AI, and update the repository.

Customizable Schema and Templates

Teams can replace the default schema.yaml with a custom one, adding new artifact types or reordering dependencies. For example, a “research‑first” schema adds a research artifact that must precede proposal:

name: research-first
artifacts:
- id: research
  generates: research.md
  requires: []
- id: proposal
  generates: proposal.md
  requires: [research]
- id: tasks
  generates: tasks.md
  requires: [proposal]

Corresponding Markdown templates (e.g., research.md, proposal.md, tasks.md) live in the templates/ directory, guiding the AI on how to produce each artifact.

Comparison with Other Practices

OpenAPI/Swagger + Code Generation : Both are spec‑first, but OpenAPI focuses only on API contracts, while OPSX covers the full lifecycle from intent to tasks.

BDD / Gherkin : Both use near‑natural language to describe behavior. OPSX’s spec.md can adopt Gherkin syntax, but adds upstream artifacts (proposal, design) and downstream tasks, making it a “double‑sided” document for humans and AI.

Traditional RFC : RFCs are heavyweight, document‑centric processes. OPSX treats each change as a lightweight, continuously evolving RFC‑like artifact set, keeping the process agile and AI‑native.

Architecture and Core Commands

The architecture evolved from hard‑coded TypeScript templates to an external schema.yaml and a graph engine that:

Parses the schema to discover artifacts and dependencies.

Scans the file system to compute each artifact’s state (BLOCKED/READY/DONE).

Loads the appropriate Markdown template, injects global context and artifact‑specific rules from openspec/config.yaml, and sends the prompt to the AI.

Receives the AI‑generated content and writes it to the corresponding file.

Key commands (invoked via slash commands in the AI chat or the openspec CLI) include: /opsx:explore – Brainstorm ideas without a fixed structure. /opsx:propose "..." – Create a new change with all planning artifacts. /opsx:apply – Execute implementation tasks from tasks.md, confirming each step. /opsx:archive – Merge delta specs into the main spec set and move the change folder to changes/archive/.

Extended commands such as /opsx:new, /opsx:continue, /opsx:ff, and /opsx:verify provide fine‑grained control over scaffolding, step‑wise creation, fast‑forward generation, and verification of implementation against specs.

Getting Started

Install the OpenSpec CLI and run openspec init to create the openspec/ directory.

Optionally edit openspec/config.yaml to describe project context (tech stack, coding standards, etc.) and define rules for specific artifacts.

Use /opsx:explore for vague ideas or /opsx:propose "Your change description" to bootstrap a change.

Review the AI‑generated proposal.md, specs/, design.md, and tasks.md, editing as needed.

Run /opsx:apply to let the AI implement tasks, confirming each step.

When all tasks are done, execute /opsx:archive to finalize the change.

Risks and Misuse

Over‑templating can re‑introduce bureaucracy; keep schemas lightweight.

Injecting irrelevant or contradictory information into

config.yaml

context

can degrade AI output quality.

Never skip human review of generated artifacts; treat them as code that requires validation.

Regularly clean up stale or abandoned folders under changes/ to avoid repository clutter.

Conclusion

OPSX does not replace developer thinking; it makes the thinking process explicit, structured, and traceable, allowing AI to act as a precise co‑pilot. By shifting from linear phases to discrete, AI‑enabled actions, teams can achieve faster, more reliable development while preserving deep understanding of system intent.