Build guide

Bounded extensions move through an explicit build, validation, and promotion lifecycle.

The detailed build path stays narrow on purpose: bundle-first, preview-workspace validation, explicit review gates, and service-backed runtime only when clearly justified.

Open the extension developer start page Review the extension model

Agent-first route: Start at /agents, inspect /docs/cli, and drop into this page when you need proof, detail, or rollout guidance.

Agent-first route

Humans should usually delegate first-pass evaluation to an agent. Agents should start at /agents, use /docs/cli as the official product tour, and open /docs/graphql only when needed.

Agent-ready surface

Start with the CLI, not browser guesswork.

Preferred route: /agents, then /docs/cli, then /docs/graphql only when lower-level integration details matter.

$ mbr spec export --json
$ mbr auth whoami --json
$ mbr queues list --workspace ws_preview --json

Open GraphQL reference | Open schema.graphql

Public start page first

Use `/extension-developers` as the public route that sends humans and agents into the right authoring path before they drop into this detailed guide.

Prerequisites exist first

The build path assumes there is already a running instance, an authenticated CLI, and a preview workspace.

Proof

Definition extension-sdk/README.md Defines the extension authoring contract and the intended bundle-first default.
Definition extension-sdk/START_HERE.md Single-file agent handoff for creating and validating a bounded extension.
Implementation extension-sdk/manifest.json Concrete extension manifest scaffold for scope, kind, and runtime behavior.
Enforcement extension-sdk/security/threat-model.md Threat-model prompt used before activating custom extensions.

Bounded capability

Define the slice and its relationship to the core primitives.

Proof

Definition docs/ARCHITECTURE.md Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
Definition docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md Defines when work belongs in the instance repo versus a separate extension repo.
Contract docs/EXTENSION_SECURITY_MODEL.md Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
Implementation extension-sdk/README.md Shows the canonical public scaffold for bounded custom extension authoring.

Bundle-first default

Start workspace-scoped, standard-risk, and bundle-first unless the requirement clearly needs more.

Proof

Definition extension-sdk/README.md Defines the extension authoring contract and the intended bundle-first default.
Definition extension-sdk/START_HERE.md Single-file agent handoff for creating and validating a bounded extension.
Implementation extension-sdk/manifest.json Concrete extension manifest scaffold for scope, kind, and runtime behavior.
Enforcement extension-sdk/security/threat-model.md Threat-model prompt used before activating custom extensions.

Supported generic slice

The generic self-built path is for workspace-scoped standard-risk product or operational extensions.

Proof

Definition docs/ARCHITECTURE.md Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
Definition docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md Defines when work belongs in the instance repo versus a separate extension repo.
Contract docs/EXTENSION_SECURITY_MODEL.md Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
Implementation extension-sdk/README.md Shows the canonical public scaffold for bounded custom extension authoring.

Preview-workspace validation

Validate in a preview workspace before production review.

Proof

Contract docs/AGENT_CLI.md Defines the supported agent CLI contract, auth modes, and command surface.
Contract docs/swagger.yaml Documents the public API surface, auth model, and health endpoints.
Implementation cmd/api/routers.go Implements the split between `/graphql`, `/admin/graphql`, public routes, and authenticated agent surfaces.
Enforcement .github/workflows/_test.yml Verifies builds, tests, and contract-sensitive paths on the public platform codebase.

Service-backed needs justification

Only move into handlers, jobs, event consumers, or owned schema when the requirement truly calls for it.

Proof

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition docs/EXTENSION_ENDPOINT_MODEL.md Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
Definition docs/EXTENSION_SECURITY_MODEL.md Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
Implementation internal/platform/domain/extension.go Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation internal/platform/domain/extension_runtime.go Enforces that only service-backed `owned_schema` extensions can register owned schemas.
Implementation internal/infrastructure/stores/sql/extension_runtime_store.go Stores extension package registrations and schema migration history in the shared core runtime store.

Table of contents

Section map.

Jump directly to the part you need.

The extension SDK is not the first step in the journey. Prerequisites Begin with the simplest safe extension shape. Default rule The CLI gives the shortest supported path from source tree to a live preview-workspace extension. Local development loop Do not add backend process complexity unless the requirement truly needs it. When to add service-backed runtime Activation should happen only after the threat model and review checklist are complete. Review gates

Prerequisites

The extension SDK is not the first step in the journey.

Start a custom extension repo only after there is a Move Big Rocks instance you control, `mbr` is authenticated to it, and a preview workspace exists for safe installs. If those do not exist yet, the deployment and instance-repo path comes first.

Use `/extension-developers` as the public start page when the builder or agent still needs the routing and boundary summary.
Use `/docs/self-host` first when the runtime does not exist yet.
Log in with `mbr auth login` before trying extension commands.
Treat the preview workspace as the default proving ground for installs and upgrades.

Default rule

Begin with the simplest safe extension shape.

The canonical authoring flow starts from the extension SDK and keeps the first version narrow. That means `workspace` scope, `standard` risk, and `bundle` runtime unless the product slice truly needs more infrastructure.

Proof bundle

Definition extension-sdk/README.md Defines the extension authoring contract and the intended bundle-first default.
Definition extension-sdk/START_HERE.md Single-file agent handoff for creating and validating a bounded extension.
Implementation extension-sdk/manifest.json Concrete extension manifest scaffold for scope, kind, and runtime behavior.
Enforcement extension-sdk/security/threat-model.md Threat-model prompt used before activating custom extensions.

Keep the repo separate from the core repo and from the private instance repo.
Rename the manifest, routes, and publisher details before deeper work.
Stay inside the supported generic self-built slice: `workspace`, `standard`, and `product` or `operational`.
Do not force `instance`, `privileged`, `identity`, or `connector` extensions through the generic SDK path.
Implement one useful admin or public page before adding more surface area.
Ship one bundled agent skill so the extension remains legible to agents.

Local development loop

The CLI gives the shortest supported path from source tree to a live preview-workspace extension.

The public extension build story should be operational, not aspirational. These commands come from the extension SDK handoff and show the default loop for building and operating a custom extension.

Proof bundle

Definition extension-sdk/README.md Defines the extension authoring contract and the intended bundle-first default.
Definition extension-sdk/START_HERE.md Single-file agent handoff for creating and validating a bounded extension.
Implementation extension-sdk/manifest.json Concrete extension manifest scaffold for scope, kind, and runtime behavior.
Enforcement extension-sdk/security/threat-model.md Threat-model prompt used before activating custom extensions.

Treat `extension.contract.json` as a checked-in proof artifact, not generated noise.
For workspace-scoped admin UI, make instance-admin entrypoints work even without an active workspace session.

Lint, verify, and inspect before rollout

Use a preview workspace first, then prove the runtime surface before treating the extension as ready.

$ mbr extensions lint . --json$ mbr auth login --url https://app.yourdomain.com$ mbr workspaces list$ mbr extensions verify . --workspace ws_preview --json$ mbr extensions nav --instance --json$ mbr extensions widgets --instance --json$ mbr extensions skills list --id EXTENSION_ID

Refresh the contract and prove the same surface again

When the extension changes, update the checked-in contract deliberately and rerun the same proof loop before rollout or rollback decisions.

$ mbr extensions lint . --write-contract --json$ mbr extensions verify . --workspace ws_preview --json$ mbr extensions nav --instance --json$ mbr extensions deactivate --id EXTENSION_ID

When to add service-backed runtime

Do not add backend process complexity unless the requirement truly needs it.

Bundle-first is the default because most workflow extensions do not need their own long-running service. Move into `service_backed` only when the extension needs custom endpoint handlers, event consumers, scheduled jobs, health checks, or an owned `ext_*` schema and migrations. The SDK now documents this as an explicit upgrade path rather than leaving authors to invent it.

Proof bundle

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition docs/EXTENSION_ENDPOINT_MODEL.md Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
Definition docs/EXTENSION_SECURITY_MODEL.md Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
Implementation internal/platform/domain/extension.go Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation internal/platform/domain/extension_runtime.go Enforces that only service-backed `owned_schema` extensions can register owned schemas.
Implementation internal/infrastructure/stores/sql/extension_runtime_store.go Stores extension package registrations and schema migration history in the shared core runtime store.

If the requirement is mostly branded pages, workflow seeds, bundled skills, or admin UI, stay bundle-first.
If the extension must ingest external traffic, process domain events, or own a richer data model, service-backed is justified.
Service-backed does not remove the need for shared routing, shared auth, shared audit, or shared lifecycle controls.

Review gates

Activation should happen only after the threat model and review checklist are complete.

The extension security model is explicit about what must happen before a self-built extension leaves preview-only evaluation. The goal is not merely that the extension runs. The goal is that its trust boundaries and operational impact are reviewable.

Proof bundle

Definition docs/ARCHITECTURE.md Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
Definition docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md Defines when work belongs in the instance repo versus a separate extension repo.
Contract docs/EXTENSION_SECURITY_MODEL.md Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
Implementation extension-sdk/README.md Shows the canonical public scaffold for bounded custom extension authoring.

Threat-model the extension before activation.
Record the review result in the instance-repo workflow before production rollout.
Review public routes, external calls, permissions, secret needs, and failure behavior.
Treat production activation as a human-visible decision even when an agent prepared the extension.

Move Big Rocks

Let agents inspect the CLI-first surface. Let humans decide trust, rollout, and boundaries.

Start from /agents, use /docs/cli as the official product tour, inspect /resources for source and proof, and review /security before making deployment or data-handling decisions.

Open /agents Open resources