Stability

What semver covers from v1.0 โ€” and what deliberately tracks upstream instead. Edit on GitHub

Stability contract

Status: binding as of v1.0.0. This document is the semver contract โ€” breaking any covered item requires a major release. Groot v2 is that major: its deliberate changes are listed under Version 2; v2-only surfaces become covered when 2.0.0 leaves the next prerelease channel.

groot's promise is narrow on purpose: the interface is stable; the output workspaces track living upstream generators by design. This page defines exactly where that line sits.

Covered by semver

SurfaceWhere it's specified
The command set: init, add, doctor โ€” plus the bun-create bare-destination routing (bun create groot my-app โ†’ init)cli-spec.md
Every documented flag: name, value domain, default, and semantics (including aliases like -y)cli-spec flag tables
Exit codes: 0 ok ยท 1 internal ยท 2 usage ยท 3 preflight ยท 4 generator ยท 5 stitch/verify/doctor-problems ยท 130 cancelledcli-spec.md#exit-codes
The groot.json schema โ€” version: 1 (frozen: groot.v1.schema.json) and version: 2 (the blueprint) โ€” and its published $schema URL, which accepts bothschemas/groot.schema.json
--json output shapes: init/add dry runs emit the manifest schema on pure stdout; doctor --json emits { healthy, workspaceRoot, checks[] } with checks[] entries shaped { name, status: pass|warn|fail, detail, fix? }cli-spec output contracts
The non-interactive contract (never prompt without a TTY; stdout purity in --json; plain line-based progress; interactive steps deferred, never run)cli-spec.md#non-interactive-contract-ci--agents
Bin names groot and create-groot; install.sh / install.ps1 entry points and their checksum-verification behaviorpackage.json bin, installers

Explicitly NOT covered

Change rules

Manifest schema evolution

Enforcement

packages/cli/src/contract.test.ts snapshots the covered surface โ€” the flag set of every command, aliases, exit codes, the bun-create routing table, and the schema's invariants (version const, required fields, slot/framework enums cross-checked against the live scaffold matrix). Any PR that touches the surface fails CI until the snapshot is updated in the same PR, which is the reviewer's cue to check this contract's change rules before merging.

Version 2 (deliberate changes)

v2 keeps the v1 command set, flags, exit codes, and stdout/stderr routing. These changes are deliberate and only ship in a major release:

ChangeBefore (v1)After (v2)Rollback limit
groot.json written by initversion: 1 manifestversion: 2 blueprint โ€” a strict superset (createdWith, conventions, scaffolds keep their v1 meaning)v1 CLIs reject version 2 files; pin create-groot@1 to keep writing v1
init --dry-run --json and add --dry-run --json on fresh/v2 workspacesv1 manifestv2 blueprintconsumers of the v1 fields keep working; version checks must accept 2
groot.json reading (add, doctor, --preset)version 1 onlyversions 1 and 2; add writes back the version it foundโ€”
groot add dev-port collision in a v2 workspacewarning; the new scaffold keeps the colliding default portthe new scaffold gets the next free port, applied to its dev script or source and recorded in groot.json (v1 workspaces and Metro/Tauri keep the warning โ€” architecture.md#port-allocation)change the port back by hand; groot doctor then flags the collision as in v1
Reserved bare words for bun create groot <word>init, add, doctoralso the v2 command names (see v2-cli-spec.md)use groot init <dir> for such directory names
Compiled binariesload .env/bunfig.toml from the working directorynever do (security fix); child process trees are swept on exitโ€”
init --name "" (empty or blank)dry runs exited 0; real runs crashed after generatingusage error up front (exit 2)pass a non-empty name

Additive in v2 (minor-compatible): init --topology single, new doctor checks (workspace layout, blueprint apps), and the v2 commands.

Newly covered once 2.0.0 is stable (normative in v2-cli-spec.md):

Not covered in v2: recipe-generated file contents (recipes are versioned and certified separately), evidence summary/details wording, managed-region text, MCP tool descriptions and instructions text.