The mental model
The platform thinks in five layers. Once you grasp them, you'll find your way around in the UI immediately:
- Project — idea, goal and requirements, as a draft, then as Markdown artifacts.
- Artifacts —
PROJECT.md,INSTRUCTIONS.md,AGENTS.md,WORKFLOW.md,DEFINITION_OF_DONE.md,README.mdas the agent's working basis. - Team — collection of agent roles with guardrails and model assignment.
- Run — concrete execution with status, phases, logs, token usage and cost.
- Quality Gate — automatic evaluation of the result by multiple reviewers.
Terms in the factory
What things are called in the interface; the German UI label is in brackets.
- Project (Projekt)
- What is to be built or improved — with description, project folder and all runs.
- Run (Lauf)
- A task for the AI agent: it works in the project folder, builds and checks the result. A run has steps (phases) and ends completed, failed or cancelled.
- Task (Auftrag)
- What the run should do, in your own words — e.g. “The high score should survive a restart.”
- Build (Bauen)
- Creates the run and starts it right away.
- AI agent (KI-Agent, adapter)
- The program that does the actual work, e.g. Claude Code or Codex. It signs in with a subscription or an API key.
- Subscription / API key (Abo / API-Schlüssel)
- Subscription: you sign in to the AI application once and pay monthly. API key: billed by usage. How to set up either is described under Set up real runs.
- Project folder (Projektordner, workspace)
- The folder on the machine the factory runs on. The result lives there; you can also download it as a ZIP.
- Approval (Freigabe)
- A human confirms before things continue — depending on the setting before execution, before the merge or never.
- Quality check (Qualitätsprüfung, quality gate)
- Checks the result after building (tests, security, dependencies): advisory or blocking.
- Build check (Build-Prüfung, build gate)
- Builds and tests the project. “Nicht geprüft” (not checked) means the factory found no build — not an error, but no confirmation either.
- Trial run (Probelauf)
- Builds a freshly imported project once without an agent, so you know where it stood before.
- Guardrails (Leitplanken)
- How cautiously the factory works: Vorsichtig (cautious), Ausgewogen (balanced) or Schnell (fast) — or set individually.
- Simple / expert (Einfach / Experte)
- How much the interface shows. What you may do is decided by your role, not by the view.
- Role (Rolle)
- Viewer, developer, maintainer, owner, administrator — from “view only” to “set up everything”.
- Tenant (Mandant)
- In team operation a separated area, e.g. a department: projects and costs stay apart.
- Attestation (Attestierung)
- Every important action is recorded in a signed, gap-free chain — it cannot be changed later without being noticed.
- Policy-as-code
- Signed, versioned rules for the whole factory, e.g. which AI agents are allowed. Stronger than the settings in the interface.
Terms on the website and in the docs
You will mostly meet these words on the pages about architecture, pricing and operations.
- Control plane
- The steering layer: the factory is a local web application that creates, starts, monitors and records runs. The AI agent does the actual work on the code; the factory gives it the frame, checks the result and records what happened.
- Lease
- A time-limited, signed confirmation of the license that the factory fetches from the license server and renews regularly. While the lease is valid, the factory needs no contact with the license server. Durations per tier: see Pricing.
- Grace period
- Courtesy time after the lease expires, e.g. when the license server was unreachable: runs keep starting. After that a short emergency grace can be activated; once that has expired too, no new run with a real AI agent starts until the license is renewed; runs with the mock remain possible. Duration: see Pricing.
- JWT
- JSON Web Token — a signed, machine-readable data package. License and lease are JWTs with an Ed25519 signature; the factory verifies them offline against the embedded public key.
- Conductor
- The part of the factory that writes the configuration for the agent CLI into the project folder before every run, for Claude Code e.g.
.claude/settings.local.jsonand.claude/agents/<role>.md. - SSE
- Server-Sent Events — how a run’s logs reach the browser live. If the connection drops, the browser reconnects after 5 seconds; a heartbeat every 20 seconds keeps it open behind proxies.
- Capability routing
- The factory picks the model per kind of run: plan and spec runs use the Architect's model, build runs the Developer's (with Claude Code e.g. a strong model for planning and a faster one for building).
More terms from A to Z
Technical terms from the manual, tutorial and academy — one line each.
| Term | Meaning |
|---|---|
| Adapter | Backend component that drives a concrete agent — coding CLIs (Claude Code, Codex, Gemini, Kimi, Aider), local model, cloud gateways (Bedrock, Vertex, Azure OpenAI) or mock. |
| Agent / agent role | Logical role like Architect, Developer, Reviewer. Described in AGENTS.md and read by the coding agent as context. |
| Approval | Manual gate in a run — before execution or before the merge, depending on the guardrails. Prevents critical steps from running without confirmation. |
| Artifacts | The six Markdown files (PROJECT.md …) the agent reads as specification. |
| Auto follow-up proposals | Optional feature: a successful build run automatically triggers the next plan run, so the SDLC loop keeps turning on its own. |
| Backlog | List of proposals produced by the plan run (plans/*.md). The next step to implement is activated from the backlog. |
| Bootstrap admin | The initial admin account created at first start from SOFTWAREFABRIK_ADMIN_USER/PASSWORD. |
| Budget | Monthly budget in EUR per project (Analytics → Budget). The alert threshold warns; with enforcement on it blocks new runs when exceeded; plus an optional hard cap per tenant. |
| Build container | Per-project frame for the build gate and the trial run: own image, CPUs, memory, time limit (since v0.45.0, MAINTAINER and above). The operator restricts the images and the upper limits. |
| Build gate / NICHT_GEPRUEFT | The VALIDATION phase: the factory builds and tests the project itself, according to the project profile. If it detects no build or a tool is missing, the result is NICHT_GEPRUEFT (not checked) — this never counts as passed; the run then needs an approval before the merge. |
| Draft | Status of a project or wizard draft: not final, still editable, not yet in use. |
| Mock adapter | Test adapter that works without an API key. Simulates the run with deterministic pseudo tokens but writes no code (in plan mode only a sample plan). Ideal for learning. |
| Phase | Section of a run. Seven in fixed order: INTAKE, PROMPT_ASSEMBLY, WORKSPACE_PREPARATION, EXECUTION, VALIDATION, CORRECTION, COMPLETION. Visible in the run detail. |
| Plan run | Run type that doesn't build but produces proposals for the next steps as plans/*.md — the source of the backlog. |
| Build run | Run type that actually implements a selected backlog proposal on its own branch (sdlc/run-…). |
| Policy | Rules for runs: in the interface they are called guardrails (Leitplanken: level, approvals, quality-gate mode, sandbox, costs); as policy-as-code they apply signed to the whole factory and take precedence over the guardrails. |
| Project memory | Project-bound store of decisions and learnings that flows into every follow-up run, enabling continuous, iterative development. |
| Project profile | A stack described as data: how the factory recognises it, how the build gate builds and tests it and which commands the agent may run for it. Level A (checked): Maven, .NET; level B (usable): Gradle, Python, Node.js, Go, Rust, CMake. |
| Pull request | GitHub PR opened automatically for the run branch on delivery (with a remote + token set). Without a remote/token: a local merge into the base branch. |
| Self-correction | Automatic feedback loop: a failed build is retried with the build feedback on the same branch (limited attempts, NEEDS_CORRECTION → RUNNING). |
| Quality gate | Aggregated verdict over multiple reviewer findings: PASSED / WARNING / FAILED / SKIPPED / ERROR. |
| Reviewer | Read-only component that inspects a run output (CLI-based or static heuristic). Six reviewers are available (claude-review, aider-review, security-reviewer, architecture-reviewer, hallucination-reviewer, dependency-scan); with a bound, approved spec, spec-conformance runs in addition. |
| Run | UI „Lauf“. Concrete execution of a coding agent against a project. Has status, phases, logs, token usage and a Git workspace. |
| Settings | Global platform configuration at /einstellungen: adapters, AI access, operating mode, workspace and Git author, models, costs, runs, feature switches. ADMIN-only. Quality gate and sandbox live under guardrails (Leitplanken). |
| Team | Bundle of agent roles assigned to a project, surfaced in the artifacts. |
| Toggle (quality gate) | In the wizard (step 5): switches for checking tools such as ArchUnit, OWASP Dependency-Check, Trivy, Playwright or, per stack, ESLint, Ruff, Bandit … Active toggles appear as sections in the generated initial prompt. |
| Version cache | DB table with daily-refreshed “latest stable” versions for Spring Boot, ArchUnit, Trivy, etc. Source for wizard pre-fill. |
| Tools (Werkzeuge) | Toolchains the factory installs itself (“Einrichtung → Werkzeuge”, ADMIN, since v0.45.0): JDK, Maven, .NET SDK, Node.js, Go, uv — without administrator rights, from the official source, with a checksum. The agent and the build gate share them. |
| Wizard | Project creation at /wizard: the quick start (/wizard/schnellstart; name, kind, description) or the six-step „Ausführlicher Assistent“ (detailed wizard). |
| Workspace | Persistent per-project directory with its own Git repo where the coding agent works; follow-up runs build on it. Defaults to ./workspaces/<project-slug>/workspace/. |
Common pitfalls
From the experience of early adopters — typical friction points and how to avoid them:
“There's no login button”
The platform starts with an empty database. If you haven't set a bootstrap admin, no account is created. Set SOFTWAREFABRIK_ADMIN_PASSWORD in .env and restart the factory (starter package: ./start.sh or .\start.ps1).
“My run is stuck in draft”
„Bauen“ (build) starts a run right away. It only stays in Entwurf (DRAFT) if it could not start — the run page then names the reason (rights, budget, policy) — or if you created it in expert view with „Nur anlegen“ (only create). Then click „Lauf starten“ (start run).
“Logs aren't showing up”
SSE connections sometimes get stuck behind reverse proxies or corporate firewalls. Check your DevTools console. The platform auto-reconnects after 5 s and sends a heartbeat every 20 s; if it still stays empty, the proxy has to pass SSE (text/event-stream) through unbuffered.
“My adapter fails”
Vendor adapters need an API key or a subscription login. The CLIs read keys from the environment of the factory process (e.g. ANTHROPIC_API_KEY); if a key is missing there, the factory injects the one stored at /integrations in API-key mode (Claude from 0.41.1, the other adapters from 0.41.2). The mock adapter never has this problem — use it for first tests. If a CLI isn't installed locally, the run log surfaces a clear error. The system check (Einrichtung → Werkzeuge & System) shows beforehand which agent programs are installed and whether a subscription login or key is present.
“I have a wizard draft that won't go away”
Drafts without completion stay in the DB. End them explicitly via “Discard wizard” on the summary page, or let the cleanup job remove them automatically after 30 days.
“The version cache is empty / stale”
On a fresh install the daily refresh hasn't run yet — you see the fallback values from code. Hit “Refresh now” at /einstellungen/wizard/versions to trigger a lookup immediately (needs internet).
“Quality gate says FAILED, but I see nothing”
Click on the quality-gate result in the run detail. You see findings per reviewer with confidence scores. SECURITY/HIGH and ARCHITECTURE/CRITICAL are always blocking — even with policy lenient.
“I'm burning too many tokens”
Set a monthly budget per project under Analytics → Budget. With enforcement on it blocks new runs at > 100 % usage; the alert threshold (default 80 %) just warns — sensible for the first few weeks.