plan-repl-html

plan-repl-html (experimental)

A prototype variant of plan-repl. Same five phases (research, plan, annotation cycle, task breakdown, implementation), but each phase produces an HTML page with an interactive annotation widget. Each task folder also contains a sibling .repl-assets/ directory holding the shared stylesheet and widget JS (one snapshot per task). The goal is to evaluate whether HTML output unlocks meaningfully better review affordances — timelines, diagrams, severity tags, collapsible sections, in-page navigation, exportable structured annotations — compared to the markdown flow.

This skill is explicitly experimental. When something feels awkward, surface that to the user rather than smoothing it over; the friction is the point.

What this experiments with

• Richer artifacts at each phase: SVG data-flow diagrams in research, a timeline + risk table in the plan, a checkbox grid in the todo. Things HTML is good at and markdown isn't.
• In-browser annotation: the user clicks a section, types a note, and exports a per-phase JSON file Claude reads on the next turn. Replaces the > NOTE: blockquote convention from plan-repl.
• Annotation in every phase, not just planning. Research findings and the todo breakdown become annotatable too — the working hypothesis is that catching mistakes in research is even cheaper than catching them in the plan.
• Shared CSS + JS per task: the scaffold's styling and annotation widget live in two files (style.css, annotations.js) copied once per task to tasks/{task-name}/.repl-assets/. Each phase HTML links to them via relative paths. This trades the previous single-file shareability for much cheaper regeneration on each annotation round, and eliminates CSS drift between phase pages of the same task.

Starting a task

Suggest a short kebab-case name based on the user's prompt. Persisted files live in tasks/{task-name}/ alongside any markdown files from a parallel plan-repl run:

File	Purpose
tasks/{task-name}/research.html	Research findings, annotatable per section
tasks/{task-name}/plan.html	Implementation plan, annotatable per section
tasks/{task-name}/todo.html	Task breakdown, checkboxes are source of truth
tasks/{task-name}/{phase}.annotations.json	Latest annotation export from the user, per phase
tasks/{task-name}/.repl-assets/style.css	Shared stylesheet, copied from the skill on first phase
tasks/{task-name}/.repl-assets/annotations.js	Shared annotation widget, copied from the skill on first phase

Phase 0: One-time setup (first phase only)

Before generating any HTML, do this once per task:

1. Create tasks/{task-name}/.repl-assets/ if it doesn't already exist
2. Copy skills/plan-repl-html/assets/style.css to tasks/{task-name}/.repl-assets/style.css
3. Copy skills/plan-repl-html/assets/annotations.js to tasks/{task-name}/.repl-assets/annotations.js

The copy is a snapshot. Once a task has .repl-assets/, leave them alone for the life of the task. If the skill's assets are updated mid-task, in-flight tasks keep their original snapshot — preventing surprise visual drift between annotation rounds. To pick up new assets, the user deletes the task's .repl-assets/ and asks you to regenerate (you re-copy and re-render the phase pages).

Skip this step on subsequent phases of the same task — the assets are already there.

Scaffold mechanics

Two files in this skill's templates/ directory drive what you generate:

• templates/base.html — the page shell. Head, <link> to the shared stylesheet, body with toolbar, and a <script> tag that loads the widget. Each phase reuses this verbatim and fills <main> with phase-specific content.
• templates/examples.html — one fully-populated example of every affordance the shared sheet provides. Read it to see the canonical markup for a section, callout, code-ref, risk table, timeline, todo list, or inline SVG. Copy the markup pattern, swap in your content, keep the classes and attribute names unchanged.

What's already in the shared sheet (so you know when to add a scoped phase-specific <style> block and when not to):

• section.annot — the annotatable section shape, including the box the widget injects at the end
• .callout / .callout-warning / .callout-question — three callout flavors with a .label slot
• .code-ref — clickable, copyable inline code chips for file paths
• <pre><code> — multi-line code blocks
• <table class="risks"> + .pill.risk-high / .risk-med / .risk-low — the risk table and its severity pills
• <ol class="timeline"> — numbered phase cards (numbering on top-level <li> only)
• <ul class="todos"> — checkbox list for todo.html
• .grid-2 — two-column layout helper (use sparingly; not for annotation-target content)
• The hero header, sticky ToC, and toolbar all come from base.html unchanged

If a phase needs a visual element not in that list (a custom inventory table, an extra pill variant, a step strip), add it to the empty <style> block in the head — keep it short.

What the widget builds for you, so you don't have to:

• The sticky left-rail ToC auto-populates from every <section class="annot"> with an id. Don't render <ol id="toc-list"> entries by hand; just give your sections stable ids.
• The notes box at the end of each annotatable section is injected by the JS — don't include one in your markup.
• Anything outside an annotatable section (the hero's TL;DR, intro prose, an autonomous-run callout placed above the first section) won't appear in the ToC. That's fine — but if you want that content reachable from the ToC, wrap it in a <section class="annot" id="…">.

What to preserve from the scaffold, what to fill in:

• Preserve: the entire <head> (<title> aside), the <link rel="stylesheet" href=".repl-assets/style.css">, the <body> element's data-task / data-phase attributes (you'll fill those values), the <div class="layout"> wrapper, <nav class="toc">, the <div class="toolbar"> block, and the <script src=".repl-assets/ annotations.js"> tag. The widget depends on this markup unchanged.
• Fill in: the <title>, the data-task / data-phase attribute values, the <header class="hero"> crumbs / <h1> / <p class="tldr">, and all content inside <main>. If the phase genuinely needs new visual elements the shared sheet doesn't cover (e.g. a custom inventory table), add a short, scoped CSS block inside the existing <style> element in the <head>. Keep additions minimal — most pages won't need any.
• Remove: the placeholder HTML comment block inside <main> (<!-- Phase- specific sections go here... -->) before saving the file. Don't ship the scaffold's own how-to comments in the final output.

Picking data-annot-id values: use descriptive slugs derived from the section's noun phrase — migration-rollout, auth-middleware-flow, tradeoff-option-b. Avoid positional ids (section-3) because exported annotations reference these ids, and a re-ordering between turns silently breaks the link between a note and the text it was attached to.

Non-interactive mode

The phase prompts below tell you to ask the user a question or wait for the user. When this skill is invoked from an evaluation, a CI job, or any context without a live user (a parent agent driving subagents, for example), there's no one to answer.

In that case: don't try to skip the question; just make a reasonable judgment call, then write the assumption into the page itself as a callout at the top of the relevant section:

<div class="callout callout-question">
  <div class="label">Autonomous-run assumption</div>
  <p>No user was present to answer "<em>which areas should I research?</em>".
     I assumed the relevant code is X, Y, Z based on the task prompt. If a
     reviewer disagrees, they can annotate this section to redirect.</p>
</div>

This keeps the assumption visible in the artifact and annotatable, instead of buried in a chat reply that doesn't exist. Apply the same pattern any time the interactive workflow would have asked or waited.

When running non-interactively, also skip the user-facing "Transition" lines below — they assume someone will open the file and follow up.

---

Phase 1: Research

Goal: build genuine understanding, render it as a browsable HTML page the user can navigate and annotate.

Ask: "What areas of the codebase should I research for this?"

Then explore — read the actual code, not file names. Cover the files that will be touched, adjacent code, existing patterns, edge cases, tests. Quote file paths and line numbers; the HTML can render path:line as a clickable code chip that copies on click.

Structure research.html with these affordances HTML enables:

• One section per area researched, each with an id so the in-page table of contents links to it
• A sticky left-rail ToC for jumping between sections
• File/line references rendered as styled code chips — use the .code-ref class from the scaffold; the JS makes them copyable
• Callouts for open questions — use the .callout-question class
• Callouts for potential pitfalls — use the .callout-warning class
• A "research summary" hero at the top: one-paragraph TL;DR

Every section that the user might want to comment on gets a data-annot-id attribute with a stable, descriptive id (e.g. auth-middleware-flow, not section-7). Stable ids matter because exported annotations reference them, and renaming an id between turns breaks the link between the note and the text it was attached to.

Transition (interactive mode only): "Research is in tasks/{task-name}/research.html — open it in your browser, click sections to annotate, hit Export annotations when you're done. Then tell me to read them."

Wait for the user. In non-interactive mode, skip both the transition and the wait — just continue to Phase 2.

---

Phase 2: Planning

Goal: produce a detailed, annotatable HTML plan that uses every visual affordance HTML offers where it actually helps.

Ask: "Ready for the plan — anything specific about how you want this implemented?" Then write plan.html. Use the scaffold and add phase-specific content. Lean into these patterns when they fit the work (not all will — only use what genuinely helps):

Annotation-target principle: every piece of prose the user might want to comment on individually should be its own <section class="annot"> with a stable data-annot-id. Don't bundle two prose items into a side-by-side layout if a reviewer might want to react to one and not the other — the notes box attaches to the whole section, and ambiguity about which half a note refers to makes the annotation cycle worse than markdown was.

• Phased timeline as an ordered list of cards, each with an estimated size, the files it touches, and the rationale
• Data-flow or sequence diagram as inline SVG when the change involves multiple components talking to each other. Hand-author the SVG; don't reach for a library
• Risk table (<table class="risks">) with columns for risk, likelihood, mitigation. Likelihood gets a .pill .risk-high / .risk-med / .risk-low chip. Tight tabular data like this scans well and doesn't need per-row annotation
• Trade-offs as a vertical list of sections, not a side-by-side grid. Each trade-off is its own <section class="annot"> with the option considered, the choice made, and the reasoning. Side-by-side grids collapse two pieces of prose into one annotatable target, which makes the annotation cycle worse than markdown was. Lists keep each rationale individually addressable
• Before/after for refactors as stacked code blocks, not side-by-side. Same reason: when "before" and "after" are sharing a row, the user can't comment on one without comment-on-the-other ambiguity

The plan should be detailed enough that implementation becomes mechanical. Every annotatable section gets a data-annot-id.

Transition (interactive mode only): "Plan is in tasks/{task-name}/plan.html. Annotate in the browser, export, and tell me to read them."

Wait for the user. In non-interactive mode, skip both the transition and the wait.

---

Phase 3: Annotation cycle

Goal: iterate on the plan (and research, and todo, when those come back with annotations) until the user is satisfied.

The cycle:

1. User opens the relevant .html, clicks sections to add notes via the built-in widget, clicks Export annotations
2. The browser downloads {task}.{phase}.annotations.json — the user moves it next to the HTML at tasks/{task-name}/{phase}.annotations.json (or pastes the path)
3. You read the file, find each {section_id, note} pair, locate the matching data-annot-id in the HTML, update that section, and regenerate the page
4. After updating, delete or empty the annotations file so stale notes from the previous round don't re-apply. Also tell the user to click Clear in the toolbar so the browser's localStorage matches — otherwise the next export will resurrect the old notes
5. Repeat until the user exports no notes (or just tells you it's good)

Also: the checks field in the export carries todo-page checkbox state. Ignore it during the annotation cycle for research.html and plan.html; only todo.html exports use it meaningfully.

Annotation export format

The widget exports this shape — keep it stable, the JS depends on it:

{
  "task": "task-name",
  "phase": "plan",
  "exported_at": "2026-05-11T20:44:00Z",
  "annotations": [
    {
      "section_id": "auth-middleware-flow",
      "section_excerpt": "First ~120 chars of the section, for context",
      "note": "the user's note text, may be multiline"
    }
  ],
  "checks": { "todo-1": true, "todo-2": false }
}

The checks map is only populated by todo.html; for the other phases it will be present but empty.

When addressing a note:

• Update the section the note targeted. If the note disagreed with you and you stand by your call, respond in chat before changing the HTML — same rule as plan-repl's markdown notes
• Don't reword sections the user didn't annotate; minimize churn so a diff between revisions is readable
• If section_id doesn't match any current data-annot-id (because the HTML was regenerated and ids shifted), surface it: don't silently drop the note

Expect several rounds. This is the highest-leverage phase — the same as in plan-repl. The HTML widget exists to make a round faster, not to compress the number of rounds.

---

Phase 4: Task breakdown

Goal: generate todo.html from the approved plan.

The breakdown is a checkbox grid grouped by plan phase. Two design choices to lean into here:

• Checkboxes are the source of truth. The widget persists checkbox state to localStorage keyed by task name, and exports it as part of annotations.json when the user hits export. On resume, you read the exported state to figure out where implementation is — not by inferring from git
• Each task links back to the plan section it came from (via anchor links into plan.html). Cross-document linking is one of the cheap wins HTML gives you

Same structure as plan-repl: one group per plan phase, each task small enough to be a single clear change.

After generating, stop and wait for the user to sign off before implementation. Don't auto-proceed.

---

Phase 5: Implementation

Goal: execute the approved plan. Mechanical work.

Work through todo.html in order. After each task, regenerate the page with the corresponding checkbox checked (or instruct the user to check it in the browser, then export so you can read state back — either is fine, agree with the user up front which loop you're using).

Same guard rails as plan-repl:

• Don't add features that aren't in the plan
• Don't refactor surrounding code
• If you discover the plan needs to change, stop and discuss

---

Notes for evaluation (this is an experiment)

This skill exists to find out where HTML output earns its keep and where it gets in the way. While running through a real task with it, keep a running ledger — surface these to the user when relevant, not as a final report dump:

• What HTML made easier than markdown. Concrete moments: "the timeline for this 3-phase rollout was much easier to scan in HTML than as a bulleted list."
• What HTML made harder. "Regenerating the page after each annotation pass is heavier than editing a markdown file in place."
• Where the annotation widget felt awkward. Section ids that didn't survive a regeneration, notes that wanted to attach to a sub-element, the export-and-move-file dance.
• What you'd change in a v2. Be specific. "Live-saving annotations to a watched file would remove the manual export step."

The point isn't to be optimistic about the format. It's to learn fast.

---

Things not to do

• Don't treat HTML as a way to skip planning rigor. The format is prettier; the discipline is the same. A flashy timeline doesn't make up for a vague plan.
• Don't invent your own annotation UI per page. The templates/base.html scaffold ships the widget; every generated page must include it unchanged, or the export format drifts and round-trips break.
• Don't silently regenerate annotated sections you didn't touch — the user expects diffs to be reviewable. Minimize churn.
• Don't load assets over the network in generated HTML. The shared CSS and JS already sit alongside the page in .repl-assets/; anything beyond that needs to be inlined into the phase-specific <style> block. The goal is that a tasks/{task-name}/ folder can be opened on any machine with a browser and zero setup.
• Don't edit the shared .repl-assets/style.css or annotations.js inside a task folder once they've been snapshotted. Those files are the task's locked-in baseline; if behavior needs to change, update the skill's assets/ and have the user delete the task's .repl-assets/ so the next phase re-copies the new version. Editing the snapshot in place invites drift between what the SKILL.md documents and what the page actually does.
• Don't auto-suggest this skill for tasks that aren't an explicit experiment in HTML output. plan-repl is the default workflow; this is the lab variant.