Archboard in a Home Repo
Keep one model of the whole system in your Home Repo, bind it to the code of every other repository, and see which parts of the system an agent changed across all of them.
On this page
A Home Repo is one repository that holds your skills, your AGENTS.md and your shared docs. You start every agent session there, and its AGENTS.md points to each of your other repositories. Matt Pocock describes the pattern in The Home Repo Pattern. The architecture of a system that spans those repositories is a shared doc too, so its vault goes in the Home Repo.
The layout#
~/repos/acme/├── home/ the Home Repo│ ├── AGENTS.md a pointer to each other repository│ └── .archboard/vault one model of the whole system├── storefront/├── payments-api/└── platform/The other repositories have no vault. A module in the model binds to a file or a directory in any repository, by the identity of the repository and a path, such as github.com/acme/storefront and src/checkout/. The identity comes from the origin remote of the checkout. The binding holds no absolute path, so it resolves on every machine.
Set it up#
-
Run
archboard initin the Home Repo. It installs the skills for your user, makes the vault and registers the checkout of the Home Repo.Terminal window cd ~/repos/acme/homearchboard init -
Register a checkout of each other repository on this machine. The code check and the browser read the code of a binding from that checkout.
Terminal window archboard repo add ~/repos/acme/storefrontarchboard repo add ~/repos/acme/payments-apiarchboard repo add ~/repos/acme/platformarchboard repo list -
Ask your agent to draw the first map in the Home Repo.
initcreates an empty model. Bind each module to its source in the other repositories. Use the repository identities fromarchboard repo list. -
Commit the vault in the Home Repo.
Terminal window git add .archboardgit commit -m "docs(architecture): add the Archboard vault"
Each machine that runs the check registers its own checkouts, because the registry belongs to the machine. Register a language server for each language in the repository that holds the code, as Install and set up shows.
Where the agent runs commands#
A model command run in the Home Repo finds the vault without -C. In another repository, model read refuses with VAULT_NOT_FOUND. If the Home Repo’s model binds that repository, the refusal names the Home Repo as the directory to give with -C:
archboard -C ~/repos/acme/home model readIn a checkout without a vault, archboard check skips the semantic and code checks. Pass -C to run them against the Home Repo.
See what an agent changed#
Git tells you which repositories have new commits. archboard model footprint tells you which modules those commits changed, in every repository that the model binds. Run it in the Home Repo:
archboard model footprint --base mainIt reads the commits between main and HEAD in the chosen checkout of each repository. It lists each module that the commits changed. Under unboundFiles, it lists each changed file that no module is bound to.
If the agent worked from a proposal, select the draft with --state. The answer then puts modules in three groups: planned and changed, changed outside the plan, and planned but unchanged. Review the modules changed outside the plan first. --fail-outside exits 1 for changed modules outside the plan. It ignores an outer directory module when changed modules inside it bind every changed file there. Unbound files never fail this gate.
The answer also lists each module that the draft adds although the commits add none of its code. --fail-preexisting exits 1 for these modules. Model their code in the current architecture first.
archboard model footprint --base main --state "Split payments" --fail-outsideIf the branch adopted its proposal, the proposal is the current state at the head. Without --state, the command then sets the current state against the current state at the merge base, so the three groups stay. The command does this when the two current states differ.
The command reads one checkout of each repository, the chosen checkout. archboard repo list shows which checkout that is. If an agent commits in a worktree, choose that worktree first with archboard repo use <dir>.
To read another branch, name it with --head. By default, the command reads the vault at that head if the Home Repo holds it. Then --state can name a proposal that exists only on that branch. If only a code repository holds the head, the command reads the vault on disk. With --checkpoint, it reads the saved state instead.
archboard model footprint --base main --head agent/split-payments --state "Split payments"The answer’s vaultRead records the model’s source. For the vault on disk, it holds { "at": "checkout" }. For a Git ref, it holds { "at": "ref", "ref": "<head>", "commit": "<commit>" }.
If you edited a proposal without a commit to the head, add --model-at checkout. The command then reads the model on disk.
In the browser#
Open Measures and choose What this branch changed. Choose the base, the head and the state to set the commits against. Each of the three menus is searchable, and you can type any ref. The view reads when it opens and when you press Refresh.
With a proposal, the view shows three cards: Planned and changed, Changed outside the plan and Planned, not changed yet. Without one, it shows one card, Changed. If the branch adopted its proposal, Against says Current, adopted on this branch, and the view shows the three cards. Select a module in a card to select it on its picture. The information key beside Refresh shows what the read covers.
Each card with modules has Show on picture at its foot. It opens the nearest shared parent of the card’s modules. If they share no parent, it opens the root reading. It selects each listed module that the picture draws, or the drawn module that holds it.
It uses the model that the footprint read, in the state that Against names. If the footprint read a Git ref, it opens a branch reading: the model at that ref’s commit. If only a code repository holds the head, it uses the model on disk. The state chip names a branch reading’s ref and commit. A branch reading is read-only, and its address survives a reload.
In CI#
The other repositories have no vault, so their own archboard check has no model to read. Run the check with the vault of the Home Repo, and register the checkout of the code beside it. In the CI of a repository such as the storefront, check out both and list the code in the check Action’s repos input:
jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: path: storefront - uses: actions/checkout@v5 with: repository: acme/home path: home token: ${{ secrets.HOME_REPO_TOKEN }} - uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0 with: version: "0.5.0" working-directory: home repos: | storefrontInstall the dependencies and the language servers of the storefront before the check, as The check as a gate shows. Without a language server, a call that needs resolved evidence stays information, and the check passes. A private Home Repo needs a token with read access, as the second checkout shows. A binding into a repository that the run does not register is skipped as repository-unregistered. A skip never fails the check. To check the whole system in the CI of the Home Repo, check out every repository and list each one under repos.
When the vault stays in its repository#
A Home Repo puts the change to the model and the change to the code in different pull requests. If one repository holds most of the system, keep the vault in that repository. A reviewer then reads both changes in one diff, and that model can still bind into the other repositories, as Application and infrastructure shows.