spechtml

spechtml

Use this skill to keep human-facing documents and LLM-facing inputs in sync.

The human never runs commands. Write files and execute scripts yourself.

Quick Reference: Abbreviation Table

Memorize these abbreviations before generating any TOON.

short	canonical	context
t	title	doc, section, reqs, steps
k	kind	doc
p	priority	reqs
s	status	reqs, decisions
s	state	steps (timeline only)
d	description	reqs
cat	category	components
rec	recommendation	decisions

code	canonical
M	must
S	should
C	could
A	accepted
P	planned
B	blocked
D	done

Important: s means status in reqs/decisions, but means state in steps/timeline. When ambiguity is possible, use the canonical form status or state.

Core Rule

Do not make HTML the source of truth.
Use Compact TOON for LLM exchange.
Use HTML/Markdown as human views.
Use TOON patch for edits.

• Never edit generated HTML directly.
• Never feed generated HTML back to the LLM unless visual layout is the task.
• Always keep Compact TOON as the editable source of truth.

New Document Workflow

When the user asks to create a document:

1. Choose block types based on content (see Block Selection Guide).
2. Construct Compact TOON using the spechtml-v1 profile.
3. Write the TOON to a file (e.g., docs/spec.compact.toon).
4. Execute the renderer immediately:

node ${CLAUDE_SKILL_DIR}/runtime/dist/cli.bundle.js docs/spec.compact.toon dist/spec.html

5. Tell the user: "Generated dist/spec.html. Open it in a browser and let me know if you want to edit anything by its id number."

What the human sees

The generated HTML has visible reference IDs (id10, id11, ...) on every section, block, and row. The human reads the HTML and can say:

id10 を初心者向けに書き直して

They never need to touch a terminal.

Edit Workflow

When the human asks for changes by visible id:

Step 1 — Resolve id to data-path

Read the generated HTML file and find the data-ref and data-path attributes:

<div data-ref="id10" data-stable-id="dd9ec098" data-path="/stack/components/name=Tokio">

The key field is data-path. For this id10, the path is /stack/components/name=Tokio.

Step 2 — Write a TOON patch file

meta:
  pf: spechtml-patch-v1
  v: 1
  target: docs/spec.compact.toon
  target_hash: sha256:<sha256 of docs/spec.compact.toon>

replace[1|]{path|value}:
  /stack/components/name=Tokio/purpose|Rustの非同期処理を動かすための実行基盤

target_hash is required. Compute it from the current source file (e.g. Get-FileHash -Algorithm SHA256 on Windows, shasum -a 256 on POSIX). The applier will refuse the patch if the hash does not match.

Write it to docs/spec.patch.toon.

Step 3 — Apply the patch and re-render

node ${CLAUDE_SKILL_DIR}/runtime/dist/apply-toon-patch.bundle.js docs/spec.compact.toon docs/spec.patch.toon
node ${CLAUDE_SKILL_DIR}/runtime/dist/cli.bundle.js docs/spec.compact.toon dist/spec.html

The patch is applied in-place. The applier overwrites the source file, so no third argument is accepted.

Step 4 — Tell the human

"Updated id10 in dist/spec.html. Refresh the page to see the change."

What NOT to do

• Do NOT edit the HTML file directly.
• Do NOT regenerate the entire TOON for a single field change.
• Do NOT ask the human to run commands.

Human Feedback Loop — All Variants

Human says	Action
"id10 をもっと平易に"	replace the field at id10's data-path
"id10 の後に新しい項目を追加"	append to the table containing id10
"id10 と id12 の間に新しい行を入れて"	insert with the index between id10 and id12 (v0.4)
"id10 を削除"	remove the row at id10's data-path
"id5 の優先度を must に"	replace the priority/status field
"新しいセクションを追加"	add_section with key, index, and body (v0.4)

For any edit, always: write patch → apply in-place → re-render → notify human.

Block Selection Guide

Templates exist as reference examples only. The primary workflow is to select blocks based on content.

Block Catalog

Each block maps to a specific semantic need. Learn all of them.

Block	TOON syntax	When to use	Example
note	note: text	Short prose, background, summary, conclusion (1-3 sentences)	note: TOONは人間とLLMの中間表現として使うフォーマット。
prose	prose: text	Long-form explanation, narrative context	prose: この設計判断の背景には...
metrics	metrics[N|]{label|value|caption}:	Key values, design targets, KPI summary	Throughput, SLA, team size
reqs	reqs[N|]{id|p|s|t|d}:	Requirements, constraints, cautions, action items	R1|M|A|制約|理由
decisions	decisions[N|]{id|option|score|tradeoff|recommend}:	Options, tradeoffs, recommendations	D1|方式A|8|tradeoff|理由
components	components[N|]{name|cat|purpose|note}:	Concepts, parts, API elements, terms, catalog	Json<T>|extractor|用途|補足
steps	steps[N|]{step|state|detail}:	Ordered process, timeline, workflow, operation log	request到着|done|説明
nodes+edges	nodes[N|]{id|label|kind}: + edges[N|]{from|to|label}:	Flowchart, data flow, architecture diagram	kinds: input/process/output/event/decision
notes	notes[N|]{file|line|concept|note}:	Code annotations, inline explanations	src/main.rs|42|handler|説明
snippets	snippets[N|]{lang|path|lines|code}:	Code examples with file reference and line numbers	rust|src/main.rs|1-10|fn main() {
controls	controls[N|]{id|label|kind|min|max|step|value|options}:	Interactive sliders, toggles, selects	kinds: slider/toggle/select
relations	relations[N|]{from|to|type}:	Cross-references between requirements, decisions, etc.	reqs/C1|decisions/D1|addresses

Decision Flow

What is the content?

  Structured data (rows with consistent fields)?
    → Component/API list?            → components
    → Requirements/constraints?      → reqs
    → Options with tradeoffs?        → decisions
    → Ordered steps/timeline?        → steps
    → Code annotations?              → notes
    → Cross-block references?        → relations

  Short text (1-3 sentences)?
    → note

  Long text (paragraphs)?
    → prose

  Key-value metrics?
    → metrics

  Flow/diagram?
    → nodes + edges (Mermaid)

  Code to display?
    → snippets (with path/lines/lang)

  User-configurable parameters?
    → controls

Composition Patterns by Document Type

These are patterns, not templates. Select blocks from the catalog above.

Document type	Primary blocks	Secondary blocks
API specification	components, reqs, snippets	decisions, notes, metrics
Architecture Decision Record	decisions, prose, relations	reqs, metrics
Incident report	steps, metrics, prose	components, reqs
Learning material	prose, snippets, components	nodes+edges, notes, controls
Code review	reqs, notes, snippets	decisions, prose

No document type requires all blocks. Use only what the content demands.

Natural Prose And Code

Do not force everything into tables.

Use:

• note for short prose, background, summaries
• components, reqs, decisions, steps for structured content
• notes for code explanations
• prose for narrative + inline code fences (v0.3.1+)
• File reference (file + lines) for long code instead of embedding full code

For long code, prefer a file reference:

notes[1|]{file|line|concept|note}:
  src/main.rs|42-58|handler|async fn handler(...) -> impl IntoResponse

Code blocks inside prose (v0.3.1+)

prose accepts triple-backtick fences. The HTML renderer turns them into <pre><code class="language-...">. Other Markdown syntax (bold, links, tables) is left as plain text.

Write prose as a \n-escaped quoted string (TOON SPEC v3 has no YAML-style block scalar). Example:

prose: "実装はこんな感じ。\n\n```python\ndef hello():\n    print('hi')\n```\n\n以上。"

Render outputs:

• HTML: <p>実装はこんな感じ。</p><pre><code class="language-python">def hello():\n print('hi')</code></pre><p>以上。</p>
• Markdown: the fence is passed through as a Markdown code fence

Use prose + fence for "narrative with code". Use snippets for "standalone code references" (the path / lines / lang metadata is preserved as a Copy-able block).

Markdown round-trip workflow (v0.3.1+)

When team members want to edit the document via the Markdown view:

1. Generate spec.md from spec.compact.toon with cli-md.bundle.js
2. Commit spec.md to the repo, share with team
3. Reviewer edits spec.md directly and commits the diff
4. Owner asks the LLM: "apply this Markdown diff to spec.compact.toon"
5. LLM produces a TOON patch (replace / append / insert / remove / add_section) targeting the right path
6. apply-toon-patch.bundle.js applies the patch in place; target_hash rejects stale patches
7. Re-render to confirm the round-trip is consistent

Do not machine-reverse Markdown to TOON: spechtml-v1 metadata (reqs ids, decisions scores, relations) does not survive a generic md→toon parse. The LLM-mediated patch path is the safe one.

Markdown round-trip — strict procedure (v0.3.2+)

When the human says any of the trigger phrases below, the LLM must follow the 5 numbered steps in order. Do not improvise the procedure. A verified golden sample lives at plugin/skills/spechtml/examples/md-roundtrip/.

Trigger phrases

• "Markdown を反映"
• "MD diff を反映"
• "レビュー後 MD を TOON に戻す"
• "apply this Markdown diff to "

Step-by-step procedure

1. Extract the diff with the helper:

   node ${CLAUDE_SKILL_DIR}/scripts/md-diff-helper.mjs <before.md> <after.md>
   

   The output is JSON: { changes: [{ kind, before_line, after_line, context_before, before, after, context_after }, ...] }. Use context_before / context_after to map each change to a TOON section / block.

2. Map each change to a TOON path:

   • prose-style change (changed line is part of a paragraph) → replace /section/prose
   • new prose paragraph → still replace /section/prose (re-emit the whole prose string)
   • structured-block row added → append or insert on /section/<block>
   • structured-block row removed → remove on /section/<block>/id=...
   • new section appeared in MD → add_section
   • section removed in MD → remove /<section_key> If context_before / context_after do not uniquely identify a path, ask the human for clarification rather than guessing.

3. Compute target_hash from the current TOON source:

   node -e "import('node:crypto').then(c => import('node:fs').then(f => process.stdout.write('sha256:' + c.createHash('sha256').update(f.readFileSync('<source.toon>')).digest('hex'))))"
   

4. Write the patch.toon with all required meta fields and the chosen ops, then apply:

   node ${CLAUDE_SKILL_DIR}/runtime/dist/apply-toon-patch.bundle.js <source.toon> <patch.toon>
   

   If the applier rejects with Path segment does not exist, look at the Did you mean hint and retry with the corrected path.

5. Verify the round-trip:

   node ${CLAUDE_SKILL_DIR}/runtime/dist/cli-md.bundle.js <source.toon> <re-rendered.md>
   diff <after.md> <re-rendered.md>
   

   Exit code 0 means the round-trip is lossless. Non-zero means structural / formatting differences exist; ask the human whether to accept or refine.

Failure branches

• Path does not exist: do not invent. Ask the human to point at the visible id or section.
• Multiple changes that overlap a single prose: collapse into one replace op on the whole /section/prose.
• Diff includes formatting-only changes (e.g. table column reorder): clarify with the human; this often means a structural patch (replace of the entire block) rather than per-row ops.
• target_hash mismatch: the source has changed since the MD was generated. Refuse the patch, regenerate the MD, ask the team member to re-edit.

Reproducibility guarantee

If the procedure above is followed exactly, a verified-clean round-trip yields a diff of zero lines. Four golden samples ship with the plugin:

• examples/md-roundtrip/ — prose-text edit (replace on /section/prose)
• examples/md-roundtrip-structural/01-row-add/ — table row added (append)
• examples/md-roundtrip-structural/02-row-remove/ — table row removed (remove)
• examples/md-roundtrip-structural/03-section-add/ — top-level section added (add_section)

Any deviation from diff exit 0 indicates either an LLM judgement error or a structural change that the procedure deliberately surfaces to the human.

Common Pitfalls

Pitfall 1: Editing generated HTML

Wrong: Open dist/spec.html, edit text. Right: Write a TOON patch, apply it in-place, re-render. Why: HTML is not the source of truth. Edits to HTML will be lost on re-render.

Pitfall 2: Full TOON regeneration for a small change

Wrong: When the human says "fix id10", regenerate the entire TOON. Right: Write a 3-line patch targeting the specific data-path. Why: Full regeneration wastes tokens and risks unintended changes.

Pitfall 3: Using the wrong s abbreviation

Wrong: Writing s: D in a requirement row. Right: For reqs/decisions, s = status (A/P/B/D). For steps, use canonical state. Why: Context-dependent ambiguity causes validation errors.

Pitfall 4: Omitting meta.profile

Wrong: Starting a TOON document without meta: pf: spechtml-v1. Right: Always include the meta block. Why: The renderer may not recognize the compact format without it.

Pitfall 5: Asking the human to run commands

Wrong: "Run node src/cli.js ... to render." Right: Execute the command yourself with the Bash tool. Why: The human's role is to read output and give instructions, nothing else.

Verification Checklist

Before executing a render or patch:

1. [ ] Path syntax: Starts with /, uses / separators, row selectors use = (e.g., /section/table/name=Tokio)
2. [ ] Abbreviations correct: t not title, p not prio, s not state (in reqs context)
3. [ ] Enum codes valid: Priority is M/S/C, Status is A/P/B/D
4. [ ] Array sizes match: replace[N|]{fields} — N must equal the number of rows that follow
5. [ ] Patch applies in-place: apply-toon-patch.js output goes to the same file as source

References

Read only what is needed:

• references/profile-v1.md: Full abbreviation table, all standard block schemas.
• references/patch-format.md: TOON patch format, path rules, operation reference.
• references/workflow.md: End-to-end behavior for human/LLM document loops.

Scripts

All paths use ${CLAUDE_SKILL_DIR}/runtime/dist/. Execute them yourself — do not tell the human to run them. The runtime is shipped as standalone Node bundles, so no npm install or NODE_PATH is needed.

All input and output paths must be relative to the human's current working directory and must end in the expected extension (.toon for inputs, .html/.md for outputs). Paths that escape the working directory (.., absolute paths outside cwd) are rejected.

Validate a TOON file before rendering:

node ${CLAUDE_SKILL_DIR}/runtime/dist/validate-toon.bundle.js <input.toon>

Render Compact TOON to HTML:

node ${CLAUDE_SKILL_DIR}/runtime/dist/cli.bundle.js <input.toon> <output.html>

Render Compact TOON to Markdown:

node ${CLAUDE_SKILL_DIR}/runtime/dist/cli-md.bundle.js <input.toon> <output.md>

Apply a TOON patch (in-place — output goes back to the source file):

node ${CLAUDE_SKILL_DIR}/runtime/dist/apply-toon-patch.bundle.js <source.toon> <patch.toon>

The patch must declare meta.target (matching the source path's basename or relative form) and meta.target_hash (SHA-256 of the source file). The applier verifies both before writing.