Introduction · v0.44.0

Introduction for new users.

Step by step — from the very first login to a supervised development run. Focused on operation, not on architecture. If you want to bootstrap a project quickly, the project wizard gives you a six-step guided path.

Operation, not architecture 30-min walkthrough Mock adapter · no cost

What is the Software Factory?

A local web application that structures, supervises and traces AI-assisted development processes. You don't work directly with the CLI of Claude Code, Codex or Gemini, but through a UI-centric control plane.

Think of the platform as a cockpit: you describe your project, pick your team of agent roles, define a goal — and the platform starts a run, collects logs, tokens and cost, and at the end delivers a reproducible workspace with Git history, build status and quality-gate result.

Key facts v0.44.0:

9 vendor adapters 18 wizard templates 14 quality-gate toggles 6 reviewer roles 2 sandbox variants

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.
Mnemonic: Good runs begin with good artifacts. Plan deliberately before the first run click.

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!
Important: Without an explicitly set password, no bootstrap admin is created intentionally. Weak defaults would be a security bug.

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 / drafts / ready for run), runs (total / active), success rate, average run duration and 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
The Software Factory dashboard after login
The dashboard after login — metrics, license status and notices (here: the active mock adapter on the demo). Your command centre for projects and runs. (German UI)

Create a project

Two paths:

  1. Project wizard (recommended): six-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
The project wizard for creating a new project
The project wizard guides you through creation in six steps — target platform, backend, frontend(s) and the matching questions. (German UI)
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.
  • 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:

FilePurpose
PROJECT.mdVision, audience, requirements — the project's “charter”.
INSTRUCTIONS.mdConcrete operating instructions for the agent.
AGENTS.mdRoles in the team (Architect, Developer, Reviewer …) including model assignment.
WORKFLOW.mdPhase model, approval gates, branching conventions.
DEFINITION_OF_DONE.mdWhen is a run done? Build green, quality gate passed, …
README.mdReading 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.

Settings and defaults

As bootstrap admin you get the /einstellungen area. The UI sets values globally; the data model also knows project and user overrides (order: PROJECT > USER > GLOBAL > YAML), which cannot yet be maintained in the UI. Examples:

  • workspace.root — where run workspaces are created.
  • execution.adapter.default — default adapter for new runs.
  • execution.sandbox.variant — local or container.
  • run.quality-gate.mode — quality gate in the pipeline: off, advisory (default) or blocking.
  • run.approval-vor-merge — approval before EXECUTION (on by default).
Cache tip: Setting changes take effect without restart — saving clears this instance's cache entry, and the SettingService also uses a 5-minute TTL cache.

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. The standard team is preselected.
  • Run title: required. Short and meaningful, e.g. “Initial scaffolding for the BFF skeleton”.
  • Goal: optional but strongly recommended (up to 4000 characters). 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 with Mark ready and then deliberately click Start run. Before execution (EXECUTION) it additionally waits for Approve and continue — no token is burned without your confirmation.

Quick start: Once you have one successful run, click “Quick start from last setup” on the run list. Three clicks, done.

Monitoring a run

While a run is active you mostly use three views:

01 · DETAIL

Run detail

Status (RUNNING / PAUSED / WAITING_FOR_APPROVAL / COMPLETED / FAILED), current phase, token and cost figures. Pause / Resume / Cancel buttons.

02 · LOGS

Logs (live)

Server-Sent Events stream agent output to the browser. 20 s heartbeat, 5 s auto-reconnect, auto-scroll toggle.

03 · GIT

Git status

Branch, HEAD, commit list and working-tree status. The diff of the workspace changes is shown on the run detail page before approval.

The quality gate

After a successful build the quality gate runs automatically as part of the pipeline (mode advisory, default); you can also trigger it manually on the run detail page. It calls multiple reviewers, aggregates their findings and produces a verdict:

PASSED WARNING FAILED SKIPPED ERROR

Available reviewers (six; plus spec-conformance when a bound, approved spec is present):

  • architecture-reviewer — checks layer and module boundaries.
  • hallucination-reviewer — looks for invented methods / packages.
  • security-reviewer — 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.
  • dependency-scan — Trivy scan for CVEs and licence violations in dependencies.
Special rules (always blocking, regardless of policy): SECURITY/HIGH and ARCHITECTURE/CRITICAL. Reviewer crashes are surfaced as ERROR rather than swallowed.

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.
In short: Plan → Select → Build → Self-correction → Quality gate → Deliver → Learn → Continue. Each pass leaves a pushed branch with a pull request (or a local merge) and feeds the next.

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 (EXECUTION) the platform waits for an explicit user decision. An additional approval before the merge only exists when an approval policy or policy-as-code requires it. 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 6 (summary with prompt preview) 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.

  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

    Under Projects click “New project with assistant”. Choose platform Web, backend “Modern Spring Boot Backend” and no frontend. Answer the questions — pick example values everywhere; you can edit later. Toggle ArchUnit as the only quality gate. Finish with “Create and edit project”.

  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. Save, then on the project page 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

    On the project page click “Create 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. “Create”, then “Mark ready” and “Start run”.

  6. Minute 25–30: watch live

    You land on the run detail page. Before EXECUTION the run stops in WAITING_FOR_APPROVAL: look at the inline diff and click “Approve and continue”. Under “Show logs” the logs stream in; watch the phase updates, the token usage and the Git status. The mock only simulates the run and writes no code.

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

TermMeaning
AdapterBackend 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 roleLogical role like Architect, Developer, Reviewer. Described in AGENTS.md and read by the coding agent as context.
ApprovalManual gate between run phases. Prevents critical steps from running without confirmation.
ArtifactsThe six Markdown files (PROJECT.md …) the agent reads as specification.
Auto follow-up proposalsOptional feature: a successful build run automatically triggers the next plan run, so the SDLC loop keeps turning on its own.
BacklogList of proposals produced by the plan run (plans/*.md). The next step to implement is activated from the backlog.
Bootstrap adminThe initial admin account created at first start from SOFTWAREFABRIK_ADMIN_USER/PASSWORD.
BudgetMonthly 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.
DraftStatus of a project or wizard draft: not final, still editable, not yet in use.
Mock adapterTest 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.
PhaseSection of a run. Seven in fixed order: INTAKE, PROMPT_ASSEMBLY, WORKSPACE_PREPARATION, EXECUTION, VALIDATION, CORRECTION, COMPLETION. Visible in the run detail.
Plan runRun type that doesn't build but produces proposals for the next steps as plans/*.md — the source of the backlog.
Build runRun type that actually implements a selected backlog proposal on its own branch (sdlc/run-…).
PolicyRule set defining when a run continues automatically vs. where approval is required.
Project memoryProject-bound store of decisions and learnings that flows into every follow-up run, enabling continuous, iterative development.
Pull requestGitHub 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-correctionAutomatic feedback loop: a failed build is retried with the build feedback on the same branch (limited attempts, NEEDS_CORRECTION → RUNNING).
Quality gateAggregated verdict over multiple reviewer findings: PASSED / WARNING / FAILED / SKIPPED / ERROR.
ReviewerRead-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.
RunConcrete execution of a coding agent against a project. Has status, phases, logs, token usage and a Git workspace.
SettingsGlobal platform configuration at /einstellungen. Adapter defaults, workspace path, sandbox, quality gate. ADMIN-only.
TeamBundle 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 cacheDB table with daily-refreshed “latest stable” versions for Spring Boot, ArchUnit, Trivy, etc. Source for wizard pre-fill.
WizardSix-step assistant at /wizard for guided project creation.
WorkspacePersistent 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 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 (“Mark 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 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.

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