spec-doc

Stop refining big plans in a chat thread. Refine them in a document you can mark up.

spec-doc is a Claude Code skill that turns a design / architecture / product decision into a served, visually-communicative HTML spec with a Notion-style margin-comment system. Claude writes the plan as a real doc; you open it in the browser, select any line, and comment; Claude reads your notes, amends the spec, replies inline, and resolves — looping until the plan is right.

---

Why

The default way to plan a large feature with Claude is a long chat thread. A thread is a terrible surface for a plan:

• it scrolls away — there's no durable artifact at the end,
• you can't point at "this paragraph, change it" — you re-describe what you mean,
• and the structure (the diagrams, the trade-offs, the open questions) lives in your head, not on the page.

spec-doc makes the plan a reviewable object. Claude drafts it as a designed document — masthead, thesis, before/after diagrams, a tech-spec table, risks, a roadmap, open questions. You mark up the exact lines you disagree with. Claude revises, replies on the thread, and marks it resolved. The conversation lives on the document, persisted to disk, until you're both happy.

It's the difference between editing a contract by voice memo and editing it with tracked changes.

What you get

• A served HTML spec — an editorial design system (hand-built HTML/CSS/SVG charts, zero chart libraries) so the doc makes the argument visually, not just in prose.
• Margin comments — select text → ⌘/Ctrl+M → comment. Reply, edit, resolve; resolved threads tuck into a drawer. Everything persists to comments.json.
• Zero dependencies — the whole engine is Python stdlib (http.server) + vanilla JS. No npm, no pip, nothing to install or audit.
• A verification pass baked into the skill — Claude checks the page renders, the comment API round-trips, and comments actually anchor to the right text before handing it to you.

Install

Option A — copy the skill (works instantly):

git clone https://github.com/tim-win/spec-doc
cp -r spec-doc/skills/spec-doc ~/.claude/skills/

Then in Claude Code, just ask — "spin this up as a spec doc" — or invoke it directly with /spec-doc.

Option B — install as a plugin (one command in Claude Code):

/plugin marketplace add tim-win/spec-doc
/plugin install spec-doc@spec-doc

Try the demo

The example doc in this repo (a passwordless-auth spec for a fictional product) is fully runnable — it's the same doc in the GIF above:

cd spec-doc/examples/passkey-auth
python3 serve.py 8801
# open http://localhost:8801 — select text and hit ⌘/Ctrl+M

How it works

The skill bundles a tiny engine and a designed template. Claude's job is to author your content; the engine and the look come for free.

spec-doc/
├── skills/spec-doc/
│   ├── SKILL.md              # the procedure Claude follows
│   └── assets/
│       ├── serve.py          # zero-dep static server + JSON comment API
│       ├── app.js            # the margin-comment system (selection anchoring, threads, resolve)
│       └── template.html     # design system + a complete worked example to start from
├── examples/passkey-auth/    # the runnable demo doc from the GIF
├── docs/demo.gif
└── .claude-plugin/marketplace.json

1. Claude copies the engine into a folder for your doc and replaces the template's worked example with your spec.
2. It starts the server and runs its own verification pass.
3. You review in the browser and leave comments.
4. Claude reads comments.json, amends the doc, replies on each thread as it goes, and resolves them — looping until you're satisfied.

Philosophy

A good skill encodes a way of working, not just a prompt. This one encodes a belief: the hard part of a big feature is the thinking, and thinking is better done against a durable, markup-able artifact than against a scrolling chat. Make the plan a thing you can point at, and the iteration gets sharp.

License

MIT. Built as a Claude Code skill; the comment engine is plain Python + JS you can lift into anything.