A file-based SDLC harness for Claude Code · W0–W3Một harness SDLC file-based cho Claude Code · W0–W3

Make every change
earn its way to ship. Bắt mọi thay đổi
tự chứng minh trước khi ship.

PlanLập kế hoạch BuildThực thi VerifyKiểm thử GateChặn ObserveQuan sát

Not prose reminders — a coordinated .claude-style rig that enforces the workflow at runtime: 109 hs:* skills, 50 hooks in three tiers, 140 scripts, and a compliance gate that advises push / pr / ship locally and is enforced for real at remote CI — with an agent cage that hard-blocks forgery on the spot. Every gate, approval, and decision is traced with an actor. Không phải lời nhắc — mà cả một bộ kiểu .claude phối hợp, ép quy trình ngay lúc chạy: 109 skill hs:*, 50 hook ba hạng, 140 script, và một gate compliance khuyên push / pr / ship ở local rồi được ép thật ở remote CI — kèm cũi agent chặn cứng giả-mạo tại chỗ. Mọi gate, duyệt và quyết định đều được trace kèm actor.

Install the harness →Cài harness → Quick startBắt đầu nhanh Browse the guidesXem bộ hướng dẫn
hs:plan
workflow
hs:cook
TDD red→green
hs:test
100% pass
The rig
gate · trace · telemetry
How enforcement works ↓Cơ chế enforcement ↓
Before the pipeline · how enforcement worksTrước quy trình · cơ chế enforcement

Personal-first — local advises, remote enforcesPersonal-first — local khuyên, remote ép

One person, one machine, one clone. The local gate never blocks you — it advises and traces; quality is enforced at remote CI. No reviewer roster, no approval quorum, no team/solo posture to choose. What the harness never loosens: the agent stays caged. v4.0.0.Một người, một máy, một clone. Gate local không bao giờ chặn bạn — nó khuyên và ghi trace; chất lượng được ép ở remote CI. Không roster người duyệt, không quorum, không phải chọn thế team/solo. Cái harness không bao giờ nới: agent luôn bị nhốt. v4.0.0.

Local — advisoryLocal — advisory

You commit / push / ship straight throughBạn commit / push / ship thẳng

  • Gate: a hard stage with a missing receipt emits [advisory] + a gate_advisory trace and proceeds — no human blockGate: hard stage thiếu receipt phát [advisory] + trace gate_advisory rồi đi tiếp — không chặn người
  • Pre-push: WARNs on a missing receipt, but still BLOCKS the two floors — destructive-to-protected + secretPre-push: WARN khi thiếu receipt, nhưng vẫn CHẶN hai floor — destructive-to-protected + secret
  • Agent cage: RBAC block + safety floors — never loosenedNhốt agent: RBAC block + safety floor — không bao giờ nới

The one hard local block is the artifact-forgery arm (the agent cage).Chốt cứng local duy nhất là nhánh chống giả-mạo-artifact (cũi agent).

Remote — enforcedRemote — được ép

Quality is the CI's job, not a local wallChất lượng là việc của CI, không phải tường local

  • Receipts-gate: .github/workflows/receipts-gate.yml enforces plan receipts on PR and push→mainReceipts-gate: .github/workflows/receipts-gate.yml ép plan receipts trên PR và push→main
  • Fail-closed: a resolve error blocks the merge — presence is enforced where it can't be self-bypassedFail-closed: lỗi resolve chặn merge — sự-hiện-diện được ép ở nơi không tự-bỏ-qua được
  • Plan-approval: self-approval — verdict + plan_hash anti-drift + a mandatory plan-graph sidecarPlan-approval: tự-duyệt — verdict + plan_hash chống-drift + sidecar plan-graph bắt buộc

No roster, no quorum, no role check.Không roster, không quorum, không role check.

📘
Reading the gate pages below? The gate at push / pr / ship advises locally and traces — it does not block you. The same checks are enforced for real at remote CI (the receipts-gate). What stays hard locally: the agent RBAC cage, the safety floors, and the artifact trace. Full detail on Configure.Đọc các trang gate bên dưới? Gate tại push / pr / ship khuyên ở local và ghi trace — nó không chặn bạn. Chính các kiểm tra đó được ép thật ở remote CI (receipts-gate). Cái vẫn cứng ở local: cũi RBAC agent, các safety floor, và trace artifact. Chi tiết đầy đủ ở Cấu hình.
The enforced loopVòng được ép

One spine — plan, cook, test, ship — and a gate that says noMột xương sống — plan, cook, test, ship — và một gate biết nói không

An idea enters at plan; a human-approved, test-verified change leaves at ship — or it doesn't leave at all. The compliance gate at ship reads acceptance artifacts off the filesystem and fails closed. Usage of the whole rig flows back as observability.Ý tưởng vào ở plan; một thay đổi đã-người-duyệt, đã-test ra ở ship — hoặc không ra được. Gate compliance tại ship đọc artifact nghiệm thu từ filesystem và fail-closed. Mức dùng của cả bộ chảy ngược về thành quan trắc.

Optional · ungatedTùy chọn · không gate
hs:discoverhs:researchhs:brainstorm

Figure out what to build. No stage requires their output — run them when the problem is fuzzy, skip them when it's clear. They feed hs:plan ↓Tìm xem nên làm gì. Không stage nào đòi đầu ra của chúng — chạy khi vấn đề còn mơ hồ, bỏ khi đã rõ. Chúng nạp vào hs:plan ↓

01

hs:plan

Research → constraint-scan → red-team → validate. The plan is a contract; cook only runs once a human approves it.Research → constraint-scan → red-team → validate. Plan là hợp đồng; cook chỉ chạy khi người duyệt.

DefineĐịnh nghĩa
02

hs:cook

Per-phase TDD red→green. Writes a machine verification.json; traces every step with an actor.TDD đỏ→xanh từng phase. Ghi verification.json máy-ghi; trace mọi bước kèm actor.

BuildThực thi
03

hs:test

unit / integration profiles, 100% pass is the gate, a tight QA report, verdict into the artifact.profile unit / integration, 100% pass là gate, QA report gọn, verdict vào artifact.

VerifyKiểm thử
04

hs:ship

The gate here reads verification + review-decision + plan-approval + critique-consensus off the filesystem and fails closed. No artifact, no ship.Gate tại đây đọc verification + review-decision + plan-approval + critique-consensus từ filesystem và fail-closed. Thiếu artifact, không ship.

ReleasePhát hành
The return edge: a blocked stage (exit 2 + an actionable reason) sends you back to cook/test. critique-consensus (from hs:critique) is required at pr/ship too — a change that was never critiqued can't be released. The workflow lens then compares the chain you declared against the chain you actually ran. Cạnh quay về: một stage bị chặn (exit 2 + lý do xử lý được) đẩy bạn về cook/test. critique-consensus (từ hs:critique) cũng bị đòi ở pr/ship — thay đổi chưa từng được critique thì không ra được. Workflow lens rồi so chuỗi bạn khai báo với chuỗi bạn thực sự chạy.
107
hs:* skills in the suiteskill hs:* trong bộ
20
hooks · 3 tiershook · 3 hạng
2508
unit + invariant tests passtest unit + invariant pass
0
network calls in the gate pathlần gọi mạng trong đường gate
Under the hoodBên trong

What lives in harness/ — the whole rigCái gì nằm trong harness/ — cả bộ

The product is the harness/ tree: skills, hooks, scripts, rules, data, schemas, install, tests. Delete the directory and the harness is gone — a CI invariant forbids the string .claude/skills/ inside harness/.Sản phẩm là cây harness/: skills, hooks, scripts, rules, data, schemas, install, tests. Xóa thư mục là gỡ sạch — một invariant CI cấm chuỗi .claude/skills/ trong harness/.

🧩 109 skills109 skillplugins/hs
  • SDLC spine: plan · cook · test · shipXương sống: plan · cook · test · ship
  • orchestrators, review, debug, research, ideation, docsđiều phối, review, debug, nghiên cứu, ý tưởng, docs
  • packaged as plugin hs → /hs:planđóng gói plugin hs → /hs:plan
🪝 50 hooks · 3 tiers50 hook · 3 hạng/hooks
  • telemetry sinks (ON, fail-open)sink telemetry (ON, fail-open)
  • memory-gap nudge (OFF)memory-gap nudge (OFF)
  • gate_stage · write_guard (compliance)gate_stage · write_guard (compliance)
🛠️ 140 scripts140 script/scripts
  • stage_detector · artifact_check · fs_guardstage_detector · artifact_check · fs_guard
  • claims · task_store · plan_approval
  • analyze_telemetry · spec_graph · decision_register
📐 15 rules15 rule/rules
  • harness-contract.md (≤60 lines, always-load)(≤60 dòng, luôn-load)
  • tdd-discipline · verification-mechanism
  • workflow-handoffs · terminal-voice
🧪 13 schemas13 schema/schemas
  • artifact-verification · review-decision
  • plan-approval · critique-consensus
  • bakeoff-verdict · harness-release
📦 Install + manifestCài + manifest/install
  • install.py --target (one command)(một lệnh)
  • manifest.json (sha256 tracked files)(sha256 file tracked)
  • verify_install.py --strict
🤝
Honest by design: the contract names its own limits in plain words. The gate is a presence gate (it stops forgotten steps, not a determined cheater); actor is attribution, not authentication (it raises the cost of lying, it doesn't prove identity); the config gate is tamper-visible (editable in an emergency, but the diff shows). No claim of security the code doesn't have.Trung thực theo thiết kế: contract tự nêu giới hạn bằng lời thẳng. Gate là presence gate (chặn bước bị quên, không chặn kẻ cố gian); actor là attribution, không phải authentication (tăng giá nói dối, không chứng minh danh tính); config gate là tamper-visible (sửa được khi khẩn, nhưng lộ diff). Không claim bảo mật mà code chưa có.
Where to nextĐi tiếp đâu

Start with the guidesBắt đầu từ bộ hướng dẫn

Four tracks, in the order you'd actually meet them: get running, watch one change flow through, learn each core skill, then open the machinery. Jump in anywhere.Bốn mạch, theo đúng thứ tự bạn sẽ gặp: chạy được trước, xem một thay đổi đi qua quy trình, học từng skill lõi, rồi mở bộ máy bên trong. Vào ở đâu cũng được.

Getting startedBắt đầu

Quick start & Journey — install, verify, and follow one change from idea to ship.Quick start & Journey — cài đặt, kiểm tra, và theo một thay đổi từ ý tưởng đến ship.

Core pipelineQuy trình lõi

hs:plan · hs:cook · hs:test → ship — the enforced loop the gate guards, one skill at a time.hs:plan · hs:cook · hs:test → ship — vòng được ép mà gate canh, từng skill một.

AdvancedNâng cao

hs:bakeoff & the full hs:* catalog — pick winners by numbers, find the right skill.hs:bakeoff & toàn bộ catalog hs:* — chọn kẻ thắng bằng số, tìm đúng skill.

InternalsBên trong

The rig & Vision — hooks, scripts, the gate, and where the harness is headed.Bộ máy & Tầm nhìn — hook, script, gate, và harness đang đi về đâu.
Open all guidesMở toàn bộ hướng dẫn
NextSau →All guidesMục lục