Spec-Driven Development Tool

Introduction

Coding agents got very good at writing code. They did not get good at knowing what your business needs. That gap is what Qlerify fills.

You model the process with the people who understand it, validate the model, push it to your repository as a specification file, and let your coding agent build from it. The model lives in version control next to the code, so every later change starts from the same source of truth instead of a new prompt.

‍

What the specification actually contains?

The exported model is not a picture of a diagram. It is a machine-readable JSON file describing one bounded context:

• Aggregates and their aggregate roots
• Entities and value objects, with every attribute's type, cardinality, required flag and constraints
• Commands and their input fields
• Domain events emitted by each command
• Read models available to the actor before a command is invoked
• Given-When-Then acceptance criterias
  ‍

That is enough for an agent to derive a database schema, an API surface, handler logic that enforces the invariants, and one test per acceptance criterion.

‍

Before you start

• A workflow with a domain model. Start from Event Storming, Event Modeling or Domain-Driven Design if you do not have one yet.
• At least one bounded context. Push Spec unlocks once at least one entity is assigned to a bounded context.
• A GitHub account, connected from Account -> Integrations or from Step 3 below.
• A coding agent. Claude Code, Cursor, Antigravity, Gemini CLI, Claude Web, Claude Desktop and ChatGPT are all supported.

‍

Step 1: Validate the domain model

Open the Domain Model tab, pick a bounded context, and switch to Push Spec.

Validate Domain Model, checks the whole context and groups what it finds into
Major Issues, Minor Issues and Notices. Click any issue to jump straight to the
element that caused it.

Fix the major ones first. They are the ones that turn into broken code: an event with no aggregate root, a command that emits nothing, a value object that carries an id, an acceptance criterion that contradicts an attribute constraint. Minor issues and notices are worth reading but will not stop you.

Note: Validation is advisory, not a gate. You can push a model with open issues. Your agent will run its own pre-flight scan and ask about anything it cannot resolve.

‍

Step 2: Review the Specification

Review Spec shows the exact file that will be written. You cab toggle between JSON and YAML formats.

If the repository already holds an older version of the file, this step shows the difference instead, so you can see precisely what changed since the last push.

Click Approve Changes* when the specification reads correctly. Approval is required before the push button becomes active, which keeps an unreviewed model from reaching your repository.

Step 3: Connect to GitHub

Connect to GitHub, links the bounded context to a repository. Pick an account,
choose an existing repository or create a new one, and select a branch.

Point it at the repository where the application lives, not a separate docs repository. The whole idea is that the model and the code travel together.

Step 4: Push the specification

Push Specification to GitHub asks for a File path in repository. The
default is `qlerify-domain-model.json`; name it after the context if you plan to push more than one, for example.

Click Push Specification. When the file in the repository matches the model in Qlerify, the step shows Up to date.

Step 5: Connect your coding agent

Your agent can now read the specification from the repository. Connecting Qlerify over MCP on top of that lets it read workflows directly, and lets it write changes back later.

1. Go to Account -> Integrations and click Generate API Key under MCP API Key.
2. Open Setup Instructions  and pick your coding agent.
   For Claude Code that is one command:

claude mcp add --transport http qlerify https://mcp.qlerify.com \
--header "x-api-key: YOUR_API_KEY"

Then install the companion plugin, which carries the Qlerify skills:

/plugin marketplace add qlerify/qlerify-plugins
/plugin install mcp-companion@qlerify-plugins

The dialog has equivalent instructions for Cursor, Antigravity IDE, Lovable, VS Code, Gemini CLI, Claude Web, Claude Desktop and ChatGPT.

Step 6: Generate the application

Clone the repository, start your agent in that folder, and run:

/code-generation

The agent works through six phases:

1. Acuire the model: It reads the pushed specification file, or lists your Qlerify   workflows over MCP and asks which one to build from.
2. Pre-flight scan. It reports what it found and asks only about hard blockers, for example an event with no aggregate root or an acceptance critera that contradicts an invariant.
3. Choose the platform. It asks once where the app should live and confirms a stack, with a single recommended default rather than a menu. Name a stack yourself and it uses that instead, including older or unconventional choices.
4. Map the model to storage. Aggregate boundaries become transaction boundaries. Owned entities and value objects go with their root. Cross aggregate effects propagate through domain events, never joined transactions.
5. Generate. Project scaffold, persistence schema, aggregate types with invariant guards, command handlers behind pluggable authorization, the API surface, read models, domain event emission, one test per Given-When Then, and a frontend.
6. Test and iterate. It runs the suite and fixes what fails, and asks you only if a test is still failing after three attempts, since that usually means the model is wrong rather than the code.

A typical bounded context takes around fifteen minutes end to end and finishes with a green test suite.

The agent leaves two files behind in .qlerify: a copy of the model it built from, and codegen.json, which records the stack and the persistence decisions it made. That anchor is what makes the next step precise.

‍

Step 7: Keep the model and the code in agreement

The model is only worth keeping if it stays true. Run:

/sync

Sync works in both directions. Change the code, and it reads the new entities, endpoints, schemas and events and applies them to the Qlerify model. Change the model, and it detects the drift and hands off to code generation.

Two habits make this hold up over time:

• Commit the model with the code: Every pull request that changes behavior should include the updated specification file alongside the implementation. Reviewers then see the intent and the code in one place.
• Re-push after the modelling sessions: When the model changes in Qlerify, push it, then run sync so the repository catches up.

Note: The specification file is reversible. Import it back into Qlerify at any time and you get the full workflow and domain model again, which makes it a durable record of the system rather than a one-time export.