# Agent instructions — hal-hq

This repository is the source of truth for the HAL mesh's mission, research, design and
decisions. Implementation lives in the code repositories (see
[`00-META/repos.md`](00-META/repos.md)).

Before changing anything here, read the playbooks in
[`00-META/process/`](00-META/process/) — every workflow (research, graduation, design
amendment, issues, build handoff, constitution sync) is documented there, and agents operate
through them. Thin skills in `.claude/skills/` wrap these playbooks for invocation
(`hal-new-research`, `hal-graduate`, `hal-new-issue`, `hal-diagnose`, `hal-amend-design`,
`hal-handoff`, `hal-sync-constitution`, `hal-status`); each defers to its playbook as
authoritative and adds only the mechanical scaffolding.

## Ground rules

- **Markdown only.** No new top-level folders without explicit confirmation.
- **Status lives in YAML frontmatter** — on research overviews (`status`, `became`), design
  docs (`layer`, `status`, `code`, `updated`), issue reports (`status`, `located-in`,
  `fixed-by`, `amended-design`) and decision records (`status`, `date`, `deciders`).
  Never create a central status file; cross-cutting views are generated from frontmatter.
- **`02-DECISIONS/` records are immutable.** Supersede with a new record; never edit meaning. Fixing a
  broken link or path is allowed.
- **Design docs are prose and diagrams only** — no code. A manifest field may be named; a
  manifest may not be pasted.
- **Two layers, never mixed.** [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) describes the mesh
  that exists; [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) describes the one being built
  toward. Every design doc says which it is in `layer:`. A statement about the future does not
  belong in an as-is document, and an as-is document is never edited to describe an intention.
- **`00-META/how-we-build.md` is the source of the mesh constitution.** The knowledge-base
  constitution page is derived from it — see playbook
  [`05-constitution-sync.md`](00-META/process/05-constitution-sync.md). Never edit the
  derived page directly.

## This repository is public

Nothing here may contain routable addresses, real domain names, hosting providers, node
names, absolute paths, usernames, credentials, or operational detail useful only to an
attacker. Use documentation ranges (RFC 5737, RFC 1918) and role names — `anchor`,
`home-server`, `workstation`, `laptop`, `the build node`, `the broker node`.

The test: would this paragraph still teach a stranger running an entirely different mesh?
If yes, it belongs. If it only makes sense to someone who knows this installation, it is
either a note in the wrong place or a disclosure. The full rule is in
[`README.md`](README.md).

## A rule states how it is checked

If a document states a rule about the mesh, it says how that rule is verified. An unenforced
rule is indistinguishable from a wrong one, and costs more, because people believe it.