# Extension Developers: Start Here

Give Claude Code, Codex, or any capable agent the extension SDK and describe what you want. It scaffolds, implements, tests, and deploys a working extension against the same runtime model as the first-party set. No team required. No months of development. This is the canonical public handoff for humans and agents building a custom Move Big Rocks extension. If the task is product evaluation, start at `/agents` instead. If there is no running instance yet, stop and use `/docs/self-host` first.

## Summary

- Canonical extension-author route: Agents should send extension builders here first instead of scattering them across generic product, deployment, and runtime pages.
- Prerequisites first [Create the runtime first]: The authoring path assumes there is already a running instance, an authenticated `mbr`, and a preview workspace. (/docs/self-host)
  Proof:
- Definition: docs/CUSTOMER_INSTANCE_SETUP.md (https://github.com/MoveBigRocks/platform/blob/main/docs/CUSTOMER_INSTANCE_SETUP.md) — Defines the production self-host setup flow, required inputs, and instance-repo model.
- Definition: instance-template/README.md (https://github.com/MoveBigRocks/instance-template/blob/main/README.md) — Defines the private instance repo as the deployment control plane for one live installation.
- Contract: docs/RELEASE_ARTIFACT_CONTRACT.md (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md) — Defines pinned core artifacts and the instance-repo responsibility boundary.
- Provenance: .github/workflows/production.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/production.yml) — Shows how tests, builds, tags, and artifact digests connect source changes to shipped releases.

- Bundle-first default: The supported generic self-built path is `workspace` scope, `standard` risk, and a `bundle` runtime until the requirement truly proves otherwise.
  Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- Service-backed is an explicit later branch: Move into handlers, jobs, event consumers, or owned-schema migrations only when a real product requirement needs them.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Proof loop stays command-driven: Lint, verify, inspect nav/widgets, and check bundled skills before rollout decisions.
  Proof:
- Contract: docs/AGENT_CLI.md (https://github.com/MoveBigRocks/platform/blob/main/docs/AGENT_CLI.md) — Defines the supported agent CLI contract, auth modes, and command surface.
- Contract: docs/swagger.yaml (https://github.com/MoveBigRocks/platform/blob/main/docs/swagger.yaml) — Documents the public API surface, auth model, and health endpoints.
- Implementation: cmd/api/routers.go (https://github.com/MoveBigRocks/platform/blob/main/cmd/api/routers.go) — Implements the split between `/graphql`, `/admin/graphql`, public routes, and authenticated agent surfaces.
- Enforcement: .github/workflows/_test.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_test.yml) — Verifies builds, tests, and contract-sensitive paths on the public platform codebase.


## Use this page when the task is extension authoring, not general product evaluation.

The path is easier for humans and much easier for agents when the first routing decision is explicit. Do not mix evaluation, deployment, and extension authoring into one reading order.

- Use `/agents` for product evaluation [Canonical evaluation route]: When the question is what Move Big Rocks is, what it replaces, or whether the platform is a fit, start at `/agents` and `/docs/cli` instead. (/agents)
- Use `/docs/self-host` when no runtime exists yet [Prerequisite runtime path]: If there is no running instance or preview workspace, do not start from the SDK. Create the owned runtime first. (/docs/self-host)
- Do not start here for configured core workflows: If the workflow can already live on workspaces, teams, forms, queues, cases, knowledge, and automation, use the shared base first. Many approvals and requisitions are configuration work, not extension authoring.
- Use this page for custom extension work [Canonical extension-author route]: When the job is to build, upgrade, review, or explain a private extension, start here and then move deeper into the build and runtime references. (/docs/build-extensions)

## Agents should follow a short extension-author route and stop inventing missing steps.

The goal is a deterministic route an agent can follow without having to guess which page matters next.

- 1. Start on `/extension-developers`: Confirm prerequisites, the supported self-built slice, and whether the task is really extension work.
- 2. Open `/docs/build-extensions` [Detailed build guide]: Use the detailed build guide for the full lifecycle, review gates, and command loop. (/docs/build-extensions)
- 3. Open the extension SDK handoff [Canonical public SDK]: Use `README.md` and `START_HERE.md` in the public SDK as the concrete scaffold and local workflow. (https://github.com/MoveBigRocks/extension-sdk)
  Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- 4. Open `SERVICE_BACKED.md` only when needed [Explicit service-backed upgrade path]: Branch into service-backed runtime design only when the extension truly needs handlers, jobs, event consumers, or an owned schema. (https://github.com/MoveBigRocks/extension-sdk/blob/main/SERVICE_BACKED.md)
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- 5. Return to `/docs/extensions` for runtime boundaries [Model and trust reference]: Use the extension model reference when runtime class, endpoint class, storage class, or trust boundaries are in question. (/docs/extensions)

## Stay inside the supported generic self-built slice unless there is a strong reason not to.

The SDK and site now say this plainly because agents were otherwise too likely to infer an overpowered starting point.

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

- Start `workspace` scoped.
- Start `standard` risk.
- Start `product` or `operational` kind.
- Start `bundle` runtime.
- For a startup team, prefer one narrow workflow or product slice over a broad internal-platform fork.
- Do not force `instance`, `privileged`, `identity`, or `connector` extensions through the generic public authoring path.
- Keep the first version small enough that an instance admin and an agent can both explain it clearly.

## The first version should prove itself through one repeatable command loop.

This is the shortest supported path from a private extension repo to a preview-workspace extension with an inspectable surface.

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

- Treat `extension.contract.json` as deliberate checked-in proof, not generated noise.
- Verify workspace-scoped admin entrypoints from an instance-admin session too, not just from an already-selected workspace.
### Recommended first proof loop

Use this exact loop before you tell anyone the extension is ready.

```text
$ git clone https://github.com/MoveBigRocks/extension-sdk acme-my-extension
$ cd acme-my-extension
$ mbr extensions lint . --json
$ mbr auth login --url https://app.yourdomain.com
$ mbr extensions verify . --workspace ws_preview --json
$ mbr extensions nav --instance --json
$ mbr extensions widgets --instance --json
$ mbr extensions skills list --id EXTENSION_ID --json
```


## Move to `service_backed` only when the product requirement proves it.

Service-backed runtime is a legitimate next step, but it should be a conscious upgrade rather than the default starting point.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/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 (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- Stay bundle-first when the extension is mostly UI and workflow: Branded pages, admin UI, bundled skills, workflow seeds, and declarative product slices usually do not need a separate backend process.
- Go service-backed for handlers or ingest: Choose `service_backed` when the extension needs custom server-side handlers, public ingest, or compatibility-sensitive endpoints.
- Go service-backed for jobs or consumers: Choose `service_backed` when the extension needs scheduled jobs, domain event consumers, or richer background work.
- Go service-backed for owned schema: Choose `service_backed` when the extension needs an `ext_*` PostgreSQL schema, its own migrations, and a bounded data model.

## Agents should avoid the mistakes that made extension authoring feel fuzzy before.

The extension author route should now be explicit enough that these failure modes are unnecessary.

- Do not start from the core repo when the task is a private extension.
- Do not start from the SDK when there is no running instance or preview workspace yet.
- Do not invent privileged or instance-scoped capabilities into the generic public authoring path.
- Do not jump into `service_backed` just because it sounds more powerful.
- Do not describe an extension as ready until the lint, verify, nav, widgets, and skills loop is green.

## Related

- Build extensions overview: /build-extensions
- Detailed build guide: /docs/build-extensions
- Extension model: /docs/extensions
- Self-host guide: /docs/self-host