@jakkrichm/create-nexus-devflow 2.0.11 → 2.0.13

package/template/.agents/skills/incremental-implementation/SKILL.md

@@ -1,248 +0,0 @@
----
-name: incremental-implementation
-description: "[Devflow] Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step."
----
-
-# Incremental Implementation
-
-## Overview
-
-Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
-
-## When to Use
-
-- Implementing any multi-file change
-- Building a new feature from a task breakdown
-- Refactoring existing code
-- Any time you're tempted to write more than ~100 lines before testing
-
-**When NOT to use:** Single-file, single-function changes where the scope is already minimal.
-
-## The Increment Cycle
-
-```
-┌──────────────────────────────────────┐
-│                                      │
-│   Implement ──→ Test ──→ Verify ──┐  │
-│       ▲                           │  │
-│       └───── Commit ◄─────────────┘  │
-│              │                       │
-│              ▼                       │
-│          Next slice                  │
-│                                      │
-└──────────────────────────────────────┘
-```
-
-For each slice:
-
-1. **Implement** the smallest complete piece of functionality
-2. **Test** — run the test suite (or write a test if none exists)
-3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)
-4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)
-5. **Move to the next slice** — carry forward, don't restart
-
-## Slicing Strategies
-
-### Vertical Slices (Preferred)
-
-Build one complete path through the stack:
-
-```
-Slice 1: Create a task (DB + API + basic UI)
-    → Tests pass, user can create a task via the UI
-
-Slice 2: List tasks (query + API + UI)
-    → Tests pass, user can see their tasks
-
-Slice 3: Edit a task (update + API + UI)
-    → Tests pass, user can modify tasks
-
-Slice 4: Delete a task (delete + API + UI + confirmation)
-    → Tests pass, full CRUD complete
-```
-
-Each slice delivers working end-to-end functionality.
-
-### Contract-First Slicing
-
-When backend and frontend need to develop in parallel:
-
-```
-Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
-Slice 1a: Implement backend against the contract + API tests
-Slice 1b: Implement frontend against mock data matching the contract
-Slice 2: Integrate and test end-to-end
-```
-
-### Risk-First Slicing
-
-Tackle the riskiest or most uncertain piece first:
-
-```
-Slice 1: Prove the WebSocket connection works (highest risk)
-Slice 2: Build real-time task updates on the proven connection
-Slice 3: Add offline support and reconnection
-```
-
-If Slice 1 fails, you discover it before investing in Slices 2 and 3.
-
-## Implementation Rules
-
-### Rule 0: Simplicity First
-
-Before writing any code, ask: "What is the simplest thing that could work?"
-
-After writing code, review it against these checks:
-- Can this be done in fewer lines?
-- Are these abstractions earning their complexity?
-- Would a staff engineer look at this and say "why didn't you just..."?
-- Am I building for hypothetical future requirements, or the current task?
-
-```
-SIMPLICITY CHECK:
-✗ Generic EventBus with middleware pipeline for one notification
-✓ Simple function call
-
-✗ Abstract factory pattern for two similar components
-✓ Two straightforward components with shared utilities
-
-✗ Config-driven form builder for three forms
-✓ Three form components
-```
-
-Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
-
-### Rule 0.5: Scope Discipline
-
-Touch only what the task requires.
-
-Do NOT:
-- "Clean up" code adjacent to your change
-- Refactor imports in files you're not modifying
-- Remove comments you don't fully understand
-- Add features not in the spec because they "seem useful"
-- Modernize syntax in files you're only reading
-
-If you notice something worth improving outside your task scope, note it — don't fix it:
-
-```
-NOTICED BUT NOT TOUCHING:
-- src/utils/format.ts has an unused import (unrelated to this task)
-- The auth middleware could use better error messages (separate task)
-→ Want me to create tasks for these?
-```
-
-### Rule 1: One Thing at a Time
-
-Each increment changes one logical thing. Don't mix concerns:
-
-**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.
-
-**Good:** Three separate commits — one for each change.
-
-### Rule 2: Keep It Compilable
-
-After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
-
-### Rule 3: Feature Flags for Incomplete Features
-
-If a feature isn't ready for users but you need to merge increments:
-
-```typescript
-// Feature flag for work-in-progress
-const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
-
-if (ENABLE_TASK_SHARING) {
-  // New sharing UI
-}
-```
-
-This lets you merge small increments to the main branch without exposing incomplete work.
-
-### Rule 4: Safe Defaults
-
-New code should default to safe, conservative behavior:
-
-```typescript
-// Safe: disabled by default, opt-in
-export function createTask(data: TaskInput, options?: { notify?: boolean }) {
-  const shouldNotify = options?.notify ?? false;
-  // ...
-}
-```
-
-### Rule 5: Rollback-Friendly
-
-Each increment should be independently revertable:
-
-- Additive changes (new files, new functions) are easy to revert
-- Modifications to existing code should be minimal and focused
-- Database migrations should have corresponding rollback migrations
-- Avoid deleting something in one commit and replacing it in the same commit — separate them
-
-## Working with Agents
-
-When directing an agent to implement incrementally:
-
-```
-"Let's implement Task 3 from the plan.
-
-Start with just the database schema change and the API endpoint.
-Don't touch the UI yet — we'll do that in the next increment.
-
-After implementing, run `npm test` and `npm run build` to verify
-nothing is broken."
-```
-
-Be explicit about what's in scope and what's NOT in scope for each increment.
-
-## Increment Checklist
-
-After each increment, verify:
-
-- [ ] The change does one thing and does it completely
-- [ ] All existing tests still pass (`npm test`)
-- [ ] The build succeeds (`npm run build`)
-- [ ] Type checking passes (`npx tsc --noEmit`)
-- [ ] Linting passes (`npm run lint`)
-- [ ] The new functionality works as expected
-- [ ] The change is committed with a descriptive message
-
-## DevFlow 2.0 Progress Tracking
-
-During implementation, keep progress visible in markdown first:
-
-1. **Update `implement.md`**: Record the current slice, completed work, validation evidence, blockers, and next step.
-2. **Commit stage artifacts with code changes**: The implementation history should remain understandable from the repository, even without old dashboard tooling.
-
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
-| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. |
-| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |
-| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
-| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
-
-## Red Flags
-
-- More than 100 lines of code written without running tests
-- Multiple unrelated changes in a single increment
-- "Let me just quickly add this too" scope expansion
-- Skipping the test/verify step to move faster
-- Build or tests broken between increments
-- Large uncommitted changes accumulating
-- Building abstractions before the third use case demands it
-- Touching files outside the task scope "while I'm here"
-- Creating new utility files for one-time operations
-
-## Verification
-
-After completing all increments for a task:
-
-- [ ] Each increment was individually tested and committed
-- [ ] The full test suite passes
-- [ ] The build is clean
-- [ ] The feature works end-to-end as specified
-- [ ] No uncommitted changes remain

package/template/.agents/skills/insight-capture/SKILL.md

@@ -1,84 +0,0 @@
----
-name: insight-capture
-description: "[Devflow] Extract durable lessons, patterns, gotchas, and post-mortem knowledge from completed work. Use when implementation or verification work should become reusable team knowledge."
----
-
-# Insight Capture
-
-## Overview
-
-This skill is the shared behavior layer behind `Insight`.
-
-It preserves the valuable learning workflow from the legacy system while treating insight capture as a support capability rather than a numbered stage.
-
-## Related Foundation Skills
-
-This skill should reuse and align with:
-
-- `.agents/skills/9arm-skills/post-mortem/SKILL.md`
-- `.agent/resources/schemas/lessons.template.md`
-
-## When to Use
-
-- after `50-verify`, release preparation, or a completed implementation run
-- after debugging, regression fixes, or incidents that deserve durable learning
-- when reusable project knowledge should move into lessons, wiki material, or final reporting
-
-## Process
-
-### 1. Load Evidence
-
-Inspect only the evidence needed:
-
-- `implement.md`
-- `verify.md`
-- `release.md`
-- `report.md`
-- recent diff, commits, or review comments when relevant
-
-### 2. Extract Actionable Knowledge
-
-Capture only useful knowledge such as:
-
-- important file or behavior changes
-- reusable patterns
-- gotchas and triggers
-- approach outcome
-- alternatives tried
-- context loading waste or handoff overhead
-- recommendations for future runs
-
-### 3. Apply Post-Mortem When Needed
-
-For bug, regression, or incident work, use the `post-mortem` lens only after fix and validation evidence exist:
-
-- what broke
-- impact
-- repro or timeline
-- root cause
-- fix
-- validation evidence
-- why it slipped through
-- prevention or follow-up
-
-### 4. Save To The Smallest Durable Destination
-
-Prefer:
-
-- stage artifacts when the lesson is run-specific
-- `devflow/lessons.md` for project-wide knowledge
-- `Wiki` when the knowledge should become navigable team documentation
-- `60-report` when the lesson belongs in the final communication package before release
-
-When updating `devflow/lessons.md`, use `.agent/resources/schemas/lessons.template.md` and replace placeholder text completely.
-
-## Output
-
-Return:
-
-- lessons captured
-- patterns and gotchas
-- approach outcome
-- recommendations
-- where the insight was recorded
-- whether `Wiki` or `60-report` should be the next handoff

package/template/.agents/skills/intelligent-routing/SKILL.md

@@ -1,176 +0,0 @@
----
-name: intelligent-routing
-description: "[Devflow] Automatic agent and stage routing for DevFlow 2.0. Use when deciding which active workflow, skill, or specialist should own the next step."
-version: 2.0.0
----
-
-# Intelligent Routing For DevFlow 2.0
-
-## Purpose
-
-Analyze a user request and route it to the correct DevFlow 2.0 surface without requiring the user to name the exact workflow, skill, or agent.
-
-## Canonical Routing Order
-
-Always route in this order:
-
-1. Mainline stage if the request is lifecycle work
-2. Public companion command if the request is support work
-3. Specialist agent if the user needs focused expert judgment
-4. Internal companion or skill only when the public surface should stay thin
-
-Do not route new work into retired JSON-first commands, dashboard-first flows, or removed aliases.
-
-When routing to support skills, follow `docs/skill-selection-policy.md`.
-
-## Timeline Stages
-
-`00-discover -> 10-define -> 20-spec -> 30-plan -> 40-implement -> 50-verify -> 60-report -> 70-release`
-
-## Public Companion Commands
-
-- `Goal`
-- `Brainstorm`
-- `Research`
-- `Debug`
-- `PRD`
-- `Issue-Triage`
-- `Wiki`
-- `Check-For-Updates`
-- `Help`
-
-## Specialist Agent Routing
-
-Use these agent mappings when expert judgment is the best next step:
-
-| Request Type | Route To |
-|---|---|
-| requirements clarification | `requirements-engineer` |
-| product framing | `prp-core-prd-architect` |
-| planning breakdown | `prp-core-planner` |
-| codebase exploration | `codebase-explorer` |
-| backend implementation or API review | `backend-specialist` |
-| frontend implementation or UI review | `frontend-specialist` |
-| schema and query design | `database-architect` |
-| implementation execution | `prp-core-coder` |
-| tests and coverage | `test-engineer` |
-| code review and risk review | `code-reviewer` |
-| security review | `security-auditor` |
-| performance review | `performance-engineer` |
-| root-cause debugging | `prp-core-debugger` |
-| release packaging and commit scope | `prp-core-git-committer`, `prp-core-git-pr-maker` |
-| broad orchestration across domains | `orchestrator` |
-| overnight maintenance loops and repo cleanup | `ob-loop-engineer` |
-
-## Lifecycle Routing Rules
-
-| User State | Recommended Route |
-|---|---|
-| new request, vague or clear | `00-discover`; it selects support inquiry and owns the delivery decision |
-| approved discovery needs one or more delivery boundaries | `10-define {discovery_id}` |
-| needs requirements and acceptance criteria | `20-spec` |
-| has a stable spec and needs execution plan | `30-plan` |
-| needs implementation work | `40-implement` |
-| needs testing, review, or validation evidence | `50-verify` |
-| needs packaging, commit, PR, or release handling | `70-release` |
-| needs the final summary or handoff narrative | `60-report` |
-
-## Routing Heuristics
-
-### Use a Timeline stage when:
-
-- the request advances a task through its lifecycle
-- the user needs an artifact in `devflow`
-- the next step should change stage ownership
-
-### Use a public companion command when:
-
-- the request supports a stage rather than replacing it
-- the user needs exploration, research, debugging, or help
-- the output is advisory or investigative
-
-### Use an internal clarification skill when:
-
-- the current stage is blocked by ambiguity, not by missing execution effort
-- a small amount of user interaction could change scope, acceptance criteria, or planning decisions
-- the public surface should stay the same and the questioning method is only supporting the active stage
-
-If `grill-with-docs` is available in the current environment, prefer it as an optional internal support skill for:
-
-- `10-define` when scope or terminology is unstable
-- `20-spec` when acceptance criteria or rules are ambiguous
-- `30-plan` when architecture or verification choices are still reversible but unclear
-
-Do not use deep questioning by default in every stage. Collect only the information that affects the current Timeline-stage decision.
-
-### Use an internal clarification skill when:
-
-- the current stage is blocked by ambiguity, not by missing execution effort
-- a small amount of user interaction could change scope, acceptance criteria, or planning decisions
-- the public surface should stay the same and the questioning method is only supporting the active stage
-
-If `grill-with-docs` is available in the current environment, prefer it as an optional internal support skill for:
-
-- `10-define` when scope or terminology is unstable
-- `20-spec` when acceptance criteria or rules are ambiguous
-- `30-plan` when architecture or verification choices are still reversible but unclear
-
-Do not use deep questioning by default in every stage. Collect only the information that affects the current stage decision.
-
-### Use a specialist agent when:
-
-- the user explicitly asks for one
-- a narrow expert lens is more useful than a workflow shell
-- the active stage already exists and only specialist judgment is missing
-
-### Use a support skill when:
-
-- a mainline stage or public companion already owns the work
-- the skill resolves a bounded uncertainty inside that owner
-- the skill is more specific than the general companion surface
-- the skill output can be captured in the owning stage artifact, `CONTEXT.md`, an ADR, or a focused doc
-
-Support skill limits:
-
-- choose one primary skill per pass
-- add at most two secondary skills when each has a distinct purpose
-- prefer the most specific skill when descriptions overlap
-- route back to the owning stage when a skill finds a lifecycle-level contradiction
-
-Key conflict defaults:
-
-| Conflict | Route |
-|---|---|
-| `Brainstorm` vs `grilling` | `Brainstorm` for option generation; `grilling` for stress-testing a candidate idea |
-| `grilling` vs `grill-with-docs` | `grill-with-docs` when a codebase or durable docs matter |
-| `grill-with-docs` vs `domain-modeling` | `grill-with-docs` interviews; `domain-modeling` records confirmed glossary terms or ADRs |
-| `to-prd` vs `PRD` | `PRD` owns the public surface; `to-prd` is an internal synthesis method |
-| `to-issues` vs `30-plan` | `30-plan` owns work breakdown; `to-issues` packages slices when issue tracker output is needed |
-| `implement` vs `40-implement` | `40-implement` owns implementation |
-| `review` vs `50-verify` | `50-verify` owns verification; `review` is one lane |
-
-## Examples
-
-| User Request | Route |
-|---|---|
-| "I have an idea but not the shape yet" | `00-discover`, likely `Brainstorm`, then return to Discover |
-| "Turn this stable new goal into requirements" | `00-discover`, then `10-define {discovery_id}` before `20-spec {running_id}` |
-| "Fix this newly reported broken auth flow" | `00-discover`, likely `Debug`, then return to Discover before Define |
-| "Review this implementation for risks" | `50-verify` or `Agent code-reviewer ...` |
-| "Install or upgrade Nexus-DevFlow on this machine" | `Check-For-Updates` |
-| "Help me figure out which command to use" | `Help` |
-
-## Guardrails
-
-- Do not recommend removed numeric aliases such as old task/code/verify commands.
-- Do not mention legacy external control files as part of the routing model.
-- Do not invent agent names that are not present in the current repo.
-- If the request spans multiple domains and the owner is unclear, route to `orchestrator`.
-- If clarification is needed, ask only for information that can change the active stage decision.
-- If clarification is needed, ask only for information that can change the active stage decision.
-
-## Output Pattern
-
-When applying this skill, answer in one short line before proceeding:
-
-`Applying DevFlow 2.0 routing: <chosen route> because <reason>.`

package/template/.agents/skills/md2html/SKILL.md

@@ -1,154 +0,0 @@
----
-name: md2html
-description: "[Devflow] Convert long-form Markdown (plan, spec, system design, RFC, runbook, postmortem, brainstorm, notes) into a single self-contained HTML page with Mermaid diagrams, step timelines, callouts, sidebar TOC. Claude-orange light+dark theme. Multi-language. Portable across Claude Code / Codex / Antigravity / any AI agent."
-trigger: /md2html
----
-
-# /md2html
-
-Convert a verbose Markdown document into a single, self-contained HTML file that a tired human can actually scan: diagrams instead of paragraphs, step cards instead of numbered lists, callouts for the parts that matter.
-
-## Usage
-
-```
-/md2html <file.md>             # output <file>.html next to source
-/md2html <file.md> --out X.html # custom output path
-/md2html                       # if no arg, ask user which file
-```
-
-## Skill files (resolved relative to this SKILL.md)
-
-- `template.html`   — HTML skeleton with embedded CSS (Claude orange light+dark), Mermaid CDN, theme toggle, TOC sidebar, footer. Contains `{{PLACEHOLDER}}` strings and `<!-- COMMENT -->` slots.
-- `components.md`  — catalog of HTML snippets you must copy verbatim (step cards, callouts, mermaid blocks, pros-cons, comparison cards, collapsibles).
-- `examples/`     — at least one reference `<doc>.md` → `<doc>.html` pair. Read one to calibrate output quality before starting.
-
-**You MUST read all three before writing output.** Do not invent CSS classes or skip the catalog.
-
-## What you must do when invoked
-
-Follow these steps in order. Do not skip.
-
-### Step 1 — Resolve inputs
-
-1. Determine the source file from the user's invocation. If none given, ask: *"Tệp `.md` nào cần convert?"* and stop.
-2. Read the source `.md` fully.
-3. Read `template.html` and `components.md` from the same directory as this SKILL.md.
-4. Read one example pair under `examples/` to calibrate.
-
-### Step 2 — Analyze the source document
-
-Do this analysis silently in your head (or as one short summary line to the user). Identify:
-
-- **Language of the source** — detect from the actual prose, not the filename. Set `<html lang="...">` to the ISO 639-1 code (`en`, `vi`, `zh`, `ja`, `ko`, `es`, `fr`, `de`, `ru`, `ar`, `th`, …) and translate every UI label to that language.
-
-  Common samples (extend to any language using the same scheme):
-
-  | Key            | EN                 | VI                 | ZH (中文)           | JA (日本語)         | KO (한국어)         | ES (Español)        |
-  |---             |---                 |---                 |---                  |---                  |---                  |---                  |
-  | TOC title      | Contents           | Mục lục            | 目录                | 目次                | 목차                | Contenido           |
-  | Read-time      | ~N min read        | ~N phút đọc        | ~N 分钟阅读         | ~N 分で読了         | ~N분 소요           | ~N min de lectura   |
-  | Recommended    | ★ Recommended      | ★ Đề xuất          | ★ 推荐              | ★ 推奨              | ★ 추천              | ★ Recomendado       |
-  | Key point      | Key point          | Ý chính            | 要点                | 要点                | 핵심                | Idea clave          |
-  | Pros           | ✓ Pros             | ✓ Ưu điểm          | ✓ 优点              | ✓ 長所              | ✓ 장점              | ✓ Ventajas          |
-  | Cons           | ✕ Cons             | ✕ Nhược điểm       | ✕ 缺点              | ✕ 短所              | ✕ 단점              | ✕ Desventajas       |
-  | Print tooltip  | Print / Save PDF   | In / Lưu PDF       | 打印 / 保存 PDF     | 印刷 / PDF 保存     | 인쇄 / PDF 저장     | Imprimir / Guardar  |
-  | Theme tooltip  | Toggle theme       | Đổi theme          | 切换主题            | テーマ切替          | 테마 전환           | Cambiar tema        |
-  | Source: prefix | Source:            | Nguồn:             | 来源:               | ソース:             | 소스:               | Fuente:             |
-
-  For any language not listed, translate using the same conventions. The "Recommended" badge is configured via the `--rec-label` CSS variable set on `<html>` (no per-language CSS needed) — see `{{REC_LABEL}}` below.
-
-  **RTL languages** (Arabic, Hebrew, Persian) — current template is LTR-only. If source is RTL, also add `dir="rtl"` to `<html>` and consider it a known visual limitation (sidebar will stay on the left).
-
-- **Title** — from first H1 or filename. Title should be ≤ 80 chars.
-- **Subtitle** — first paragraph after H1, or the document's TL;DR sentence. ≤ 200 chars.
-- **Doc type** — infer one of: `PLAN`, `SPEC`, `SYSTEM DESIGN`, `RFC`, `RUNBOOK`, `POSTMORTEM`, `BRAINSTORM`, `NOTES`. Pick the closest match based on the document's *purpose*, not its filename. Brainstorm = exploring options with rationale; Plan = ordered steps to a goal; Spec = exact behavior contract; System design = architecture + tradeoffs; RFC = proposal seeking feedback; Runbook = operational procedure; Postmortem = incident review. The uppercase code in the eyebrow stays universal; the topbar `BRAND_LABEL` localizes (Plan / Kế hoạch / 计划 / etc).
-- **Reading time** — words ÷ 250, round to nearest minute. Format: `~N min read` (EN) or `~N phút đọc` (VI).
-- **Section map** — walk each H2/H3 and tag with the BEST component using §11 cheatsheet in `components.md`:
-  - numbered action list → Timeline
-  - architecture/flow prose → Mermaid
-  - "ưu/nhược", "pros/cons" → Pros-Cons
-  - "option A vs B" → Comparison cards
-  - critical conclusion → Key-point highlight
-  - warnings/decisions → Callouts
-  - long appendix → Collapsible
-  - everything else → plain `<h2>` + `<p>`
-
-### Step 3 — Build the output HTML
-
-1. **Copy** the full `template.html` content into a string. Do NOT use Read-then-Edit on a file you haven't created; instead, build the output buffer in memory then `Write` once.
-2. **Replace placeholders** in the template (all values come from Step 2 analysis, language-matched):
-   - `{{LANG}}` → ISO 639-1 code: `en` / `vi` / `zh` / `ja` / `ko` / `es` / …
-   - `{{REC_LABEL}}` → text shown on the "Recommended" comparison-card badge, e.g. `★ Recommended` / `★ Đề xuất` / `★ 推荐` / `★ 추천`. Sets the `--rec-label` CSS variable on `<html>`. If you forget this, CSS falls back to `★ Recommended`.
-   - `{{TITLE}}` (appears twice: `<title>` and `.doc-title`)
-   - `{{SUBTITLE}}`
-   - `{{DOC_TYPE}}` → universal uppercase code: `PLAN`, `SPEC`, `SYSTEM DESIGN`, `RFC`, `RUNBOOK`, `POSTMORTEM`, `BRAINSTORM`, `NOTES`
-   - `{{SOURCE_FILE}}` → basename of source (e.g. `plan.md`)
-   - `{{DATE}}` → ISO date or localized "Updated <today>"
-   - `{{READ_TIME}}` → localized reading time, e.g. `~3 min read` / `~3 phút đọc` / `~3 分钟阅读`
-   - `{{BRAND_LABEL}}` → localized doc-type label for the topbar
-   - `{{TOC_TITLE}}` → localized "Contents" (also used as `aria-label` for the TOC drawer)
-   - `{{PRINT_TOOLTIP}}` → localized print tooltip
-   - `{{THEME_TOOLTIP}}` → localized theme-toggle tooltip
-   - `{{CLOSE_LABEL}}` → localized "Close" (used for the mobile TOC drawer close button), e.g. `Close` / `Đóng` / `关闭` / `閉じる`
-   - `{{SKIP_LINK_LABEL}}` → localized skip-to-content link text, e.g. `Skip to content` / `Bỏ qua menu` / `跳到正文`
-   - `{{FOOTER_NOTE}}` → localized source attribution (e.g. `Source: plan.md` / `Nguồn: plan.md` / `来源: plan.md`)
-3. **Replace `<!-- TOC_ENTRIES -->`** with one `<a>` per H2/H3 (see §2 in components.md). Generate stable kebab-case `id` from heading text.
-4. **Replace the slot between `<!-- CONTENT_START -->` and `<!-- CONTENT_END -->`** with the document body, section by section, using components from `components.md`. Each section must:
-   - Start with `<h2 id="..."> ` (matching the TOC entry).
-   - Use ONE primary component per logical chunk (don't stack 3 callouts in a row).
-   - Preserve original meaning — do not summarize away technical detail; condense only filler/repetition.
-5. **Write** the assembled HTML to the output path.
-
-### Step 4 — Verify
-
-After writing, do ONE quick sanity check by re-reading just the section you generated (not the whole file):
-- Every `id="..."` referenced in the TOC exists on a heading.
-- No leftover `{{PLACEHOLDER}}` strings.
-- Mermaid blocks have valid syntax (use `flowchart`, `sequenceDiagram`, `erDiagram`, `stateDiagram-v2`, or `gantt` — never bare `graph` without direction).
-- No `<script>` tags added beyond what `template.html` already includes.
-
-Report back to the user with:
-- Output file path
-- 1-line summary of what changed (e.g. *"Rendered 7 sections: 1 mermaid flow, 2 step timelines, 4 callouts. ~6 phút đọc."*)
-- A reminder they can open it with `xdg-open <file>.html` (Linux) / `open <file>.html` (mac).
-
-## Critical rules
-
-1. **Never paraphrase technical content into vague prose.** A step `chạy migration 0042_user_schema.sql` must remain that exact filename — don't change to `chạy migration mới`.
-2. **One component per chunk.** Don't wrap a callout inside a step card inside a collapsible. Keep nesting flat.
-3. **Mermaid > prose for any flow ≥ 3 hops.** If the source says "A gọi B, B gọi C, C ghi DB", make a diagram.
-4. **Key-point highlights are rare.** Max 1 per H2 section, ideally 2-3 total per document.
-5. **UI text follows the detected source language** — including for non-EN/non-VI sources (Chinese, Japanese, Korean, Spanish, etc). Use the language sample table in Step 2 or translate equivalently. Code, commands, file names, library names, error messages stay verbatim regardless of language.
-6. **Self-contained output.** No external file references except the CDN scripts already in `template.html`.
-7. **Do not modify `template.html` or `components.md`** — those are the skill's source of truth. Only Write the output `.html`.
-8. **Use SVG icons only — never emojis.** Every icon is `<svg class="..."><use href="#i-NAME"/></svg>` referencing the sprite at the top of `<body>`. See §13 in `components.md` for the catalog. No emoji glyphs anywhere in callouts, doc-meta, topbar, or body content.
-9. **Anchor links and copy-to-clipboard auto-inject via JS** — do NOT add them manually. Just give H2/H3 a proper `id`, and put code in `<pre><code>`. The template's boot script handles the rest.
-10. **Wrap wide tables in `.table-wrap`** — see components.md §14b. Tables ≥ 4 columns or with long cells need the wrapper for mobile scroll.
-11. **Use `<figure>` + `<figcaption>` for images** with descriptive `alt`. See components.md §14a.
-
-## Cross-AI compatibility
-
-This skill is designed to run identically on:
-
-- **Claude Code** — install at `~/.claude/skills/md2html/` (this directory, symlinked or copied). Invoke with `/md2html <file>`.
-- **Codex CLI** — copy `SKILL.md` content to `~/.codex/prompts/md2html.md`, keep `template.html` and `components.md` at a stable absolute path, update the file references in SKILL.md if needed. Invoke with `/md2html`.
-- **Antigravity** — add SKILL.md as a custom prompt/agent instruction, ensure the agent has Read/Write tool access to the skill folder.
-
-The only external dependency is `mermaid` via CDN (resolved at HTML open time, not at skill execution time). No npm/pip install required for the skill itself.
-
-## Edge cases
-
-- **Source has no headings** — wrap content in one `<h2 id="content">Nội dung</h2>` and infer logical breaks from blank lines + topic shifts.
-- **Source has existing mermaid code blocks** — keep them, just rewrap in `<figure class="diagram">` with caption.
-- **Source has HTML embedded** — pass through as-is inside `<div>` if safe, else escape.
-- **Source is very short (< 200 words)** — skip TOC sidebar (delete `<aside class="toc">` block), render as single column.
-- **Source is very long (> 5000 words)** — collapse low-priority sections by default with `<details>`.
-- **Output file already exists** — overwrite. The source `.md` is canonical; HTML is regenerated artifact.
-
-## Anti-patterns
-
-- ❌ Generating the HTML in many small Edit calls — produces drift. Build full string, Write once.
-- ❌ Adding new CSS via `<style>` — extend `template.html` instead and tell the user.
-- ❌ Translating proper nouns or code identifiers.
-- ❌ "Improving" the source by adding info not in the original.
-- ❌ Reporting success without running Step 4 verification.