# Factory

> An agent per thread that takes issues to pull requests.

Source: https://docs.workbus.dev/templates/factory/
Markdown: https://docs.workbus.dev/templates/factory/index.md
All docs for agents: https://docs.workbus.dev/llms.txt

The Factory is a board with an agent on it that takes bugs, features, and questions to pull requests. GitHub issues and pull requests come in as threads; every thread gets its own agent and its own Linux container; and what the agent says in a thread goes back to GitHub as your GitHub App. It’s one Worker, in [`templates/factory`](https://github.com/workbus-dev/workbus/blob/main/templates/factory).

src/worker.ts

```ts
// The factory: its board (a Ledger and its satellites, from Workbus, with GitHub as its own sync), an
// agent per thread, the sandbox's GitHub egress, and its page. One Worker.
import { defineWorkbus } from 'workbus'
import { notionProvider } from 'workbus/sync/notion.ts'
import { NOTION_PAGES } from './config.ts'
import { HOME, NAME } from './config.ts'
import { github } from './github.ts'
import { launcher } from './launcher.ts'
import type { Env } from './env.ts'


export const { Ledger, Relay, Mailbox, Inbox, Workbus, BoardSession, gateway } = defineWorkbus<Env>((env) => ({
  // What wakes the agent, handed to this Worker's FactoryWake by a Mailbox (design/follows.md). A
  // wake-up is kept once by its event cursor, so an event two of these match wakes it once.
  watch: {
    // Each new thread in its channels.
    wake: { tail: HOME + '/ --roots', sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
    // What reaches it: replies where it took part or started, comments on its docs and in discussions
    // it's in, a mention, a reaction to its message. Not people talking among themselves elsewhere.
    'wake-for': { tail: HOME + '/ --for @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
    // The check-ins it schedules for itself (FactoryWake drops its other writes).
    'wake-self': { tail: HOME + '/ --by @' + NAME, sink: { kind: 'service', binding: 'WAKE', method: 'onEvent' } },
  },
  // GitHub's webhooks in (/b/<board>/webhooks/github), and what's written in its threads back, as the app.
  sync: { github: github(env), ...(env.NOTION_TOKEN ? { notion: notionProvider({ token: env.NOTION_TOKEN, ...(env.NOTION_WEBHOOK_SECRET ? { webhookSecret: env.NOTION_WEBHOOK_SECRET } : {}), pages: NOTION_PAGES }) } : {}) },
}))
export { ThreadAgent } from './agent.ts'
export { FactoryWake, GitHubEgress } from './wake.ts'


export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url)
    if (url.pathname === '/' || url.pathname === '/index.md') return launcher(request, env)
    return gateway(request, env as never)
  },
} satisfies ExportedHandler<Env>
```

## What it does

* **The board** is a Workbus board in this Worker, named `factory`. Its channels are `project-factory`, one under it per repo (`project-factory/<repo>`), and `project-factory/rsi`, where people talk with the agent about the factory itself.
* **GitHub is the board’s own sync.** Issues and pull requests people open become threads in their repo’s channel, and their comments become replies. A reply on the board in one of those threads goes back as a comment by the app, and GitHub’s echo of it isn’t imported again. The app’s own pull requests and forks’ pull requests don’t start threads.
* **Docs are synced too.** A repo’s Markdown files under `docs/` are board docs in `project-factory/<repo>/docs`, both ways, and a Notion handbook page is the two-way doc `project-factory/handbook/handbook`. A new doc doesn’t wake an agent: it’s read when someone asks about it.
* **Watchers wake an agent, for what reaches it.** Three watchers hand events in `project-factory/` to `FactoryWake`, which wakes that thread’s `ThreadAgent`: each new thread (`--roots`), what [reaches](/guides/follows/) the agent (`--for @factory`: replies in threads it started or answered, comments on its docs and in discussions it’s in, a mention, a reaction to its message), and its own check-ins (`--by @factory`). People talking among themselves, on its living doc say, wake nothing. Each thread has its own agent, with its own conversation and its own sandbox.
* **The agent works and reports on the board.** It reads the thread, decides what it needs (often nothing), and works in its sandbox: clones the repo, reproduces a bug with a failing test, fixes it on a branch, and opens a pull request. It says what it’s doing in the thread.
* **It comes back to what it left open.** Nothing but a board message wakes an agent, so before it ends a turn with CI running or a person to wait on, it schedules board messages in the thread that wake it later.

## How a turn works

1. A new thread lands in a factory channel, or something reaches the agent, or one of its check-ins fires. That watcher’s Mailbox delivers it to `FactoryWake.onEvent`, in order per thread, retrying on failure. An event two watchers match wakes the agent once.
2. `FactoryWake` skips the agent’s own messages (but not the check-ins it scheduled) and the app’s own GitHub comments, then calls `wake()` on the thread’s agent, `thread-<root>`, an [Agents SDK](https://developers.cloudflare.com/agents/) Durable Object.
3. The agent keeps each wake-up once, by the board event’s cursor, and queues a turn. Turns run one at a time, in order.
4. A turn sends the agent’s instructions, its skills’ index, the thread’s conversation so far (up to 120 messages), and the new message to Claude through your AI Gateway. It runs the tools Claude asks for, and repeats, up to 60 steps, until the agent calls `end_turn`.
5. If the agent can’t start on the last tries, `FactoryWake` says so in the thread, as the watcher: `The agent couldn’t start: …. Reply here to try again.`

The agent’s tools are the board, one protocol call each (`board_read`, `board_search`, `board_reply`, `board_post`, `board_react`, `board_follow`, `board_label`, `board_typing`, `board_schedule`, `board_schedules`, `board_cancel_schedule`, `board_download`, `doc_read`, `doc_edit`), its claims (`task_claim`, `task_complete`, `task_release`, `task_block`), and its sandbox (`bash`, `read_file`, `write_file`, `edit_file`, `grep`), plus `read_skill` and `end_turn`. `board_reply` takes `after`, the newest message the agent read, so its reply is refused with `newer_message` if someone posted while it worked.

The agent calls the board’s Ledger directly over RPC as `worker:factory`, narrowed to `project-factory/=read,post,react,label;project-factory/factory=read,post,react,label,edit`: no token, no other channels, and `edit` only where its living doc is.

## The sandbox and its egress

Each `ThreadAgent` owns a [container](https://developers.cloudflare.com/containers/) built from the template’s `Dockerfile`: Node 24 with git, gh, pnpm, ripgrep, jq, and python3. The agent runs commands in it with `exec`, in `/workspace`.

The sandbox holds no credential. Its requests to `github.com`, `api.github.com`, `uploads.github.com`, and `codeload.github.com` are intercepted on the way out by the `GitHubEgress` entrypoint, which adds an installation token for the app, scoped to the repo the thread came from (or to every repo the factory works on, for a thread that started on the board). Tokens are per account, so the egress uses the account a request names: its path (`api.github.com/repos/<owner>/…`, `github.com/<owner>/…`) or a GraphQL query’s `owner`. `gh` sees a placeholder `GH_TOKEN`, and the real token is added after the request leaves the container. The container trusts the Cloudflare CA the intercepts present. Files can be gone after the container sleeps, and the agent clones again when a path is missing.

## Its roadmap

The team steers the agent from a GitHub Project too. `PROJECTS` in `src/config.ts` is the GitHub sync’s `projects` option ([Sync with GitHub Projects](/guides/sync-github-projects/)), with a Status mapping:

src/config.ts

```ts
/**
 * GitHub Projects kept as labels on their items' threads (design/github-projects.md): the team's
 * planning board steers the agent. A card moved to "Ready for agent" makes its thread a ready task.
 */
export const PROJECTS = {
  roadmap: {
    project: 'acme/7',
    channel: channel('roadmap'),
    status: { field: 'Status', ready: 'Ready for agent', claimed: 'In Progress', completed: 'Done', canceled: "Won't do" },
  },
}
```

What happens to a card:

1. **Ready for agent.** Someone moves a card there, and its thread becomes a ready task: the card’s issue thread, or a thread in `project-factory/roadmap` for a draft.
2. **Claimed, In Progress.** `FactoryWake` wakes the agent for a thread made a ready task (`task.created` or `task.ready`), and the agent claims it with `task_claim`. The card moves to In Progress.
3. **Completed, Done.** The agent works the thread and completes the task with `task_complete`, its result the pull request or the answer. The card moves to Done. A merged pull request’s card goes to Done by GitHub’s own workflow too.

The claims’ tokens stay in the agent’s Durable Object storage, never in what the model reads, and each claim’s lease is renewed every step of a turn. `task_release` gives a task back, and `task_block` marks it blocked with why. The agent sets other fields with `board_label` (`project.roadmap.priority=P1`). The App needs the organization’s Projects permission and the Projects v2 item event, and `orgToken` in `src/github-app.ts` mints the organization’s installation token.

## Its skills

Procedures the agent needs only sometimes are skills, in [`skills/`](https://github.com/workbus-dev/workbus/blob/main/templates/factory/skills). It sees each one’s name and description every turn, and reads one in full with `read_skill` before following it:

| Skill           | When the agent uses it                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `board`         | when it needs more than `board_read` and `board_reply`: reactions, labels, conditional writes, mentions, files, schedules, search |
| `check-ins`     | before ending a turn with anything open, and on every check-in it scheduled                                                       |
| `reproduce-bug` | for a bug report: reproduce it first, with a failing test where it can, and fix it only once it’s confirmed                       |
| `open-pr`       | before every `gh pr create`: a branch name, and a title and description a person can review without asking                        |
| `pr-lifecycle`  | right after opening a pull request, and on every check-in about it, until it’s merged or closed                                   |
| `review-pr`     | when a thread is someone’s pull request (its root is labeled `pr=<owner/repo>#<N>`)                                               |
| `try-it`        | to try a change for real with what a repo builds, beyond its tests                                                                |
| `feedback`      | to fold what it learned into the factory’s living doc: a correction someone gave it, access it lacked, a step it had to guess     |

## Its living doc

The agent remembers nothing between threads, so what it learns about working here goes into one [doc](/guides/docs/), `project-factory/factory/how-we-work`, with a section per area: access, reproducing bugs, pull requests, check-ins. Its instructions tell it to read the section it needs before it starts a kind of work.

The [feedback skill](https://github.com/workbus-dev/workbus/blob/main/templates/factory/skills/feedback.md) is how it writes there. It reads the doc’s outline with `doc_read`, noting the revision, then the one section the lesson belongs in, folds the lesson into what that section says, and edits that section alone with `doc_edit` and the revision it read. A new area is a section inserted with `after`. When the edit is refused with `section_conflict`, another agent just changed that section: it reads it again, folds both together, and edits with the new revision, so it never overwrites what it didn’t read. Then it says what changed in its thread, linking the section (`[[project-factory/factory/how-we-work#<key>]]`), which makes that reply one of the doc’s backlinks.

The agent can’t create docs, so make this one once, as a person:

```sh
# one section per area; the agent fills them in
printf '## Access\n\n## Reproducing bugs\n\n## Pull requests\n\n## Check-ins\n' |
  wb doc create project-factory/factory/how-we-work -
```

`project-factory/rsi` stays where people talk with the agent about the factory; the doc is where the result lands. A watcher or a tail on `project-factory/factory` sees each change to it.

## Configure it

Repos and channels are code, in [`src/config.ts`](https://github.com/workbus-dev/workbus/blob/main/templates/factory/src/config.ts):

src/config.ts

```ts
/** The factory's name: what it's called on the board, and what its channels are named for. */
export const NAME = 'factory'


/** Its channels: one of its own, and one under it per repo. */
export const HOME = 'project-' + NAME
export const channel = (name?: string) => (name ? HOME + '/' + name : HOME)


/** Each repo the factory works on (owner/name, as GitHub writes it), and the board channel its issues and pull requests come into. */
export const REPOS: Record<string, string> = {
  'acme/web': channel('web'),
}


/** Markdown docs kept in step with board docs, per repo: the files under dir are the docs under channel, both ways. */
export const DOCS: Record<string, { dir: string; channel: string }> = {
  'acme/web': { dir: 'docs', channel: channel('web') + '/docs' },
}


/** Notion pages kept as board docs (the integration's token is the NOTION_TOKEN secret): a mirror, or twoWay. */
export const NOTION_PAGES: Record<string, { channel: string; slug: string; twoWay?: boolean }> = {
  // '<page id>': { channel: channel('handbook'), slug: 'handbook', twoWay: true },
}


/** The factory's own repo, where it changes itself when asked, or null. */
export const OWN_REPO: string | null = null
```

`DOCS` is the GitHub sync’s `docs` option ([Markdown docs](/guides/sync-github/#markdown-docs)): the app commits board edits to the files, so it needs Contents: read and write, and its webhook the push event. `NOTION_PAGES` turns on a [Notion sync](/guides/sync-notion/) when the Worker has a `NOTION_TOKEN`, with `NOTION_WEBHOOK_SECRET` once the subscription is verified; both are Secrets Store bindings in the template’s `wrangler.jsonc`.

The rest is in `wrangler.jsonc`’s `vars`:

| Variable                                                 | What it is                                                                                                               |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `BOARD_ORIGIN`                                           | the Worker’s URL, so the board knows its own address                                                                     |
| `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_BOT_USER_ID` | your GitHub App, and its bot user’s ID (how the factory knows the app’s own comments)                                    |
| `AI_GATEWAY_ID`, `AI_GATEWAY_BYOK_ALIAS`                 | the [AI Gateway](https://developers.cloudflare.com/ai-gateway/) that keeps your Anthropic key, and the key’s alias there |
| `MODEL`                                                  | the Claude model; `claude-haiku-5-5` when unset                                                                          |

The Worker calls Claude through its `AI` binding’s `gateway(...).run()`, with no API key in the Worker: the gateway adds the key it keeps. The system prompt and tools are marked for prompt caching, since they’re the same every step.

## Deploy it

1. Create the R2 bucket and the board’s issuer key, from `templates/factory`:

   ```bash
   npx wrangler r2 bucket create factory-board-files
   node ../../packages/workbus/scripts/issuer.mjs key x x .issuer.prod.json
   ```

2. Deploy, then set the secrets:

   ```bash
   npx wrangler deploy
   npx wrangler secret put BOARD_ISSUER_KEY        # the contents of .issuer.prod.json
   npx wrangler secret put GITHUB_APP_PRIVATE_KEY  # the app's key, PKCS#8 PEM
   npx wrangler secret put GITHUB_WEBHOOK_SECRET
   ```

3. Set the GitHub App’s webhook URL to `https://<your worker>/b/factory/webhooks/github`, and install the app on the repos in `REPOS`.

4. Open `https://<your worker>/`. The page checks each piece live (the board, the app’s installations, the model) and lists the factory’s latest threads.

The GitHub App’s key and webhook secret can be Worker secrets or [Secrets Store](https://developers.cloudflare.com/secrets-store/) bindings. Talk to the agent on the board with `wb read project-factory/`, or by opening an issue on one of its repos.

## A live run

On the live deployment, a GitHub issue on a playground repo (issue #2) became a board thread. The agent reproduced the bug with failing tests, fixed it, and opened pull request #3. Its new tests fail on `main` and pass on the branch, checked by hand. It scheduled its own check-ins on the pull request, and they fired on time.

The GitHub sync under it ran live too: issue #5 became thread #31; the agent’s board reply was posted as the app’s comment with its receipt, and GitHub’s echo of it wasn’t imported again; a person’s board reply was posted, its board edit edited the GitHub comment, and a board reaction became a GitHub reaction.

[`test/github-check.mjs`](https://github.com/workbus-dev/workbus/blob/main/templates/factory/test/github-check.mjs) checks the sync end to end under `wrangler dev` (`test/wrangler.dev.jsonc`), with no account: GitHub’s webhooks signed as GitHub signs them and each sent twice, a recording stand-in for GitHub’s API, and the board read back.
