OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Spec pack

Builder is a governed authoring control plane, not a frontier coding agent.

The implemented Builder stack sits across @contractspec/lib.builder-spec, @contractspec/lib.builder-runtime, @contractspec/lib.provider-spec, and the reusable workbench/mobile modules. It orchestrates inputs, provider routing, readiness, and export decisions on top of the OSS ContractSpec foundation and the Studio operating layer.

What Builder ownsfusion, routing, readiness, export

Builder delegates synthesis and coding to external execution providers. Its job is to keep those runs policy-aware, provenance-rich, and usable from both desktop and mobile operator surfaces.

Implemented stack and entrypoints

You can use the type surfaces directly in code, or start from the already wired workbench and mobile review routes in the public app shell.

builder-stack
Packages
- @contractspec/lib.builder-spec
- @contractspec/lib.builder-runtime
- @contractspec/lib.provider-spec
- @contractspec/module.builder-workbench
- @contractspec/module.mobile-review

Web app routes
- /operate/builder/workspaces/:workspaceId
- /operate/builder/workspaces/:workspaceId/mobile-review/:cardId

Operate API proxy
- /api/operate/builder/queries/builder.workspace.snapshot
- /api/operate/builder/commands/builder.blueprint.patch
- /api/operate/builder/commands/builder.export.execute

Managed

Best when the team wants the platform to own setup, routing, readiness, API defaults, and mobile-safe operator flows.

Local

Best for power users who want local-daemon registration, tenant-local execution providers, and tighter data-locality control.

Hybrid

Best when some work should stay local while preview, review, export, or mobile operator flows still use managed coordination.

Typical Builder loop

  1. Bootstrap managed, local-daemon, or hybrid presets explicitly instead of inventing provider posture ad hoc per host.
  2. Capture prompts, files, voice, and other inbound sources into a typed workspace instead of relying on a single chat transcript.
  3. Fuse the sources into decisions, assumptions, and blueprint updates with provenance and approval memory.
  4. Compile authoring work into execution lanes, then route the work to explicit provider profiles and runtime targets.
  5. Create previews, run readiness gates, and record receipts before export becomes an operator action.
  6. Keep mobile review parity so approvals, incidents, and patch proposals can be inspected away from the desktop workbench.

What Builder should not become

  • Not a competitor to specialized coding agents such as Codex or Claude Code.
  • Not a managed-only product that traps teams away from OSS-local runtime paths.
  • Not a hidden routing layer that obscures provider provenance, receipts, or runtime mode.
  • Not a desktop-only surface. Mobile review parity is part of the control-plane contract.

Workspace config carries the current Builder defaults

Builder setup is no longer just an app-shell concern. The shared workspace config now carries runtime mode, bootstrap preset, control plane API defaults, and local runtime registration metadata so the CLI, editors, and web shells resolve the same posture.

.contractsrc.json
{
  "builder": {
    "enabled": true,
    "runtimeMode": "local",
    "bootstrapPreset": "local_daemon_mvp",
    "api": {
      "baseUrl": "https://api.contractspec.io",
      "controlPlaneTokenEnvVar": "CONTROL_PLANE_API_TOKEN"
    },
    "localRuntime": {
      "runtimeId": "rt_local_daemon",
      "grantedTo": "local:operator",
      "providerIds": ["provider.codex", "provider.local.model"]
    }
  }
}

Operator posture stays visible

  • local trust and lease posture for registered local runtimes
  • channel-action and comparison posture data in the shared Builder snapshot
  • preview, readiness, export, and mobile-review state derived from the same workspace snapshot

Use the workbench UI as the host surface

The reusable module already exposes the desktop workbench shell. Your host app keeps control of action wiring, runtime mode selection, and approval flows.

BuilderWorkbenchHost.tsx
import { BuilderWorkbench, useBuilderWorkbenchState } from "@contractspec/module.builder-workbench";

const state = useBuilderWorkbenchState({
  workspace: initialSnapshot.workspace,
  initialSnapshot,
});

<BuilderWorkbench
  snapshot={state.snapshot}
  promptDraft={state.promptDraft}
  onPromptDraftChange={state.setPromptDraft}
  onCapturePrompt={capturePrompt}
  onGenerateBlueprint={generateBlueprint}
  onCompilePlan={compilePlan}
  onCreatePreview={createPreview}
  onRunReadiness={runReadiness}
  onExecuteExport={executeExport}
  selectedExportRuntimeMode="hybrid"
/>;

Read this with the Studio bridge in mind

Builder is where the OSS foundation meets the richer operating layer. Use the Studio overview when you want the higher-level product posture and team workflows on top of these contracts.

Studio overviewControl-plane runtime
OSS docscore-modelStudio is additive to OSS, not the source of truth.
Previous

ContractSpec Connect

Guard coding-agent edits and shell actions with task-scoped context, plan packets, patch verdicts, and review packets.

Next

Contract types

Choose the right contract surface for the behavior you want to make explicit.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

ManifestoContract-first APISpec-driven development