AI-assisted, Spec-Driven Software Development with markdown-denmarkdown-den

AI-assisted, Spec-Driven Software Development with markdown-den

By Diego Guridi

Problems with prompting your way to a feature

TL;DR: A chat window is a good way to get code and a bad way to keep purpose and decisions.

Problem one: the reasoning disappears. Getting a feature built takes a lot of explaining, and almost none of it ends up in the code: why an awkward case is handled the way it is, which approach you tried first and abandoned, what the alternative would have cost. All of it lived in the conversation, and the conversation is gone by the next session. What survives is the code, and code is a poor record of intent: it tells you what happens, never what was meant to happen.

Problem two: the ideas you have while waiting get lost. This one is quieter, and day to day it costs more. You send a prompt, and then you wait. That minute is exactly when a good but unrelated thought arrives: the sign-up flow is confusing, that error message is wrong, this page is slow on a phone. None of it is about what the agent is doing right now, and a chat has one queue. So you either derail the work in progress, or you hold the thought until it evaporates. Most evaporate. The waiting costs focus as well: an empty minute pulls you somewhere else, and coming back is slower than leaving was.

Neither problem is new. In The New Code, Sean Grove estimates that the code itself is only 10-20% of what a programmer contributes; the rest is understanding the problem, deciding what to build, and checking that the result solves it. Call that "the writing around the code", and it is the part a chat window throws away, because a spec keeps it and a prompt does not. The tooling is following this trend: GitHub's Spec Kit and AWS's Kiro both make a spec the unit of work. Vibe coding without killing focus takes up the second problem, and answers it by batching: plan a handful of small tasks in one sitting, launch them in parallel, then review the results together. That only works if the thought arriving mid-wait has somewhere to land, so it can join the next batch instead of derailing this one.

Markdown is what makes that workable. It is the one format both parties read natively (a person needs no viewer, a model needs no conversion), and it is still precise enough to carry a table of scenarios and to diff cleanly when one line changes. Neither side is translating for the other, which is why the document can be where the work happens rather than a record of it.

What markdown-den adds is a where. The spec lives in the workspace the agent works in, the collaborator that writes the code also maintains the document, and reviewing it happens on the document itself rather than on a copy of it.

Idea formality is a ladder

Formality usually gets treated as a switch: either you just prompt, or you write the whole specification. Most ideas need neither. They arrive half-formed, and they are worth writing down long before they are worth designing, so writing one down should cost nothing, and only deciding to build it should cost something.

That gives one idea four shapes it can have, in order of how much work it has earned:

Idea ShapeWho writes itWhat it costsIt moves on when
A line in a to-do listyou, mid-thought, in secondsnothingan agent or human picks it up
A paragraph in your own words, informal and unstructuredyoua minuteit's worth a design
A draft spec: the problem, the options, a recommendation, and how you'd know it workedthe agent writes it; you read and commentrounds of reviewyou agree to build it
A spec, with code: versioned beside the code, tests named after its scenariosthe agent implements; you mergea branch and a reviewit ships

Three things are worth saying about these:

None of the first three go into version control. The line, the paragraph and the draft all live outside it: they are documents you argue with in the margins. No branch, no pull request, no merge. Version control makes disagreement expensive at exactly the moment it should be cheap. A line you thought better of should cost a deletion rather than a revert, a paragraph should be rewritten without ceremony, and the whole value of writing a proposal down is that rejecting it costs a comment. The repository begins at the last step, where a decision has been made and the code has to match it, or at a branch that skipped the documents entirely, because the work never needed designing.

A line can go straight to the end. Plenty of work needs no design at all: a bug someone can reproduce from the sentence describing it, a rename, a wrong label, a missing guard. That goes from one line to a branch and a pull request without passing through anything in between. The reasoning fits in the commit message, and inventing a document for it would be ceremony rather than thought. These are shapes an idea can take, not steps that have to be walked through.

A paragraph is a fine place to stop. Most ideas never need to become anything more, and half-thought prose in a file is a real answer rather than a failure to write a proper document. A process that only accepts finished thinking gets routed around by the people it was built for.

One thing has to hold across all four: an idea should never have to move somewhere else as it grows. Every hand-off, a notes app to a chat, a chat to an issue tracker, is a place where ideas quietly get dropped.

What is markdown-den

markdown-den is a markdown workspace you share with people and with AI agents. It can serve as a context engineering workbench for your agents. Documents are the work product rather than a byproduct: notes, drafts and specs live in folders you can open from a browser or a phone, comments attach to the sentence they are about and stay attached as the text changes around them, and agents connected over MCP are members of the workspace with a role: they read the same files, reply on the same threads, and can branch, implement and open pull requests against your repository.

That speaks to both problems directly. The reasoning ends up in a document rather than a transcript, sitting next to the code it explains and maintained by the same collaborator that writes that code. And an idea arriving at the wrong moment has somewhere to go in ten seconds, in the same workspace it will grow up in, so writing it down costs nothing and promoting it later never means retyping it somewhere else.

The rules live in the workspace too. An AGENTS.md at its root says how that particular workspace works: where a note belongs, how to handle a TODO.md file, which checks have to pass before a pull request, what the agent must never decide on its own. The ladder above is exactly the kind of thing it holds. Nothing in markdown-den enforces those four "idea shapes", so a workspace writes down the ones it wants and the agent reads them before acting.

Setting up a markdown-den workspace for spec-driven development

Five steps, none of them long.

  1. Make your folders mean something. e.g. TODO.md for tasks and line-shaped ideas, notes/ for paragraphs written by you, drafts/ for proposals, specs/ for what has been agreed.

  2. Write the AGENTS.md. Half a page is enough: where each kind of document belongs, what, for example, an "assess this" ask should produce, which checks have to pass before a pull request, and what the agent must never do on its own. Merging and closing discussions are the usual two. Something like this is a good start:

    # AGENTS.md

## Where things live
- `TODO.md`: one-line ideas/tasks. **Read it on every check-in**: an unstruck line
  is open work. Take them top to bottom and strike each one as it ships,
  leaving the original wording intact so the struck line is the record.
- `notes/`: paragraphs. Informal, half-thought, no structure required. Never
  in git.
- `drafts/`: proposals for me to read and argue with. Never in git.
- `specs/`: agreed. Mirrored into the repo under `docs/specs/`.
- `STATUS.md`: the dashboard. **Rewrite it at the end of every check-in.**
  Re-derive it from the folders and the repository; never append. List open
  pull requests and what each waits on, drafts and ideas awaiting my review,
  anything blocked on me, and known gaps. One line each.

## What each ask produces
- "assess X" → a write-up in `notes/`, grounded in the real code, citing file
  paths, ending in options and a recommendation, including "don't build it".
- "spec X" → a draft in `drafts/`: problem, options, recommendation, and
  Given/When/Then scenarios.
- "build X" → only from an agreed spec, or from a `TODO.md` line small enough
  not to need one.

## Before you open a pull request
- Type-check, lint, build and the test suite are all green.
- Tests are named after the spec's scenarios; anything a test cannot cover is
  listed as needing a human, not claimed as covered.
- Say what you did NOT do, and what you could not verify.

## Never
- Merge. Opening the pull request is where you stop.
- Resolve a comment thread. That is my signal, not yours.
- Guess when an ask is genuinely ambiguous. Ask on the thread instead.

  3. Add the agent as a member. Create it under Manage agents, copy the MCP URL and connection key into your coding agent's configuration, and share the workspace with it in the role you would give a person: viewer if you want it commenting, editor when you want it writing.

  4. Give it the repository. The agent runs as an ordinary coding session with access to your code host, so the collaborator that edits the spec is the one that branches, implements and opens the pull request. This is between you and your agent; markdown-den doesn't play a role in this.

  5. Then just write. A line when the thought arrives; a paragraph when it nags; an @mention on that paragraph when you want it designed. Say "Check in" to the agent and the agent reads read its inbox, works the oldest item, replies on the thread, and looks again.

None of this is enforced by markdown-den, which is the point: the folder names, the ladder and every rule above are one workspace's answer, not markdown-den's. A team shipping a mobile app and a team maintaining a library want different folders, different checks and workflows before a pull request, and different things the agent may never decide on its own.

Further reading