owflow 0.5.0 → 0.7.0

package/dist/skills/goal-research/SKILL.md

@@ -1,118 +1,118 @@
----
-name: owflow:goal-research
-description: Full orchestrated research wrapper — runs ALL research steps in one session by invoking every research-* subskill in sequence with question gates between them (equivalent to the classic unified orchestrator for research). Use /owflow:research for the same lifecycle in assisted mode — tasks can mix both modes freely.
-argument-hint: "[task description | task-path] [--from=<slug>] [--type=<type>]"
-user-invocable: true
----
-
-# Orchestrated Research Wrapper
-
-Autonomous mode for research tasks. Initializes (or resumes) the task, then invokes every required `research-*` subskill back-to-back via the Skill tool, pausing at gates between subskills. Shares `orchestrator-state.yml` with assisted mode (`/owflow:research`) — tasks can mix both modes freely.
-
-Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — orchestrated mode exception: each subskill's own Exit Gate acceptance question IS the loop gate (Accept = continue to the next subskill).
-
-## Input / Output Artifacts
-
-| Artifact                            | Normal mode (this wrapper)                                                  | Quick mode (`research-quick`)                                                                |
-| ----------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Consumed: argument (question / path)| research question (new task) or task path/identifier (resume)                 | n/a — this wrapper never starts a quick run; a completed quick pass just skips rows 2-3            |
-| Consumed/produced: all task artifacts| owned entirely by the invoked subskills (none here — delegate, never inline) | same — the subskills run at full fidelity after a quick pass                                       |
-| State write                         | `orchestrator.task_ids` (task items) + `orchestrator.updated` only            | none additional — state was already written by the quick pass                                      |
-
-## Entry Gate
-
-Identical to the research dispatcher — complete ALL of its entry-gate steps first (see `../research/SKILL.md` Entry Gate):
-
-1. Read the framework reference files NOW, exactly as the research dispatcher's Step 1: the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md), the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), and the [Orchestrator Patterns](../orchestrator-framework/references/orchestrator-patterns.md).
-2. Resolve the argument the same way the research dispatcher does: task path or identifier (a directory, or a directory name under `.owflow/tasks/research/`) → **resume mode** (read `orchestrator-state.yml`, validate expected artifacts for `completed_phases`; find the first step slug NOT in `completed_phases`, with `--from=<slug>` overriding); a research question (free text) → new task; nothing provided → ask via `question` — "What is your research question?" — then WAIT. Missing state file → print `No research task found at <path>. Run /owflow:research <question> to start from scratch.` and STOP.
-3. Initialize (new task) exactly as the dispatcher: create `.owflow/tasks/research/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the research template — `task.title` / `task.description` from the question, `task.status: in_progress`, `orchestrator.task_path`, `orchestrator.entry_point: "research"`. **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`. No project-docs discovery at this layer — the `research-plan` brief step owns it.
-4. Command flags: `--type=TYPE` → `research_context.research_type`. Subskills read it from there. This wrapper never forwards quick runs. The optional brainstorm/design chain has no flags — the chain decision is asked at the gate after synthesis (row 4 below) or made by manually invoking the optional subskills.
-5. Create ONE task item via `TaskCreate` per subskill in the upcoming loop (subject: `"<step name>: <subskill>"`, e.g. `"Brief + plan: research-plan"`), then set the execution order with `TaskUpdate addBlockedBy` (plan → gather → synthesize → optional chain (gate question) → finalize). On resume, refresh the already-evidenced items instead of re-creating them. Update statuses as the loop progresses.
-
-**Output**:
-
-```
-🚀 Orchestrated Research
-
-Task: [research question]
-Directory: [task-path]
-Loop: research-plan → research-gather → research-synthesize → [research-brainstorm] → [research-converge] → [research-design] → research-finalize (chain asked at the gate)
-```
-
----
-
-## The Loop
-
-For each subskill in sequence, execute — skipping any row whose condition is not met (a row whose slug is already in `completed_phases` counts as done):
-
-1. **Announce**: 1-line step banner.
-2. **Invoke**: Skill tool with `name: "<subskill>"` and `prompt: "<task-path> [flags relevant to that subskill]"`. The subskill owns its Entry Gate, delegation, and state updates.
-3. **Verify handback**: after the skill returns, re-read `orchestrator-state.yml` — confirm the expected step slugs were appended to `completed_phases` (per the Sequence and Conditionals table). A user-chosen skip of `research-brainstorm` or `research-design` appends no slug — the gate answer itself settles the decision, and the loop continues to the next selected row (or to finalize). Do not treat a skipped optional subskill as an early stop. If a subskill stopped early (entry check failed), STOP the loop and relay its routing message to the user.
-4. **Gate (subskill's Exit Gate is the loop gate)**: each subskill presents its results box and fires its own results-acceptance `question` before its handoff hint (Orchestrated-mode exception, [Gate Contract](../orchestrator-framework/references/gate-contract.md)). [Rule 5 of the Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) — "subskills only SUGGEST the next command" — is superseded for Accept: when the user answers **Accept** to the subskill's Exit Gate question pointing at the next subskill in this loop, treat that as "continue to the next subskill" and invoke it. Any other answer (Adjust / Discuss / Stop / other options picked) ends the loop the same way a rejected gate would.
-   - **Exception**: the per-area convergence `question`s `research-converge` fires (one area, one question) are part of that subskill's own decision flow — they are NOT the loop gate and are NEVER auto-accepted or answered by this wrapper. There is exactly ONE gate definition per subskill hop; the wrapper adds NO second consecutive `question`.
-   - **Condensed lane**: this wrapper never starts a quick run. A task already started with `/owflow:research-quick` enters the loop with `brief-written` … `synthesis-complete` already recorded, so those rows are skipped like any other completed slug. An interrupted quick pass (those slugs missing) is not finished condensed here — the user runs `/owflow:research-quick <task-path>` for that.
-
-### Sequence and Conditionals
-
-| Order | Subskill           | Run when (from state)                                                                                             |
-| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
-| 1     | research-plan      | Always (new task or partial foundation)                                                                                 |
-| 2     | research-gather    | `plan-created` completed (parses `## Gathering Strategy`, or falls back to 4 default categories; existing findings count as done) |
-| 3     | research-synthesize| `findings-gathered` completed                                                                                       |
-| 4     | chain decision     | `synthesis-complete` completed — the wrapper asks via `question`: brainstorm → converge → design, design-only, or straight to finalize |
-| 5     | research-brainstorm| User chose brainstorming at the gate (invoking/sequencing the skill IS the decision)                                 |
-| 6     | research-converge  | `alternatives-generated` completed (brainstorm ran)                                                                 |
-| 7     | research-design    | User chose design — after `approaches-chosen`, or the design-only branch (seeded from the research report)           |
-| 8     | research-finalize  | Foundation complete + optional chain settled (every step the user chose to run is recorded)                          |
-
-A completed quick pass already recorded `brief-written` … `synthesis-complete`, so rows 2-3 are skipped as already done and the loop continues at row 4 (the chain decision). This wrapper never starts a quick run.
-
-The optional chain is the user's choice — asked at the gate (row 4) or made by manually invoking the optional subskills. There is no enablement flag in state:
-
-- Brainstorm chosen → `research-brainstorm` → `research-converge` → design (if chosen) → finalize.
-- Design-only chosen → skip the brainstorm + converge rows → `research-design` → finalize.
-- Neither chosen → all conditional rows are skipped → `research-finalize`.
-
-`research-completed` already in `completed_phases` → the task is TERMINAL: skip the Loop and present the wrapper Exit Gate.
-
-**Interruptible**: at any gate the user may answer "stop" — print the standard handoff block (next command + `/owflow:research <task-path>` resume hint) and end the session. The task resumes later in either mode.
-
----
-
-## Exit Gate
-
-When research-finalize completes (`task.status: completed`):
-
-1. Mark the final task item completed via `TaskUpdate`.
-2. Present the workflow results box:
-
-```markdown
-## ✅ RESEARCH WORKFLOW COMPLETE — <research question>
-
-**Steps** — [executed step slugs, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated → research-completed]
-**Confidence** — [research_context.confidence_level]
-**Decisions** — [count of ADRs in the decision log, if design ran]
-**Artifacts** — [artifact inventory: outputs/research-report.md always; outputs/solution-exploration.md / outputs/high-level-design.md / outputs/decision-log.md conditionally]
-```
-
-3. Use `question` — "Are these results correct?" with options: **Accept** (print follow-up suggestions: clear context, then `/owflow:development <task-path>` to build on this research, `/owflow:standards-update "<lesson>"` if a standard surfaced, then end) / **Adjust** (re-open the relevant `/owflow:research-*` skill with the corrections) / **Discuss** (walk through the research summary) / **Stop here** (print the resume command `/owflow:research <task-path>` and end).
-
-Then end. No further owflow phase commands are required.
-
----
-
-## Loop Rules
-
-- **Delegate, never inline**: the wrapper only sequences — all step work happens inside subskills. If you catch yourself researching/authoring outside a subskill, STOP and invoke the subskill instead.
-- **State is the truth**: gates and routing read `orchestrator-state.yml`, not memory. Re-read after every subskill returns.
-- **Same state schema as assisted mode**: `completed_phases` step slugs (`brief-written` … `research-completed`) are identical; resume works across modes.
-- **Wrapper writes almost nothing**: step slugs, summaries, and outputs belong to the subskills — this wrapper writes ONLY `orchestrator.task_ids` (task items) and `orchestrator.updated` (timestamps).
-
-## Command Integration
-
-Invoked via:
-
-- `/owflow:goal-research [question] [--type=TYPE]` (new)
-- `/owflow:goal-research [task-path] [--from=<slug>]` (resume)
-
-Alternative: `/owflow:research` — same task in assisted mode (one subskill per invocation, fresh context each step).
+---
+name: owflow:goal-research
+description: Full orchestrated research wrapper — runs ALL research steps in one session by invoking every research-* subskill in sequence with question gates between them (equivalent to the classic unified orchestrator for research). Use /owflow:research for the same lifecycle in assisted mode — tasks can mix both modes freely.
+argument-hint: "[task description | task-path] [--from=<slug>] [--type=<type>]"
+user-invocable: true
+---
+
+# Orchestrated Research Wrapper
+
+Autonomous mode for research tasks. Initializes (or resumes) the task, then invokes every required `research-*` subskill back-to-back via the Skill tool, pausing at gates between subskills. Shares `orchestrator-state.yml` with assisted mode (`/owflow:research`) — tasks can mix both modes freely.
+
+Gates follow the shared contract in [Gate Contract](../orchestrator-framework/references/gate-contract.md) — orchestrated mode exception: each subskill's own Exit Gate acceptance question IS the loop gate (Accept = continue to the next subskill).
+
+## Input / Output Artifacts
+
+| Artifact                            | Normal mode (this wrapper)                                                  | Quick mode (`research-quick`)                                                                |
+| ----------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Consumed: argument (question / path)| research question (new task) or task path/identifier (resume)                 | n/a — this wrapper never starts a quick run; a completed quick pass just skips rows 2-3            |
+| Consumed/produced: all task artifacts| owned entirely by the invoked subskills (none here — delegate, never inline) | same — the subskills run at full fidelity after a quick pass                                       |
+| State write                         | `orchestrator.task_ids` (task items) + `orchestrator.updated` only            | none additional — state was already written by the quick pass                                      |
+
+## Entry Gate
+
+Identical to the research dispatcher — complete ALL of its entry-gate steps first (see `../research/SKILL.md` Entry Gate):
+
+1. Read the framework reference files NOW, exactly as the research dispatcher's Step 1: the [Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md), the [Delegation Rules](../orchestrator-framework/references/delegation-rules.md), and the [Orchestrator Patterns](../orchestrator-framework/references/orchestrator-patterns.md).
+2. Resolve the argument the same way the research dispatcher does: task path or identifier (a directory, or a directory name under `.owflow/tasks/research/`) → **resume mode** (read `orchestrator-state.yml`, validate expected artifacts for `completed_phases`; find the first step slug NOT in `completed_phases`, with `--from=<slug>` overriding); a research question (free text) → new task; nothing provided → ask via `question` — "What is your research question?" — then WAIT. Missing state file → print `No research task found at <path>. Run /owflow:research <question> to start from scratch.` and STOP.
+3. Initialize (new task) exactly as the dispatcher: create `.owflow/tasks/research/YYYY-MM-DD-task-name/` + `orchestrator-state.yml` from the research template — `task.title` / `task.description` from the question, `task.status: in_progress`, `orchestrator.task_path`, `orchestrator.entry_point: "research"`. **CRITICAL**: use the `verify_template` tool immediately after creation to check YAML validity against `orchestrator-state-research.yml`. No project-docs discovery at this layer — the `research-plan` brief step owns it.
+4. Command flags: `--type=TYPE` → `research_context.research_type`. Subskills read it from there. This wrapper never forwards quick runs. The optional brainstorm/design chain has no flags — the chain decision is asked at the gate after synthesis (row 4 below) or made by manually invoking the optional subskills.
+5. Create ONE task item via `TaskCreate` per subskill in the upcoming loop (subject: `"<step name>: <subskill>"`, e.g. `"Brief + plan: research-plan"`), then set the execution order with `TaskUpdate addBlockedBy` (plan → gather → synthesize → optional chain (gate question) → finalize). On resume, refresh the already-evidenced items instead of re-creating them. Update statuses as the loop progresses.
+
+**Output**:
+
+```
+🚀 Orchestrated Research
+
+Task: [research question]
+Directory: [task-path]
+Loop: research-plan → research-gather → research-synthesize → [research-brainstorm] → [research-converge] → [research-design] → research-finalize (chain asked at the gate)
+```
+
+---
+
+## The Loop
+
+For each subskill in sequence, execute — skipping any row whose condition is not met (a row whose slug is already in `completed_phases` counts as done):
+
+1. **Announce**: 1-line step banner.
+2. **Invoke**: Skill tool with `name: "<subskill>"` and `prompt: "<task-path> [flags relevant to that subskill]"`. The subskill owns its Entry Gate, delegation, and state updates.
+3. **Verify handback**: after the skill returns, re-read `orchestrator-state.yml` — confirm the expected step slugs were appended to `completed_phases` (per the Sequence and Conditionals table). A user-chosen skip of `research-brainstorm` or `research-design` appends no slug — the gate answer itself settles the decision, and the loop continues to the next selected row (or to finalize). Do not treat a skipped optional subskill as an early stop. If a subskill stopped early (entry check failed), STOP the loop and relay its routing message to the user.
+4. **Gate (subskill's Exit Gate is the loop gate)**: each subskill presents its results box and fires its own results-acceptance `question` before its handoff hint (Orchestrated-mode exception, [Gate Contract](../orchestrator-framework/references/gate-contract.md)). [Rule 5 of the Dispatcher & Handoff Pattern](../orchestrator-framework/references/dispatcher-handoff.md) — "subskills only SUGGEST the next command" — is superseded for Accept: when the user answers **Accept** to the subskill's Exit Gate question pointing at the next subskill in this loop, treat that as "continue to the next subskill" and invoke it. Any other answer (Adjust / Discuss / Stop / other options picked) ends the loop the same way a rejected gate would.
+   - **Exception**: the per-area convergence `question`s `research-converge` fires (one area, one question) are part of that subskill's own decision flow — they are NOT the loop gate and are NEVER auto-accepted or answered by this wrapper. There is exactly ONE gate definition per subskill hop; the wrapper adds NO second consecutive `question`.
+   - **Condensed lane**: this wrapper never starts a quick run. A task already started with `/owflow:research-quick` enters the loop with `brief-written` … `synthesis-complete` already recorded, so those rows are skipped like any other completed slug. An interrupted quick pass (those slugs missing) is not finished condensed here — the user runs `/owflow:research-quick <task-path>` for that.
+
+### Sequence and Conditionals
+
+| Order | Subskill           | Run when (from state)                                                                                             |
+| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| 1     | research-plan      | Always (new task or partial foundation)                                                                                 |
+| 2     | research-gather    | `plan-created` completed (parses `## Gathering Strategy`, or falls back to 4 default categories; existing findings count as done) |
+| 3     | research-synthesize| `findings-gathered` completed                                                                                       |
+| 4     | chain decision     | `synthesis-complete` completed — the wrapper asks via `question`: brainstorm → converge → design, design-only, or straight to finalize |
+| 5     | research-brainstorm| User chose brainstorming at the gate (invoking/sequencing the skill IS the decision)                                 |
+| 6     | research-converge  | `alternatives-generated` completed (brainstorm ran)                                                                 |
+| 7     | research-design    | User chose design — after `approaches-chosen`, or the design-only branch (seeded from the research report)           |
+| 8     | research-finalize  | Foundation complete + optional chain settled (every step the user chose to run is recorded)                          |
+
+A completed quick pass already recorded `brief-written` … `synthesis-complete`, so rows 2-3 are skipped as already done and the loop continues at row 4 (the chain decision). This wrapper never starts a quick run.
+
+The optional chain is the user's choice — asked at the gate (row 4) or made by manually invoking the optional subskills. There is no enablement flag in state:
+
+- Brainstorm chosen → `research-brainstorm` → `research-converge` → design (if chosen) → finalize.
+- Design-only chosen → skip the brainstorm + converge rows → `research-design` → finalize.
+- Neither chosen → all conditional rows are skipped → `research-finalize`.
+
+`research-completed` already in `completed_phases` → the task is TERMINAL: skip the Loop and present the wrapper Exit Gate.
+
+**Interruptible**: at any gate the user may answer "stop" — print the standard handoff block (next command + `/owflow:research <task-path>` resume hint) and end the session. The task resumes later in either mode.
+
+---
+
+## Exit Gate
+
+When research-finalize completes (`task.status: completed`):
+
+1. Mark the final task item completed via `TaskUpdate`.
+2. Present the workflow results box:
+
+```markdown
+## ✅ RESEARCH WORKFLOW COMPLETE — <research question>
+
+**Steps** — [executed step slugs, e.g. brief-written → plan-created → findings-gathered → synthesis-complete → alternatives-generated → approaches-chosen → design-generated → research-completed]
+**Confidence** — [research_context.confidence_level]
+**Decisions** — [count of ADRs in the decision log, if design ran]
+**Artifacts** — [artifact inventory: outputs/research-report.md always; outputs/solution-exploration.md / outputs/high-level-design.md / outputs/decision-log.md conditionally]
+```
+
+3. Use `question` — "Are these results correct?" with options: **Accept** (print follow-up suggestions: clear context, then `/owflow:development <task-path>` to build on this research, `/owflow:standards-update "<lesson>"` if a standard surfaced, then end) / **Adjust** (re-open the relevant `/owflow:research-*` skill with the corrections) / **Discuss** (walk through the research summary) / **Stop here** (print the resume command `/owflow:research <task-path>` and end).
+
+Then end. No further owflow phase commands are required.
+
+---
+
+## Loop Rules
+
+- **Delegate, never inline**: the wrapper only sequences — all step work happens inside subskills. If you catch yourself researching/authoring outside a subskill, STOP and invoke the subskill instead.
+- **State is the truth**: gates and routing read `orchestrator-state.yml`, not memory. Re-read after every subskill returns.
+- **Same state schema as assisted mode**: `completed_phases` step slugs (`brief-written` … `research-completed`) are identical; resume works across modes.
+- **Wrapper writes almost nothing**: step slugs, summaries, and outputs belong to the subskills — this wrapper writes ONLY `orchestrator.task_ids` (task items) and `orchestrator.updated` (timestamps).
+
+## Command Integration
+
+Invoked via:
+
+- `/owflow:goal-research [question] [--type=TYPE]` (new)
+- `/owflow:goal-research [task-path] [--from=<slug>]` (resume)
+
+Alternative: `/owflow:research` — same task in assisted mode (one subskill per invocation, fresh context each step).

package/dist/skills/html-renderer/SKILL.md

@@ -1,173 +1,173 @@
----
-name: owflow:html-renderer
-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`.
-argument-hint: "[path to markdown file]"
-disable-model-invocation: true
-user-invocable: true
----
-
-# HTML Renderer
-
-Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
-
-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.
-
-## When to use
-
-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.
-
-This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
-
-## Inputs and outputs
-
-- **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
-- **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`.
-- **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.
-- **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
-
-## Reference files (read these before writing output)
-
-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:
-
-- `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.
-- `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.
-- `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.
-
-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-`.
-
-## Workflow
-
-1. **Resolve input**: confirm the source markdown path; read the file.
-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).
-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.
-4. **Map elements** using the mapping table below.
-5. **Assemble** a single HTML document:
-   - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
-   - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
-6. **Write** the file as `<basename>.html` next to the source.
-7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
-8. **Exit Gate**: present the results box, then confirm (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
-
-```markdown
-## ✅ HTML RENDER COMPLETE
-
-**Source** — `<source.md>`
-**Output** — `<basename>.html` (single file, self-contained)
-**Sections** — [count] · **Diagrams** — [count, if any]
-```
-
-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.
-
-## Markdown → HTML mapping
-
-| Markdown | HTML |
-|---|---|
-| `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
-| `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
-| Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
-| Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
-| Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
-| Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
-| `**bold**` / `*italic*` | `<strong>` / `<em>` |
-| Inline `` `code` `` | `<code>` |
-| Links `[text](url)` | `<a href="url">text</a>` |
-| Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
-| Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
-| Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
-| ` ```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) |
-| Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
-| 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 |
-| 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`. |
-| Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
-
-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.
-
-## Rendering rules
-
-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`.
-2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
-3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
-4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
-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).
-
-## Mermaid diagrams
-
-When the source markdown contains one or more ` ```mermaid ` fences:
-
-1. Render each fence as:
-   ```html
-   <div class="hr-diagram">
-     <div class="mermaid">
-   …raw mermaid source, preserved verbatim, NOT HTML-escaped…
-     </div>
-   </div>
-   ```
-   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).
-2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
-   ```html
-   <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
-   <script>
-     window.mermaid &&
-       mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-   </script>
-   ```
-3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
-
-## Minimal example
-
-Input (`idea.md`):
-```markdown
-# Lightweight RFC inbox
-
-A small daily ritual to capture half-formed ideas without losing them.
-
-## Why
-Ideas evaporate within a day if there's no easy capture path.
-
-## How
-- One markdown file per idea
-- Rendered to HTML on demand for sharing
-
-> [!NOTE]
-> This is intentionally low-tech: no database, no auth.
-```
-
-Output (`idea.html`, abbreviated):
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Lightweight RFC inbox</title>
-    <style>/* entire contents of references/styles.css inlined here */</style>
-  </head>
-  <body>
-    <main class="hr-page">
-      <section class="hr-section hr-stack">
-        <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
-        <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
-      </section>
-      <section class="hr-section hr-stack">
-        <h2 class="hr-heading-h2">Why</h2>
-        <div class="hr-text-block hr-stack">
-          <p>Ideas evaporate within a day if there's no easy capture path.</p>
-        </div>
-      </section>
-      <section class="hr-section hr-stack">
-        <h2 class="hr-heading-h2">How</h2>
-        <div class="hr-text-block hr-stack">
-          <ul>
-            <li>One markdown file per idea</li>
-            <li>Rendered to HTML on demand for sharing</li>
-          </ul>
-        </div>
-        <aside class="hr-highlight hr-highlight-note">
-          <p class="hr-highlight-title">Note</p>
-          <p>This is intentionally low-tech: no database, no auth.</p>
-        </aside>
-      </section>
-    </main>
-  </body>
-</html>
-```
+---
+name: owflow:html-renderer
+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`.
+argument-hint: "[path to markdown file]"
+disable-model-invocation: true
+user-invocable: true
+---
+
+# HTML Renderer
+
+Turn a markdown plan/idea/RFC into a single self-contained HTML page that follows the warm editorial design system bundled in this skill.
+
+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.
+
+## When to use
+
+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.
+
+This skill is opt-in: it does not auto-trigger. The user invokes it explicitly.
+
+## Inputs and outputs
+
+- **Input**: path to a `.md` file (or raw markdown content). If raw markdown is provided, ask for a filename stem.
+- **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`.
+- **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.
+- **Title**: use the first `# H1` from the markdown as `<title>`; if none, fall back to the file's basename humanized.
+
+## Reference files (read these before writing output)
+
+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:
+
+- `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.
+- `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.
+- `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.
+
+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-`.
+
+## Workflow
+
+1. **Resolve input**: confirm the source markdown path; read the file.
+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).
+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.
+4. **Map elements** using the mapping table below.
+5. **Assemble** a single HTML document:
+   - `<!doctype html>` + `<html lang="en">` + `<head>` with `<meta charset>`, `<meta viewport>`, `<title>`, and a `<style>` block containing the *entire* contents of `references/styles.css`.
+   - `<body>` containing `<main class="hr-page">` wrapping the sectioned content.
+6. **Write** the file as `<basename>.html` next to the source.
+7. **Verify**: re-open the output and confirm every `class="hr-..."` you emitted exists in the inlined CSS.
+8. **Exit Gate**: present the results box, then confirm (Exit Gate contract, [Gate Contract](../orchestrator-framework/references/gate-contract.md)):
+
+```markdown
+## ✅ HTML RENDER COMPLETE
+
+**Source** — `<source.md>`
+**Output** — `<basename>.html` (single file, self-contained)
+**Sections** — [count] · **Diagrams** — [count, if any]
+```
+
+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.
+
+## Markdown → HTML mapping
+
+| Markdown | HTML |
+|---|---|
+| `# Title` (first one) | `<h1 class="hr-heading-h1">` (also sets `<title>`) |
+| `##`, `###`, `####` | `<h2 class="hr-heading-h2">`, `<h3 class="hr-heading-h3">`, `<h4 class="hr-heading-h4">` |
+| Eyebrow line (italic small intro before H1, e.g. `_Reference Base_`) | `<span class="hr-heading-eyebrow">` |
+| Paragraphs & lists in narrative flow | wrap in `<div class="hr-text-block hr-stack">` |
+| Short summary paragraph right under H1 | `<p class="hr-text-muted">` |
+| Unordered/ordered lists | plain `<ul>`/`<ol>` inside `hr-text-block` |
+| `**bold**` / `*italic*` | `<strong>` / `<em>` |
+| Inline `` `code` `` | `<code>` |
+| Links `[text](url)` | `<a href="url">text</a>` |
+| Horizontal rule `---` | new `<section class="hr-section hr-stack">` (prefer sectioning over `<hr>`) |
+| Tables | `<div class="hr-table-wrap"><table class="hr-table">…</table></div>` |
+| Blockquote `>` | `<blockquote class="hr-quote">`; if the last line starts with `— `, render as `<footer>` |
+| ` ```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) |
+| Any other fenced code | `<pre><code>…</code></pre>` (escape `<`, `>`, `&`) |
+| 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 |
+| 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`. |
+| Tags / labels (e.g. `[Priority]`, `[Default]`) | `<span class="hr-badge">` |
+
+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.
+
+## Rendering rules
+
+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`.
+2. No inline `style="…"` attributes unless the user explicitly asks for a one-off override.
+3. Favor semantic tags (`section`, `article`, `aside`, `blockquote`, `table`, `figure`) and apply `hr-*` classes on top of them.
+4. Escape HTML special characters in content (`<`, `>`, `&`) so user prose never breaks the page.
+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).
+
+## Mermaid diagrams
+
+When the source markdown contains one or more ` ```mermaid ` fences:
+
+1. Render each fence as:
+   ```html
+   <div class="hr-diagram">
+     <div class="mermaid">
+   …raw mermaid source, preserved verbatim, NOT HTML-escaped…
+     </div>
+   </div>
+   ```
+   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).
+2. Inject the Mermaid script + initializer immediately before `</body>`, exactly once per document:
+   ```html
+   <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+   <script>
+     window.mermaid &&
+       mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+   </script>
+   ```
+3. If the markdown has no ` ```mermaid ` fences, **do not** add the script — keep the output fully offline.
+
+## Minimal example
+
+Input (`idea.md`):
+```markdown
+# Lightweight RFC inbox
+
+A small daily ritual to capture half-formed ideas without losing them.
+
+## Why
+Ideas evaporate within a day if there's no easy capture path.
+
+## How
+- One markdown file per idea
+- Rendered to HTML on demand for sharing
+
+> [!NOTE]
+> This is intentionally low-tech: no database, no auth.
+```
+
+Output (`idea.html`, abbreviated):
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Lightweight RFC inbox</title>
+    <style>/* entire contents of references/styles.css inlined here */</style>
+  </head>
+  <body>
+    <main class="hr-page">
+      <section class="hr-section hr-stack">
+        <h1 class="hr-heading-h1">Lightweight RFC inbox</h1>
+        <p class="hr-text-muted">A small daily ritual to capture half-formed ideas without losing them.</p>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">Why</h2>
+        <div class="hr-text-block hr-stack">
+          <p>Ideas evaporate within a day if there's no easy capture path.</p>
+        </div>
+      </section>
+      <section class="hr-section hr-stack">
+        <h2 class="hr-heading-h2">How</h2>
+        <div class="hr-text-block hr-stack">
+          <ul>
+            <li>One markdown file per idea</li>
+            <li>Rendered to HTML on demand for sharing</li>
+          </ul>
+        </div>
+        <aside class="hr-highlight hr-highlight-note">
+          <p class="hr-highlight-title">Note</p>
+          <p>This is intentionally low-tech: no database, no auth.</p>
+        </aside>
+      </section>
+    </main>
+  </body>
+</html>
+```