VisionTầm nhìn
The Product Spec Harness is opinionated by design. Every flag, every rule, every limit traces back to a small set of principles chosen to keep a non-technical product owner in control of their own spec — and keep the AI from taking shortcuts that erode that control. This page documents those principles, the always-on safety floor, and the feedback loop they make possible.Product Spec Harness có quan điểm rõ ràng theo thiết kế. Mọi flag, mọi rule, mọi giới hạn đều xuất phát từ một tập nhỏ nguyên tắc được chọn để giữ cho Product Owner không chuyên kỹ thuật nắm quyền kiểm soát spec của mình — và ngăn AI đi tắt theo cách làm mòn quyền kiểm soát đó. Trang này ghi lại những nguyên tắc đó, lằn ranh an toàn luôn bật, và vòng phản hồi mà chúng tạo ra.
Five operating principlesNăm nguyên tắc vận hành
These five principles are stated verbatim in CLAUDE.md and govern every turn — not just when a skill is loaded. They resolve the ambiguity that anti-rationalization shortcuts exploit.Năm nguyên tắc này được ghi nguyên văn trong CLAUDE.md và chi phối mọi lượt — không chỉ khi skill được nạp. Chúng giải quyết sự mơ hồ mà các lối tắt anti-rationalization khai thác.
1 — Frontmatter is source-of-truth1 — Frontmatter là nguồn chân lý
Parse YAML; never infer structure from headings. The spec hierarchy lives in structured frontmatter, not in prose. A heading can be edited without changing the spec's meaning; the YAML fields cannot be.Phân tích YAML; không bao giờ suy cấu trúc từ heading. Cây spec nằm trong frontmatter có cấu trúc, không phải trong văn xuôi. Heading có thể sửa mà không đổi nghĩa spec; các trường YAML thì không.
2 — DRY — one home per fact2 — DRY — một nơi cho mỗi sự thật
Cross-reference by ID; never duplicate prose. A goal stated in the BRD is referenced from child PRDs by its ID (BRD-G1), not copied. Copied prose drifts; IDs don't.Tham chiếu bằng ID; không bao giờ nhân đôi văn xuôi. Mục tiêu trong BRD được tham chiếu từ PRD con bằng ID (BRD-G1), không sao chép. Văn sao chép thì trôi dạt; ID thì không.
3 — Script vs LLM split — scripts handle graph/struct; LLM judges prose/alignment. Scripts first.3 — Phân tách script vs LLM — script lo đồ thị/cấu trúc; LLM nhận định văn/căn chỉnh. Script chạy trước.
Deterministic scripts catch orphans, broken trace, missing AC, ID integrity. The LLM layer adds what scripts cannot: INVEST quality, vagueness, core-value drift, contradiction. Running scripts first keeps the gate reproducible; the LLM layer is advisory and never gates CI alone.Script tất định bắt mồ côi, truy vết gãy, thiếu AC, toàn vẹn ID. Lớp LLM thêm cái script không làm được: chất lượng INVEST, độ mơ hồ, lệch core-value, mâu thuẫn. Script chạy trước giữ cổng có thể tái tạo; lớp LLM là advisory và không bao giờ một mình gác CI.
4 — Never overwrite PO prose4 — Không bao giờ ghi đè văn của PO
On --update, flag affected nodes and ask before regenerating. The product owner's wording is their intent. Silently tidying it up substitutes the AI's judgment for theirs. Flag, then ask — always.Khi --update, gắn cờ node bị ảnh hưởng và hỏi trước khi sinh lại. Cách diễn đạt của PO là chủ ý của họ. Lặng lẽ "dọn dẹp" là thay thế phán đoán của AI cho phán đoán của họ. Gắn cờ, rồi hỏi — luôn luôn.
5 — No silent reversals5 — Không đảo ngầm
A new claim that contradicts an approved artifact is a stop point — not an auto-fix. Three choices are surfaced: Keep (reject the new claim) · Change (re-approve with owner + date) · Hybrid (record both, schedule follow-up). Only the PO choosing Change with explicit re-approval touches approved content. See the Decision Register for how rulings are recorded.Một khẳng định mới mâu thuẫn với hiện vật approved là điểm dừng — không phải tự sửa. Ba lựa chọn được đưa ra: Giữ (bác khẳng định mới) · Đổi (duyệt lại với chủ sở hữu + ngày) · Kết hợp (ghi cả hai, lên lịch theo dõi). Chỉ PO chọn Đổi với duyệt lại tường minh mới được chạm nội dung đã duyệt. Xem Decision Register để biết cách ghi phán quyết.
- "Let me just write the code" → Spec tool. Capture story + AC for the build team."Để tôi viết code luôn" → Đây là công cụ spec. Ghi story + AC cho đội build.
- "Scope is obvious, I'll set it" → Scope is the PO's call. Never assume — ask."Phạm vi hiển nhiên, tôi tự đặt" → Phạm vi là quyền của PO. Không được giả định — hỏi.
- "Contradicts approved, I'll fix it" → Surface Keep / Change / Hybrid. Never silently flip."Mâu thuẫn rồi, tôi sửa luôn" → Đưa ra Giữ / Đổi / Kết hợp. Không bao giờ tự đảo.
- "Clear to mark approved" → Needs explicit PO approval + owner + date."Rõ ràng rồi, đánh dấu approved luôn" → Cần duyệt tường minh của PO + chủ sở hữu + ngày.
- "I'll tidy their wording" → Never overwrite PO prose. Flag, then ask."Để tôi dọn văn của họ" → Không bao giờ ghi đè văn PO. Gắn cờ, rồi hỏi.
The always-on safety floorLằn ranh an toàn luôn bật
Two GATEs in CLAUDE.md apply on every single turn — they do not depend on a skill being loaded, a reference file being in context, or a PO having opted in. They are the floor below which the harness never operates.Hai GATE trong CLAUDE.md áp dụng mọi lượt đơn lẻ — không phụ thuộc vào việc có skill được nạp, file tham chiếu có trong context, hay PO đã opt-in hay không. Chúng là lằn ranh mà harness không bao giờ hoạt động dưới đó.
GATE-NO-SILENT-REVERSAL
A new claim that contradicts an approved artifact is a stop point. Do not edit, pick a side, or tidy it up. Surface verbatim with three choices: Keep (reject new claim) · Change (re-approve, owner + date) · Hybrid (record both, follow-up). Only the PO choosing Change with explicit re-approval touches approved content. If unsure it truly contradicts — ask. Record the ruling in the Decision Register (DEC-<n>) so it is not re-litigated.Một khẳng định mới mâu thuẫn với hiện vật approved là điểm dừng. Không sửa, không chọn phe, không dọn dẹp. Đưa ra nguyên văn với ba lựa chọn: Giữ (bác khẳng định mới) · Đổi (duyệt lại, chủ sở hữu + ngày) · Kết hợp (ghi cả hai, theo dõi). Chỉ PO chọn Đổi với duyệt lại tường minh mới được chạm nội dung đã duyệt. Không chắc có thật sự mâu thuẫn không — hỏi. Ghi phán quyết vào Decision Register (DEC-<n>) để không tranh luận lại.
GATE-NEVER-ASSUME
Ask by default. Assume only when: the PO already answered (.session.md / PRODUCT.md); a closed allowed-value field has exactly one fit; or generating PO-editable boilerplate (and you say so). Never assume persona identities/counts, core-value alignment, scope (in / out / core-value), or sign-off. Never set status: approved without explicit PO approval + owner + date. In doubt about assuming — you're not. Ask.Hỏi theo mặc định. Chỉ giả định khi: PO đã trả lời (.session.md / PRODUCT.md); trường giá trị đóng có đúng một lựa chọn phù hợp; hoặc sinh boilerplate PO-có-thể-sửa (và bạn nói rõ điều đó). Không bao giờ giả định danh tính/số lượng persona, căn chỉnh core-value, phạm vi (in / out / core-value), hay duyệt. Không bao giờ đặt status: approved mà không có duyệt tường minh của PO + chủ sở hữu + ngày. Nghi ngờ về việc giả định — bạn không nên. Hỏi.
These GATEs cannot be waived — not even if the PO says "skip asking." If the PO requests that, proceed, but name the residual risk. The gates themselves never switch off.Các GATE này không thể bãi bỏ — kể cả khi PO nói "bỏ qua phần hỏi." Nếu PO yêu cầu vậy, tiến hành, nhưng nêu rủi ro còn lại. Bản thân các gate không bao giờ tắt.
The closed loopVòng khép kín
The four skills are not independent tools — they form a pipeline with a return edge. A critique report flows back into the spec via --apply-critique, turning findings into recorded decisions. Usage data flows back via telemetry, showing which skills run and which stall. The --learn flag closes the full loop: spec → build → measure → learn.Bốn skill không phải công cụ độc lập — chúng tạo thành một quy trình có cạnh quay về. Báo cáo phản biện chảy ngược vào spec qua --apply-critique, biến phát hiện thành quyết định được ghi. Dữ liệu mức dùng chảy ngược qua telemetry, cho thấy skill nào chạy và skill nào bị nghẽn. Cờ --learn khép vòng hoàn toàn: spec → build → đo → học.
Define → Validate → CritiqueĐịnh nghĩa → Kiểm tra → Phản biện
product-spec builds the hierarchy; --validate proves it is structurally sound; product-spec-critique says whether it is actually good — and why it might die. The critique report ends with concrete fixes, not free-floating insults.product-spec dựng cây; --validate chứng minh nó vững về cấu trúc; product-spec-critique nói nó có thực sự tốt không — và vì sao nó có thể chết. Báo cáo phản biện kết thúc bằng cách sửa cụ thể, không phải những lời chỉ trích vô căn.
Critique → Decisions (--apply-critique)Phản biện → Quyết định (--apply-critique)
A finding becomes a DEC-<n> entry in the Decision Register only when the PO confirms it. --apply-critique <report> walks through each finding and asks. Nothing is auto-accepted. See Decision Register for the full ruling format.Một phát hiện chỉ trở thành mục DEC-<n> trong Decision Register khi PO xác nhận. --apply-critique <báo-cáo> đi qua từng phát hiện và hỏi. Không có gì được tự động chấp nhận. Xem Decision Register cho định dạng phán quyết đầy đủ.
Approved spec → Ship (release)Spec đã duyệt → Đóng gói (release)
Once the spec is approved and critiques resolved, release packs the harness itself — skills, agents, hooks, rules, eval-gate — into a versioned, byte-identical tar.gz. CI builds are tag-triggered; SHA-256 sidecars prove integrity. See release.Khi spec đã duyệt và phản biện được xử lý, release đóng gói bản thân harness — skill, agent, hook, rule, eval-gate — thành tar.gz versioned, byte-identical. Build CI kích bởi tag; sidecar SHA-256 chứng minh toàn vẹn. Xem release.
Observe → Learn (telemetry)Quan sát → Học (telemetry)
telemetry closes the loop with read-only usage and health data — which skills ran, which scripts errored, whether sub-agents succeeded. It reports whether the machinery runs, never whether the product wins the market. Every report ends with a mandatory "what this does NOT measure" section. See telemetry.telemetry khép vòng bằng dữ liệu mức dùng và sức khỏe chỉ-đọc — skill nào chạy, script nào lỗi, sub-agent có thành công không. Nó báo máy móc có chạy không, không bao giờ báo sản phẩm có thắng thị trường không. Mọi báo cáo kết thúc bằng mục bắt buộc "cái này KHÔNG đo được". Xem telemetry.
The full journey — from first install through a spec, critique, and shipped release — is walked step by step in the journey guide.Hành trình đầy đủ — từ lần cài đầu tiên qua spec, phản biện, và phát hành — được đi từng bước trong hướng dẫn hành trình.
Built for product ownersĐược xây dựng cho Product Owner
No code requiredKhông cần code
Every skill is invoked with a single /cleanmatic:* command. The interview, validation, critique, and reports all happen in plain language. The PO never touches a terminal, a YAML file, or a Python script directly.Mọi skill được gọi bằng một lệnh /cleanmatic:* duy nhất. Phỏng vấn, kiểm tra, phản biện và báo cáo đều diễn ra bằng ngôn ngữ bình thường. PO không bao giờ trực tiếp chạm terminal, file YAML hay script Python.
Bilingual EN / VISong ngữ EN / VI
Every skill accepts --lang en or --lang vi. The interview, generated prose, visualization labels, and critique reports all render in the chosen language. IDs and frontmatter keys stay English so the structure is stable across languages. Vietnamese phrasing is native-reviewed for natural wording.Mọi skill nhận --lang en hoặc --lang vi. Phỏng vấn, văn sinh ra, nhãn trực quan và báo cáo phản biện đều render theo ngôn ngữ được chọn. ID và khóa frontmatter giữ tiếng Anh để cấu trúc ổn định. Tiếng Việt được người bản ngữ rà cho tự nhiên.
Offline after installOffline sau khi cài
All four skills make no network calls at runtime. Your spec, your telemetry data, and your critique reports stay on your machine. The one-time installer vendors the JS runtimes and verifies each with a pinned SHA-256. See the rig — runs offline for the full privacy guarantee.Cả bốn skill không gọi mạng khi chạy. Spec, dữ liệu telemetry và báo cáo phản biện của bạn ở trên máy bạn. Installer một lần vendor JS runtime và verify từng cái bằng SHA-256 đã ghim. Xem bộ máy — chạy offline cho đảm bảo quyền riêng tư đầy đủ.
LICENSE and CONTRIBUTING.md.
AGPL-3.0: bạn được tự do dùng, nghiên cứu, sửa và chia sẻ harness. Nếu chạy bản đã sửa dưới dạng dịch vụ qua mạng hoặc phân phối, bạn phải công bố toàn bộ source dưới AGPL-3.0. Tích hợp vào sản phẩm thương mại đóng cần license thương mại riêng. Xem LICENSE và CONTRIBUTING.md.