Brand Gen Setup

Pi / Sage full-pipeline prompt

For Sage brand work in Pi, use the paste-ready prompt at docs/prompts/pi-sage-brand-gen-full-pipeline.md. It routes Pi through the typed brand_* tools, the brand-orchestrator subagent, exact-text gates, v2/DSPy review, GEPA-ready disagreement fields, and typed mutation loops. Keep this link instead of copying the full prompt into skill bodies.

This skill covers installation, validation, and host wiring.

After setup is complete, load:

• skills/brand-gen/SKILL.md — main workflow
• skills/brand-gen-reference/SKILL.md — models, surfaces, file layout
• skills/brand-gen-logo/SKILL.md — logo workflows
• skills/brand-content-ideation/SKILL.md — messaging/copy ideation

New saved brands and testing sessions also get a generated Pi runtime prompt at <brand-dir>/prompts/pi-full-pipeline.md. Use that brand-scoped prompt for non-Sage brands instead of the Sage-specific prompt under docs/prompts/.

Prerequisites

• Python 3.11+
• a Replicate API token
• Node.js if using Pi, OpenClaw, or agent-browser

Step 1 — clone and install

git clone <your-fork-or-repo-url>
cd brand-gen
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .
bgen --help

If bgen is not found, activate the venv first.

Step 2 — configure environment

cp .env.example .env

Set REPLICATE_API_TOKEN in .env.

Important notes:

• repo-local .env is the preferred config source
• a legacy host-specific fallback may still be read for compatibility
• set BRAND_GEN_DIR if you want durable state outside the repo checkout

Local config

Create .brand-gen-local.json at the repo root. The agent should do this automatically:

1. Detect repo_root from the current working directory (pwd).
2. Ask the user: "Do you have an Obsidian vault or brand docs folder you want to connect? If so, what's the path and which brand should use it?" If yes, prefer a brand-specific map (brand_vault_paths / brand_knowledge_base_paths). Use global vault_paths only for a single-brand checkout.
3. Write the file:

{
  "repo_root": "<detected path>",
  "vault_paths": [],
  "brand_vault_paths": {
    "<brand-key>": ["<user-provided Obsidian vault path if any>"]
  },
  "brand_knowledge_base_paths": {
    "<brand-key>": ["<user-provided docs path if any>"]
  }
}

This file is only needed for Pi agents. If the user is CLI-only, skip this step. Do not put Sage vault paths in global vault_paths for a multi-brand workspace; each brand should inherit only its own source knowledge.

Creative defaults (quality benchmarks, concept categories, metaphor vocabulary) are stored per-brand in brand-profile.json → creative_context and seeded on bgen create-brand.

Verify creative_context

After creating or connecting a brand, verify brand-profile.json contains a creative_context block. If missing (older brands or extract-brand workflows), the agent should create it with defaults: quality_benchmarks from .brand-gen-local.json or ["Stripe", "Aesop", "Criterion", "Muji"], concept_categories derived from the brand's keywords, metaphor_vocabulary empty.

Step 3 — install recommended optional tools

agent-browser is treated as required by the validation script because capture/inspiration workflows depend on it, even though basic generation can run without it.

Step 4 — validate

python3 scripts/validate_setup.py

This checks:

• required commands
• optional commands
• required env vars
• optional env vars
• which env files are being read

Fix any required missing items before moving on.

Step 5 — connect to your agent

Start with the most generic option your host supports.

CLI-first agents

Add instructions like:

For brand material generation, use `bgen ...` or `python3 -m brand_gen ...`.
Start by checking `bgen context-snapshot --format json`.

Any MCP-compatible host

Run the stdio MCP server:

python3 -m brand_gen.brand_iterate_mcp

Register that command in your host’s normal MCP config.

Claude Code

If your Claude setup expects copied local skills:

cp -r skills/brand-gen-setup/ ~/.claude/skills/brand-gen-setup/
cp -r skills/brand-gen/ ~/.claude/skills/brand-gen/
cp -r skills/brand-gen-reference/ ~/.claude/skills/brand-gen-reference/
cp -r skills/brand-gen-logo/ ~/.claude/skills/brand-gen-logo/
cp -r skills/brand-content-ideation/ ~/.claude/skills/brand-content-ideation/
cp -r skills/brand-gen-orchestration/ ~/.claude/skills/brand-gen-orchestration/

claude mcp add brand-gen -- python3 -m brand_gen.brand_iterate_mcp

Or add the MCP server manually to Claude’s config with cwd set to the repo root.

Pi

Use the tracked package under packages/pi-brand-gen/.

Install Pi first using the official quickstart in the badlogic/pi-mono coding-agent README:

• https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md
• current install command: npm install -g @mariozechner/pi-coding-agent
• then either export an API key before running pi, or run pi and use /login

Typical local setup from the repo checkout:

cd packages/pi-brand-gen
npm install
npm run typecheck

Then register the local extension in Pi. Note that brand-gen's Pi integration currently ships from this repo checkout under packages/pi-brand-gen/; it is not yet a standalone published Pi package. Configure at least:

• brandGenDir
• optionally brandIterateMcpPath, approvalMode, heartbeatIntervalMinutes, autoHeartbeat

Important Pi note:

• the backend still reads the repo .env, so set REPLICATE_API_TOKEN there
• in a normal repo checkout or fork, Pi auto-detects brand_gen/brand_iterate_mcp.py
• Pi prefers <repo>/.venv/bin/python if that interpreter exists; otherwise it falls back to python3
• only set brandIterateMcpPath if you need to override the detected backend path

After Pi is wired up, verify with:

/brand-gen status
/brand-gen brands
/brand-gen summary

If you need to change the active saved brand inside Pi, use:

/brand-gen switch <brand>

Creating a new saved brand or starting a testing session is still CLI-first today:

bgen create-brand ...
bgen start-testing ...

See packages/pi-brand-gen/README.md for the current config and command surface.

OpenClaw

Use the tracked package under packages/openclaw-brand-gen/.

Typical local setup from the repo checkout:

cd packages/openclaw-brand-gen
npm install
npm run typecheck

Then configure the plugin with at least:

• brandIterateMcpPath
• optionally brandGenDir, logoIterateMcpPath, approvalMode, autoHeartbeat

See packages/openclaw-brand-gen/README.md for the current config and tool surface.

Loading the orchestration pipeline

For the full 6-phase generation pipeline (prepare → plan → validate → generate → critique → evolve), load skills/brand-gen-orchestration/SKILL.md after setup. This skill encodes the multi-agent quality workflow as sequential instructions any host can follow.

On OpenClaw, add it to your skills paths. On Claude Code, copy it to ~/.claude/skills/. On CLI-first agents, reference it in your agent instructions.

Step 6 — verify with a test run

bgen create-brand \
  --name "test-brand" \
  --description "A test brand for validating the setup" \
  --tone "calm,modern" \
  --palette "#336699"

bgen pipeline \
  --material-type x-feed \
  --goal "Validation run" \
  --mode hybrid \
  --format json

bgen show --format json --latest 1

If the pipeline completes and show returns a recent version, the install is working end to end.

Troubleshooting

What to do next

Once setup is validated, load skills/brand-gen/SKILL.md for the real workflow.