The brief

Exactly what an agent is given before it writes anything — the eight sections in order, where each comes from, the budget, and the manifest that makes it auditable.

The brief is the whole before half of the product. Constraint applied at the start costs nothing; the same constraint applied at the pull request costs the whole branch.

An agent receives one when it opens a session, and again every time it re-briefs.

The eight sections, in order

The order is not arbitrary. It is stable-prefix-first, which is what makes prompt caching work, and it is also the model's priority order.

# Section Where it comes from Share of the budget
1 Role and policies The organization's approved policies not budgeted
2 Architecture constitution The current constitution and its rules not budgeted — never truncated
3 Skills The skill router, at pinned versions 18%
4 Decisions already made Active decisions, scope-matched 5%
5 Workspace and context The workspace's mission and objective, plus the context brain 17%
6 Mission contract The mission, verbatim 5%
7 Repository Tree skeleton, manifests, selected files 50%
8 The task The caller's own intent —

The total budget is 160,000 characters — roughly 40,000 tokens, which leaves generous room for output on a 200,000-token model.

The constitution is deliberately outside the budget. The rules an agent is held to are never the thing that gets cut.

1. Role and policies

The role an agent is given, verbatim:

You are an AI coding agent working inside a Madebook-supervised session. Madebook is the layer that holds the rules, the memory and the other sessions; you report what you change and it tells you what that means.

Then ## Policies in force, with the preamble "These are the organization's rules. They are checked by Madebook on every change you report." Each policy renders as its name, severity, what triggers it, what happens, and its description.

2. The constitution

Every rule with its ruling, rationale, confidence, whether it is enforced, and its do-not-use list. A draft constitution is labelled "DRAFT — not yet approved, advisory only."

3. Skills

Router-selected, at pinned versions, with up to three examples each. The section's own instruction is careful about precedence:

Follow them unless the constitution, a decision or a security rule contradicts one, in which case the workspace wins and you should say so.

4. Decisions

See Decisions for exactly how scope matching works.

5. Workspace and context

The workspace's mission, business objective, target date and description, then the context brain in this order:

  1. What this product does
  2. Business constraints
  3. Architecture
  4. Data flow
  5. Technology stack — confirmed only
  6. Engineering standards — confirmed only, grouped by category
  7. Security rules — "these are not negotiable"
  8. Known problems — open only
  9. Organization preferences

Security rules sit last within the section, on purpose: that is the position a model weights most.

With no context at all, the brief says so rather than saying nothing:

Not yet filled in. You have no stated architecture, standards or security rules for this workspace. Where you need one, say what you assumed rather than presenting a guess as fact.

6. The mission contract

Every clause, verbatim, with its verification state.

7. The repository

The tree skeleton, the manifests, then lexically selected files expanded by one hop of the module graph. Files matching a secret pattern are excluded unconditionally.

For an agent's session brief, file bodies are not included:

File bodies are the agent's to read — it has the checkout. The brief carries the index and the digest, not a second copy of the code.

What else the reply carries

A brief is not only prose. Alongside the assembled package, it carries:

Field What it is
next_action and its reasons See the execution protocol.
blocked_scope / allowed_scope What may not and may proceed.
resolved_decisions Anything a person decided since the agent last looked — handed over once.
new_remediations Fixes it has been asked to make.
stop_requested and pause_reason Whether a person pulled the brake.
instruction The one instruction for this moment.
plan The execution plan with its step counts and the active step.
context_health The six dimensions, the verdict, and whether a re-brief is recommended.
other_sessions What every other live session is touching.
protocol The full execution protocol text.
warnings Anything that was empty or truncated.

other_sessions

This is the part no single-agent tool can give an agent. Each live session in the workspace, with the symbols it has touched and whether their shape changed. The guidance attached to it:

Other sessions are live in this workspace. Before changing the shape of anything listed under other_sessions.touching, report it — Madebook will tell the affected session.

Or, when there are none: "No other sessions are live in this workspace right now."

The manifest

Every item in the package is recorded. For each one: its kind, its reference, the entity it came from, its version, an approximate token count, and the reason it was selected.

That record is what makes "why did it say that" an answerable question. The model is never asked which files it consulted, because Madebook chose them.

For a session, the manifest is frozen as a context snapshot and the session is stamped with the constitution version, the mission version, the skill versions, the policy count and the decision count it was briefed on. Those stamps are what drift detection later compares against.

Truncation is announced

When a section will not fit, the lowest-ranked items in it are dropped, the text gains … [{section} shortened to fit the context budget], and a warning is added to the reply.

Warnings you may see:

  • "This workspace has no Workspace Brain yet. Fill it in — business context, stack, standards and security rules — and the output of this and every future run improves substantially."
  • "No repository is connected to this workspace, so nothing here is grounded in real code."
  • "{repository} has not been indexed yet."
  • "The repository is larger than the context budget, so only part of it was included. Ask a narrower question, or name the area you care about, for a more grounded answer."
  • "The {section} section was too large for the context budget and was shortened."

Side effects of briefing

Calling for a brief does five things to the session:

  1. Writes the context snapshot and links it.
  2. Stamps briefed_at and the versions it was briefed on.
  3. Moves the session from starting to working.
  4. Clears any pause — though the brief still reports the pause and its reason, so the agent knows why it was stopped.
  5. Records context health.

It also writes a timeline event naming what went in:

Briefed: 8 contract clause(s), 12 constitution rule(s), 4 decision(s), 3 skill(s), 6 policy(ies), and 2 other live session(s). ~31,400 tokens.

← PreviousDecisionsNext →Missions