Repo-Local Documentation System for Humans & Agents

Excellent questions.

1. The workflow is to copy the appropriate template from the docs/templates directory into its destination, such as copying system.md into the docs/systems directory for a new system. Fill in what you already know, then have the AI complete or refine the rest. If you prefer, you can skip the manual setup entirely and ask the AI to generate the document directly from the appropriate template.
2. The best way to prevent stale documentation is to require documentation updates in every PR that changes behavior. If a PR modifies the billing system, the billing documentation should change in the same review. Reviewers and review agents can then verify that the code and documentation remain consistent.
3. For planning new features or refactors, the knowledge base gives both humans and agents a reliable, high-level understanding of the system without having to reconstruct it from source code. It's much easier for an agent to reason across a few thousand lines of structured documentation than tens of thousands of lines of source code, especially when analyzing changes that span multiple systems. This could make it more effective for planning large changes or refactors.

1. I'm starting to integrate this into production projects at work today, so I don't have any long-running production codebases using it yet. I do plan to introduce it into a large six-year-old monorepo, but that will require a coordinated team effort.
2. The documentation should consistently reinforce that code changes require corresponding documentation updates. This has worked surprisingly well in practice. In the projects I've tested, agents almost always update the code and documentation together. Review agents can also use the documentation as additional evidence, for example by flagging inconsistencies such as, "Why do the docs say one thing while the code does another?"