hs:plan
Turns a request into a plan under plans/<timestamp>-<slug>/ — researched, constraint-scanned, red-teamed and validated before a line of code. Standards are an input, never invented: it reads harness/standards/ first and stops if they're missing. The plan is a contract for hs:cook; it writes nothing outside plans/.Biến một yêu cầu thành plan dưới plans/<timestamp>-<slug>/ — đã research, đã constraint-scan, đã red-team và validate trước dòng code đầu tiên. Standards là input, không tự chế: đọc harness/standards/ trước, thiếu thì dừng. Plan là hợp đồng cho hs:cook; không ghi gì ngoài plans/.
When to useKhi nào dùng
✓ Reach for it when✓ Dùng khi
- a real feature/refactor needs phases a teammate can runfeature/refactor thật cần phase dev khác cầm chạy được
- an open decision must be pinned against existing config/standardsquyết-định-mở phải chốt theo config/standards đã có
- you want a red-team pass before spending build budgetbạn muốn một lượt red-team trước khi rót ngân sách build
✗ Not for✗ Không dùng để
- writing code — that's
hs:cook's jobviết code — đó là việc củahs:cook - approving the plan for you — sign-off is the human's calltự duyệt plan — duyệt là việc của người
- files outside
plans/file ngoàiplans/
How to run itCách chạy
Invoke it in Claude Code with your request — e.g. /hs:plan add rate-limiting to the upload endpoint. Hard mode (default) runs the full chain; add --fast for a 1–2 file, low-risk change. --tdd is orthogonal: it spells out test-first → implement-after in every phase.Gọi trong Claude Code kèm yêu cầu — ví dụ /hs:plan thêm rate-limit cho endpoint upload. Hard mode (mặc định) chạy đủ chuỗi; thêm --fast cho việc 1–2 file, rủi ro thấp. --tdd trực giao: ghi rõ test-trước → implement-sau ở mỗi phase.
Standards firstStandards trước
It reads harness/standards/ before anything. Missing → it STOPS and asks you to load them; it won't plan on an empty base.Đọc harness/standards/ trước tiên. Thiếu → DỪNG và yêu cầu bạn nạp; không plan trên nền rỗng.
Scope challengeThách thức phạm vi
Three questions — what to reuse, the minimal change set, is it >8 files / >2 new classes / >3 phases — to expand, hold, or cut before any research.Ba câu hỏi — tái dùng gì, tập thay đổi tối thiểu, có >8 file / >2 class mới / >3 phase — để mở rộng, giữ, hoặc cắt trước khi research.
Research → constraint-scanResearch → constraint-scan
Up to two researcher agents in parallel, then grep ownership.yaml, stage-policy.yaml, and schemas/ so decisions respect existing policy.Tối đa hai agent researcher song song, rồi grep ownership.yaml, stage-policy.yaml, schemas/ để quyết định tôn trọng policy đã có.
Write the planViết plan
plan.md + phase files good enough for another dev to run. Any claim without a file:line anchor gets an [UNVERIFIED] tag.plan.md + phase file đủ để dev khác chạy. Mọi khẳng định thiếu mỏ neo file:line bị gắn tag [UNVERIFIED].
Red-team → validate → sweepRed-team → validate → quét
A hostile reviewer hunts failure modes; validate resolves the [UNVERIFIED] tags; a consistency sweep requires 0 contradictions before it recommends cook.Reviewer thù địch săn lỗi; validate giải các tag [UNVERIFIED]; quét nhất quán yêu cầu 0 mâu thuẫn trước khi đề xuất cook.
You approve, then cookBạn duyệt, rồi cook
It returns the plan's absolute path and asks for your approval. Then /clear and /hs:cook <absolute-path>.Nó trả về đường dẫn tuyệt đối của plan và xin duyệt từ bạn. Rồi /clear và /hs:cook <đường-dẫn-tuyệt-đối>.
Worked example: the contract, and the gateVí dụ thật: hợp đồng, và gate
The contract chain: plan → approve → cook → test → shipChuỗi hợp đồng: plan → duyệt → cook → test → ship
One enforced path. Each step leaves an artifact the next step (or the gate) reads. Drop the plan and the chain can't reach ship. real pipeline Một đường được ép. Mỗi bước để lại artifact mà bước sau (hoặc gate) đọc. Bỏ plan là chuỗi không tới được ship. pipeline thật
A plan directory is the contract on disk — plan.md, phase files, an artifacts/ folder the gate reads, and review reports:Một thư mục plan là hợp đồng trên đĩa — plan.md, các phase file, thư mục artifacts/ mà gate đọc, và báo cáo review:
plans/260612-1237-harness-w2-horizontal-1/ artifacts/verification.json phase-01-claims-fsm-team-config.md phase-02-task-store-adapter-github.md phase-03-plan-approval-role-check.md phase-04-write-guard-env-scrub-en-3.md phase-05-memory-gap-staged-port.md phase-06-telemetry-hooks-workflow-lens.md plan.md reports/code-review-260613-phase6-telemetry.md reports/from-code-reviewer-to-planner-red-team-maintainer-operator-plan-review-report.md reports/from-code-reviewer-to-planner-red-team-security-failure-plan-review-report.md
No plan, no ship — the gate, realKhông plan, không ship — gate, thật
Try to git push with no active plan. The compliance hook fails closed with exit 2 and names three exits — never a dead end. real output
Thử git push khi không có plan active. Hook compliance fail-closed exit 2 và nêu ba lối ra — không bao giờ là ngõ cụt. đầu ra thật
[gate_stage] BLOCKED: 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) [exit 2 — compliance hook fail-closed]
Two modes, one orthogonal flagHai mode, một cờ trực giao
| ModeMode | WhenKhi nào | GatesGates |
|---|---|---|
| fast | small job, 1–2 files, low riskviệc nhỏ, 1–2 file, rủi ro thấp | skips research + red-teambỏ research + red-team |
| hard (default) | a real feature or refactorfeature/refactor thật | constraint-scan → red-team → validateconstraint-scan → red-team → validate |
| --tdd | orthogonal to modetrực giao với mode | each phase spells out test-first → implement-aftermỗi phase ghi rõ test-trước → implement-sau |
The hard-mode flowLuồng hard-mode
An Evidence Filter runs both ways: every open-decision spot must cite file:line or carry an explicit [UNVERIFIED] tag. Validate resolves those — interactive asks via questions, headless emits a "question + suggested default" table instead of blocking.Evidence Filter hai chiều: mọi vị trí quyết-định-mở phải dẫn file:line hoặc gắn tag [UNVERIFIED]. Validate giải chúng — interactive hỏi qua câu hỏi, headless phát bảng "câu hỏi + default đề xuất" thay vì chặn.
Decisions, and the gate behind themQuyết định, và gate phía sau
Decisions outlive the chatQuyết định sống lâu hơn cuộc chat
An architecture decision pinned in validate is written via decision_register.py — append-only, monotonic IDs, injection-escaped. The register kills re-litigation: meet an old tension, read the register first, don't re-argue.Một quyết định kiến trúc chốt ở validate được ghi qua decision_register.py — append-only, ID monotonic, escape injection. Register giết re-litigation: gặp lại tension cũ, đọc register trước, không cãi lại.
The enforcement gateGate cưỡng chế
plan-approval.json is enforced on the remote CI: a plan hash must match the normalized plan directory to prevent drift. You approve locally (advisory), but the remote gate checks that the plan hasn't been modified after approval before allowing PR merge and push-to-main.plan-approval.json được ép ở CI remote: hash plan phải khớp thư mục plan chuẩn-hóa để chặn lệch. Bạn duyệt local (advisory), nhưng gate remote kiểm plan chưa sửa sau duyệt trước cho merge PR và push-main.
harness/hooks/gate_stage.py (PreToolUse·Bash, compliance, fail-closed) blocks push|pr|ship|deploy when the active plan is missing the required artifact. No plan on disk → nothing ships. This is a presence gate (DEC-9): it catches forgotten steps, not a determined cheater.
harness/hooks/gate_stage.py (PreToolUse·Bash, compliance, fail-closed) chặn push|pr|ship|deploy khi plan active thiếu artifact bắt buộc. Không plan trên đĩa → không ship được. Đây là presence gate (DEC-9): bắt bước bị quên, không bắt kẻ cố gian.
FAQHỏi đáp
Does hs:plan write code?hs:plan có viết code không?
plans/. Implementation is hs:cook's job — keeping planning and building separate is the point.Không. Nó chỉ ghi file dưới plans/. Việc implement là của hs:cook — tách planning và build chính là chủ đích.What happens if standards are missing?Thiếu standards thì sao?
harness/standards/ (system-architecture.md + code-standards.md) first. The plan references shared standards instead of inventing its own.Nó dừng và yêu cầu nạp harness/standards/ (system-architecture.md + code-standards.md) trước. Plan tham chiếu standards chung thay vì tự chế.When should I use --fast instead of hard mode?Khi nào dùng --fast thay vì hard mode?
Who can approve the plan?Ai được duyệt plan?
team.yaml who is not the author. Approval binds to a normalized plan_hash, so reformatting needs no re-approval but a content change does. It's recorded via plan_approval.py.Một reviewer (người) có trong team.yaml và không phải tác giả. Duyệt gắn với plan_hash chuẩn hóa, nên reformat không cần duyệt lại nhưng đổi nội dung thì cần. Ghi qua plan_approval.py.