I keep my agent planning and spec-driven development work in HTML. That choice started as a small experiment and turned into a default because the documents became more usable in practice. This post is a short tour of how I work, what I gain, and the tradeoffs I accept.
Defining Planning and Spec-driven Development
For me, an agent spec is the contract. It defines tools, constraints, guardrails, and definitions. A plan file is the working scaffold for a single task with steps, checks, and decision points. Spec-driven development is the habit of writing the contract first and keeping it visible as work happens.
HTML has been the best format for those artifacts because it supports the way I use them, with quick scanning, clear hierarchy, and a layout that looks like a working surface rather than a note.
Why HTML Works For Me
HTML gives me rich presentation without extra tooling. Color coding, cards, and nested sections keep long specs from collapsing into walls of text. I can emphasize high-risk rules or reserved areas with visual weight, and I can keep related items grouped in a way that reads like an interface.
Code highlighting and embedded links make the documents feel alive. When I need a reminder of a command, a snippet, or a policy, it is right there in the layout. That matters when I am moving quickly, because the spec stays in front of me instead of living in a separate doc or wiki.
I also like that the agent can drop in quick inline prototypes of UI ideas. A tiny mock card, a button layout, or a colored status block communicates the intent faster than a paragraph. I am not building the final UI there, but I am creating a visual anchor that informs the next implementation steps.
HTML gives me a clear visual hierarchy. The spec reads like a structured object, which makes it easier to review and easier to extend without losing the shape of the document.
How I Serve and Share Specs
My default workflow is simple. I open the file in a browser, or I run a little static file server like Python’s http.server and share a link locally. That makes reviews easier because people can see a rendered version, not a raw file. It also makes it easy to grab a screenshot for a conversation in chat.
This works even when I am just working solo, because the browser view is a better editing target than a plain text view when the document is intended to guide action. The format becomes a working surface, not just a record.
A Typical Flow
Here is the flow that keeps me consistent.
- Start with a spec section that defines the scope, tools, constraints, and success criteria.
- Follow with a plan section that is stepwise and testable, with checkboxes for key validation moments.
- Add a status area for what changed and what was verified.
- Inline any UI sketches or small examples that clarify intent.
- Keep links to related documents or source files close to the plan steps that need them.
This keeps the spec and the plan in one place, and it keeps the work anchored to the contract.
Tradeoffs I Accept
HTML takes more effort to write by hand. Diffs can be noisier, and it is easier to introduce a small tag mismatch that looks fine in a text editor. I also have to be disciplined about conventions, or the document turns into a collection of ad hoc layouts.
Those costs are real, but they are predictable. For me, the clarity during execution is worth the extra authoring friction.
A Minimal Example Structure
A structure like this has worked well for me.
- Header with title, date, and tags
- Spec block with rules, invariants, and tool access
- Plan block with ordered steps and verification notes
- Notes block for follow-ups, open questions, and links
The point is not the exact layout. It is the consistency. HTML helps me keep that consistency without relying on memory.
Closing Thoughts
HTML lets me treat specs and plans as a working interface. That changes how I read them, how I share them, and how I execute on them. If your planning documents are already central to your workflow, a format that supports richer presentation may be worth the extra effort.