Skip to content

Instantly share code, notes, and snippets.

@thothagent

thothagent/2026-05-22-evaluate-impeccable-as-first-class-website-design-rail.md

Created May 22, 2026 22:21
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save thothagent/4476fb63ebdeda69a795e393f05cc11e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save thothagent/4476fb63ebdeda69a795e393f05cc11e to your computer and use it in GitHub Desktop.
Download ZIP
Issue draft: Evaluate Impeccable as first-class website design rail
Raw
2026-05-22-evaluate-impeccable-as-first-class-website-design-rail.md

Summary

A Hermes/VPS setup conversation raised whether Impeccable should become a first-class Main Branch design-quality rail, especially for lightweight website repos.

Public-safe external verification on 2026-05-22:

  • GitHub repo: pbakaus/impeccable
  • Description: "The design language that makes your AI harness better at design."
  • License: Apache-2.0
  • Stars at check time: 29,403
  • Latest release at check time: skill-v3.1.1, published 2026-05-14
  • Official site/docs describe one skill with 23 design commands, including teach, shape, craft, audit, critique, polish, and live.

This issue should decide and implement the right Main Branch integration shape without making Impeccable a required core dependency.

Product Question

Should Main Branch make Impeccable a first-class part of website/page workflows?

Short proposed answer:

Use Impeccable as an optional first-class design-quality rail for website repos, not as a required dependency of every Main Branch install.

Main Branch should own:

  • repo/profile detection;
  • website design brief workflow;
  • design token and CMS schema placement;
  • readiness/status/doctor facts;
  • public/private boundaries;
  • deterministic checks and graceful degradation;
  • clear handoff to the parent business hub.

Impeccable should own:

  • design fluency;
  • anti-pattern vocabulary;
  • design critique/audit/polish workflow;
  • visual iteration commands where the runtime supports them.

Why It Matters

Main Branch website repos are a natural place where AI-generated output can become generic, visually weak, or inconsistent with the business. A first-class design-quality rail would improve the Ship loop for pages, offers, launch pushes, docs sites, and public marketing surfaces.

The same conversation also raised a repo-typing system ("Repology"). Impeccable integration should depend on that repo profile layer: auto-load or recommend Impeccable only where the current repo is a website/UI repo, not in finance/legal/source repos or ordinary business hubs.

Recommended Abstraction

Do not vendor Impeccable into mb core by default.

Treat it as an optional external design sidecar/skill:

  • detected by mb;
  • recommended by mb site / future mb design;
  • invoked by runtime skills when available;
  • recorded in repo-safe design metadata;
  • skipped with clear fallback when missing.

This matches the existing dependency policy in docs/dependency-choices.md: optional sidecars/tools can enrich Sense and Ship workflows, but missing sidecars must not break core mb.

Touch Points

1. Repo Profile / Auto-Load

Only consider Impeccable auto-load when the repo declares or is detected as:

  • role: site, profile: lightweight_website;
  • or a product/code repo with a frontend surface;
  • or an explicit project marker such as PRODUCT.md and DESIGN.md.

Do not auto-load for:

  • business_hub unless a site/design workflow is active;
  • finance, legal, client, restricted provider sidecars, or raw community/member source repos;
  • unknown repos without explicit user intent.

For website repos, the profile descriptor can eventually include:

{
  "website": {
    "product_brief": "PRODUCT.md",
    "design_brief": "DESIGN.md",
    "design_tokens": "design/tokens.json",
    "cms_schema": ".mainbranch/cms.schema.json",
    "design_quality": {
      "tool": "impeccable",
      "mode": "brand",
      "required_for_launch": false
    }
  }
}

2. Website Template

The lightweight website template should include the files Impeccable expects or can use cleanly:

PRODUCT.md
DESIGN.md
design/tokens.json
.mainbranch/cms.schema.json
.mainbranch/conversion.json
.mainbranch/repo.json
content/
src/
public/

Main Branch should be able to generate starter PRODUCT.md / DESIGN.md from hub context:

  • core/brand/
  • core/offer.md or core/offers/<slug>/offer.md
  • core/audience or audience frontmatter where present
  • linked push
  • linked decision/research files

Impeccable can then refine, audit, or polish that design context.

3. Skill / Runtime Workflow

Possible skill surface:

  • extend .claude/skills/mb-site with an optional design-quality section;
  • or add a focused mb-design skill if this becomes broader than sites.

Runtime behavior should be profile-aware:

  1. Read .mainbranch/repo.json.
  2. If website repo, read PRODUCT.md, DESIGN.md, design/tokens.json, and CMS schema.
  3. If Impeccable is installed/discoverable, route to the appropriate Impeccable command.
  4. If not installed, produce the Main Branch design brief/checklist fallback without claiming Impeccable ran.
  5. Save durable decisions to the repo or parent hub only when appropriate:
    • design system/site facts in the website repo;
    • business strategy/offer/push decisions in the hub.

Candidate mapping:

  • New site: mb site init -> Main Branch website skeleton -> /impeccable teach or shape.
  • Design brief only: /impeccable shape from business/offer context, no code mutation.
  • Build/polish: /impeccable craft or polish inside the website repo.
  • Review: audit/critique before launch.
  • Live iteration: live only when dev server and runtime support are available.

Runtime support claims must stay honest. Claude Code may be first-class if smoked. Codex/Hermes should be described as target/experimental until adapter and smoke evidence exist.

4. CLI Integration

Do not make impeccable a hard Python dependency.

Add deterministic checks around it:

Possible command shape:

mb site check --design
mb design check
mb doctor
mb status --json --peek

Checks should answer:

  • Is the current repo a website/UI repo?
  • Are PRODUCT.md and DESIGN.md present?
  • Are design tokens present and valid JSON?
  • Is there a CMS schema?
  • Is Impeccable installed/discoverable for this runtime?
  • What version/release was detected?
  • Did a design audit/check run, or is it missing/manual?
  • What should the operator do next?

If Impeccable offers a stable CLI JSON output for anti-pattern detection, mb can shell out behind an optional check. If not, mb should limit itself to detection and runtime guidance.

5. Design Brief Workflow

Main Branch should own the business-to-design handoff:

  • extract offer, audience, proof boundaries, brand voice, channel, CTA, and launch push constraints from the hub;
  • create a website-local PRODUCT.md;
  • create or update DESIGN.md;
  • write or validate design/tokens.json;
  • connect to .mainbranch/cms.schema.json;
  • record which hub files informed the design brief.

Impeccable should then use those files for craft/audit/polish.

6. CMS Schema

Website repos need a content model separate from the business hub:

.mainbranch/cms.schema.json

The schema should describe editable content collections such as:

  • pages;
  • sections;
  • testimonials/proof snippets that are already approved for public use;
  • FAQs;
  • offers/pricing blocks;
  • legal/privacy pages;
  • navigation.

It should not contain raw customer/member data, raw private proof, secrets, or unpublished strategy.

mb validate should eventually validate this schema, and mb site check should report whether site content conforms.

7. Design Tokens

Use a deterministic token file:

design/tokens.json

Minimum useful shape:

{
  "schema": "mb.design_tokens.v0",
  "color": {},
  "typography": {},
  "spacing": {},
  "radius": {},
  "motion": {},
  "components": {}
}

This gives agents, CMS tooling, and future dashboards one stable place to inspect design choices instead of scraping CSS.

8. Other Useful Integrations

Evaluate, separately from Impeccable itself:

  • Playwright screenshot checks for desktop/mobile rendering;
  • accessibility checks;
  • Lighthouse or equivalent static checks;
  • Cloudflare preview/deploy readiness;
  • social/OG image rendering checks;
  • mb image prompt/output records for brand imagery;
  • visual diff artifacts stored outside public repos unless safe;
  • GitHub Checks integration for team repos.

These should remain deterministic checks or optional sidecars, not mixed into a design prose workflow.

Implementation Risks

  • Supply chain: do not run npx installers silently; require explicit operator action or documented install path.
  • Runtime claims: Impeccable's docs may list many AI harnesses, but Main Branch should only claim support after adapter and smoke evidence.
  • Version churn: Impeccable is moving quickly; pin or record detected versions in evidence.
  • Slash-command conflict: /impeccable commands are runtime-specific; mb should not pretend they are native mb commands.
  • Repo boundary: design edits belong in the website repo; business decisions and launch strategy belong in the parent hub.
  • Public/private: design briefs may include sensitive offer strategy. Website repos should default private unless source is intentionally public.
  • User confusion: "first-class" should mean integrated checks and workflow, not bundled mandatory dependency.

Suggested Implementation Slices

  1. Decision slice: add a dependency decision row for Impeccable as optional first-class website design rail.
  2. Repo profile dependency: wait for or pair with the repo-profile issue so auto-load is gated by profile: lightweight_website.
  3. Template slice: add website skeleton files for PRODUCT.md, DESIGN.md, design/tokens.json, .mainbranch/cms.schema.json.
  4. CLI detection slice: surface design context/readiness in mb site check, mb status --json --peek, and mb doctor.
  5. Skill slice: add optional Impeccable handoff to mb-site or create mb-design.
  6. Runtime smoke slice: verify at least one website repo workflow in Claude Code; add Codex/Hermes only after evidence.
  7. Launch readiness slice: make design audit status visible before page launch without blocking all site work.

Acceptance Criteria

  • Main Branch has a written decision on whether Impeccable is adopted, optional, reference-only, or declined.
  • Website repo profile guidance explains when Impeccable should be used and when it should not be loaded.
  • A lightweight website template can carry PRODUCT.md, DESIGN.md, design/tokens.json, and .mainbranch/cms.schema.json.
  • mb site check or a related command reports design-context readiness without requiring Impeccable to be installed.
  • If Impeccable is detected, mb reports version/discovery facts and a safe next action.
  • Skill guidance routes design work to the website repo, not the parent business hub.
  • Runtime support claims are backed by smoke evidence.
  • Public/private and supply-chain boundaries are explicit.

Related

  • Repo-profile / Repology issue to be created from the same conversation
  • #615: Hermes Agent integration and cross-platform skill primitives
  • #631: repo-boundary decision helper
  • docs/dependency-choices.md
  • docs/child-repo-descriptors.md
  • mb/mb/site.py
  • mb/mb/topology.py
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment