Custom OpenSpec schemas packaged as copyable folders under openspec/schemas/.

Default OpenSpec includes the spec-driven schema, which is a strong general-purpose workflow. This repo adds more focused workflows for specific delivery contexts, and also demonstrates how to customise OpenSpec for different styles of work.

Detailed write-up: https://intent-driven.dev/blog/2026/02/12/openspec-custom-schemas/

For most projects, the built-in spec-driven schema is all you need. For complex projects — meaningful behaviour, technical design, and long-lived architectural decisions — intent-driven is the most complete general-purpose schema in this collection. The remaining schemas are either lighter subsets or specialised for a particular style of delivery.

How the schemas relate: intent-driven is behaviour-driven plus a durable ADR artifact — the same fenced-Gherkin specs verified by the same acceptance suite, adding per-change ADR review and repository-level decision records. It still subsumes spec-driven-with-adr (same ADR handling, richer specs, larger companion skill set). Choose behaviour-driven when you don't need durable ADRs. event-driven is domain-specific for event-centric/AsyncAPI-first systems, and minimalist is for small, low-risk changes.

To try these schemas without installing anything, start from a template repo — intent-driven-template or behaviour-driven-template — each a starter project with the schema, OpenSpec config, commands, and companion skills already installed.

Ask your coding agent to read the install guide and follow the instructions:

Read this file: https://raw.githubusercontent.com/intent-driven-dev/openspec-schemas/refs/heads/main/AGENT_INSTALL.md and follow the instructions.

If you already know which schema you want, include the name and the guide will confirm it exists before proceeding:

Read this file: https://raw.githubusercontent.com/intent-driven-dev/openspec-schemas/refs/heads/main/AGENT_INSTALL.md and install schema intent-driven.

Otherwise the guide will enumerate all available schemas and ask you to pick one.

Schemas declare their companion skills in a skills.txt manifest inside the schema directory. The install guide's Step 6 installs those skills from intent-driven-dev/skills into your project's .agents/skills/, so installing a schema also brings in the skills it works best with.

schema: intent-driven
stack: javascript # javascript | python

context: |
  Tech Stack:
    - Node.js, TypeScript
    - PostgreSQL

rules:
  proposal:
    - Maximum of 250 words
  tasks:
    - Break tasks to logical commits.

Artifact alignment source: openspec/schemas/intent-driven/schema.yaml (proposal, specs, design, adr, tasks).

For the full step-by-step install flow, see AGENT_INSTALL.md.

Spec-as-source BDD workflow: business use cases are Gherkin scenarios inside fenced ```gherkin blocks in spec.md, and those scenarios run as the acceptance suite every change must keep green (cucumber-js or behave, selected by stack: in config.yaml). Two rules govern the workflow: acceptance tests always pass, and specs and code are never modified together.

To try it without installing anything, start from the behaviour-driven-template — a starter project with the schema, OpenSpec config, commands, and companion skills already installed.

Artifact order:

proposal -> (specs, design) -> tasks

Activation:

schema: behaviour-driven

Validate:

openspec schema validate behaviour-driven

For more details, see openspec/schemas/behaviour-driven/README.md.

Experimental proposal-to-tasks workflow for changes that also need durable Architecture Decision Records persisted under the target repository's top-level adr/ folder. intent-driven shares this schema's ADR handling and adds fenced-Gherkin specs verified by an acceptance suite plus a larger skill set — prefer it unless you want plain spec-driven specs with ADRs and nothing more.

Artifact order:

proposal -> specs / design -> adr -> tasks

Activation:

schema: spec-driven-with-adr

Validate:

openspec schema validate spec-driven-with-adr

For more details, see openspec/schemas/spec-driven-with-adr/README.md.

behaviour-driven plus durable Architecture Decision Records: behaviour is written as Gherkin scenarios inside fenced blocks in spec.md, and the acceptance suite (cucumber-js or behave) runs them against the implementation, technical design is constrained by in-force ADRs, and each change completes an ADR review before task planning.

To try it without installing anything, start from the intent-driven-template — a starter project with the schema, OpenSpec config, commands, and companion skills already installed. (Companion skills are canonically hosted at intent-driven-dev/skills.)

Artifact order:

proposal -> (specs, design) -> adr -> tasks

Activation:

schema: intent-driven

Validate:

openspec schema validate intent-driven

For more details, see openspec/schemas/intent-driven/README.md.

Structured workflow for event-centric systems with Event Storming discovery followed by AsyncAPI specification.

Artifact order:

event-storming -> event-modeling -> specs -> design -> asyncapi -> tasks

Activation:

schema: event-driven

Validate:

openspec schema validate event-driven

For more details, see openspec/schemas/event-driven/README.md.

Fast path from spec to execution using user-story requirements and Gherkin acceptance-criteria style. Lightweight schema for well-scoped, low-risk changes.

Artifact order:

specs -> tasks

Activation:

schema: minimalist

Validate:

openspec schema validate minimalist

For more details, see openspec/schemas/minimalist/README.md.

See CONTRIBUTING.md for how to create/customize schemas using openspec schema init / openspec schema fork, and how to validate before opening a PR.