Linked products & the factory lifecycle

Openbook is one of three products that share a Bookbag account and the same organizations. Openbook plans the work, CodeBook executes it, and MadeBook governs it. A workspace here can be linked to its counterpart in each of the other two, and once a workspace is linked to a CodeBook factory, a story on one of its boards can be sent there and worked as a card — with the factory reporting back onto the story as it goes.

This page covers the Openbook side: creating and linking, sending a story, what the card shows, how delivery works, and — because this is new — exactly which steps of the lifecycle have been exercised with the real products and which have not.

The three products

Product	Role	A workspace there is called
Openbook	Plans: stories, boards, the checklist that becomes the acceptance criteria	a space (workspace)
CodeBook	Executes: a factory of workflows whose workers write the code	a workspace, with factories
MadeBook	Governs: supervises each worker session, judges the pull request	a workspace

Nothing crosses between products without a link. A link records that a workspace here and a workspace there are the same work, and both sides store it. Links are what authorize everything else.

Creating a workspace in the siblings

The Create workspace dialog has an Also create it in row with CodeBook and MadeBook. Tick either and the workspace is created there at the same time, and the link recorded on both sides. Each product answers for itself: the space here exists either way, and a sibling that refuses shows up as a toast ("Also created in CodeBook" when it worked) rather than failing the creation.

Linking an existing workspace

Space settings → Linked products lists every link this space has, with a delivery-health line per link, and offers Link CodeBook and Link MadeBook. Pressing one shows Choose a workspace — the workspaces you administer in that product for this organization. If you administer none, or every one is already linked, it says so.

• Linking and unlinking need you to be an admin of the space or of the organization, and the other product checks your role there too, read live from Bookbag SSO. Nothing is taken on trust from the calling product.
• Unlink ends the link and the other product is told ("Unlinked — CodeBook is being told"). Anything issued under that link is revoked, and story revisions still on their way to that factory are cancelled.
• If a message to a sibling has given up, it appears here as failed with a Send again button.

Sending a story to a factory

A story is a Kanban card, and its checklist is its acceptance criteria, in order. On a space linked to a CodeBook factory, the card carries a Factory section:

1. Choose a factory — one of the linked CodeBook workspaces.
2. Workflow (optional) — "The id of a workflow in that factory. Leave it empty to use the factory's first one." Openbook cannot list a factory's workflows, so the id is typed by hand if you want one.
3. Send. The story goes across as revision 1, as you — not as the organization or the space.

From then on, every change to the card's title, description or checklist is sent automatically as the next revision of the same CodeBook card — whether the edit came from the card, its checklist, the board MCP server or the planning agent. A machine's edit is sent as the person who sent the story. Nothing is duplicated: the same revision sent twice gives the same card, and a new revision updates the card's text rather than opening a second card.

Deleting a story card is not sent to CodeBook; the contract has no message for it, so the factory's card stays where it is.

What the card shows

The Factory section shows what CodeBook has reported, most recent first, and each report is one of three events:

Event	What it means	What you see
story.accepted	The factory made a card	Card made — a link to CodeBook's card and the column it landed in
story.status_changed	The card moved, or its worker blocked or resumed	Queued, In progress, Blocked, In review, Done or Dropped, with the column and a reason
story.evidence	There is something to show for it	The pull request link, the MadeBook session and MadeBook's verdict on the pull request

Until the first report arrives the section reads "Waiting for CodeBook to make a card." If you revise a story whose card is already finished, CodeBook says so and nothing is reopened: "CodeBook says this card is already done or dropped. The latest revision was recorded, but nothing was reopened — a person decides that in CodeBook."

A report about an older revision than the one Openbook last recorded, or from a factory other than the one the story was sent to, or over a link that has ended, is ignored.

Delivery: nothing is dropped

Everything Openbook tells a sibling goes through an outbox. Each message is written in the same request as the change, signed, given a key that names the fact, and delivered at once if the sibling is up. If not, it is retried at 30 seconds, then 1, 2, 4 … minutes, up to 30 minutes apart, for 17 attempts (about six hours). The card shows where it stands:

• Revision delivered — arrived.
• Not delivered yet — attempt n of 17, with the last error and when the next try is.
• CodeBook never received this revision — every attempt failed. The message is kept, not dropped, and Send again retries it once you have fixed the cause. The same failure shows in Linked products.
• A revision replaced by a newer one before it arrived, or one whose link ended, is cancelled with the reason.

Every message that comes in is verified over its exact bytes against the shared secret, and its key is claimed before it is applied, so a repeat — or two copies at once — is acknowledged and ignored rather than applied twice.

What has run for real, and what has not

The lifecycle has four steps. Two of them have been run with the three real products on one Bookbag SSO (2026-09-21, fresh databases, a stub model for the worker). Two have only been exercised in each product's own tests against stand-ins for the others.

#	Step	Status
0	A story is written in Openbook and sent to a CodeBook factory, where it becomes a card. Editing the story sends a new revision to the same card.	Ran for real
1	A CodeBook worker picks up the card and appears in MadeBook as a supervised session. It asks a question, a person answers in MadeBook, and the worker resumes and finishes. Pause, resume, a peer that is down and catches up, and unlinking from each side were exercised too.	Ran for real
2	The worker's code becomes a pull request on GitHub, and MadeBook judges it — tests passed, independent approval, open decisions — posting its verdict as the madebook/compliance check.	Never run for real. Covered by MadeBook's compliance tests against a GitHub stand-in that sends real signed webhooks.
3	MadeBook tells CodeBook the verdict changed, and CodeBook passes it to Openbook as the story's evidence, so the story shows the pull request link and "it passed".	Never run for real. Covered by CodeBook's and Openbook's end-to-end tests against stand-ins.

So, concretely: the Card made and status reports on the Factory section have been seen from a real factory; the pull request and verdict on the Factory section have only ever been produced by a stand-in. Steps 2 and 3 need an actual pull request on a repository that a MadeBook workspace is watching, and the real run had no repository connected.

Running steps 2 and 3 yourself

In any environment where all three products run with the same peer secret and each other's addresses, with the Openbook space, the CodeBook workspace and the MadeBook workspace linked:

1. Connect a throwaway repository to the MadeBook workspace and to the CodeBook workflow, and turn on Open draft pull requests on the station whose worker writes the code. The worker then commits to a branch and opens a draft pull request; it never merges.
2. Turn compliance on for the MadeBook workspace — monitor posts a neutral check and blocks nothing, which is the right first test.
3. Send a story from Openbook and move its card to that station.
4. Expect, in order: the madebook/compliance check on the pull request; the verdict on MadeBook's Pull requests page; the verdict on the CodeBook card; and finally the pull request link and verdict in the story's Factory section here.
5. Change the verdict — approve as someone who did not write it, or push a commit — and all three should update again.

If something does not arrive it is not lost: each product's Linked products lists what it owes the others with a status and last error, and a failed message can be retried from there.

For operators

Peer messaging needs, on the Openbook server: PEER_SECRET (the same on all three products), the siblings' API addresses (PEER_CODEBOOK_URL, PEER_MADEBOOK_URL), and Openbook's own public API address (OPENBOOK_PUBLIC_API_URL), which is what CodeBook reports back under. Without that last one the Factory section says why no story can be sent. None of this is behind a feature flag: once configured and linked, it is on.

Where to go next

• The build agent — the agent that works a story on Openbook's own engine, without leaving the product.
• Board MCP server — editing a story from your own Claude or ChatGPT, which also sends revisions to the factory.
• Kanban — the board and card the story lives on.