Skip to content
CodeBook

Linked products — MadeBook, OpenBook and EvalBook

Link a workspace to MadeBook, OpenBook and EvalBook, run work under MadeBook governance, receive stories and epics from OpenBook and report back, gate a station on an EvalBook suite, and verify a linked story from plan through pull request evidence.

CodeBook is one of four Bookbag products that share a lifecycle: OpenBook plans the work, CodeBook executes it, MadeBook governs it, and EvalBook evaluates it. A CodeBook workspace can be linked to a MadeBook workspace, to an OpenBook space and to any number of EvalBook projects. 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.

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, a native 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.

In a linked workspace, CodeBook registers its native worker runs and governed crew runs as MadeBook sessions. An external worker runtime uses its own execution path. A supervisor attending a governed card has its own supervised session.

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).

EvalBook

EvalBook is Bookbag's evaluation product. A workspace administrator links an EvalBook project under Workspace settings → Linked products (EvalBook is never offered when a workspace is created). With a project linked, four things happen, and nothing without the link.

A station can require an EvalBook suite. In a station's evaluators, choose An EvalBook suite, the linked project and one of the suites EvalBook lists for it (optionally pinned to a version, and with a most-per-evaluation in US dollars). After the station's worker passes, CodeBook asks EvalBook to evaluate the exact candidate — the card, the open pull request's head and base commits as the repository host reports them at that moment, the repository, and a digest of what the run attached — and the run waits ("Waiting for EvalBook") until EvalBook's report arrives or the two-hour deadline passes. The decision is CodeBook's, from the report it fetches and verifies: a pass only when the report's digest matches its contents, it is this organization's, this exact candidate's, this suite's and version's, current, not expired, with complete evidence and every required check passed, and the pull request has not moved since. Anything else — EvalBook's fail, error or inconclusive, a check reported missing, stale or unsupported, a superseded, expired or tampered report, a deadline that passed, EvalBook unreachable — is "cannot tell" with the reason, which blocks a required evaluator exactly as a fail would. Advisory suites are recorded and measured only. Cancelling the run cancels the evaluation at EvalBook. The card's Evidence shows each evaluation with what was asked, what came back and a link to EvalBook's report; the run's evaluations and the operations center ("Waiting on EvalBook") show the same.

One authoritative gate per criterion. An agent evaluator and an EvalBook suite may both say what they measure (a short criterion key). A station whose required evaluators include both on the same criterion cannot be saved until a workspace administrator records a cutover saying which one decides; the other then runs as a shadow — recorded and measured, never deciding. Editing the station otherwise needs only write access; changing the cutover is the administrator's act.

Runs can be exported as traces. Per link, an administrator switches trace export on, with or without the runs' bodies. Every run that finishes afterwards goes to the project as one signed, idempotent batch of spans (the run, each model it used, each tool call, each evaluator verdict, with links to the card, the run, its artifacts and the pull request). Bodies go only when the link sends them and this workspace's retention keeps them; under a MadeBook link with a stricter retention they stay back, and the page says so. A batch EvalBook could not take gives up visibly under Linked products with Send again. Export never holds a run.

Improvement proposals arrive as cards. EvalBook sends a proposal (a problem it found, a hypothesis, how to reproduce it, the reports it was drawn from, a bound and the paths that must not be touched) to a workflow here; CodeBook makes one card per proposal, "From EvalBook proposal #N", in that workflow's first station. The bound — at most N runs, a deadline, a budget — is enforced by the run limits, not asked of a model; a run past it does not start, and an unpriced model counts as unmeasured, not as free. The protected paths are a refusal list every repository-writing tool checks before anything reaches the host; a refused write is recorded on the run. The card reports its progress back to EvalBook as it moves.

Outcomes are told to EvalBook. Everything CodeBook records about what became of finished work — a card finished or dropped, its pull request merged, closed or reverted, a reopen, a deploy, a production issue, a person's override, a withdrawn report — goes to each linked project as one signed, idempotent outcome.observed message, through the same outbox that shows under Linked products. EvalBook decides what each means (a completion is self-declared done, not acceptance). The factory's Outcomes page gains What EvalBook observed: EvalBook's own funnel of the factory's work — declared done, accepted, deployed, observed success — in EvalBook's words, never a re-count of CodeBook's figures. A project EvalBook cannot answer for is said so, not shown as zeros.

Every call between CodeBook and EvalBook is signed over its raw bytes and keyed so a retry is acted on once; every event names the link it travels on; a message for a link that has ended is acknowledged and ignored. The message contract is EvalBook's peer protocol, with CodeBook's readings recorded in its own peer protocol document.

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.

Verify a linked story

Choose a test repository and a workspace where you can see all linked products. The steps below create a card, a governed run and a draft pull request.

  1. Connect the same repository in MadeBook and to the CodeBook workflow. Enable Open draft pull requests on the station doing the work. In MadeBook, enable compliance in monitor mode.
  2. Send a small story from OpenBook. Confirm that CodeBook creates a card for the correct revision in the intended workflow. Move it to the writing station and open its MadeBook session. For a requested decision, answer in MadeBook and check that CodeBook resumes the same session.
  3. On the draft PR, open the GitHub check named madebook/compliance and compare its head commit and verdict with the pull request in MadeBook and the MadeBook panel on the CodeBook card.
  4. Open the original story in OpenBook and verify its PR link and evidence. If one product is missing an update, check Workspace settings → Linked products in the sending product for a pending delivery or last error. Repair the link or configuration and retry the delivery there.

For incident rules, confirm the governed run’s report includes the approved rule, service-owner reference and result for the same candidate commit. Use the linked EvalBook project to inspect its own station evaluation. Governance handoff · Incident checks