From 462171f27b31c0edf6e5256d0154be162bd833f2 Mon Sep 17 00:00:00 2001 From: Richard Zink Date: Tue, 17 Nov 2026 13:37:16 +0100 Subject: [PATCH] README: explain the code factory Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 6 ++++ README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++ web/src/whatsnew.ts | 4 +++ 3 files changed, 95 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 718b747..df3a197 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ until 1.0, minor versions may contain breaking changes. - **Factory versioning.** The current version is read from the tags on the forge, not from the checkout (which kept tags that were deleted there and so counted from a stale version). +## [Unreleased] + +### Changed + +- **README:** new "Code factory" section explaining phases, scope, planning chats, versions and releases. + ## [v202611-00052] – 2026-11-17 ### Fixed diff --git a/README.md b/README.md index b4c6287..0967554 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ Models · Terminal client · Automations · + Code factory · Integrations · Users · Statistics · @@ -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-`. + 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: ` and `Scope: ` 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/.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.`) 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 diff --git a/web/src/whatsnew.ts b/web/src/whatsnew.ts index 8844797..3dd189c 100644 --- a/web/src/whatsnew.ts +++ b/web/src/whatsnew.ts @@ -3,6 +3,10 @@ * under "unreleased"; scripts/release.sh renames the key to the release version. */ export const WHATS_NEW: Record = { + unreleased: { + en: ["README: new section explaining the code factory"], + de: ["README: neuer Abschnitt zur Code-Factory"], + }, "202611-00053": { en: ["Factory: the current version is read from the tags on the forge"], de: ["Factory: die aktuelle Version wird aus den Tags im Forge gelesen"],