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.
Builder guide
Handle a specs pack with Connect-gated Builder apply.
Use
builder pack
when a zip or folder should become a governed execution input: analyze it, derive a task ledger, route Contract Steward work before code edits, and keep apply blocked until Connect evidence is complete.Import and analyze the pack
Start with a zip or folder and keep README, AGENTS, prompts, examples, fixtures, acceptance criteria, non-goals, ambiguity, and risk signals traceable to source refs.
Plan into a typed ledger
Builder turns requirements into a dynamic task ledger with run ids, task ids, dependencies, role assignments, write scopes, evidence refs, and verifier state.
Route Contract Steward work first
Contract create, update, delete, migrate, validate, and compatibility-classify tasks are modeled before generated or handwritten code tasks.
Apply only after Connect review
The apply surface is fail-closed until a typed Connect decision proves review verdict, scope/hash alignment, tests, replay refs, and no production-effect or broad-rewrite bypass.
Operator JSON flow
Import, analyze, and plan stay safe dry-run surfaces. The explicit mutating entrypoint is
builder pack apply
, and it still returns blocked JSON instead of writing when Connect, tests, replay, or verifier evidence is incomplete.contractspec builder pack import <zip-or-folder> --json
contractspec builder pack analyze <zip-or-folder> --json
contractspec builder pack plan <zip-or-folder> --dry-run --json
contractspec builder pack apply <zip-or-folder> --connect-decision <decision-id> --json
contractspec builder pack verify <pack-run-id> --json
contractspec builder pack report <pack-run-id> --json
contractspec builder pack replay <pack-run-id> --jsonEvidence gate
Connect decision id, verdict, verification status, touched scopes, plan/apply hashes, and timestamp.
Contract Steward action receipts before generated or handwritten implementation receipts.
Test output refs, replay bundle refs, verifier decisions, and alignment report refs.
Parallel-agent leases, dependencies, write scopes, outputs, aggregation status, and final signoff.
What stays blocked
The pack workflow is additive, but Builder must not treat a specs pack as permission to rewrite the repository. These cases remain blockers that require plan revision or fresh review evidence.
missing or denied Connect decisions
stale hashes or mismatched scopes
missing test output or replay refs
production-effect requests
broad repo rewrites submitted as one apply step
Validation checklist
Use the targeted package checks from the release capsule before claiming a specs-pack apply workflow is ready for operators.
bun run --cwd packages/libs/builder-spec test
bun run --cwd packages/libs/builder-spec lint:check
bun run --cwd packages/libs/builder-spec typecheck
bun run --cwd packages/libs/builder-runtime test
bun run --cwd packages/libs/builder-runtime lint:check
bun run --cwd packages/libs/builder-runtime typecheck
bun run --cwd packages/apps/cli-contractspec test src/commands/builder/pack.test.ts
bun run --cwd packages/apps/cli-contractspec lint:check
bun run --cwd packages/apps/cli-contractspec typecheckHost the Builder workbench
Load a Builder workspace snapshot, wire common commands, and keep runtime mode plus mobile review flows explicit.
Index Builder memory and routing
Use dry-run Builder Intelligence artifacts for secure indexing, hybrid retrieval, durable memory, trajectories, and SONA-lite routing proposals.
Why ContractSpec
Keep educational and comparison content reachable without letting it define the primary OSS learning path.