Spec-Driven Development Tool

Introduction

Coding agents are good at writing code, but not at knowing what your business needs. Qlerify fills that gap.

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.

‍

What does the specification contain?

The specification is a machine-readable JSON file, not a picture of a diagram. It covers every bounded context in the workflow and marks the one you push from as the current context. For each context it describes:

• 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 criteria

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

‍

Before you start

You need:

• A workflow with a domain model. If you do not have one yet, start with Event Storming, Event Modeling or Domain-Driven Design, or reverse-engineer one from existing code.
• At least one bounded context. Push Spec is enabled for a context once it contains an aggregate.
• A GitHub account. Connect it from Account → Integrations or in Step 3 below.
• A coding agent. Claude Code, Cursor, Antigravity IDE and Gemini CLI support every step. Claude Web, Claude Desktop, Lovable, VS Code and ChatGPT connect over MCP; see the setup instructions for what each supports.

‍

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 its findings into Major Issues, Minor Issues and Notices. Click an issue to go to the element that caused it.

Fix the major issues first. They lead to broken code: two domain events with the same name, a command with no parameters, a command field that points to a different entity than the entity field it maps to, or a read model that references an entity that does not exist. Minor issues and notices are worth reading but do not block you.

Note: Validation is advisory. You can push a model that still has open issues, and your agent runs its own pre-flight scan and asks about anything it cannot resolve.

‍

Step 2: Review the specification

Review Spec shows the exact file you will push. You can toggle between JSON and YAML.

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

Click Approve Changes when the specification is correct. The push button stays disabled until you approve, which keeps an unreviewed model out of 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.

Use the repository that contains your application code, so the model and the code stay together.

Step 4: Push the specification

Push Specification to GitHub asks for a File path in repository. The default is qlerify-domain-model.json. If you plan to push more than one context, name each file after its context, for example orders-domain-model.json.

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 also lets the agent read workflows directly and 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, run this command:

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

Then install the companion plugin, which adds 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. Acquire 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 its findings and asks only about hard blockers, such as an event with no aggregate root or an acceptance criterion that contradicts an invariant.
3. Choose the platform. It asks once where the app should run and proposes one recommended stack by default. If you name a stack, 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, keeping each aggregate in its own transaction.
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 test suite, fixes failures, and asks you only if a test still fails after three attempts, since that usually points to a problem in the model.

How long a run takes depends on the size of the bounded context and the stack you choose. The agent finishes when the test suite passes or when it stops to ask you about a test it could not fix.

The agent leaves two files in .qlerify: a copy of the model it built from, and codegen.json, which records the stack and the persistence decisions it made. Step 7 uses these files as a reference point.

‍

Step 7: Keep the model and the code in agreement

The model is only useful if it stays accurate. 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 keep this working 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 modeling sessions. When the model changes in Qlerify, push it, then run sync to update the repository.

Note: You can import the specification file back into Qlerify at any time to recreate the full workflow and domain model, so the file also serves as a record of the system.