This introduction walks you through the platform step by step — from your first login to a supervised development run. It is deliberately aimed at beginners and focuses on using the platform, not on deep architectural decisions. If you want to bootstrap your first project quickly, the project wizard gives you a four-step guided path with progress stepper, cost estimate and a preview of the initial prompt.
What is the Software Factory?
The Agentic Software Factory is a local web application that lets you kick off, supervise and trace AI-assisted development workflows in a structured way. You don't drive the Claude Code, Codex or Gemini CLIs directly from your shell — you work through a UI-centric control plane. That reduces friction and makes every run reproducible.
Think of the platform as a cockpit: you describe your project, pick your team of agent roles, set a goal — and the platform launches a run, collects logs, tokens and costs, and hands you back a reproducible workspace with Git history, build status and quality-gate result.
The platform thinks in five layers. Once you understand them, every screen makes sense:
ProjectIdea, vision and requirements — first as a draft, then as Markdown artifacts.
ArtifactsPROJECT.md, INSTRUCTIONS.md, AGENTS.md, ... — the working brief for the agent.
TeamA bundle of agent roles with guardrails and per-role model assignment.
RunA concrete execution with status, phases, logs, token usage and cost.
Quality gateAutomatic evaluation of the result through several reviewers.
Mantra: Good runs start with good artifacts — and good artifacts don't fall from the sky. Plan deliberately before hitting "start run".
Log in
After a local start (e.g. via docker compose up) the platform is reachable in your browser. You log in with an administrative account that the platform creates from configuration on first boot:
Important: Without an explicitly set password, the bootstrap admin is deliberately not created. Weak defaults would be a security bug because nobody would remember to change them.
If you just want to look around without installing locally, use the live demo at demo.softwarefabrik.io. You're auto-logged-in there as the demo user; the database resets daily at 04:00 so every visit starts fresh.
Understanding the dashboard
The dashboard is your command centre for projects, runs and status overviews:
KPIs at the top: total / draft / active projects, active runs, 14-day token usage and 14-day cost in EUR.
Charts: run activity, input/output token split and a EUR cost curve — entirely server-rendered SVG, no JavaScript needed.
Recent projects: jump back into existing work.
Recent runs: direct link to logs, Git status and phases.
In the header you'll always find the theme toggle (light / dark, persisted in localStorage) and the user popover with the logout button.
Creating a project — two paths
Since v0.4.0 there are two ways to start a new project. Pick the one that matches your experience:
Pick a template — currently Modern Spring Boot Backend or Static Frontend.
Answer questions — title, vision, language plus template-specific fields (Java version, database, architecture style).
Choose quality gates — ArchUnit, OWASP, Trivy or Playwright (depending on the template).
Review & confirm — done.
After the wizard you land in the regular project editor with all fields pre-filled.
⚡ Quick create (for experienced users)
The Quick create button on the project list opens a minimal two-field form (project title and product name). You go straight to the project editor and fill the rest yourself.
Recommended once you know the platform and don't need template pre-fill.
Tip: Even if you don't need the wizard, run through it once on day one — you'll see what the platform makes of your answers.
Filling in the project content
In the project editor you maintain the actual project content. These fields feed directly into the generated Markdown artifacts. The more precise you are here, the more reliable the run later:
Vision: 2–4 sentences. What should the result be?
Target audience: Who will use the software?
Technology preferences: Stack, versions, frameworks. Pre-filled when you used the wizard.
When is a run done? Build green, quality gate passed, ...
README.md
Reading entry-point for the agent inside the workspace.
Important: Read these files once before kicking off the first run. Typos or fuzzy phrasing get implemented very honestly by the agent — and you'll see them in the commits later.
Global settings (ADMIN)
Since v0.4.0 the bootstrap admin gets a dedicated area at /einstellungen. Values apply globally to all projects and runs of the instance, but can be overridden per project (override order: PROJECT > USER > GLOBAL > YAML):
Cache tip: Setting changes take effect within at most 5 minutes without restart — the SettingService uses a 5-minute TTL cache.
Agents and teams
The platform models classic roles: Architect, Developer, Reviewer, QA, Security Reviewer, Documentation and Merge/Release. You assemble a team per project from those roles. At run-start the team is handed to the coding agent (via AGENTS.md).
Per role you can configure a preferredModel — Architect gets claude-opus-4-7, Reviewer gets claude-haiku-4-5, and so on. The Claude Code adapter passes the model as a --model flag and falls back to the CLI default if the id is unknown (phase 5, shipped in v0.6.0).
Creating and starting a run
A run binds project, goal and team into a concrete execution. Fields:
Project: required. Pick from drafts or active projects.
Team: optional. Default is the project's team.
Run title: required. Short and meaningful, e.g. "Initial scaffolding for the BFF skeleton".
Goal: required. What should the run actually do? Be detailed — the agent reads this as a top-level instruction.
Adapter: only if you want a non-default one.
A new run starts in DRAFT. You move it to READY and then deliberately click Start run. Two confirmation points before tokens get burned — by design.
Quick start: Once you have one successful run, click "New run from last setup" on the run list. Three clicks, done.
Monitoring a run
While a run is active you mostly use three views:
Run detail
Status (RUNNING / PAUSED / WAITING_FOR_APPROVAL / COMPLETED / FAILED), current phase, token and cost figures. Pause / Resume / Cancel buttons.
Logs (live)
Server-Sent Events stream agent output to the browser. 20 s heartbeat, 5 s auto-reconnect, auto-scroll toggle.
Git view
Branch, commit list, working tree and diff. You see in real time what the agent writes into the workspace.
The quality gate
At the end of a run (or any time during it) you fire the quality gate. It calls multiple reviewers, aggregates their findings and produces a verdict:
PASSEDWARNINGFAILEDSKIPPEDERROR
Available reviewers:
aider-review / claude-review — invoke the matching CLI in read-only mode.
security — static heuristic for typical security smells.
architecture-reviewer — checks layer and module boundaries.
hallucination-review — looks for invented methods / packages.
Special rules (always blocking, regardless of policy): SECURITY/HIGH and ARCHITECTURE/CRITICAL. Reviewer crashes are surfaced as ERROR rather than swallowed.
Policies & approvals
Policies decide which run phases proceed automatically and where a manual approval is required. By default, low-risk phases run automatically; before execution and before completion the platform waits for an explicit user decision. That guarantees no run silently commits something heavy.
Tips for everyday use
Start with the mock adapter before plugging in a real vendor API key. Mock yields deterministic pseudo tokens, so you see the platform mechanics without paying.
Keep the run goal small. Three runs of "create skeleton", "write tests", "add docs" beat one mega run.
Fire the quality gate early, not just at the end. Findings accumulate otherwise.
Watch logs and Git view in the first minutes. If the agent goes off course, abort early instead of burning tokens.
Use the wizard as a learning tool: step 4 shows you what the platform makes of your answers — a good cheat sheet for the regular editor fields.
Important: You don't need ADRs for this introduction. Focus on wizard, artifacts, run, logs and quality gate first — the rest becomes obvious once a few runs have been through.
The first 30 minutes — guided walkthrough
Just logged in and not sure where to start? Here's a deliberately small-step sequence that delivers a first success in 30 minutes.
Minute 0–2: scan the dashboard. If everything is at zero, you're on a fresh instance. If there are values, it's a demo or someone else's prior instance.
Minute 2–10: walk through the wizard. Click "New project with assistant". Choose "Modern Spring Boot Backend". Answer the questions — pick example values everywhere; you can edit later. Toggle ArchUnit as the only quality gate. Finish.
Minute 10–15: explore the project editor. You land at /projects/<id>/edit. See what the platform did with your answers — especially technologyPreferences, architecturePreferences and nonfunctionalRequirements. Click "Generate Markdown artifacts".
Minute 15–18: read the artifacts. Open PROJECT.md, INSTRUCTIONS.md, AGENTS.md. You don't have to understand everything — but can you see how your wizard answers became a coherent brief?
Minute 18–25: create a run. Click "New run". Pick the project, give it a title ("create skeleton") and a goal ("Set up the initial Maven project with Spring Boot, a health endpoint and a first smoke test"). Pick the mock adapter — it costs nothing and you see the mechanics. Move to READY, then "Start run".
Minute 25–30: watch live. You land on the run detail page. Logs stream in. Watch the token counter, the phase updates, the Git status. When the run finishes (mock takes ~10 s), peek at the workspace diff.
Done! You've gone through the whole lifecycle once — project, artifacts, run, logs, diff. Now you can repeat the same with a real adapter (Claude / Codex / Gemini / Aider) — only then do you need an API key.
Glossary — every term in one line
Term
Meaning
Adapter
Backend component that talks to a concrete coding CLI (Claude Code, Codex, Gemini, Aider, 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 between run phases. Prevents critical steps from running without confirmation.
Artifacts
The six Markdown files (PROJECT.md ...) the agent reads as specification.
Bootstrap admin
The initial admin account created at first start from SOFTWAREFABRIK_ADMIN_USER/PASSWORD.
Budget
Token cap per day or week. Soft threshold warns, hard mode blocks new runs.
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. Writes deterministic pseudo content into the workspace. Ideal for learning.
Phase
Section of a run (e.g. Plan, Implement, Review, Merge). Visible in the run detail.
Policy
Rule set defining when a run continues automatically vs. where approval is required.
Read-only component that inspects a run output (CLI-based or static heuristic). Multiple reviewers per quality-gate run.
Run
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. Adapter defaults, workspace path, budget. ADMIN-only.
Team
Bundle of agent roles assigned to a project, surfaced in the artifacts.
Toggle (quality gate)
In the wizard: switch for ArchUnit / OWASP / Trivy / Playwright. 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.
Wizard
Four-step assistant at /wizard for guided project creation.
Workspace
Per-run local directory where the coding agent writes its files. Defaults to ./workspaces/<run-id>/.
Common pitfalls for beginners
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_USER and ...PASSWORD in .env, then docker compose up again.
"My run is stuck in DRAFT"
A new run is always DRAFT. You first move it to READY, then click "Start run". Two deliberate clicks before any tokens get spent.
"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 — if that's not enough, the run detail page falls back to polling.
"My adapter fails"
Vendor adapters need API keys. Set them at /integrations or via env vars. 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.
"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 budget at /einstellungen (daily or weekly). Hard mode blocks new run creation at > 100 % usage. The default soft threshold (80 %) just warns — sensible for the first few weeks.