@jakkrichm/create-nexus-devflow 2.0.0

package/template/.agents/skills/mcp-builder/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: mcp-builder
+description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# MCP Builder
+
+> Principles for building MCP servers.
+
+---
+
+## 1. MCP Overview
+
+### What is MCP?
+
+Model Context Protocol - standard for connecting AI systems with external tools and data sources.
+
+### Core Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| **Tools** | Functions AI can call |
+| **Resources** | Data AI can read |
+| **Prompts** | Pre-defined prompt templates |
+
+---
+
+## 2. Server Architecture
+
+### Project Structure
+
+```
+my-mcp-server/
+├── src/
+│   └── index.ts      # Main entry
+├── package.json
+└── tsconfig.json
+```
+
+### Transport Types
+
+| Type | Use |
+|------|-----|
+| **Stdio** | Local, CLI-based |
+| **SSE** | Web-based, streaming |
+| **WebSocket** | Real-time, bidirectional |
+
+---
+
+## 3. Tool Design Principles
+
+### Good Tool Design
+
+| Principle | Description |
+|-----------|-------------|
+| Clear name | Action-oriented (get_weather, create_user) |
+| Single purpose | One thing well |
+| Validated input | Schema with types and descriptions |
+| Structured output | Predictable response format |
+
+### Input Schema Design
+
+| Field | Required? |
+|-------|-----------|
+| Type | Yes - object |
+| Properties | Define each param |
+| Required | List mandatory params |
+| Description | Human-readable |
+
+---
+
+## 4. Resource Patterns
+
+### Resource Types
+
+| Type | Use |
+|------|-----|
+| Static | Fixed data (config, docs) |
+| Dynamic | Generated on request |
+| Template | URI with parameters |
+
+### URI Patterns
+
+| Pattern | Example |
+|---------|---------|
+| Fixed | `docs://readme` |
+| Parameterized | `users://{userId}` |
+| Collection | `files://project/*` |
+
+---
+
+## 5. Error Handling
+
+### Error Types
+
+| Situation | Response |
+|-----------|----------|
+| Invalid params | Validation error message |
+| Not found | Clear "not found" |
+| Server error | Generic error, log details |
+
+### Best Practices
+
+- Return structured errors
+- Don't expose internal details
+- Log for debugging
+- Provide actionable messages
+
+---
+
+## 6. Multimodal Handling
+
+### Supported Types
+
+| Type | Encoding |
+|------|----------|
+| Text | Plain text |
+| Images | Base64 + MIME type |
+| Files | Base64 + MIME type |
+
+---
+
+## 7. Security Principles
+
+### Input Validation
+
+- Validate all tool inputs
+- Sanitize user-provided data
+- Limit resource access
+
+### API Keys
+
+- Use environment variables
+- Don't log secrets
+- Validate permissions
+
+---
+
+## 8. Configuration
+
+### Claude Desktop Config
+
+| Field | Purpose |
+|-------|---------|
+| command | Executable to run |
+| args | Command arguments |
+| env | Environment variables |
+
+---
+
+## 9. Testing
+
+### Test Categories
+
+| Type | Focus |
+|------|-------|
+| Unit | Tool logic |
+| Integration | Full server |
+| Contract | Schema validation |
+
+---
+
+## 10. Best Practices Checklist
+
+- [ ] Clear, action-oriented tool names
+- [ ] Complete input schemas with descriptions
+- [ ] Structured JSON output
+- [ ] Error handling for all cases
+- [ ] Input validation
+- [ ] Environment-based configuration
+- [ ] Logging for debugging
+
+---
+
+> **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.

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

@@ -0,0 +1,154 @@
+---
+name: md2html
+description: 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.