One thing has been bothering me about most work with code agents: every tool invents its own way of understanding a project. One reads an instructions file at the root, another expects implicit conventions, another simply loads everything into context and hopes. Each case looks like a detail. When the project grows — more modules, old decisions, directions that changed — that detail starts defining the quality of everything the agent produces.

That is where Prumo came from. Not as “yet another CLI”, but as a question: what if the repository were the durable source of truth, readable by humans and agents alike, without depending on the tool of the moment?

What I was trying to solve

I want any agent to enter a project and answer fast: what is the current goal, which decisions cannot be broken, what has been validated and by which evidence. Today that context lives scattered — some in people’s heads, some in loose docs, some in chat history nobody can find anymore.

Where the obvious solution starts to fail

The obvious path would be writing an ever-bigger AGENTS.md. It works up to a point, but it has a low ceiling: the more stuff goes into the file, the less the agent knows what matters for that specific task. We can have entire folders of ADRs, specs and roadmaps and still have the same problem, because nothing says which document has authority over which part.

The idea, then, is not more documentation. It is structured documentation: goals, decisions, contracts, tasks and evidence related to each other, versioned in Git, validated by schema.

What Prumo proposes

Simply put: canonical project state in Markdown, JSON and JSON Schema inside the repo itself — and everything else (caches, indexes, per-tool adapters) as derived. Goals have a lifecycle with verifiable integrity, plans are validated as DAGs, and adapters translate that state to each harness: Claude Code, Codex, OpenCode, Gemini and so on.

What draws me to this design is reversibility. If a new agent shows up tomorrow, nobody rewrites the project: you write an adapter. Content keeps belonging to the right places; the protocol only maintains the relationships.

What still worries me

Two honest gaps. First, a protocol without adoption is just a pretty specification — Prumo has to prove value in daily use, not in the diagram. Second, there is the risk of the system becoming a platform that tries to control too much detail. I do not want that: its job is keeping relationships, authority and provenance, not dictating how each tool works.

Current state

Today Prumo is a single Go binary with zero external runtime dependencies, plus conformance tests comparing behavior against baselines. I would rate this part 7/10: the foundation is good, but validation on real large projects and more adapters in daily use are still missing.

The next step that could confirm or overturn these choices is using the protocol on real projects for a few weeks and measuring: less agent rework? Fewer broken decisions? If yes, we have infrastructure. If not, we have a lesson. Both count. Code and docs in the repository.