Splitting a root
llms.txtlists every page for an agent
Optional: hand this page to your coding agentThe steps work by hand too.Show the whole prompt
Read https://intentius.io/terragucci/concepts/splitting-a-root/.
Find the largest roots in this repo by resource count, from the estate's inventory (the `inventory` table of `terragucci query`, or `terragucci mcp`), and for each suggest where it could split by the boundaries on the page, naming the resources on each side and the reads the split would add.
Do not change anything and do not write a migration file.
Never apply, approve (a pull request review or `terragucci approve`), override a policy denial (`terragucci override`), use `--mode apply`, or merge; never touch `.chant/allowed_signers` or `chant/lifecycle`.Splitting is an ordinary reviewed change: a pull request with a plan, a digest and an approval. With choudoufu it moves no state at all.
Signs a root is too big
Section titled “Signs a root is too big”| Sign | Where it shows |
|---|---|
| its plan takes long | the Runs dashboard’s slowest roots and each run’s trace, with a span per root, and the plan’s bar on the run view’s timeline |
| it holds many resources | the estate page’s Resources section, and the inventory table of terragucci query |
| small changes reach far | the plan note’s blast radius by resource, which lists every resource a change reaches |
| many teams change it | the root’s own commit history: every change waits on one plan and one approval |
Boundaries
Section titled “Boundaries”| Boundary | Split when |
|---|---|
| environment | dev and prod share a root, so one approval covers both |
| lifecycle | long-lived resources, such as a network or a database, sit beside ones that change daily |
| team | two teams change the same root and wait on each other’s reviews |
| rate of change | a few resources change on most pull requests and the rest almost never |
Costs of a split
Section titled “Costs of a split”| Cost | Because |
|---|---|
| a read between roots | a value one side used directly becomes a terraform_remote_state read (or terraform_estate_outputs under choudoufu) of the other |
| a later wave | the reading root now applies after the one it reads (Waves) |
| a plan after the upstream applies | a change that moves an output the reader reads holds the reader’s wave for its own approval (Linked roots) |
Two ways to split
Section titled “Two ways to split”| Root | How | Proved by | Released by |
|---|---|---|---|
| a stock root, on OpenTofu or Terraform | a migration file in the pull request that moves the resources’ state, applied as a gated wave 1 before any root plans | every root it touches plans with no change against its new state | terragucci approve <name> from a checkout; a pull request review never counts |
| a choudoufu estate | a moves file: choudoufu rewrites each resource’s estate tags with live-mv, with no state file to cut |
live-mv -dry-run, which must find each resource in the estate it leaves |
the same approval of the migration’s digest |
A stock root becomes an estate first, by a backends file that adopts its state with live-import, and is split with moves after. Two estates can share one record store bucket, each under its own prefix. With apply.resume, the resume job applies a migration once it is approved. A repo that applies each wave in one job per identity runs no migrations. Move resources between roots has the steps.
terragucciHelp setting it up: Intentius
These docs count page views and clicks with PostHog. They set no cookies, store nothing in your browser, and send nothing when your browser asks not to be tracked.