Tutorial

From project draft to Claude Code commit

This tutorial walks you through the full Software Factory workflow in one go: capture a project, generate artifacts, run against Claude Code, inspect the result. No mock, no shortcuts — this is the real path.

~20 minutes real LLM call project to commit local workspace

What you will have at the end

1
Project definition with 6 markdown artifacts
1
Git workspace with commits
✓
Validated build gate
✓
Logs, phases, approvals tracked
Scope: For your very first contact with the platform, the Quickstart is the better fit — it uses the mock adapter without any API call. This tutorial is for the real use case with Claude Code.

Prerequisites

ToolVersionCheck
Docker Composev2.xdocker compose version
JDK25java -version
Maven≥ 3.9mvn -v
Claude Code CLIcurrentclaude --version
git≥ 2.4git --version

Claude Code must already be logged in interactively once. The factory invokes the claude CLI as a subprocess and reuses your stored credentials.

Steps

1

Start the infrastructure

Bring up Postgres via Docker Compose and run the app via Maven. The app intentionally does not run inside a container so it can call Claude Code as a local subprocess.

# in the repo root:
docker compose up -d postgres

# in a second terminal:
cd app
export SOFTWAREFABRIK_ADMIN_PASSWORD='test-admin-123'
export SOFTWAREFABRIK_EXECUTION_ADAPTER=claude
export SOFTWAREFABRIK_CLAUDECODE_COMMAND="$(which claude)"
export SOFTWAREFABRIK_WORKSPACES_ROOT=/tmp/softwarefabrik-workspaces
mvn spring-boot:run
2

Log in

Open http://localhost:8080, sign in as admin (password from the env variable). The first login provisions the bootstrap admin in the DB.

3

Create a project

In the wizard: title, short description, goal, technology context. Well-written fields produce substantially better results — the factory turns them into the work orders for the agent.

Example: "CSV parser for IBAN lists in Kotlin/Spring Boot, output as JSON, no external libraries beyond Spring Boot starter web."
4

Generate artifacts

The Generate artifacts button creates six markdown documents (PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md). They are editable — read them carefully, especially INSTRUCTIONS.md and DEFINITION_OF_DONE.md.

Tip: The sharper your acceptance criteria, the better the platform can gate the build. Imagine handing the brief to an external developer you only reach via document.

Then set the status to READY.

5

Create a team and start the run

Menu Teams → new team with at least one agent (e.g. Developer). Then Runs → new run: project, team, title, goal. Status to READY, then Start run.

6

Watch execution

The run goes through four phases asynchronously:

PhaseWhat happens
WORKSPACE_PREPARATIONCreate git repo under SOFTWAREFABRIK_WORKSPACES_ROOT/<slug>/<run-id>, copy artifacts
EXECUTIONclaude --print <task> runs inside the workspace, agent produces code
VALIDATIONmvn verify (or the configured build) validates the result
COMPLETIONOn success: commit + status COMPLETED. On failure: NEEDS_CORRECTION

In parallel you can use the Show logs and Git status buttons, and if needed perform a manual approval step.

7

Inspect the result

cd /tmp/softwarefabrik-workspaces/<slug>/<run-id>
git log --oneline -10
mvn verify                 # optionally re-run locally

Code and artifacts stay in the workspace until you delete it manually. The workspace is a normal git repo — you can push, branch, review from here.

Expectations for the first run

Typically works well

Often needs a follow-up run

Typical pattern: The first run lands at 70–90 %, the second run closes the gap. The factory is built exactly for this iteration — structured rather than ad-hoc CLI loops.

Common pitfalls

SymptomFix
claude: command not foundSet an absolute path in SOFTWAREFABRIK_CLAUDECODE_COMMAND.
Run stuck in PREPARINGCheck write permissions on SOFTWAREFABRIK_WORKSPACES_ROOT, open the logs.
mvn verify fails immediatelyThe agent did not produce a Maven project. Switch build via SOFTWAREFABRIK_MAVEN_COMMAND to gradle/npm, or try the mock adapter first.
License check blocks startV1 license module is off by default (SOFTWAREFABRIK_LICENSE_V1_ENABLED=false). Leave unset or set to false.
Port 8080 busySet SOFTWAREFABRIK_PORT=9090 or stop the competing process.

Next steps

softwarefabrik.io · Tutorial · Project → Artifacts → Run → Commit