Introduction for new users.

The mental model

The platform thinks in five layers. Once you grasp them, you'll find your way around in the UI immediately:

1. Project — idea, goal and requirements, as a draft, then as Markdown artifacts.
2. Artifacts — PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md as the agent's working basis.
3. Team — collection of agent roles with guardrails and model assignment.
4. Run — concrete execution with status, phases, logs, token usage and cost.
5. Quality Gate — automatic evaluation of the result by multiple reviewers.

Logging in

After the local start (e.g. via docker compose up) you reach the platform in the browser. Login uses an administrative account created at bootstrap from configuration:

SOFTWAREFABRIK_ADMIN_USER=admin
SOFTWAREFABRIK_ADMIN_PASSWORD=ChangeMe-2026!

If you just want to look: Live demo at demo.softwarefabrik.io. You're auto-logged-in as demo; daily reset at 04:00 UTC.

Understanding the dashboard

After login you land on the dashboard — the command centre for projects, runs and status overviews:

• Top metrics: projects (total / draft / active), active runs, 14-day token consumption, 14-day cost in EUR.
• Charts: run activity, token distribution input/output and EUR cost curve — entirely server-rendered SVG.
• Recent projects: quick re-entry into existing work.
• Recent runs: direct jump to logs, Git status and phases.

localhost:8080

Create a project

Two paths:

1. Project wizard (recommended): four-step wizard with stepper, template selection, quality-gate toggles and a summary with cost estimate and objective preview.
2. Quick create: minimal form (project title, product name) — you land directly in the editor.

On completion the structured Markdown artifacts are produced. The wizard also writes the initial-objective prompt that later serves as the agent's input on the first run.

localhost:8080/wizard

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.
• Architecture preferences: Database, architecture style, package layout.
• Security & accessibility: Project-specific requirements.
• Non-functional requirements: Performance goals, SLAs.
• Git workflow & docs: Branching model, commit conventions.
• Language: Drives the language of the generated artifacts (de/en).
• Free text: Anything that doesn't fit elsewhere.

Generating the Markdown artifacts

One click on Generate Markdown artifacts produces six specification files for the coding agent:

Settings and defaults

As bootstrap admin you get the /einstellungen area. Values apply globally, but can be overridden per project (override order: PROJECT > USER > GLOBAL > YAML). Examples:

• workspace.root — where run workspaces are created.
• execution.adapter.default — default adapter for new runs.
• execution.sandbox.variant — local or container.
• execution.claudecode.model — default model for Claude.
• budget.daily.tokens, budget.weekly.tokens — token caps.

Team and roles

Classic roles: Architect, Developer, Reviewer, QA, Security Reviewer, Documentation, Merge/Release. Per project a team from a selection of those. On run start, the team lands in AGENTS.md. Each role can have a preferredModel — the Claude Code adapter appends it as a --model flag, falling back to the CLI default for unknown IDs.

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.

Monitoring a run

While a run is active you mostly use three views:

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:

Available reviewers (five):

• architecture-reviewer — checks layer and module boundaries.
• hallucination-review — looks for invented methods / packages.
• security — static heuristic for typical security smells.
• aider-review — invokes the Aider CLI in read-only mode.
• claude-review — invokes the Claude Code CLI in read-only mode.

The iterative SDLC loop

A single run is just one building block. Across multiple runs the platform closes a complete, self-sustaining software lifecycle — from proposal through build to delivery as a pull request — and then starts over. On a project-persistent workspace the state is preserved between runs, so work builds on what came before instead of starting from scratch each time.

1. Plan — a plan run produces proposals for the next steps as plans/*.md. They then show up as the backlog.
2. Select — in the backlog you activate the proposal to be implemented next.
3. Build — a build run implements the proposal on its own branch (sdlc/run-…) on the project-persistent workspace.
4. Self-correction — if the build fails, the factory feeds the build feedback automatically into another run on the same branch (a limited number of attempts, transition NEEDS_CORRECTION → RUNNING).
5. Quality gate — after a successful build the AI quality gate checks the result. The mode is selectable: off, advisory or blocking.
6. Deliver — with a Git remote set and a GitHub token configured, the branch is pushed and a pull request is opened automatically. Without a remote/token, a local merge into the base branch happens instead.
7. Learn — the project memory records decisions and learnings that flow into every follow-up run.
8. Continue — optionally a successful build automatically triggers the next plan run (auto follow-up proposals) — the loop closes and starts again at Plan.

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.

A run moves through seven phases: INTAKE → PROMPT_ASSEMBLY → WORKSPACE_PREPARATION → EXECUTION → VALIDATION → CORRECTION → COMPLETION.

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.

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.

1. 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.

2. 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.

3. 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”.

4. 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?

5. 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”.

6. 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.

Glossary — every term in one line

Common pitfalls for beginners

From the experience of early adopters — typical friction points and how to avoid them:

Where to go next