flat plan.md
Readable, but hard to inhabit
Markdown was the useful compromise: human-readable, machine-readable, and quick to write. But long implementation plans can become walls of text that get skimmed instead of used.
2026-05-18 / AGENT-NATIVE WORKING SURFACE
Make the Spec Usable
Markdown made plans easy to write. HTML makes them possible to inspect, edit, render, and hand to agents as a living working surface.
rendered specs micro UI agent OS
plan.md implementation-plan.html
editable rules table
interactiveMicro software on top of micro software
The perfect throwaway interface for the one part of the plan that matters now.
working artifact
“This ‘micro software on top of micro software’ approach means you can have the perfect tool for every specific problem, then discard it when you’re done.”
HTML SPECS
Plans Should Be Read, Rendered, and Used
rendered spec.html
Structured enough to work inside
HTML can hold mockups, tables, scrollable regions, swatches, components, and embedded review affordances without giving up machine readability.
MICRO UI
Throwaway Interfaces for the One Section That Matters
01 / isolate
Find the dense section
A rules table, plan subsection, QA matrix, or prompt library that is too important to skim and too awkward to edit as plain text.
02 / render
Generate the perfect tiny tool
Ask the agent to turn that one section into a custom interface with filters, toggles, cards, examples, and visual affordances.
03 / discard
Use it, then let it go
The interface does not need to become a product. It only needs to make this one editing pass more legible and more enjoyable.
implementation-notes.html
FEEDBACK LOOP
Keep Notes While Reality Deviates From the Spec
The missing artifact is not a post-hoc summary. It is a running decision log that stays attached to the work while the agent is still making tradeoffs.
implement <SPEC> and while you do,
keep a running implementation-notes.html file
(or markdown) with decisions you had to make
weren't in the spec, things you had to change,
tradeoffs you had to make or anything else
I should knowAGENT OS
Portable Context Is the Layer Under the HTML Layer
Rich specs help one project. Shared memory, instructions, skills, prompts, and goal templates help every agent that touches the workflow.
01
Export ChatGPT + Claude memories, context, and workflows.
02
Generate DESIGN.md, CLAUDE.md, and AGENTS.md for agentic repos.
03
Build a model-agnostic skills library that tools can share through adapters or symlinks.
04
Version system prompts in git so silent drift gets caught in review.
05
Turn the top recurring workflows into /goal templates instead of repeated prompting.
Design Notes
YIL 2026-05-18 — HTML as Agent-Native Working Surface
A day about HTML replacing flat Markdown as a high-density working surface for AI collaboration: interactive specs, throwaway editing UIs, living design systems, running implementation notes, and portable agent context.
accent-1 / HTML specs
accent-2 / Micro UI
accent-3 / Implementation notes
accent-4 / Agent OS
The artifact follows the Clay reference analysis with a cream canvas, rounded generous surfaces, saturated feature cards, and product-mockup/browser motifs. The uniqueness comes from the day's content: the spec itself becomes a usable, rendered interface with room for a design system, custom editor, implementation log, and portable context checklist.