gusto.md Format Specification#

Version: 0.1.2 Status: Draft, under active development License: Apache-2.0

A format specification for describing a brand's verbal identity to AI agents and content tools. A GUSTO.md file gives agents a persistent, structured understanding of how a brand sounds — its vocabulary, sentence rhythm, tonal modes, cultural references, and refusals — so that every piece of generated copy stays on voice across every surface a brand touches.

This document is the normative reference. The specification is opinionated and authored by the gusto.md project. Vendors, tools, and brands are free to adopt, implement, and extend it under the Apache-2.0 license.

Background and Position#

The visual layer of brand identity has a working machine-readable standard. The W3C Design Tokens Community Group has shipped a stable specification (DTCG, 2025.10). Google's DESIGN.md format builds on that work to describe a full visual system — colors, typography, spacing, components — in a file that AI agents can read and apply.

The verbal layer has no equivalent. Brand voice today lives in PDFs, Notion pages, and the trained instincts of human writers. AI tools either ignore voice (and default to a generic "tasteful tech" tone) or solve it inside vendor silos (Jasper, Copy.ai, Contentstack — each with proprietary JSON formats that don't move between tools).

GUSTO.md fills that gap. The specification is opinionated, the file format is portable, and the lint rules are deterministic. Vendors are not required to participate in a standards body to support it. Brands are not required to commit to a vendor to use it. The format is open, the license is permissive, and the design decisions documented here are the considered output of a single project — not a committee.

This is the same posture that produced Markdown, AGENTS.md, and the early DTCG drafts. Standardization through adoption, not consensus.

GUSTO.md is designed as the verbal companion to a DESIGN.md file. The two formats sit alongside each other in a project, share the same conceptual model (machine-readable tokens + human-readable rationale), and are intended to be consumed together by the same generation of AI agents.

File Structure#

A GUSTO.md file has two layers, in a fixed order.

1. YAML front matter — Machine-readable voice tokens, delimited by --- fences at the top of the file.
2. Markdown body — Human-readable voice rationale organized into ## sections.

The tokens are the normative values. The prose provides context for how to apply them. An agent that consumes a GUSTO.md file should treat the tokens as ground truth for lintable decisions (cadence, banned phrases, refusals) and the prose as guidance for judgement calls (atmosphere, cultural reference, register).

Tokens are not a substitute for prose. The prose is the primary guidance for an agent producing copy; tokens are the enforcement surface for lint and validation tools. An agent reading both should weight the prose for tone and judgment, and apply the tokens for checking and post-editing.

Minimal Example#

---
version: "0.1.2"
name: "Heritage"
voice:
  formality: medium
  density: high
  warmth: medium
  irony: low
  imperative_ratio: 0.4
rhythm:
  avg_sentence_length: 14
  max_sentence_length: 22
vocabulary:
  preferred:
    - crafted
    - considered
    - direct
  banned:
    - "take it to the next level"
    - "game-changer"
    - "supercharge"
  avoid:
    - "just"
    - "very"
    - "we hope"
refusals:
  - no_apology_as_style
  - no_exclamation_for_emphasis
---

## Voice Atmosphere

Heritage speaks the way a senior editor speaks — calm, declarative, never
breathless. The voice trusts the reader to follow without being led.

## Vocabulary Palette
...

An agent reading this file knows several things immediately: that sentences should average 14 words and never exceed 22, that "game-changer" is hard-banned (an error on use), that "very" and "just" are softer hedges to avoid where possible (a warning on use), and that apologies should not be used as a stylistic device. The prose tells the agent why — Heritage is editorial, not promotional.

Token Schema#

The YAML front matter defines token groups. All groups are optional except name. Groups present must follow the schema below.

Top-Level Fields#

version: <string>             # optional, current: "0.1.1"
name: <string>                # required
description: <string>         # optional, one sentence
extends: <string>             # optional, see Extends below

Voice Tokens#

Voice tokens describe the overall stance of the voice on a small number of orthogonal axes. Values are categorical (low | medium | high) for human-judgment axes, and numeric (0.0–1.0) for ratio axes.

voice:
  formality: <low | medium | high>
  density: <low | medium | high>
  warmth: <low | medium | high>
  irony: <low | medium | high>
  imperative_ratio: <number 0.0–1.0>

Voice tokens are deliberately few. Adding more axes invites false precision — voice is not a vector space, and an eight-axis system suggests a calibration we cannot deliver. Five axes capture the meaningful distinctions; further specificity belongs in prose.

Rhythm Tokens#

Rhythm tokens describe sentence-level cadence in measurable terms. These are the primary linting surface — most cadence violations can be checked deterministically.

rhythm:
  avg_sentence_length: <number>      # words
  max_sentence_length: <number>      # words
  paragraph_style: <single_sentence_allowed | dense_only>
  exclamation_policy: <forbidden | tagline_only | sparing | free>
  semicolon_policy: <forbidden | sparing | free>

Rhythm tokens are advisory targets, not hard rules. The linter reports violations as warnings; tools may choose to enforce or soften.

Vocabulary Tokens#

Vocabulary tokens are the most directly lintable group. They define what to reach for, what to avoid softly, and what to ban hard.

vocabulary:
  preferred:
    - <word or phrase>
  banned:                            # hard ban — error on use, no register exceptions
    - <word or phrase>
  avoid:                             # soft avoid — warning on use, register may override
    - <word or phrase>
  signature_phrases:
    - <phrase that is uniquely the brand's>
  reclaimed_terms:                   # optional
    - term: <word>
      note: <why this term is used unusually>

The banned and avoid lists are deliberately separate. banned is for marketing clichés, hype words, and retired phrases — vocabulary that should not appear in any consumer-facing copy regardless of register. avoid is for filler words, hedges, and apologetic vocabulary — vocabulary that should generally not appear but can occasionally serve cadence or warmth in specific registers (legal, support, error). The linter treats banned violations as errors and avoid violations as warnings.

The signature_phrases list is intentionally distinct from preferred. Signature phrases are brand-owned (e.g., Murder your thirst. for Liquid Death, Designed by Apple in California. for Apple). A consumer tool must not transfer signature phrases across brands.

Reclaimed Terms#

Some voices use ordinary words in deliberately unusual ways. The reclaimed_terms list flags these for consumer tools so that linters don't flag them as off-voice and prompt-builders don't strip their irony.

vocabulary:
  reclaimed_terms:
    - term: healthy
      note: "Used straight-faced as wellness vocabulary, played for ironic contrast against the brand's violence imagery."
    - term: hydration
      note: "Reclaimed wellness term, used in deadpan voice to land the joke."

Reclaimed terms are not banned, not preferred — they are a third category. A consumer tool should preserve them in output and treat the note as guidance for register.

Register Tokens#

Register tokens describe how the voice adjusts across surfaces. Each register is a named context with override rules.

register:
  <register_name>:
    formality: <override>           # optional, overrides voice.formality
    density: <override>             # optional
    warmth: <override>              # optional
    irony: <override>               # optional
    max_sentence_length: <number>   # optional, overrides rhythm
    notes: <prose>                  # optional, free text

Conventional register names — used by linters and tools — are:

marketing | support | error | developer | newsroom | legal | sustainability | social | packaging

Custom register names are permitted; consumers should preserve unknown registers without error.

Refusal Tokens#

Refusals are the non-negotiable rules of the voice. They are listed as either named constants (linter-aware) or free-form strings.

refusals:
  - <refusal_name_or_freeform_string>

The specification defines a starter set of refusal names. These names are recognized by linters and produce specific findings when violated. Unknown refusal names are preserved without error.

Named Refusals — Style and Voice#

Named Refusals — Ethics and Reader Treatment#

Brands may add their own refusal strings beyond this set. Consumers should preserve unknown refusals as free-form strings and treat them as advisory guidance.

Cultural Reference Tokens#

Cultural references shape feel rather than syntax. They are advisory, not lintable.

references:
  drawn_from:
    - <cultural_touchstone>
  avoided:
    - <cultural_touchstone>

Token Types#

Token References#

A token may reference another token by path. This allows a register override to reuse a top-level token without restating it.

voice:
  formality: low

register:
  error:
    formality: "{voice.formality}"   # explicitly reuses top-level value
  marketing:
    formality: high                  # overrides

Token references resolve at consumer time. A reference that does not resolve to a defined token produces a broken-ref linter error.

Section Order and Aliases#

Sections in the markdown body use ## headings. Sections may be omitted, but those present must appear in the canonical order below. Sections are referenced by name, not number — the canonical order is enforced by linting, not by author-supplied numbering. Authors should not prefix section headings with numbers.

The canonical names are normative; aliases are accepted by consumers. Out-of-order sections produce a section-order linter warning, not an error — older files may have legitimate variations.

extends for Inherited Voice#

A GUSTO.md file may reference another GUSTO.md file as a base. The top-level extends field resolves to a URL or path; the consumer must merge the base file's tokens with the local file, with local values taking precedence.

extends: "./parent-brand.gusto.md"
name: "Sub-brand"
voice:
  warmth: high                       # overrides parent

This supports multi-brand systems where a parent voice has variants. Consumers should resolve extends chains to a maximum depth of five, and produce a circular-extends error on cycles.

Consumer Behavior#

Consumers of GUSTO.md files (linters, generators, AI agents, design tools) should behave predictably when they encounter content outside the spec.

This permissive posture is deliberate. The spec will grow; consumers built against 0.1 should not break against 0.2 files. Strict enforcement applies only to clearly malformed input.

Linting Rules#

The reference linter (gusto-lint) runs the following rules against a parsed GUSTO.md. Each rule produces findings at a fixed severity level.

Linting validates structure and consistency. It does not evaluate generated copy against the voice — that is a separate function, described below.

Validation of Generated Copy#

A linter validates the GUSTO.md file itself. A separate function — referred to here as copy validation — checks whether a piece of generated copy conforms to the file's rules.

Copy validation is the consumer's responsibility. The specification defines the surface for this validation: a copy validator that reads a GUSTO.md file and a piece of copy and returns findings.

The reference CLI exposes this as:

gusto check <copy.txt> --against GUSTO.md

Expected findings include:

Copy validation is intentionally pragmatic. It catches obvious violations, not nuanced ones. Voice is partly judgment, and the validator does not pretend otherwise.

CLI Reference#

A reference CLI is available as @gusto-md/cli on npm. All commands accept a file path or - for stdin and output JSON by default.

gusto lint#

Validate a GUSTO.md file for structural correctness.

npx @gusto-md/cli lint GUSTO.md

Exit code 1 if errors are found, 0 otherwise.

gusto check#

Validate a piece of copy against a GUSTO.md file.

npx @gusto-md/cli check hero.txt --against GUSTO.md

gusto diff#

Compare two GUSTO.md files and report token-level changes.

npx @gusto-md/cli diff GUSTO.md GUSTO-v2.md

Exit code 1 if regressions are detected (added refusals violated by historical copy, removed banned phrases, etc.).

gusto export#

Export a GUSTO.md file to other consumer formats.

npx @gusto-md/cli export --format system-prompt GUSTO.md > prompt.md
npx @gusto-md/cli export --format claude-project GUSTO.md > claude-config.json

gusto spec#

Output the GUSTO.md format specification (useful for injecting spec context into agent prompts).

npx @gusto-md/cli spec
npx @gusto-md/cli spec --rules-only --format json

Integration Guidance for Vendors#

Tools and platforms adopting GUSTO.md should follow these conventions.

Read. Accept a GUSTO.md file as an input artifact. Parse the YAML front matter as voice tokens. Treat the markdown body as guidance prose. Pass both to the underlying generation model — tokens as rules, prose as context.

Write. When producing a GUSTO.md from a tool's internal voice profile, emit tokens conformant to this specification. Preserve unknown fields when round-tripping.

Validate. Before generating copy on a user's behalf, lint the GUSTO.md and surface errors to the user. Do not silently ignore broken references or invalid values.

Silent application. The voice should be applied without surfacing the rules to the user. Generated copy should not include meta-commentary like "following your spec" or "according to your rules." The voice is the output, not the rules behind it. This is best-practice guidance rather than a strict requirement: output testing during the development of the Liquid Death exemplar (two surfaces, six runs total, May 2026) did not surface meta-commentary even without this guidance in place. The recommendation is included to guide vendor implementations toward the cleaner pattern.

Round-trip. A GUSTO.md exported from a tool, imported into a second tool, and exported again should remain equivalent at the token level. Prose may be reformatted but should not be discarded.

Attribute. A user-facing surface that consumes GUSTO.md should indicate which file is active, so the user can verify what voice is being applied.

A reference implementation, integration kit, and example consumer adapters are maintained in the gusto.md repository.

Versioning and Compatibility#

The format follows a <major>.<minor>.<patch> versioning scheme. Patch releases are non-breaking clarifications and additions to the named-constants sets. Minor releases may add new token groups or rules. Major releases may break compatibility. A version 1.0 will be declared when the specification has stabilized through real-world use.

Consumers should declare which spec version they implement. Files should declare the version they target via the version field. Consumers encountering a file targeting a newer spec version should attempt best-effort parsing and surface an info-level warning.

Status and Roadmap#

This specification is 0.1.2. The format, schema, lint rules, and CLI surface are under active development. Breaking changes are expected before 1.0.

Near-term priorities for the spec:

• Stabilize the voice axis enumeration
• Continue expanding the named refusals and named registers sets through exemplar authoring
• Define a JSON Schema for the YAML front matter
• Publish reference exemplar files alongside the spec (Apple and Liquid Death in this release; three additional voice families to follow)
• Ship gusto check as the first copy validator

The specification is authored and maintained by the gusto.md project. Issues, discussion, and proposed changes are tracked in the public repository.

Changelog#

0.1.2#

• Split vocabulary.banned into vocabulary.banned (hard ban — error on use) and vocabulary.avoid (soft avoid — warning on use). The single banned list was treating context-blind hedges and marketing clichés at the same severity, causing models to over-correct and strip natural language flow. Apple exemplar migrates to the new shape (filler and hedge words moved to avoid); Liquid Death exemplar's list is uniformly hard-banned and stays in banned only.
• Added avoid-phrase-used linter rule at warning severity, to accompany the existing banned-phrase-used rule (now scoped to hard bans only).
• Added clarification in the File Structure section that prose is the primary guidance for an agent producing copy, and tokens are the enforcement surface for lint and validation tools. The two-layer architecture was documented but the hierarchy was not; output testing across May 2026 (Apple) and May 2026 (Liquid Death, two surfaces) confirmed that prose carries voice atmosphere and tokens enforce vocabulary at the word level. A separate observation — that token-enforced cadence may compress brand-flavored vocabulary at tight length budgets — was surfaced in the same tests and is logged for monitoring across future exemplars rather than acted on at this version.
• Added "Silent application" paragraph to the Integration Guidance for Vendors section, recommending that voice be applied without surfacing the rules to the reader. Best-practice guidance, not an urgent fix: the Liquid Death output tests (two surfaces, six runs total) did not reproduce the May Apple regression in which the model cited the spec back to itself. The recommendation is included to guide vendor implementations toward the cleaner pattern.
• Updated minimal example and all internal version references from 0.1.1 to 0.1.2.

0.1.1#

• Renamed all internal section references from numbered (e.g. "Section 3.2") to named (e.g. "the Voice Tokens section"). Section numbers were a documentation convention, not a token, and exemplar authors were mistakenly numbering their markdown headings to match.
• Added section-numbered warning to the linter, with consumer behavior to strip author-supplied numbering automatically.
• Expanded named refusals from 8 to 16, split into two tables — style/voice and ethics/reader treatment. New names: no_all_caps_for_emphasis, no_mid_sentence_capitalization, no_specs_in_marketing_headlines, no_introducing_as_opener, no_version_2_framing, no_first_without_qualification, no_manufactured_urgency, no_ai_as_a_feature. Surfaced through writing the Apple exemplar.
• Added Reclaimed Terms subsection under Vocabulary Tokens with worked example. The schema field existed in 0.1 but had no example; needed before authoring brands that play with wellness or corporate vocabulary ironically.
• Added reclaimed-in-banned linter rule to catch authors who reclaim a term in one list and ban it in another.
• Updated minimal example and all references from version: "alpha" to version: "0.1.1".

0.1 (alpha)#

• Initial draft. Five voice axes, eight named refusals, nine canonical sections, reference CLI commands defined.

License#

This specification is published under the Apache License 2.0. Exemplar GUSTO.md files in the reference collection are published under the MIT License.

GUSTO.md is the verbal companion to a DESIGN.md file. Where DESIGN.md captures the visual layer — colors, typography, spacing — GUSTO.md captures the verbal layer: vocabulary, rhythm, register, refusals, and references. Together, the two formats describe a brand a coding agent can read.