@htechcs/harness-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HoangTechCS-AIE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,139 @@
+<div align="center">
+
+# 🛠️ harness-kit
+
+**Set up any repo for a coding agent (Claude Code) across the 5 maturity levels of harness engineering — in one command.**
+
+[![npm](https://img.shields.io/npm/v/@htechcs/harness-kit?logo=npm&color=cb3837)](https://www.npmjs.com/package/@htechcs/harness-kit)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
+
+[Tiếng Việt](README.md) · **English**
+
+</div>
+
+---
+
+**Harness** = everything *around* the model (context, instructions, tools, safety constraints,
+orchestration, measurement) that makes an agent reliable. This kit packages it into installable
+**artifacts** plus a **tutorial** that teaches *when* to use each. The kit ships files; the tutorial
+teaches the discipline.
+
+## ⚙️ How it works
+
+```mermaid
+flowchart LR
+    D([You]) -->|"npx @htechcs/harness-kit"| I[["harness-kit<br/>installer"]]
+    I --> R1[".claude/<br/>settings.json · agents/"]
+    I --> R2["repo root<br/>setup.sh · TASK.md"]
+    I --> R3["~/.claude/skills/<br/>init-harness"]
+    I --> R4["docs/harness/<br/>tutorial + guides"]
+    R1 --> A([Claude Code<br/>reads every session])
+    R2 --> A
+    R3 --> A
+    R4 --> A
+```
+
+One `npx` command drops artifacts in the right places; from there Claude Code reads them every session.
+
+## 🚀 Quick install
+
+```bash
+npx @htechcs/harness-kit              # pick levels interactively, then install
+npx @htechcs/harness-kit --all        # install all 5 levels
+npx @htechcs/harness-kit --levels=1,3 # specific levels only
+```
+
+Requires **Node ≥18**. The command saves all docs into `docs/harness/` so your team keeps them.
+**Idempotent** — safe to re-run (`--force` to overwrite).
+
+## 🪜 The 5 levels — each prevents a failure mode
+
+```mermaid
+flowchart TD
+    L1["Level 1 · Foundation — CLAUDE.md"] --> L2["Level 2 · Clean context"]
+    L2 --> L3["Level 3 · Guardrails"]
+    L3 --> L4["Level 4 · Long-running"]
+    L4 --> L5["Level 5 · Evals & Observability"]
+    L5 -.->|"surface a failure → reinforce the harness"| L1
+```
+
+| Level | Without it | Artifact |
+|-------|------------|----------|
+| **1 — Foundation** | the agent has no durable repo guidance | `/init-harness` skill → generates `CLAUDE.md` |
+| **2 — Clean context** | context floods, the agent's attention dilutes | sample subagent + MCP audit checklist |
+| **3 — Guardrails** | agent deletes/pushes by mistake, asks permission nonstop | `settings.json` (deny/ask/allow) |
+| **4 — Long-running** | long tasks break mid-way, can't resume | `setup.sh`, `new-worktree.sh`, `TASK.md` |
+| **5 — Evals & Obs** | no idea whether the agent does well or badly | golden-task template + observability guide |
+
+## 📦 Manual install per level
+
+> The installer just automates the `cp` commands below — expand them to understand/do it by hand.
+
+<details>
+<summary><b>Level 1 — Foundation · CLAUDE.md</b> &nbsp;<code>[do this first]</code></summary>
+
+```bash
+cp -r skills/init-harness ~/.claude/skills/   # then run /init-harness in the target repo
+```
+</details>
+
+<details>
+<summary><b>Level 2 — Clean context</b></summary>
+
+```bash
+mkdir -p .claude/agents && cp templates/agents/repo-explorer.md .claude/agents/
+```
+Read `templates/agents/README.md` + `templates/mcp-audit.md`.
+</details>
+
+<details>
+<summary><b>Level 3 — Guardrails</b> &nbsp;<code>[points into CLAUDE.md]</code></summary>
+
+```bash
+mkdir -p .claude && cp templates/settings.json .claude/settings.json
+```
+**First thing to do:** add your repo's test/lint commands to `allow` (see `templates/guardrails/README.md`).
+</details>
+
+<details>
+<summary><b>Level 4 — Long-running</b> &nbsp;<code>[points into CLAUDE.md]</code></summary>
+
+```bash
+cp templates/setup.sh templates/new-worktree.sh . && chmod +x setup.sh new-worktree.sh
+cp templates/long-running/TASK.md .            # when starting a long task
+```
+</details>
+
+<details>
+<summary><b>Level 5 — Evals & Observability</b> &nbsp;<code>[needs ≥1 level applied to have something to measure]</code></summary>
+
+```bash
+mkdir -p evals/cases && cp templates/evals/cases/example-task.md evals/cases/
+```
+Read `templates/evals/README.md` (includes a **no-harness baseline** step) + `observability.md`.
+</details>
+
+<details>
+<summary><b>+ Specs</b> — the other half of Pillar 2</summary>
+
+```bash
+mkdir -p docs/specs && cp templates/spec/FEATURE.md docs/specs/<feature>.md
+```
+</details>
+
+## 🔗 Level dependencies
+
+- **Level 1 first** — it's the backbone; later levels reference `CLAUDE.md`.
+- **Levels 3 & 4** both "point `CLAUDE.md` to" their artifacts → require Level 1 done.
+- **Level 5** needs at least one level applied to have a change to measure (see the feedback loop above).
+
+## 📚 Docs
+
+`docs/harness-engineering-tutorial.en.md` ([Tiếng Việt](docs/harness-engineering-tutorial.md)) — the
+why + *when* to use each piece (after install: `docs/harness/`). Full industry-wide source catalog:
+[Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering).
+
+## 📄 License
+
+[MIT](LICENSE).

package/README.md

@@ -0,0 +1,138 @@
+<div align="center">
+
+# 🛠️ harness-kit
+
+**Thiết lập repo cho coding agent (Claude Code) theo 5 mức trưởng thành của harness engineering — bằng một lệnh.**
+
+[![npm](https://img.shields.io/npm/v/@htechcs/harness-kit?logo=npm&color=cb3837)](https://www.npmjs.com/package/@htechcs/harness-kit)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
+
+**Tiếng Việt** · [English](README.en.md)
+
+</div>
+
+---
+
+**Harness** = mọi thứ *bao quanh* model (context, chỉ dẫn, tools, ràng buộc an toàn, orchestration,
+đo lường) để agent làm việc đáng tin. Kit này đóng gói nó thành **artifact** cài được + một
+**tutorial** dạy *khi nào* dùng từng thứ. Kit ship file; tutorial dạy kỷ luật.
+
+## ⚙️ Hoạt động thế nào
+
+```mermaid
+flowchart LR
+    D([Bạn]) -->|"npx @htechcs/harness-kit"| I[["harness-kit<br/>installer"]]
+    I --> R1[".claude/<br/>settings.json · agents/"]
+    I --> R2["repo root<br/>setup.sh · TASK.md"]
+    I --> R3["~/.claude/skills/<br/>init-harness"]
+    I --> R4["docs/harness/<br/>tutorial + guides"]
+    R1 --> A([Claude Code<br/>đọc mỗi session])
+    R2 --> A
+    R3 --> A
+    R4 --> A
+```
+
+Một lệnh `npx` rải artifact vào đúng chỗ; từ đó Claude Code đọc chúng ở mọi phiên làm việc.
+
+## 🚀 Cài nhanh
+
+```bash
+npx @htechcs/harness-kit              # hỏi chọn mức rồi cài
+npx @htechcs/harness-kit --all        # cài cả 5 mức
+npx @htechcs/harness-kit --levels=1,3 # chỉ mức cụ thể
+```
+
+Cần **Node ≥18**. Lệnh lưu toàn bộ tài liệu vào `docs/harness/` để team giữ lại. **Idempotent** —
+chạy lại an toàn (`--force` để ghi đè).
+
+## 🪜 5 mức — mỗi mức chặn một kiểu thất bại
+
+```mermaid
+flowchart TD
+    L1["Mức 1 · Nền tảng — CLAUDE.md"] --> L2["Mức 2 · Context sạch"]
+    L2 --> L3["Mức 3 · Guardrails"]
+    L3 --> L4["Mức 4 · Long-running"]
+    L4 --> L5["Mức 5 · Evals & Observability"]
+    L5 -.->|"phát hiện lỗi → gia cố harness"| L1
+```
+
+| Mức | Khi không có nó | Artifact |
+|-----|-----------------|----------|
+| **1 — Nền tảng** | agent không có chỉ dẫn repo bền vững | skill `/init-harness` → sinh `CLAUDE.md` |
+| **2 — Context sạch** | context ngập, agent "loãng" sự chú ý | subagent mẫu + checklist rà MCP |
+| **3 — Guardrails** | agent xoá/push nhầm, bị hỏi quyền liên tục | `settings.json` (deny/ask/allow) |
+| **4 — Long-running** | việc dài đứt giữa chừng, không resume | `setup.sh`, `new-worktree.sh`, `TASK.md` |
+| **5 — Evals & Obs** | không biết agent làm tốt hay tệ | golden-task template + guide observability |
+
+## 📦 Cài tay từng mức
+
+> Installer chỉ tự động hoá đúng những lệnh `cp` dưới đây — mở ra nếu muốn hiểu/làm thủ công.
+
+<details>
+<summary><b>Mức 1 — Nền tảng · CLAUDE.md</b> &nbsp;<code>[làm trước tiên]</code></summary>
+
+```bash
+cp -r skills/init-harness ~/.claude/skills/   # rồi gõ /init-harness trong repo đích
+```
+</details>
+
+<details>
+<summary><b>Mức 2 — Context sạch</b></summary>
+
+```bash
+mkdir -p .claude/agents && cp templates/agents/repo-explorer.md .claude/agents/
+```
+Đọc `templates/agents/README.md` + `templates/mcp-audit.md`.
+</details>
+
+<details>
+<summary><b>Mức 3 — Guardrails</b> &nbsp;<code>[trỏ vào CLAUDE.md]</code></summary>
+
+```bash
+mkdir -p .claude && cp templates/settings.json .claude/settings.json
+```
+**Việc đầu tiên:** thêm lệnh test/lint của repo vào `allow` (xem `templates/guardrails/README.md`).
+</details>
+
+<details>
+<summary><b>Mức 4 — Long-running</b> &nbsp;<code>[trỏ vào CLAUDE.md]</code></summary>
+
+```bash
+cp templates/setup.sh templates/new-worktree.sh . && chmod +x setup.sh new-worktree.sh
+cp templates/long-running/TASK.md .            # khi bắt đầu một việc dài
+```
+</details>
+
+<details>
+<summary><b>Mức 5 — Evals & Observability</b> &nbsp;<code>[cần ≥1 mức đã áp để có cái mà đo]</code></summary>
+
+```bash
+mkdir -p evals/cases && cp templates/evals/cases/example-task.md evals/cases/
+```
+Đọc `templates/evals/README.md` (có bước **baseline không-harness**) + `observability.md`.
+</details>
+
+<details>
+<summary><b>+ Specs</b> — nửa còn lại của Trụ cột 2</summary>
+
+```bash
+mkdir -p docs/specs && cp templates/spec/FEATURE.md docs/specs/<feature>.md
+```
+</details>
+
+## 🔗 Phụ thuộc giữa các mức
+
+- **Mức 1 trước hết** — xương sống; các mức sau viện tới `CLAUDE.md`.
+- **Mức 3 & 4** đều "trỏ `CLAUDE.md` tới" artifact của chúng → cần Mức 1 xong.
+- **Mức 5** cần ít nhất một mức đã áp để có thay đổi mà đo (xem vòng feedback ở sơ đồ trên).
+
+## 📚 Tài liệu
+
+`docs/harness-engineering-tutorial.md` ([English](docs/harness-engineering-tutorial.en.md)) — vì sao +
+*khi nào* dùng từng thứ (sau khi cài: `docs/harness/`). Danh mục nguồn đầy đủ của cả ngành:
+[Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering).
+
+## 📄 License
+
+[MIT](LICENSE).

package/bin/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict'
+
+// harness-kit — installer cho Harness Engineering starter kit.
+// Chạy: npx harness-kit            (hỏi chọn mức)
+//        npx harness-kit --all      (cài hết, không hỏi)
+//        npx harness-kit --levels=1,3,4
+// Cờ phụ: --target=<dir> (mặc định thư mục hiện tại), --force (ghi đè), --help.
+//
+// Nguyên tắc: IDEMPOTENT (chạy lại an toàn — file đã có thì bỏ qua trừ khi --force)
+// và FAIL-SOFT (thiếu một artifact thì cảnh báo, không sập cả lần cài).
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const readline = require('readline')
+
+const KIT = path.resolve(__dirname, '..') // gốc package (nơi có templates/, skills/, docs/)
+const HOME = os.homedir()
+let TARGET = process.cwd() // đặt lại trong main(); dùng để hiển thị đường dẫn cho gọn
+
+// ---- Bản đồ artifact theo mức: [nguồn-trong-kit, đích]. Đích tuyệt đối = cài cấp user. ----
+const LEVELS = {
+  '1': {
+    title: 'Mức 1 — Nền tảng (CLAUDE.md)',
+    copy: [['skills/init-harness', path.join(HOME, '.claude', 'skills', 'init-harness')]],
+    next: 'Gõ  /init-harness  trong repo đích để sinh CLAUDE.md.',
+  },
+  '2': {
+    title: 'Mức 2 — Context sạch',
+    copy: [['templates/agents/repo-explorer.md', '.claude/agents/repo-explorer.md']],
+    next: 'Đọc docs/harness/agents-README.md (quy tắc subagent) + mcp-audit.md (rà MCP thừa).',
+  },
+  '3': {
+    title: 'Mức 3 — Guardrails',
+    copy: [['templates/settings.json', '.claude/settings.json']],
+    next: 'MỞ .claude/settings.json → thêm lệnh test/lint của repo vào "allow" (xem docs/harness/guardrails-README.md). Đây là việc ĐẦU TIÊN.',
+  },
+  '4': {
+    title: 'Mức 4 — Long-running',
+    copy: [
+      ['templates/setup.sh', 'setup.sh'],
+      ['templates/new-worktree.sh', 'new-worktree.sh'],
+    ],
+    chmod: ['setup.sh', 'new-worktree.sh'],
+    next: 'Điền setup.sh cho repo bạn; copy docs/harness/TASK.md ra khi bắt đầu một việc dài.',
+  },
+  '5': {
+    title: 'Mức 5 — Evals & Observability',
+    copy: [['templates/evals/cases/example-task.md', 'evals/cases/example-task.md']],
+    next: 'Đọc docs/harness/evals-README.md (có bước baseline "không harness") + observability.md.',
+  },
+}
+
+// ---- Tài liệu hướng dẫn: luôn copy vào <target>/docs/harness/ để team GIỮ LẠI ----
+// (npx cache biến mất sau khi chạy, nên phải đổ guidance vào repo.)
+const GUIDE_DIR = path.join('docs', 'harness')
+const GUIDE = [
+  ['docs/harness-engineering-tutorial.md', 'tutorial.md'],
+  ['docs/harness-engineering-tutorial.en.md', 'tutorial.en.md'],
+  ['README.md', 'kit-README.md'],
+  ['templates/agents/README.md', 'agents-README.md'],
+  ['templates/mcp-audit.md', 'mcp-audit.md'],
+  ['templates/guardrails/README.md', 'guardrails-README.md'],
+  ['templates/long-running/README.md', 'long-running-README.md'],
+  ['templates/long-running/TASK.md', 'TASK.md'],
+  ['templates/evals/README.md', 'evals-README.md'],
+  ['templates/evals/observability.md', 'observability.md'],
+  ['templates/spec/README.md', 'spec-README.md'],
+  ['templates/spec/FEATURE.md', 'FEATURE.md'],
+]
+
+function parseArgs(argv) {
+  const o = { levels: null, all: false, force: false, target: process.cwd(), help: false }
+  for (const a of argv) {
+    if (a === '--all') o.all = true
+    else if (a === '--force') o.force = true
+    else if (a === '--help' || a === '-h') o.help = true
+    else if (a.startsWith('--levels=')) o.levels = a.slice(9).split(',').map((s) => s.trim()).filter(Boolean)
+    else if (a.startsWith('--target=')) o.target = path.resolve(a.slice(9))
+  }
+  return o
+}
+
+function showHelp() {
+  console.log(`
+harness-kit — thiết lập repo cho coding agent theo 5 mức.
+
+  npx harness-kit                 hỏi chọn mức rồi cài
+  npx harness-kit --all           cài cả 5 mức
+  npx harness-kit --levels=1,3    cài mức cụ thể
+
+Cờ:
+  --target=<dir>   thư mục đích (mặc định: thư mục hiện tại)
+  --force          ghi đè file đã tồn tại (mặc định: bỏ qua)
+  --help
+
+Mức: 1 Nền tảng · 2 Context · 3 Guardrails · 4 Long-running · 5 Evals.
+Tài liệu luôn được đổ vào <target>/docs/harness/.
+`)
+}
+
+function rel(p) {
+  if (p.startsWith(HOME)) return '~' + p.slice(HOME.length)
+  if (p.startsWith(TARGET)) return path.relative(TARGET, p) || '.'
+  return p
+}
+
+// Đặt một artifact. destAbs: đường dẫn tuyệt đối đã resolve.
+function place(srcRel, destAbs, force) {
+  const src = path.join(KIT, srcRel)
+  if (!fs.existsSync(src)) {
+    console.log(`  ⚠ thiếu trong kit, bỏ qua: ${srcRel}`)
+    return false
+  }
+  if (fs.existsSync(destAbs) && !force) {
+    console.log(`  • đã có, giữ nguyên: ${rel(destAbs)}  (dùng --force để ghi đè)`)
+    return false
+  }
+  fs.mkdirSync(path.dirname(destAbs), { recursive: true })
+  fs.cpSync(src, destAbs, { recursive: true })
+  console.log(`  ✓ ${rel(destAbs)}`)
+  return true
+}
+
+function installLevel(key, target, force) {
+  const lv = LEVELS[key]
+  if (!lv) {
+    console.log(`\n(bỏ qua mức không hợp lệ: ${key})`)
+    return
+  }
+  console.log(`\n${lv.title}`)
+  for (const [srcRel, dest] of lv.copy) {
+    const destAbs = path.isAbsolute(dest) ? dest : path.join(target, dest)
+    place(srcRel, destAbs, force)
+  }
+  for (const f of lv.chmod || []) {
+    const p = path.join(target, f)
+    try { if (fs.existsSync(p)) fs.chmodSync(p, 0o755) } catch (_) {}
+  }
+}
+
+function installGuide(target, force) {
+  console.log(`\nTài liệu hướng dẫn → ${path.join(rel(path.join(target, GUIDE_DIR)))}/`)
+  for (const [srcRel, name] of GUIDE) {
+    place(srcRel, path.join(target, GUIDE_DIR, name), force)
+  }
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a) }))
+}
+
+async function main() {
+  const opt = parseArgs(process.argv.slice(2))
+  if (opt.help) { showHelp(); return }
+
+  TARGET = opt.target
+  console.log(`harness-kit → cài vào: ${opt.target}`)
+
+  let levels
+  if (opt.all) levels = Object.keys(LEVELS)
+  else if (opt.levels) levels = opt.levels
+  else if (process.stdin.isTTY) {
+    const a = (await ask('\nCài mức nào? [all] hoặc danh sách vd 1,3,4: ')).trim()
+    levels = !a || a.toLowerCase() === 'all' ? Object.keys(LEVELS) : a.split(',').map((s) => s.trim()).filter(Boolean)
+  } else {
+    levels = Object.keys(LEVELS) // không có TTY (CI/pipe) → cài hết
+  }
+
+  for (const k of levels) installLevel(k, opt.target, opt.force)
+  installGuide(opt.target, opt.force)
+
+  console.log('\n— Xong. Bước tiếp theo —')
+  for (const k of levels) {
+    if (LEVELS[k]) console.log(`  [${k}] ${LEVELS[k].next}`)
+  }
+  console.log('\nĐọc trước hết: docs/harness/tutorial.md (vì sao + KHI NÀO dùng từng thứ).')
+}
+
+main().catch((e) => { console.error('harness-kit lỗi:', e.message); process.exit(1) })