brand.md

The behavioral brand contract for AI agents.

brand.md is to brand/content what design.md is to visual design — a single file that gives agents a persistent, structured understanding of brand behavior.

DESIGN.md  →  how it looks
BRAND.md   →  how it acts

What BRAND.md is

A behavioral identity file. It tells autonomous agents:

• How it speaks (voice rules)
• Who it speaks to (audience segments with their real pressures)
• What it says and proves (message)
• What it monitors (topics, signals, communities)
• What it does and doesn't do (behavior)
• What it can never say or must escalate (safety)

What BRAND.md is not

• A brand guidelines document (that lives in a PDF)
• A visual identity file (that's DESIGN.md)
• A marketing strategy document
• A content calendar
• A product brief

Brand is not content — it is behavior. The test for any field: does it change what an agent does, not just what it produces?

The format

A BRAND.md file has two layers:

YAML front matter — machine-readable brand tokens: voice rules, audience segments, message claims, topic signals, behavioral triggers, and safety constraints. Exact, parseable, actionable.

Markdown body — agent-readable rationale: why this tone, what this brand stands for, how to apply rules to edge cases. The judgment layer that transforms rules into decisions.

---
name: GiveCare
description: "Care coordination for family caregivers"
positioning: "AI caregiving coordination that reduces caregiver burnout"
voice:
  tone: [warm, authoritative, hopeful]
  do:
    - Acknowledge emotional weight before offering a solution
  dont:
    - Medical jargon without plain-language follow-up
message:
  core_claim: "The problem isn't love — it's logistics"
  proof_points:
    - "AARP 2023: unpaid caregiving valued at $600B annually in the U.S."
topics:
  pillars:
    - id: care-economy
      angle: "Unpaid care labor is structurally undervalued"
      signals: [care economy, unpaid labor, caregiver workforce]
      funnel_role: authority
behavior:
  engage:
    - Inbound questions about caregiving logistics or resources
  escalate:
    - crisis situations involving audience members in distress
    - medical misinformation spreading at scale
safety:
  forbidden_claims:
    - Any specific medical advice or treatment recommendation
  citation_policy: "All factual claims require a named source."
  delegation:
    autonomous: [content_discovery, social_reply, amplification]
    human_required: [product_claims, crisis_response, partner_mentions]
---

## Voice
The tone is warm but not saccharine. Write the way a trusted friend
who happens to be a nurse would talk...

Spec

See spec.md for the full field reference.

Adoption tiers

Start with the smallest file that changes agent behavior:

• Minimal: name, positioning
• Operational: voice, audience, message, topics, behavior, safety
• Regulated: safety.forbidden_claims, safety.regulated_claims, safety.citation_policy, safety.sensitive_topics, safety.crisis_policy, safety.delegation

Do not add fields because a brand guide has them. Add fields when they change what an agent may do, say, monitor, create, amplify, escalate, or publish.

Examples

• examples/givecare.brand.md — AI caregiving platform
• examples/scty.brand.md — AI systems studio

Tooling

# Scaffold a new BRAND.md interactively
npx brand-md init

# Validate a BRAND.md file
npx brand-md lint BRAND.md

# Parse front matter to JSON
npx brand-md parse BRAND.md

# Export to agent system prompt
npx brand-md export --format prompt BRAND.md

# Export to JSON for API consumption
npx brand-md export --format json BRAND.md

# Diff two versions
npx brand-md diff v1.brand.md v2.brand.md

The linter runs JSON Schema validation first, then spec rules. Schema catches type errors and missing required sub-fields; spec rules catch semantic constraints (e.g. engage without escalate).

Conformance classes

Declare conformance_class to tell the linter which agent type the file targets. It enforces the minimum field set for that class.

conformance_class: reply_agent  # content_agent | social_agent | reply_agent | research_agent | support_agent

Class	Minimum required fields
content_agent	voice, topics.pillars, behavior.create, safety
social_agent	voice, behavior.channels, behavior.escalate, handles
reply_agent	voice, behavior.engage, behavior.escalate, safety.sensitive_topics
research_agent	topics, topics.pillars with signals, topics.watch
support_agent	voice, behavior.escalate, safety.delegation

Ecosystem position

BRAND.md sits alongside — not inside — other agent instruction files:

File	Purpose	Who reads it
AGENTS.md	How to work in this repo	Coding agents
DESIGN.md	How the product looks	Design and UI agents
BRAND.md	How the brand behaves	Content, social, reply, support agents
llms.txt	What public content exists	Model ingestion, RAG
CLAUDE.md	Project-specific agent rules	Claude Code

The rule: BRAND.md is the dedicated, predictable place for brand-agent behavioral instructions — same logic as AGENTS.md being the dedicated place for coding-agent instructions.

Hierarchy

In multi-brand or multi-product systems:

/BRAND.md                          ← company-level contract
/products/foo/BRAND.md             ← product overrides
/campaigns/bar/BRAND.md            ← campaign overrides

Safety constraints (forbidden claims, escalation rules, delegation policy) can only get stricter in child files — never weaker.

Design principles

Behavior over guidelines. A BRAND.md should change what an agent does, not just inform what it produces. Every field should answer: does this constrain or direct agent behavior?

Rationale over rules. Rules break at edges. Rationale lets agents make judgment calls the author would endorse. The markdown body is not documentation — it is judgment transfer.

Search-ready by design. Pillar signals, signal keywords, event triggers, and watch lists are first-class fields — not afterthoughts. A BRAND.md should drive content discovery without additional configuration.

Delegation is explicit. What an agent can do autonomously and what requires human approval must be stated, not inferred. Unstated delegation is a liability.

Safety constraints are monotonic. Child brand files can only tighten safety rules, never relax them.

Composable with DESIGN.md. A complete brand specification is DESIGN.md + BRAND.md. Visual identity and behavioral identity are separate concerns with separate owners.

Status

v0.3.0. The format and CLI are stable for use. Field names and nesting may evolve before v1.0.

License

MIT