Frequently asked questions.

What is the Agentic Software Factory?

A local web application that lets you kick off, supervise and trace AI-assisted development in a structured way. It connects project capture (with or without the wizard), automatic generation of Markdown specifications, run orchestration against coding CLIs (Claude Code, Codex, Gemini, Aider), live logs, Git discipline and an automatic quality gate. The goal is not „magic AI coding with one click“ — it's reproducible, reviewed results you can hand to your team.

What has changed since v0.4.0?

Eight releases have taken the platform from „MVP with two wizard templates“ to a fully orchestrated solo-dev tool:

• v0.4.0 — settings + wizard. /einstellungen with override order PROJECT > USER > GLOBAL > YAML + 5-min TTL cache; four-step wizard with two templates and version cache.
• v0.5.0 — polyglot. Four more wizard templates: .NET Backend, Python FastAPI, Node Express, plus the later Existing-Repo-Import. Six templates total.
• v0.6.0 — conductor. Per-role model routing (preferredModel passed as --model flag); plugins/skills sync; repo-import wizard and PROJECT_NOTES.md.
• v0.7.0 — hardening. Container-per-run sandbox (Docker/Podman with --cpus 2 --memory 4g --pids-limit 512 --read-only --network=none) switchable via setting; run templates saved from successful runs; live token stream via line-by-line NDJSON parser.
• v0.8.0 — UX peak. Cost estimate in wizard step 4 (local via JTokkit); inline diff of workspace changes before approval; browser notifications on run completion.
• v0.8.1 — wizard polish. Progress stepper, objective preview, server-side required-field validation, version-cache empty state.
• v0.9.0 — Claude subscription auth & observability. Coding runs optionally via your Claude Max/Pro subscription instead of an API key; Prometheus metrics (observability level 1) at /actuator/prometheus.
• v0.9.1 — hardening & quality. Higher test coverage (issuer security test, testable CSV escaping; branch coverage 0.815 against a ≥0.80 gate), extended ArchUnit rules (hexagonal ports-and-adapters + a freeze ratchet against module cycles and web→repository), and docs/DRY cleanup.
• v0.10.0 — Windows-native single seat & boot hardening. Claude plan mode runs natively on Windows (OS-aware env allowlist + claude.cmd default, verified end-to-end); boot crash in non-demo profiles and the /teams/{id} 500 fixed; boot smoke as a mandatory CI gate; community lease raised to 30 days with refresh on start.
• v0.11.0 — stack wizard & Codex plan. Project wizard combines target platform × backend × frontend(s) (17 templates, 12 frontends, multi-target, migration V16); OpenAI Codex runs on the ChatGPT plan instead of OPENAI_API_KEY (mirrors the Claude plan, switchable in the UI).
• v0.12.0 — Quarkus & user manual. Quarkus as a backend stack in the wizard (next to Spring Boot); a comprehensive user manual (EN+DE) for the single seat; proper umlauts in the German UI and clean cache headers.
• v0.13.0 — iterative SDLC. Project-persistent workspace + re-run (development on existing code), real repo import, project memory (learnings), and roadmap/plans as a backlog (plan run creates plans/*.md, activation starts a build run).
• v0.14.0 — branch/PR & SDLC maturity. Branch isolation per build run with optional push + pull request (GitHub), automatic correction feedback loop, quality gate in the pipeline (off/advisory/blocking) and auto follow-up proposals; wizard with .NET 10.

The news page has the full release notes.

What's the main difference vs. Claude Code in the shell?

With direct shell use you have to organise project definition, guardrails, approvals, Git discipline and status oversight manually. The Software Factory makes those aspects visible and reusable — you don't kick off one coding pass, you orchestrate a sequence of plan, implement, review and validate, with live logs and a quality-gate verdict at the end. It's not a different coding mode, it's a different abstraction layer.

Who is the platform for?

Primarily for software architects, lead developers, technical project managers and small teams who want to do AI-assisted development in a more controlled, reproducible way — typically in mid-sized companies, regulated industries, or consultancies that have to document code outcomes. It's not meant as a mass consumer product and isn't aimed at hobbyists who want to generate a quick script — Claude Code on its own is faster for that.

What problems does the platform solve?

• Too few or unstructured commits during AI-assisted coding.
• Lack of transparency around logs, status and approvals.
• Inconsistent project definitions across teams.
• Hard to reuse good project setups (start from scratch every time).
• High manual effort orchestrating multiple coding CLIs.
• Missing automated quality assessment of AI-generated output.

What agent roles are envisaged?

Seven roles: Architect, Developer, Reviewer, QA, Security Reviewer, Documentation and Merge/Release. Each role can have a preferredModel — an Architect might use claude-opus-4-8 for deep design decisions, a Reviewer the faster claude-haiku-4-5. Roles are serialised as Markdown into AGENTS.md and read by the coding agent as context.

What's a typical workflow?

1. Capture the project idea (wizard or quick create).
2. Fill in project fields or take what the wizard pre-filled.
3. Generate Markdown artifacts and read them once.
4. Verify the team composition (or accept the default).
5. Create a run with a clear goal, move to READY, start.
6. Follow logs, phases and Git diff, click approvals.
7. After COMPLETED, run the quality gate, review findings.
8. If needed, set up a follow-up run with a corrective goal.

Why work with Markdown artifacts?

Files like PROJECT.md or INSTRUCTIONS.md are human-readable, versionable and friendly to AI tools. They form the „working contract“ between user, platform and agent. The agent reads them as a top-level brief, you can edit them and trace changes in Git history. Unlike binary configurations or DB columns, Markdown is also useful outside our platform — you never get locked into a proprietary format.

Why Spring Boot + Thymeleaf instead of Angular/React?

Version 1 prioritises orchestration, run model, Git/build integration and traceability. A server-rendered UI with Spring Boot and Thymeleaf reduces complexity — no separate frontend build, no API versioning, no double authentication. That makes the product core trustworthy faster. A SPA version is on the backlog (ADR-0015 under discussion), but only after the core is stable.

Is the platform a real multi-agent system?

Not in the sense of „multiple agents running in parallel and talking to each other“. v1 prepares roles, teams and workflow structure for that, but starts with one executing adapter per run. The goal is a clean extension path, not maximum complexity in step one. True multi-agent (different models per phase, mutual review) is on the roadmap from phase 5/6 onwards.

How do I install the platform locally?

Three paths: (1) Docker Compose with the included docker-compose.yml; (2) Spring Boot JAR directly plus your own Postgres; (3) Air-gap delivery on request. See Quickstart for click-by-click guidance.

What are the prerequisites?

• Docker (24+) and Docker Compose v2.
• Free port 8080 (web) and 5432 (Postgres, bound to localhost).
• ~5 GB disk space for container images, build cache and first workspaces.
• A .env file with bootstrap admin credentials and master key.

You don't need to install Java, Maven or Node locally as long as you stay in container mode. Only when you use real vendor adapters such as claudecode or codex do you need that CLI locally.

How do I start the platform?

From the unlocked distribution bundle (no public repo — access on request):

tar xzf softwarefabrik-einzelplatz.tar.gz
cd softwarefabrik
# create .env with ADMIN_USER, ADMIN_PASSWORD, DB_PASSWORD, SECRETS_MASTER_KEY
docker compose up -d

Generate the master key with openssl rand -base64 32 (at least 32 bytes). Details in the quickstart.

Which Java version?

Java 25 (LTS). Spring Boot 4.0.7. If you run the JAR directly you need a matching JDK.

What about Postgres?

PostgreSQL 18 as the single-tenant DB (pinned to postgres:18.3-alpine in docker-compose.yml). Schema migrations via Flyway, currently up to V32. In the test profile H2 runs with Postgres compatibility mode.

Do I need API keys?

For the local demo the mock adapter is enough — no keys. For real vendor calls: Anthropic / OpenAI / Gemini keys are persisted encrypted in the /integrations view (AES-GCM, master key from SOFTWAREFABRIK_SECRETS_MASTER_KEY).

Does the platform work offline?

Depends on the tier:

• Community and Professional: usable up to 30 days offline (grace period after lease expiry). After that the 24-hour emergency grace can be activated once with one click.
• Enterprise Self-Hosted: up to 90 days offline. The license server typically lives on the internal network anyway.
• Enterprise Air-Gap: fully offline. Renewal once a year via a signed certificate file (USB stick or controlled file transfer).

Can it be run air-gapped?

Yes, with an Enterprise Air-Gap license. The platform itself has no hard internet dependency. What you need:

• A fully offline-verifiable license certificate (Ed25519-signed, 365 days).
• Annual renewal via USB stick or file transfer.
• The LLM must be on-prem (e.g. Ollama with Qwen 3 Coder, DeepSeek V3.2). Vendor cloud adapters aren't possible in air-gap mode.
• Version cache must be seeded in internet mode — alternatively the code-level fallback versions kick in.

What data is sent to external servers?

In the default setup only:

• To the license server: license ID (UUID), device fingerprint hash (SHA-256), email hash, client version, ISO country of the IP.
• To the version lookup (Maven Central, GitHub, npm): just unauthenticated HTTP GETs.
• To the configured LLM vendor: your prompt + workspace contents. Depends on the vendor.

In air-gap mode: nothing. Details in the transparency document.

How does the wizard work internally?

The wizard is a four-step controller at /wizard with its own persistence in wizard_draft (V12). Steps:

1. Pick a template: you choose between spring-boot-backend and static-frontend. The template determines the questions in step 2.
2. Questions: per template a fixed set of questions (Java version, DB, architecture style, Node version, build tool, …). Answers are stored in a JSON column.
3. Quality-gate toggles: ArchUnit, OWASP, Trivy, Playwright. Which ones appear depends on the template (e.g. ArchUnit only for backends).
4. Summary: overview of all answers, then „Create project“. On completion the wizard creates a ProjectDefinition, fills all editor fields, sets the draft status to completed.

Drafts survive browser reload and server restart. The next visit to /wizard shows a „Resume draft“ button that takes you to the last saved step. Unfinished drafts are auto-deleted after 30 days (cleanup job at 04:00).

How many templates exist?

Six: spring-boot-backend, static-frontend, dotnet-backend, python-fastapi, node-express, existing-repo-import.

Which templates exist in detail?

Snippets sit on the classpath under resources/wizard/templates/<name>/ and exist in DE and EN (you choose the language in wizard step 2).

How do version values reach the wizard?

From the version_cache (V13). A daily @Scheduled job at 03:00 fetches current stable versions from three sources:

• Maven Central for Spring Boot, ArchUnit, OWASP Dependency-Check.
• GitHub Releases for the Trivy CLI.
• npm registry for Playwright.

Cache keys are functional, not technical: spring-boot.3.x, archunit.latest, trivy.cli.latest, … If the cache is empty or stale, the wizard falls back to hard-coded versions from the source.

What happens if the version cache is stale?

„Stale“ means: Java-computed, the last refresh is more than 25 hours old. The wizard still shows the values (with a stale badge in the admin UI), and you can hit „Refresh now“ at /einstellungen/wizard/versions to trigger a synchronous lookup. If the lookup job has failed multiple times, the last error is shown in the last_error column.

What happens in step 4 of the wizard?

Summary with objective preview (collapsible, shows the final initial prompt for the agent) and cost estimate (local via JTokkit, no LLM call, default model claude-sonnet-5).

How do I disable the wizard and only use „Quick create“?

You don't need to disable it — the „Quick create“ button stays on the project list and opens a two-field form (project title, product name). You go straight to the editor and fill the rest yourself.

If you want to hide the wizard completely (e.g. because your team only uses quick create), there's a toggle in settings under UI for „Wizard menu entry“. The route stays technically reachable — we only hide it from navigation.

Can templates be extended?

In code: a new entry in TemplateRegistry (immutable record with fields and supported toggle IDs) plus snippets under resources/wizard/snippets/<lang>/<toggleId>.md and base prompt under resources/wizard/prompts/<lang>/<templateId>/basis.md. Six templates are registered today. UI-based template management (custom templates via drag-and-drop) stays a V2 topic.

Which adapters are there?

Which default models does the platform use per role?

Each agent role has a default model (ModelCatalog):

• Architect & Documentation: claude-opus-4-8 — for deep design and documentation decisions.
• Developer, QA & Merge/Release: claude-sonnet-5 — balanced for implementation.
• Reviewer & Security Reviewer: claude-haiku-4-5 — fast and cheap for read-only checks.

There's also a per-adapter default model under /einstellungen → Adapter (e.g. execution.model.codex → gpt-5, execution.model.gemini → gemini-2.5-pro). These defaults apply to all new runs unless the user explicitly picks another model in the run-creation dialog.

How does per-role model routing work?

Every AgentDefinition has a nullable preferredModel field (V11). The Claude Code adapter appends it as a --model flag. Unknown IDs fall back to the CLI default. Drift detection emits a warning event when the model used differs from the requested one.

What is the mock adapter for?

The mock adapter is a test adapter that works without an API key and writes deterministic pseudo tokens into the workspace. Ideal for:

• First platform tests: quickstart, onboarding without vendor cost.
• CI pipelines: when you want to test the platform mechanics, not the LLM.
• Bug reproduction: if a run shows weird logs, you can replay it with mock without burning real tokens.

Output is not „real code“ — more like pseudo content that simulates a typical run flow.

Can I pick a different adapter per run?

Yes. The run-creation page has an „Adapter“ dropdown. If you pick something there, it overrides the global default (override order: RUN > PROJECT > USER > GLOBAL > YAML). Useful for A/B comparisons: same brief, once with Claude, once with Codex, then compare results.

What does the quality gate do?

The quality gate is an automatic assessment of the run output. It calls multiple reviewers, collects their findings and produces an aggregated verdict (PASSED / WARNING / FAILED / SKIPPED / ERROR). Reviewers are read-only — they don't write into the workspace, they only inspect.

Which reviewers are built in?

• aider-review — invokes the Aider CLI in read-only mode, looks for code smells and improvements.
• claude-review — invokes Claude Code in read-only mode and has the model critique its own output.
• security — static heuristic engine: scans for hardcoded passwords, weak crypto, SQL injection patterns, missing input validation, …
• architecture-reviewer — compares code against the architecture spec in PROJECT.md + WORKFLOW.md. Detects layer violations and bad dependencies.
• hallucination-review — looks for invented method calls, non-existent packages, or made-up API signatures.

What do the verdicts mean?

• PASSED — no findings, all reviewers green.
• WARNING — some findings below the blocking threshold.
• FAILED — at least one blocking finding (by policy or special rule).
• SKIPPED — quality gate was not run (e.g. because the run was cancelled).
• ERROR — a reviewer crashed (e.g. its CLI is missing). Deliberately not swallowed.

Each reviewer returns findings with severity (LOW/MEDIUM/HIGH/CRITICAL) and confidence (0..1), from which the overall verdict is aggregated.

What are the special rules?

Two finding types are always blocking, regardless of policy:

• SECURITY/HIGH — e.g. hardcoded secrets in committed code, weak crypto algorithms, obvious SQL injection.
• ARCHITECTURE/CRITICAL — e.g. a domain class importing Spring, web layer reaching directly into infrastructure.

This rule prevents an overly relaxed policy from quietly waving through critical issues.

What's the difference between strict and lenient policy?

• strict (default): every WARNING blocks subsequent phases. Good for production setups.
• lenient: WARNING is shown but doesn't block. Good for first tutorial runs and experimental projects.

Special rules (SECURITY/HIGH, ARCHITECTURE/CRITICAL) are blocking either way.

What can I configure in the settings area?

Under /einstellungen (ADMIN-only) you can configure:

• Workspace: default root path for run workspaces.
• Git: user name and email for auto-commits.
• Adapter: default adapter and default model per adapter.
• Budget: daily and weekly token caps, soft threshold.
• Wizard: version cache overview and manual refresh.
• Quality gate: policy strict / lenient, reviewer activation.

What is the override order?

PROJECT > USER > GLOBAL > YAML. A project-level value beats a user-level value beats a global value beats the default in application.yml. SettingService implements this resolution uniformly for all settings.

How does the token budget work?

You set a daily token cap (e.g. 2,000,000) and/or a weekly token cap. Per run, used tokens (input + output) are summed. Two modes:

• Soft threshold (default 80 %): on breach the UI shows a warning banner. New runs remain possible.
• Hard limit at 100 %: new run creation is blocked with the message „daily budget reached“. Running runs are not aborted — they finish.

Reset at midnight (local time) for daily, Sunday 00:00 for weekly.

When do settings changes take effect?

At most 5 minutes after saving, because SettingService uses a 5-minute TTL cache. That's an intentional trade-off: fewer DB hits per resolve, slight delay in return. To see changes immediately, click „Invalidate cache now“ on the settings page.

Who can change settings?

Only users with the ADMIN role. Primarily the bootstrap admin (SOFTWAREFABRIK_ADMIN_USER); you can create more admins under /admin/users. Every change creates an audit log entry with subject (who), key, old value, new value, timestamp.

How does the platform handle security and privacy?

The platform aims for data-minimal, traceable use:

• No secrets in source, no plaintext password in logs.
• API keys AES-GCM-encrypted in Postgres (master key from env var).
• Passwords BCrypt-hashed at cost 12.
• Audit log for all security-relevant events.
• Approval policies before critical phases.
• docker-compose Postgres mapping pinned to 127.0.0.1 — not accidentally exposed.
• pgJDBC 42.7.11 with the CVE-2026-42198 fix.

How is the agent isolated?

Two modes: LocalProcessSandbox (default) starts the agent in the same container as the platform, with filtered env vars, workspace as working directory. ContainerProcessSandbox (setting execution.sandbox.variant=container) starts each run in an ephemeral Docker or Podman container with --cpus 2 --memory 4g --pids-limit 512 --read-only --network=none.

Where are API keys stored?

In Postgres, encrypted with AES-GCM. Master key from SOFTWAREFABRIK_SECRETS_MASTER_KEY (at least 32 bytes Base64). Without the master key the platform refuses to start. Audit log records every key change.

How is a user authenticated?

In v1: local authentication with username + password against the platform DB. BCrypt-hashed passwords, CSRF protection, session cookies (HttpOnly, Secure, SameSite=Lax). For the Enterprise tier, additional Keycloak OIDC with the device authorization grant — one-time browser login, then the app keeps an encrypted refresh token locally.

What goes into the audit log?

• Login attempts (successful + failed, with user subject and IP country).
• Settings changes (key, old value, new value, subject, timestamp).
• Run starts (run ID, adapter, model, subject).
• Approval decisions (phase, decision, subject).
• Adapter configuration changes (integration setup with encrypted API key).

Append-only — nothing is deleted or edited. Table audit_event.

Is the platform suitable for regulated environments?

It's well aligned — traceability, structure, documentation, Git discipline and explicit approvals are built in. Concrete hardening (e.g. ISO-27001, BAIT, DORA conformance) depends on the deployment environment and needs additional organisational measures. For government we recommend the air-gap tier with on-prem LLM.

Which license tiers exist?

Three tiers — Community, Professional and Enterprise:

• COMMUNITY (free, no registration): 10 runs/day, 3 parallel agents, 3 devices. No team, no SSO, no audit log. Good for trying things out.
• PROFESSIONAL (20–30 €/month per user): 100 runs/day, 10 agents, 5 devices, priority support. No team/SSO/audit.
• ENTERPRISE (from 20,000 €/year): 1000 runs/day, 50 agents, devices per contract, team + SSO + audit log + priority support.

Details: License model. The public demo instance needs no license — „Demo“ is not a tier.

How much does the platform cost?

Community is free. Professional costs 20–30 €/month per user, Enterprise starts at 20,000 €/year (Self-Hosted and Air-Gap as individual contracts). What costs extra are vendor API costs (Anthropic, OpenAI, Google) for actual coding calls — the platform only acts as a broker there.

How does the license work technically?

EdDSA/Ed25519-signed JWT lease tokens from the license service. The platform verifies offline against the public key (https://license.softwarefabrik.io/api/v1/pubkey). Tier features are coded in the lease claim. Setup & trust chain in the transparency document.

Which LLMs are supported?

• Anthropic Claude (official API; the cloud gateways AWS Bedrock and Google Vertex AI are experimental — implemented but not yet live end-to-end tested; production use only after customer-side verification).
• OpenAI (official API; Azure OpenAI is experimental — implemented but not yet live end-to-end tested; production use only after customer-side verification).
• Google Gemini (Vertex AI is experimental — implemented but not yet live end-to-end tested; production use only after customer-side verification).
• On-prem via Ollama or vLLM: Qwen 3 Coder, DeepSeek V3.2, GLM-5.1, others.

LLM choice is the customer's call and configured in the adapter. Air-gap mode allows on-prem LLMs only. A consolidated list of open items is available under Known Limitations.

Can I switch between tiers?

• Community → Professional: any time via account upgrade.
• Professional → Enterprise: via contact, individual migration including contractual alignment.
• Enterprise deployment switch (e.g. cloud → self-hosted): part of the contract, applied with a new license file.

What are the Community tier limits?

• 10 successful runs per day (reset at 00:00 local time).
• 3 parallel agents per run.
• No team features, no SSO, no audit log, no support SLA.
• Failed, cancelled or timed-out runs don't count.

How does it differ from LangChain / LangGraph / AutoGPT?

LangChain and LangGraph are library frameworks for Python developers building AI workflows themselves. AutoGPT is an experimental auto-run agent that decomposes tasks largely autonomously. The Software Factory is not a library — it's a finished web application with a defined workflow (project → artifacts → run → quality gate). You don't program it, you use it. The audience is therefore much broader: not only Python devs with an AI background, but every lead developer.

When does multi-agent execution arrive?

Roadmap phase 5/6 (summer/autumn 2026). Concretely: a different agent per phase (Plan = Architect / Implement = Developer / Review = Reviewer), with role-specific models. The DB schema prep is already in place via V11 (agent_preferred_model) — only the orchestration logic is missing.

Can external plugins / adapters be loaded?

In v1: no. Adapters are added as Java classes in the codebase. A plugin API (e.g. via Java Service Provider Interface or Spring Boot Starter mechanism) is on the backlog (ADR-0014). We deliberately defer it because a stable plugin API design is only worth designing once the adapter logic has iterated a few times.

Is there a roadmap?

Yes, in the distribution at docs/roadmap/reifegrad-roadmap.md. The tenant foundations (project-boundary isolation, RBAC, SSO) are already in place; full audit-grade multi-tenancy (separate policy/audit/reports per tenant), an external plugin API and an SPA frontend are planned for the horizon — until then, one instance per tenant is recommended. The news page keeps the current status, and the Known Limitations page collects open constraints.

Is there deeper technical background available?

Yes. As an architecture deep-dive there's a separate whitepaper covering the architectural foundations of agentic software development: reference architecture, agent orchestration, AI guardrails, shared knowledge stores and integration into the SDLC. The PDF is free and downloadable without registration.

What's the best way to get started?

The quickstart (10 minutes, mock adapter, no API cost). Once that runs: tutorial with the real Claude Code adapter (45 minutes). If you'd rather just click around without installing: live demo.