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

ContractSpec Connect puts coding-agent actions behind explicit, local-first governance.

Connect is the adapter layer between agent-native actions and the existing ContractSpec stack. It reuses control-plane, ACP, workspace, knowledge, and harness primitives to explain what the agent is trying to do before a file edit or shell command lands.

Authoritative surfacescontrol plane, ACP, workspace, harness

Connect stays narrow on purpose. It projects local evidence, maps its verdicts back to runtime semantics, and leaves the canonical system contracts where they already live.

What you use in practice

The CLI and the workspace service already implement the pack. The main workflow is local initialization, task projection, verification, then optional review sync.

contractspec-connect
contractspec connect init --scope workspace
contractspec connect adoption sync --json
printf '{"goal":"Prefer an existing release helper before adding a new one"}' | contractspec connect adoption resolve --family sharedLibs --stdin --json
contractspec connect context --task refactor-docs --paths packages/libs/contracts-spec/src/control-plane/contracts.ts --json
printf '{"objective":"Document the control-plane contract surface","commands":["bun run typecheck"]}' | contractspec connect plan --task refactor-docs --stdin --json
printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | contractspec connect verify --task refactor-docs --tool acp.fs.access --stdin --json
printf 'bun run typecheck' | contractspec connect verify --task refactor-docs --tool acp.terminal.exec --stdin --json
contractspec connect review list --json
contractspec connect replay <decisionId> --json

The four core artifacts

Every Connect command is there to emit or inspect one of these reviewable objects under `.contractspec/connect/*`.

ContextPack

Projects the current repo state, impacted contracts, canon packs, policy bindings, and acceptance checks into one task-scoped envelope.

PlanPacket

Compiles a candidate objective into ACP-aware steps plus explicit refs back to control-plane intent, plan compile, and plan verify contracts.

PatchVerdict

Classifies one file edit or shell command as permit, rewrite, require_review, or deny, with runtime-linked control-plane state when available.

ReviewPacket

Persists the evidence a human needs when Connect escalates, while keeping the local artifact trail authoritative in OSS mode.

Reuse-first adoption is part of the workflow

Connect adoption keeps reuse guidance in the same local control surface. Before a new contract family, helper, or runtime abstraction lands, Connect can mirror the bundled catalog and resolve the best reuse candidate by family.

  • `.contractspec/adoption/catalog.json` mirrored from the bundled ContractSpec catalog
  • family-aware reuse recommendations for `ui`, `contracts`, `integrations`, `runtime`, `sharedLibs`, and `solutions`
  • verdict thresholds that can prefer workspace reuse, ContractSpec reuse, review, or explicit denial before a new implementation starts

Adopt Connect in this order

  1. Enable `connect` in `.contractsrc.json` and keep your protected, immutable, generated, and smoke-check policies explicit.
  2. Run `contractspec connect context` and `contractspec connect plan` before risky work so the agent is operating on task-scoped evidence, not ambient repo assumptions.
  3. Gate file and shell mutations through `contractspec connect verify` or the host hook commands instead of inventing editor-specific approval logic.
  4. Inspect pending review packets locally first, then sync them to the Studio bridge only if your team wants centralized operator workflows.
  5. Use replay and harness evaluation to prove whether a prior decision stayed safe when the workspace changed.

Boundaries that keep it trustworthy

  • Connect is not a second control plane or a second package family.
  • Verdicts are projections over existing `controlPlane.*`, ACP, workspace, and harness primitives.
  • Studio is optional for baseline enforcement. Local artifacts remain the OSS source of truth.
  • Destructive commands, protected paths, drift, and unknown impact stay visible instead of being hidden behind adapter magic.

Where Connect fits in the rest of the docs

Read the control-plane runtime page when you want the underlying governance contracts, then use the Studio bridge only if your team wants centralized review queues on top of the OSS-local evidence path.

Control-plane runtimeStudio bridge
OSS docscore-modelStart with OSS. Adopt Studio when you want the operating layer.
Previous

Module bundles

Define AI-native surfaces as typed bundle specs that resolve into personalized, auditable runtime plans.

Next

Builder control plane

Route multimodal authoring work through governed builder contracts, provider policies, readiness gates, and mobile review flows.

Why ContractSpec

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

ManifestoContract-first APISpec-driven development