GitHub

The check as a gate

Run archboard check where you already run tsc, ruff and your tests. It fails while the map and the code disagree, in a Git hook, in CI and in an agent's loop.

On this page

A rule in AGENTS.md is a request. An agent can ignore it. A check that fails the build is a fact that the agent must deal with. archboard check is deterministic: the same model and the same code give the same answer, with an exit code that CI understands.

A terminal in the relay example. archboard check passes with exit 0. npm run gate:break makes Intake read BILLING_URL and call Billing. archboard check then fails with exit 1 and a RELATIONSHIP_UNDRAWN warning, with evidence in services/intake/src/accept.ts line 51 and deploy/kubernetes/peer-endpoints.yaml line 13. npm run gate:restore, and the check passes again.

The relay example: the check passes, fails on a call that the model does not draw, and passes again. A real recording of the published CLI.

What passes and what fails#

archboard check runs three checks in order: semantics, code, then embeds. It exits 1 while one of them has something that you must fix.

OutcomeExitExample
Nothing to report0A model that matches its code
Information only0A relationship whose evidence is a candidate, matched by name only
A code warning1RELATIONSHIP_UNDRAWN: code calls a module that the model does not join
A semantic diagnostic1RELATIONSHIP_ON_CONTAINER: a line that ends on a module with parts
An outdated picture1EMBED_OUTDATED: a tracked SVG that no longer matches the model
No vault in the checkout0, or 1 when an embed warnsOnly the embeds check runs, and a skip says that the others did not
A usage error, or no checkout2Outside any Git checkout, with no vault above it
No server3The server did not answer and could not start

Information and skips print on standard error and never change the exit status. Check findings lists every code. Each check also runs alone:

Terminal window
archboard check semantics
archboard check code
archboard check embeds

Read a failure#

A warning of the code check names its code, the file of the module in the vault, the module and what to do. Each piece of evidence follows on its own line, with its kind, whether it is resolved, and its file and line:

stderr
warning: RELATIONSHIP_UNDRAWN: ZvzEpjXR.module.json: module "Rate card": The code of "Accept parcel" reaches "Rate card". No relationship joins these modules. Add the relationship between the parts that make and answer the call. If this dependency is unintended, change the code.
configured-path, resolved, services/intake/src/accept.ts:51
configured-path, resolved, deploy/kubernetes/peer-endpoints.yaml:13

There are two fixes, and the finding says both. If the call is intended, the agent draws the relationship. If it is not, the agent changes the code. Either way the next check passes. The JSON answer on standard output carries the same findings for a script.

In a Git hook#

A pre-push hook keeps a failing map off the remote. Save this as .githooks/pre-push and make it executable:

.githooks/pre-push
#!/bin/sh
# Block the push while the architecture check fails.
# Skip it once with: git push --no-verify
archboard check > /dev/null

Point Git at the directory once per clone:

Terminal window
chmod +x .githooks/pre-push
git config core.hooksPath .githooks

In a Node.js repository, pin the CLI as a dev dependency and let npm install set the hook path for every clone:

package.json
{
"scripts": {
"prepare": "test -e .git && git config core.hooksPath .githooks || true"
},
"devDependencies": {
"archboard": "0.5.0"
}
}

For this setup, replace archboard check in .githooks/pre-push with ./node_modules/.bin/archboard check. The hook then runs the pinned program, the same one that CI runs. A pre-commit hook works the same way, but a full check on every commit is slow on a large repository. Push is the better moment.

In CI#

The check Action installs the CLI, runs archboard check, and turns each finding into an annotation on the pull request’s diff. It fails the job on a warning or a diagnostic:

.github/workflows/architecture.yml
name: architecture
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
# The checkout's own TypeScript is the default TypeScript server.
- run: npm ci
# A server for each other language in .archboard/language-servers.json.
- run: pip install pyright
- uses: miklschmidt/archboard/actions/check@30d365ca9caab6dad98f45568a50a890c9f105f9 # v0.5.0
with:
version: "0.5.0"

The code check resolves a name only through a language server, and only resolved evidence makes a warning. So install the dependencies first. npm ci installs the checkout’s own TypeScript, which serves from version 7. Before 7, the check also needs typescript-language-server in the dev dependencies. Install the server of each other language that .archboard/language-servers.json names, as pip install pyright does for Python. Without a server, a call that needs resolved evidence stays information, and the gate passes.

Pin version to the release that your team runs, as you pin your compiler. Without it, the Action installs the CLI of the release that it comes from. The examples pin the Action to the commit of v0.5.0, with the tag in a comment. A tag can move, and a commit cannot, so pin any third-party Action this way. The Actions reference lists every input: fail-on: never reports findings without failing, though a checkout without a vault still fails, and allow-codes keeps chosen findings visible without failing on them.

Any other CI runs the same command. The exit code is the gate:

.gitlab-ci.yml
architecture:
image: node:22
script:
- npm ci
- npm install --global archboard@0.5.0
- archboard check > check.json
artifacts:
when: always
paths: [check.json]

In an agent’s loop#

Give the check’s words back to the agent before a person reviews the work. The agent then fixes the map or the code while it still holds the context. Three ways work today.

Claude Code: a hook when it stops#

A Stop hook runs when Claude Code wants to finish. When the hook ends with status 2, Claude Code gives the hook’s standard error back to Claude, and Claude goes on working:

.claude/settings.json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "archboard check > /dev/null 2> /tmp/archboard-check.log || { cat /tmp/archboard-check.log >&2; exit 2; }"
}
]
}
]
}
}

Any agent: a loop in the shell#

Run the agent, run the check, and give the findings back until the check passes or the rounds run out:

agent-loop.sh
#!/usr/bin/env bash
# Ask the agent for a change, then hold it to the architecture check.
set -u
task="$1"
codex exec "$task"
for round in 0 1 2 3; do
if archboard check > /dev/null 2> check.log; then
echo "archboard check passed after round $round"
exit 0
fi
if [ "$round" -eq 3 ]; then
break
fi
codex exec "archboard check failed. Fix the code or the Archboard model so that it passes. Do not hide a finding. The findings:
$(cat check.log)"
done
echo "archboard check still fails after 3 rounds" >&2
exit 1

In the instructions of the repository#

Tell the agent where the gate is, so it runs the check before it says it is done:

AGENTS.md
Run `archboard check` before you finish. It fails while the architecture model and the code
disagree. Fix the code or the model. Never silence a finding.

An instruction alone is a request, so keep the hook or the loop as the gate.

Keep the pictures current#

Pictures in your README and ADRs are embeds: SVG or PNG files that Archboard drew and Git tracks. The embeds check fails when one no longer matches the model. Draw them again and commit them:

Terminal window
archboard check embeds --fix
git add docs/architecture

Next#

Docs

Type to search every page, command and schema.