The HTML Shift: Why Your AI Planning Workflow is Obsolete

Thariq Shihipar explains that the main bottleneck in AI-assisted development is not model intelligence, but the communication medium between human and agent. While Markdown has been the industry standard for planning, it fails as projects scale. This leads to "long-form fatigue," where developers stop reading their own specifications. Shihipar argues that shifting to HTML artifacts turns planning from a static, text-heavy chore into an interactive, visual, and modular workspace. This change redefines the developer role from a passive reader to an active compute allocator. By adopting this workflow, teams can move faster, maintain better alignment with their agents, and create living documentation that stays relevant. This is essential reading for technical leaders who suspect their current planning processes create more friction than clarity.

The Hidden Cost of Readable Markdown

Conventional wisdom suggests that Markdown is ideal because it is simple, human-readable, and machine-readable. However, Shihipar identifies a dangerous downstream effect: as AI agents have become more capable, running for hours and generating thousands of lines of code, the resulting Markdown plans become unreadable.

When a plan exceeds the length of a screen, the human developer stops engaging with it. They stop editing it, stop verifying it, and eventually stop reading it. This creates a blind trust loop where the agent continues to build based on stale or unverified assumptions.

"I honestly have stopped reading them and this was honestly a mistake... like a thousand line markdown file, you know I don't even edit them anymore I just have Claude to edit them instead."

-- Thariq Shihipar

The system responds to this lack of engagement by producing lower-quality outputs. Because the human is no longer effectively in the loop, the agent loses the corrective feedback necessary to stay aligned with the actual project goal.

Why Compute Allocation Requires Better Interfaces

Shihipar redefines the role of the modern developer as a compute allocator. When an agent runs for eight hours, it is not just generating text; it is consuming significant resources. If you are not actively curating the plan, you are burning capital on unguided work.

The move to HTML allows for just-in-time documentation. Instead of maintaining a separate, rigid PRD or tech spec, developers can build throwaway micro-UIs that serve the immediate need of the project. This is not about building perfect software; it is about building the minimal interface required to keep the human and the agent synchronized.

"The amount of tokens I produce that go into production code is extremely small... but I'm generating so many more tokens like this--my dashboards, my custom interfaces--really trying to get a sense of what do I want to do."

-- Thariq Shihipar

This creates a competitive advantage: teams that use rich, interactive artifacts to guide their agents can steer the development process with higher precision than teams relying on static, disconnected text files.

The Systemic Advantage of Living Design Systems

One of the most persistent problems in software engineering is the drift between the design system and the actual implementation. Shihipar proposes using HTML to encode the design system directly into the repository.

When the design system is a living HTML artifact rather than a static document, it becomes portable. It travels with the codebase, meaning the agent has a constant, compressed understanding of the project's visual and functional constraints. This creates a feedback loop where the agent can reference the design system during every task, reducing the frequency of style errors and component inconsistencies.

Key Action Items

• Audit your current planning format: If your team specs are longer than a screen and rarely edited by humans, initiate a pilot project to move to HTML-based planning artifacts. (Next 2 weeks)
• Adopt the Compute Allocator mindset: Stop viewing AI output as a finished product. Treat every planning session as a budget allocation exercise where you must define clear success criteria before the agent begins execution. (Immediate