Crypts and Commits - Boss Edition — The Braindonor Network

I was standing up a demo for the first API service on a new platform, and I wanted the environment to stay warm. Nothing exotic. Set a minimum instance count on the service so the first request of the demo isn't sitting through a cold start. One service, one setting, move on.

The agent didn't want to move on. It suggested making minimum instances a shared platform variable instead.

My first reaction was the one you'd expect: I asked you for one setting. But its reasoning wasn't about the service in front of us. It was about the ten-plus services coming after it — including Gemini Agent Runtime agents making long agent-to-agent calls. Warming that demo was never going to mean warming one service. It was going to mean warming all of them, and a per-service setting is exactly the kind of thing you forget on service number seven, five minutes before the demo starts.

It knew to look because the campaign we were working in effectively said, "We are implementing item 8 from docs/roadmap.md." So it read the rest of the list.

With one or two services, that suggestion is a nice-to-have. With ten, it was the right call. And it was the right call for one reason: the agent knew where we were going.

The roadmap wasn't for me

I've written before about how the documentation in my repositories isn't really for me anymore. The roadmap turned out to be the same story — I just took longer to notice it.

For a while now I've kept a roadmap in the repository, usually at docs/roadmap.md, on four different projects. They start with somewhere between three and twenty milestones. The early ones tend to be module skeletons. The later ones are deliverable features. It's effectively become a hybrid between spec-driven development and agile development: the long-range goal of the project is written down well ahead of the current work, and I'm perfectly willing to reorder it, or bolt on new milestones, whenever reality has an opinion.

I need to be careful with the word "roadmap," though, because it drags a lot of baggage in with it. I'm not talking about quarterly planning or a slide that gets shown to executives. The biggest one I've kept had more than twenty milestones, and it covered a three-week greenfield proof of concept on a tight timeline. Those milestones weren't months apart. They were concrete delivery checkpoints, sometimes days apart. At that pace, two weeks out is the long range.

So: not a plan. Not a promise. Context. Context the agent can reason over, the same way it reasons over the code.

The Terraform variable is the example I like to lead with, but it isn't the only kind of judgment I've watched an agent make with a roadmap in view.

On a personal project I was building a view engine. The roadmap had three concrete view types, each in its own milestone, followed by a milestone for a formal state machine to manage them. When we started on the first view, the agent noticed that a debug harness already launched and monitored views — which meant the first milestone didn't need to solve what happens after a view completes. That problem already had a home further down the list. So instead of building the state machine early, it recommended splitting up the first unit of work and updating a future milestone.

That's a different skill from the Terraform case. One was knowing what to share. This one was knowing what not to build yet. Honestly? That's the one that impressed me more.

The third is about order. On a project built on Gemini Enterprise Agent Platform, we learned the hard way that Agent Registry's IAM governs access to the registry, not to the individual entries in it. Our initial reading had suggested users would only see the entries they had access to. They wouldn't. Our application needed to filter MCP servers for different users, so we needed a formal grant mechanism in the application itself, and that became a new roadmap entry. It had to land before we built any more MCP servers — but it didn't have to be the very next campaign. Seeing the whole roadmap is what made that dependency obvious, instead of something we'd trip over three servers later.

Those two work examples come from Revel Labs, where we use Chi-Town — the closed-source sibling to Crypts and Commits that shares the broad ideas but none of the code. Both frameworks have lived with roadmap documents, and at work the practice is getting tested by several developers moving fast, not just by me poking at my own projects at night.

Here's the point, as plainly as I can put it: an agent can only weigh a future it can see.

What I can actually claim

In the Terraform and view-engine cases, the agent cited the roadmap and told me it would have chosen differently without it. That's what it said. I don't treat an agent explaining its own reasoning as proof of anything — I wouldn't take that from a person, either. What I find more convincing is what it actually did, and how well those decisions held up against the milestones that came after.

Beyond that, I've got feel and anecdata. It feels like I get better output when I work this way. Some of my coworkers have been surprised at how much output I produce without completely depleting my usage quotas. That's the evidence. That's all of it.

Do I have raw evidence? No. But I'd also point out that nobody really does — I don't know of anyone who's figured out how to truly measure AI-assisted output yet. I'm not going to pretend I'm the exception. If anything, I'd be suspicious of the person who claims they've got it nailed down.

I still think it's worth writing down. "This seems to work, here's why I think so, and here's what I don't know" is more useful than silence — as long as it's labeled that way.

When the map is wrong

More future context isn't automatically better. I've got a story where it made things worse, and the problem wasn't the agent.

On that same large work project, the roadmap listed every MCP server "flavor" as needing two versions: read-only and read-write. The agent did the reasonable thing with that. Every flavor was going to need a read side, so it started pulling the read side into common code.

Then reality hit. We didn't need separate versions of each MCP server.

The cleanup meant refactoring multiple modules to delete "common" code that had exactly one consumer. Which, if we're being honest, isn't common code.

I've written before about the developer who sets out to build a single dining room chair and ends up with a fully automated furniture factory. This time I didn't build the factory myself. I handed the agent the blueprints for one and it did exactly what blueprints are for.

That was a pure case of YAGNI, and it was a failure of the human who put an unnecessary item on the roadmap — not a failure of the AI. That's the uncomfortable flip side of this whole approach. If the agent really does weigh the future you give it, then whoever writes the roadmap is steering everyone's agent, including when they're wrong.

I don't have a clever fix for that. The best I have is the same answer I give for most technical decisions: strong opinions, loosely held. Three entries in that twenty-plus milestone roadmap went stale as we learned more, and we deleted them. A wrong roadmap isn't wasted — fixing it is how the team writes down what it learned.

But that only works if changing the roadmap is cheap. And that's where my single file started to fall apart.

A linear document just isn't sustainable

Here's the thing that actually pushed me to build this. I was spending a significant amount of time crafting and maintaining these roadmaps. The roadmaps were paying for themselves — but the maintenance was real, and it kept growing.

The problem is that a roadmap has to follow two rules that fight each other. Completed milestones should be read-only, because they're history: they describe what we actually set out to do. Future milestones need to stay flexible, because they're guesses. One Markdown file has to do both, and it isn't good at either.

The friction showed up the way you'd expect:

The file grows, and the agent has a harder time pulling out just the section it needs.
More than one developer editing the same file means merge conflicts.
I reorder and insert milestones constantly. That's the whole point of holding the opinions loosely.
I had to put instructions into AGENTS.md and CLAUDE.md telling the agent how to change the roadmap, and I still found myself walking it through the same mutations every time we hit a milestone.

My rule of thumb for when a single file has been outgrown is somewhere around 30,000 characters, or the first merge conflict. I should be upfront about where that number came from: the agents gave it to me, while we were working around the output limits of the MCP protocol. I didn't measure it. That's real friction, though, and it's exactly the kind of friction I've been trying to engineer around.

And the fix? About as unglamorous as it gets. Break the one big file into a bunch of small ones. That's been the standard answer to merge conflicts and extraction problems for far longer than AI agents have existed. I'm solving a 2026 problem with a very old trick... which is a big part of why I trust it.

Boss Edition

Crypts and Commits v0.3.0 — the Boss Edition — is that old trick, plus the process around it.

The vocabulary sticks with the tabletop framing from the rest of the package. Milestones are bosses. The long-running initiatives that take them on are campaigns. I like the gaming analogy here more than I probably should: the best campaigns require a boss fight. (If you want the plain-language version of every term, the README has it.)

Each boss is its own Markdown file with tracking metadata in the frontmatter. Prerequisites go in a depends_on list that points to other bosses, so the order can stay loose while the dependencies stay explicit. The Agent Registry grant mechanism is exactly that kind of relationship: it has to come before more MCP servers, but it doesn't have to come next.

The part I care about most is the move from aspirational to historical. A boss is a guess about the future right up until a campaign takes it on. Once the campaign opens, its membership locks, and from then on the boss is a record of the campaign's starting goal. Whatever we learn along the way goes into the campaign's log — not back into the boss. Sometimes a campaign drifts far enough that its boss doesn't really feel like its boss anymore. That's fine. The record shows how we got from one to the other, and that's more honest than quietly rewriting the goal after the fact.

I'll be straight about the limits, though: nothing in a git repo is ever truly read-only. The framework is guidelines for the AI and suggestions for the Game Master — the developer. If I want to open a file and change it by hand, I can. That's intentional.

What changed most for me is who does the upkeep. Skills and an MCP server give the agent the process — context priming before work starts, fast search, and reference documents that describe how all of this is supposed to work. My AGENTS.md and CLAUDE.md barely need to mention it. Every change to the roadmap still needs my approval. In practice, I tell the agent what boss I want, it drafts one, and we refine it in chat.

Here's a real one, straight out of the Crypts and Commits repository:

---
archived: false
campaign: c001-boss-edition
created_by: John Hoff
created_on: '2026-10-28T17:42:54Z'
depends_on:
- b001-boss-records
name: b002-rumor-records
status: vanquished
summary: 'Standalone rumor records: numbered rNNN backlog notes ...'
updated_by: John Hoff
updated_on: '2026-10-28T22:42:24Z'
---

## Goal

Give CAC a backlog for ideas that are not yet goals: a place to capture
"we think X should be done" from anywhere, and a planning-side path that
turns those notes into bosses or dismisses them with a reason.

## Rationale

The first design tied rumors to a single per-campaign document, which made
them a strict output of execution. Most good ideas come from elsewhere
(operating the project, reviews, other people), and each needs its own
identity so planning can triage it, link it to a goal, dismiss it, or
notice how often it recurs.

A rumor, in case you're wondering, is a numbered backlog note for an idea that isn't a goal yet — planning either promotes it to a boss or dismisses it with a reason. And yes, this boss is dogfood. Crypts and Commits is built with Crypts and Commits, and this boss was part of the Boss Edition campaign that took the project from 0.2.0 to 0.3.0. It's on the small side, too. I'd expect most bosses to run ten to twenty paragraphs.

So what do I actually know? Splitting the roadmap into separate files takes care of the merge conflicts and the extraction problem — that part is old news. Less time spent maintaining the roadmap is an expectation. I don't have to tell the agent how to mutate the roadmap as we hit each milestone anymore, and that already feels like a relief. But the release went up on PyPI a few hours ago, and as far as I know, I'm still its only user. Ask me again in a few weeks.

Try a small map

You don't need Crypts and Commits to try any of this.

Create a docs/roadmap.md. Sketch out what you expect to do with an AI agent over the next two weeks. It doesn't have to be pretty — a detailed to-do list is fine. When you start a piece of work, point at it: "We're implementing item 3." Then watch whether the agent's suggestions change. When they do, ask it why. And then judge it by what it did, not just by what it says.

If that file creeps up toward 30,000 characters, or starts throwing merge conflicts, that's your sign to break it up — with this package, or with whatever structure fits the way you work.

The tools are just how I happen to do it. The reason is the part I'd hang on to: give the agent a future to reason about.

This is how I'm adapting to AI right now. And no, I don't know yet whether Boss Edition actually works. But I'm more than willing to be wrong in public with it.