Product Spec Harness Eco-system

An AI-powered harness for Claude Code to define, strictly validate, brutally critique, ship, and observe Product Specs. Bulletproof requirements before a single line of code is written — then package the whole rig and watch how it actually gets used.

It is not just a pile of skills. Installing the bundle drops a coordinated .claude/ rig into your project: four skills, the critique sub-agents they spawn, the hooks that nudge and instrument them, the rules that steer the orchestration, a shared eval-gate, and a deterministic packager — all wired to work together.

📘 Usage guides (every use case as a sample conversation):

• product-spec — GUIDE-VI.md (Tiếng Việt) · GUIDE-EN.md (English)
• product-spec-critique — GUIDE-VI.md (Tiếng Việt) · GUIDE-EN.md (English)
• release — GUIDE-VI.md (Tiếng Việt) · GUIDE-EN.md (English)
• telemetry — GUIDE-VI.md (Tiếng Việt) · GUIDE-EN.md (English)

What the harness installs (the whole rig, not just skills)

Generated as you use it: your spec under docs/product/, telemetry sinks under .claude/telemetry/*.jsonl (gitignored runtime data, never bundled), and reproducible tarballs under dist/.

The four skills share one Python virtual environment at .claude/skills/.venv/ (created by any installer). The telemetry lenses and its sink hooks are stdlib-only and also run under a plain system python3 on a recipient machine.

🇬🇧 English overview below · 🇻🇳 Tiếng Việt: cuộn xuống mục Tiếng Việt ở cuối trang.

---

product-spec — for Product Owners

Runs an interview, captures your product spec as a strictly-traceable hierarchy, validates it, and visualizes it — all in plain language, no code required from you. Bilingual: English and Vietnamese.

What it does for you

Output lives in docs/product/ inside your project — markdown files with rich YAML metadata. The skill never writes outside docs/product/.

Install

# POSIX (macOS / Linux / WSL)
bash .claude/skills/product-spec/install.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\.claude\skills\product-spec\install.ps1

Requires Python 3.11+ and (on first run only, if the vendored JS is absent) curl/wget. The installer creates the shared venv, installs pyyaml, and vendors the Mermaid + marked + DOMPurify runtimes for offline HTML. Idempotent — re-running is safe.

Then invoke from Claude Code:

/cleanmatic:product-spec

Deep links

• Usage guide: GUIDE-VI.md / GUIDE-EN.md
• README: .claude/skills/product-spec/README.md
• Operating contract: .claude/skills/product-spec/SKILL.md
• Worked sample: examples/acme-shop

What it does NOT do

• No production code — output is product specs; your engineering team writes the code.
• No story-point / hour estimation — stories carry only size: S | M | L.
• No overwriting your manual edits — on --update it flags affected items and asks first.
• No auto-flipping an approved decision — contradictions are surfaced for you to resolve (Keep / Change / Hybrid).
• No internet at runtime — after install, everything runs on your machine (one caveat: if Mermaid failed to vendor at install time, Mermaid graph views fall back to a CDN script at browser-render; re-run the installer to vendor it — ASCII and body views never reach a CDN).

💬 Want an opinion, not just a pass/fail? product-spec-critique (below) tears the same spec apart and tells you whether it is worth building. Optional: install its post-validate drift nudge with product-spec-critique/install.sh --critique-hook to be reminded (once per session) when the spec has changed enough to be worth re-critiquing.

---

product-spec-critique — for Product Owners

--validate tells you the spec is structurally sound. product-spec-critique tells you whether it is any good — an honest, sarcastic, brutal-but-grounded tear-down across four lenses (product / tech / market / craft). It reuses the validate findings as ammo, then says what validate cannot: why this would die in the market, whether it is a me-too, whether the writing actually holds up. It never edits your spec and is never in a CI gate (it is opinion + web research + voice, non-deterministic by design).

What it does for you

Every finding cites a real ID:line, says why it dies, and ends with a concrete fix — no free-floating insults.

Re-runs are cheap. Critique the same scope twice and it reuses prior work (no spec change → nothing re-analysed; just a level bump → only the voice re-renders). Critique a child after its parent and the child inherits the parent’s unresolved blockers as risk; critique a parent after its children and it rolls up “N of M children carry blockers”. All token-saving only — --fresh forces a full rebuild.

Voice levels (1 to 9) and the safety floor

Nine intensity levels. Default is 5 (no-mercy: brutal, may jab you, but still all about the work). Levels 1 to 4 never attack you, only the artifact. Levels 6 to 9 are dangerous and opt-in — 6 roasts you as the author, 7 to 9 escalate through a harsher Vietnamese register (ông/tôi → mày/tao) and, at 9, work-aimed profanity; 6 to 8 ask you to confirm, and 9 re-confirms on every run. There is one line the tool never crosses, at any level, even 9, even with your consent: it attacks the work, never you — no threats, no slurs on who you are, nothing about your family, no self-harm or sexual content. The rule is the target of the line, not how harsh it is.

Deep links

• Usage guide: GUIDE-VI.md / GUIDE-EN.md
• README: .claude/skills/product-spec-critique/README.md
• Operating contract: .claude/skills/product-spec-critique/SKILL.md
• The voice (all 9 levels + the floor): references/voice-and-tone.md

What it does NOT do

• No code generation, and no spec editing — it writes one critique report, never touches your spec artifacts.
• No CI gate — it is opinionated and non-deterministic by design; --validate stays the reproducible gate.
• No auto-memory — a big finding only becomes a recorded decision (DEC-) if you confirm it.
• It does not run --validate for you — that stays reproducible and PO-facing; critique only reads its results.

---

release — for Developers

Bundles a curated subset of .claude/ (skills, agents, hooks, rules) plus optional top-level files into a versioned, deterministic tar.gz. Each bundle ships a MANIFEST.json (per-file SHA256), an INSTALL.md, and multiplatform installers (install.sh + install.ps1) so the recipient extracts once and runs.

What it does for you

Output lands in dist/product-spec-{version}.tar.gz + a .sha256 sidecar (dist/ is gitignored — tarballs are reproducible artifacts, not source).

Install

# POSIX (macOS / Linux / WSL)
bash .claude/skills/release/install.sh            # add --dev for pytest

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File .\.claude\skills\release\install.ps1

Requires Python 3.11+. Then invoke from Claude Code:

/cleanmatic:release

Deep links

• Usage guide: GUIDE-VI.md / GUIDE-EN.md
• README: .claude/skills/release/README.md
• Operating contract: .claude/skills/release/SKILL.md

What it does NOT do

• No remote upload — use gh release upload manually.
• No GPG signing in v1 — SHA256 sidecar only.
• No merge-resolver — the recipient installer skips existing skills; FORCE_OVERWRITE=1 opts in.
• No multi-project packing — one .claude/ root per bundle.
• No zip / tar.zst — tar.gz only in v1.

---

telemetry — for Product Owners

After you have been using the harness for a while, telemetry tells you — in plain Vietnamese — how your own tooling is actually doing. It is read-only and honest by design: it reports whether the machinery runs (usage & health), never whether the product wins in the market (that is E3, deliberately out of scope). A script gathers deterministic counts; the skill narrates them, always ending with a “what this does NOT measure” section.

What it does for you

Eight lenses (usage, session, health, reliability, workflow, validate, memory, forensics); four formats (ascii, md, mermaid, json). On a thin/new repo most lenses say “chưa đủ dữ liệu” and suppress recommendations rather than inventing trends.

The 5 sink hooks are auto-registered at install (opt out with python3 .claude/skills/telemetry/scripts/register_telemetry_hooks.py --remove). They are fail-open, make no network calls, and write only to gitignored .claude/telemetry/*.jsonl sinks.

Deep links

• Usage guide: GUIDE-VI.md / GUIDE-EN.md
• README: .claude/skills/telemetry/README.md
• Operating contract: .claude/skills/telemetry/SKILL.md
• Narration & honesty gate: references/narration-contract.md

What it does NOT do

• No market/user-outcome metric (E3) — the validate proxy means “spec is well-formed”, not “users adopted it”.
• No writing — it never edits specs, code, the catalog, or memory; there is no --apply.
• Not billing-exact — token weight and ms durations are directional/approx, labelled “ước lượng”.
• Not a CI gate — opinion-free numbers for you to read; nothing blocks on it.

---

Bilingual (product-spec)

• The interview asks questions in your chosen language (--lang en or --lang vi).
• LLM-generated prose (vision narrative, story descriptions, AC) is written in your chosen language.
• IDs (BRD-G1, PRD-AUTH, PRD-AUTH-E1-S1) and frontmatter keys (personas, scope, moscow, …) stay English so the structure is stable.
• Visualization labels (Now/Next/Later, Must/Should/Could/Won't) localize when you pass --lang vi.

Vietnamese phrasing is native-reviewed for natural wording.

---

Troubleshooting

---

Privacy

All four skills make no network calls at runtime (telemetry’s sink hooks and lenses are fail-open and stdlib-only; they read/write only local gitignored .claude/telemetry/*.jsonl sinks and never transmit anything). product-spec’s one-time installer downloads the Mermaid, marked, and DOMPurify runtimes from the public CDN (cdn.jsdelivr.net); each is then stored locally as mermaid.min.js / marked.min.js / purify.min.js and verified against a pinned SHA-256 hash. (Degraded-install caveat: if mermaid.min.js failed to vendor, product-spec’s Mermaid graph views fall back to a cdn.jsdelivr.net `` at browser-render time — re-run the installer to vendor it; ASCII and body views never reach a CDN.) release’s safety filter always drops .env/secrets/keys, .git/, runtime caches, and session state from any bundle — non-removable via any flag.

---

Need help?

Each skill can answer most “how do I…” questions — invoke it and ask. For installer issues, re-run the POSIX installer with bash -x .claude/skills//install.sh to see each step. For deeper detail, start from the skill’s GUIDE-*.md and SKILL.md.

---

License

Copyright © 2026 Hieu Bui. Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — see LICENSE.

In short: you may use, study, modify, and share this freely, but if you run a modified version as a network service or distribute it, you must release your complete source under AGPL-3.0 too. You may not fold this code into a closed-source / proprietary commercial product — that requires a separate commercial license (contact the copyright holder). See CONTRIBUTING.md for how contributions are licensed (inbound = outbound).

---

Tiếng Việt

Một bộ AI Harness cho Claude Code giúp định nghĩa, kiểm tra chặt, phản biện gắt gao, đóng gói và quan sát các Đặc tả Sản phẩm (Product Spec). Ép logic Business phải chặt chẽ trước khi bàn giao cho Dev — rồi đóng gói cả bộ và theo dõi nó thực sự được dùng ra sao.

Đây không chỉ là một mớ skill. Cài bundle là thả vào dự án bạn cả một bộ .claude/ phối hợp: bốn skill, các sub-agent phản biện mà chúng gọi ra, các hook nhắc/đo lường chúng, các rule điều phối, một eval-gate dùng chung, và một bộ đóng gói deterministic — tất cả nối với nhau.

Bốn skill dùng chung một venv Python ở .claude/skills/.venv/ (do bất kỳ installer nào tạo). Riêng telemetry (lăng kính + 5 sink hook) chỉ dùng stdlib nên chạy được cả bằng python3 hệ thống trên máy người nhận.

Harness cài những gì (cả bộ, không chỉ skill)

Sinh ra khi bạn dùng: spec ở docs/product/, sink telemetry ở .claude/telemetry/*.jsonl (dữ liệu runtime, gitignore, không bao giờ bundle), và tarball reproducible ở dist/.

📘 Hướng dẫn dùng (mỗi tình huống là một hội thoại mẫu) + lộ trình học + khái niệm cốt lõi: mỗi skill có GUIDE-VI.md (Tiếng Việt) và GUIDE-EN.md (English) trong thư mục của nó. README chi tiết từng skill cũng có 2 phần Anh + Việt.

product-spec — cho Product Owner

Phỏng vấn bạn, ghi lại spec thành cây có truy vết chặt, kiểm tra và trực quan hóa — tất cả bằng lời, không cần code.

Đầu ra nằm trong docs/product/ của dự án bạn (markdown + metadata YAML). Skill không bao giờ ghi ra ngoài docs/product/.

KHÔNG làm: không sinh code; không ước lượng story-point/giờ (chỉ size: S|M|L); không ghi đè văn bạn viết (gắn cờ + hỏi khi --update); không tự đảo ngược quyết định đã duyệt (nêu ra Giữ/Đổi/Kết hợp); không cần Internet khi chạy.

product-spec-critique — cho Product Owner

--validate nói spec vững về cấu trúc. product-spec-critique nói nó có tốt không — một bản mổ xẻ thật lòng, châm biếm, gắt-nhưng-có-căn-cứ qua bốn lăng kính. Mỗi phát hiện trích mã:dòng, nói vì sao nó chết, kèm cách sửa. Không bao giờ sửa spec và không bao giờ vào cổng CI (quan điểm + tra mạng + giọng, bản chất không tất định).

Mức giọng (1→9) và lằn ranh an toàn. Mặc định mức 5 (gắt, có thể đá xéo bạn, nhưng vẫn xoay quanh công việc). Mức 1–4 không công kích bạn, chỉ hiện vật. Mức 6–9 nguy hiểm, phải opt-in — mức 6 chửi thẳng người viết; 7–9 leo thang theo bậc đại từ (ông/tôi → mày/tao) và ở mức 9 có chửi thề nhắm-vào-công-việc; 6–8 hỏi xác nhận, mức 9 hỏi lại mỗi lần chạy. Có một lằn ranh không bao giờ vượt ở mọi mức kể cả 9, kể cả khi bạn đồng ý: nó nhắm công việc, không nhắm bạn — không đe dọa, không miệt thị con người bạn, không nhắm gia đình, không tự hại/tình dục.

KHÔNG làm: không sinh code, không sửa spec (chỉ ghi báo cáo); không làm cổng CI; không tự ghi bộ nhớ (chỉ thành DEC- khi bạn xác nhận); không tự chạy --validate.

release — cho Developer

Đóng gói một tập con chọn lọc của .claude/ thành tar.gz versioned + deterministic. Mỗi bundle kèm MANIFEST.json (per-file SHA256), INSTALL.md, và installer đa nền tảng (install.sh + install.ps1).

Đầu ra ở dist/product-spec-{version}.tar.gz + sidecar .sha256 (dist/ bị gitignore — tarball là artifact reproducible, không phải source).

6 điều cốt lõi: manifest là source-of-truth; determinism là hợp đồng (byte-identical); safety filter không thể tắt (secrets/.env/.git/caches luôn bị loại, settings/.ck opt-in); script lo cấu trúc, LLM lo UI; không auto-install (người nhận tự chạy); release chỉ kích bằng tag qua CI — không bao giờ gh release create bằng tay (SHA build tay không khớp build CI).

telemetry — cho Product Owner

Sau khi dùng harness một thời gian, telemetry cho bạn biết — bằng tiếng Việt thuần — bộ đồ nghề của bạn đang chạy thế nào. Nó chỉ-đọc và trung thực theo thiết kế: báo máy móc có chạy không (mức dùng & sức khỏe), không bao giờ báo sản phẩm có thắng thị trường không (đó là E3, cố ý nằm ngoài phạm vi). Script gom số liệu tất định; skill diễn giải, luôn kết thúc bằng mục “Cái này KHÔNG đo được”.

Tám lăng kính (usage, session, health, reliability, workflow, validate, memory, forensics); bốn định dạng (ascii, md, mermaid, json). Trên repo mới/mỏng, hầu hết lăng kính nói “chưa đủ dữ liệu” và tắt gợi ý thay vì bịa ra xu hướng.

5 sink hook tự đăng ký khi cài (tắt bằng python3 .claude/skills/telemetry/scripts/register_telemetry_hooks.py --remove). Chúng fail-open, không gọi mạng, chỉ ghi vào sink .claude/telemetry/*.jsonl (đã gitignore).

KHÔNG làm: không đo hiệu quả thị trường/người dùng (E3 — proxy validate nghĩa là “spec đúng cấu trúc”, không phải “người dùng đã chấp nhận”); không ghi gì (không sửa spec/code/catalog/memory, không --apply); không chính xác hóa đơn (token & ms là ước lượng); không làm cổng CI.

Song ngữ (product-spec)

Phỏng vấn hỏi bằng ngôn ngữ bạn chọn (--lang en / --lang vi); phần văn LLM sinh ra (tầm nhìn, mô tả story, AC) viết theo ngôn ngữ đó. Mã (BRD-G1, PRD-AUTH-E1-S1) và khóa frontmatter (personas, scope, moscow…) giữ tiếng Anh để cấu trúc ổn định. Nhãn trực quan (Now/Next/Later, Must/Should/Could/Won't) bản địa hóa khi --lang vi. Tiếng Việt được người bản ngữ rà cho tự nhiên.

Quyền riêng tư

Cả bốn skill không gọi mạng khi chạy (sink hook + lăng kính của telemetry fail-open, chỉ-stdlib, chỉ đọc/ghi sink cục bộ .claude/telemetry/*.jsonl đã gitignore, không truyền gì đi đâu). Installer một lần của product-spec tải Mermaid/marked/DOMPurify từ CDN công khai rồi lưu cục bộ + verify SHA-256. Safety filter của release luôn loại .env/secrets/keys, .git/, caches, session state khỏi mọi bundle — không flag nào kéo lại được.

Cần trợ giúp?

Mỗi skill tự trả lời được hầu hết câu “làm thế nào…” — cứ gọi nó và hỏi. Sự cố installer: chạy lại bash -x .claude/skills//install.sh để thấy từng bước. Chi tiết sâu hơn: bắt đầu từ GUIDE-*.md và SKILL.md của skill. Bảng xử lý sự cố đầy đủ ở mục English bên trên.

Giấy phép

Copyright © 2026 Hieu Bui. Cấp phép theo GNU Affero General Public License v3.0 (AGPL-3.0) — xem LICENSE.

Tóm tắt: bạn được tự do dùng, nghiên cứu, sửa và chia sẻ, nhưng nếu chạy bản đã sửa dưới dạng dịch vụ qua mạng hoặc phân phối nó, bạn phải công bố toàn bộ source dưới AGPL-3.0. Bạn không được đưa code này vào sản phẩm thương mại đóng/độc quyền — việc đó cần một license thương mại riêng (liên hệ chủ bản quyền). Xem CONTRIBUTING.md về cách đóng góp được cấp phép (inbound = outbound).