Documentation

Everything you need
to use B2

Install in two commands. Start with /b2. Each command explains exactly what to do next.

Quickstart

Two commands to install. One command to start.

# Step 1 — add the marketplace
/plugin marketplace add bofrese/claude-plugins

# Step 2 — install B2
/plugin install b2@bofrese-plugins

# Start your project
/b2

/b2 reads your project state and recommends exactly one next action. Follow it. B2 enforces the correct order — running /b2:brand without a vision document stops with a clear error.

Requirements: Claude Code · Claude Pro plan recommended

Command reference

Commands are listed in execution order: exploration, setup (run once), then maintenance (ongoing).

/b2 — Orchestrator

The entry point. Reads project state, shows a status table, and recommends exactly one next action. Never presents multiple options. In maintenance mode (all setup phases complete), shows available maintenance commands.

/b2:talk — Exploration

Anytime command. Communication strategist persona — pushes back on vague answers, captures stories, positioning, and voice. Saves to docs/notes/. Read automatically by every setup command that follows.

Not required — but the more you put in, the less the setup steps have to ask.

/b2:vision — Vision Expert

Structured interview: purpose, audience, success criteria. Mom Test principles — past behaviour and concrete facts only. No hypotheticals.

Produces: docs/product/vision.md

/b2:brand — Brand Expert

Brand positioning interview: name, tagline, competitive positioning, tone of voice (3 adjectives tested against real scenarios), primary CTA (forced to one), and what the site deliberately does not say.

Produces:

  • docs/product/website-design-brief.md — human-readable brand record
  • ai/decisions.md — terse voice guide read by every future AI call

/b2:structure — Structure Expert

Information architecture: pages, content types, navigation, user journey. Creates website/docs/content-types.md, subfolders, and stub .md files.

/b2:write — Write Expert

World-class copywriter persona. Reads ai/decisions.md for brand voice. Harvests existing content (URL, file, or paste). Proposes an outline before writing anything. Waits for approval. Writes to the correct website/src/ path with correct frontmatter.

Use during setup to fill content stubs, and again anytime you're adding or updating a page.

/b2:design — Design Expert

Five phases: interview → written design brief (approval required) → 3 concurrent HTML mockups → iteration → theme generation.

Produces website/theme/{name}/: styles.css, components.md, header.html, footer.html, scripts.js, design.md.

components.md is the contract between theme and content. design.md includes image size specifications used by SEO and review commands.

/b2:sync — Sync Expert

Converts stale .md source files to semantic HTML partials. The only AI-calling step in the maintenance workflow.

  • Detects stale files via git history, falling back to timestamps
  • For each stale file: reads source, existing partial (if any), components.md, content-types.md, and ai/decisions.md, then converts
  • Regenerates index files for content types where any item is stale
  • Integrates changes surgically if a partial exists — preserves structure, doesn't regenerate from scratch

/b2:setup — Technical Setup

Verifies theme is complete, writes website/b2.cfg (build tool, base path), creates missing directories, runs the first build. Reports success or diagnoses failure — does not auto-fix.

/b2:build — Build Expert

The recommended maintenance entry point. Runs stale-file detection, calls /b2:sync if needed, then assembles dist/. Handles the full pipeline in one command.

/b2:serve — Local Server

Starts a local server on website/dist/ at http://localhost:8099. Run after /b2:build.

/b2:website-review — Visual Review

Screenshots pages via Playwright, evaluates them against your design system (components.md, mockup.html, ai/decisions.md), and fixes layout issues directly in the partials. Flags copy issues without modifying them. Requires the local server running.

/b2:seo — SEO Expert

Full-cycle SEO audit and fix. Four buckets:

  • Auto-fixed: lang, viewport, font-display: swap, image dimensions/loading, canonical, sitemap.xml, robots.txt
  • One question then fixed: base URL (used for canonical, Open Graph, sitemap)
  • Dialog: schema markup, alt text, page titles and descriptions
  • Images: resized to what the design actually requires, converted to WebP, wrapped in <picture> for fallback

/b2:illustrate — Illustration Expert

Style brief interview on first run (produces docs/product/illustration-style.md). On subsequent runs: generates prompts, evaluates results, iterates until approved. Optional background removal via rembg.

/b2:image — Image Generation

Direct Gemini API image generation. Requires GEMINI_API_KEY in .env. Paid key required.

Build commands

/b2:build is the recommended entry point, but the underlying make commands are available if needed:

make              # Build dist/ — aborts if stale .md files detected
make watch        # Watch mode — warns on stale .md, rebuilds on .html changes
make clean        # Remove dist/
make publish      # Build + FTP dist/ to host via websync.cfg

make watch requires fswatch: brew install fswatch

Maintenance workflow

Edit website/src/page.md
→ /b2:build          (detects stale files, syncs, assembles dist/)
→ /b2:serve          (local server at http://localhost:8099)
→ /b2:website-review (visual check — requires server running)
→ /b2:seo            (full SEO audit and fix)

Writing new content:

/b2:write [topic]    (harvest → outline → approval → markdown)
/b2:build            (sync + assemble)
/b2:serve            (preview)

FAQ

Does B2 work with an existing site?

B2 is designed for new projects starting from a blank folder. Using it with an existing site is possible but not the intended use.

Can I edit the theme manually?

Yes — website/theme/{name}/ is yours. Keep styles.css and components.md in sync: if a class is in one, it must be in both. /b2:sync only uses classes listed in components.md.

What if the AI output isn't what I wanted?

Edit the source markdown in website/src/ and re-run /b2:build. Sync integrates changes surgically — it preserves existing HTML structure and doesn't regenerate from scratch.

Do I need a Claude Pro plan?

Recommended. B2 runs complex, multi-step AI workflows. Free plan rate limits can interrupt the process at inconvenient moments.

Where does the site get hosted?

Anywhere that serves static files. make publish FTPs dist/ to any host using websync.cfg.

What's the difference between /b2:sync and /b2:build?

/b2:sync converts .md to .html — the AI step. /b2:build runs the full pipeline: detects stale files, calls sync if needed, then assembles dist/. During maintenance, use /b2:build. Use /b2:sync directly only if you need the conversion step in isolation.