brand-library-architect

What this skill does

# Brand Library Architect

## Overview

This skill captures a phased workflow for building a complete brand library for a product. It produces a coherent set of artifacts: a render pipeline for visual assets (HTML sheets → Playwright → WebP), a documentation set rooted in locked vocabulary and voice rules, repo conventions for open-source projects, and a press kit. The phases reference each other (e.g., the press kit pulls bios from `BIOS.md`, the README banner cites the visual pipeline output) so cross-references work even when phases are run independently.

Every template uses `{{TOKEN}}` placeholders for product-specific content. Prompt the user for the relevant tokens at the start of each phase rather than guessing, so the resulting library is voice-true to the product and not generically branded.

## When to use this skill

Apply when the user asks for any of:

- "Build a brand library / brand kit / brand assets for product X"
- "Set up the brand library workflow for this repo"
- "Create a positioning manifesto + visual identity"
- "Author a press kit / FAQ / glossary / tone guide / pricing doc / founder bio"
- "Add CONTRIBUTING / SECURITY / CODE_OF_CONDUCT to this repo with brand voice"
- "I have visual assets — help me write the brand documentation that anchors them" (or vice versa)
- "Audit the brand assets in this repo" / "What brand assets do we have?" / "Discover existing brand surface" → run **Phase 0 only** as a standalone audit

Apply selectively when only one or two phases are needed. The phases are independent enough to mix and match.

Do not apply this skill when the user wants:
- Product feature documentation (use `documentation-production`)
- Generic copywriting unrelated to brand library structure (use `copywriter`)
- Visual UI components or design systems (use `ui-design-aesthetics` or `frontend-design`)
- Internal-only docs (this skill is public-facing brand surface)

## Phases

The workflow is seven phases (0-6). Run sequentially for a new product, or jump to a specific phase for incremental work. Phases 0 and 1 are required before any other phase.

### Phase 0 — Discovery

Read `references/existing-assets.md` and run the four-step Discovery workflow:

1. **Search** the repo for existing brand assets, CSS color tokens, typography, logo files, OG/banner images, package metadata, internal pricing/entitlement docs that may constrain brand claims, and adjacent docs (CLAUDE.md, backlog tasks).
2. **Infer** what each finding implies about brand decisions (e.g., `--primary: #2d6a96` in `src/index.css` → primary brand color; existing README subtitle → pre-locked-vocabulary version of the locked hero; package.json `author.email` → canonical contact email).
3. **Confirm** with the user. Surface the inventory and proposed dispositions; surface any inference uncertainties or detected conflicts. Default to **preserve and surface** rather than overwrite — never silently rewrite existing brand assets.
4. **Request** sources the agent can't grep for: designer Figma files, brand guideline PDFs, past marketing materials, external blog/podcast voice samples, logo files in shared drives or other repos. The highest-value brand inputs almost always live outside the repo.

The output is `brand/discovery.md` — a permanent record of what was found, what was inferred, what the user confirmed, and what additional sources the user provided. Subsequent phases read this doc.

Discovery can also run as a standalone capability (e.g., "audit the brand assets in this repo") — produce `brand/discovery.md` and stop. The discovery doc on its own is a useful audit deliverable.

### Phase 1 — Decision rubric

Read `references/decision-rubric.md` and walk the user through any decisions Discovery didn't already answer. Don't re-elicit values that exist in `brand/discovery.md` — that's the whole point of running Discovery first. The output is `brand/decisions.md` capturing:

- Product name, domain, repo URL, contact email
- Brand verb (the owned action), durable noun (the substrate term), tagline, locked hero, trust line
- Color palette (primary brand color minimum; full palette preferred)
- Typography choices (body, mono, wordmark, display)
- License (AGPL-3.0 / MIT / Apache-2.0 / proprietary)
- Pricing model (episodic-pass / subscription / freemium / free / open-source-only)
- Pre-launch state (yes/no — affects deferral language throughout)
- Distribution domain for public docs (when public site lands)

Do not skip this. Subsequent phases reference these decisions. If the user resists upfront commitment on any token (e.g., "I don't have a tagline yet"), record the gap and proceed; later phases will surface where the gap blocks specific deliverables.

### Phase 2 — Bootstrap

Read `references/directory-structure.md` first — it documents the canonical layout (where files live, naming conventions, what goes in `icons/svg/` vs `icons/png/`, what goes in `_source/html/` vs `exports/`, etc.) and the rationale behind each choice.

Create the directory structure and seed the canonical brand docs with placeholders:

```
brand/
├── README.md         # library navigator (start here)
├── CHEATSHEET.md     # 30-second locked-values lookup
├── CHANGELOG.md      # chronological log of brand changes
├── CLAUDE.md         # directory-local AI agent rules
├── RECIPES.md        # common-task playbook
├── BRAND.md          # visual brand reference (marks, colors, typography, asset library)
├── COPY.md           # language reference (locked vocabulary, voice, asset → phrase index)
├── MANIFESTO.md      # long-form positioning argument
├── decisions.md      # the upfront commitments from Phase 1
└── (later phases populate the rest)
```

Anchor doc templates: `assets/brand-docs/BRAND.md.template`, `assets/brand-docs/COPY.md.template`, `assets/brand-docs/MANIFESTO.md.template`.

Quick-reference doc templates (one-line landing page for each common task):
- `assets/brand-docs/README.md.template` — library navigator with "what lives where" tables and quick paths
- `assets/brand-docs/CHEATSHEET.md.template` — 30-second locked phrases / colors / fonts / pricing card
- `assets/brand-docs/CLAUDE.md.template` — directory-local rules for AI agents editing brand files
- `assets/brand-docs/CHANGELOG.md.template` — audit log seed with bootstrap entry, examples for common change types
- `assets/brand-docs/RECIPES.md.template` — common-task playbook (add a sheet, refresh press kit, run vocab check, etc.)

Walk the user through filling each section. The MANIFESTO is the highest-leverage; it's where the positioning argument actually lives, and the FAQ / TONE / PRICING / BIOS docs reference it for long-form. Do not skim it — spend real time here. A weak manifesto produces weak everything else.

The quick-ref docs are templated specifically — fill the `{{TOKEN}}` placeholders from `decisions.md` (CHEATSHEET) or genericize based on Phase 0 inventory (README, RECIPES). The CHANGELOG seeds with the bootstrap entry; future entries get appended as substantive changes happen. CLAUDE.md is mostly product-agnostic — only the `{{PRODUCT_SLUG}}` and `{{BRAND_VERB}}` placeholders need filling.

### Phase 3 — Visual asset pipeline

Set up the render pipeline that produces brand exports from HTML source sheets. Templates:

- `assets/pipeline/brand.justfile.template` — parameterized just recipes for rendering, WebP conversion, and composite reference sheets
- `assets/sheets/concept-1200x630.html.template` — concept poster (system / identity / methodology / etc)
- `assets/sheets/manifesto-1080x1350.html.template` — portrait anti-positioning card
- `assets/sheets/method-1600x900.html.template` — widescreen methodology one-pager
- `assets/sheets/readme-1280x640.html.template` — 2:1 GitHub README banner
- `assets/sheets/og-1200x630.html.template` — Open Graph image
- `assets/sheets/poster-1224x1584.html.template` — letter-portrait designer-handoff brand summary (dark + light)
- `assets/sheets/swatch-1584x1224.html.template