Use `/agents` for product evaluation
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.
Extension developers
Build your own extensions with your favourite AI coding assistant.
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.
Table of contents
Section map.
Jump directly to the part you need.
Use this page when the task is extension authoring, not general product evaluation.
When to use this route
Agents should follow a short extension-author route and stop inventing missing steps.
Agent reading order
Stay inside the supported generic self-built slice unless there is a strong reason not to.
Supported self-built slice
The first version should prove itself through one repeatable command loop.
Default proof loop
Move to `service_backed` only when the product requirement proves it.
Service-backed branch
Agents should avoid the mistakes that made extension authoring feel fuzzy before.
Common failure modes
When to use this route
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 `/docs/self-host` when no runtime exists yet
If there is no running instance or preview workspace, do not start from the SDK. Create the owned runtime first.
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
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.
Agent reading order
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`
Use the detailed build guide for the full lifecycle, review gates, and command loop.
3. Open the extension SDK handoff
Use `README.md` and `START_HERE.md` in the public SDK as the concrete scaffold and local workflow.
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.
4. Open `SERVICE_BACKED.md` only when needed
Branch into service-backed runtime design only when the extension truly needs handlers, jobs, event consumers, or an owned schema.
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.
5. Return to `/docs/extensions` for runtime boundaries
Use the extension model reference when runtime class, endpoint class, storage class, or trust boundaries are in question.
Supported self-built slice
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 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.
- 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.
Default proof loop
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 bundle
- 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.
- 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.
$ 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 --jsonService-backed branch
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 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.
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.
Common failure modes
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.
References
Canonical next surfaces.
Each link goes to the next authoritative page, reference, or support surface.
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.