From draft to a passing quality gate.

1. New project with the wizard

In this tutorial you choose stack and checking tools yourself. Under Projects click „Ausführlicher Assistent“ (detailed wizard; or open /wizard and click „Neuen Assistenten starten“). The short path without these details is „Neues Projekt“ (new project) → quick start (name, kind, description; see the quickstart).

1. Step 1 – target platform: Web.
2. Step 2 – backend: choose "Modern Spring Boot Backend".
3. Step 3 – frontend(s): none (pure API).
4. Step 4 – questions: use realistic values:
   • Project title: Phonebook API
   • Vision: "REST API for a simple phonebook with CRUD endpoints and Postgres persistence."
   • Java version: 25
   • Base package: io.example.phonebook
   • Database: PostgreSQL
   • Architecture: hexagonal
   • Language: English
5. Step 5 – quality gates: turn on ArchUnit and OWASP Dependency-Check. Leave Trivy off (Trivy is for container builds; Playwright only appears with a frontend).
6. Step 6 – summary: review all values and the cost estimate, then click "Create and edit project".

You land in the project editor with all fields sensibly pre-filled. Among other things the wizard turned your answers into:

• technologyPreferences: "Template: Modernes Spring Boot Backend. Spring Boot <version>. Java 25."
• architecturePreferences: "Datenbank: PostgreSQL. Architektur-Stil: hexagonal. Basis-Paket: io.example.phonebook."
• nonfunctionalRequirements: "Aktivierte Quality-Gates: …" (ArchUnit, OWASP Dependency-Check; the wizard writes these values in German)

2. Review and adjust the artifacts

Save in the project editor and on the project page, under „Technische Einstellungen“ (technical settings, collapsed in simple view), click "Generate Markdown artifacts" („Markdown-Artefakte generieren“). The platform produces six files (view and edit them under "Show artifacts"). Read them once:

1. PROJECT.md — the charter. Is the vision clear? Is the audience right?
2. INSTRUCTIONS.md — the concrete brief for the agent. This is the most important file. Typos or ambiguities here are taken at face value by the agent.
3. AGENTS.md — the role description of the team, preceded in the workspace by the engineering guardrails.
4. WORKFLOW.md — phase model and approval gates.
5. DEFINITION_OF_DONE.md — when is the run done?
6. README.md — entry point for the agent inside the workspace.

Fix anything that's unclear. Example: if INSTRUCTIONS.md says "create CRUD endpoints", spell out which fields a Person has (name, phone, email). The more precise, the smaller the chance of hallucinations.

3. Plan – the plan run produces the backlog

Instead of generating code right away, you first let the agent plan. In the project open "Backlog / Plans" („Backlog / Pläne“, project page under „Technische Einstellungen“):

1. Focus (optional): e.g. skeleton, persistence, CRUD endpoints, tests, docs — small, individually testable packages.
2. Click „Plan-Lauf starten“ (start plan run). The factory creates the plan run and starts it right away; it phrases the planning brief itself.
3. Before EXECUTION you approve it on the run page with „Freigeben und fortsetzen“ (approve and continue; see step 6).

A plan run writes no production code. It creates Markdown files in the workspace under plans/ (plans/NNNN-*.md) — one per work package. After the run the platform indexes them as backlog items with status PROPOSED.

4. Select – activate a backlog item

Open "Backlog / Plans" in the project. You see the items produced by the plan run, each with a title and status. Pick the first, smallest package — typically "Create skeleton" — and click "Activate".

"Activate" immediately creates a build run whose goal is the plan, and starts it. An item only becomes DONE once its build run has actually been merged, so you can read progress off the backlog at any time. Dependencies between items are maintained with "+ Blocker".

5. Build – build run on its own branch

The activated backlog item has already started a build run. Alternatively you create a build run by hand — keep it small. Navigate to /runs/new (or, in expert view, „Lauf mit allen Optionen anlegen“ (create run with all options) on the project page; the project is then prefilled). The short path is „Nächster Auftrag“ (next task) on the project page: enter the task, click „Bauen“ (build):

1. Project: Phonebook API.
2. „Titel des Laufs“ (run title): Create skeleton (left empty, the factory uses the first line of the task)
3. „Auftrag“ (task): a concrete prompt like this:

   Set up the initial Maven project with Spring Boot 4.x.
   Create:
   - pom.xml with spring-boot-starter-web, spring-boot-starter-data-jpa, postgresql, h2 (test)
   - Application class with @SpringBootApplication
   - application.yml with Postgres config (local) and H2 (test profile)
   - a simple Person entity with id, name, phone
   - a PersonRepository as a Spring Data JPA repository
   - a REST controller with GET /persons (return all)
   - smoke test with @SpringBootTest that loads the context
   - README explaining "how to start" and "how to test"

4. „KI-Werkzeug (Adapter)“ (AI tool): claude (default from the settings). The model comes from the agent role in the team or the role default.
5. Click „Bauen“ (build) — the run is created and starts right away. („Nur anlegen“ (only create) creates it as a draft; then start it on the run page with „Lauf starten“.)

The build run works in the project's persistent workspace and creates its own branch sdlc/run-<id8> (the first eight characters of the run ID) for its changes. That keeps main clean and makes every run traceable as a self-contained branch history. Only one run per project executes at a time.

6. Click through phase approvals

While the run executes, it goes through seven phases. At critical transitions the platform waits for your explicit approval:

The buttons are on the run page under „Aktionen“ (actions; only those that work in the current state, and the „Was jetzt?“ box names the next step): „Freigeben und fortsetzen“ (approve and continue, optionally with a reason) or „Abbrechen“ (cancel) with a reason — the run then becomes Abgebrochen (CANCELLED). Browser notifications can be activated bottom right on the run page; they fire on WAITING_FOR_APPROVAL or run end.

7. Read logs, inspect Git diff, approve with inline diff

During the EXECUTION phase Claude Code outputs stream live into the log view ("Show logs"). Look for, for example:

• "Reading PROJECT.md..." — agent has read the charter.
• "Reading INSTRUCTIONS.md..." — agent has read the brief.
• "Creating pom.xml..." — first file is being written.
• "Starte automatische Korrektur (Versuch 1/2)" — the build was red, the factory feeds the feedback back in (see step 8).

Under "Git status" you see branch, HEAD, working tree and the latest commits. The commits are created by the factory itself (the agent is not allowed to commit).

At WAITING_FOR_APPROVAL the detail view embeds the git diff since run start directly — no terminal switch needed. If OK: Approve and continue with a short justification.

8. Self-correction – automatic feedback retry

If the build goes red in the VALIDATION phase (compile errors, failing tests), the run does not abort. Instead it moves to NEEDS_CORRECTION and the platform starts self-correction:

1. The platform collects the error output of mvn verify (compiler and test logs).
2. It builds a corrective prompt from it and sends it to the agent — the run goes back to RUNNING.
3. The agent fixes things on the same branch, then mvn verify runs again.

This loop is bounded: after two automatic correction attempts the platform gives up and leaves the run at NEEDS_CORRECTION for you to step in. That way a stubbornly red task doesn't burn tokens forever.

9. Quality gate – off, advisory or blocking

After a successful build the quality gate runs automatically as part of the pipeline (mode advisory, default). On the run page under „Quality-Gate“ you see the result or re-run it with „Quality-Gate ausführen“ (run quality gate). It calls six reviewers (plus spec-conformance with a bound, approved spec):

• aider-review — calls the Aider CLI in read-only mode, hunts for smells.
• claude-review — calls Claude Code in read-only mode, has the model critique itself.
• security-reviewer — static heuristic: hardcoded passwords, weak crypto, SQL injection patterns, …
• architecture-reviewer — checks layer and module boundaries against the artifacts.
• hallucination-reviewer — looks for invented methods, packages or API calls.
• dependency-scan — Trivy scan for CVEs and licence violations in dependencies.

Per reviewer you see findings with severity (LOW / MEDIUM / HIGH / CRITICAL) and a confidence score. The aggregated verdict is one of:

How the quality gate acts is set by the mode (Leitplanken page, /leitplanken: level Ausgewogen = advisory, Vorsichtig = blocking; in expert view as an individual value; overridable via policy-as-code):

• off: the quality gate doesn't run at all; the run counts as done on a green build alone.
• advisory (default): the reviewers run and report findings but block nothing — a FAILED verdict is just a hint. Good to start with.
• blocking: a FAILED or ERROR verdict produces feedback and starts the correction loop; delivery only happens after the gate passes.

The policy sets the strictness: lenient (default) blocks only CRITICAL, strict blocks HIGH and CRITICAL and requires security and architecture review. Regardless of that, SECURITY/HIGH, SECURITY/CRITICAL and ARCHITECTURE/CRITICAL are always blocking. Reviewer crashes appear as ERROR — they are not silently swallowed; a missing reviewer CLI yields SKIPPED.

Typical findings on a first run:

• "Hardcoded password in application.yml" — the agent baked in a default Postgres password. Fix: reference a property like ${POSTGRES_PASSWORD}.
• "Missing test coverage" — the smoke test only covers context loading. Fix: a follow-up run with the goal "write tests".

10. Deliver – push + pull request or local merge

Once the build is green (and, in mode blocking, the quality gate too), the factory delivers the result automatically. What happens depends on whether you've configured a Git remote together with a GitHub token.

Variant A: with Git remote + GitHub token → pull request

1. Under /integrations, on the GitHub card, store a personal access token (scope repo) and on the project page set the Git remote (push & PR) (e.g. git@github.com:your-user/phonebook-api.git; the host must be listed in SOFTWAREFABRIK_GIT_ALLOWED_HOSTS, default github.com).
2. The next successful build run pushes its branch sdlc/run-<id8> to the remote and opens a pull request against the base branch — no extra click.
3. You review the PR on GitHub like any other and merge it there.

Variant B: without a remote → local merge

Without a remote or token the platform falls back to a local merge: the branch sdlc/run-<id8> is merged into main inside the persistent workspace. The result is then available locally, and you can push it yourself later (see step 13).

11. Learn – project memory

The project memory holds decisions, conventions and learnings. You curate it in the project under "Memory"; if an agent updates the MEMORY.md file in the workspace, the factory ingests it back after the run.

Before every run the platform mirrors the memory into the workspace as MEMORY.md, and the run brief names the file explicitly. That way the agent doesn't repeat the same mistakes, sticks to once-chosen patterns (e.g. "passwords always as env vars, never hardcoded") and builds on what's already there instead of starting from scratch.

12. Continue – auto follow-up proposals close the loop

One mega-run that does everything in one go rarely works in practice. Much better: small, focused follow-up runs. That's what the auto follow-up proposals are for (Einrichtung → Einstellungen, under „Erweitert“ (advanced) → Läufe → „Auto-Folgevorschläge nach Build-Lauf“, off by default): after every successful build run the factory automatically starts a plan run that puts the next steps into the backlog as plans/*.md. Possible proposals:

1. Proposal: "Write unit tests for PersonRepository and PersonController, cover all CRUD operations. Target: ≥ 85 % line coverage."
2. Proposal: "Fix the 'Hardcoded password' quality-gate finding and replace the value with an env var reference in application.yml."
3. Proposal: "Extend README.md with a 'Deployment' section including a docker-compose example, and an 'API examples' section with curl calls per endpoint."

The proposals appear in the backlog (status PROPOSED) — and you're back at step 4 (Select). That closes the loop: plan → select → build → correct → check → deliver → learn → continue. Each pass uses the same persistent workspace and the grown project memory.

13. Inspect & export the workspace

The workspace belongs to the project and lives at ./workspaces/<project-slug>/workspace/ (or under the workspace root configured in settings). Switch into it and look at what the agent built:

cd ./workspaces/<project-slug>/workspace
ls -la
git branch -a
git log --oneline -20
git diff HEAD~5 HEAD

You can keep working from here — make your own commits, push to a remote, branch, merge. The platform leaves the workspace alone unless you start another run.

If you merged locally in step 10 (variant B), you can export the result by hand at any time:

# push into a fresh GitHub repo:
cd ./workspaces/<project-slug>/workspace
git remote add origin git@github.com:your-user/phonebook-api.git
git push -u origin main

Tips for good prompts and run goals

• Concrete beats generic. "CRUD for Person" is weak. "GET /persons (list), GET /persons/{id} (detail), POST /persons (create with body {name, phone}), PUT /persons/{id}, DELETE /persons/{id}" is strong.
• State the definition of done. "Build must be green", "Tests must reach ≥ 85 % line and ≥ 81 % branch coverage", "README must contain API examples". That's what makes the quality gate meaningful.
• Provide example data. If the agent should write a migration, hand a sample: "Sample person: Max Mustermann, +49 30 12345678, max@example.org". Prevents generic Lorem-Ipsum data.
• Say what NOT to do too. "Use no external libraries beyond Spring Boot starters" stops the agent from pulling in some exotic lib you'd then have to maintain.
• Think iteratively. Three runs of 10 minutes each beat one run of 30 minutes. You can correct in between.

When things go wrong – debug strategies

What you can do now & next steps

• Structure a project, describe it and send it into a run.
• Produce a backlog with a plan run and activate items.
• Run build runs on their own branch and watch them live.
• Inspect what the agent changed before approval.
• Use self-correction on a red build and apply the quality gate (off/advisory/blocking).
• Deliver results via pull request or local merge.
• Close the loop from project memory and auto follow-up proposals.

Next steps: Glossary and help for glossary and mental model, Architecture for the substructure, Pricing for tiers and limits, or the FAQ for typical pitfalls.