owflow 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (195) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +448 -283
  3. package/dist/agents/bottleneck-analyzer.md +332 -333
  4. package/dist/agents/code-quality-pragmatist.md +353 -354
  5. package/dist/agents/code-reviewer.md +238 -239
  6. package/dist/agents/codebase-analysis-reporter.md +245 -246
  7. package/dist/agents/docs-operator.md +22 -23
  8. package/dist/agents/e2e-test-verifier.md +447 -448
  9. package/dist/agents/gap-analyzer.md +501 -502
  10. package/dist/agents/implementation-completeness-checker.md +219 -220
  11. package/dist/agents/implementation-planner.md +308 -309
  12. package/dist/agents/information-gatherer.md +690 -691
  13. package/dist/agents/production-readiness-checker.md +278 -279
  14. package/dist/agents/project-analyzer.md +403 -403
  15. package/dist/agents/reality-assessor.md +365 -366
  16. package/dist/agents/research-planner.md +449 -450
  17. package/dist/agents/research-synthesizer.md +402 -403
  18. package/dist/agents/solution-brainstormer.md +256 -257
  19. package/dist/agents/solution-designer.md +371 -372
  20. package/dist/agents/spec-auditor.md +297 -298
  21. package/dist/agents/specification-creator.md +333 -334
  22. package/dist/agents/task-classifier.md +449 -450
  23. package/dist/agents/task-group-implementer.md +283 -284
  24. package/dist/agents/test-suite-runner.md +194 -195
  25. package/dist/agents/user-docs-generator.md +508 -509
  26. package/dist/commands/reviews-code.md +90 -90
  27. package/dist/commands/reviews-pragmatic.md +99 -99
  28. package/dist/commands/reviews-production-readiness.md +113 -113
  29. package/dist/commands/reviews-reality-check.md +110 -110
  30. package/dist/commands/reviews-spec-audit.md +114 -114
  31. package/dist/commands/work.md +280 -280
  32. package/dist/configuration/agents-config.d.ts +2 -0
  33. package/dist/configuration/agents-config.js +8 -44
  34. package/dist/configuration/commands-config.d.ts +23 -0
  35. package/dist/configuration/commands-config.js +17 -17
  36. package/dist/configuration/skills-config.d.ts +2 -0
  37. package/dist/configuration/skills-config.js +3 -3
  38. package/dist/hooks/hooks-diagnostics.d.ts +3 -0
  39. package/dist/hooks/hooks-diagnostics.js +21 -0
  40. package/dist/hooks/hooks-persistence.d.ts +17 -0
  41. package/dist/hooks/hooks-persistence.js +207 -0
  42. package/dist/hooks/hooks-registry.d.ts +6 -0
  43. package/dist/hooks/hooks-registry.js +104 -0
  44. package/dist/hooks/hooks-wrapper.d.ts +25 -0
  45. package/dist/hooks/hooks-wrapper.js +318 -0
  46. package/dist/hooks/internal/before-tool.d.ts +6 -0
  47. package/dist/hooks/internal/before-tool.js +13 -0
  48. package/dist/hooks/internal/session-compaction.d.ts +9 -0
  49. package/dist/hooks/{session-compaction.js → internal/session-compaction.js} +9 -7
  50. package/dist/hooks/runtime/circuit-breaker.d.ts +23 -0
  51. package/dist/hooks/runtime/circuit-breaker.js +39 -0
  52. package/dist/hooks/runtime/failure-policy.d.ts +15 -0
  53. package/dist/hooks/runtime/failure-policy.js +49 -0
  54. package/dist/hooks/runtime/process-executor.d.ts +33 -0
  55. package/dist/hooks/runtime/process-executor.js +147 -0
  56. package/dist/hooks/runtime/status-recorder.d.ts +27 -0
  57. package/dist/hooks/runtime/status-recorder.js +111 -0
  58. package/dist/index.d.ts +7 -0
  59. package/dist/index.js +111 -40
  60. package/dist/skills/agents-md-generator/SKILL.md +223 -223
  61. package/dist/skills/codebase-analyzer/SKILL.md +162 -162
  62. package/dist/skills/codebase-analyzer/references/code-analysis.md +63 -63
  63. package/dist/skills/codebase-analyzer/references/combined.md +31 -31
  64. package/dist/skills/codebase-analyzer/references/context-discovery.md +63 -63
  65. package/dist/skills/codebase-analyzer/references/file-discovery.md +51 -51
  66. package/dist/skills/codebase-analyzer/references/migration-target.md +23 -23
  67. package/dist/skills/codebase-analyzer/references/pattern-mining.md +22 -22
  68. package/dist/skills/dev-analyze/SKILL.md +115 -115
  69. package/dist/skills/dev-bugfix/SKILL.md +452 -452
  70. package/dist/skills/dev-finalize/SKILL.md +118 -118
  71. package/dist/skills/dev-implement/SKILL.md +167 -167
  72. package/dist/skills/dev-plan/SKILL.md +147 -147
  73. package/dist/skills/dev-spec/SKILL.md +182 -182
  74. package/dist/skills/dev-tdd-red/SKILL.md +94 -94
  75. package/dist/skills/dev-verify/SKILL.md +153 -153
  76. package/dist/skills/development/SKILL.md +260 -260
  77. package/dist/skills/diagrams-mermaid/SKILL.md +183 -159
  78. package/dist/skills/diagrams-mermaid/references/reference.md +220 -148
  79. package/dist/skills/docs-manager/SKILL.md +379 -379
  80. package/dist/skills/docs-manager/docs/INDEX.md +199 -199
  81. package/dist/skills/docs-manager/docs/standards/backend/api.md +25 -25
  82. package/dist/skills/docs-manager/docs/standards/backend/migrations.md +22 -22
  83. package/dist/skills/docs-manager/docs/standards/backend/models.md +25 -25
  84. package/dist/skills/docs-manager/docs/standards/backend/queries.md +22 -22
  85. package/dist/skills/docs-manager/docs/standards/frontend/accessibility.md +25 -25
  86. package/dist/skills/docs-manager/docs/standards/frontend/components.md +28 -28
  87. package/dist/skills/docs-manager/docs/standards/frontend/css.md +16 -16
  88. package/dist/skills/docs-manager/docs/standards/frontend/responsive.md +28 -28
  89. package/dist/skills/docs-manager/docs/standards/global/coding-style.md +25 -25
  90. package/dist/skills/docs-manager/docs/standards/global/commenting.md +10 -10
  91. package/dist/skills/docs-manager/docs/standards/global/conventions.md +31 -31
  92. package/dist/skills/docs-manager/docs/standards/global/error-handling.md +22 -22
  93. package/dist/skills/docs-manager/docs/standards/global/minimal-implementation.md +22 -22
  94. package/dist/skills/docs-manager/docs/standards/global/validation.md +28 -28
  95. package/dist/skills/docs-manager/docs/standards/testing/test-writing.md +25 -25
  96. package/dist/skills/docs-manager/references/agents-md-template.md +29 -29
  97. package/dist/skills/docs-manager/references/index-md-template.md +73 -73
  98. package/dist/skills/flow-init/SKILL.md +234 -234
  99. package/dist/skills/flow-init/references/architecture-template.md +45 -45
  100. package/dist/skills/flow-init/references/roadmap-templates.md +93 -93
  101. package/dist/skills/flow-init/references/tech-stack-template.md +70 -70
  102. package/dist/skills/flow-init/references/vision-templates.md +75 -75
  103. package/dist/skills/goal-development/SKILL.md +96 -96
  104. package/dist/skills/goal-migration/SKILL.md +114 -114
  105. package/dist/skills/goal-performance/SKILL.md +126 -126
  106. package/dist/skills/goal-research/SKILL.md +118 -118
  107. package/dist/skills/html-renderer/SKILL.md +173 -173
  108. package/dist/skills/html-renderer/references/index.html +318 -318
  109. package/dist/skills/html-renderer/references/styles.css +388 -388
  110. package/dist/skills/html-renderer/references/tokens.json +104 -104
  111. package/dist/skills/implementation-plan-executor/SKILL.md +378 -378
  112. package/dist/skills/implementation-verifier/SKILL.md +307 -307
  113. package/dist/skills/migration/SKILL.md +268 -268
  114. package/dist/skills/migration-analyze/SKILL.md +126 -126
  115. package/dist/skills/migration-finalize/SKILL.md +161 -161
  116. package/dist/skills/migration-fix/SKILL.md +155 -155
  117. package/dist/skills/migration-implement/SKILL.md +131 -131
  118. package/dist/skills/migration-plan/SKILL.md +131 -131
  119. package/dist/skills/migration-spec/SKILL.md +135 -135
  120. package/dist/skills/migration-spec/references/migration-strategies.md +430 -430
  121. package/dist/skills/migration-target/SKILL.md +134 -134
  122. package/dist/skills/migration-target/references/migration-types.md +489 -489
  123. package/dist/skills/migration-verify/SKILL.md +184 -184
  124. package/dist/skills/orchestrator-framework/SKILL.md +65 -65
  125. package/dist/skills/orchestrator-framework/references/command-namespacing.md +7 -7
  126. package/dist/skills/orchestrator-framework/references/confirm-or-revise-exception.md +20 -20
  127. package/dist/skills/orchestrator-framework/references/delegation-rules.md +54 -54
  128. package/dist/skills/orchestrator-framework/references/dispatcher-handoff.md +27 -27
  129. package/dist/skills/orchestrator-framework/references/fix-loop-contract.md +65 -65
  130. package/dist/skills/orchestrator-framework/references/gate-contract.md +122 -122
  131. package/dist/skills/orchestrator-framework/references/orchestrator-creation-checklist.md +51 -51
  132. package/dist/skills/orchestrator-framework/references/orchestrator-patterns.md +235 -235
  133. package/dist/skills/performance/SKILL.md +267 -267
  134. package/dist/skills/performance-analyze/SKILL.md +129 -129
  135. package/dist/skills/performance-analyze/references/performance-optimization-guide.md +271 -271
  136. package/dist/skills/performance-finalize/SKILL.md +117 -117
  137. package/dist/skills/performance-implement/SKILL.md +114 -114
  138. package/dist/skills/performance-plan/SKILL.md +112 -112
  139. package/dist/skills/performance-spec/SKILL.md +145 -145
  140. package/dist/skills/performance-verify/SKILL.md +164 -164
  141. package/dist/skills/research/SKILL.md +249 -249
  142. package/dist/skills/research-brainstorm/SKILL.md +120 -120
  143. package/dist/skills/research-brainstorm/references/brainstorming-techniques.md +84 -84
  144. package/dist/skills/research-converge/SKILL.md +130 -130
  145. package/dist/skills/research-design/SKILL.md +146 -146
  146. package/dist/skills/research-design/references/design-techniques.md +40 -40
  147. package/dist/skills/research-finalize/SKILL.md +125 -125
  148. package/dist/skills/research-fork/SKILL.md +190 -190
  149. package/dist/skills/research-gather/SKILL.md +133 -133
  150. package/dist/skills/research-plan/SKILL.md +141 -141
  151. package/dist/skills/research-plan/references/research-methodologies.md +710 -710
  152. package/dist/skills/research-quick/SKILL.md +139 -139
  153. package/dist/skills/research-synthesize/SKILL.md +127 -127
  154. package/dist/skills/rule-reviewer/SKILL.md +334 -334
  155. package/dist/skills/standards-discover/SKILL.md +260 -260
  156. package/dist/skills/standards-discover/references/aggregation-strategy.md +76 -76
  157. package/dist/skills/standards-discover/references/code-pattern-prompt.md +68 -68
  158. package/dist/skills/standards-discover/references/config-analyzer-prompt.md +67 -67
  159. package/dist/skills/standards-discover/references/docs-extractor-prompt.md +65 -65
  160. package/dist/skills/standards-discover/references/external-analyzer-prompt.md +75 -75
  161. package/dist/skills/standards-update/SKILL.md +207 -207
  162. package/dist/templates/orchestrator-state-base.yml +17 -17
  163. package/dist/templates/orchestrator-state-development.yml +95 -95
  164. package/dist/templates/orchestrator-state-migration.yml +95 -95
  165. package/dist/templates/orchestrator-state-performance.yml +64 -64
  166. package/dist/templates/orchestrator-state-research.yml +67 -67
  167. package/dist/tools/fork_task.d.ts +17 -0
  168. package/dist/tools/fork_task.js +21 -11
  169. package/dist/tools/verify_template.d.ts +11 -0
  170. package/dist/tools/verify_template.js +32 -17
  171. package/dist/tui/hooks-dialogs.d.ts +20 -0
  172. package/dist/tui/hooks-dialogs.js +181 -0
  173. package/dist/tui/hooks-presenter.d.ts +15 -0
  174. package/dist/tui/hooks-presenter.js +70 -0
  175. package/dist/tui/hooks-sidebar.d.ts +10 -0
  176. package/dist/tui/hooks-sidebar.js +104 -0
  177. package/dist/tui/primitives.d.ts +21 -0
  178. package/dist/tui/primitives.js +47 -0
  179. package/dist/tui.d.ts +12 -0
  180. package/dist/tui.js +129 -0
  181. package/dist/types/hook-types.d.ts +125 -0
  182. package/dist/types/hook-types.js +76 -0
  183. package/dist/types/opencode-types.d.ts +13 -0
  184. package/dist/utils/file-util.d.ts +2 -0
  185. package/dist/utils/file-util.js +6 -6
  186. package/dist/utils/fork-task.d.ts +27 -0
  187. package/dist/utils/fork-task.js +18 -23
  188. package/dist/utils/plugin-info.d.ts +3 -0
  189. package/dist/utils/plugin-info.js +8 -10
  190. package/dist/utils/workflow-paths.d.ts +17 -0
  191. package/dist/utils/workflow-paths.js +18 -0
  192. package/dist/utils/yaml-structure.d.ts +7 -0
  193. package/dist/utils/yaml-structure.js +7 -11
  194. package/package.json +68 -48
  195. package/dist/hooks/before-tool.js +0 -19
package/dist/skills/html-renderer/SKILL.md CHANGED
@@ -1,173 +1,173 @@
1
- ---
2
- name: owflow:html-renderer
3
- description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system bundled under `references/`. Use this skill whenever the user asks to "render", "convert", "turn into HTML", "make a nice HTML version", "share this as a page", or "make this look good" for a markdown file containing a plan, proposal, idea, brief, RFC, design note, or pitch — even if they don't explicitly say "HTML". The output is a single .html file with all CSS inlined, written next to the source .md, that visually matches the reference layout in `references/index.html` and uses tokens from `references/tokens.json`.
4
- argument-hint: "[path to markdown file]"
5
- disable-model-invocation: true
6
- user-invocable: true
7
- ---
8
-
9
- # HTML Renderer
10
-
11
- Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
12
-
13
- Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — "Inputs and outputs" below IS the Entry Gate; Workflow step 7 (Verify) plus the Exit Gate block at the close.
14
-
15
- ## When to use
16
-
17
- The user gives you a markdown file (or pastes markdown) describing a plan, idea, proposal, RFC, design note, or brief, and wants a clean HTML representation they can share. Output is *always* a portable single-file `.html` with the stylesheet inlined — no external assets, no JS.
18
-
19
- This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
20
-
21
- ## Inputs and outputs
22
-
23
- - **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
24
- - **Output**: write `<source-basename>.html` in the same directory as the source `.md`. If the source is `~/notes/q4-plan.md`, output is `~/notes/q4-plan.html`.
25
- - **Self-contained**: inline the full stylesheet inside a single `<style>` block in `<head>`. Do not link to external CSS, fonts (use the font stacks already in tokens — they fall back to system fonts), or images that aren't already in the source. The one allowed external script is Mermaid (see "Mermaid diagrams" below), and only when the source contains at least one ` ```mermaid ` fence.
26
- - **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
27
-
28
- ## Reference files (read these before writing output)
29
-
30
- The `references/` folder is the source of truth for the visual system. Read each file once at the start of a rendering task so the output matches:
31
-
32
- - `references/index.html` — canonical reference page showing every component (heading scale, text block, cards, table, diagram, quote, highlights). Use it as the structural template: the output should look like a variant of this page filled with the user's content.
33
- - `references/styles.css` — every `hr-*` class definition. **Copy this verbatim into the inlined `<style>` block** of the output. Do not paraphrase, rewrite, or trim it; the classes you emit in the HTML must resolve against these exact rules.
34
- - `references/tokens.json` — design tokens (colors, spacing, radius, typography). The CSS already consumes these via `:root` variables, so tokens.json is mostly informational — consult it only if the user asks to tweak colors/spacing or when you need to add a new component that should harmonize with existing tokens.
35
-
36
- Reuse existing classes and tokens before inventing anything. If the user asks for something genuinely new, declare any new CSS variables in `:root` using the same naming pattern, and keep class names prefixed with `hr-`.
37
-
38
- ## Workflow
39
-
40
- 1. **Resolve input**: confirm the source markdown path; read the file.
41
- 2. **Load references**: read `references/index.html` (structure), `references/styles.css` (full CSS to inline), and `references/tokens.json` (only if you need token values).
42
- 3. **Plan structure**: scan the markdown and decide how to group content into `<section class="hr-section hr-stack">` blocks. Each top-level `##` typically opens a new section.
43
- 4. **Map elements** using the mapping table below.
44
- 5. **Assemble** a single HTML document:
45
- - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
46
- - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
47
- 6. **Write** the file as `<basename>.html` next to the source.
48
- 7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
49
- 8. **Exit Gate**: present the results box, then confirm (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
50
-
51
- ```markdown
52
- ## ✅ HTML RENDER COMPLETE
53
-
54
- **Source** — `<source.md>`
55
- **Output** — `<basename>.html` (single file, self-contained)
56
- **Sections** — [count] · **Diagrams** — [count, if any]
57
- ```
58
-
59
- Use `question` — "Is the rendering correct?" with options: **Accept** (open the file in a browser and stop) / **Adjust** (user names layout/section issues; fix and re-present) / **Discuss** (explain a mapping or class choice) / **Stop here**. Note: visual correctness can only be confirmed by the user in a browser — offer to open it via the user's preferred `open`/`xdg-open` command.
60
-
61
- ## Markdown → HTML mapping
62
-
63
- | Markdown | HTML |
64
- |---|---|
65
- | `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
66
- | `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
67
- | Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
68
- | Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
69
- | Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
70
- | Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
71
- | `**bold**` / `*italic*` | `<strong>` / `<em>` |
72
- | Inline `` `code` `` | `<code>` |
73
- | Links `[text](url)` | `<a href="url">text</a>` |
74
- | Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
75
- | Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
76
- | Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
77
- | ` ```mermaid ` code fence | `<div class="hr-diagram"><div class="mermaid">…raw mermaid source, **not** HTML-escaped…</div></div>` (also include the Mermaid script described in "Mermaid diagrams" below) |
78
- | Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
79
- | Admonitions — lines starting with `> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]` (GitHub-style) or sections prefixed `**Note:**`, `**Warning:**`, `**Important:**` | `<aside class="hr-highlight hr-highlight-{note\|warning\|important}">` with `<p class="hr-highlight-title">` for the label |
80
- | Card-like content — a bolded title followed by 1–3 lines, especially in a list of similar items | `<article class="hr-card">` with `<h3 class="hr-card-title">` and `<p class="hr-card-text">`. Wrap multiple cards in `<div class="hr-grid">` (auto-fit). For fixed layouts use `hr-grid-2`, `hr-grid-3`, `hr-grid-4`, `hr-grid-feature` (2fr/1fr/1fr with `hr-card-featured` first), or `hr-grid-sidebar` (2fr/1fr). Mark the most important card as `hr-card-featured`. |
81
- | Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
82
-
83
- When the markdown is ambiguous (e.g., "is this a card or a paragraph?"), prefer the simpler choice: text block first, cards only when the content is clearly a set of parallel small items.
84
-
85
- ## Rendering rules
86
-
87
- 1. Every class you emit must be prefixed `hr-` and must exist in `references/styles.css`. If you need a new one, also add its rule to the inlined `<style>` and (if it relies on a new token) extend `:root`.
88
- 2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
89
- 3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
90
- 4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
91
- 5. **Keep the output a single file with zero external dependencies** — it must render correctly when opened directly in a browser. The one exception is the Mermaid CDN script, which is only injected when ` ```mermaid ` fences are present; users will need network access to see those diagrams render (the raw mermaid source remains in the DOM as a graceful fallback).
92
-
93
- ## Mermaid diagrams
94
-
95
- When the source markdown contains one or more ` ```mermaid ` fences:
96
-
97
- 1. Render each fence as:
98
- ```html
99
- <div class="hr-diagram">
100
- <div class="mermaid">
101
- …raw mermaid source, preserved verbatim, NOT HTML-escaped…
102
- </div>
103
- </div>
104
- ```
105
- Mermaid replaces the inner text with an SVG at page load, so the content must stay as plain text (do not wrap it in `<pre><code>` and do not escape `<`, `>`, `&` — mermaid needs the original characters).
106
- 2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
107
- ```html
108
- <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
109
- <script>
110
- window.mermaid &&
111
- mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
112
- </script>
113
- ```
114
- 3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
115
-
116
- ## Minimal example
117
-
118
- Input (`idea.md`):
119
- ```markdown
120
- # Lightweight RFC inbox
121
-
122
- A small daily ritual to capture half-formed ideas without losing them.
123
-
124
- ## Why
125
- Ideas evaporate within a day if there's no easy capture path.
126
-
127
- ## How
128
- - One markdown file per idea
129
- - Rendered to HTML on demand for sharing
130
-
131
- > [!NOTE]
132
- > This is intentionally low-tech: no database, no auth.
133
- ```
134
-
135
- Output (`idea.html`, abbreviated):
136
- ```html
137
- <!doctype html>
138
- <html lang="en">
139
- <head>
140
- <meta charset="UTF-8" />
141
- <meta name="viewport" content="width=device-width, initial-scale=1.0" />
142
- <title>Lightweight RFC inbox</title>
143
- <style>/* entire contents of references/styles.css inlined here */</style>
144
- </head>
145
- <body>
146
- <main class="hr-page">
147
- <section class="hr-section hr-stack">
148
- <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
149
- <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
150
- </section>
151
- <section class="hr-section hr-stack">
152
- <h2 class="hr-heading-h2">Why</h2>
153
- <div class="hr-text-block hr-stack">
154
- <p>Ideas evaporate within a day if there's no easy capture path.</p>
155
- </div>
156
- </section>
157
- <section class="hr-section hr-stack">
158
- <h2 class="hr-heading-h2">How</h2>
159
- <div class="hr-text-block hr-stack">
160
- <ul>
161
- <li>One markdown file per idea</li>
162
- <li>Rendered to HTML on demand for sharing</li>
163
- </ul>
164
- </div>
165
- <aside class="hr-highlight hr-highlight-note">
166
- <p class="hr-highlight-title">Note</p>
167
- <p>This is intentionally low-tech: no database, no auth.</p>
168
- </aside>
169
- </section>
170
- </main>
171
- </body>
172
- </html>
173
- ```
1
+ ---
2
+ name: owflow:html-renderer
3
+ description: Render a markdown plan, idea, RFC, or design note into a self-contained, share-ready HTML file using the warm editorial visual system bundled under `references/`. Use this skill whenever the user asks to "render", "convert", "turn into HTML", "make a nice HTML version", "share this as a page", or "make this look good" for a markdown file containing a plan, proposal, idea, brief, RFC, design note, or pitch — even if they don't explicitly say "HTML". The output is a single .html file with all CSS inlined, written next to the source .md, that visually matches the reference layout in `references/index.html` and uses tokens from `references/tokens.json`.
4
+ argument-hint: "[path to markdown file]"
5
+ disable-model-invocation: true
6
+ user-invocable: true
7
+ ---
8
+
9
+ # HTML Renderer
10
+
11
+ Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
12
+
13
+ Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — "Inputs and outputs" below IS the Entry Gate; Workflow step 7 (Verify) plus the Exit Gate block at the close.
14
+
15
+ ## When to use
16
+
17
+ The user gives you a markdown file (or pastes markdown) describing a plan, idea, proposal, RFC, design note, or brief, and wants a clean HTML representation they can share. Output is *always* a portable single-file `.html` with the stylesheet inlined — no external assets, no JS.
18
+
19
+ This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
20
+
21
+ ## Inputs and outputs
22
+
23
+ - **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
24
+ - **Output**: write `<source-basename>.html` in the same directory as the source `.md`. If the source is `~/notes/q4-plan.md`, output is `~/notes/q4-plan.html`.
25
+ - **Self-contained**: inline the full stylesheet inside a single `<style>` block in `<head>`. Do not link to external CSS, fonts (use the font stacks already in tokens — they fall back to system fonts), or images that aren't already in the source. The one allowed external script is Mermaid (see "Mermaid diagrams" below), and only when the source contains at least one ` ```mermaid ` fence.
26
+ - **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
27
+
28
+ ## Reference files (read these before writing output)
29
+
30
+ The `references/` folder is the source of truth for the visual system. Read each file once at the start of a rendering task so the output matches:
31
+
32
+ - `references/index.html` — canonical reference page showing every component (heading scale, text block, cards, table, diagram, quote, highlights). Use it as the structural template: the output should look like a variant of this page filled with the user's content.
33
+ - `references/styles.css` — every `hr-*` class definition. **Copy this verbatim into the inlined `<style>` block** of the output. Do not paraphrase, rewrite, or trim it; the classes you emit in the HTML must resolve against these exact rules.
34
+ - `references/tokens.json` — design tokens (colors, spacing, radius, typography). The CSS already consumes these via `:root` variables, so tokens.json is mostly informational — consult it only if the user asks to tweak colors/spacing or when you need to add a new component that should harmonize with existing tokens.
35
+
36
+ Reuse existing classes and tokens before inventing anything. If the user asks for something genuinely new, declare any new CSS variables in `:root` using the same naming pattern, and keep class names prefixed with `hr-`.
37
+
38
+ ## Workflow
39
+
40
+ 1. **Resolve input**: confirm the source markdown path; read the file.
41
+ 2. **Load references**: read `references/index.html` (structure), `references/styles.css` (full CSS to inline), and `references/tokens.json` (only if you need token values).
42
+ 3. **Plan structure**: scan the markdown and decide how to group content into `<section class="hr-section hr-stack">` blocks. Each top-level `##` typically opens a new section.
43
+ 4. **Map elements** using the mapping table below.
44
+ 5. **Assemble** a single HTML document:
45
+ - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
46
+ - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
47
+ 6. **Write** the file as `<basename>.html` next to the source.
48
+ 7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
49
+ 8. **Exit Gate**: present the results box, then confirm (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
50
+
51
+ ```markdown
52
+ ## ✅ HTML RENDER COMPLETE
53
+
54
+ **Source** — `<source.md>`
55
+ **Output** — `<basename>.html` (single file, self-contained)
56
+ **Sections** — [count] · **Diagrams** — [count, if any]
57
+ ```
58
+
59
+ Use `question` — "Is the rendering correct?" with options: **Accept** (open the file in a browser and stop) / **Adjust** (user names layout/section issues; fix and re-present) / **Discuss** (explain a mapping or class choice) / **Stop here**. Note: visual correctness can only be confirmed by the user in a browser — offer to open it via the user's preferred `open`/`xdg-open` command.
60
+
61
+ ## Markdown → HTML mapping
62
+
63
+ | Markdown | HTML |
64
+ |---|---|
65
+ | `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
66
+ | `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
67
+ | Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
68
+ | Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
69
+ | Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
70
+ | Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
71
+ | `**bold**` / `*italic*` | `<strong>` / `<em>` |
72
+ | Inline `` `code` `` | `<code>` |
73
+ | Links `[text](url)` | `<a href="url">text</a>` |
74
+ | Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
75
+ | Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
76
+ | Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
77
+ | ` ```mermaid ` code fence | `<div class="hr-diagram"><div class="mermaid">…raw mermaid source, **not** HTML-escaped…</div></div>` (also include the Mermaid script described in "Mermaid diagrams" below) |
78
+ | Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
79
+ | Admonitions — lines starting with `> [!NOTE]`, `> [!WARNING]`, `> [!IMPORTANT]` (GitHub-style) or sections prefixed `**Note:**`, `**Warning:**`, `**Important:**` | `<aside class="hr-highlight hr-highlight-{note\|warning\|important}">` with `<p class="hr-highlight-title">` for the label |
80
+ | Card-like content — a bolded title followed by 1–3 lines, especially in a list of similar items | `<article class="hr-card">` with `<h3 class="hr-card-title">` and `<p class="hr-card-text">`. Wrap multiple cards in `<div class="hr-grid">` (auto-fit). For fixed layouts use `hr-grid-2`, `hr-grid-3`, `hr-grid-4`, `hr-grid-feature` (2fr/1fr/1fr with `hr-card-featured` first), or `hr-grid-sidebar` (2fr/1fr). Mark the most important card as `hr-card-featured`. |
81
+ | Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
82
+
83
+ When the markdown is ambiguous (e.g., "is this a card or a paragraph?"), prefer the simpler choice: text block first, cards only when the content is clearly a set of parallel small items.
84
+
85
+ ## Rendering rules
86
+
87
+ 1. Every class you emit must be prefixed `hr-` and must exist in `references/styles.css`. If you need a new one, also add its rule to the inlined `<style>` and (if it relies on a new token) extend `:root`.
88
+ 2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
89
+ 3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
90
+ 4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
91
+ 5. **Keep the output a single file with zero external dependencies** — it must render correctly when opened directly in a browser. The one exception is the Mermaid CDN script, which is only injected when ` ```mermaid ` fences are present; users will need network access to see those diagrams render (the raw mermaid source remains in the DOM as a graceful fallback).
92
+
93
+ ## Mermaid diagrams
94
+
95
+ When the source markdown contains one or more ` ```mermaid ` fences:
96
+
97
+ 1. Render each fence as:
98
+ ```html
99
+ <div class="hr-diagram">
100
+ <div class="mermaid">
101
+ …raw mermaid source, preserved verbatim, NOT HTML-escaped…
102
+ </div>
103
+ </div>
104
+ ```
105
+ Mermaid replaces the inner text with an SVG at page load, so the content must stay as plain text (do not wrap it in `<pre><code>` and do not escape `<`, `>`, `&` — mermaid needs the original characters).
106
+ 2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
107
+ ```html
108
+ <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
109
+ <script>
110
+ window.mermaid &&
111
+ mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
112
+ </script>
113
+ ```
114
+ 3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
115
+
116
+ ## Minimal example
117
+
118
+ Input (`idea.md`):
119
+ ```markdown
120
+ # Lightweight RFC inbox
121
+
122
+ A small daily ritual to capture half-formed ideas without losing them.
123
+
124
+ ## Why
125
+ Ideas evaporate within a day if there's no easy capture path.
126
+
127
+ ## How
128
+ - One markdown file per idea
129
+ - Rendered to HTML on demand for sharing
130
+
131
+ > [!NOTE]
132
+ > This is intentionally low-tech: no database, no auth.
133
+ ```
134
+
135
+ Output (`idea.html`, abbreviated):
136
+ ```html
137
+ <!doctype html>
138
+ <html lang="en">
139
+ <head>
140
+ <meta charset="UTF-8" />
141
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
142
+ <title>Lightweight RFC inbox</title>
143
+ <style>/* entire contents of references/styles.css inlined here */</style>
144
+ </head>
145
+ <body>
146
+ <main class="hr-page">
147
+ <section class="hr-section hr-stack">
148
+ <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
149
+ <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
150
+ </section>
151
+ <section class="hr-section hr-stack">
152
+ <h2 class="hr-heading-h2">Why</h2>
153
+ <div class="hr-text-block hr-stack">
154
+ <p>Ideas evaporate within a day if there's no easy capture path.</p>
155
+ </div>
156
+ </section>
157
+ <section class="hr-section hr-stack">
158
+ <h2 class="hr-heading-h2">How</h2>
159
+ <div class="hr-text-block hr-stack">
160
+ <ul>
161
+ <li>One markdown file per idea</li>
162
+ <li>Rendered to HTML on demand for sharing</li>
163
+ </ul>
164
+ </div>
165
+ <aside class="hr-highlight hr-highlight-note">
166
+ <p class="hr-highlight-title">Note</p>
167
+ <p>This is intentionally low-tech: no database, no auth.</p>
168
+ </aside>
169
+ </section>
170
+ </main>
171
+ </body>
172
+ </html>
173
+ ```