OpenSpec Custom Schemas

In the OpenSpec 1.0 release post, I mentioned how config.yaml lets you tailor the OpenSpec workflow to your team’s needs. Custom schemas take that idea further. Instead of just configuring the workflow, you define the artifacts themselves, shaping what gets generated and in what order.

OpenSpec ships with a default schema called spec-driven. It produces four artifacts in sequence: proposal.md, specs.md, design.md, and tasks.md. Each artifact feeds into the next, creating a deliberate path from idea to implementation. This works well for general-purpose projects, but not every project fits that mold.

Custom Schemas

I built a few custom schemas to explore what different workflows could look like: openspec-schemas on GitHub. Let us look at what is in this repository.

Scaling Down: The Minimalist Schema

Not every project needs four artifacts. For well-scoped, low-risk changes, the minimalist schema strips the workflow down to two: specs.md and tasks.md.

Specs are authored as user stories with Given/When/Then acceptance criteria. Tasks follow directly from those specs. There is no separate proposal or design step. Details like tech stack and project constraints live in config.yaml, so the schema can stay lean without losing context.

This is a good fit when the scope is clear and the team does not need a formal proposal or design review before moving to implementation.

Scaling Up: Event-Driven Architectures

For complex systems built around asynchronous messaging, the event-driven schema adds discovery and modeling steps before the usual spec-design-task flow.

The workflow starts with event storming, capturing domain events, commands, actors, and bounded contexts. Next, event modeling transforms those into structured flows with Mermaid diagrams that visualize interactions and timelines. From there, the schema moves through specs.md and design.md into AsyncAPI spec generation, producing a validated asyncapi.yaml before any implementation tasks are created.

This schema is purpose-built for teams working with message brokers and event-driven patterns, ensuring that the async contract is specified and validated before code is written.

How to Get Started

To use a custom schema, create a schemas folder inside your openspec directory and place the schema definition there. Point your config.yaml to the schema name, and OpenSpec will use it for all subsequent changes.

Video Walkthrough

Custom schemas let OpenSpec fit your process rather than the other way around. Pick one from the schemas repository or use it as a starting point to build your own.

Read the full article on intent-driven.dev →

Originally published on intent-driven.dev on February 12, 2026