---
name: hal-handoff
description: Use when a hal-hq design is settled and implementation is about to start in a code repository. Triggers on "start building this", "hand this off", "ready to implement", "who owns this now".
---

# hal-handoff

Hands a settled design to a code repository. **Authoritative playbook:**
[`00-GENESIS/process/04-build-handoff.md`](../../../00-GENESIS/process/04-build-handoff.md).

## Steps

1. **Confirm it is settled.** `status: designed`, and every claim traceable to a record in
   `adr/`. An open question in the text is a reason to run `hal-new-research`, not to build
   around it.
2. **Name the owner.** Set `code:` from
   [`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md). If the repository does not exist yet,
   add it to `repos.md` in the same change.
3. **Read the as-is counterpart.** What is being replaced must be written down in
   `02-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how
   shipped behaviour gets lost.
4. **Flip the status** to `in-progress`, `updated:` today.
5. Build in the code repository. hal-hq never carries implementation.
6. On completion, run `hal-graduate`'s "when something ships" section.

## Non-negotiable

- Every merge is a human checkpoint, without exception.
- **Never open a pull request unprompted.** A permissions list saying it is allowed is not a
  request.
- Work in an isolated worktree, never a shared checkout.
- Never push to the main branch.