Skip to main content

Your first spec-driven change

What you will build​

You will add an ISBN field to a small Spring Boot API by writing no code yourself. A spec describes the change, a workflow of agents implements it on its own Git branch, and you review the result.

Prerequisites
  • The running stack from the Quickstart
  • A GitHub account and a fork of openjcockpit-demo-shop
  • A GitHub token that can push branches to your fork
  • JDK 25 and Maven 3.9 or newer, to verify the result locally
Tested version
This tutorial was tested on OpenJCockpit develop (draft, not yet verified on a clean machine). OpenJCockpit is in active development, so details may differ on other versions.
About the model
The demo runs on a local Ollama model (qwen3.6:27b). Output varies from run to run and is slower than hosted models, so your results will not match the screenshots exactly. Long waits in the video are sped up and labelled.
Video coming soon: Your first spec-driven change (end to end). The written steps below cover the same content.
Your first spec-driven change (end to end)

Steps​

1. Add the project​

In the dashboard, add a project with the URL of your fork. Then add a Git credential under Settings → Git credentials. Use a throwaway token and keep it off screen when recording.

Checkpoint
The project appears in the project selector.

2. Initialize the spec structure​

Select the project and open the spec files area. The repository has no .specify folder on its base branch, so the dashboard offers the spec-init flow. It pushes a starter template branch. Review that branch and merge it on GitHub.

Checkpoint

The dashboard no longer offers spec-init, and shows the Create spec with prompt button or your existing specs.

3. Bring in the first spec​

The demo repository already contains specs/001-add-isbn-field/spec.md. You can also download it. Read it first. It has three requirements and four acceptance criteria, each of them testable.

Prefer to write your own? Use Create spec with prompt. It starts the Create spec from prompt (RAG) workflow with the Business Analyst agent.

Checkpoint

The spec 001-add-isbn-field is listed for the project.

4. Run the implementation workflow​

Select the spec and start the Implement spec workflow. Its agents run in order:

Follow the run live in the workflow execution view: agent sequence, logs, outputs, policy decisions and the Git branch.

note

Expect this to be slow on a local model. Each agent call can take minutes.

Checkpoint

All three agents finish and the run shows a Git branch with one checkpoint commit per agent.

5. Review the branch​

The default workflows do not open a pull request or merge anything. Open the branch on GitHub and read the diff against your spec.

git fetch origin
git switch <run-branch>
mvn verify

Compare each acceptance criterion with a test. If a criterion has no test, that is a review finding.

Checkpoint

mvn verify passes, and GET /api/books/isbn/{isbn} returns a created book.

6. Open a pull request​

Open a pull request from the run branch the way you would for a colleague's change. Merging is your decision.

What just happened​

The spec was the input contract. The workflow chained role-based agents, each building on the previous output, and every output was committed as a checkpoint on a separate branch. Nothing reached your base branch without your review. Read more in the product docs on spec-driven development and agents and workflows.

Relevant limitations: output varies from run to run on a local model, and the default workflows have no approval gate. See known limitations.

Troubleshooting​

  • A job fails to start its container: run docker pull eclipse-temurin:25-jre.
  • A start on the project returns 502: the clone failed. Check the project URL and the Git credential.
  • The dashboard shows "run state lost": the run id expired or the service restarted mid-agent. Start the workflow again.

Next steps​

Spec 002 adds input validation, and spec 003 changes two classes. Try them for more practice. The approval gates tutorial builds on it.