brandbook.md Specification

brandbook.md is a standard for actionable brand books: brand governance that people can maintain and AI agents can act on. It defines how a brand’s knowledge is packaged — structure, metadata, versioning, multi-market support, hierarchy, and progressive disclosure for AI context efficiency — and leaves which marketing framework that knowledge follows to the brand. Optional named profiles (§1.1) layer content models on top of the structural base. It is a governance standard for brand organisations, not a brand-identity file for dev projects.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.

1. Purpose and scope#

A brandbook package is a folder of Markdown files with YAML frontmatter that encodes a brand’s growth-critical knowledge: its assets, audience definition, voice, entry points into buying situations, and non-negotiable rules — in whatever marketing framework the organisation works, plus the governance metadata (versioning, validation dates, review cycles) that makes the package trustworthy over time.

The standard’s organising principle is actionability. Traditional brand books open with mission statements and essays; the rules a designer, copywriter, or AI agent actually needs are buried somewhere behind them. A brandbook package inverts that: every line in a core file is something a person or an agent can act on, and the narrative material keeps a home of its own (see context/, §2 and §5.2).

The standard serves two consumers with one artefact:

1. Humans: brand managers, agencies, and approvers who need a current, unambiguous source of truth instead of a stale PDF.
2. Machines: AI agents, MCP servers, and validation tooling that generate, review, or approve brand-facing output.

This specification is deliberately methodology-agnostic. It is normative about the machine contract — package structure, frontmatter, the files: index, citable IDs, inheritance, and how agents consume packages — and takes no position on the marketing framework a brand uses. Personas or category buyers, archetypes or distinctive assets: any school of brand thinking fits the same structure, because a consuming agent works with whatever knowledge the package carries. What the agent depends on is the structure around that knowledge, and that is what this document specifies.

1.1 Profiles#

A profile is a named, optional content model layered on the structural base: it recommends which knowledge a package should carry and how the root should be organised. A package opts in by declaring the profile in root frontmatter (profile:, F-14); packages that declare no profile are complete, first-class citizens of the standard. Profile rules are advisory — validators surface them as warnings, and no profile outcome affects conformance (§9).

This repository ships one profile: evidence-based, grounded in the marketing science of Byron Sharp, Jenni Romaniuk, and Mark Ritson. It is the content model the authors of this standard use and recommend — and, like every profile, required by nobody.

1.2 Other standards#

brandbook.md is one of several open standards for machine-readable brand knowledge. The standards landscape names the alternatives, compares them honestly, and helps you choose; interoperability between standards is a goal, not a turf war.

2. Package structure#

A brandbook package is a directory. Directory names are a human convenience (S-03); a typical layout — this one from a package using the evidence-based profile — looks like:

brand/
├── BRANDBOOK.md          ← Primary file. Always loaded. REQUIRED.
├── assets/
│   ├── dba-inventory.md  ← All Distinctive Brand Assets + usage rules
│   └── files/            ← Binary/machine-readable assets (logos, fonts, tokens)
├── voice/
│   └── verbal-identity.md
├── ceps/
│   └── category-entry-points.md
├── audience/
│   └── buyers.md
├── governance/
│   ├── anchor-rules.md
│   └── legal.md
├── evidence/
│   └── tracking.md
├── portfolio/
│   └── portfolio.md      ← Product ranges + the CEPs they serve
└── context/              ← Narrative home: mission, vision, values, heritage.
                            Not loaded by agents unless explicitly requested.

Rules:

• S-01. The package root MUST contain exactly one file named BRANDBOOK.md (uppercase, like README.md). Rationale: a fixed, cased entry point makes discovery trivial for both humans and tooling.
• S-02. BRANDBOOK.md MUST NOT exceed approximately 5,000 tokens; authors SHOULD target 3,000. Rationale: the root file is always loaded into agent context; progressive disclosure fails if the router itself is bloated.
• S-03. Secondary files MAY be organised in any directory layout; the canonical layout above is RECOMMENDED. The files: index (§3), not the directory tree, is normative. Rationale: tooling navigates by index, so directory names are a human convenience.
• S-04. A directory named context/ MAY exist in the package. It is the home for narrative material: mission, vision, purpose, values, manifestos, brand history, and anything else that matters to the organisation but is not an operational instruction. Tooling MUST NOT load it by default and MAY offer it on explicit request (§6.7). The legacy name misc/ is treated the same way. Rationale: narrative content has real cultural value, and it keeps that value best in a place where it cannot crowd operational rules out of agent context.
• S-05. Binary and machine-readable design assets (logos, fonts, colour tokens) SHOULD live under assets/files/. Colour and typography tokens SHOULD use the W3C Design Tokens Community Group format (tokens.json). Rationale: aligning with the emerging design-tokens standard avoids inventing a parallel format. (Non-normative recommendation; see Open Questions.)
• S-06. A directory inside a package that contains its own BRANDBOOK.md is a child package (§7), not part of the parent’s file tree. Parent tooling MUST NOT index or warn about a child package’s files; the child is validated as a package of its own. Rationale: nesting is how brand architectures compose (§7); treating a child’s files as unindexed strays would make every multi-brand repository fail its parent’s hygiene checks.

3. Root frontmatter (BRANDBOOK.md)#

The root file MUST begin with a YAML frontmatter block. Machine-readable schema: schema/brandbook-root.schema.json.

---
standard: brandbook.md
spec_version: "0.1"
profile: evidence-based    # optional content profile (§1.1)
brand:
  name: Acme Hot Sauce
  slug: acme-hot-sauce
  owner: Acme Foods Ltd.
  category: "Hot sauce / chilli condiments"   # buyer-term category, not self-image
markets: [US, GB, DE]
languages: [en, de]
default_language: en
maintainer: brand@acmefoods.example
version: "2.3.0"
last_validated: 2026-07-07
review_cycle: P6M
confidentiality: internal
files:
  - path: assets/dba-inventory.md
    type: dba
    summary: "All Distinctive Brand Assets incl. usage rules"
  - path: ceps/category-entry-points.md
    type: cep
    summary: "Prioritised CEPs per market"
  - path: governance/anchor-rules.md
    type: governance
    summary: "Non-negotiables and approval processes"
---

Field rules:

• F-01. standard MUST be the literal string brandbook.md; spec_version MUST name the spec version the package conforms to. Rationale: lets tooling detect the format and version without heuristics.
• F-02. brand.name, brand.slug, brand.owner, and brand.category are REQUIRED. brand.slug MUST be a lowercase kebab-case identifier; secondary files reference it. Rationale: a stable slug lets tooling join files to their brand without path guessing.
• F-03. brand.category MUST describe the category in buyer terms (what a buyer would call the shelf or search category), not in self-image terms (“lifestyle companion”). Rationale: strategy starts with honest diagnosis; a self-flattering category definition corrupts everything downstream.
• F-04. version MUST follow Semantic Versioning 2.0.0: major for strategy changes (category, positioning, buyer definition), minor for content changes (new CEP, revised rule), patch for corrections. Rationale: consumers can pin to a major version and know that brand strategy has not shifted underneath them.
• F-05. last_validated (ISO 8601 date) is REQUIRED. review_cycle (ISO 8601 duration) is OPTIONAL but RECOMMENDED (P6M is a sensible default); when present, tooling SHOULD warn when last_validated + review_cycle is in the past. A package without review_cycle receives no freshness warnings. Rationale: a brand file that cannot expire silently rots, exactly like the PDFs this standard replaces; the date is mandatory, the review commitment is the maintainer’s to make.
• F-06. markets (ISO 3166-1 alpha-2 codes) and languages (BCP 47 tags) are REQUIRED, each with at least one entry; default_language MUST be one of languages. Rationale: multi-market support cannot be retrofitted; single-market brands simply list one entry.
• F-07. maintainer (a contact for questions and changes) and confidentiality are OPTIONAL. confidentiality, when present, MUST be one of public | internal | restricted; when absent it defaults to internal. Tooling MUST NOT expose internal or restricted packages (including packages that omit the field) to unauthenticated consumers. Rationale: brand books routinely contain unreleased campaign material, so the default errs towards privacy; ownership is usually recoverable from version control, so maintainer is a convenience, not a gate.
• F-08. files is the machine-readable index of secondary files and is REQUIRED (it MAY be an empty list for a minimal single-file package). Each entry MUST have path (relative, POSIX separators), type (§4), and summary (200 characters or fewer). Entries MAY have scope (list of market codes) and language. Rationale: the index is the MCP interface. A server answers “what does this package know?” from frontmatter alone, with no Markdown parsing.
• F-09. Every secondary file that tooling should see MUST appear in files:. A file on disk but not in the index is invisible to conforming tooling (except context/, which is handled by S-04). Rationale: the index must be trustworthy or agents will fall back to directory scanning, defeating progressive disclosure.
• F-14. profile is OPTIONAL. When present it MUST be a lowercase token naming a content profile (§1.1); the well-known value is evidence-based. Tooling MUST apply a profile’s checks only when it recognises the declared value, SHOULD warn on an unrecognised value (“unknown profile; no profile checks applied”), and MUST NOT treat any profile outcome as a conformance failure. profile applies to its own package root only and is never inherited (§7): in a multi-brand estate, each child that wants a profile’s checks declares it itself. Rationale: profiles are advisory content models; an unknown profile is a coordination gap between package and tooling, not an invalid package.

4. Secondary-file frontmatter#

Every file listed in files: MUST begin with a lean YAML frontmatter block declaring at least type. All other fields are OPTIONAL but RECOMMENDED. Rationale: the frontmatter is what tooling reads first; a file that cannot state its kind cannot be selected by kind. Machine-readable schema: schema/brandbook-file.schema.json.

---
standard: brandbook.md
type: dba                  # well-known or custom token (F-10)
brand: acme-hot-sauce      # slug, references root brand.slug
version: "1.4.0"
last_validated: 2026-05-12
scope: [US, GB]            # optional; default = all markets in root
language: en               # optional; default = root default_language
---

• F-10. type MUST be a lowercase token matching ^[a-z][a-z0-9-]*$. The well-known types below have defined semantics, and a file that uses one MUST observe that type’s rules; any other token is a custom type and is equally valid. Rationale: well-known types keep select-by-kind loading (“load the governance files”) portable across packages and tools, while the mandatory summary in the files: index (F-08) makes custom types discoverable to agents. A closed list would force a marketing methodology on every package — that is a profile’s job (§1.1), not the base standard’s.

• F-11. brand, when present, MUST equal the root brand.slug. Rationale: guards against files copied between brand packages without review.
• F-12. Secondary files SHOULD carry their own version and last_validated. Rationale: a brand’s CEP research and its logo rules age at different speeds; per-file freshness keeps review cycles honest.
• F-13. scope restricts a file to listed markets; omitted means all root markets. Every market in a scope MUST be one of the root markets. When both the file’s frontmatter and its files: index entry declare type, scope, or language, the values MUST match; when only one side declares a value, validators SHOULD warn. Rationale: contradictory metadata between index and file makes the index untrustworthy (see F-09).

5. Content model of BRANDBOOK.md#

The root file’s body is free-form Markdown organised as ## sections. The base standard prescribes no section list: which knowledge a root should present, and in what order, is profile territory (§1.1 — the evidence-based profile recommends a specific seven-section shape). Two recommendations apply regardless of profile:

• The root SHOULD contain a File Index section: a human-readable mirror of the files: YAML. Rationale: progressive disclosure for human readers, who do not parse frontmatter.
• The root SHOULD stay a router — essentials and pointers, within the S-02 token budget — rather than a dumping ground.

5.1 Citable IDs#

Operational content earns its keep by being referenceable: approvals, tickets, and AI prompts cite rules by ID (“draft rejected: violates AR-03”).

• C-01. A package MAY define Anchor Rules: hard, non-negotiable constraints, numbered AR-01, AR-02, …, and numbers MUST NOT be reused after deletion (retire, don’t recycle). In a package that declares inherits:, anchor rules MUST instead be numbered AR-<SLUG>-01, AR-<SLUG>-02, …, where <SLUG> is an uppercase alphanumeric token, RECOMMENDED to be the final segment of the child’s brand.slug (slug acme-verde → AR-VERDE-01); child IDs MUST NOT collide with any ancestor’s rule IDs (H-02). Rationale: recycled IDs corrupt the historical record, and a shared numeric series would collide the moment a parent releases a new rule.
• C-02. Every Anchor Rule SHOULD state its rationale in one line. Rationale: rules without reasons get ignored or cargo-culted.
• C-03. Entries in the prioritised list of a type: cep file SHOULD carry stable IDs CEP-01, CEP-02, …, and an ID MUST NOT be renumbered or reused once assigned (retire, don’t recycle). Rationale: portfolio ranges (see portfolio-spec.md) and campaign briefs reference entry points by ID; renumbering corrupts those references exactly as recycled anchor-rule numbers would.
• C-04. The retire-don’t-recycle principle generalises: any ID’d list a package defines — custom rule series, asset ids, range ids — MUST NOT renumber or reuse an ID once assigned. Rationale: IDs exist to be cited; recycling silently corrupts every past citation.

5.2 Operational core, narrative context#

The test for core-file content is simple: can a designer, copywriter, approver, or AI agent act on this line? The package decides what counts as operational within its own framework — a persona a copywriter writes for is operational; a manifesto nobody executes is narrative. Narrative material (mission and vision statements, brand history, manifestos, essays) belongs in context/ (S-04), where it keeps its full cultural value for human readers without spending the token budget of every agent call. Core files (the root and everything in the files: index) SHOULD carry operational content only.

The ownable test (adopted from brand.md): if another brand’s name can be swapped into a line and the line still works, the line is too generic to be actionable. Authors SHOULD apply this test to every sentence of positioning and voice content.

6. How AI agents consume brandbook.md#

This section is normative for tooling (MCP servers, plugins, direct file readers).

1. Load order. An agent MUST load BRANDBOOK.md first and MUST NOT preload secondary files. Secondary files are loaded on demand, selected via the files: index by type, scope, and summary. Rationale: progressive disclosure. The root answers most questions in 5K tokens or fewer.
2. The index is the interface. An MCP server SHOULD serve package discovery from root frontmatter alone (parse YAML, not Markdown). A list_files-style tool maps directly onto files:. Rationale: frontmatter-only reads keep servers trivial and fast.
3. Anchor Rules are system-prompt level. When generating brand-facing output, agents MUST treat Anchor Rules (C-01; typically a type: governance file and an Anchor Rules section of the root) as hard constraints, the equivalent of system-prompt instructions, never as stylistic suggestions. Violations SHOULD be reported by rule ID. Rationale: numbered, citable rules make agent output auditable (“draft rejected: violates AR-03”).
4. Voice do/don’t pairs are few-shot material. Agents SHOULD use voice rules and their examples as few-shot demonstrations rather than paraphrasing them into abstract style adjectives. Rationale: examples steer generation; adjectives do not. (Adopted from brand.md’s consumption model.)
5. Respect scope. When generating for a specific market or language, agents MUST prefer files whose scope/language match and MUST NOT apply another market’s localised content (taglines, CEPs) outside its scope. Rationale: localised assets, above all taglines, can be meaningless or harmful in other markets.
6. Respect freshness. Agents SHOULD surface a warning when consuming a package (or file) whose last_validated + review_cycle has elapsed. Rationale: silent staleness is the failure mode of every existing brand-book format.
7. context/ loads on request only. Tooling MUST NOT read context/ content into agent context by default, and MAY load it when the user explicitly asks for narrative or heritage material (e.g. “summarise the brand’s founding story”). Rationale: narrative material is for humans first; on-request loading keeps it available without taxing every generation call.

7. Hierarchy and inheritance (multi-brand)#

Organisations with brand architectures (house of brands, endorsed brands, sub-brands) compose packages by nesting:

corp/
├── BRANDBOOK.md              ← parent (master brand)
└── brands/
    ├── sub-brand-a/
    │   └── BRANDBOOK.md      ← child; declares parent
    └── sub-brand-b/
        └── BRANDBOOK.md

A child root declares its parent in frontmatter:

inherits:
  from: ../../BRANDBOOK.md    # relative path to parent root
  mode: endorsed              # branded-house | endorsed | independent

• H-01. A child package MAY be sparse: any profile-recommended section it omits resolves to the parent’s section. Validators MUST NOT warn about omitted profile-recommended sections in a package that declares inherits:, even when it declares a profile. Rationale: sub-brands usually share most rules; sparse children avoid divergence by copy-paste.
• H-02. Guardrails merge, never loosen. A child MAY add Anchor Rules and MAY tighten inherited ones; it MUST NOT remove or weaken a parent rule. Validators MUST treat the effective rule set of a child as parent rules plus child rules. Rationale (adopted from brand.md): if children can opt out of guardrails, the parent’s governance is decorative. An exception requires the parent to release a new version that relaxes the rule for a declared scope.
• H-03. mode is informative for humans and tooling defaults: branded-house children SHOULD inherit DBAs and voice wholesale; endorsed children SHOULD inherit governance and legal but own their DBAs/CEPs; independent children inherit only what they explicitly reference. Rationale: three modes cover the practical architectures without brand.md’s fourth (sub-brand), which behaves identically to endorsed at file level; kept simple until real packages prove otherwise.
• H-04. Inheritance is single-parent and MUST NOT be circular. Tooling MUST resolve at most 3 levels deep. Rationale: real brand architectures are shallow; unlimited depth invites unresolvable graphs.
• H-05. Sparse resolution extends to secondary files: a type absent from a child’s files: index resolves to the parent’s file(s) of that type. The mode defaults of H-03 describe which types a child SHOULD own outright (an endorsed child SHOULD carry its own DBAs and CEPs); where a child nonetheless omits a type, resolution still falls back to the parent — except for independent children, which inherit nothing implicitly. Exception: portfolio is never inherited wholesale — a package that sells things declares its own ranges. Rationale: H-01 without file-level resolution leaves agents guessing where a child’s voice or legal rules live; the portfolio exception keeps CEP-coverage checks meaningful per brand (P-08).

8. Versioning and governance workflow#

• G-01. Any change to a package MUST bump the version of the changed file(s) and the root version per F-04’s semantics. Rationale: consumers cache by version; unbumped edits break trust in caching.
• G-02. Revalidation (confirming content is still correct, without change) updates last_validated only, not version. Rationale: freshness and content identity are independent signals.
• G-03. Packages SHOULD live in version control; the optional Changelog section carries only major, human-salient changes. Rationale: Git is the audit trail; duplicating it in Markdown invites drift.

9. Conformance#

Conformance is structural — it covers the machine contract, not the content. A package is conforming when: the root file passes schema/brandbook-root.schema.json; the files: index is internally sound (every entry’s path stays inside the package, exists on disk, and appears only once); every indexed file passes schema/brandbook-file.schema.json; every fenced record in indexed dba and portfolio files passes its record schema (schema/dba-asset.schema.json, schema/portfolio-range.schema.json); every declared scope uses only root markets; and the F-11/F-13 cross-checks hold wherever both sides declare a value.

Everything else is advisory: profile checks (§1.1, applied only when the root declares a profile the validator recognises), token budget (S-02), freshness (F-05), one-sided index metadata (F-13), and unrecognised spec_version or profile values are surfaced by validators as warnings, and warnings never affect conformance. Sparse child packages (H-01) are conforming by construction. The reference validator is tools/validate.js.

Tooling is conforming when it observes the MUST-level rules of §6 and §7.

A package that declares inherits: is conforming only when, additionally: the parent chain resolves to valid roots without cycles at 3 levels or fewer (H-04), and its own anchor-rule IDs observe the child namespace form of C-01 without colliding with ancestor IDs (H-02). Sparse-resolution behaviour (H-01, H-05) and the inherited-CEP fallback for portfolio checks are tooling obligations, not package conformance criteria.

10. Decisions and open questions (v0.1)#

Decided (07.2026):

1. Licence: dual — specification text and examples CC-BY-4.0, code MIT.
2. Conformance is structural (§9): schemas and index integrity decide validity; sections, content genres, token budgets, and freshness are guidance surfaced as warnings.
3. Methodology lives in profiles (§1.1): the base standard defines structure and governance only; content models are opt-in named profiles, of which evidence-based is the first.
4. Bilingual documentation: spec in English; examples may be localised.

Open, flagged for revision before v1.0:

1. Hierarchy model: three inheritance modes (§7 H-03); revisit if real packages need finer distinctions.
2. Design tokens: W3C Design Tokens format recommended but not mandated (S-05); may become normative once the W3C format stabilises.
3. Profile mechanics: single profile value per root, never inherited (F-14). Revisit whether multi-profile declarations, estate-wide profiles, or a third-party profile registry are needed.
4. DBA inventory detail: specified separately in dba-inventory-spec.md (draft).