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 safeguards 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 only changes the content between the markers, so hand-written prose stays untouched; the refs block anchors which source files it 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. To keep the result reliable, a verification script ships with the skill: it scans the generated documentation, reports every deviation as a finding, and only once it runs clean does the update count as done. 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 only those - 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
What the code does not reveal, arc-steward does not invent; it marks the gap honestly as TODO(human) - the essential business flows, for instance, you have to name yourself. 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 keeps 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.