The RigCả Bộ Máy
The homepage teaser names the pieces. This page walks each one. Installing the bundle drops a single coordinated .claude/ tree into your project — four skills, seven critique sub-agents, hooks that instrument them, rules that steer the orchestration, a shared eval-gate, and a deterministic packager. All wired to work together; nothing requires a server or a network call at runtime.Trang chủ đặt tên các thành phần. Trang này đi qua từng cái. Cài bundle là thả vào dự án một cây .claude/ phối hợp duy nhất — bốn skill, bảy sub-agent phản biện, hook đo lường chúng, rule điều phối, eval-gate dùng chung, và bộ đóng gói deterministic. Tất cả nối với nhau; không cái nào cần server hay gọi mạng khi chạy.
What installs — the coordinated .claude/ treeCài gì — cả cây .claude/ phối hợp
A single install.sh (or install.ps1) call places all six groups of components under your project's .claude/ directory and creates the shared Python virtual environment. The table below is the exact layout — no generated runtime files, no hidden extras.Một lần gọi install.sh (hoặc install.ps1) đặt tất cả sáu nhóm thành phần vào .claude/ của dự án và tạo venv Python dùng chung. Bảng dưới là bố cục chính xác — không có file runtime sinh ra, không có gì ẩn.
| ComponentThành phần | PathĐường dẫn | CountSố lượng | What it isLà gì |
|---|---|---|---|
| SkillsSkill | .claude/skills/ |
4 | User-invocable /cleanmatic:* commands. Each is self-contained with its own scripts/, references/, and guides.Lệnh /cleanmatic:* người dùng gọi. Mỗi skill tự chứa với scripts/, references/ và guide riêng. |
| Sub-agentsSub-agent | .claude/agents/ |
7 | Critique lens critics + consolidator + humanizer + memory harvester — spawned by product-spec-critique and --reflect.Lens critic phản biện + consolidator + humanizer + memory harvester — được product-spec-critique và --reflect gọi ra. |
| HooksHook | .claude/hooks/ |
7 | 5 telemetry sinks (auto-registered) + memory-gap enforcement + critique-nudge (both opt-in).5 sink telemetry (tự đăng ký) + memory-gap + critique-nudge (cả hai opt-in). |
| RulesRule | .claude/rules/ |
5 | Workflow · orchestration · development · documentation rules + the always-on safety floor (CLAUDE.md).Rule workflow · điều phối · phát triển · tài liệu + lằn ranh an toàn luôn bật (CLAUDE.md). |
| Shared eval-gateEval-gate dùng chung | .claude/skills/_shared/lib/ |
2 scripts | run_evals.py (structural) + llm_eval.py (advisory) + runnable golden fixtures bundled per skill.run_evals.py (cấu trúc) + llm_eval.py (advisory) + fixture golden chạy được đóng kèm mỗi skill. |
| Packager + installerĐóng gói + installer | project rootgốc dự án | — | pack.manifest.yaml + install.sh / install.ps1 — deterministic builder and multiplatform installer that recreates the shared venv.pack.manifest.yaml + install.sh / install.ps1 — builder deterministic + installer đa nền tảng dựng lại venv dùng chung. |
Generated at runtime (not bundled): your spec under docs/product/, telemetry sinks under .claude/telemetry/*.jsonl (gitignored), and reproducible tarballs under dist/.Sinh ra khi chạy (không bundle): spec ở docs/product/, sink telemetry ở .claude/telemetry/*.jsonl (gitignored), và tarball reproducible ở dist/.
The pieces — a closer lookCác thành phần — nhìn gần hơn
product-spec— interview, spec, validate, vizphỏng vấn, spec, kiểm tra, trực quanproduct-spec-critique— 4-lens tear-down, 9 voice levels4 lăng kính mổ xẻ, 9 mức giọngrelease— pack into deterministic tar.gzđóng thành tar.gz deterministictelemetry— read-only usage & health, 8 lensesmức dùng & sức khỏe chỉ-đọc, 8 lăng kính
All four share one Python venv at .claude/skills/.venv/. Telemetry's lenses and sink hooks are stdlib-only and also run under a plain system python3.Cả bốn dùng chung một venv Python tại .claude/skills/.venv/. Lăng kính và sink hook của telemetry chỉ dùng stdlib, cũng chạy được bằng python3 hệ thống.
product-critic— JTBD · Value Prop · Kano · RICElăng kính sản phẩmtech-critic— INVEST · testability · NFR gapslăng kính kỹ thuậtmarket-critic— Lean Canvas · Porter · Blue Oceanlăng kính thị trườngcraft-critic— writing quality, CSI-4Cs, term driftlăng kính biên tậpcritique-consolidator— merges 4 lenses, deduplicates, top-3gộp 4 lăng kính, loại trùng, top-3critique-humanizer— strips AI-tells, preserves bitebỏ dấu AI, giữ chất gắtmemory-harvester— retroactive harvest for--reflectthu hoạch hồi tố cho--reflect
Sub-agents are spawned by the skills — they are never user-invocable directly. They read, never write.Sub-agent được skill gọi ra — người dùng không gọi trực tiếp. Chúng chỉ đọc, không ghi.
-
5 telemetry sinks (auto-registered at install)5 sink telemetry (tự đăng ký khi cài)
track_skill_invocation.py— skill invocation eventssự kiện gọi skilltrack_script_execution.py— script duration + exit codethời gian + exit code scripttrack_subagent_outcome.py— sub-agent success / failurekết cục sub-agentmark_bash_start.py— bash command timingđo thời gian bashemit_session_summary.py— session summary on closetóm tắt phiên khi đóng
memory_gap_hook.py— memory-gap enforcement (opt-in)cưỡng chế memory-gap (opt-in)product_spec_critique_nudge.py— post-validate re-critique reminder (opt-in)nhắc re-critique sau validate (opt-in)
Sinks are fail-open and make no network calls. They write only to gitignored .claude/telemetry/*.jsonl sinks. Opt out with register_telemetry_hooks.py --remove.Sink fail-open và không gọi mạng. Chỉ ghi vào sink .claude/telemetry/*.jsonl đã gitignore. Tắt bằng register_telemetry_hooks.py --remove.
CLAUDE.md— always-on safety floor + skill routing tablelằn ranh an toàn luôn bật + bảng định tuyến skillprimary-workflow.md— understand → implement → verify → explainhiểu → thực thi → kiểm tra → giải thíchorchestration-protocol.md— delegation context + parallel work rulesngữ cảnh ủy quyền + rule làm song songdevelopment-rules.md— YAGNI / KISS / DRY, quality gates, toolingYAGNI / KISS / DRY, quality gate, công cụdocumentation-management.md— when to update docs, plan location conventionskhi nào cập nhật tài liệu, quy ước vị trí plan
The two GATEs in CLAUDE.md (GATE-NO-SILENT-REVERSAL and GATE-NEVER-ASSUME) apply on every turn regardless of which skill is active. They cannot be deferred to a loaded reference.Hai GATE trong CLAUDE.md (GATE-NO-SILENT-REVERSAL và GATE-NEVER-ASSUME) áp dụng mọi lượt bất kể skill nào đang hoạt động. Không thể hoãn sang tham chiếu đã nạp.
run_evals.py— structural checks; runs on CI; deterministickiểm tra cấu trúc; chạy trên CI; tất địnhllm_eval.py— advisory LLM-backed checks; never in CI gatekiểm tra advisory dựa LLM; không bao giờ ở CI gate- Each skill ships its own
eval/golden/fixtures — runnable on your machine via the shared eval scripts.Mỗi skill kèm fixtureeval/golden/riêng — chạy được trên máy bạn qua script eval dùng chung.
The script-vs-LLM split is an operating principle: scripts handle graph and structure; the LLM layer judges prose and alignment. Scripts always run first. See the five principles.Nguyên tắc phân tách script-vs-LLM: script lo đồ thị và cấu trúc; lớp LLM nhận định văn và căn chỉnh. Script luôn chạy trước. Xem năm nguyên tắc.
pack.manifest.yaml— source-of-truth manifest; curated file list + per-file SHA-256manifest nguồn-chân-lý; danh sách file chọn lọc + SHA-256 từng fileinstall.sh— POSIX installer (macOS / Linux / WSL); idempotentinstaller POSIX (macOS / Linux / WSL); idempotentinstall.ps1— Windows PowerShell installer; same behaviorinstaller Windows PowerShell; cùng hành vi- Output:
dist/product-spec-{version}.tar.gz+.sha256sidecar. Byte-identical across runs given the same inputs.Đầu ra:dist/product-spec-{version}.tar.gz+ sidecar.sha256. Byte-identical qua mỗi lần chạy cùng input.
The release skill manages the pack lifecycle. See release for flags, dry-run preview, and CI reproducibility. See telemetry for usage & health of the whole rig.Skill release quản lý vòng đời pack. Xem release cho flag, dry-run và CI reproducibility. Xem telemetry cho mức dùng & sức khỏe của cả bộ.
Runs offline — by designChạy offline — theo thiết kế
After install, all four skills run entirely on your machine. The telemetry sink hooks and lenses are stdlib-only — they read and write only local gitignored .claude/telemetry/*.jsonl sinks and never transmit anything. The release safety filter always drops .env files, secrets, keys, .git/, runtime caches, and session state from any bundle — no flag can override this.Sau khi cài, cả bốn skill chạy hoàn toàn trên máy bạn. Sink hook và lăng kính của telemetry chỉ dùng stdlib — chỉ đọc/ghi sink .claude/telemetry/*.jsonl cục bộ đã gitignore, không truyền gì. Safety filter của release luôn loại file .env, secret, key, .git/, cache runtime, và session state khỏi mọi bundle — không flag nào kéo lại được.
One-time install: CDN fetch + SHA-256 verifyCài một lần: tải CDN + verify SHA-256
The product-spec installer downloads the Mermaid, marked, and DOMPurify runtimes from the public CDN (cdn.jsdelivr.net), then verifies each against a pinned SHA-256 hash before storing them locally. After that step, the viz engine runs offline.Installer của product-spec tải Mermaid, marked, và DOMPurify từ CDN công khai (cdn.jsdelivr.net), sau đó verify từng cái bằng SHA-256 đã ghim trước khi lưu cục bộ. Sau bước đó, engine trực quan hóa chạy offline.
Degraded-install caveat: Mermaid graph viewsLưu ý khi cài thiếu: khung nhìn đồ thị Mermaid
If mermaid.min.js failed to vendor at install time, product-spec's Mermaid graph views fall back to a CDN <script> at browser-render time. Re-run the installer to fix it. ASCII and body views never reach a CDN.Nếu mermaid.min.js chưa được vendor khi cài, khung nhìn đồ thị Mermaid của product-spec sẽ tải từ CDN lúc trình duyệt render. Chạy lại installer để sửa. Khung nhìn ASCII và body không bao giờ gọi CDN.
Idempotent re-install is always safeCài lại idempotent luôn an toàn
Both install.sh and install.ps1 are idempotent — re-running them skips already-present components and re-vendors any missing JS assets. No state is lost.Cả install.sh và install.ps1 đều idempotent — chạy lại sẽ bỏ qua thành phần đã có và vendor lại JS asset còn thiếu. Không mất trạng thái nào.
.claude/telemetry/*.jsonl files — it is never bundled or transmitted. The release safety filter permanently excludes secrets, .env, .git/, and session state from every bundle. These protections have no opt-out flags.
Đảm bảo quyền riêng tư: cả bốn skill không gọi mạng khi chạy. Dữ liệu telemetry ở cục bộ trong file .claude/telemetry/*.jsonl đã gitignore — không bao giờ bundle hay truyền đi. Safety filter của release vĩnh viễn loại secret, .env, .git/ và session state khỏi mọi bundle. Các bảo vệ này không có flag tắt.