agent-harness-kit 0.9.0 → 0.10.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.9.0"
+        "ref": "v0.10.0"
       },
-      "version": "0.9.0",
+      "version": "0.10.0",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/README.md

@@ -59,8 +59,9 @@ Option B: install as a Claude Code plugin
 | `/add-adr`                       | Add a numbered Architecture Decision Record              |
 | `/doc-drift-scan`                | Find stale path/command references in `docs/`            |
 | `/debug-flow`                    | Run the failing flow before fixing it                    |
+| `/deliver-html`                  | Ship an analysis/audit/plan as a self-contained HTML     |
 
-## Philosophy (4 axioms)
+## Philosophy (5 axioms)
 
 1. **CLAUDE.md is a table of contents, not an encyclopedia** (HumanLayer
    measured ~150–200 instructions as the reliable cap; OpenAI's own root file
@@ -76,6 +77,15 @@ Option B: install as a Claude Code plugin
    differentiator — see [Honest expectations](#honest-expectations).
 4. **Garbage collection over Friday cleanup, scaled to solo** (OpenAI's
    ritual, shrunk to top-3 fixes per week).
+5. **HTML for human deliverables, Markdown for agent files.** Markdown is
+   the right format for files an agent reads-and-edits (CLAUDE.md, SKILL.md,
+   ADRs); HTML is the right format for documents a HUMAN reads-and-decides
+   (audit reports, analyses, plans, decision docs). A long Markdown
+   deliverable invites the human to scroll, miss the conclusion, and ask the
+   agent to clarify — burning more tokens than the HTML markup costs. The
+   `/deliver-html` skill writes self-contained HTML at repo root with a
+   shared dark-theme CSS; the rule is documented in golden principle #11 and
+   ADR-0002.
 
 ## Directory the kit drops into your repo
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {

package/src/templates/.claude/skills/deliver-html/SKILL.md.hbs

@@ -0,0 +1,96 @@
+---
+name: deliver-html
+description: Use this skill whenever the user asks to analyze, audit, review, summarize, produce a report, write a plan, make a proposal, draft a decision doc, list "next actions", or any other task that produces a DOCUMENT a HUMAN reads-and-acts-on. Outputs a self-contained <slug>.html at repo root using the shared dark-theme CSS. Why HTML and not Markdown: golden principle #9 — Markdown is great for files an agent reads-and-edits (CLAUDE.md, SKILL.md, ADRs), but a HUMAN reading a 700-line MD deliverable will scroll, miss the conclusion, and ask the agent to clarify — burning turns and tokens. HTML deliverable is read once, decided once. Do NOT use this skill for files the agent itself reads (those stay MD), for stdout output from /review-this-pr or /garbage-collection (pass-through MD), or for short summaries under ~30 lines (overhead not worth it).
+allowed-tools: Read, Write, Bash(node .claude/skills/deliver-html/scripts/wrap-html.mjs:*), Bash(cat:*), Bash(ls:*)
+suggested-turns: 6
+---
+
+## When to use
+
+Trigger words from the user (English / Vietnamese):
+
+- "analyze X", "audit X", "review X for me" / "phân tích X", "audit X", "review giúp tôi"
+- "produce a report on X" / "báo cáo về X", "tổng kết X"
+- "plan for X", "proposal for X", "decision doc for X" / "plan cho X", "đề xuất X"
+- "what should we do about X", "next actions for X" / "next actions cho X"
+
+Do **NOT** use for:
+
+- Editing `CLAUDE.md`, `SKILL.md`, `docs/*.md`, or any agent-read file (those stay MD).
+- Pass-through stdout from `/review-this-pr`, `/garbage-collection`, `/inspect-module` (the agent itself consumes that — keep it MD).
+- Short summaries (< 30 lines of body). Just answer inline.
+- Files that will be diffed in a PR. Source-of-truth stays MD.
+
+## Steps
+
+1. **Pick a template** based on what the user is asking for:
+   - `decision-doc` (default) — analysis + recommendation + next actions
+   - `audit-report` — findings table with severity, current vs. target state
+   - `status-report` — shipped progress + remaining work + KPIs
+
+2. **Write the MD body** in working memory. Use standard GitHub-flavored
+   Markdown: `#`/`##`/`###` headings, paragraphs, `-`/`1.` lists, fenced
+   ```` ```code``` ````, `> blockquote`, `| a | b |` tables, and inline
+   `code`/`**bold**`/`*italic*`/`[link](url)`.
+
+   You may also use these CSS hooks via raw HTML for richer visuals:
+   - `<div class="card good|warn|bad|info|next">…</div>` — bordered callout
+   - `<span class="pill good|warn|bad|info|alt">P0</span>` — inline badge
+   - `<div class="grid2|grid3">…</div>` — column layout
+   - `<div class="stat good|warn|info"><div class="lbl">…</div><div class="num">…</div></div>` — stat tile
+
+3. **Pick a slug** (kebab-case, derived from title). Default: same dir as
+   CWD (repo root). Example: title "Phân tích auth flow" → file
+   `phan-tich-auth-flow.html`.
+
+4. **Render** with the side-car script:
+
+   ```bash
+   node .claude/skills/deliver-html/scripts/wrap-html.mjs \
+     --title "Phân tích auth flow" \
+     --subtitle "Bằng chứng, lập luận, next actions" \
+     --template decision-doc \
+     --in /tmp/body.md \
+     --out phan-tich-auth-flow.html
+   ```
+
+   The script:
+   - Reads `assets/report.css` (single source of truth for the style).
+   - Auto-detects locale from `harness.config.json` `.claudeMd.humanLanguage` (override with `--lang`).
+   - Converts MD → HTML (self-rolled subset: headings, lists, code blocks,
+     tables, blockquotes, links, inline formatting — no npm dependency).
+   - Writes `<slug>.html` at the path you pass.
+
+5. **Print the deliverable contract** (the script already does this — copy it
+   into your response):
+
+   ```
+   ### Deliverable
+   **File:** <path>  (<size>)
+   **Template:** decision-doc | audit-report | status-report
+   **Lang:** vi | en
+   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   ```
+
+## Output contract
+
+The script writes exactly one file (`<slug>.html`) at the requested path and
+prints the deliverable contract on stdout. The HTML is self-contained
+(CSS inlined) so it can be emailed / sent on Slack / attached to a PR with no
+dependencies.
+
+## Anti-patterns
+
+- **Don't write raw HTML markup in your MD body** beyond the CSS hook
+  patterns above (cards, pills, grids, stats). The wrap script handles the
+  document chrome — your job is content.
+- **Don't inline `<style>` blocks in the body.** The wrap script injects
+  shared CSS once. Inline overrides drift over time.
+- **Don't use this skill for `docs/*.md` updates.** Those are agent-read;
+  they stay MD per principle #9.
+- **Don't claim "done" without writing the file.** The deliverable IS the
+  file. If `wrap-html.mjs` errored, do not move on.
+- **Don't open a deliverable shorter than ~30 lines as HTML.** A short
+  answer belongs in the chat response, not a file.
+- **Don't translate the CSS.** Style is locale-agnostic. Only the `lang`
+  attribute and body copy localize.

package/src/templates/.claude/skills/deliver-html/SKILL.md.vi.hbs

@@ -0,0 +1,89 @@
+---
+name: deliver-html
+description: Use this skill whenever the user asks to analyze, audit, review, summarize, produce a report, write a plan, make a proposal, draft a decision doc, list "next actions", or any other task that produces a DOCUMENT a HUMAN reads-and-acts-on. Outputs a self-contained <slug>.html at repo root using the shared dark-theme CSS. Why HTML and not Markdown: golden principle #9 — Markdown is great for files an agent reads-and-edits (CLAUDE.md, SKILL.md, ADRs), but a HUMAN reading a 700-line MD deliverable will scroll, miss the conclusion, and ask the agent to clarify — burning turns and tokens. HTML deliverable is read once, decided once. Do NOT use this skill for files the agent itself reads (those stay MD), for stdout output from /review-this-pr or /garbage-collection (pass-through MD), or for short summaries under ~30 lines (overhead not worth it).
+allowed-tools: Read, Write, Bash(node .claude/skills/deliver-html/scripts/wrap-html.mjs:*), Bash(cat:*), Bash(ls:*)
+suggested-turns: 6
+---
+
+## Khi nào dùng
+
+Trigger keyword từ user (tiếng Việt / English):
+
+- "phân tích X", "audit X", "review giúp tôi" / "analyze X", "audit X", "review X for me"
+- "báo cáo về X", "tổng kết X" / "produce a report on X"
+- "plan cho X", "đề xuất X", "decision doc cho X" / "plan for X", "proposal for X"
+- "next actions cho X", "ta nên làm gì với X"
+
+**KHÔNG** dùng cho:
+
+- Chỉnh sửa `CLAUDE.md`, `SKILL.md`, `docs/*.md`, hoặc bất kỳ file agent đọc (giữ MD).
+- Output stdout từ `/review-this-pr`, `/garbage-collection`, `/inspect-module` (agent tự consume — giữ MD).
+- Tóm tắt ngắn (< 30 dòng body). Trả lời inline.
+- File sẽ được diff trong PR. Source-of-truth phải MD.
+
+## Các bước
+
+1. **Chọn template** theo yêu cầu user:
+   - `decision-doc` (mặc định) — phân tích + đề xuất + next actions
+   - `audit-report` — bảng findings có severity, trạng thái hiện tại vs. mong muốn
+   - `status-report` — đã ship + còn lại + KPI
+
+2. **Viết body bằng MD** trong working memory. Dùng GitHub-flavored Markdown
+   thông thường: `#`/`##`/`###` headings, paragraph, `-`/`1.` list, fenced
+   ```` ```code``` ````, `> blockquote`, `| a | b |` table, inline
+   `code`/`**bold**`/`*italic*`/`[link](url)`.
+
+   Có thể nhúng các CSS hook qua raw HTML cho visual tốt hơn:
+   - `<div class="card good|warn|bad|info|next">…</div>` — callout viền màu
+   - `<span class="pill good|warn|bad|info|alt">P0</span>` — badge inline
+   - `<div class="grid2|grid3">…</div>` — bố cục cột
+   - `<div class="stat good|warn|info"><div class="lbl">…</div><div class="num">…</div></div>` — ô số liệu
+
+3. **Chọn slug** (kebab-case từ title). Default: cùng thư mục CWD (repo root).
+   Ví dụ: title "Phân tích auth flow" → file `phan-tich-auth-flow.html`.
+
+4. **Render** bằng side-car script:
+
+   ```bash
+   node .claude/skills/deliver-html/scripts/wrap-html.mjs \
+     --title "Phân tích auth flow" \
+     --subtitle "Bằng chứng, lập luận, next actions" \
+     --template decision-doc \
+     --in /tmp/body.md \
+     --out phan-tich-auth-flow.html
+   ```
+
+   Script sẽ:
+   - Đọc `assets/report.css` (single source of truth cho style).
+   - Auto-detect locale từ `harness.config.json` `.claudeMd.humanLanguage` (override bằng `--lang`).
+   - Convert MD → HTML (self-rolled subset: heading, list, code block, table,
+     blockquote, link, inline format — không cần npm dependency).
+   - Ghi `<slug>.html` tại path bạn truyền.
+
+5. **In deliverable contract** (script tự in — bạn copy vào response):
+
+   ```
+   ### Deliverable
+   **File:** <path>  (<size>)
+   **Template:** decision-doc | audit-report | status-report
+   **Lang:** vi | en
+   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   ```
+
+## Output contract
+
+Script ghi đúng 1 file (`<slug>.html`) tại path đã yêu cầu và in deliverable
+contract ra stdout. HTML self-contained (CSS inline) nên có thể gửi qua email
+/ Slack / đính kèm PR mà không cần dependency.
+
+## Anti-patterns
+
+- **Đừng viết raw HTML trong MD body** ngoài các CSS hook đã liệt kê
+  (cards, pills, grids, stats). Wrap script lo phần document chrome — bạn lo nội dung.
+- **Đừng inline `<style>` trong body.** Wrap script inject shared CSS một lần.
+  Inline override sẽ drift theo thời gian.
+- **Đừng dùng skill này cho `docs/*.md`.** Đó là agent-read; giữ MD theo principle #9.
+- **Đừng claim "xong" mà chưa ghi file.** Deliverable CHÍNH LÀ cái file.
+  Nếu `wrap-html.mjs` lỗi, dừng — không chuyển bước.
+- **Đừng tạo HTML cho output < 30 dòng.** Câu ngắn → trả lời inline trong chat.
+- **Đừng dịch CSS.** Style là locale-agnostic. Chỉ `lang` attribute và body copy localize.

package/src/templates/.claude/skills/deliver-html/assets/report.css

@@ -0,0 +1,233 @@
+/* report.css — single source of truth for deliver-html HTML output.
+ *
+ * Extracted from NEXT_ACTIONS.html / PHAN_TICH.html so every deliverable
+ * shares the same dark Github-flavored look. Edit here, every future HTML
+ * deliverable picks it up. Existing HTML files at repo root keep inline
+ * copies (self-contained shipping artefacts — see ADR-0002).
+ */
+
+:root {
+  --bg: #0f1419;
+  --panel: #161b22;
+  --panel2: #1c2128;
+  --border: #30363d;
+  --text: #e6edf3;
+  --muted: #8b949e;
+  --accent: #58a6ff;
+  --accent2: #a371f7;
+  --good: #3fb950;
+  --warn: #d29922;
+  --bad: #f85149;
+  --code-bg: #1c2128;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: var(--bg); color: var(--text); }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  line-height: 1.65;
+  font-size: 16px;
+}
+.wrap { max-width: 1180px; margin: 0 auto; padding: 32px 24px 80px; }
+
+/* ----- Hero ----- */
+header.hero {
+  border: 1px solid var(--border);
+  background: linear-gradient(180deg, #161b22 0%, #0f1419 100%);
+  border-radius: 14px;
+  padding: 30px 36px;
+  margin-bottom: 28px;
+  position: relative;
+}
+header.hero::after {
+  content: attr(data-badge);
+  position: absolute;
+  top: 24px;
+  right: 32px;
+  background: rgba(163, 113, 247, 0.15);
+  color: var(--accent2);
+  border: 1px solid rgba(163, 113, 247, 0.5);
+  border-radius: 6px;
+  padding: 4px 12px;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+}
+header.hero[data-badge-tone="good"]::after {
+  color: var(--good);
+  background: rgba(63, 185, 80, 0.15);
+  border-color: rgba(63, 185, 80, 0.5);
+}
+header.hero[data-badge-tone="warn"]::after {
+  color: var(--warn);
+  background: rgba(210, 153, 34, 0.15);
+  border-color: rgba(210, 153, 34, 0.5);
+}
+header.hero[data-badge-tone="bad"]::after {
+  color: var(--bad);
+  background: rgba(248, 81, 73, 0.15);
+  border-color: rgba(248, 81, 73, 0.5);
+}
+header.hero h1 { margin: 0 0 8px; font-size: 30px; letter-spacing: -0.02em; }
+header.hero .sub { color: var(--muted); margin: 0 0 16px; font-size: 15px; }
+header.hero .meta {
+  display: flex;
+  gap: 22px;
+  flex-wrap: wrap;
+  font-size: 13px;
+  color: var(--muted);
+}
+header.hero .meta span strong { color: var(--text); }
+header.hero .tldr {
+  margin-top: 18px;
+  padding: 14px 18px;
+  background: rgba(88, 166, 255, 0.07);
+  border: 1px solid rgba(88, 166, 255, 0.25);
+  border-radius: 8px;
+  font-size: 14.5px;
+}
+header.hero .tldr strong { color: var(--accent); }
+
+/* ----- Typography ----- */
+h2 {
+  margin-top: 44px;
+  margin-bottom: 14px;
+  padding-bottom: 8px;
+  border-bottom: 1px solid var(--border);
+  font-size: 22px;
+}
+h2 .num {
+  display: inline-block;
+  width: 30px;
+  height: 30px;
+  line-height: 30px;
+  text-align: center;
+  border-radius: 8px;
+  background: var(--panel2);
+  color: var(--accent);
+  font-size: 14px;
+  font-weight: 600;
+  margin-right: 10px;
+  border: 1px solid var(--border);
+}
+h3 { margin-top: 28px; margin-bottom: 8px; font-size: 17px; color: var(--accent); }
+h4 { margin-top: 18px; margin-bottom: 6px; font-size: 15px; }
+h5 { margin: 12px 0 6px; font-size: 13.5px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.06em; }
+h6 { margin: 10px 0 4px; font-size: 12.5px; color: var(--muted); }
+p { margin: 10px 0 14px; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+/* ----- Code ----- */
+code, kbd {
+  font-family: var(--mono);
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-size: 12.5px;
+}
+pre {
+  background: var(--code-bg);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 14px 16px;
+  overflow-x: auto;
+  font-family: var(--mono);
+  font-size: 12.5px;
+  line-height: 1.55;
+}
+pre code { background: none; border: none; padding: 0; }
+
+/* ----- Tables ----- */
+table { width: 100%; border-collapse: collapse; margin: 14px 0 20px; font-size: 14px; }
+th, td { border: 1px solid var(--border); padding: 9px 12px; text-align: left; vertical-align: top; }
+th { background: var(--panel); font-weight: 600; }
+tr:nth-child(even) td { background: rgba(255, 255, 255, 0.02); }
+
+/* ----- Lists ----- */
+ul, ol { padding-left: 22px; }
+li { margin: 5px 0; }
+
+/* ----- Cards (border-left accent) ----- */
+.card { border: 1px solid var(--border); border-radius: 10px; padding: 18px 22px; background: var(--panel); margin: 16px 0; }
+.card.good { border-left: 4px solid var(--good); }
+.card.warn { border-left: 4px solid var(--warn); }
+.card.bad  { border-left: 4px solid var(--bad); }
+.card.info { border-left: 4px solid var(--accent); }
+.card.next { border-left: 4px solid var(--accent2); }
+.card h4 { margin-top: 0; }
+
+/* ----- Pills (inline badges) ----- */
+.pill {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 11.5px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  border: 1px solid var(--border);
+  margin-right: 6px;
+}
+.pill.good { background: rgba(63, 185, 80, 0.12);  color: var(--good);    border-color: rgba(63, 185, 80, 0.5); }
+.pill.warn { background: rgba(210, 153, 34, 0.12); color: var(--warn);    border-color: rgba(210, 153, 34, 0.5); }
+.pill.bad  { background: rgba(248, 81, 73, 0.12);  color: var(--bad);     border-color: rgba(248, 81, 73, 0.5); }
+.pill.info { background: rgba(88, 166, 255, 0.12); color: var(--accent);  border-color: rgba(88, 166, 255, 0.5); }
+.pill.alt  { background: rgba(163, 113, 247, 0.12);color: var(--accent2); border-color: rgba(163, 113, 247, 0.5); }
+
+/* ----- Grids ----- */
+.grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; margin: 14px 0; }
+.grid3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; margin: 14px 0; }
+.grid4 { display: grid; grid-template-columns: repeat(4, 1fr); gap: 14px; margin: 14px 0; }
+@media (max-width: 800px) {
+  .grid2, .grid3, .grid4 { grid-template-columns: 1fr; }
+}
+
+/* ----- Stat tiles ----- */
+.stat { border: 1px solid var(--border); border-radius: 10px; padding: 16px 18px; background: var(--panel); }
+.stat .num { font-size: 28px; font-weight: 700; letter-spacing: -0.02em; }
+.stat .lbl { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; margin-bottom: 6px; }
+.stat.good .num { color: var(--good); }
+.stat.warn .num { color: var(--warn); }
+.stat.bad  .num { color: var(--bad);  }
+.stat.info .num { color: var(--accent); }
+.stat.alt  .num { color: var(--accent2); }
+
+/* ----- Blockquote ----- */
+blockquote {
+  border-left: 4px solid var(--accent);
+  margin: 14px 0;
+  padding: 8px 16px;
+  color: var(--muted);
+  background: var(--panel2);
+  border-radius: 0 8px 8px 0;
+}
+blockquote p { margin: 4px 0; }
+
+/* ----- TOC ----- */
+.toc { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 14px 22px; margin: 20px 0 28px; font-size: 14px; }
+.toc h4 { margin: 6px 0 8px; color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.08em; }
+.toc ol { margin: 0; padding-left: 22px; columns: 2; }
+@media (max-width: 800px) { .toc ol { columns: 1; } }
+
+/* ----- Side-by-side diff ----- */
+.diff-side { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 14px 0; }
+.diff-side .col { border: 1px solid var(--border); border-radius: 10px; background: var(--panel); padding: 14px 16px; }
+.diff-side .col.before { border-top: 3px solid var(--warn); }
+.diff-side .col.after  { border-top: 3px solid var(--good); }
+.diff-side .col h5 { margin: 0 0 8px; }
+@media (max-width: 800px) { .diff-side { grid-template-columns: 1fr; } }
+
+/* ----- Horizontal rule ----- */
+hr { border: 0; border-top: 1px solid var(--border); margin: 24px 0; }
+
+/* ----- Footer ----- */
+footer {
+  margin-top: 60px;
+  padding-top: 20px;
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 12.5px;
+}

package/src/templates/.claude/skills/deliver-html/templates/audit-report.html.tmpl

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="{{lang}}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>{{title}}</title>
+<style>
+{{css}}
+</style>
+</head>
+<body>
+<div class="wrap">
+<header class="hero" data-badge="{{badge}}" data-badge-tone="warn">
+  <h1>{{title}}</h1>
+  <p class="sub">{{subtitle}}</p>
+  <div class="meta">
+    <span><strong>Generated:</strong> {{generatedAt}}</span>
+    <span><strong>Template:</strong> audit-report</span>
+  </div>
+</header>
+
+{{content}}
+
+<footer>
+  <p>Generated by agent-harness-kit / <code>/deliver-html</code> — HTML for humans, MD for agents.</p>
+</footer>
+</div>
+</body>
+</html>

package/src/templates/.claude/skills/deliver-html/templates/decision-doc.html.tmpl

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="{{lang}}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>{{title}}</title>
+<style>
+{{css}}
+</style>
+</head>
+<body>
+<div class="wrap">
+<header class="hero" data-badge="{{badge}}" data-badge-tone="alt">
+  <h1>{{title}}</h1>
+  <p class="sub">{{subtitle}}</p>
+  <div class="meta">
+    <span><strong>Generated:</strong> {{generatedAt}}</span>
+    <span><strong>Template:</strong> decision-doc</span>
+  </div>
+</header>
+
+{{content}}
+
+<footer>
+  <p>Generated by agent-harness-kit / <code>/deliver-html</code> — HTML for humans, MD for agents.</p>
+</footer>
+</div>
+</body>
+</html>

package/src/templates/.claude/skills/deliver-html/templates/status-report.html.tmpl

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="{{lang}}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>{{title}}</title>
+<style>
+{{css}}
+</style>
+</head>
+<body>
+<div class="wrap">
+<header class="hero" data-badge="{{badge}}" data-badge-tone="good">
+  <h1>{{title}}</h1>
+  <p class="sub">{{subtitle}}</p>
+  <div class="meta">
+    <span><strong>Generated:</strong> {{generatedAt}}</span>
+    <span><strong>Template:</strong> status-report</span>
+  </div>
+</header>
+
+{{content}}
+
+<footer>
+  <p>Generated by agent-harness-kit / <code>/deliver-html</code> — HTML for humans, MD for agents.</p>
+</footer>
+</div>
+</body>
+</html>

package/src/templates/CLAUDE.md.hbs

@@ -48,6 +48,7 @@ CLAUDE.md tiny.
 - `/structural-test-author <layer>`   when adding a new structural rule.
 - `/garbage-collection`               every Friday or before tagging a release.
 - `/eval-runner`                      before merging any change to a skill or agent file.
+- `/deliver-html`                     when user wants an analysis / audit / plan / decision doc / next-actions report — HTML for humans, MD stays for agent files (principle #11).
 
 ## Subagents you should delegate to (do NOT inline these reviews)
 

package/src/templates/CLAUDE.md.vi.hbs

@@ -47,6 +47,7 @@ luôn gọn.
 - `/structural-test-author <layer>`   khi thêm rule kiến trúc mới.
 - `/garbage-collection`               mỗi thứ Sáu hoặc trước khi tag release.
 - `/eval-runner`                      trước khi merge bất kỳ thay đổi nào ở skill / agent file.
+- `/deliver-html`                     khi user cần analysis / audit / plan / decision doc / next-actions — HTML cho human, MD giữ cho agent file (principle #11).
 
 ## Subagents nên ủy thác (KHÔNG inline review)
 

package/src/templates/docs/adr/0002-html-first-for-humans.md.hbs

@@ -0,0 +1,116 @@
+# ADR 0002 — HTML for human deliverables, Markdown for agent files
+
+- **Status:** accepted
+- **Date:** {{now "yyyy-MM-dd"}}
+- **Deciders:** project owner
+
+## Context
+
+The kit produces two distinct kinds of long-form output:
+
+1. **Files an agent reads-and-edits.** `CLAUDE.md`, `SKILL.md`,
+   `.claude/agents/*.md`, `docs/architecture.md`, ADR notes, structural
+   reports written to stdout. These are line-oriented, diffable, and
+   typically loaded into the LLM context window.
+2. **Documents a HUMAN reads-and-decides.** Audit reports, analyses, plans,
+   "next actions" reviews, status snapshots, decision docs. These are
+   self-contained artefacts that travel via email / Slack / PR attachments
+   and exist to surface a recommendation the human signs off on.
+
+Anthropic's long-running-agent guide and the `agent-harness-kit` golden
+principles both confirm Markdown is the right format for category 1: the
+LLM tokenizes it cheaply, structural editing tools (`Edit`, `Write`) treat
+it as native, and grep / sed / awk handle it without ceremony. Category 1
+should remain Markdown.
+
+Category 2 is where pain accumulates. A 500–800-line Markdown audit forces
+the reader to:
+
+- Scroll past sections that lack visual contrast.
+- Render the file (terminal pager, GitHub preview, VS Code preview) before
+  it is readable at all.
+- Skim and miss conclusions because every heading and bullet looks alike —
+  no severity badges, no border-left callouts, no grid layout.
+
+The observed failure mode in this kit's own past sessions: the human reads
+the Markdown report, asks the agent a follow-up that was answered in line
+347, and burns another turn. That clarification turn costs more in tokens
+(input replay + new output) than the +30-50% markup overhead of HTML.
+
+## Decision
+
+Adopt the rule documented as `docs/golden-principles.md` principle #11:
+
+- **Human-facing deliverables ship as a single self-contained HTML file**
+  at repo root, produced by the `/deliver-html` skill against the shared
+  CSS at `.claude/skills/deliver-html/assets/report.css`.
+- **Agent-facing files stay Markdown.** No exception.
+
+Implementation details:
+
+1. `/deliver-html` triggers on user intent: "analyze", "audit", "review",
+   "phân tích", "báo cáo", "plan", "proposal", "decision doc",
+   "next actions", and any similar prompt that calls for a long-form
+   deliverable.
+2. The agent writes the body in Markdown (cheap tokens, easy reasoning).
+   The side-car `scripts/wrap-html.mjs` converts MD → HTML with three
+   templates (`decision-doc` | `audit-report` | `status-report`) and
+   inlines the shared CSS. No npm dependency: the converter is a
+   self-rolled subset (headings, paragraphs, lists, fenced code, tables,
+   blockquotes, inline formatting, links).
+3. The Stop hook (`scripts/precompletion-checklist.sh`) emits a
+   non-blocking nudge when the user prompt matched a deliverable keyword
+   but the session produced only `.md` files at repo root.
+4. Locale: the `<html lang="…">` attribute is read from
+   `harness.config.json` `.claudeMd.humanLanguage`. CSS is locale-agnostic.
+
+## Consequences
+
+Positive
+
+- One canonical look for every audit, plan, and decision doc. Less drift
+  across reports.
+- Human reads once, decides once. Measured benefit: each saved
+  clarification turn ≈ 2-5k output tokens + cached input replay; offsets
+  HTML markup overhead easily.
+- Self-contained HTML — emailable, Slack-attachable, PR-comment-attachable
+  without a build step.
+- Existing 5 HTML reports at repo root (`NEXT_ACTIONS.html`,
+  `PHAN_TICH.html`, `E2E_REPORT.html`, `E2E_CI_REPORT.html`,
+  `HOOK_AUDIT.html`) validate the pattern in practice — `/deliver-html`
+  formalises it.
+
+Negative
+
+- HTML output is ~30-50% larger in token count than the equivalent MD body.
+  Mitigation: the LLM writes MD; only the deterministic side-car emits
+  HTML, so the LLM token budget is not affected.
+- HTML diffs are noisy in GitHub. Mitigation: deliverables are artefacts,
+  not source. Source-of-truth lives in the conversation / commit message;
+  the HTML file is a build output. CI can ignore `*.html` at repo root.
+- Two formats to teach. Mitigation: the rule is "agent reads → MD,
+  human reads → HTML"; reviewers learn it on first encounter.
+
+## Alternatives considered
+
+- **Always Markdown.** Rejected: the failure mode this ADR closes is
+  exactly the "scrolling, miss-the-conclusion" loop that Markdown
+  invites for long deliverables. README / CHANGELOG remain MD because
+  npm/GitHub renders them and the install snippet must be copy-paste-able.
+- **Generate PDF instead.** Rejected: solo-dev kit, no print pipeline,
+  PDFs are write-only on common review tools. HTML is editable in 90
+  seconds when a reviewer wants to amend.
+- **Render Markdown server-side (Docusaurus / mdBook / GitHub Pages).**
+  Rejected: requires CI + deploy step for every report. HTML at repo root
+  opens with one click — zero friction.
+- **Inline a renderer in the IDE.** Rejected: not portable when sending the
+  artefact to someone who is not running the kit.
+
+## Out of scope
+
+- Existing HTML reports at repo root keep their inline CSS for now.
+  Self-contained shipping artefacts trump DRY at solo scale. A future
+  cleanup may reference the shared CSS file by relative path — tracked in
+  `docs/tech-debt-tracker.md` if/when it becomes load-bearing.
+- Localizing the CSS itself. Style is locale-agnostic by design; only the
+  `lang` attribute and body copy differ between locales.

package/src/templates/docs/golden-principles.md.hbs

@@ -119,6 +119,38 @@ domain. The agent reads the recommendation, invokes
 `architecture-reviewer` (or documents why review is unnecessary), and the
 loop guard (`stop_hook_active`) lets the next stop succeed.
 
+## 11. HTML for human deliverables, Markdown for agent files
+
+Files an agent reads-and-edits (`CLAUDE.md`, `.claude/skills/*/SKILL.md`,
+`.claude/agents/*.md`, `docs/architecture.md`, `docs/adr/*.md`, ADR notes,
+inline review output) stay as Markdown. Files a HUMAN reads-and-decides
+(audit reports, analyses, plans, decision docs, next-actions reviews,
+status snapshots) ship as self-contained HTML, written by the
+`/deliver-html` skill against the shared dark-theme CSS.
+
+Why: a 700-line Markdown deliverable forces the human to scroll, miss the
+conclusion, and ask the agent to clarify — a wasted turn that costs more
+tokens than the HTML overhead it was meant to avoid. HTML deliverables are
+"read once, decide once." Markdown has no visual hierarchy strong enough to
+support decision-grade reading at length.
+Enforced by:
+
+- `/deliver-html` skill triggers on user intent ("analyze", "audit",
+  "review", "phân tích", "báo cáo", "plan", "proposal", "decision doc",
+  "next actions") and writes `<slug>.html` at repo root.
+- Stop hook nudge: when the prompt matches those keywords and the session
+  produced only `.md` files at repo root, the agent is reminded to invoke
+  `/deliver-html`. Non-blocking.
+- ADR-0002 documents the trade-off (token cost +30-50% on the rendered
+  output, paid back by saving ≥1 clarification turn).
+
+Counter-rules — when Markdown is still correct:
+
+- `README.md`, `CHANGELOG.md` — npm/GitHub renders them; human installs/diffs.
+- Stdout from `/review-this-pr`, `/garbage-collection`, structural reports —
+  agent consumes the output.
+- Short summaries (< 30 lines) — answer inline, no file.
+
 ---
 
 _Add new principles via `/structural-test-author`, which forces you to

package/src/templates/scripts/precompletion-checklist.sh.hbs

@@ -202,6 +202,49 @@ if [ -f harness.config.json ] && have_jp && command -v git >/dev/null 2>&1; then
   fi
 fi
 
+# Non-blocking nudge: HTML-for-humans (golden principle #11 / ADR-0002).
+# When the session produced one or more deliverable-shaped .md files at repo
+# root (i.e. not CLAUDE.md / AGENTS.md / README.md / CHANGELOG.md), suggest
+# `/deliver-html`. Pure heuristic — never blocks the stop. Skip with
+# `AHK_DISABLE_HTML_NUDGE=1`.
+if [ "${AHK_DISABLE_HTML_NUDGE:-0}" != "1" ] && command -v git >/dev/null 2>&1; then
+  KIT_MDS="CLAUDE.md|AGENTS.md|README.md|CHANGELOG.md|LICENSE.md|CONTRIBUTING.md|CODE_OF_CONDUCT.md|SECURITY.md"
+  NEW_MD=$(
+    {
+      git ls-files --others --exclude-standard 2>/dev/null
+      git diff --name-only 2>/dev/null
+      git diff --name-only --cached 2>/dev/null
+    } \
+    | sort -u \
+    | grep -E '^[^/]+\.md$' \
+    | grep -Ev "^(${KIT_MDS})$" \
+    || true
+  )
+  if [ -n "$NEW_MD" ]; then
+    NEW_HTML=$(
+      {
+        git ls-files --others --exclude-standard 2>/dev/null
+        git diff --name-only 2>/dev/null
+        git diff --name-only --cached 2>/dev/null
+      } \
+      | sort -u \
+      | grep -E '^[^/]+\.html$' \
+      || true
+    )
+    if [ -z "$NEW_HTML" ]; then
+      {
+        echo
+        echo "[nudge] Repo root has new .md file(s) that look like human deliverables:"
+        echo "$NEW_MD" | sed 's/^/  - /'
+        echo
+        echo "Golden principle #11: HTML for human deliverables, MD for agent files."
+        echo "If these are reports/audits/plans/decision-docs, ship them via /deliver-html"
+        echo "instead. Non-blocking — suppress with AHK_DISABLE_HTML_NUDGE=1."
+      } >&2
+    fi
+  fi
+fi
+
 if [ ! -s "$TMPDIR_HOOK/failed.list" ]; then
   exit 0
 fi