Every plan I wrote in Markdown had the same fate. I read it once while it was being written, skimmed it later, and nobody else on the team opened it at all.
The format was the problem. A Markdown task carries one bit: done, or not done. A real feature plan needs to carry a mockup, an API shape, three states nobody thought about, and the reason the second approach was rejected.
The difference is who reads it
Markdown moves review to the end, where it is expensive. HTML moves it to the front, where it is cheap.
What each format can actually hold
| A plan needs to show | Markdown | Single HTML file |
|---|---|---|
| Task done or not done | Checkbox | Checkbox |
| Blocked, and blocked on what | Prose beside the box | Attribute you can query |
| What the screen looks like | Link to Figma, if it exists | Real mockup, styled with the product's own CSS |
| Loading, error, empty, permission states | A bullet each, usually skipped | A button per state |
| Two competing approaches | Two sections, read in sequence | Side by side, or a toggle |
| API and data flow | ASCII art | An actual diagram |
| Which repo the work lands in | A heading | A labelled map |
| Read by a non engineer | Rarely | Open the file |
None of this is exotic. It is one file, opened in a browser, with no build step.
The prompt I use
The whole thing is a single instruction: produce one self contained HTML file, reuse the product's existing UI as the visual source of truth, keep alternatives on the same page behind a toggle, and prefer mockups and diagrams over paragraphs.
Treat the current frontend as the visual source of truth. Not a template, not a fresh design language. If the plan does not look like the product, nobody trusts what it is proposing.
The rest is a checklist: every requested feature represented, backend and cross repo work included even when it is invisible in the UI, assumptions clearly separated from confirmed behaviour, and every demo button actually working.
The part that made it stick
I got the idea from Theo, looked at how he was using it, and then built the piece that made it work for me.
The plan is not a file I open on my own machine. Any agent can write one, and it deploys through a tunnel as soon as it lands. So I read it wherever I am, usually on my phone, and so does everyone else I send the link to.
Each plan also splits by where the work actually lands:
| Change type | What the plan leads with |
|---|---|
| Frontend | Mockup in the product's own styling, then component and state map |
| Backend | API contracts and data flow, then the repo level implementation map |
| Both | The two views on one page, switchable, so nothing gets reviewed in isolation |
Benchmarks and the acceptance checklist sit at the bottom of the same file. One artifact, one link, nothing to assemble later.
When Markdown still wins
Short plans. Three tasks and a decision, read once by one person, done by lunch. Reaching for HTML there is ceremony.
The switch pays off at the size where a plan stops being a list and starts being a document that somebody else has to agree with.