feat(sdd): migrate spec-driven development workflow from Markdown to HTML

[DanielPodolsky]

Context

Anthropic's Claude Code lead Thariq Shihipar published The Unreasonable Effectiveness of HTML on 2026-05-08, arguing HTML beats Markdown as the canonical output format for AI agents in the 1M-context era. Anthropic has adopted HTML as the internal default for plans, code reviews, design systems, and reports.

The argument in one line:

Markdown won when context windows were small and every token mattered. Context windows are a million tokens now. The original constraint is gone. HTML's display power wins.

This issue migrates OwnYourCode's Spec-Driven Development (SDD) workflow to HTML as the canonical format for all 6 SDD artifacts. Maximalist scope — no hybrid.

Why now

• 1M context windows flipped the token-cost calculus — bottleneck shifted from fitting context to human comprehension.
• The cwc-workshops 'How We Claude Code' workshop demonstrates the canonical pattern: HTML mockups as the design artifact, 4 divergent layouts side-by-side, agents reason across them.
• 'Plans you actually read' = 'plans you understood' = ownership. Aligns with OwnYourCode's anti-cognitive-offloading positioning.

Scope — all 6 SDD files

File	Created by	Read/Mutated by	Migration
`ownyourcode/product/mission.html`	`/own:init`	Human review	New HTML template
`ownyourcode/product/stack.html`	`/own:init`	Human reference	New HTML template
`ownyourcode/product/roadmap.html`	`/own:init`	`/own:feature` (phase detection), Human	HTML parsing required
`ownyourcode/specs/active/phase-[N]-[name]/spec.html`	`/own:feature`	`/own:guide`, Human	New HTML template
`ownyourcode/specs/active/phase-[N]-[name]/design.html`	`/own:feature`	`/own:guide`, Human	Killer feature: 4 design options pattern
`ownyourcode/specs/active/phase-[N]-[name]/tasks.html`	`/own:feature`	`/own:done` (mutates checkboxes), `/own:status` (parses progress)	HTML mutation + parsing required

Work items

• Templates: HTML templates for all 6 file types
• `/own:theme` command: New command for user-customizable theme prompts, stored in `.claude/ownyourcode-theme.md`
• Default theme: Premium/Apple-inspired default styling prompt (user can override theme ONLY, not workflow)
• `/own:init` migration: Write mission/stack/roadmap as HTML
• `/own:feature` migration: Write spec/design/tasks as HTML; parse `roadmap.html` for incomplete phase detection
• `/own:done` migration: Mutate HTML checkboxes in `tasks.html` (DOM-style manipulation)
• `/own:status` migration: Parse HTML for progress %
• `frontend-design` skill integration: Define when/how the skill is invoked (one-shot generation? per-file? cost boundaries)
• Migration strategy: Decide handling for existing MD installations (autoconvert? fresh-only? side-by-side during transition?)
• Design.md '4 layouts' pattern: Implement the workshop's killer feature — generate 4 divergent design directions in one HTML file, user picks one

Out of scope

• Other OwnYourCode commands (`/own:retro`, `/own:advise`, `/own:stuck`, `/own:profile`, `/own:docs`, `/own:test`, `/own:guide`) — they don't touch SDD files
• Learning registry, retro logs, career stories — those stay Markdown
• Replacing the `frontend-design` skill itself

References

• Thariq's original X post
• Workshop repo: cwc-workshops/how-we-claude-code
• Simon Willison's endorsement
• Lenny's Newsletter on HTML as the new Markdown

Notes for implementer

• This is a multi-PR feature, not a single change. Stage logically (templates → `/own:theme` → `/own:init` → `/own:feature` → `/own:done`/`/own:status`).
• DOM mutation in `/own:done` is the hardest part — that's a senior engineering challenge worth surfacing in the LinkedIn post.
• Theme system must enforce: user controls VISUAL design only, not workflow structure.
• Cost analysis: HTML costs ~2-3x MD per generation in raw tokens, but saves more in reduced iteration cycles. Net positive for human-read files.

Source of decision: brainstorm session 2026-05-28 after watching Code with Claude London lectures on YouTube.

[DanielPodolsky]

🏛️ Architecture Decisions Locked (2026-05-28 planning session)

All 6 planning decisions resolved. Full design now ready for implementation.

Decision summary

#	Topic	Decision
1	HTML parsing/mutation	Option D — `data-task-id` + `data-status` attributes on every task block; Claude uses the Edit tool for exact-string mutation. No external HTML parser dependency.
2	PR sequencing	5 PRs, strict sequential (no worktrees this round). PR1 dissolves the originally-planned PR 5 (frontend-design) into foundation.
3	Template structure	`core/templates/html/` directory — 6 `.html.template` files + `theme-prompt.md.template` + `theme-fallback.css`. Templates are semantic contracts, not literal placeholders. Inline HTML comments document mutation contracts.
4	`/own:theme` design	Single generated CSS file (`ownyourcode/.theme/theme.css`) referenced by all 6 HTML. 4 actions: change prompt, pick preset, regenerate, view. Backup history at `.theme/.history/[timestamp]/` enables revert. Default theme = Apple Documentation aesthetic.
5	frontend-design integration	Soft dependency with auto-install prompt during `/own:init`. If user declines, fallback to bundled CSS. Plugin invoked during `/own:theme` only.
6	Migration strategy	Opt-in `/own:migrate` command with backup-before-convert + `--revert`. v2.4.0 ships as non-breaking minor version. New projects: HTML default. Existing projects: stay MD until user opts in.

Final PR breakdown (5 PRs, sequential)

PR	Scope	Deliverable
PR 1	Foundation	`core/templates/html/` (6 templates + theme files), `/own:theme` command, plugin-install prompt logic, fallback CSS
PR 2	`/own:init` migrates to HTML output	mission.html, stack.html, roadmap.html generation
PR 3	`/own:feature` migrates to HTML output	spec.html, design.html, tasks.html generation + roadmap.html phase-detection parsing
PR 4	`/own:done` + `/own:status` HTML I/O	Data-attribute mutation (`/own:done`), data-attribute counting (`/own:status`)
PR 5	`/own:migrate` command	MD-to-HTML migration with backup folder, `--revert` support

Constraints (do not violate)

• ❌ No new SDD logic — HTML migration is pure visualization. Every file's PURPOSE remains identical to its MD counterpart.
• ❌ No "4 design layouts" pattern in design.html — that's a UI-mocking pattern for a future separate feature, not SDD design specs.
• ❌ No external HTML parser — Claude's Edit tool + data attributes do the work.
• ❌ No coexistence mode — projects are either MD or HTML, not both.
• ✅ Theme = visual styling only — never workflow.
• ✅ /own:migrate is opt-in, reversible, backup-first.

Task block semantic contract (the heart of Option D)

```html

Implement login form

\`\`\`

`/own:done` mutates: `data-status="pending"` → `data-status="completed"` AND adds `checked` to the ``.
`/own:status` counts: total `data-task-id="*"` vs `data-status="completed"`.

Ready for implementation

When work starts, begin with PR 1 (Foundation). Implementation guidance via `/own:guide`. Planning session referenced this issue throughout.