Issue draft: Define repo profiles for lightweight website repos (Repology)

Summary

A Hermes/VPS setup conversation raised a larger Main Branch architecture question: Main Branch already has hub/child repo topology, but it does not yet have a small, CLI-owned repo typing contract that tells mb whether the current checkout is a full business brain, a lightweight website repo, a product/code repo, a private source repo, or an integration sidecar.

Internal nickname from the conversation: Repology. Public-facing product copy should probably call this "repo profile" or "repo type" unless maintainers deliberately adopt the Repology name.

This issue should turn the existing topology work into an actionable minimal repo-type schema and CLI behavior, especially for lightweight website repos.

Current State Found In The Codebase

There are no current Repology references in the repo or open GitHub issues.

Existing relevant surfaces:

decisions/2026-05-08-business-repo-topology-map.md defines hub/child topology, roles, lifecycles, visibility, relationships, and safe metadata boundaries.
docs/child-repo-descriptors.md defines .mainbranch/repo.json with schema: mb.child_repo.v0.
mb/mb/topology.py reads core/operations/repo-topology.md, .mainbranch/repo.json, and legacy .mainbranch/source.json.
mb/mb/validate.py validates core/operations/repo-topology.md role/lifecycle/visibility/relationship frontmatter.
mb/mb/site.py reads .mainbranch/repo.json, legacy .mainbranch/source.json, and .mainbranch/conversion.json for paid-traffic site readiness.
mb status, mb graph, and mb doctor already consume topology facts.
#406, #417, #418 landed the topology/descriptor/status foundation.
#631 remains open for first-run repo-boundary decision help.

What is missing: a repo-local profile contract that can drive CLI behavior in the current repo without requiring the full business repo shape.

Problem

Website repos should not be forced to look like full Main Branch agent/business repos.

A website repo is usually:

lighter;
content-driven;
deploy-oriented;
backed by design tokens and CMS/content schemas;
linked to a parent business hub for strategy, offers, pushes, decisions, and checkpoints;
sometimes public output from private source;
sometimes edited by agents/runtimes that need design and launch checks, not the whole business operating brain.

Today mb init scaffolds the full business repo shape. mb status in non-business repos can report "no Main Branch repo" and then recommend mb init, even when the right answer is "this is a child site repo; link it to a hub and run site/design checks."

Proposed Direction

Add a minimal repo typing/profile layer on top of the existing topology model.

Keep role as business meaning:

business
site
offer
product
client
finance
legal
ops
integration_sidecar
experiment
archive

Add profile or repo_type as the CLI contract:

business_hub: full Main Branch business brain with core/, research/, decisions/, bets/, pushes/, skills, status, checkpoints, graph, providers.
lightweight_website: site/lander/docs/content repo; may have content, templates, design tokens, CMS schema, deploy metadata, measurement metadata, and a parent hub.
code_product: product/application/tool repo; has build/test commands and linked business context, but not necessarily full business memory.
private_source: restricted finance/legal/customer/member/source repo; safe descriptor only, raw private data stays inside its access boundary.
integration_sidecar: optional tool/provider sidecar that emits approved summaries or JSON envelopes back to the hub.
archive: inert historical repo with no default agent mutation path.

The exact slug names are negotiable. The important design is that role explains the repo's business purpose, while profile explains what mb should check, scaffold, and suggest in that checkout.

Minimal Schema Sketch

Preferred path:

.mainbranch/repo.json

Current child descriptor compatibility:

{
  "schema": "mb.child_repo.v0",
  "role": "site",
  "display_name": "Workshop site",
  "github_owner": "example-co",
  "repo_name": "workshop-site",
  "safe_purpose": "Public site for the workshop offer.",
  "parent": {
    "display_name": "Example Business",
    "github_owner": "example-co",
    "repo_name": "example",
    "remote": "github:example-co/example",
    "local_checkout": "../example"
  },
  "linked": {
    "offers": ["core/offers/workshop/offer.md"],
    "pushes": ["pushes/2026-05-20-workshop-launch/push.md"],
    "bets": [],
    "decisions": []
  },
  "safe_to_share": true
}

Proposed additive target:

{
  "schema": "mb.repo.v1",
  "role": "site",
  "profile": "lightweight_website",
  "display_name": "Workshop site",
  "github_owner": "example-co",
  "repo_name": "workshop-site",
  "visibility": "team_private",
  "safe_purpose": "Public site for the workshop offer.",
  "parent": {
    "display_name": "Example Business",
    "github_owner": "example-co",
    "repo_name": "example",
    "remote": "github:example-co/example",
    "local_checkout": "../example"
  },
  "linked": {
    "offers": ["core/offers/workshop/offer.md"],
    "pushes": ["pushes/2026-05-20-workshop-launch/push.md"],
    "bets": [],
    "decisions": []
  },
  "website": {
    "domain": "workshop.example.com",
    "deploy_provider": "cloudflare_pages",
    "source_root": "src",
    "content_root": "content",
    "public_root": "public",
    "build_output": "dist",
    "cms_schema": ".mainbranch/cms.schema.json",
    "design_tokens": "design/tokens.json",
    "product_brief": "PRODUCT.md",
    "design_brief": "DESIGN.md",
    "measurement_plan": ".mainbranch/conversion.json"
  },
  "checks": ["site", "content_schema", "design_tokens", "measurement", "build"],
  "safe_to_share": true
}

For a full business hub:

{
  "schema": "mb.repo.v1",
  "role": "business",
  "profile": "business_hub",
  "display_name": "Example Business",
  "github_owner": "example-co",
  "repo_name": "example",
  "visibility": "team_private",
  "safe_purpose": "Company-level strategy, decisions, bets, pushes, and operating memory.",
  "hub": {
    "schema_marker": ".mb/schema-version",
    "topology_registry": "core/operations/repo-topology.md"
  },
  "checks": ["status", "doctor", "validate", "graph", "checkpoint", "provider_readiness"],
  "safe_to_share": true
}

Do not commit absolute local paths, secrets, raw provider caches, customer/member data, private account exports, finance/legal source data, or permission claims.

Lightweight Website Repo Pattern

Target skeleton:

.mainbranch/
  repo.json
  cms.schema.json
  conversion.json
AGENTS.md or CLAUDE.md
PRODUCT.md
DESIGN.md
design/
  tokens.json
content/
  pages/
  collections/
src/
  layouts/
  components/
  pages/
public/
package.json or chosen static-site config
README.md

Notes:

PRODUCT.md captures audience, offer, register, brand personality, anti-references, and site purpose.
DESIGN.md captures visual system, typography, color, spacing, components, motion, accessibility, and usage rules.
design/tokens.json is deterministic design data for templates, agent checks, and future CMS/editor surfaces.
.mainbranch/cms.schema.json defines content collections and fields. It should be JSON Schema or a small Main Branch wrapper around JSON Schema, not prose-only guidance.
.mainbranch/conversion.json remains the measurement/paid-traffic readiness file already used by mb site check.
The repo should link back to the parent hub instead of duplicating offer strategy, decisions, or push records.

CLI Touch Points

mb init

Keep current full business behavior as default.
Add either mb init --type business|website or a clearer mb site init command.
website init writes the lightweight website skeleton and .mainbranch/repo.json.
Do not install or require the full business folder tree in website repos.

mb status

Detect repo profile from .mainbranch/repo.json, current hub markers, and legacy .mainbranch/source.json.
Render website repo status as "Site repo" or "Website workspace" instead of "no Main Branch repo."
Show parent hub link health, content schema health, design token/design brief presence, build/deploy readiness, measurement readiness, and dirty/checkpoint state.
In a child repo, recommend returning to the hub for strategy/routing and staying in the child for site/code edits.

mb doctor

Avoid business-hub-only failures in a lightweight website repo unless that profile requires them.
For website profile, check parent descriptor, relative local checkout safety, Cloudflare/provider readiness, build tool availability, design/CMS files, and measurement metadata.
Keep Claude Code/Codex/Hermes runtime checks profile-aware.

mb validate

Add JSON validation for .mainbranch/repo.json and .mainbranch/cms.schema.json.
Preserve mb.child_repo.v0 and legacy .mainbranch/source.json compatibility.
Add safe-key and local-absolute-path checks to JSON descriptors.

mb graph

Include repo profile/type as graph node metadata.
Add edges from website repo to parent hub, linked offer, linked push, design brief, content schema, measurement plan, and provider handles.

mb site check

Use the repo profile to decide whether the current repo is a site repo without requiring --business-repo when a safe relative parent checkout exists.
Extend evidence beyond GTM/measurement into content schema, design tokens, and build/deploy rails in future slices.

mb start

In a website repo, hand off to site/design/build checks and say when to return to the hub.
Do not imply full business repo setup is missing when a valid lightweight website descriptor exists.

mb skill link

Consider profile-specific skill linking. A website repo may need mb-site, design workflow guidance, and runtime-local instructions, not every business skill.

Parent / Child Behavior

Hub core/operations/repo-topology.md remains durable business truth.
Child .mainbranch/repo.json is the repo-local signpost.
If they disagree, mb status and mb doctor should call it topology drift.
Parent references should use GitHub owner/repo and optional relative local checkout only.
Parent hub owns strategy, offers, bets, pushes, decisions, and cross-repo checkpoints.
Website child owns content, templates, site-specific design, build/deploy config, and local site execution history.

Interaction With Community / Skool / Private Repos

Do not treat "website repo" as the generic answer for community or member data.

Public community landing/docs site: role: site, profile: lightweight_website.
Raw Skool/community/member exports: likely restricted integration_sidecar or future community/source profile, not public site truth.
Private finance/legal/client/member data: profile: private_source or restricted sidecar. Hub receives approved summaries and safe links only.
Public output does not require public source; website repos should default private unless the source itself is intentionally public.

Backward Compatibility

Existing .mainbranch/source.json site repos must keep working.
Existing .mainbranch/repo.json with schema: mb.child_repo.v0 must keep working.
Existing hub topology mb.repo_topology.v0 should not break.
Additive fields should be ignored safely until the CLI knows them.
Migration path should be preview-first: mb migrate status, then maybe mb migrate repo-descriptor --plan.

Suggested Implementation Slices

Decision/spec slice: document repo profile vocabulary and schema target.
Reader slice: extend mb.topology to normalize profile while preserving v0 descriptors.
Validator slice: validate .mainbranch/repo.json and .mainbranch/cms.schema.json.
CLI detection slice: make mb status, mb doctor, mb start, and mb site check profile-aware.
Init slice: add mb site init or mb init --type website.
Template slice: add lightweight website skeleton and generated instructions.
Runtime smoke slice: verify Claude Code/Codex/Hermes-adjacent handoff does not write business memory into the wrong repo.

Acceptance Criteria

A documented repo profile/type contract exists and explains why it is separate from topology role.
mb can identify at least business_hub, lightweight_website, and unknown/non-Main-Branch repos.
A lightweight website repo can be initialized without the full business folder tree.
Existing business repos, child descriptors, and legacy site source links remain compatible.
mb status and mb doctor give profile-appropriate recommendations in a website repo.
Public/private boundaries for website, private source, community/provider sidecar, finance/legal, and parent hub repos are explicit.
Tests cover descriptor parsing, validation, status/doctor behavior, and legacy compatibility.

#406: topology model decision
#417: generalized child repo descriptors
#418: topology facts in status/graph/doctor
#631: first-run repo-boundary decision helper
docs/child-repo-descriptors.md
decisions/2026-05-08-business-repo-topology-map.md

thothagent/2026-05-22-define-repo-profiles-for-lightweight-website-repos.md

Select an option

No results found