@htechcs/harness-kit 0.1.0

package/templates/evals/cases/example-task.md

@@ -0,0 +1,33 @@
+<!--
+Một "golden task" = một việc đại diện + tiêu chí đậu KHÁCH QUAN, để chạy lại được sau mỗi
+lần sửa harness. Copy file này cho mỗi case. Đặt tên theo việc: add-endpoint.md, fix-flaky-test.md...
+
+Nguyên tắc: done-criteria phải đo được bằng MÁY nếu có thể (lệnh chạy ra pass/fail), chỉ rớt
+xuống chấm bằng người khi bất khả kháng. "Trông có vẻ đúng" KHÔNG phải tiêu chí.
+Xoá comment này khi dùng thật.
+-->
+
+# Case: <tên việc — vd "thêm endpoint GET /users/:id">
+
+## Task (đưa nguyên văn cho agent)
+<Lời nhắc y như bạn sẽ gõ cho agent. Càng giống thực tế càng tốt.>
+
+## Setup (repo phải ở trạng thái nào trước khi chạy)
+<Branch/commit nền, dữ liệu seed, biến môi trường. Để case lặp lại được giống nhau mỗi lần.>
+- Base: <commit/branch>
+- 
+
+## Done-criteria (KHÁCH QUAN — đậu/rớt rõ ràng)
+<Cái PHẢI đúng sau khi agent xong. Ưu tiên lệnh chạy ra pass/fail.>
+- [ ] `<lệnh test>` xanh
+- [ ] `<lệnh lint / typecheck>` sạch
+- [ ] <thay đổi cụ thể tồn tại — vd "route mới trả 200 với id hợp lệ, 404 nếu không">
+- [ ] KHÔNG đụng <file/đường ngoài phạm vi>
+
+## Cách chấm
+<Tự động được thì ghi đúng lệnh. Phải chấm tay thì ghi rubric ngắn, đừng để "tự hiểu".>
+- Tự động: `<lệnh trả exit code>`
+- Tay (nếu cần): <1–2 câu rubric>
+
+## Tham chiếu (tùy chọn)
+<Commit/PR "đúng" để so, nếu có. Giúp thấy agent lệch ở đâu.>

package/templates/evals/observability.md

@@ -0,0 +1,42 @@
+# Observability — thấy agent đã làm gì (Mức 5)
+
+Khi một eval rớt — hoặc agent "làm gì đó lạ" — bạn cần *nhìn* được nó đã làm gì, không đoán.
+Đây là các chỗ mà nhìn, từ rẻ tới sâu.
+
+## Chỗ nào mà nhìn
+
+1. **Transcript phiên** — bản ghi *mọi* tool call agent đã gọi (đọc file nào, chạy lệnh gì,
+   sửa gì). Đây là nguồn sự thật số một khi truy "vì sao nó làm vậy". Claude Code lưu transcript
+   mỗi session dưới thư mục project trong `~/.claude/`.
+2. **`/cost`** — token & chi phí của phiên. Tăng vọt bất thường = dấu hiệu context phình
+   (đọc lại file thừa, MCP nhồi tool) → kéo về Mức 2.
+3. **Telemetry (cho cả team / chạy nền)** — Claude Code xuất được metrics/logs qua OpenTelemetry:
+   bật bằng biến môi trường `CLAUDE_CODE_ENABLE_TELEMETRY` rồi trỏ OTLP exporter sang backend
+   của bạn (Grafana, Honeycomb, Datadog…). Dùng khi cần theo dõi nhiều phiên/agent, không chỉ một.
+   → Tra cấu hình chính xác trong docs Claude Code mục *monitoring / telemetry*.
+4. **Log hook (audit chủ động)** — gắn `PostToolUse` hook ghi mỗi tool call ra file (xem
+   [guardrails/README.md](../guardrails/README.md) mục Hooks). Hữu ích khi chạy nền và muốn xem lại sau.
+
+## Dấu hiệu bệnh & nó chỉ về mức nào
+
+Observability không chỉ để debug một phiên — nó **lộ ra lỗ hổng harness**:
+
+| Thấy gì trong trace | Bệnh | Sửa ở mức |
+|---------------------|------|-----------|
+| Đọc đi đọc lại cùng file; token leo thang | context bẩn | **Mức 2** (subagent / `/clear` / cắt MCP) |
+| Bị hỏi quyền liên tục cho lệnh an toàn | allowlist thiếu | **Mức 3** (thêm vào `allow`) |
+| Suýt chạy lệnh phá hoại | thiếu chốt | **Mức 3** (thêm vào `deny`/`ask`) |
+| Mất ngữ cảnh giữa phiên dài, làm lại từ đầu | không checkpoint | **Mức 4** (`TASK.md`) |
+| Làm sai mà không ai biết tới lúc muộn | thiếu eval | **Mức 5** (thêm golden task) |
+| Mơ hồ "build/test chạy sao" | chỉ dẫn thiếu | **Mức 1** (CLAUDE.md) |
+| Lặp đi lặp lại cùng một lỗi qua nhiều phiên | luật chưa được ghi | **Mức 1** (thêm 1 dòng vào CLAUDE.md) |
+
+**Đóng vòng về Mức 1 — `CLAUDE.md` là tài liệu sống.** Khi trace cho thấy agent **lặp lại** một
+lỗi Z (vd quên chạy migration, sửa nhầm file generated), đừng chỉ sửa tay lần này: thêm **một dòng**
+guardrail/quy ước vào `CLAUDE.md` để chặn lần sau, rồi **chạy lại golden task** xác nhận hết
+regression. Đó là cách `CLAUDE.md` lớn lên *từ lỗi thật*, thay vì phình theo phỏng đoán.
+
+## Nguyên tắc
+
+> Đừng cải thiện harness bằng cảm giác. **Đọc trace, để nó chỉ đúng mức cần sửa**, sửa, rồi
+> chạy lại golden task để xác nhận tốt lên thật. Đó là toàn bộ vòng lặp Mức 5.

package/templates/guardrails/README.md

@@ -0,0 +1,120 @@
+# Guardrails — permission baseline (Mức 3)
+
+Mức 3 kiểm soát agent **được phép làm gì** — ranh giới an toàn. Khác Mức 2 (context *sạch*),
+Mức 3 lo hành động *an toàn*: chặn lệnh phá hoại, hỏi trước việc rủi ro, cho việc an toàn chạy thẳng.
+
+## Cài đặt
+
+Copy `settings.json` vào `.claude/` của repo:
+
+```bash
+mkdir -p .claude
+cp settings.json .claude/settings.json
+```
+
+**Vì sao là `.claude/settings.json` (không phải `settings.local.json`):** file này **check vào repo**,
+nên cả team clone về là **tự thừa hưởng cùng một bộ guardrail**. Còn `settings.local.json` là
+ghi đè cá nhân (đã gitignore) — để dành cho tinh chỉnh riêng máy bạn, không ép lên team.
+
+> ⚡ **Việc ĐẦU TIÊN sau khi copy — thêm lệnh test/lint/build vào `allow`.** Baseline cố ý chỉ
+> allow git read-only. Nếu không thêm vòng feedback của repo, Claude sẽ hỏi quyền *mỗi lần* chạy
+> test → bạn rơi đúng thói quen "bấm yes cho xong" mà mục *Insight* bên dưới gọi là nguy hiểm nhất.
+> Mở `.claude/settings.json`, thêm vào `allow` đúng lệnh của stack bạn:
+>
+> - **Node:** `"Bash(npm run test:*)"`, `"Bash(npm run lint:*)"`, `"Bash(npm run build:*)"`
+> - **Python:** `"Bash(pytest:*)"`, `"Bash(ruff:*)"`, `"Bash(mypy:*)"`
+> - **Go:** `"Bash(go test:*)"`, `"Bash(go build:*)"`, `"Bash(go vet:*)"`
+>
+> Đây là **bắt buộc**, không phải tuỳ chọn — vòng feedback nhanh là tinh tuý xuyên suốt cả kit.
+
+## Mô hình 3 rổ
+
+Mọi hành động (chạy bash, đọc/sửa file) rơi vào 1 trong 3 rổ:
+
+| Rổ | Nghĩa | Ví dụ trong baseline |
+|----|-------|----------------------|
+| **deny** | cấm tuyệt đối, agent không gọi được | `rm -rf`, đọc `.env`/`secrets/**`, đọc key `*.pem` |
+| **ask** | dừng lại hỏi bạn trước | `git push`, `git reset --hard`, `git clean`, `rm` |
+| **allow** | chạy thẳng, không hỏi | `git status`, `git diff`, `git log`, `git branch` |
+
+Cú pháp rule: `Tool(specifier)`.
+- Bash khớp theo **tiền tố**: `Bash(npm run test:*)` khớp mọi lệnh bắt đầu bằng `npm run test`.
+- File theo kiểu **gitignore**: `Read(./secrets/**)`, `Edit(./dist/**)`.
+
+## Cách mở rộng cho repo của bạn
+
+Baseline cố ý **tối giản và universal**. Hãy thêm cái đặc thù repo:
+
+- **Vào `allow`** — lệnh chạy hằng ngày, an toàn, để khỏi bị hỏi liên tục:
+  `Bash(npm run test:*)`, `Bash(npm run lint:*)`, `Bash(pytest:*)`, `Bash(make:*)`.
+- **Vào `ask`** — việc đặc thù repo mà *hệ quả lớn*:
+  chạy migration (`Bash(npm run migrate:*)`), deploy, `Bash(docker compose down:*)`.
+- **Vào `deny`** — path không bao giờ được sửa/đọc:
+  `Edit(./dist/**)`, `Edit(./vendor/**)`, `Read(./**/*.key)`.
+
+> Mẹo: đừng nhồi `allow` quá rộng. Mỗi lần Claude hỏi là một lần bạn *review* — nhồi allow
+> nhiều quá là tự bỏ chốt review của chính mình.
+
+## Insight: deny ≠ bảo mật kín kẽ
+
+Deny-list **không** chống được kẻ địch (agent có thể lách: viết `rm` qua script, base64…).
+Nó là **lưới an toàn + giảm ma sát**:
+- `deny`/`ask` chặn **tai nạn** (xoá nhầm, push nhầm) — phòng *lỗi*, không phòng *tấn công*.
+- `allow` cho lệnh an toàn chạy thẳng → bạn đỡ thói quen "bấm yes cho xong" (thói quen đó mới
+  là cái nguy hiểm thật).
+
+**An toàn thật sự** vẫn là **review diff + plan mode** trước khi cho agent hành động — đó là
+kỷ luật runtime, không gói thành file được.
+
+## Nội dung ngoài & prompt injection
+
+`deny`/`ask` ở trên chặn *tai nạn*, **không** chặn được prompt injection. Nội dung agent đọc từ
+web, issue, PR, log… là **dữ liệu — không phải lệnh**, nhưng kẻ xấu có thể giấu chỉ thị trong đó
+để lái agent. Đây là **kỷ luật runtime** (nên kit không nhồi hook/CI-scan sẵn), vài chốt thực dụng:
+
+- Đọc nội dung ngoài (web/issue/PR) trong **plan mode** — agent *đề xuất* trước khi *hành động*.
+- KHÔNG cho agent tự chạy lệnh / `curl` lấy ra từ nội dung nó vừa fetch về.
+- Input không tin cậy → tách **session riêng**, đừng trộn vào session đang có quyền cao.
+
+Quét tự động ở CI và phần nền sâu hơn: xem `docs/harness-engineering-tutorial.md` (link **Lurkr**
+cho CI-scan, **OpenHands — mitigating prompt injection** cho nền tảng).
+
+## Nâng cao (tùy chọn): Hooks
+
+Khi cần *logic* phức tạp hơn allow/deny tĩnh — vd "chặn mọi edit vào path bảo vệ", "tự chạy
+lint sau mỗi lần sửa" — dùng **hook**: một script chạy *trước/sau* mỗi tool call. Khai báo trong
+`settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }] }
+    ]
+  }
+}
+```
+
+Script đọc JSON tool-call từ stdin; **exit code 2 = chặn**, kèm message ra stderr. Vì hook chặn
+là script đặc thù từng repo, kit này **không nhồi sẵn** — chỉ chỉ đường. Viết khi bạn thật sự có
+một quy tắc lặp lại mà allow/deny tĩnh không diễn đạt nổi.
+
+**Audit-log (`PostToolUse`)** — ghi lại *mọi* tool call để xem lại sau. Đây là thứ
+`evals/observability.md` (Mức 5) trỏ tới; hook này **generic, không đặc thù repo**:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      { "matcher": "*", "hooks": [{ "type": "command", "command": ".claude/hooks/audit-log.sh" }] }
+    ]
+  }
+}
+```
+
+`audit-log.sh` chỉ cần nối payload stdin vào một file — mỗi dòng là JSON một tool call:
+
+```bash
+#!/usr/bin/env bash
+cat >> .claude/audit.log
+```

package/templates/long-running/README.md

@@ -0,0 +1,48 @@
+# Long-running — việc kéo dài quá một session (Mức 4)
+
+Mức 4 giữ agent làm việc *đáng tin* trên thứ dài hơi: refactor nhiều ngày, migration lớn,
+agent chạy nền hàng giờ. Việc dài chết vì 3 thứ — mỗi file ở đây chặn một thứ.
+
+## 3 file, 3 vấn đề
+
+| File | Chặn cái chết nào |
+|------|-------------------|
+| [`setup.sh`](../setup.sh) | Không về được trạng thái chạy-được (clone/agent mới không biết cài gì) |
+| [`TASK.md`](./TASK.md) | Mất trạng thái qua session / sau `/clear` |
+| [`new-worktree.sh`](../new-worktree.sh) | Nhiều task song song giẫm chân nhau |
+
+## Cài đặt
+
+```bash
+cp setup.sh new-worktree.sh .          # vào root repo
+chmod +x setup.sh new-worktree.sh
+cp long-running/TASK.md .              # khi bắt đầu một việc dài cụ thể
+```
+
+Rồi **trỏ `CLAUDE.md`** vào chúng để agent biết dùng:
+
+```md
+## Build / Test / Run
+- Dựng môi trường: ./setup.sh   (idempotent — chạy lại an toàn)
+
+## Long-running
+- Việc dài đang chạy ghi ở TASK.md — đọc trước khi bắt đầu, cập nhật khi tới mốc.
+```
+
+## Khi nào dùng cái nào (đây là phần discipline)
+
+File chỉ là công cụ — biết *khi nào* rút ra mới là kỹ năng:
+
+- **`setup.sh`** — chạy ngay khi vào checkout mới, và bất cứ khi nào nghi môi trường lệch.
+  Giữ nó **idempotent + fail-fast**: agent nền phải dựng lại được mà không cần hỏi.
+- **`TASK.md`** — mở ra khi việc *sẽ vắt qua nhiều session* hoặc bạn sắp `/clear`. Cập nhật ở
+  **mốc** (xong một phần, chốt một quyết định), không phải mỗi dòng code. Nó là thứ agent kế
+  tiếp đọc để tiếp tục — viết cho "người lạ" hiểu, không viết tốc ký cho riêng mình.
+- **`new-worktree.sh`** — tách worktree khi chạy **≥2 hướng song song**, hoặc khi một task dài
+  cần cô lập khỏi nhánh chính. Một task = một worktree. Xong: `git worktree remove <dir>`.
+
+## Chạy nền & quay lại kiểm
+
+Việc thật dài có thể chạy ở background rồi quay lại xem (không ngồi canh). Nguyên tắc:
+khúc việc phải **resume được** — nếu đứt giữa chừng, `TASK.md` + `setup.sh` đủ để bắt lại từ
+mốc gần nhất, không phải làm lại từ đầu. Đó là lý do hai file kia tồn tại.

package/templates/long-running/TASK.md

@@ -0,0 +1,33 @@
+<!--
+TASK.md — bộ nhớ sống sót của một việc dài (Mức 4).
+
+Việc kéo dài quá một session sẽ mất trạng thái khi `/clear` hoặc khi mở session mới.
+File này là nơi agent (và agent kế tiếp) đọc để TIẾP TỤC, thay vì dựng lại từ đầu.
+
+Cách dùng:
+  - Đặt ở root repo hoặc thư mục task. Cập nhật KHI có mốc đáng nhớ, không cập nhật mỗi dòng.
+  - Trỏ CLAUDE.md tới nó: "Việc dài đang chạy ghi ở TASK.md — đọc trước khi bắt đầu."
+  - Xong việc thì xoá / archive, đừng để TASK.md cũ làm nhiễu.
+Xoá phần comment này khi bắt đầu dùng thật.
+-->
+
+# Task: <một dòng — đang làm gì>
+
+## Mục tiêu
+<Định nghĩa "xong" đo được. Việc này coi là hoàn thành khi nào?>
+
+## Đang ở đâu (cập nhật mỗi mốc)
+<Trạng thái hiện tại trong 2–4 gạch đầu dòng. Cái gì đã chạy được, cái gì chưa.>
+- 
+
+## Bước tiếp theo
+<Hành động cụ thể kế tiếp, đủ rõ để bắt tay ngay mà không phải nghĩ lại.>
+- [ ] 
+
+## Quyết định đã chốt (đừng mở lại)
+<Lựa chọn đã quyết + LÝ DO ngắn. Để agent sau không bàn lại từ đầu.>
+- 
+
+## Cạm bẫy đã gặp
+<Thứ đã thử mà hỏng, ngõ cụt — để khỏi đâm lại.>
+- 

package/templates/mcp-audit.md

@@ -0,0 +1,26 @@
+# MCP hygiene — checklist dọn tool thừa (Mức 2)
+
+Mỗi MCP server bạn cắm sẽ **bơm toàn bộ định nghĩa tool của nó vào context ở MỌI lượt** —
+dù lượt đó không dùng tới. 5 server ít dùng có thể ngốn hàng nghìn token mỗi lượt và làm
+model "rối tay" khi chọn tool. Đây là **thuế context vĩnh viễn**, không phải vấn đề an toàn
+(an toàn là Mức 3).
+
+## Cách xem đang cắm những gì
+
+```bash
+claude mcp list        # liệt kê MCP server đang cấu hình
+```
+
+## Với MỖI server, hỏi 3 câu
+
+- [ ] **Tháng qua có thực sự gọi tool của nó không?** Không → gỡ.
+- [ ] **Nó thêm bao nhiêu tool vào mỗi lượt, mà bạn chỉ dùng 1–2?** Thừa nhiều → gỡ hoặc tìm bản gọn hơn.
+- [ ] **Có thể thay bằng CLI sẵn có không?** (vd `gh` thay vì MCP GitHub cho việc đơn giản) → ưu tiên CLI, gỡ MCP.
+
+## Nguyên tắc
+
+> **Tool ít mà rõ > nhiều tool chồng chéo.** Giữ đúng cái bạn dùng hằng tuần.
+> Cắm thêm khi *thật sự* cần một nguồn/khả năng mới, không cắm "để sẵn cho chắc".
+
+Cắm MCP "để sẵn cho chắc" là cái bẫy phổ biến nhất ở Mức 2: nó âm thầm làm mọi session
+đắt hơn và kém chính xác hơn, mà không ai để ý.

package/templates/new-worktree.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# new-worktree.sh — tạo một git worktree + branch riêng cho một task song song/dài.
+#
+# Mức 4 (long-running): mỗi task nặng nên có cây làm việc RIÊNG, để chạy song song
+# mà không giẫm chân (không stash/switch liên tục, không sửa đè lên nhau).
+#
+# Dùng:   ./new-worktree.sh <tên-task>
+# Vd:     ./new-worktree.sh refactor-auth
+#   -> tạo branch 'refactor-auth' + thư mục ../<repo>-refactor-auth (cạnh repo, KHÔNG lồng trong).
+
+set -euo pipefail
+
+name="${1:-}"
+[ -n "$name" ] || { echo "dùng: $0 <tên-task>   (vd: refactor-auth)"; exit 1; }
+
+# Phải đứng trong một git repo.
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "✗ không phải git repo"; exit 1; }
+
+root="$(git rev-parse --show-toplevel)"
+repo="$(basename "$root")"
+dir="$root/../${repo}-${name}"          # đặt CẠNH repo, không lồng -> git status không nhiễu
+
+[ -e "$dir" ] && { echo "✗ đã tồn tại: $dir"; exit 1; }   # fail-fast, không ghi đè
+
+# Tách từ base mới nhất. Đổi 'main' nếu repo bạn dùng tên khác.
+base="$(git symbolic-ref --quiet --short HEAD || echo main)"
+
+if git show-ref --verify --quiet "refs/heads/${name}"; then
+  git worktree add "$dir" "$name"            # branch đã có -> checkout vào worktree mới
+else
+  git worktree add -b "$name" "$dir" "$base" # branch mới tách từ base hiện tại
+fi
+
+echo "✓ worktree: $dir   (branch: $name)"
+echo "  cd \"$dir\" để bắt đầu. Xong việc: git worktree remove \"$dir\""

package/templates/settings.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(./secrets/**)",
+      "Read(./**/id_rsa)",
+      "Read(./**/*.pem)"
+    ],
+    "ask": [
+      "Bash(git push:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git clean:*)",
+      "Bash(rm:*)"
+    ],
+    "allow": [
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)"
+    ]
+  }
+}

package/templates/setup.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# setup.sh — bootstrap môi trường: "một lệnh là repo chạy được".
+#
+# Mức 4 (long-running): agent chạy nền/lặp KHÔNG thể dừng hỏi "cài gì giờ".
+# Script này phải đưa một checkout sạch về trạng thái chạy-được, không cần tương tác.
+#
+# 2 nguyên tắc bắt buộc:
+#   - IDEMPOTENT: chạy lại nhiều lần vẫn an toàn (không nhân đôi, không hỏng state).
+#   - FAIL-FAST:  thiếu thứ gì báo NGAY rồi dừng, đừng chạy tiếp trong trạng thái mù.
+#
+# ĐÂY LÀ SKELETON — mỗi repo cài thứ khác nhau. Điền phần TODO cho repo của bạn,
+# rồi trỏ CLAUDE.md tới đây ("Build / Test / Run: chạy ./setup.sh trước").
+
+set -euo pipefail   # lỗi -> dừng; biến chưa set -> dừng; lỗi giữa pipe -> dừng
+
+cd "$(dirname "$0")"
+
+# --- 1. Kiểm điều kiện cần (fail-fast) -------------------------------------
+# Thiếu tool nền là báo ngay, đừng để lỗi mơ hồ ở bước sau.
+require() {
+  command -v "$1" >/dev/null 2>&1 || { echo "✗ thiếu '$1' — cài rồi chạy lại"; exit 1; }
+}
+# TODO: liệt kê tool repo bạn cần
+require git
+# require node
+# require python3
+
+# --- 2. Cài dependencies (idempotent) --------------------------------------
+# Hầu hết package manager đã idempotent sẵn — chạy lại chỉ no-op.
+# TODO: thay bằng lệnh của repo bạn
+# npm ci
+# uv sync
+# go mod download
+
+# --- 3. Cấu hình / secrets (fail-fast, KHÔNG tự tạo bừa) --------------------
+# Có .env.example mà chưa có .env -> báo cho người chạy tự điền, đừng đoán giá trị.
+# if [ -f .env.example ] && [ ! -f .env ]; then
+#   echo "✗ chưa có .env — copy .env.example rồi điền secrets"; exit 1
+# fi
+
+# --- 4. Dịch vụ phụ trợ (idempotent) ---------------------------------------
+# TODO: DB/queue... — dùng lệnh chỉ-tạo-nếu-chưa-có
+# docker compose up -d
+
+# --- 5. Verify: chứng minh môi trường thật sự chạy được --------------------
+# Đừng kết thúc bằng "xong" mù — chạy một check rẻ để chắc chắn.
+# TODO: lệnh smoke-test nhanh nhất của repo
+# npm run build --silent
+# python -c "import yourpkg"
+
+echo "✓ môi trường sẵn sàng"

package/templates/spec/FEATURE.md

@@ -0,0 +1,40 @@
+<!--
+FEATURE.md — spec một feature TRƯỚC khi viết code (spec-driven development).
+
+Đây là nửa "Specs" của trụ cột "Repo-local instructions & Specs": CLAUDE.md (Mức 1) lo luật bền
+xuyên MỌI task; FEATURE.md lo định nghĩa MỘT feature cụ thể trước khi bắt tay. Spec rõ → agent
+chạy đúng hướng, ít lạc; acceptance criteria rõ → có cái để eval (Mức 5) chấm đậu/rớt.
+
+Cách dùng: copy cho mỗi feature đáng-kể (vd docs/specs/<feature>.md). Việc nhỏ thì bỏ qua —
+đừng nghi thức hoá. Điền đủ phần, xoá comment này khi dùng thật.
+-->
+
+# Feature: <tên ngắn gọn>
+
+## Vấn đề / vì sao
+<Giải quyết cái gì cho ai. 1–3 câu. Nếu không nói rõ được "vì sao", khoan code.>
+
+## Phạm vi
+
+### Trong phạm vi
+- 
+
+### NGOÀI phạm vi (quan trọng — chặn scope creep)
+- 
+
+## Ràng buộc
+<Bắt buộc kỹ thuật/nghiệp vụ: API phải giữ nguyên, không thêm dependency, giới hạn hiệu năng…>
+- 
+
+## Acceptance criteria (đo được — đậu/rớt rõ ràng)
+<Cái PHẢI đúng thì feature mới coi là xong. Đây cũng là nguồn cho golden task ở Mức 5.>
+- [ ] 
+- [ ] 
+
+## Test hooks
+<Sẽ kiểm bằng test nào / lệnh nào. Ưu tiên tự động hoá được.>
+- 
+
+## Ghi chú thiết kế & quyết định đã chốt
+<Hướng tiếp cận + lý do ngắn. Để người sau (và agent) không bàn lại từ đầu.>
+- 

package/templates/spec/README.md

@@ -0,0 +1,34 @@
+# Specs — spec-driven development (nửa còn lại của Trụ cột 2)
+
+Trụ cột 2 là **"Repo-local instructions & Specs"**. Mức 1 (`/init-harness` → `CLAUDE.md`) lo nửa
+**instructions**: luật bền, đúng xuyên *mọi* task. `FEATURE.md` lo nửa **specs**: định nghĩa **một
+feature cụ thể TRƯỚC khi code**. Spec rõ → agent ít lạc hướng; acceptance criteria rõ → có sẵn cái
+cho eval Mức 5 chấm đậu/rớt.
+
+## Khi nào dùng
+
+- Feature **đủ lớn để dễ lạc** / nhiều bước / nhiều người → viết spec trước.
+- Việc nhỏ, một-phát-xong → **bỏ qua**. Đừng biến spec thành nghi thức.
+
+## `FEATURE.md` vs `TASK.md` (đừng nhầm — chúng bổ sung nhau)
+
+| | `FEATURE.md` (ở đây) | `TASK.md` (Mức 4) |
+|---|---|---|
+| Mục đích | **plan TRƯỚC khi code**: cái gì + tiêu chí đậu | **trạng thái sống còn QUA session** |
+| Vòng đời | viết 1 lần đầu feature, ít đổi | cập nhật liên tục ở mỗi mốc |
+| Trả lời | "feature này *là gì*, xong khi nào" | "*đang* làm tới đâu, bước kế" |
+
+Feature lớn thường dùng **cả hai**: `FEATURE.md` chốt đích, `TASK.md` theo dõi đường đi.
+
+## Cài
+
+```bash
+mkdir -p docs/specs
+cp FEATURE.md docs/specs/<tên-feature>.md
+```
+
+## Nâng cao
+
+Feature lớn / cả team → dùng framework chuyên: **GitHub Spec Kit**, **12-Factor Agents** (link
+trong `docs/harness-engineering-tutorial.md`). `FEATURE.md` chỉ là bản tối giản để bắt đầu — đủ
+để có spec, không bắt bạn nuốt cả framework.