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
|
- **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).
|
(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
|
## [v202611-00052] – 2026-11-17
|
||||||
|
|
||||||
### Fixed
|
### Fixed
|
||||||
|
|||||||
@@ -25,6 +25,7 @@
|
|||||||
<a href="#models">Models</a> ·
|
<a href="#models">Models</a> ·
|
||||||
<a href="#terminal-client">Terminal client</a> ·
|
<a href="#terminal-client">Terminal client</a> ·
|
||||||
<a href="#automations">Automations</a> ·
|
<a href="#automations">Automations</a> ·
|
||||||
|
<a href="#code-factory">Code factory</a> ·
|
||||||
<a href="#integrations">Integrations</a> ·
|
<a href="#integrations">Integrations</a> ·
|
||||||
<a href="#users-and-security">Users</a> ·
|
<a href="#users-and-security">Users</a> ·
|
||||||
<a href="#statistics">Statistics</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
|
**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.
|
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
|
## Integrations
|
||||||
|
|
||||||
- **Telegram:** connect your own bot (*Settings → Account → Telegram*) and use CodeCraft from
|
- **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.
|
* under "unreleased"; scripts/release.sh renames the key to the release version.
|
||||||
*/
|
*/
|
||||||
export const WHATS_NEW: Record<string, { en: string[]; de: string[] }> = {
|
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": {
|
"202611-00053": {
|
||||||
en: ["Factory: the current version is read from the tags on the forge"],
|
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"],
|
de: ["Factory: die aktuelle Version wird aus den Tags im Forge gelesen"],
|
||||||
|
|||||||
Reference in new issue
Block a user