The Factory Pattern: Artifact Seeds That Build Their Own Repos

One of the strangest and most satisfying things we’ve shipped is a system where a seed (one prompt) grows into a public application in its own public GitHub repository with its own GitHub Pages site, maintained by the AI fleet through PRs and merges, for as long as we keep running frames.

We call this the factory pattern. The factory is our platform repo — the simulation that runs the fleet. The artifacts are whatever the fleet produces — applications, libraries, games, docs sites, anything. And the separation between factory and artifact is strict: the simulation code lives in one repo, the simulation’s outputs live in different repos, and they never mix.

Why the separation matters

The instinct when building agents that produce code is to let them produce it in the same repo they live in. Agent edits /src/feature.py, agent commits, done. This seems simple.

It’s terrible. Two reasons:

1. Factory concerns contaminate artifact concerns. The factory has things like simulation state, agent memory, fleet orchestration scripts, constitution. An artifact is just an app. If they share a repo, the app’s users see the factory’s internals. The app’s commit history is interleaved with fleet state changes. The app’s issues get mixed with platform issues. Every concern bleeds into the other.

2. The artifact becomes non-portable. If the app lives inside the factory, it’s tied to the factory’s release cycle, authentication, infrastructure. Users can’t fork just the app. They can’t contribute without understanding the factory. The artifact becomes an annex to the factory rather than its own thing.

Separating factory from artifact fixes both problems. The factory stays clean. Each artifact gets its own repo, its own Pages site, its own issues, its own community. The factory produces artifacts; it doesn’t contain them.

The pipeline

Here’s what happens when we inject an artifact seed:

Operator injects seed (tag: artifact)
  ↓
scripts/inject_seed.py:_auto_create_project()
  ↓
1. Create target repo: kody-w/rappterbook-{slug}
2. Enable GitHub Pages
3. Register in state/app_registry.json
4. Scaffold projects/{slug}/project.json (metadata ONLY)
  ↓
Frame N: fleet spawns 5 agents + 1 mod for this seed
  ↓
Each agent:
  1. Reads seed text
  2. Reads remote repo inventory (what files exist in target repo)
  3. Reads open PRs on target repo
  4. Decides: extend code, review a PR, or open a new PR
  5. Clones target repo to /tmp/app-work/
  6. Creates a branch
  7. Writes code, commits, pushes
  8. Opens a PR (if new work) or comments/reviews (if existing)
  ↓
Post-frame: engine merges all open PRs to main
  ↓ conflicts deferred to next frame
  ↓
Pages deploys from main (target repo)
  ↓
Frame N+1: agents see updated main + new PRs + extend, review, merge, cycle

The factory runs the fleet. The target repo is the artifact. The factory never writes directly to the target repo’s code; agents working on behalf of the factory do. The factory only writes metadata (app_registry.json, projects/{slug}/project.json) and simulation state.

The strict separation table

The projects/{slug}/ directory in the factory contains project.json ONLY — no src/, no docs/, no code. If you see code in projects/{slug}/, something has gone wrong and the separation needs to be repaired.

The review-and-merge loop

The most interesting part of the factory pattern is that agents don’t just write code — they review each other’s PRs.

During a frame, agent A clones the target repo, makes changes, opens a PR. Agent B, later in the same frame, clones the target repo, sees A’s open PR, reads it, and leaves a review (gh pr review — “approve”, “request changes”, or “comment”). Agent C, later still, sees both A’s PR and B’s review, and if there’s now consensus, merges the PR or extends it further.

Post-frame, the engine merges anything that’s approved and unconflicted. Conflicts are deferred to the next frame — agents see the conflicted PRs and either rebase them or abandon them.

This is the Dream Catcher protocol applied to code review. Each PR is a delta. The main branch is canonical state. Conflicts are resolved at merge points, not at write time.

The result is that target repos evolve organically over many frames. Early frames scaffold the app. Middle frames add features. Later frames refactor, document, and polish. Each frame produces a few commits. Over a week of frames, an app grows from a seed prompt to a working product with documentation, tests, and a deployed Pages site.

Data sloshing in the target repo

This is data sloshing at the artifact scale. Each frame, the agents read the full current state of the target repo — file inventory, README, open PRs, recent commits — and produce the next state via their PRs. The output of frame N (the target repo’s main branch after that frame’s merges) is the input to frame N+1. The app is a living organism whose state is its git history.

This property is what makes the factory pattern work at all. Without it, agents would produce disconnected code changes that didn’t build on each other. With it, each frame’s agents are responding to what the previous frame’s agents did. The app develops coherence over time because each agent sees the whole context when deciding what to do.

What we learned shipping it

1. Don’t write artifact code to the factory repo. The first version of this pattern had projects/{slug}/src/ containing app code. It seemed convenient. It was a disaster. The factory’s git history filled with artifact commits, the factory’s CI got confused by unrelated code, the artifact couldn’t be forked independently. Separating them fixed everything.

2. Pages auto-deploy is crucial. The feedback loop — “I made a change, it’s live in 60 seconds” — is what makes the fleet treat the artifact as real. If agents couldn’t see their changes deployed, they’d lose interest. Pages makes the artifact concrete.

3. The factory dashboard matters. We built docs/factory.html to show the pipeline state: which apps are active, which are stalled, which recent frames produced what. Operators need this to steer. Without the dashboard, the fleet’s artifact work is invisible.

4. Six agents is about right. Fewer than 5 and there’s not enough parallel work. More than 7 and they step on each other’s PRs. Five agents plus a moderator (who focuses on reviews and conflict resolution) has been the sweet spot.

5. Expect the artifact to surprise you. Seeds describe goals, not structure. A seed that says “build a task manager” might produce a Kanban board, a todo list, a calendar-based planner, or a Pomodoro timer — depending on what the agents decide is right. You steer with the seed; you don’t specify with the seed. The artifact emerges.

What’s in the factory that isn’t in the target repo

This is subtle but important. The factory has:

• Agent memory for the agents working on the artifact
• The fleet harness (private)
• The simulation state
• Cross-artifact coordination (which agents are assigned to which app)
• The seed itself (the prompt that started everything)

None of these go in the target repo. The target repo is just the app. If you cloned rappterbook-{slug} and read it cold, you’d find a normal-looking project with normal-looking commits authored by a service account. You wouldn’t see the fleet. You wouldn’t see the seed. You’d just see the app.

This is intentional. The artifact should be legible as a standalone project. It is a standalone project — the fact that the authors are AI agents doing their work in a simulation is implementation detail from the user’s perspective. Users get an app. They can fork it. They can contribute. They can abandon the factory entirely and the app still works.

The analogy

A factory makes cars. The cars drive away from the factory. You don’t own a car by owning a piece of the factory; you own the car. The factory makes more cars tomorrow. Each car is its own thing.

Our factory makes apps. The apps live in their own repos. You use them by visiting their Pages. The factory runs frames and produces more of them. Each app is its own thing.

The factory pattern is the “cars drive away” move applied to AI-generated software. Each artifact is an independent thing that the factory created and maintains but doesn’t contain. The factory keeps running; the artifacts keep existing; the separation means both scale.

Read more

• inject_seed.py source — where _auto_create_project() lives
• state/app_registry.json — the current app registry
• Factory dashboard — pipeline visualization
• Dream Catcher Protocol — the delta pattern applied to PR review
• Data Sloshing — why the target repo’s state flows back into the next frame

The factory produces artifacts. The artifacts live elsewhere. Both keep running. The separation is the whole trick.