{"id":3671937,"date":"2026-01-21T08:00:21","date_gmt":"2026-01-21T13:00:21","guid":{"rendered":"https:\/\/spin.atomicobject.com\/?p=3671937"},"modified":"2026-01-20T16:53:26","modified_gmt":"2026-01-20T21:53:26","slug":"html-spec-driven-development","status":"publish","type":"post","link":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/","title":{"rendered":"Why I Use HTML for Planning and Spec-Driven Development"},"content":{"rendered":"
\n
\n
\n

I keep my agent planning and spec-driven development<\/a> 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.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

Defining Planning and Spec-driven Development<\/h2>\n
\n
\n

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.<\/p>\n<\/div>\n

\n

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.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

Why HTML Works For Me<\/h2>\n
\n
\n

HTML gives me rich presentation<\/a> 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.<\/p>\n<\/div>\n

\n

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.<\/p>\n<\/div>\n

\n

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.<\/p>\n<\/div>\n

\n

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.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

How I Serve and Share Specs<\/h2>\n
\n
\n

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.<\/p>\n<\/div>\n

\n

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.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

\n

A Typical Flow<\/h2>\n
\n
\n

Here is the flow that keeps me consistent.<\/p>\n<\/div>\n

\n
    \n
  • Start with a spec section that defines the scope, tools, constraints, and success criteria.<\/li>\n
  • Follow with a plan section that is stepwise and testable, with checkboxes for key validation moments.<\/li>\n
  • Add a status area for what changed and what was verified.<\/li>\n
  • Inline any UI sketches or small examples that clarify intent.<\/li>\n
  • Keep links to related documents or source files close to the plan steps that need them.<\/li>\n<\/ul>\n<\/div>\n
    \n

    This keeps the spec and the plan in one place, and it keeps the work anchored to the contract.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

    \n

    Tradeoffs I Accept<\/h2>\n
    \n
    \n

    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.<\/p>\n<\/div>\n

    \n

    Those costs are real, but they are predictable. For me, the clarity during execution is worth the extra authoring friction.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

    \n

    A Minimal Example Structure<\/h2>\n
    \n
    \n

    A structure like this has worked well for me.<\/p>\n<\/div>\n

    \n
      \n
    • Header with title, date, and tags<\/li>\n
    • Spec block with rules, invariants, and tool access<\/li>\n
    • Plan block with ordered steps and verification notes<\/li>\n
    • Notes block for follow-ups, open questions, and links<\/li>\n<\/ul>\n<\/div>\n
      \n

      The point is not the exact layout. It is the consistency. HTML helps me keep that consistency without relying on memory.<\/p>\n<\/div>\n<\/div>\n<\/div>\n

      \n

      Closing Thoughts<\/h2>\n
      \n
      \n

      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.<\/p>\n<\/div>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"

      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 […]<\/p>\n","protected":false},"author":569,"featured_media":3672123,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1609],"tags":[],"series":[],"class_list":["post-3671937","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-development-practices"],"acf":[],"yoast_head":"\nWhy I Use HTML for Planning and Spec-Driven Development<\/title>\n<meta name=\"description\" content=\"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Why I Use HTML for Planning and Spec-Driven Development\" \/>\n<meta property=\"og:description\" content=\"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/\" \/>\n<meta property=\"og:site_name\" content=\"Atomic Spin\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/atomicobject\" \/>\n<meta property=\"article:published_time\" content=\"2026-01-21T13:00:21+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"2560\" \/>\n\t<meta property=\"og:image:height\" content=\"1707\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"author\" content=\"Nick Keuning\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@atomicobject\" \/>\n<meta name=\"twitter:site\" content=\"@atomicobject\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Nick Keuning\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"4 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/\"},\"author\":{\"name\":\"Nick Keuning\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#\\\/schema\\\/person\\\/b6d1c3de555e4853f9a2c7d33e02ec13\"},\"headline\":\"Why I Use HTML for Planning and Spec-Driven Development\",\"datePublished\":\"2026-01-21T13:00:21+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/\"},\"wordCount\":730,\"commentCount\":3,\"publisher\":{\"@id\":\"https:\\\/\\\/atomicobject.com\\\/\"},\"image\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/JDP-AO2023-114-2-scaled.jpg\",\"articleSection\":[\"Development Practices\"],\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/\",\"name\":\"Why I Use HTML for Planning and Spec-Driven Development\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/JDP-AO2023-114-2-scaled.jpg\",\"datePublished\":\"2026-01-21T13:00:21+00:00\",\"description\":\"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.\",\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/html-spec-driven-development\\\/#primaryimage\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/JDP-AO2023-114-2-scaled.jpg\",\"contentUrl\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/JDP-AO2023-114-2-scaled.jpg\",\"width\":2560,\"height\":1707,\"caption\":\"Author Nick Keuning with a co-worker. Post title: Why I Use HTML for Planning and Spec-Driven Development\"},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#website\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/\",\"name\":\"Atomic Spin\",\"description\":\"Atomic Object\u2019s blog on everything we find fascinating.\",\"publisher\":{\"@id\":\"https:\\\/\\\/atomicobject.com\\\/\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/spin.atomicobject.com\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"},{\"@type\":\"Organization\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#organization\",\"name\":\"Atomic Object\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#\\\/schema\\\/logo\\\/image\\\/\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/AO-Logo-Emblem-Color.png\",\"contentUrl\":\"https:\\\/\\\/spin.atomicobject.com\\\/wp-content\\\/uploads\\\/AO-Logo-Emblem-Color.png\",\"width\":258,\"height\":244,\"caption\":\"Atomic Object\"},\"image\":{\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#\\\/schema\\\/logo\\\/image\\\/\"},\"sameAs\":[\"https:\\\/\\\/www.facebook.com\\\/atomicobject\",\"https:\\\/\\\/x.com\\\/atomicobject\"]},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/spin.atomicobject.com\\\/#\\\/schema\\\/person\\\/b6d1c3de555e4853f9a2c7d33e02ec13\",\"name\":\"Nick Keuning\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg\",\"caption\":\"Nick Keuning\"},\"description\":\"Software Consultant & Developer at Atomic Object Grand Rapids. Member of Accelerator Cell Three. Huge fan of breakfast.\",\"url\":\"https:\\\/\\\/spin.atomicobject.com\\\/author\\\/nick-keuning\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Why I Use HTML for Planning and Spec-Driven Development","description":"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/","og_locale":"en_US","og_type":"article","og_title":"Why I Use HTML for Planning and Spec-Driven Development","og_description":"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.","og_url":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/","og_site_name":"Atomic Spin","article_publisher":"https:\/\/www.facebook.com\/atomicobject","article_published_time":"2026-01-21T13:00:21+00:00","og_image":[{"width":2560,"height":1707,"url":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg","type":"image\/jpeg"}],"author":"Nick Keuning","twitter_card":"summary_large_image","twitter_creator":"@atomicobject","twitter_site":"@atomicobject","twitter_misc":{"Written by":"Nick Keuning","Est. reading time":"4 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#article","isPartOf":{"@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/"},"author":{"name":"Nick Keuning","@id":"https:\/\/spin.atomicobject.com\/#\/schema\/person\/b6d1c3de555e4853f9a2c7d33e02ec13"},"headline":"Why I Use HTML for Planning and Spec-Driven Development","datePublished":"2026-01-21T13:00:21+00:00","mainEntityOfPage":{"@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/"},"wordCount":730,"commentCount":3,"publisher":{"@id":"https:\/\/atomicobject.com\/"},"image":{"@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#primaryimage"},"thumbnailUrl":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg","articleSection":["Development Practices"],"inLanguage":"en-US","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/","url":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/","name":"Why I Use HTML for Planning and Spec-Driven Development","isPartOf":{"@id":"https:\/\/spin.atomicobject.com\/#website"},"primaryImageOfPage":{"@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#primaryimage"},"image":{"@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#primaryimage"},"thumbnailUrl":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg","datePublished":"2026-01-21T13:00:21+00:00","description":"I keep my agent planning and spec-driven development work in HTML. That started as a small experiment and turned into a default.","inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/spin.atomicobject.com\/html-spec-driven-development\/"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/spin.atomicobject.com\/html-spec-driven-development\/#primaryimage","url":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg","contentUrl":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/JDP-AO2023-114-2-scaled.jpg","width":2560,"height":1707,"caption":"Author Nick Keuning with a co-worker. Post title: Why I Use HTML for Planning and Spec-Driven Development"},{"@type":"WebSite","@id":"https:\/\/spin.atomicobject.com\/#website","url":"https:\/\/spin.atomicobject.com\/","name":"Atomic Spin","description":"Atomic Object\u2019s blog on everything we find fascinating.","publisher":{"@id":"https:\/\/atomicobject.com\/"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/spin.atomicobject.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"},{"@type":"Organization","@id":"https:\/\/spin.atomicobject.com\/#organization","name":"Atomic Object","url":"https:\/\/spin.atomicobject.com\/","logo":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/spin.atomicobject.com\/#\/schema\/logo\/image\/","url":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/AO-Logo-Emblem-Color.png","contentUrl":"https:\/\/spin.atomicobject.com\/wp-content\/uploads\/AO-Logo-Emblem-Color.png","width":258,"height":244,"caption":"Atomic Object"},"image":{"@id":"https:\/\/spin.atomicobject.com\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/www.facebook.com\/atomicobject","https:\/\/x.com\/atomicobject"]},{"@type":"Person","@id":"https:\/\/spin.atomicobject.com\/#\/schema\/person\/b6d1c3de555e4853f9a2c7d33e02ec13","name":"Nick Keuning","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/secure.gravatar.com\/avatar\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg","url":"https:\/\/secure.gravatar.com\/avatar\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/cd2690a223e12f3884e2a19ae15efa6e53c8e8275cb16de1ce839791bb44d71b?s=96&d=blank&r=pg","caption":"Nick Keuning"},"description":"Software Consultant & Developer at Atomic Object Grand Rapids. Member of Accelerator Cell Three. Huge fan of breakfast.","url":"https:\/\/spin.atomicobject.com\/author\/nick-keuning\/"}]}},"_links":{"self":[{"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/posts\/3671937","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/users\/569"}],"replies":[{"embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/comments?post=3671937"}],"version-history":[{"count":0,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/posts\/3671937\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/media\/3672123"}],"wp:attachment":[{"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/media?parent=3671937"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/categories?post=3671937"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/tags?post=3671937"},{"taxonomy":"series","embeddable":true,"href":"https:\/\/spin.atomicobject.com\/wp-json\/wp\/v2\/series?post=3671937"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}