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.

{
  "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

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.

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.

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

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

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

Index Builder memory and routing

Use dry-run Builder Intelligence artifacts for secure indexing, hybrid retrieval, durable memory, trajectories, and SONA-lite routing proposals.

Next

Adopt provider-backed knowledge

Ingest Gmail and Google Drive into governed knowledge spaces with persisted provider deltas and mutation gates.

Why ContractSpec

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

ManifestoContract-first APISpec-driven development