README: explain the code factory
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
18818c1bd4
commit
462171f27b
3 files changed
+95
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -3,6 +3,10 @@
|
||||
* under "unreleased"; scripts/release.sh renames the key to the release version.
|
||||
*/
|
||||
export const WHATS_NEW: Record<string, { en: string[]; de: string[] }> = {
|
||||
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"],
|
||||
|
||||
Reference in new issue
Block a user