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

Use Connect in a repo

Put coding-agent edits and shell commands behind task-scoped context, plan compilation, verification, and local review evidence without introducing a second control plane.

What you'll build

  • A workspace-level Connect config in `.contractsrc.json`.
  • A reuse-first adoption check before new implementation work.
  • A context and plan flow for one task.
  • Verified file and shell mutations with local review/replay evidence.

1) Enable Connect

Start by making the safety policy explicit. Protected paths, generated paths, review thresholds, and command rules live in the workspace config, not in editor-specific hooks.

.contractsrc.json
{
  "connect": {
    "enabled": true,
    "storage": {
      "root": ".contractspec/connect",
      "contextPack": ".contractspec/connect/context-pack.json",
      "planPacket": ".contractspec/connect/plan-packet.json",
      "patchVerdict": ".contractspec/connect/patch-verdict.json",
      "auditFile": ".contractspec/connect/audit.ndjson",
      "reviewPacketsDir": ".contractspec/connect/review-packets"
    },
    "policy": {
      "protectedPaths": ["packages/libs/contracts-spec/**"],
      "generatedPaths": ["generated/**"],
      "smokeChecks": ["bun run typecheck"],
      "reviewThresholds": {
        "protectedPathWrite": "require_review",
        "breakingChange": "require_review",
        "destructiveCommand": "deny"
      }
    },
    "commands": {
      "allow": ["bun run typecheck"],
      "review": ["git push"],
      "deny": ["git reset --hard", "git push --force", "rm -rf"]
    },
    "adoption": {
      "enabled": true,
      "catalog": {
        "indexPath": ".contractspec/adoption/catalog.json",
        "overrideManifestPath": ".contractspec/adoption/overrides.json"
      },
      "workspaceScan": {
        "include": ["packages/**", "docs/**"],
        "exclude": ["generated/**", "dist/**"]
      },
      "families": {
        "contracts": true,
        "runtime": true,
        "sharedLibs": true
      },
      "thresholds": {
        "workspaceReuse": "permit",
        "contractspecReuse": "permit",
        "ambiguous": "require_review",
        "newImplementation": "require_review"
      }
    }
  }
}

Expected output: Connect has enough policy to classify writes, commands, drift, and review thresholds deterministically.

2) Initialize storage

connect-init
contractspec connect init --scope workspace

Expected output: `.contractsrc.json` is updated if needed and `.contractspec/connect/` is created.

3) Mirror the adoption catalog and resolve reuse first

Connect adoption is the reuse-first layer for authoring. Mirror the local catalog, then resolve the best existing surface for the family you are about to touch before you scaffold or invent anything new.

connect-adoption
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

Expected output: a mirrored local adoption catalog plus a reuse recommendation that can point to an existing workspace package or a ContractSpec surface before the task reaches file mutation.

4) Project context and compile a plan

Use the task id as the thread that connects context, plan, verdict, and replay artifacts.

connect-plan
contractspec connect context \
  --task docs-connect \
  --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 docs-connect --stdin --json

Expected output: a `ContextPack` and `PlanPacket` that point back to `controlPlane.intent.submit`, `controlPlane.plan.compile`, and `controlPlane.plan.verify`.

5) Verify file and shell mutations

connect-verify
printf '{"operation":"edit","path":"packages/libs/contracts-spec/src/control-plane/contracts.ts"}' | \
  contractspec connect verify --task docs-connect --tool acp.fs.access --stdin --json

printf 'bun run typecheck' | \
  contractspec connect verify --task docs-connect --tool acp.terminal.exec --stdin --json

Expected output: a `PatchVerdict` with `permit`, `rewrite`, `require_review`, or `deny`, plus a runtime-linked control-plane state when that linkage is available.

Artifacts to inspect

  • .contractspec/connect/context-pack.json
  • .contractspec/connect/plan-packet.json
  • .contractspec/connect/patch-verdict.json
  • .contractspec/connect/audit.ndjson
  • .contractspec/connect/decisions/<decisionId>/
  • .contractspec/adoption/catalog.json
  • .contractspec/adoption/overrides.json

6) Review, replay, and optional Studio sync

connect-review-replay
contractspec connect review list --json
contractspec connect replay <decisionId> --json
contractspec connect eval <decisionId> --registry ./harness-registry.ts --scenario connect.safe-refactor --json

# Optional when Studio review-bridge mode is enabled
contractspec connect review sync --decision <decisionId> --json

Local review packets remain authoritative. Studio sync is an operator convenience layer, not a requirement for baseline OSS safety.

Back to Connect spec Control-plane runtime
OSS docsbuildStart with OSS. Adopt Studio when you want the operating layer.
Previous

Host the Builder workbench

Load a Builder workspace snapshot, wire common commands, and keep runtime mode plus mobile review flows explicit.

Next

Libraries overview

Navigate the core libraries, runtimes, and system packages that make up the open foundation.

Why ContractSpec

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

ManifestoContract-first APISpec-driven development