Linked products — MadeBook and OpenBook

CodeBook is one of three Bookbag products that share a lifecycle: OpenBook plans the work, CodeBook executes it, and MadeBook governs it. A CodeBook workspace can be linked to a MadeBook workspace and to an OpenBook space. The link is what authorizes everything else on this page; an unlinked workspace runs exactly as it always has.

Open Workspace settings → Linked products. It lists the links, links an existing MadeBook or OpenBook workspace, unlinks, picks the workflow that stories from OpenBook land in, and shows any message CodeBook still owes a peer, with a Retry button.

Links

A link records that a workspace here and a workspace there are the same work. Both products store it. A link is recorded when a workspace is created in a sibling product, or when an administrator links two existing workspaces from either side. Linking and unlinking need a workspace or organization administrator; the peer reads that person's role live from Bookbag SSO, never from what the calling product claims.

Every call between the products carries the shared peer secret and names the calling product. Callbacks and link events also carry an HMAC signature over the raw body, and each carries an idempotency key so a repeated delivery is acted on once. A refusal is always a non-2xx answer, so the sender retries rather than assuming success.

Unlinking from either side ends the link and revokes anything issued for it, including the credential a governed factory was using. A callback that arrives for a link that has ended is acknowledged and ignored.

Governed runs under MadeBook

In a factory whose workspace is linked to MadeBook, each AI worker job becomes a MadeBook session. Before the run counts, CodeBook registers the job with MadeBook using the job ID as its external ID, so a retry or a resumed job gets the same session. The brief goes into the worker's system prompt, the worker gets a request_decision tool, every report carries a report ID so a retry records nothing new, and the worker must submit implementation-complete before the card may reach Done.

The credential CodeBook uses is requested from MadeBook for the linked workspace, stored encrypted, and requested again once if MadeBook answers 401. MadeBook must have approved codebook as a client for the organization; it is never approved automatically.

Every MadeBook reply carries a next_action, and CodeBook obeys it:

• Continue (with or without a warning) carries on.
• Remediate fixes what MadeBook names.
• Decision required parks the job until a person decides in MadeBook and the decision.resolved callback arrives.
• Blocked and hard stop stop the job where it is.

Pausing and resuming a session in MadeBook arrive by callback and pause or resume the job. If MadeBook cannot be reached, the job waits as awaiting MadeBook, the card says why, the scheduler retries, and the card offers Retry now. A governed run never runs ungoverned because MadeBook did not answer.

Only stations worked by CodeBook's own AI agents are registered as MadeBook sessions. Stations worked by outside runtimes, crews or another factory are not.

Beyond starting and stopping, CodeBook enforces MadeBook's answers at the moment it acts: it asks before every model a governed run uses, tells MadeBook when a session ends for any reason, reports its own contract and evaluator results as evidence, sends its governance events to MadeBook's audit trail and keeps run bodies only as long as the organization's retention settings allow. See the governance handoff.

Stories from OpenBook

OpenBook sends a story to a factory, and CodeBook makes one card for it in the workflow chosen under Linked products. A story can name a workflow by ID or by name. A resend of the same revision is answered as a duplicate, an older revision as stale, a newer revision updates the card, and a story whose card has been closed is reported as closed.

Epics from OpenBook

An epic is bigger than a card. OpenBook sends one to a factory, which it names by the factory's numeric id; an epic is not sent to a single workflow. CodeBook makes the epic a work order in that factory. The work order gets the epic's title, and a goal made of the epic's description, its acceptance criteria and any stories a person already wrote under it. The planner is told not to propose those stories again. It runs at once and proposes the missing stories, choosing each one's workflow in the factory. CodeBook reports the plan back (epic.planned): each proposed story with its description, risk and category, plus the plan's summary, what is out of scope, and why the planner stopped if it did.

Nothing is built yet. The stories stay proposals until a person approves them in OpenBook. The approval names the exact stories the person saw, and CodeBook turns those into cards in their stations, the same way approving a work order's plan in CodeBook does. Stories still waiting on a dependency stay proposed and are listed as waiting. A resend of the same epic revision finds the same work order. A newer revision rewrites the goal without planning again, and the work order stays in the factory where it was first planned.

An epic's text is data. It becomes the work order's goal, which the planner reads as the task, never as instructions.

In OpenBook this happens on the workspace's Epics page (/space/<id>/epics), which is linked from its Workspace settings › Linked products. There a person sends an epic card to the factory, reviews the plan the planner proposed, approves some or all of the stories, follows the epic's status and each message's delivery, and sends a new revision after changing the epic. CodeBook has no list of factories for OpenBook to show, so the person types the factory's numeric id.

Two limits apply today. CodeBook reports only the plan (epic.planned). OpenBook learns which cards an approval made from CodeBook's answer to the approval, but no per-story progress or evidence goes back for an epic's cards. To follow them, look at the work order in CodeBook. The message contract is in the shared peer protocol, under Epics (OpenBook → CodeBook).

Reports to OpenBook

CodeBook keeps an outbox of what it owes a peer:

• story.accepted when a story becomes a card.
• story.status_changed on every card move, block and resume.
• story.evidence when a pull request is attached to the card, and when MadeBook's compliance verdict on that pull request changes.
• epic.planned when an epic from OpenBook has been planned: the stories the planner proposed, for a person to approve.
• link.unlinked when a link ends here.

Each message is signed, keyed for idempotency and retried with backoff. After the last attempt it is marked failed, never dropped, and shown under Linked products and on the card so a person can send it again.

What the card shows

A card that came from a story, or that is running under MadeBook, has a MadeBook and OpenBook panel: the story and what OpenBook sees, the governed session with a link into MadeBook, the decisions made, any hold, and the compliance verdict once one has arrived.

Configuration

Nothing is configured on CodeBook's server or in the workspace. CodeBook reads the peer directory from Bookbag SSO's app registry with its own app token: the sibling products with their names and API bases, CodeBook's own public API base, and the shared peer secret. Each product is registered once, under Platform admin → Apps at SSO, and an address that is wrong is fixed there.

CodeBook keeps the answer for a minute, refreshes it in the background and keeps the last good answer through an SSO outage; before its first answer it has no peers. When the secret is rotated at SSO, the previous one is still accepted for one hour so a sibling is not cut off mid-delivery; only the current one signs. A product switched off at SSO is an answer, not an outage: its peers disappear until it is switched on again.

A callback address is accepted only under the peer's API base from the directory, and CodeBook tells MadeBook to call it back under its own. PEER_SECRET, PEER_<APP>_URL and CODEBOOK_PUBLIC_API_URL still exist as local-development overrides; when one is set it wins and CodeBook logs that it is in effect. Production sets none.

What has run for real, and what has not

The lifecycle has four steps. "Ran for real" means the three actual products, on one Bookbag SSO, talking to each other with nothing standing in (21 September 2026, fresh databases, a stub model for the worker). "Stand-ins only" means each product's own tests against a fake of the others or of GitHub.

#	Step	Status
0	A story is written in OpenBook and sent to a CodeBook factory, where it becomes a card (story.accepted). 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 (decision.resolved comes back), 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. MadeBook judges that pull request (tests passed, independent approval, open decisions) and posts its verdict as the madebook/compliance check.	Never run for real. Covered by MadeBook's compliance smoke suite against a GitHub stand-in that sends real signed webhooks.
3	MadeBook tells CodeBook the verdict changed (compliance.changed). CodeBook passes it to OpenBook as the story's evidence (story.evidence), with the pull request link and the verdict.	Never run for real. Covered by CodeBook's and OpenBook's end-to-end tests against stand-ins.

Steps 2 and 3 need an actual pull request on a GitHub repository that a MadeBook workspace is watching. The real run had no repository connected, so there was never a pull request to judge.

To test them yourself: connect the same repository to the MadeBook workspace and to the CodeBook workflow, turn on Open draft pull requests for the station whose worker writes code, turn compliance on in MadeBook (monitor first), send a story from OpenBook and move its card to that station. Expect, in order, the madebook/compliance check on GitHub, the verdict on MadeBook's Pull requests page, the verdict in the card's MadeBook panel, and the pull request link and verdict on the story in OpenBook. If a message does not arrive it is not lost: each product's Linked products page lists what it owes with the last error.