Linked products & the factory lifecycle

Openbook is one of three products that share a Vibeforce 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, sending an epic and approving its plan, 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 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 a workspace dialog has an Also create it in row with CodeBook and MadeBook — The same workspace, under <organization>, owned by you. Each product answers for itself. Tick either and the workspace is created there at the same time, and the link recorded on both sides. The workspace 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

The workspace's Settings → Linked products lists every link this workspace 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 workspace or of the organization, and the other product checks your role there too, read live from Vibeforce 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.
• A CodeBook link has an Epics sent to CodeBook — plans to approve link, which opens the workspace's Epics page. See Epics.

Sending a story to a factory

A story is a Kanban card, and its checklist is its acceptance criteria, in order. On a workspace 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 workspace.

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.

Epics

A story is one card. An epic is a larger piece of work: a card whose stories hang under it as child cards (epic → story → subtask, one level at a time), with acceptance criteria that say how anyone can tell the whole thing is done.

The planning tools of the build agent and workflows can write one for you. Ask an agent room to plan an epic and its create_epic tool puts it on a board: the epic card, its acceptance criteria as the card's checklist, and the stories you already know as child cards. Like every other planning tool it writes cards a person can review, and a room in a plan-only mode will not run it.

An epic can also be sent to a linked CodeBook factory, where it becomes one work order. Its child stories go with it, so the factory's planner does not propose them again. The planner proposes the stories that are still missing, and nothing is built until you approve them here.

Sending an epic and approving its plan

Epics are sent from the workspace's Epics page, /space/<id>/epics. To open it, go to Settings → Linked products and choose Epics sent to CodeBook — plans to approve under the CodeBook link. The page lists every card marked as an epic on the boards you can read, with how many stories each already has and where it stands (Not sent, Sent, Plan to review, Approved, In progress, Done and so on). Choose an epic to open its panel.

1. Mark the card as an epic on its board if it is not one yet. Its checklist is the acceptance criteria, and its child cards are the stories you have already written.
2. Choose the factory. If the workspace is linked to more than one CodeBook workspace, pick the Linked CodeBook workspace first. Then type the Factory, which is the factory's id in CodeBook. CodeBook does not publish a list of its factories, so the id is typed by hand. An epic is planned across all of one factory's workflows.
3. Send to CodeBook as an epic. It goes across as revision 1, sent as you. CodeBook opens a work order (for example WO-9) and its planner writes the plan right away. If CodeBook refuses the epic (for example because no factory has that id), the panel says so at once in CodeBook's words. Correct the epic and send it again.
4. Review the plan. The plan CodeBook proposed shows the planner's summary, what it left out of scope, and each proposed story with its risk. If the planner stopped (its budget ran out, or the epic was too vague to divide), the panel says why.
5. Approve. Tick the stories you want and press Approve n selected, or press Approve all n proposed with nothing ticked. Only the stories you saw are approved: a story the planner adds later is never approved by accident. Approved stories become cards in the factory. Anything CodeBook could not make yet is listed under Not made or Waiting, with the reason.
6. Follow it. The panel shows the epic's status, the revision that was sent, the work order, and the delivery of each message. A story that became a card shows Card made.
7. Send again after a change. Unlike a story, an epic is not re-sent automatically when you edit it. The panel says "This epic has changed since revision n was sent", and Send revision n+1 sends the change. CodeBook rewrites the work order's goal but keeps the plan it already wrote. Pressing Send when nothing changed sends nothing.

Reading the Epics page needs read access to the epic's room. Sending and approving need write access, the same as editing the card. If the workspace is unlinked, nothing more is sent and later reports from that factory are ignored.

Progress per story does not come back yet. CodeBook reports the plan (epic.planned) and answers each approval with the cards it made. Openbook is also ready to show each story's status and evidence, and roll them up into the epic's own status (epic.status, epic.evidence), but CodeBook does not send those reports yet. To follow the cards once they are made, look at the factory in CodeBook.

An epic card's own Factory section still sends the card as a single story, like any other card. To send it as an epic, use the Epics page.

Sending an epic has been run end to end against a real CodeBook: a two-story epic became work order WO-9, CodeBook's planner proposed its stories, and the epic.planned report was applied here. The message contract is in the peer protocol (Epics (OpenBook → CodeBook)).

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 Vibeforce 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 workspace, 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 is configured at Vibeforce SSO, not on the Openbook server. SSO's app registry holds each product's public address and API base, and the deployment-wide peer secret; Openbook reads them with its app token at startup and refreshes them every minute. When the secret is rotated at SSO, the one it replaced is still accepted for an hour, so no sibling is cut off mid-rotation. If Openbook's own API address is not registered, the Factory section says why no story can be sent. None of this is behind a feature flag: once registered and linked, it is on.

For local development only, PEER_SECRET, PEER_CODEBOOK_URL, PEER_MADEBOOK_URL and OPENBOOK_PUBLIC_API_URL in the environment override what SSO says.

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.