Is there a recommended way to construct .md files for such a system? For instance when I make them for human consumption they'd have lots of markup for readability but that may or may not be consumable by an llm. Can you create a .md the same as for human consumption that doesn't hinder an llm?
claude doesn't read them reliably and has to be reminded across sessions. I ususally do @AGENT.main and @AGENT.knowledge and it figures out the rest. Over the period of doing this claude is able to maintain the "project management" part itself, as in terms of "whats the current state of the project" and "what are the next ideal todos and how to go about them".
> Can you provide any form of demonstration of an LLM reading these files and acting accordingly
claude does update them at the end of the session (i say wrap up on prompt). the ones you are seeing in that gist are original forms, they evolve with each commit.
Just writing a clear document, like you would for a person, gets you 95% of the way there. There are little tweaks you can do, but they don't matter as much as just being concise and factual, and structuring the document clearly. You just don't want the documentation to get too long.
I've had very good experience with building a very architecture-conscious folder structure and putting AGENTS.md in every folder (and, of course, instruction to read _and_ update those in the root prompt). But with Agent-written docs I also have to run doc maintainer agent pretty often.
