mdplane

mdplane started because I wanted to share markdown with a non-technical friend so he could load it straight into Claude Code. Everything I found felt wrong for that use case. It was either ugly, full of ads, weak at rendering markdown, or too public. I first thought I was building a nicer way to share files.

That idea changed pretty quickly. Markdown sharing was already a mature category. The part that seemed underbuilt was coordination. I wanted one document that both humans and agents could work through together, especially across colleagues and separate machines. That is where mdplane came from: not just file sharing, but a place for tasks, claims, blockers, answers, and results to accumulate in the same file.

The important architectural decision was keeping the product boundary clean. mdplane is not the thing that runs agents. It is the shared layer underneath them: it stores files, records workflow activity, exposes permissions, and emits events when work changes. A separate script or service can listen for those events, start an agent run, and let that agent append the result back into the same file. Keeping those responsibilities separate made the system much easier to reason about.

Markdown was the key product decision. Agents already read and write it well, and humans can inspect the same file without any special tooling. More importantly, one markdown file can hold both the durable context at the top and the workflow activity underneath it. That let me keep instructions, handoffs, blockers, and outcomes in one artefact instead of scattering them across logs, chats, and framework state. The append model sits on top of that: tasks, claims, blockers, answers, and responses. I also had to rewrite the docs several times before I found a way of explaining that cleanly to someone seeing the idea for the first time.

This was my first proper agentic coding project. Claude Code, Codex, and OpenCode wrote almost all of the code. I was directing them, reviewing the output, and correcting course constantly. At the start of 2026 there was a lot of hype around models supposedly one-shotting serious apps. mdplane was the opposite experience. It took about a month, around 2,000 commits, and roughly 5,000 prompts because the main problem was drift. URLs drifted. Query params drifted. Request and response shapes drifted. Agents would also claim something was finished when it plainly was not.

That is why the repo ended up so programmatic and so heavily tested. I leaned hard on spec-driven development and TDD. OpenAPI came first. Types came from the spec. The Elysia routes were wired around those generated contracts. The docs came from the same source. The repo also has checks for route coverage, enum sync, query params, and docs drift. It has thousands of tests because I stopped trusting model output very early on. Opus 4.5 in particular was happy to tell me something was bulletproof when it was half-migrated. Without hard gates, this project would not have shipped cleanly.

The product itself also forced some backend work that I had not really done in public before. The append model had to be simple in markdown but still hold up in real use. Claims needed expiry. Writes needed idempotency. Capability URLs needed least-privilege rules. File paths needed proper traversal guards. Once the code was public, I also had to think much more seriously about how a hosted service like this gets attacked. That pushed me into security work I had mostly avoided in personal projects before.

The useful part of agentic coding was leverage, not autonomy. It let me take on a much larger system than I would usually build alone, and it let me move quickly. But it only worked because I kept the models inside a process with contracts, tests, and a lot of review.

The part I am happiest with is the append model. Silent edits are bad for coordination. A file that shows tasks, claims, blockers, answers, and responses is much easier to reason about, both for humans and for other agents. That is the bit of mdplane that feels genuinely new to me.

More generally, mdplane made me think that good engineering in the agentic era still looks pretty familiar. You still need clear contracts, strong boundaries, and boring checks that catch mistakes early. The tools are new. The need for rigor is not.