make-spec — HTML design-doc scaffold (P18 Category-C)
One template + one theme + one filename convention — so the writer
spends 100% of energy on substance, 0% on boilerplate.
Why this skill exists
Since P18's promotion 2026-05-13, the workspace produces substantive
design docs as native HTML rather than markdown:
| Type |
Location |
Examples (last 7d) |
| Spec |
docs/specs/ |
2026-05-22-broker-selection-cross-asset.html, 2026-05-23-life-houston-runtime-integration.html |
| Plan |
docs/plans/ |
2026-05-22-feature-flag-design.html, 2026-05-22-houston-advanced-settings.html, 2026-05-22-houston-developer-mode.html |
| Report |
docs/reports/ |
2026-05-22-houston-dogfood-pattern.html, 2026-05-22-mission-control-vs-houston.html |
| ADR |
docs/adrs/ |
(folder reserved; pattern proven via broker-selection ADR in docs/specs/) |
| PR explainer |
docs/pr-explainers/PR-<n>.html |
(P18-reserved path) |
All 7 hand-rolled HTMLs above share the same 70-line CSS preamble:
--bg #0e1116, --ink #e7ecf2, --accent #7ec4ff, --accent-2 #b58cff,
h1-h4 with identical sizes/margins/colors, table with hover, callout
classes (warn/bad/ok/big), tag chips (info/warn/ok/bad/pick/cfd),
TOC block, footnote/cite styling.
Before this skill, every HTML doc rebuilt that boilerplate from
memory or copy-paste. The boilerplate IS the Broomva visual identity for
internal docs; centralizing it makes the visual identity stable AND
saves ~5 minutes per doc.
What this skill provides
references/theme.css — the canonical 70-line stylesheet,
verbatim from the proven specs. Reference, don't recopy.references/template-spec.html — the one shipped base
template (the spec layout). Every variant below is generated
from this base, not loaded from its own file: start from
template-spec.html, then swap the title prefix, TOC sections,
and section skeleton per the variant's section list. No separate
template-plan/adr/report/pr-explainer.html files ship — the
variants are prose skeletons applied to the spec base.
The four variants (generated, not shipped — apply to the
template-spec.html base + the canonical skeleton below):
- Plan variant — base + sub-phase table + acceptance-criteria
sections.
- ADR variant — base + Status / Context / Decision /
Consequences / Alternatives sections.
- Report variant — base + Executive summary / Findings /
Recommendations / Appendix sections.
- PR-explainer variant — base + What changed / Why / Test plan
/ Risk / Rollout sections.
When to invoke
- Substantive design doc (>100 lines OR contains ≥1 of: decision
matrix, multi-row PR table, regulatory citations, multi-stage plan).
- ADR for any architectural decision worth keeping for posterity.
- PR explainer for a substantive PR (>200 LOC OR public API OR
governance-class change — same trigger as P20's review requirement).
- Plan for any multi-week / multi-PR arc that a stakeholder will
review (not just the executor).
- Report synthesizing prior research, briefings, or post-mortems.
Carve-outs (do not invoke)
- Brief docs <100 lines → markdown is fine (P18 audience rule: the
HTML payoff doesn't justify the 2-4× generation cost on short docs).
- Agent-loaded references (SKILL.md, entity pages, AGENTS.md) →
always markdown (Category A: substrate stays markdown).
- README / CHANGELOG / docs that GitHub renders → markdown (GitHub's
markdown renderer is the audience layer).
- PR descriptions (
gh pr create --body) → markdown (GitHub renders).
- Throw-away interactive UI → use Webdesign / impeccable / arcan-glass
skills; this skill is for static design docs only.
The canonical structure
Every variant follows the same skeleton:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title><Doc type> — <Doc title></title>
<meta name="viewport" content="width=device-width,initial-scale=1">
<style>
/* paste references/theme.css verbatim */
</style>
</head>
<body>
<h1><Doc title></h1>
<p class="subtitle"><One-line summary></p>
<p class="meta">
Author: <agent | user> · Generated: YYYY-MM-DD · Status: <draft | accepted | superseded><br>
Decision-class: <span class="tag info">substantive</span> · risk-class: <span class="tag warn">…</span><br>
Upstream context: <code>…</code>
</p>
<div class="callout warn">
<strong>Verification scope</strong>. <When this doc requires
out-of-band verification before action — e.g. CPA review, legal
review, deploy approval — state it here.>
</div>
<div class="toc">
<strong>Contents</strong>
<ol>
<li><a href="#section-1">…</a></li>
</ol>
</div>
<h2 id="section-1">1. <Section title></h2>
<!-- … -->
</body>
</html>
CSS theme (load from references/theme.css)
The theme is not open for tweaking inside individual docs. The
visual identity is stable across all internal Broomva HTMLs:
- Background:
#0e1116 (the deep ink that lets the --accent
blue and --accent-2 purple read cleanly)
- Ink:
#e7ecf2 primary, #98a2b3 dim, #6b7280 muted
- Accents:
#7ec4ff (h3 + tag.info) and #b58cff (tag.pick, the
"this is the decision" highlight)
- Status colors:
#66d699 ok, #ffd166 warn, #ff7a7a bad
- Code:
#0b0f15 background; monospaced via system stack
(ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo)
- Sans:
-apple-system, "SF Pro Text", system-ui, sans-serif
To change the theme: amend references/theme.css and the change
propagates to every new doc. Existing docs are not retro-updated
(P13 stability budget — don't rewrite history for cosmetic deltas).
Tag system
The <span class="tag X">…</span> chips are the doc's status
vocabulary. Always-supported classes:
| Class |
Use |
Color |
info |
neutral metadata / classification |
--accent blue |
ok |
confirmed / passing / accepted |
--ok green |
warn |
needs verification / blocked-on-external |
--warn yellow |
bad |
rejected / failing / unsafe |
--bad red |
pick |
THE decision (uniquely highlighted) |
--accent-2 purple, bold |
cfd |
specific anti-pattern marker (synthetic exposure / not-real-ownership; from the broker-selection ADR vocabulary) |
--bad muted |
Callout system
Four callout flavors:
<div class="callout">…</div> <!-- neutral; accent border -->
<div class="callout ok">…</div> <!-- success / confirmed -->
<div class="callout warn">…</div> <!-- needs verification -->
<div class="callout bad">…</div> <!-- rejected / unsafe -->
<div class="callout big">…</div> <!-- the headline decision / TL;DR -->
File placement
| Doc type |
Path |
Filename |
| Spec |
docs/specs/ |
YYYY-MM-DD-<slug>.html |
| Plan |
docs/plans/ |
YYYY-MM-DD-<slug>.html |
| ADR |
docs/adrs/ (or docs/specs/ until the dir is canonical) |
YYYY-MM-DD-adr-<slug>.html |
| Report |
docs/reports/ |
YYYY-MM-DD-<slug>.html |
| PR explainer |
docs/pr-explainers/ |
PR-<n>.html (no date — PR number is the identifier) |
Slug names the topic, not the date. The date is the mtime.
The five anti-patterns this skill exists to prevent
| Anti-pattern |
Failure mode |
Fix |
| Rebuilding the theme inline |
70-line :root drift across docs; visual identity erodes. |
Always reference references/theme.css; don't paraphrase. |
| Markdown for a 200-line spec |
Tables don't render the way the writer pictured; ASCII pseudo-diagrams; reader bounces by line 80 (the trq212 ceiling). |
Apply the audience test: human-read substantive → HTML. |
| HTML for a 30-line note |
2-4× generation cost for no information-density payoff. |
Brief docs stay markdown. |
Title in <h1> differs from <title> |
Tab-bar text doesn't match doc heading; reader gets confused when 5 tabs open. |
Keep <title> and <h1> in sync; <title> adds the doc-type prefix ("ADR — …"). |
No meta line |
Reader can't tell author / date / status / risk-class without skimming. |
The <p class="meta"> line is mandatory: author + date + status + risk + upstream context. |
Composition rules
| Compose with |
When |
bookkeeping render |
NEVER for native HTML — bookkeeping render is for Category-B (MD canonical → HTML projection). This skill produces Category-C natives. They're disjoint per P18. |
handoff |
A handoff is markdown (agent-loaded) but may link to a make-spec HTML companion when the arc warrants. Handoff stays MD; companion is HTML. |
autonomous |
When /autonomous is mid-arc and a substantive plan emerges, fork the plan into docs/plans/<slug>.html via this skill, then continue execution. |
Webdesign / impeccable / arcan-glass |
Disjoint — those are for product-surface UI; this is for internal design docs. |
Validation (spec self-test)
References
- Canonical theme source:
docs/specs/2026-05-22-broker-selection-cross-asset.html lines 8–71 (extracted into references/theme.css)
- P18 audience rule:
CLAUDE.md §P18 + AGENTS.md §P18
- trq212 thesis: The Unreasonable Effectiveness of HTML (May 2026, Claude Code team) — the empirical case behind P18
- Related skills:
bookkeeping (Category-B render), handoff (companion MD artifact), Webdesign (product UI, disjoint)
1---2name: make-spec3description: Scaffold a substantive human-readable design doc (spec / plan / ADR / report / PR explainer) as native HTML using the workspace's canonical Broomva dark theme. Implements P18 (Format-Follows-Audience) for Category-C native artifacts — distinct from `bookkeeping render`, which projects Category-B markdown canonicals to HTML. Use when: (1) drafting a substantive design doc a human will actually read (>100 lines OR contains tables/diagrams/decision matrices), (2) writing an ADR (architectural decision record), (3) producing a plan a non-agent stakeholder will review, (4) writing a PR explainer for a substantive PR, (5) producing a report that synthesizes prior research. The skill ships theme.css + the spec HTML template, and generates the plan / adr / report / pr-explainer variants from that same theme + the prose skeletons below — so the agent doesn't rebuild the 70-line :root + h1-h4 + table + callout boilerplate every time. Triggers on "spec", "plan", "ADR", "decision record", "design doc", "explainer", "repo4---56# make-spec — HTML design-doc scaffold (P18 Category-C)78**One template + one theme + one filename convention — so the writer9spends 100% of energy on substance, 0% on boilerplate.**1011## Why this skill exists1213Since P18's promotion 2026-05-13, the workspace produces substantive14design docs as native HTML rather than markdown:1516| Type | Location | Examples (last 7d) |17|---|---|---|18| Spec | `docs/specs/` | `2026-05-22-broker-selection-cross-asset.html`, `2026-05-23-life-houston-runtime-integration.html` |19| Plan | `docs/plans/` | `2026-05-22-feature-flag-design.html`, `2026-05-22-houston-advanced-settings.html`, `2026-05-22-houston-developer-mode.html` |20| Report | `docs/reports/` | `2026-05-22-houston-dogfood-pattern.html`, `2026-05-22-mission-control-vs-houston.html` |21| ADR | `docs/adrs/` | (folder reserved; pattern proven via broker-selection ADR in `docs/specs/`) |22| PR explainer | `docs/pr-explainers/PR-<n>.html` | (P18-reserved path) |2324All 7 hand-rolled HTMLs above share the same 70-line CSS preamble:25`--bg #0e1116`, `--ink #e7ecf2`, `--accent #7ec4ff`, `--accent-2 #b58cff`,26h1-h4 with identical sizes/margins/colors, table with hover, callout27classes (warn/bad/ok/big), tag chips (info/warn/ok/bad/pick/cfd),28TOC block, footnote/cite styling.2930Before this skill, every HTML doc rebuilt that boilerplate from31memory or copy-paste. The boilerplate IS the Broomva visual identity for32internal docs; centralizing it makes the visual identity stable AND33saves ~5 minutes per doc.3435## What this skill provides36371. **`references/theme.css`** — the canonical 70-line stylesheet,38 verbatim from the proven specs. Reference, don't recopy.392. **`references/template-spec.html`** — the one shipped base40 template (the spec layout). Every variant below is **generated41 from this base**, not loaded from its own file: start from42 `template-spec.html`, then swap the title prefix, TOC sections,43 and section skeleton per the variant's section list. No separate44 `template-plan/adr/report/pr-explainer.html` files ship — the45 variants are prose skeletons applied to the spec base.4647The four variants (generated, not shipped — apply to the48`template-spec.html` base + the canonical skeleton below):49503. **Plan variant** — base + sub-phase table + acceptance-criteria51 sections.524. **ADR variant** — base + Status / Context / Decision /53 Consequences / Alternatives sections.545. **Report variant** — base + Executive summary / Findings /55 Recommendations / Appendix sections.566. **PR-explainer variant** — base + What changed / Why / Test plan57 / Risk / Rollout sections.5859## When to invoke6061- **Substantive design doc** (>100 lines OR contains ≥1 of: decision62 matrix, multi-row PR table, regulatory citations, multi-stage plan).63- **ADR** for any architectural decision worth keeping for posterity.64- **PR explainer** for a substantive PR (>200 LOC OR public API OR65 governance-class change — same trigger as P20's review requirement).66- **Plan** for any multi-week / multi-PR arc that a stakeholder will67 review (not just the executor).68- **Report** synthesizing prior research, briefings, or post-mortems.6970## Carve-outs (do not invoke)7172- Brief docs <100 lines → markdown is fine (P18 audience rule: the73 HTML payoff doesn't justify the 2-4× generation cost on short docs).74- Agent-loaded references (SKILL.md, entity pages, AGENTS.md) →75 always markdown (Category A: substrate stays markdown).76- README / CHANGELOG / docs that GitHub renders → markdown (GitHub's77 markdown renderer is the audience layer).78- PR descriptions (`gh pr create --body`) → markdown (GitHub renders).79- Throw-away interactive UI → use Webdesign / impeccable / arcan-glass80 skills; this skill is for static design docs only.8182## The canonical structure8384Every variant follows the same skeleton:8586```html87<!doctype html>88<html lang="en">89<head>90 <meta charset="utf-8">91 <title><Doc type> — <Doc title></title>92 <meta name="viewport" content="width=device-width,initial-scale=1">93 <style>94 /* paste references/theme.css verbatim */95 </style>96</head>97<body>98 <h1><Doc title></h1>99 <p class="subtitle"><One-line summary></p>100 <p class="meta">101 Author: <agent | user> · Generated: YYYY-MM-DD · Status: <draft | accepted | superseded><br>102 Decision-class: <span class="tag info">substantive</span> · risk-class: <span class="tag warn">…</span><br>103 Upstream context: <code>…</code>104 </p>105106 <div class="callout warn">107 <strong>Verification scope</strong>. <When this doc requires108 out-of-band verification before action — e.g. CPA review, legal109 review, deploy approval — state it here.>110 </div>111112 <div class="toc">113 <strong>Contents</strong>114 <ol>115 <li><a href="#section-1">…</a></li>116 </ol>117 </div>118119 <h2 id="section-1">1. <Section title></h2>120 <!-- … -->121</body>122</html>123```124125## CSS theme (load from `references/theme.css`)126127The theme is **not** open for tweaking inside individual docs. The128visual identity is stable across all internal Broomva HTMLs:129130- **Background**: `#0e1116` (the deep ink that lets the `--accent`131 blue and `--accent-2` purple read cleanly)132- **Ink**: `#e7ecf2` primary, `#98a2b3` dim, `#6b7280` muted133- **Accents**: `#7ec4ff` (h3 + tag.info) and `#b58cff` (tag.pick, the134 "this is the decision" highlight)135- **Status colors**: `#66d699` ok, `#ffd166` warn, `#ff7a7a` bad136- **Code**: `#0b0f15` background; monospaced via system stack137 (`ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo`)138- **Sans**: `-apple-system, "SF Pro Text", system-ui, sans-serif`139140To change the theme: amend `references/theme.css` and the change141propagates to every new doc. Existing docs are not retro-updated142(P13 stability budget — don't rewrite history for cosmetic deltas).143144## Tag system145146The `<span class="tag X">…</span>` chips are the doc's status147vocabulary. Always-supported classes:148149| Class | Use | Color |150|---|---|---|151| `info` | neutral metadata / classification | `--accent` blue |152| `ok` | confirmed / passing / accepted | `--ok` green |153| `warn` | needs verification / blocked-on-external | `--warn` yellow |154| `bad` | rejected / failing / unsafe | `--bad` red |155| `pick` | THE decision (uniquely highlighted) | `--accent-2` purple, bold |156| `cfd` | specific anti-pattern marker (synthetic exposure / not-real-ownership; from the broker-selection ADR vocabulary) | `--bad` muted |157158## Callout system159160Four callout flavors:161162```html163<div class="callout">…</div> <!-- neutral; accent border -->164<div class="callout ok">…</div> <!-- success / confirmed -->165<div class="callout warn">…</div> <!-- needs verification -->166<div class="callout bad">…</div> <!-- rejected / unsafe -->167<div class="callout big">…</div> <!-- the headline decision / TL;DR -->168```169170## File placement171172| Doc type | Path | Filename |173|---|---|---|174| Spec | `docs/specs/` | `YYYY-MM-DD-<slug>.html` |175| Plan | `docs/plans/` | `YYYY-MM-DD-<slug>.html` |176| ADR | `docs/adrs/` (or `docs/specs/` until the dir is canonical) | `YYYY-MM-DD-adr-<slug>.html` |177| Report | `docs/reports/` | `YYYY-MM-DD-<slug>.html` |178| PR explainer | `docs/pr-explainers/` | `PR-<n>.html` (no date — PR number is the identifier) |179180Slug names the **topic**, not the date. The date is the mtime.181182## The five anti-patterns this skill exists to prevent183184| Anti-pattern | Failure mode | Fix |185|---|---|---|186| **Rebuilding the theme inline** | 70-line :root drift across docs; visual identity erodes. | Always reference `references/theme.css`; don't paraphrase. |187| **Markdown for a 200-line spec** | Tables don't render the way the writer pictured; ASCII pseudo-diagrams; reader bounces by line 80 (the trq212 ceiling). | Apply the audience test: human-read substantive → HTML. |188| **HTML for a 30-line note** | 2-4× generation cost for no information-density payoff. | Brief docs stay markdown. |189| **Title in `<h1>` differs from `<title>`** | Tab-bar text doesn't match doc heading; reader gets confused when 5 tabs open. | Keep `<title>` and `<h1>` in sync; `<title>` adds the doc-type prefix (`"ADR — …"`). |190| **No `meta` line** | Reader can't tell author / date / status / risk-class without skimming. | The `<p class="meta">` line is mandatory: author + date + status + risk + upstream context. |191192## Composition rules193194| Compose with | When |195|---|---|196| **`bookkeeping render`** | NEVER for native HTML — `bookkeeping render` is for Category-B (MD canonical → HTML projection). This skill produces Category-C natives. They're disjoint per P18. |197| **`handoff`** | A handoff is markdown (agent-loaded) but may *link to* a make-spec HTML companion when the arc warrants. Handoff stays MD; companion is HTML. |198| **`autonomous`** | When `/autonomous` is mid-arc and a substantive plan emerges, fork the plan into `docs/plans/<slug>.html` via this skill, then continue execution. |199| **`Webdesign` / `impeccable` / `arcan-glass`** | Disjoint — those are for product-surface UI; this is for internal design docs. |200201## Validation (spec self-test)202203- [ ] `<title>` and `<h1>` match (with doc-type prefix on `<title>`)204- [ ] `<p class="meta">` line present with author + date + status + risk205- [ ] Theme CSS is the `references/theme.css` content verbatim (or `<link>` to it if hosted) — no inline drift206- [ ] At least one `<div class="toc">` if the doc has ≥4 H2 sections207- [ ] All `tag` chips use one of the six canonical classes (info/ok/warn/bad/pick/cfd)208- [ ] Filename matches `YYYY-MM-DD-<slug>.html` (date = mtime, slug = topic)209210## References211212- Canonical theme source: `docs/specs/2026-05-22-broker-selection-cross-asset.html` lines 8–71 (extracted into `references/theme.css`)213- P18 audience rule: `CLAUDE.md` §P18 + `AGENTS.md` §P18214- trq212 thesis: *The Unreasonable Effectiveness of HTML* (May 2026, Claude Code team) — the empirical case behind P18215- Related skills: `bookkeeping` (Category-B render), `handoff` (companion MD artifact), `Webdesign` (product UI, disjoint)
broomva