Quick startBắt đầu
[advisory] + a trace when an acceptance artifact is missing and lets you commit / push / ship straight through; the hard guarantees are the agent cage and the two safety floors (destructive-to-protected + secret) — those still hard-block, every time. No reviewer roster, no posture to choose. More on the overview.Personal-first — gate local khuyên, không chặn bạn. Mạch này chạy xương sống SDLC (plan · cook · test · ship). Ở local, gate phát [advisory] + trace khi thiếu artifact nghiệm thu rồi để bạn commit / push / ship thẳng; bảo đảm cứng nằm ở cũi agent và hai safety floor (destructive-to-protected + secret) — hai thứ này vẫn chặn cứng, mọi lúc. Không roster người duyệt, không phải chọn thế. Thêm ở tổng quan.This page takes you from an empty repo to your first change shipped through the gate. Four steps: one in the shell (install), three in Claude Code (plan, build, ship). The whole walkthrough uses one worked example so the plan slug stays the same throughout. No package manager, no build step — requirements: Linux, Python ≥ 3.12, git, and Claude Code.Trang này đưa bạn từ một repo trống đến thay đổi đầu tiên được ship qua gate. Bốn bước: một bước ở shell (cài), ba bước trong Claude Code (plan, build, ship). Cả mạch dùng chung một ví dụ nên slug của plan giữ nguyên xuyên suốt. Không package manager, không bước build — yêu cầu: Linux, Python ≥ 3.12, git, và Claude Code.
Install into your repoCài vào repo của bạn
One online command, run from inside your repo. It self-downloads the latest release, verifies the checksum, extracts, checks dependencies, installs, and verifies the install — no clone, no separate preflight step, nothing to chain.Một lệnh online duy nhất, chạy từ bên trong repo của bạn. Nó tự tải bản release mới nhất, kiểm checksum, giải nén, kiểm deps, cài, rồi verify bản cài — không cần clone, không có bước preflight riêng, không phải nối lệnh nào cả.
curl -fsSL https://hieubui2409.github.io/sdlc-harness-release/install.sh | shWindows PowerShell: irm https://hieubui2409.github.io/sdlc-harness-release/install.ps1 | iex. The post-install test suite is opt-in — pass --run-tests (PowerShell: -RunTests) if you want the full suite too; the strict install check already confirms the install without it. real outputWindows PowerShell: irm https://hieubui2409.github.io/sdlc-harness-release/install.ps1 | iex. Bộ test sau cài là tùy chọn — thêm --run-tests (PowerShell: -RunTests) nếu muốn chạy cả bộ test; kiểm strict lúc cài đã xác nhận cài đúng mà không cần nó. đầu ra thật
WARN harness/bin/hs-cli: not reachable on PATH — skill bodies tell the user to type `hs-cli`. Fix: `ln -s <repo>/harness/bin/hs-cli ~/.local/bin/hs-cli` (or `install.py --cli` for every launcher; Windows: add <repo>/harness/bin to PATH) … 5 more of the same shape (hs-run, hs-code, hs-rops, hs-secrets, hs-usage: a launcher not yet linked onto PATH) WARN harness/data/harness-hooks.yaml: bash_write_guard: enabled=false in the SSOT but its entrypoint is still wired in .claude/settings.json — not a bug (the process spawns and self-no-ops each matching event under the wire-then-toggle pattern), but it costs a spawn; unwire it there too if you want zero per-event cost … 9 more of the same shape (a hook disabled in the SSOT whose entrypoint stays wired) WARN harness/data/harness-hooks.yaml: hash mismatch (deployer-localized config — expected to differ from the shipped baseline) verify_install OK: manifest + hook registration consistent
After installing, enable the plugin with /reload-plugins in Claude Code (or restart it). Full options: docs/harness/deployment-guide.md; every config knob: docs/harness/config-reference.md.Sau khi cài, bật plugin bằng /reload-plugins trong Claude Code (hoặc khởi động lại). Tùy chọn đầy đủ: docs/harness/deployment-guide.md; mọi núm cấu hình: docs/harness/config-reference.md.
Plan your first taskLập plan cho task đầu tiên
In Claude Code, run /hs:plan and describe what you want — starting from an empty repo instead? Run /hs:bootstrap first; it clarifies requirements, inits git, and hands off into plan for you. The harness researches, scans constraints, red-teams, and writes a plan under plans/<slug>/ (plan.md + phase files). You approve it — cook will not run until a human does. Then /clear so cook starts from a clean context. real outputTrong Claude Code, chạy /hs:plan và mô tả điều bạn muốn — bắt đầu từ repo trống? Chạy /hs:bootstrap trước; nó làm rõ yêu cầu, init git, rồi bàn giao sang plan hộ bạn. Harness nghiên cứu, quét ràng buộc, red-team, rồi ghi plan dưới plans/<slug>/ (plan.md + file phase). Bạn duyệt — cook không chạy cho tới khi một con người duyệt. Rồi /clear để cook bắt đầu từ context sạch. đầu ra thật
/hs:plan add a token-bucket rate limit to the public APIplans/260818-0400-rate-limit-middleware/ plan.md phases/phase-1-4.md artifacts/verification.json artifacts/verification-p1.json artifacts/phase-latest-P1.json artifacts/plan-approval.yaml reports/code-review-260818-p1.md
--grid to plan (/hs:plan … --grid) for a coverage grid built from the plan's own features and risks — it makes you resolve thin cells before the plan is ready, and stamps a coverage-grid artifact cook and test read downstream. How it works: Methodology.Thay đổi rủi ro cao? Thêm --grid vào plan (/hs:plan … --grid) để có một coverage grid dựng từ chính features và risks của plan — nó bắt bạn giải các ô mỏng trước khi plan sẵn sàng, và đóng dấu một artifact coverage-grid mà cook và test đọc về sau. Cơ chế: Phương pháp.Build it — and write the acceptance artifactBuild — và ghi artifact nghiệm thu
Run /hs:cook with the absolute path to the approved plan. It executes phase by phase in TDD red→green, then on the final phase writes verification.json — the exact artifact the gate will look for. /hs:test can re-run the suite and refresh the verdict any time. real outputChạy /hs:cook với đường dẫn tuyệt đối tới plan đã duyệt. Nó thực thi từng phase theo TDD đỏ→xanh, rồi ở phase cuối ghi verification.json — đúng artifact mà gate sẽ tìm. /hs:test có thể chạy lại bộ test và làm mới verdict bất cứ lúc nào. đầu ra thật
/hs:cook /abs/path/plans/260818-0400-rate-limit-middleware/plan.md{
"stage": "push",
"plan": "260818-0400-rate-limit-middleware",
"phase": "p1",
"actor": "user:dev@team.example",
"ts": "2026-08-18T04:12:41.118203+00:00",
"checks": [
{
"name": "preflight_deps",
"status": "PASS",
"detail": "22 declared deps resolved"
},
{
"name": "pytest harness/tests",
"status": "PASS",
"detail": "22405 passed, 418 skipped"
},
{
"name": "schema load yaml+json",
"status": "PASS",
"detail": "yaml ok, schemas ok"
},
{
"name": "verify_install --strict",
"status": "PASS",
"detail": "manifest 3490 files"
},
{
"name": "e2e vertical slice",
"status": "PASS",
"detail": "advisory-then-pass, transport=simulated-stdin"
}
],
"verdict": "PASS"
}
Ship through the gateShip qua gate
Now push. If the artifact is missing, the pre-push gate ADVISES (exit 0), naming the missing artifact and the exact path to create — never a dead end. Once Step 3 has written verification.json, the same push passes. That advise-then-pass loop is the whole point — the hard guarantees are the agent cage and the two safety floors (destructive-to-protected + secret), not this gate. real outputGiờ push. Nếu thiếu artifact, pre-push gate NHẮC (exit 0), nêu tên artifact thiếu và đúng đường cần tạo — không bao giờ là ngõ cụt. Khi Bước 3 đã ghi verification.json, chính lệnh push đó vượt qua. Vòng nhắc-rồi-vượt chính là cốt lõi — bảo đảm cứng nằm ở cũi agent và hai safety floor (destructive-to-protected + secret), không phải ở gate này. đầu ra thật
[advisory] gate_stage: hard stage 'push' needs an active plan but none resolved. Three exits: (1) create a plan under plans/ with `status: in_progress` frontmatter; (2) set HARNESS_ACTIVE_PLAN to the plan dir; (3) set `require_plan: false` for this stage in harness/data/stage-policy.yaml (tracked in git) — presence enforcement lives in remote CI (receipts-gate) [exit 0 — local gate is advisory; the remote CI receipts-gate is the hard block]
exit 0), while the agent cage and the two safety floors hold the hard line. Watch the same change flow end to end in Journey, or learn each skill in depth: hs:plan · hs:cook · hs:test.Đó là vòng lặp. plan → cook → test → ship, với một gate đọc artifact nghiệm thu từ filesystem — advisory tại máy (exit 0), trong khi cũi agent và hai safety floor giữ chốt chặn cứng. Xem chính thay đổi đó chạy từ đầu đến cuối trong Journey, hoặc học sâu từng skill: hs:plan · hs:cook · hs:test.Autonomy modes — pick your leashChế độ tự chủ — chọn mức kiểm soát
Set HARNESS_AUTONOMY before running any hs:* skill. All three modes still require the artifact gate at push/pr/ship — no mode auto-ships.Đặt HARNESS_AUTONOMY trước khi chạy skill hs:*. Cả ba mức đều qua artifact gate tại push/pr/ship — không mức nào tự ship.
| Env varBiến môi trường | BehaviorHành vi |
|---|---|
| HARNESS_AUTONOMY=default | Runs the phase chain; pauses at plan-approval and ship only.Chạy chuỗi phase; dừng tại duyệt plan và ship. |
| HARNESS_AUTONOMY=ask_all | Pauses after every phase — maximum human checkpoints.Dừng sau mỗi phase — nhiều chốt người nhất. |
| HARNESS_AUTONOMY=god | Never pauses mid-chain — trace still records everything.Không dừng giữa chuỗi — trace vẫn ghi đủ mọi bước. |
FAQHỏi đáp
Do I need a package manager or a build step?Có cần package manager hay bước build không?
The gate blocked my push — how do I unblock it?Gate chặn push — làm sao mở?
hs:cook writes verification.json (Step 3). The block message names the exact path to create — it's never a dead end.Chạy vòng lặp để artifact nghiệm thu tồn tại: plan đã duyệt (Bước 2), rồi hs:cook ghi verification.json (Bước 3). Thông báo chặn nêu đúng đường cần tạo — không bao giờ là ngõ cụt.Will installing overwrite my existing .claude hooks?Cài có ghi đè hook .claude của tôi không?
.claude/settings.json — your own hooks survive. It's idempotent; advanced flags like --dry-run and --uninstall are available if you run the installer directly (see the Install page).Không. Cài gộp hook theo kiểu cộng thêm vào .claude/settings.json — hook của bạn vẫn còn. Idempotent; các cờ nâng cao như --dry-run và --uninstall có khi bạn chạy thẳng trình cài (xem trang Cài đặt).Why /clear between plan and cook?Vì sao /clear giữa plan và cook?
Does any of this hit the network?Có thứ gì gọi mạng không?
Which autonomy mode should I start with?Nên bắt đầu với mức tự chủ nào?
default — it pauses at exactly two human checkpoints (plan approval + ship). No mode auto-ships, so it's a safe place to learn the loop.default — dừng ở đúng hai chốt người (duyệt plan + ship). Không mức nào tự ship, nên đây là chỗ an toàn để học vòng lặp.When should I add --grid to a plan?Khi nào thêm --grid vào plan?
hs:plan --grid builds a coverage grid from the plan's own features/risks (never hand-typed), makes you resolve thin cells, and emits a coverage-grid artifact that later stages read. It's an optional planning mode — the deep dive is on Methodology.Cho thay đổi rủi ro cao khi "đã nghĩ hết chưa?" quan trọng. hs:plan --grid dựng coverage grid từ chính features/risks của plan (không gõ tay), bắt bạn giải các ô mỏng, và emit một artifact coverage-grid mà các bước sau đọc. Đây là chế độ plan tùy chọn — đi sâu ở Phương pháp.What actually runs behind /hs:plan and /hs:cook?/hs:plan và /hs:cook chạy cái gì bên dưới?
hs-run <domain> <verb> — the deterministic step-sequence engine, 13 domains / 24 verbs. Most domains expose one next verb; cook has 8 (close, next, open, preflight, prompt, record, status, verify) and plan has 5 (graph, next, prompt, record, scaffold). Every verb returns a JSON envelope (state, next_action, artifacts, refs) on one of six exit codes: 0 done, 1 findings, 2 broken, 3 deliberate refusal, 10 needs a model turn, 11 one more deterministic step. You never call it by hand in this walkthrough — the skill does.Mỗi skill chạy hs-run <domain> <verb> — engine bước chạy tất định, 13 domain / 24 verb. Hầu hết domain chỉ có một cửa next; cook có 8 (close, next, open, preflight, prompt, record, status, verify) và plan có 5 (graph, next, prompt, record, scaffold). Mỗi verb trả envelope JSON (state, next_action, artifacts, refs) trên một trong sáu mã thoát: 0 xong, 1 phát hiện, 2 hỏng, 3 từ chối có chủ đích, 10 cần lượt model, 11 còn một bước tất định. Ở mạch này bạn không gọi tay — skill tự gọi.