Comprehensive manual for single-seat users. Covers installation and operation (Claude plan, Codex plan, API keys), defining projects with complete examples, the run lifecycle, and — honestly — what the factory does today for the wider SDLC (roadmap, upgrades, bug fixing) and where its limits are.
As of version 0.30.0. Deutsche Version:
benutzerhandbuch.md. Screenshots live underimg/(added incrementally).
Contents
- What the Software Factory is (and isn't)
- Installation & operating modes
- Defining a project
- Running a run
- The result: workspace, Git, artifacts
- Further development, roadmap & SDLC — honestly
- End-to-end example
- Troubleshooting & FAQ
1. What the Software Factory is (and isn't)
The Agentic Software Factory is a local control plane for AI-assisted software development. Instead of driving a coding agent (Claude Code, OpenAI Codex, Gemini, Aider) directly in the shell, you describe your intent in a structured UI; the factory turns it into precise input artifacts, starts supervised runs, collects logs/tokens/cost, and enforces Git discipline plus a build gate.
The mental model — a "cockpit": describe the project → pick a team of agent roles → define an objective → the factory starts a run, works in an isolated workspace, commits, builds (mvn verify) and delivers a reproducible result with Git history.
Current maturity (honest): the factory does both — the initial setup of a new project ("greenfield scaffolding") and iterative development across multiple versions: persistent workspace, repo import, plan/build runs with a backlog, branch isolation, pull requests, an automatic correction loop, milestone releases and scheduled routines (see chapter 6). What is still missing or limited is listed in 6.3.1. This manual states clearly at each point what works and what doesn't yet.
2. Installation & operating modes
The single seat runs hybrid: Postgres in a Docker container, the factory app natively as your OS user. Reason: in plan mode the factory calls the agent CLI (claude / codex) as the same OS user and reads its login from the home directory — in a container neither the CLI nor the login would exist.
2.1 Prerequisites
| What | For | Check |
|---|---|---|
| Java 25 (JRE/JDK) | runs the factory | java -version |
| Docker (Desktop/Engine) | only for Postgres | docker compose version |
| Agent CLI (one of them) | called as a subprocess | claude --version / codex --version / kimi --version / gemini --version / aider --version |
| Git | workspaces, diffs | git --version |
| (target project's build tool) | for the build gate, e.g. Maven | depends on stack |
| (optional) Trivy | SBOM and dependency/licence scan | trivy --version |
| (optional) Docker/Podman | container sandbox per run | docker --version |
The single-seat test package lives in the repo under dist/einzelplatz/ (compose.yml, .env.example, start.sh, start.ps1, README.md). Download the runnable softwarefabrik-app.jar from the GitHub release of the desired version and place it next to the start scripts.
2.2 Mode A — Claude plan (sign-in)
Runs use your Claude Max/Pro plan instead of an API key.
- Sign in once:
Credentials then live underclaude # go through the login/OAuth flow~/.claude(Linux/WSL/macOS) or%USERPROFILE%\.claude(Windows). - In
.env:
In plan mode the factory actively strips anySOFTWAREFABRIK_EXECUTION_ADAPTER=claude SOFTWAREFABRIK_CLAUDECODE_AUTH_MODE=subscriptionANTHROPIC_API_KEYfrom the subprocess (otherwise the key would take precedence over the plan). - Optional, if credentials are not at the default location:
SOFTWAREFABRIK_CLAUDECODE_CONFIG_DIR=/path/to/.claude
2.3 Mode B — Codex plan (Sign in with ChatGPT)
Analogous, with OpenAI Codex on a ChatGPT Plus/Pro plan.
- Sign in once:
Credentials land incodex login # "Sign in with ChatGPT"~/.codex/auth.jsonor%USERPROFILE%\.codex\auth.json. - In
.env:
In plan modeSOFTWAREFABRIK_EXECUTION_ADAPTER=codex SOFTWAREFABRIK_CODEX_AUTH_MODE=subscriptionOPENAI_API_KEYis actively stripped from the subprocess. - Optional different directory (
CODEX_HOME):SOFTWAREFABRIK_CODEX_CONFIG_DIR=/path/to/.codex
The auth mode is also switchable in the UI under Settings and takes effect without a restart (max. 5 min cache).
2.4 Mode C — Kimi plan (Moonshot AI)
Same idea as Claude and Codex, using the Kimi CLI with a "Kimi for Coding" membership (flat rate instead of per-token billing).
- Sign in once:
Credentials land inkimi login~/.kimi-codeor%USERPROFILE%\.kimi-code. - In
.env:
Note: the Kimi CLI reads keys only from itsSOFTWAREFABRIK_EXECUTION_ADAPTER=kimi SOFTWAREFABRIK_KIMI_AUTH_MODE=subscriptionconfig.tomlor theKIMI_MODEL_*override trio. In subscription mode the factory actively strips that trio from the subprocess; in API-key mode it injects it. - Optional custom directory (
KIMI_CODE_HOME):SOFTWAREFABRIK_KIMI_CONFIG_DIR=/path/to/.kimi-code
In subscription mode the model aliases
k3andkimi-for-codingare valid; the cost view reports them at €0.00 because a flat rate incurs no token cost.
2.5 Mode D — API keys
Classic API-key operation (no plan sign-in). Auth mode stays the default api-key; you just provide the matching key.
| Adapter | .env |
Key |
|---|---|---|
| Claude Code | SOFTWAREFABRIK_EXECUTION_ADAPTER=claude |
ANTHROPIC_API_KEY=sk-ant-… |
| OpenAI Codex | SOFTWAREFABRIK_EXECUTION_ADAPTER=codex |
OPENAI_API_KEY=sk-… |
| Google Gemini | SOFTWAREFABRIK_EXECUTION_ADAPTER=gemini |
GEMINI_API_KEY=… |
| Aider | SOFTWAREFABRIK_EXECUTION_ADAPTER=aider |
depends on backend model |
| Kimi (Moonshot) | SOFTWAREFABRIK_EXECUTION_ADAPTER=kimi |
KIMI_API_KEY=… or MOONSHOT_API_KEY=… |
| Local model | SOFTWAREFABRIK_EXECUTION_ADAPTER=local-llm |
— (OpenAI-compatible endpoint) |
| AWS Bedrock | SOFTWAREFABRIK_EXECUTION_ADAPTER=bedrock |
AWS credentials (experimental) |
| Google Vertex AI | SOFTWAREFABRIK_EXECUTION_ADAPTER=vertex |
GCP credentials (experimental) |
| Azure OpenAI | SOFTWAREFABRIK_EXECUTION_ADAPTER=azure-openai |
Azure credentials (experimental) |
| Mock (no tool/key) | SOFTWAREFABRIK_EXECUTION_ADAPTER=mock |
— |
The three cloud gateways (Bedrock, Vertex, Azure OpenAI) are implemented but not verified end-to-end against real cloud credentials. Verify before production use.
Example (Claude via API key):
SOFTWAREFABRIK_EXECUTION_ADAPTER=claude
SOFTWAREFABRIK_CLAUDECODE_AUTH_MODE=api-key
ANTHROPIC_API_KEY=sk-ant-...
Tip for cost-free exploration: with
SOFTWAREFABRIK_EXECUTION_ADAPTER=mockyou can walk the entire run flow without a real agent — ideal for learning the UI and lifecycle before spending real money/tokens.
2.6 Mode E — Local model (air-gap)
For operation without any network access: an OpenAI-compatible local backend (Ollama, vLLM, LM Studio, self-hosted).
SOFTWAREFABRIK_EXECUTION_ADAPTER=local-llm
For true air-gap operation, additionally:
- enable the container sandbox (Settings →
execution.sandbox.variant=container); it starts the agent per run in an ephemeral container with--network=none, - leave PR/CI feedback off (the default) and keep the remote host allowlist empty or restricted to internal hosts,
- licence without a callback channel: see
docs/adr/0009-air-gap-ueber-refresh-required-false.md.
2.7 Starting & logging in
# in dist/einzelplatz/ (with the .jar placed next to it)
cp .env.example .env # set SOFTWAREFABRIK_ADMIN_PASSWORD!
./start.sh # Windows: ./start.ps1
The script brings up Postgres and starts the factory. Then open http://localhost:8080, log in as admin / your SOFTWAREFABRIK_ADMIN_PASSWORD.
Stop: Ctrl+C (app) and docker compose down (Postgres; -v also deletes the data).
3. Defining a project
There are two ways to create a project:
- Project wizard (
/wizard) — guided, recommended to start. - Quick create (
/projects/new) — expert form, all fields free.
3.1 The project wizard
The wizard guides you through six steps. Since version 0.11 it thinks in three orthogonal dimensions — target platform × backend × frontend(s) — so full-stack and multi-target products (one backend, several clients) can be expressed.
| Step | Content |
|---|---|
| 1 — Target platform & project type | Web / Mobile / Desktop (multi-select) or "import existing repo" |
| 2 — Backend | backend technology (Spring Boot, Quarkus, ASP.NET, FastAPI/Flask, Node) or "no backend" |
| 3 — Frontend(s) | multi-select, filtered by platform and backend (e.g. Thymeleaf/Vaadin only with Java, Blazor/WPF only with .NET; React/Angular/Vue/Flutter are backend-agnostic) |
| 4 — Questions | base data + stack-specific fields (e.g. Java version, DB, architecture style) |
| 5 — Quality gates | optional toggles (ArchUnit, OWASP Dependency-Check, Trivy, ESLint, Playwright …), unioned over all chosen stacks |
| 6 — Summary | review + local token/cost estimate + preview of the initial prompt |
At the end the wizard creates a project in "draft" status and lands you in the normal project editor — where all fields remain editable.
Note on the filter: if a target platform is not covered by any selected frontend, the wizard warns (it does not block). You can deliberately continue without a frontend (e.g. an API only) and add one later.
3.2 The 13 project-definition fields
The project definition is the heart — the agent artifacts are generated from it. It has 13 content fields (plus master data title/product name):
| Field | Meaning | Example |
|---|---|---|
| shortDescription | one/two-liner of what it is | "REST API to manage maintenance orders." |
| vision | target picture, what should be achieved | "Technicians capture orders on mobile; dispatchers plan on the web." |
| targetAudience | who uses the product | "Field technicians and back-office dispatchers." |
| technologyPreferences | desired stack / versions | "Spring Boot 3.4, Java 21, PostgreSQL, Maven." |
| architecturePreferences | architecture style, layers, packages | "Hexagonal, ports & adapters, base package io.example.maint." |
| securityRequirements | security requirements | "OAuth2/OIDC login, roles Admin/Dispatcher/Technician." |
| accessibilityRequirements | accessibility | "WCAG 2.1 AA for the web UI." |
| nonfunctionalRequirements | NFRs (performance, availability, quality gates) | "p95 < 300ms; ArchUnit + OWASP check enabled." |
| gitWorkflowPreferences | branching/commit conventions | "Conventional Commits; trunk-based." |
| documentationRequirements | desired docs | "README, ADRs for architecture decisions, OpenAPI." |
| languagePreference | language for comments/docs (de/en) |
"en" |
| sectorContext | industry/domain context | "Facility management, GDPR-relevant." |
| freeText | anything else; the wizard prompt also lands here | (free) |
The more precise these fields, the better the agent's starting context. Empty fields show up as open placeholders in the generated prompt — fill them in the editor before you start the first run.
3.3 What the factory generates (artifacts)
On generation the factory turns the definition into versioned Markdown artifacts that the agent receives as input:
- PROJECT.md — 14 numbered sections, 1:1 from the fields (target picture, stack, architecture, security, NFRs, Git, docs, language, sector, free text).
- INSTRUCTIONS.md — way of working (autonomous), architecture/security guardrails, build/test (
mvn verify), Git discipline, forbidden shortcuts. - Plus: AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md.
These files are written into the workspace and committed on a run; PROJECT.md/INSTRUCTIONS.md additionally go straight into the agent call.
3.4 Example definitions
Example 1 — Spring Boot REST API + React web (full-stack)
Title: Maintenance order portal
Product name: MaintHub
shortDescription: Web portal + REST API to manage maintenance orders.
vision: Dispatchers plan orders on the web; a clean REST API later
also serves a mobile app.
targetAudience: Back-office dispatchers (web), later technicians (mobile).
technologyPreferences: Backend Spring Boot 3.4 / Java 21 / PostgreSQL / Maven;
frontend React + Vite + TypeScript.
architecturePreferences: Hexagonal (ports & adapters), base package
io.example.maint; REST under /api/v1.
securityRequirements: OAuth2/OIDC; roles ADMIN, DISPATCHER.
nonfunctionalRequirements: ArchUnit layer tests + OWASP Dependency-Check enabled;
p95 < 300 ms.
gitWorkflowPreferences: Conventional Commits, trunk-based.
documentationRequirements: README, OpenAPI spec, ADRs.
languagePreference: en
sectorContext: Facility management.
Wizard selection: platform = Web · backend = Spring Boot · frontend = React.
Example 2 — Python FastAPI service (API only, no frontend)
Title: Receipt extraction service
Product name: DocScan API
shortDescription: FastAPI service that structures uploaded receipts via OCR.
vision: Other systems send PDFs/images and get structured JSON
receipt data back.
targetAudience: Internal backends (machine-to-machine).
technologyPreferences: Python 3.12, FastAPI, SQLAlchemy + PostgreSQL, uv.
architecturePreferences: Layered (api / service / repository), root package docscan.
securityRequirements: API key per client; rate limiting.
nonfunctionalRequirements: Ruff + mypy + pytest-cov enabled; Bandit scan.
languagePreference: en
sectorContext: Accounting/fintech.
Wizard selection: platform = Web · backend = Python FastAPI · frontend = (none / API only).
Example 3 — Static frontend (no backend)
Title: Product landing page
Product name: LaunchPad
shortDescription: Fast, static marketing landing page.
vision: Performant, accessible page with no server backend.
targetAudience: End customers/prospects.
technologyPreferences: Node 22, Vite, plain HTML/CSS/JS.
accessibilityRequirements: WCAG 2.1 AA.
nonfunctionalRequirements: Playwright E2E + Trivy enabled; Lighthouse > 95.
languagePreference: en
Wizard selection: platform = Web · backend = no backend · frontend = static frontend.
4. Running a run
A run is a supervised execution of the agent against an objective.
4.1 Team, adapter, objective
When creating a run (/runs/new) you choose:
- Adapter — which agent executes (
claude,codex,gemini,aider,kimi,local-llm,bedrock,vertex,azure-openai,mock; default from Settings, possibly restricted by a project or tenant policy). - Team — the participating agent roles.
- Objective — free per run (up to 4000 chars). This is where you say what this run should do, e.g. "Create the project skeleton per PROJECT.md and implement the order CRUD."
4.2 The run lifecycle
A run goes through seven business phases:
INTAKE → PROMPT_ASSEMBLY → WORKSPACE_PREPARATION → EXECUTION → VALIDATION → CORRECTION → COMPLETION
and technical statuses: DRAFT → READY → PREPARING → RUNNING → (WAITING_FOR_APPROVAL) → VALIDATING → COMPLETED (or NEEDS_CORRECTION, FAILED, TIMEOUT, CANCELLED, PAUSED).
Flow in the UI:
- "Mark ready" (DRAFT → READY).
- "Start run" (READY → PREPARING): the workspace is created,
git init, the Markdown artifacts are written and committed (checkpoint). - RUNNING: the agent works; live logs stream via Server-Sent Events.
- VALIDATING:
mvn verify(build gate). - COMPLETED or NEEDS_CORRECTION.
You can pause/resume and cancel runs.
4.3 Approval gate & inline diff
Before the execution phase — depending on policy — an approval gate kicks in: the run goes to WAITING_FOR_APPROVAL. On the run detail page you see an inline diff of the workspace changes since the earliest checkpoint (up to 256 KB) and approve via "Approve".
4.4 Validation & correction
The VALIDATION phase today runs mvn verify (Java-centric; without a pom.xml it is skipped). If the build is red, the run goes to NEEDS_CORRECTION.
Honest limitation: an automatic correction/feedback loop ("give feedback, let the agent fix it") is not implemented today. The transition
NEEDS_CORRECTION → RUNNINGis allowed in the state machine but triggered by no UI action. In practice: on a red build you create a new run with an adjusted objective (see chapter 6).
4.5 Quality gate / AI review
In addition to the build gate there is the quality gate (/runs/{id}/quality-gate). It invokes six read-only reviewers and aggregates their findings into a verdict (PASSED / WARNING / FAILED / SKIPPED / ERROR):
| Reviewer | Kind | Checks |
|---|---|---|
claude-review |
LLM (read-only) | diff review via Claude Code |
aider-review |
LLM (read-only) | diff review via Aider |
security |
static | hardcoded keys, path traversal, SQL concatenation, Runtime.exec, password logging |
architecture-reviewer |
static | layering violations, JPA in the domain layer, changes to existing Flyway migrations (CRITICAL) |
hallucination-review |
static | invented classes/methods, TODO markers, "tests pass" without any test change |
dependency-scan |
Trivy | CVEs and licence violations in dependencies |
Reviewers are read-only — they never write into the workspace.
Policy: strict blocks CRITICAL + HIGH, requires SECURITY and ARCHITECTURE and sets a confidence floor of 0.70; lenient blocks CRITICAL only. Three rules apply always, regardless of policy: SECURITY/HIGH and SECURITY/CRITICAL block, ARCHITECTURE/CRITICAL blocks, and a crashed reviewer yields ERROR — never a silent pass.
Operating mode (Settings; can be overridden tenant-wide via policy-as-code):
| Mode | Effect |
|---|---|
off |
reviewers do not run |
advisory (default) |
findings are collected and shown but do not block |
blocking |
a FAIL produces feedback and starts the correction loop |
Since v0.14 the gate runs as part of the run pipeline after a successful build; you can additionally trigger it manually on the run detail page.
5. The result: workspace, Git, artifacts
Every project has a persistent workspace under <workspaces-root>/<project-slug>/. It contains:
- a Git repo initialized by the first run (or cloned/copied on repo import),
- the generated Markdown artifacts (refreshed on every run, non-destructively),
MEMORY.mdfrom the curated project memory,AGENTS.mdwith the engineering guardrails (plus a minimalCLAUDE.mdpointing at it),- the code produced by the agent.
Important: the workspace belongs to the project, not the run. A follow-up run continues on the existing code — that is what makes iterative development possible. Each build run branches off to
sdlc/run-<id8>and, on success, is merged into the base branch or opened as a pull request. On failure the work stays on the run branch for inspection and the base stays clean.Consequence: only one run per project executes at a time (concurrency guard). Different projects run in parallel.
6. Further development, roadmap & SDLC — honestly
You asked whether what you do with the AI assistant on the factory itself (roadmap-driven development, upgrades, bug fixing across many versions) can be done with the factory. Since the SDLC build-out the answer is: yes — the iterative loop is now supported. Greenfield build and development on existing code run through the same factory.
6.1 The iterative SDLC loop (now supported)
Plan (plan run) → backlog from plans/*.md → select/activate
→ Build (build run on the persistent workspace) → validate
→ Learn (memory) → re-plan
- Project-persistent workspace + re-run. Follow-up runs continue on the existing code/Git repo (
<root>/<slug>/workspace) instead of starting empty. "Run 2" sees "run 1"'s code. Only one active run per project at a time (concurrency guard). - Real repo import. The
existing-repo-importtemplate brings an existing repo (local path → copy incl..git; Git URL →git clone) into the persistent workspace; development then proceeds via plan/build runs — not via re-scaffolding. - Project memory. Curated learnings/decisions per project (DB source, editable in the UI under Memory) are mirrored into the workspace as
MEMORY.mdbefore each run and ingested back from an agent-updatedMEMORY.mdafterwards. Adapter-independent, version-stable. - Roadmap/plans as a backlog. A plan run (changes no code) has the agent produce
plans/NNNN-*.mdwith next steps; the factory indexes them as backlog items (selection menu under Backlog / Plans). "Activate" starts a build run whose objective is the plan MD — against the existing code. Plan content lives in the repo (plans/), status/order in the DB.
6.2 Branch/PR, self-correction, quality gate & auto-loop (now supported)
The former "iteration block" is implemented:
- Branch isolation per build run. Each build run works on its own branch
sdlc/run-<id>; on success it is merged into the base branch (or a PR is opened, see below), on failure the work stays on the branch for inspection and the base stays clean. - Push + pull request (GitHub). If a Git remote URL is set on the project and a GitHub token is stored under Integrations, a successful build run pushes its branch and opens a pull request (merge via the PR) — otherwise the local merge applies.
- Automatic correction feedback loop. On a red build the factory feeds the build feedback into another run on the same branch (
NEEDS_CORRECTION → RUNNING), up to 2 attempts; after that the run stays inNEEDS_CORRECTION. - Quality gate in the pipeline. After a successful build the AI quality gate optionally runs as part of the pipeline. Mode under Settings:
off/advisory(default: run + log) /blocking(FAILED/ERROR triggers the correction loop). - Auto follow-up proposals. Optionally (setting) a successful build run automatically triggers a plan run → the Plan→Build→Plan loop closes itself.
6.3 Further building blocks (added since v0.15)
Milestone release. Under /projects/{id}/milestones you bundle runs into a version. The release produces a changelog entry, a Git tag and — with a GitHub remote configured — a GitHub release.
Routines. Under /projects/{id}/routines you schedule plan or build runs (toggleable). Together with auto follow-up suggestions the loop plan → build → check → merge → plan again keeps going without manual triggering — with the approval points as deliberate stops.
Backlog with dependencies. Backlog items can depend on each other; an item becomes DONE only once its build run is actually merged — not when code was written.
Skill/plugin library. Under /skills you manage versioned skills and plugins. Before each run they are materialized into the workspace as .claude/skills/<name>/SKILL.md, .claude/agents/<role>.md and .claude/settings.local.json. That makes it traceable which extension, in which version, was in the agent's context.
Engineering guardrails. A vendor-neutral behavioural policy flows into the context of every coding agent on every run and is projected into the repo as AGENTS.md — one source, several projections, instead of one maintained copy per tool.
Repository reality. Before each build run the base branch is fast-forwarded to the remote state. A merge conflict does not abort the run; the conflicting files enter the correction loop as a work instruction. With PR feedback enabled (git.pr-feedback.enabled, off by default) the run waits in WAITING_FOR_PR for green CI and a merge; red CI likewise starts a correction.
Multi-user operation. Roles (VIEWER … ADMIN), tenants, optional SSO, budget caps, policy-as-code, compliance profiles and the signed audit chain are available — described in the separate administration manual.
6.3.1 What is still open (outlook)
- More Git hosts: push, pull request, CI status polling and releases are implemented against the GitHub API. GitLab, Bitbucket and Azure DevOps are missing; there the local merge applies.
- Issue-tracker sync (Jira/Linear/GitHub Issues) as a backlog source.
- Parallel multi-branch execution: only one run per project at a time (deliberately deferred).
- Seat-level budget caps — the per-user breakdown exists (
/mandanten/seat-kosten), but the hard cap only applies per tenant. - Cloud gateways (Bedrock/Vertex/Azure OpenAI) are not verified end-to-end.
- Cross-project learning.
6.4 Recommended workflow
- New project: wizard → definition → artifacts → build run (scaffolding). Existing repo: choose "import repo" in the wizard, give the path/URL.
- Optional: set a Git remote on the project + a GitHub token under Integrations → build runs create PRs.
- Start a plan run (Backlog/Plans): the AI proposes the next steps as
plans/*.md. - In the backlog, activate an item → a build run implements it on the existing code (own branch, self-correction, optional quality gate).
- Curate memory: keep decisions/learnings there; they flow into every follow-up run.
- Repeat (loop) — optionally automatically via auto follow-up proposals. Use the
mockadapter to practice the whole loop for free.
7. End-to-end example
A complete walkthrough with example 1 (Spring Boot + React):
- Wizard:
/wizard→ platform Web → backend Spring Boot (Java 21, PostgreSQL, hexagonal, packageio.example.maint) → frontend React (TypeScript) → quality gates ArchUnit + OWASP → summary → create project. - Editor: review/complete the fields from 3.4, save. Generate artifacts.
- Create run: adapter claude (or mock to practice), pick a team, objective: "Create the Spring Boot skeleton per PROJECT.md, implement the order CRUD (entity, repository, REST under /api/v1) and a React frontend with an order list. mvn verify must be green."
- "Mark ready" → "Start run". Follow the live logs.
- Approve once the inline diff looks right.
- After
mvn verifyis green → COMPLETED. Optionally trigger the quality gate. - Inspect the result workspace and adopt it into your repo.
8. Troubleshooting & FAQ
claude: command not found/CreateProcess error=2— CLI not on PATH. Checkclaude --version; setSOFTWAREFABRIK_CLAUDECODE_COMMAND(or…CODEX_COMMAND) to the full path.- Run auth error / 401 — plan login missing. Run
claude/codex loginonce; the credential directory must be populated. - Plan mode still bills via API? — make sure no
ANTHROPIC_API_KEY/OPENAI_API_KEYis set in the environment. The factory strips it in plan mode, but it's cleaner to leave it out entirely. Port 8080 in use— stop the other app or setSOFTWAREFABRIK_PORT.- Postgres won't start — is Docker running? (
docker ps). Windows: start Docker Desktop first.Port 5432 in use→ stop your local Postgres. - VALIDATION skipped — no
pom.xmlin the workspace;mvn verifyis the build gate for Java stacks. - "Run 2 doesn't build on run 1" — should not happen: the workspace is project-persistent. Check that it really is the same project and that the previous run was merged (on
NEEDS_CORRECTIONthe work is still on the run branch). - Run stuck in
WAITING_FOR_PR— the PR is not merged yet or CI is not green. Is the poller enabled? (git.pr-feedback.enabled). - Quality gate reports
ERROR— a reviewer crashed (e.g. missing CLI). That is deliberately not a silent pass; install the CLI or disable the reviewer via the gate mode. - Merge conflict — the factory feeds the conflicting files back as a correction task (max. 2 attempts); after that the run stays in
NEEDS_CORRECTIONand you resolve it manually. - Just explore without cost —
SOFTWAREFABRIK_EXECUTION_ADAPTER=mock.