OpenSpec Deep Dive: Four Steps to Make AI Coding a Transparent, White‑Box Engine

What problem does OpenSpec address?

When using AI coding assistants, developers often lose requirements in chat logs, receive inconsistent code outputs, and struggle to track changes across a team. OpenSpec solves these issues by establishing a documented, file‑based specification before code generation.

What is OpenSpec?

OpenSpec is an AI‑native spec‑driven development (Spec‑Driven Development) system written in TypeScript (98.7% of its 34,900+ GitHub stars). It introduces a clear consensus on "what to build" between humans and AI, and it works with 22+ AI coding tools (Claude Code, Cursor, Windsurf, etc.) without locking into any single tool.

Three‑layer architecture

The system is split into three layers, each with a distinct responsibility:

CLI layer (command entry)

openspec init

– initialize a project and generate configuration for detected AI tools. openspec list – list active change proposals. openspec validate – validate spec file format. openspec archive – archive completed changes.

All commands accept the --json flag for downstream consumption.

Core engine layer

This layer implements the technical heart of OpenSpec:

Validation engine – provides four core validation methods ( validateSpec, validateChange, validateChangeDeltaSpecs, validateSpecContent) that parse Markdown, enforce Zod schemas, and apply business rules such as minimum purpose length (50 chars) and requirement keyword requirements (SHALL/MUST).

Artifact Graph – a directed acyclic graph (DAG) that records dependencies between Markdown artifacts. It computes a topological order using Kahn’s algorithm, guaranteeing deterministic ordering.

Specs Apply – merges Delta Specs into the main specification. The merge order (RENAMED → REMOVED → MODIFIED → ADDED) ensures renamed items are available for later modifications.

Schema layer

The schema layer defines the data model using Zod v4:

const ScenarioSchema = z.object({
  rawText: z.string().min(1),
});

const RequirementSchema = z.object({
  text: z.string().min(1).refine(t => t.includes('SHALL') || t.includes('MUST'),
    'Requirement must contain SHALL or MUST keyword'),
  scenarios: z.array(ScenarioSchema).min(1),
});

const SpecSchema = z.object({
  name: z.string().min(1),
  overview: z.string().min(1),
  requirements: z.array(RequirementSchema).min(1),
  metadata: z.object({
    version: z.string().default('1.0.0'),
    format: z.literal('openspec'),
    sourcePath: z.string().optional(),
  }).optional(),
});

const DeltaSchema = z.object({
  spec: z.string().min(1),
  operation: z.enum(['ADDED','MODIFIED','REMOVED','RENAMED']),
  description: z.string().min(1),
  requirement: RequirementSchema.optional(),
  requirements: z.array(RequirementSchema).optional(),
  rename: z.object({ from: z.string(), to: z.string() }).optional(),
});

const ChangeSchema = z.object({
  name: z.string().min(1),
  why: z.string().min(50).max(1000),
  whatChanges: z.string().min(1),
  deltas: z.array(DeltaSchema).min(1).max(10),
});

const ProjectConfigSchema = z.object({
  schema: z.string().min(1),
  context: z.string().optional(),
  rules: z.record(z.string(), z.array(z.string())).optional(),
});

Development workflow

OpenSpec offers two profiles:

Core Profile (quick path)

Ideal for small features or solo developers. Three commands complete a change:

# Step 1: create a change proposal
/opsx:propose add-dark-mode
# AI creates the following files:
#   proposal.md – why and what
#   specs/      – requirements & scenarios
#   design.md   – technical design
#   tasks.md    – implementation checklist
# Step 2: implement
/opsx:apply
# Step 3: archive
/opsx:archive

Example tasks.md generated for a dark‑mode feature shows a checklist of file creation, testing, and completion criteria.

Extended Profile (fine‑grained control)

Designed for large features and team collaboration. It adds stages such as /opsx:explore, /opsx:continue, /opsx:verify, and /opsx:sync. The explore stage lets the AI suggest implementation options, and the verify stage checks that tasks, code, and tests satisfy the spec.

Key design patterns

Registry + Adapter – a central CommandAdapterRegistry holds 22 adapters, each mapping a toolId (e.g., claude) to a file‑path pattern.

Strategy pattern – validation rules are an array of functions ( checkPurposeLength, checkRequirementTextLength, …) that can be extended.

Three‑level cache – schema resolution follows project‑level, user‑level, and package‑level precedence.

Builder pattern – generateInstructions assembles artifact instructions step by step.

Best practices

Spec authoring

Focus on what the system should do, not how. Use the GIVEN‑WHEN‑THEN format and include mandatory SHALL or MUST keywords.

Workflow selection

Core Profile – small, fast‑iteration tasks, personal projects.

Extended Profile – large, multi‑stage features, team work.

Context management

Clear the AI context before starting implementation.

Periodically summarize long conversations.

Prefer persistent documentation over transient chat logs.

Change management

Keep each change focused on a single logical unit.

Name changes descriptively (e.g., add-dark-mode).

Archive completed changes promptly.

Iterate – initial specs need not be perfect.

Benefits

Predictability – specifications are defined first, so AI generates code that matches expectations, reducing rework.

Traceability – all requirements live in version‑controlled Markdown, making it easy to revisit decisions after a session ends.

Tool freedom – the same spec works with any of the 22+ supported AI assistants.

Incremental adoption – teams can introduce OpenSpec gradually, starting with the Core Profile and later expanding to the Extended Profile.