brand-docs

BrandDocs: AI On-Brand Document Generator for Word, PowerPoint & Excel

BrandDocs is a set of agent skills that learn your existing Word, PowerPoint and Excel templates and generate new on-brand documents from them. Unlike generic AI document generators, it preserves brand, structure, styles and formulas by construction. Built for Claude Code, Codex and compatible AI agents.

What is BrandDocs?

BrandDocs is an open-source agent-skill bundle that learns a company’s existing Office templates and generates new on-brand documents from them. Point it at one branded .docx, .pptx, or .xlsx; it extracts the brand (theme colors and fonts, named styles, the document’s structure, layouts, cover anchors, logos and tables) into a portable Brand Profile. From then on, every document it generates is built from the original template shell and uses only the artifacts the template actually defines. Each format stays in its own lane: there is no cross-format conversion.

The core guarantee: off-brand output is impossible by construction. No generator ever writes a literal style name, hex color, or font: those live only in the Brand Profile, and verify refuses a profile that points at anything the template doesn’t contain.

At a glance

The three skills

All three share one engine and expose the same verbs: extract → comprehend (optional, model-driven) → verify → generate, plus the learning verbs learn / propose-overrides / refine that fold QA findings and user feedback back into the profile. Details → documentation/SKILLS.md.

Several templates, one brand? extract --blend folds a second same-format template into a saved profile at the value-fact level: it fills gaps and corroborates agreements, the primary template wins every conflict, and the brand guarantee is untouched because artifact pointers never cross templates. compare-profiles reports brand drift (theme colors, fonts, off-theme usage) between any two saved profiles and exits non-zero on drift, so it can gate brand coherence in CI.

Two-phase by design: the deterministic engine works with no model at all (extract / verify / generate, fully offline); the model-assisted verbs sit ON TOP and can only NAME captured facts - every proposal is validated fail-closed, so the brand guarantee never depends on a model being right.

Published only after proof: generation preflights the profile and shell, writes to a same-directory temporary file, and atomically publishes the requested output only after deterministic QA passes. XLSX also preserves formulas and raw worksheet extensions such as sparkline groups; extension loss is a blocking QA error.

Prerequisites

BrandDocs runs locally and needs a few things installed before first use:

• Python 3.10-3.13 plus the packages in requirements.txt (python-docx, python-pptx, openpyxl, lxml, Pillow):

  pip install -r requirements.txt
  

• Visual QA tools (keep the visual gate on): the render-based visual QA gate runs by default and catches layout problems the deterministic checks can’t (text overflow, blank pages, clipping, stale demo text). It needs LibreOffice + Poppler (Tesseract is optional, for OCR). Install them with one auto-detecting command:

  bash scripts/setup_visual_qa.sh
  

  Generation still runs without them (it degrades gracefully to deterministic-only QA, level L0), but install them so the visual gate stays on.

Check what’s present at any time with python scripts/brandkit/cli.py doctor. Per-OS commands and the full setup → documentation/INSTALLATION.md.

Installation

The three skills share one Python engine (scripts/brandkit/), so install the whole repository (copying a single skill folder on its own won’t work). After either install below, set up the prerequisites so the engine can run, then verify with python scripts/brandkit/cli.py doctor.

Claude Code

The plugin loads all three skills plus the shared engine together:

/plugin marketplace add ferdinandobons/brand-docs
/plugin install brand-docs@brand-docs

Codex (and other agents)

Clone the repo and symlink the three skills into your Codex skills directory, so each skill’s engine in scripts/brandkit/ travels with it:

git clone https://github.com/ferdinandobons/brand-docs.git ~/.codex/brand-docs
cd ~/.codex/brand-docs && python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
mkdir -p ~/.codex/skills
for s in brand-docx brand-pptx brand-xlsx; do ln -s ~/.codex/brand-docs/skills/$s ~/.codex/skills/$s; done

Restart or reload the agent if the skills don’t appear immediately.

Git-submodule install and updating instructions are in documentation/INSTALLATION.md.

Quick start

With an AI agent (the intended experience). Describe what you want and attach a template:

“Use this company Word template and write a report on the history of Napoleon.”

The agent activates brand-docx, extracts (or reuses) a Brand Profile, fills the template shell in its structural order, runs QA, and returns the file. PowerPoint (brand-pptx) and Excel (brand-xlsx) work the same way.

How long does it take? The FIRST run on a new template is the slow one: extraction, the optional model comprehension, content authoring and the visual QA gate (plus any repair round) can take up to ~15 minutes end to end with an AI agent. Every later document from the saved profile takes seconds. Still a fraction of formatting the document by hand, and you get a faithful file instead of an approximate one.

Direct CLI (the engine, for tests & debugging). No template at hand? Try the shipped synthetic example: examples/templates/branddocs_template.docx (also .pptx / .xlsx).

# 1) Extract the brand from a template into a reusable Brand Profile
python scripts/brandkit/cli.py extract --name <your_company> --template examples/templates/branddocs_template.docx --scope project

# 2) Verify the profile (fails if a role points at a missing artifact)
python scripts/brandkit/cli.py verify --name <your_company> --scope auto --qa auto

# 3) Generate a new on-brand document from structured content
python scripts/brandkit/cli.py generate --name <your_company> --input idoc.json --output out.docx --scope auto --qa auto

The input (idoc.json) is an IntermediateDocument of brand-agnostic typed blocks (no styles, colors or fonts); the Brand Profile resolves all of that.

Project status

Alpha, maturing. Stability is per format: Word (brand-docx) is robust - the reference implementation, verified end-to-end on real templates with a 900+ test suite, three QA lanes and frozen byte-identity anchors; PowerPoint and Excel share the engine and are catching up to docx parity. The profile schema (1.2.0) is frozen and additive: profiles keep working across releases. Full status table → documentation/SKILLS.md.

Website & discovery

• Public website: ferdinandobons.github.io/brand-docs
• Full documentation: documentation/

Changelog

Latest release: v0.10.1. See CHANGELOG.md.

License, citation & acknowledgements

• This project’s own code is MIT © 2026 Ferdinando Bonsegna.
• Self-contained: the OOXML engine is re-implemented from scratch; it does not vendor any proprietary or third-party Office tooling. See NOTICE.
• Citing BrandDocs in academic or organizational work → CITATION.cff.