HTML vs Markdown Plans

Why we switched from Markdown to self-contained HTML files for AI-generated architecture plans and implementation tracking.

Used with Claude Code for real production planning
📝 Markdown Plan
# Payment Migration Plan ## Overview Migrate Stripe v2 to v3, add Klarna. ## Phases | Phase | Task | Status | |-------|------|--------| | 1 | Stripe SDK Upgrade | DONE | | 2 | Webhook Migration | IN PROGRESS | | 3 | Klarna Integration | TODO | ## Architecture No visual diagrams possible in raw .md Mermaid only renders in GitHub/tools ```mermaid flowchart LR A[Client] --> B[API] B --> C[Stripe v3] ``` ## Decisions - **Webhook delivery**: SNS vs direct - Decision: Direct (simpler) - **Klarna market**: DACH first ## Code References - `src/payments/stripe.ts:142` - `src/webhooks/handler.ts:89` ### Notes Plain text. No interactivity. No way to give feedback inline. Can't highlight a section + comment.
Limitations:
  • Mermaid doesn't render in most editors
  • No interactivity or feedback mechanism
  • Status tracking is plain text
  • No visual hierarchy for decision states
  • Can't share as standalone viewable file
🌐 Interactive HTML Plan

Payment Provider Migration

Stripe v2 → v3 upgrade + Klarna DACH integration

PhaseTaskStatus
1 Stripe SDK Upgrade DONE
2 Webhook Migration IN PROGRESS
3 Klarna Integration PENDING

Architecture

flowchart LR
    A["Client App"] --> B["API Gateway"]
    B --> C["Stripe v3"]
    B --> D["Klarna"]
    C --> E["Webhook Handler"]
    D --> E
    E --> F[("Database")]
    style C fill:#635bff,color:#fff
    style D fill:#ffb3c7,color:#1a1a1a

Decisions

Webhook delivery DECIDED
Direct HTTP → simpler, fewer moving parts
Klarna market rollout DECIDED
DACH first, expand to Nordics in Q3
Interactive Feedback: Select any text, right-click any element, or click the feedback panel to leave comments — then export as JSON and paste into Claude Code.

Feature Comparison

Feature
Markdown
HTML
Mermaid diagrams render
⚠️ Only GitHub/tools
✓ Always (CDN)
Visual status badges
✗ Plain text
✓ Color-coded
Shareable standalone file
⚠️ Needs renderer
✓ Any browser
Interactive feedback
✗ Not possible
✓ Select + comment
Grid/card layouts
✗ Linear only
✓ CSS Grid/Flexbox
Dark/light theming
✗ No control
✓ CSS variables
Decision tracking
⚠️ Manual text
✓ Structured cards
Real-time progress
✗ Edit text
✓ Badge updates
Export feedback as JSON
✗
✓ Copy → Claude
Zero dependencies
✓ Plain text
✓ Self-contained
Version control friendly
✓ Great diffs
⚠️ Larger diffs
Edit without tooling
✓ Any editor
⚠️ Needs HTML knowledge

How the HTML Plan Workflow Works

Human + AI collaboration loop with structured feedback

1

AI Creates Plan

Claude Code generates a self-contained HTML with Mermaid diagrams, phase tables, and decision cards

2

Human Reviews

Open in browser, see rendered diagrams. Select text or right-click elements to leave inline comments

3

Export Feedback

Click "Export JSON" in the feedback panel. Paste the structured feedback into Claude Code

4

AI Iterates

Claude updates the plan based on feedback, re-uploads. Repeat until approved, then implement

Feedback Loop Diagram

sequenceDiagram
    participant Dev as Developer
    participant CC as Claude Code
    participant GCS as Cloud Storage
    participant Browser as Browser

    Dev->>CC: Describe feature/task
    CC->>CC: Explore codebase, design plan
    CC->>GCS: Upload plan.html
    CC->>Dev: Here's the plan link
    Dev->>Browser: Open plan URL
    Browser->>Dev: Rendered diagrams + tables
    Dev->>Browser: Select text, add comments
    Browser->>Dev: Feedback JSON
    Dev->>CC: Paste feedback JSON
    CC->>CC: Update plan based on feedback
    CC->>GCS: Upload updated plan.html
    Note over Dev,CC: Repeat until approved
    Dev->>CC: Looks good, implement it
    CC->>CC: Write code following the plan

When to Use What

Use Markdown when...

  • Quick notes or scratchpad
  • Simple task lists (no visual tracking)
  • README files and docs in repo
  • Content that lives in version control long-term
  • No diagrams or simple text descriptions suffice

Use HTML plans when...

  • Multi-phase implementation plans
  • Architecture decisions with trade-offs
  • Plans that need visual diagrams (flows, ERDs, sequences)
  • Collaborative review with structured feedback
  • Tracking progress across phases
  • Sharing with stakeholders who don't use dev tools

Try It Yourself

Ask Claude Code to create an interactive HTML plan for your next feature.

claude "Create an interactive HTML plan for [your feature] with Mermaid diagrams"

See a full example: Payment Provider Migration Plan

Pro Tip: Save as a Skill

Make this a reusable slash command so you can generate interactive HTML plans anytime with /plan.

1. Create the skill file

# .claude/skills/interactive-plan.md

## Description
Generate an interactive HTML architecture plan
with Mermaid diagrams, phase tracking, decision
cards, and a feedback panel for review.

## Instructions
1. Explore the codebase for context
2. Create a self-contained HTML file with:
  - Mermaid.js CDN for diagrams
  - Phase table with status badges
  - Architecture decision cards
  - Code reference table
  - Feedback panel (select text +
    right-click to comment, export JSON)
3. Upload to GCS / serve locally
4. Share the URL with the user

2. Use it anytime

# In Claude Code, just type:

/plan Add eBay cancellation handling

# Claude will:
1. Explore relevant files
2. Generate the HTML plan
3. Include Mermaid flow diagrams
4. Add feedback panel for review
5. Upload & share the link

# Review in browser, export feedback
# JSON, paste back into Claude Code
Skills are reusable prompt templates stored in .claude/skills/. They become slash commands that any team member can use. Docs