README: explain the code factory

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Richard ZinkandClaude Sonnet 5.5 committed 2026-11-17 13:37:16 +01:00
1 parent 18818c1bd4
commit 462171f27b
3 files changed
+95

No files matched your search

+85
View File
@@ -25,6 +25,7 @@
<a href="#models">Models</a> ·
<a href="#terminal-client">Terminal client</a> ·
<a href="#automations">Automations</a> ·
<a href="#code-factory">Code factory</a> ·
<a href="#integrations">Integrations</a> ·
<a href="#users-and-security">Users</a> ·
<a href="#statistics">Statistics</a> ·
@@ -219,6 +220,90 @@ read and continue it.
**Webhooks** start an automation from outside, e.g. on every push: the request is checked with a
shared secret or a Gitea/GitHub HMAC signature, and its JSON payload is handed to the agent.
## Code factory
The factory turns issues on your Git forge (Gitea, GitHub or GitLab) into reviewed, built, accepted and
merged changes – with agents doing the work and you deciding at the points that matter. It is
the **Factory** page in the sidebar; all chats it creates live in the sidebar folder *Factory*.
```
issue + label "factory"
│
▼
review ──► question (the agent asks in the issue; you answer, it continues)
│ └──► rejected (not buildable as written)
▼
approved ──► building ──► qa (acceptance) ──► done ──► PR merged ──► version + tag ──► closed
▲ │
└── rework ◄──┘ (up to N rounds, then failed)
```
**Phases.** Each phase is a normal CodeCraft chat in the sandbox, so you can open and read it.
The agent's answer ends with a JSON result that the factory parses; everything else is done by
the server.
1. **Review.** An agent reads the issue and the repository and decides: *approved*, *question*
(it comments in the issue and waits for your reply) or *rejected*. It also writes acceptance
scenarios. The scenarios are stored in the factory database and are **never shown to the
builder**, so the build cannot be tuned to the test.
2. **Build.** The builder works in its own git worktree on the branch `factory/issue-<n>`.
The server – not the agent – commits, pushes (never forced) and restores the spec file.
3. **Acceptance.** A different agent checks the pushed branch in a clean checkout against the
scenarios, using the repository's `.factory/setup.json` to build and start the app. Each
scenario ends as `pass`, `fail`, `unverified` or `out_of_scope`; the verdict comes from these
results, not from the model's opinion, and a run without any pass or fail counts as failed.
On *pass* the factory opens the pull request (if none is open) and comments a result table
in the issue. On *fail* the issue goes back to the build with the findings (*rework*).
4. **Done, merge, version.** You review the pull request in the factory (diff, description) and
merge it there. The factory then pulls the merge, gives the issue its version, commits
`VERSION`, pushes an annotated tag, comments on the issue and closes it.
Issue text is treated as data, never as instructions for the factory itself.
**Scope.** An issue body can contain `Spec: <file>` and `Scope: <deliverable>` lines. Review,
build and acceptance then restrict themselves to that deliverable, so a big specification is
built in small steps instead of one huge run. Without a `Scope:` line the review picks the
first unbuilt milestone of the spec. `Prerequisite:` lines name what must be merged first.
**Planning with a model.** Three chats help you create issues, without the usual review loop:
- **Spec chat** (*New project*): works out a specification with you and creates the repository
with `docs/specs/<name>.md`, the factory setup and the first issues.
- **Plan a feature**: you describe a feature or a bug; the model asks questions and ends with a
list of issues (title, description, scope, prerequisites).
- **Cut a milestone**: the model splits a milestone of the spec into numbered deliverables
(`M2.1 – …`).
*Create issues* shows the proposal for editing and files the issues on the forge. They get the
`factory` label only if you tick *Start right away*; by default you set the label yourself,
one after the other, because later issues build on the merged earlier ones.
**Versions and releases.** Every issue that is merged raises the version of the repository
(starting from the highest `vX.Y.Z` tag): a deliverable of a milestone raises the **patch**
number (0.0.1, 0.0.2, …); the **last** open deliverable of a milestone (`M<k>.<n>`) raises the
**minor** number and resets the patch (M1 complete → 0.1.0). Issues without a milestone
(bugs, features) raise the patch number. The factory writes the `VERSION` file, pushes the tag
`vX.Y.Z` and closes the issue. The **Release** button turns the current version into a
release, e.g. 0.x → 1.0.0: it builds what the repository's `.factory/release.json` describes
(Docker image for amd64 and arm64 pushed to your registry, a source zip, extra files by glob,
shell commands), tags it and creates the release on the forge with notes from the git log and
the files attached (Gitea and GitHub).
**Settings per repository** (*Factory → Repositories*, *New repository*): forge connection and token, label
(default `factory`), parallel runs, allowed issue authors (default: the token's owner), and per
phase the model, agent (CodeCraft or Claude Code), permission mode, timeout and tries on
technical failures, plus the number of rework rounds (default 2). Failed or rejected issues
can be restarted from the board, finished ones are closed with a comment.
**Files in the repository** (all optional, kept in `.factory/`):
| File | Purpose |
|---|---|
| `setup.json` | How acceptance installs and starts the app: `install`, `start`, `url` |
| `release.json` | Recipe for releases: image, platforms, Dockerfile, build args, commands, files |
Repositories are cloned into a separate factory area, not into your workspace, and agents never see the forge API token.
## Integrations
- **Telegram:** connect your own bot (*Settings → Account → Telegram*) and use CodeCraft from