OpenSpec-practise: a spec-driven development case study with runnable examples

A repository of documents, commands and two sample applications

OpenSpec Practise is described simply as a practical guide, and the project description says it originated in a community discussion about AI programming where the idea of implementing spec-driven development with OpenSpec was proposed. What the repository delivers is a complete worked case rather than a tool.

The README is organised around five modules, and that structure is the fastest way to understand what the project is.

The first is AI tool configuration: the collaboration commands and skills for AI assistants live in .claude/, generated by running openspec init --tools claude. Inside .claude/commands/opsx/ are the slash command definitions, and .claude/skills/ holds the matching SKILL.md files that spell out the instructions for each step.

The second is documentation. docs/openspec-user-manual.md is a complete manual covering installation, initialisation, document conventions, validation and best practices, and it is accompanied by two slide decks. docs/openspec-practical-guide.md covers how the approach lands in a real project, and docs/openspec-ai-workflow-analysis.md analyses the role of specs in an AI programming workflow.

The third is example code, an e-commerce minimum viable implementation in two languages. The fourth is the OpenSpec specification set in openspec/. The fifth is test data for the examples.

For a reader, the value is that all five are present. You can read the manual, then read a real archived change, then look at the code that came out of it, in the order the project suggests.

Six slash commands carry the whole workflow

The command set is small enough to read in a minute, and it is the clearest expression of the method.

There are six commands under .claude/commands/opsx/: /opsx:explore, /opsx:propose, /opsx:update, /opsx:apply, /opsx:sync and /opsx:archive. Each has a matching skill file in .claude/skills/ that defines the detailed instructions for that step.

The design point is that these are not ad hoc prompts. They are generated artefacts: the README states that the commands and skills are produced by openspec init --tools claude, so a developer who has OpenSpec installed can regenerate the same setup for a new project rather than copying it by hand. What this repository publishes is a working example of that generated configuration.

The lifecycle the commands describe has five stages with an extra one. Explore investigates the codebase and the options before anything is written, and is described as a zero-cost, low-risk step. Propose turns that into a change with a proposal, and the README notes that it uses openspec instructions to fetch templates and context dynamically. Apply is the implementation step, where the assistant writes code against the spec and the work is verified. Update is the middle stage that came later, used to revise a proposal while it is being implemented and to keep the artefacts consistent. Sync merges the delta spec changes into the main spec directory, and Archive moves the change into changes/archive/ so the main specs stay the single source of truth.

The order the project recommends for learning is the manual first, then the practical guide, then the workflow analysis, and only then the examples.

A fluid workflow, and a diff that only shows real changes

Two design choices distinguish this version of the workflow from a waterfall one.

The first is that the stages are not locked. The README says the Propose, Apply and Archive phases are no longer fixed, that you can go back and revise a specification at any time, and that explore can be interleaved at any stage. In practice that means the document you are about to implement against is a living artefact rather than a frozen contract, and the point of the /opsx:update command is to change it deliberately rather than to let the code drift away from it in silence.

The second is the review mechanism, and it is more specific than the general idea of a diff. The command openspec show <change> --diff is described as focused review, where a delta review looks only at the lines that truly changed. The subtlety the README spells out is that a MODIFIED requirement still has to restate all of its retained scenarios in the spec text, while the diff renders only the actual change.

That distinction matters for anyone reviewing specs in a pull request. A full file diff of a modified requirement looks enormous because the requirement repeats its scenarios, so a reviewer cannot tell what moved. The delta rendering solves exactly that, and it is a good example of a tool designed around how people actually read changes rather than around how text diffs happen to work.

The manual also documents validation, best practices and the document conventions, so the reasoning behind these choices is available for anyone who wants to extend the workflow rather than only follow it.

Findings validation, and the hardening between v1.13 and v1.14

The quality side of the workflow is a validation command and a report. openspec validate --report findings outputs a focused warnings and errors report, and the README notes a fix in the delta parser to prevent silent failures, so that spec drift is found earlier rather than quietly tolerated.

The mention of a silent failure is the important part. A validator that passes when it should fail is worse than no validator, because it converts a known unknown into a false reassurance. The project treats that as a bug worth naming in a feature list.

The release line between v1.13.1 and v1.14.3 is described as boundary tightening, and the items are worth listing because they describe the kind of tool this is. Configuration injection, so the project context reaches the assistant on every planning request. Path escape and symlink protection, which matters for a tool that reads files named in a specification. openspec list --archived and --all, so a change can be found whether it is live or archived. And openspec version --check, which lets a repository confirm which version of OpenSpec it expects.

There is also a practice described as using skip_specs to complete implementation-only alignment, which is the case where code changes without the specification changing and you need to say so explicitly rather than leave the two out of step.

Between them, these are the features of a specification tool that has been used on real repositories rather than only demonstrated on an example.

One set of specs, two implementations that disagree in useful ways

The example code is an e-commerce minimum viable implementation, written twice from the same specifications, once in Node.js and once in Python.

The Node.js version, in examples/ecommerce-mini, is layered as src/domain for the core business logic and a clean domain layer, src/http for the API implementation, src/services for the business service layer, src/repo for in-memory data storage, src/persist for file-backed persistence, and __tests__ for the test cases, which the README describes as unit, integration and performance tests. The core features list also notes the Node.js implementation has zero dependencies.

The Python version, in examples/ecommerce-mini-python, uses src/domain for the domain models defined with Pydantic, src/services for the business service layer, src/api for the interface service implemented with FastAPI, src/repo for in-memory storage, and tests for the Pytest suite.

Having the same specification produce two different codebases is the point of the exercise. It shows that the spec constrains behaviour while leaving implementation choices open, and it gives you a second opinion on any design decision, because the two implementations are free to disagree about how to organise the same capabilities.

The specification set itself lives in openspec/. openspec/config.yaml holds the project context, described as the tech stack, convention rules and store and references support, and it is injected automatically into every AI planning request. openspec/specs/ holds the archived main specifications, one directory per capability: cart-management, catalog-management, order-management, payment, domain-model and error-handling. And openspec/changes/archive/2025-01-27-v1-mvp/ holds a complete archived MVP change, with proposal.md carrying the why, what changes and capabilities, design.md for the architecture design, tasks.md as the implementation task list, and a specs/ subdirectory holding one spec.md per capability.

Running the two examples end to end

Both sample applications are runnable, and the README gives the commands for each.

For the Node.js version, you enter the examples/ecommerce-mini directory and run:

npm install
npm test
npm start
npm run start:prod

The tests use the Node.js built-in test runner. The development server uses in-memory storage and listens on port 3000 by default, while the production start uses file persistence with authentication and listens on port 3002 by default. The comment in the README also notes that the project has no external dependencies, while still recommending the install step as a habit.

The Python version lives in examples/ecommerce-mini-python:

pip install -r requirements.txt
pytest
python -m uvicorn src.api.server:app --reload

The service listens on port 8000 by default, and the entry point is the FastAPI application object in src.api.server.

The learning path suggests running both after reading the three documents, and the repository makes that order easy because the two implementations are products of the same specification set.

There is also test data in examples/ecommerce-mini/data/, with products.json, carts.json and orders.json, so the examples have something to work with out of the box.

DDD vocabulary mapped onto the spec tree, plus a beta cross-repository mode

The repository also connects OpenSpec to domain driven design, and the mapping is concrete rather than rhetorical.

A bounded context from the DDD vocabulary maps to a subdirectory under specs/, so every business boundary the modelling identifies has a home in the engineering specification. A requirement maps to a domain service or a command, describing one core business capability. A scenario maps to aggregate behaviour and is written in Given, When, Then form. A technical design maps to an application service that coordinates several domain services and manages transactions and security. And implementation tasks map to the tactical design to-do list, where entities, value objects and repository interfaces become concrete work items.

The mapping document, ddd-openspec-mapping.md, is described as being distilled from an open source skills repository called domain-driven-design-skills, which is a separate project by the same organisation. The README notes the project context in openspec/config.yaml can declare this mapping so the agent has the global architectural context, and shows a short configuration snippet for a domain and bounded context map.

Two further capabilities are worth knowing. The learning path walks through two archived changes in detail, one adding a get-product-by-id feature under the v1.5.0 workflow and one adding product search with price sorting under v1.7.0, the latter demonstrating /opsx:update revising a planning document mid-implementation while keeping the artefacts consistent. And Stores, marked as Beta, support planning across repositories, with the planning centralised in a separate store repository and multiple code repositories referencing read-only context through references.

On the practical side, the repository is Apache-2.0 licensed, ships both Chinese and English documentation in docs/ and docs-en/, and the release line is active, with v1.11.0, v1.13.0 and v1.14.3 published in September and October 2026.

Editorial conclusion

OpenSpec-practise suits developers who want to understand spec-driven development with AI assistants by reading a real, complete case rather than a toy, and it suits teams that already use OpenSpec and want a worked reference for how a change flows from exploration to an archived spec. It does not suit you if you are looking for a tool to adopt, because the artefact here is documentation and example code rather than a library, and it does not suit a team that wants its own specifications written for it. Check three things before you spend time on it: that the OpenSpec version it demonstrates matches the one you use, since the repository tracks recent releases and the features described differ between v1.13, v1.14 and v1.5, that you read the archived MVP change alongside the final server code so you see the whole chain, and that the workflow is not locked, because the Propose, Apply and Archive stages are described as fluid and revisable. The last push to the repository was on 2026-10-19 and the newest release is v1.14.3 from the same day.

Frequently asked questions

Official sources

1. ForceInjection/OpenSpec-practise on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases