Architecture docs without drift: arc-steward
AI writes code faster than a human can follow. Good architecture documentation helps you keep a grip on the system as a whole, even as it changes - but only while it stays correct. And keeping it current was a real challenge for teams long before AI agents: stale documentation typically gets noticed far too late. At some point the diagram describes a system that no longer exists, and nobody trusts it enough to even open it. AI speed only makes that worse.
That is why I released arc-steward.
What is arc-steward?
arc-steward is an agent skill you embed in your own agentic workflow. It creates architecture documentation and keeps it current with every code change - at its core, that is instructions a coding agent follows plus a small verification script that checks consistency.
The documentation follows no free-form style but a fixed canon - and which one is your choice, per repository: arc42 or Simon Brown's Software Guidebook. Both are established structures that prescribe fixed chapters - context, building blocks, runtime views, decisions - so you don't reinvent what belongs where in every project. Those very chapters are what arc-steward maintains.
In action
As an example, I had arc-steward document itself - here is its own context diagram, exactly as the skill generated it:
In the repository, this diagram sits inside a marked block. A refresh is instructed to change only the content between the markers and to leave hand-written prose outside them alone; the refs block anchors which source files the diagram comes from:
<!-- arc-steward:generated:context -->
… context diagram …
<!-- arc-steward:refs
SKILL.md · conventions.md · scripts/verify.py
-->
<!-- /arc-steward:generated -->
Which code change affects which diagram is held in a routing table: a change to a path triggers exactly the update of the artifacts assigned to it. A verification script also ships with the skill: it checks what can be checked mechanically - markers, diagram structure, references to code and schema, links - reports violations as findings, and only once it runs clean does the update count as done. Whether the content is right, it cannot tell. In the pull request, a reviewer finally sees the updated diagrams right in the diff, next to the code that triggered them.
Usage in your own workflow
arc-steward works in two modes, and which one applies depends solely on whether the repository already holds documentation.
No docs yet: bootstrapping
If the architecture documentation is missing entirely, arc-steward creates it for the first time in bootstrapping. This is a deliberate, one-off step - and one where the human has a say: arc-steward reads the repository's structure, detects the documentation language and any schema sources, derives a routing table from the actual directory layout, and has you confirm the essential business flows rather than inventing them. Only once the standard - arc42 or Guidebook - and the chapter selection are settled does it write the canon: the entry page, every selected chapter, and, wherever the code gives no answer, an honest TODO(human). Because this run touches the whole repository and asks questions, you start it deliberately - not on the side during some unrelated task whose scope it would otherwise blow up.
The docs exist: refresh
Once the canon is in place, the refresh takes over. In this mode arc-steward determines the diff of the current feature, maps the changed paths through the routing table to the affected artifacts, and updates those specifically - surgically and small. If a change touches nothing documented, it says so and stays idle. Precisely because such a run is so small, it fits into the same pull request as the feature. In my own development workflow the refresh is therefore a fixed step before every pull request, so the updated diagrams land next to the code that triggered them. The skill itself provides the trigger: its description tells the agent when to step in.
Limits
The documentation is written by an AI agent. It can differ from run to run and can simply be wrong. arc-steward is instructed not to invent what the code does not reveal and to mark the gap as TODO(human) instead - the essential business flows, for instance, you have to name yourself. That only the marked blocks get touched is likewise an instruction to the agent, not a technical guarantee - the verification script checks the markers, not the prose around them. So review the diff before committing; the notes on safe use in the repository go into more detail. If a diff touches nothing documented, the tool deliberately stays idle and only runs when there is actually something to do. And it does not replace review: it helps keep the documentation current, but whether it says the right thing is still your call.
Try it
arc-steward is open source: github.com/robertfoobar/arc-steward. Try it on a feature branch and see what the diagram got wrong. I welcome feedback and issues.