Retire the HAL name where it points forward #2

Merged
jschoubben merged 1 commits from chore/retire-the-hal-name into main 2026-08-23 19:26:34 +00:00
17 changed files with 39 additions and 39 deletions
@@ -1,9 +1,9 @@
---
name: hal-amend-design
name: hq-amend-design
description: Use when an HQ design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently".
---
# hal-amend-design
# hq-amend-design
Changes a design document. **Authoritative playbook:**
[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md).
@@ -1,9 +1,9 @@
---
name: hal-diagnose
name: hq-diagnose
description: Use when investigating an open HQ issue — finding which component owns a symptom, and why. Triggers on "diagnose issue N", "where does this live", "who owns this bug", "why does this happen".
---
# hal-diagnose
# hq-diagnose
Investigates an open issue to the point where its owner is known. **Authoritative playbook:**
[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md).
@@ -30,7 +30,7 @@ result is not "nothing to learn" — it is the reason the next person repeats th
3. When the owner is known, set `status: located` and fill `located-in:` with repositories or
modules from [`00-META/repos.md`](../../../00-META/repos.md).
4. On resolution: `status: resolved`, fill `fixed-by:`. If the root cause was a design gap, run
`hal-graduate` for the amendment and fill `amended-design:`.
`hq-graduate` for the amendment and fill `amended-design:`.
## Rules
@@ -1,9 +1,9 @@
---
name: hal-graduate
name: hq-graduate
description: Use when a research effort in HQ concludes and becomes design, or when a design must change. Triggers on "graduate this research", "this is decided", "write the ADR", "close the effort", "the design changed".
---
# hal-graduate
# hq-graduate
Closes a research effort into a decision and a design, or amends an existing design.
**Authoritative playbook:**
@@ -1,9 +1,9 @@
---
name: hal-handoff
name: hq-handoff
description: Use when an 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
# hq-handoff
Hands a settled design to a code repository. **Authoritative playbook:**
[`00-META/process/04-build-handoff.md`](../../../00-META/process/04-build-handoff.md).
@@ -11,7 +11,7 @@ Hands a settled design to a code repository. **Authoritative playbook:**
## Steps
1. **Confirm it is settled.** `status: designed`, and every claim traceable to a record in
`02-DECISIONS/`. An open question in the text is a reason to run `hal-new-research`, not to build
`02-DECISIONS/`. An open question in the text is a reason to run `hq-new-research`, not to build
around it.
2. **Name the owner.** Set `code:` from
[`00-META/repos.md`](../../../00-META/repos.md). If the repository does not exist yet,
@@ -21,7 +21,7 @@ Hands a settled design to a code repository. **Authoritative playbook:**
shipped behaviour gets lost.
4. **Flip the status** to `in-progress`, `updated:` today.
5. Build in the code repository. HQ never carries implementation.
6. On completion, run `hal-graduate`'s "when something ships" section.
6. On completion, run `hq-graduate`'s "when something ships" section.
## Non-negotiable
@@ -1,9 +1,9 @@
---
name: hal-new-issue
description: Use when something is wrong with the HAL mesh at the level of design or governance — a rule enforced by nothing, a stated behaviour that does not happen, a failure the design lets pass silently. Triggers on "this is broken", "open an issue", "that rule isn't enforced", "this reports success and does nothing".
name: hq-new-issue
description: Use when something is wrong with the mesh at the level of design or governance — a rule enforced by nothing, a stated behaviour that does not happen, a failure the design lets pass silently. Triggers on "this is broken", "open an issue", "that rule isn't enforced", "this reports success and does nothing".
---
# hal-new-issue
# hq-new-issue
Opens a numbered issue. **Authoritative playbook:**
[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md).
@@ -1,9 +1,9 @@
---
name: hal-new-research
name: hq-new-research
description: Use when starting a new research effort in HQ — an idea, technology or approach worth investigating before it is committed to design. Triggers on "research X", "investigate X", "spike X", "should we use X", "is X worth doing".
---
# hal-new-research
# hq-new-research
Scaffolds a new research effort. **Authoritative playbook:**
[`00-META/process/01-research.md`](../../../00-META/process/01-research.md) — read it;
@@ -31,12 +31,12 @@ this skill only does the mechanical setup.
## Do not
- Do not restate the status in prose. It lives in frontmatter, in one place.
- Do not fill `became:` while the effort is open — `hal-graduate` sets it at closure.
- Do not fill `became:` while the effort is open — `hq-graduate` sets it at closure.
- Do not skip or reuse a sequence number.
- Do not write into `03-DESIGN` from an open effort.
- Do not name the mesh being observed. Evidence is required; identification is forbidden.
## Closing
An effort never just stops. It closes through `hal-graduate` as `graduated` or `abandoned`,
An effort never just stops. It closes through `hq-graduate` as `graduated` or `abandoned`,
always with `became:` pointing at what it turned into. Nothing is deleted.
@@ -1,9 +1,9 @@
---
name: hal-status
name: hq-status
description: Use when you need a cross-cutting view of where HQ stands — research state, design implementation state, open issues, or the decision-record index. Triggers on "what's the status", "show the ADR index", "where do things stand", "what's in progress", "what's open".
---
# hal-status
# hq-status
Generates a cross-cutting view **from frontmatter**. This is a read-and-render skill, not a
workflow — HQ has **no central status file by design** (decision 35). Every view is
@@ -1,9 +1,9 @@
---
name: hal-sync-constitution
name: hq-sync-constitution
description: Use after changing a rule in HQ's 00-META/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page".
---
# hal-sync-constitution
# hq-sync-constitution
Publishes the derived constitution from its source. **Authoritative playbook:**
[`00-META/process/05-constitution-sync.md`](../../../00-META/process/05-constitution-sync.md).
@@ -21,7 +21,7 @@ the claim "HQ is the source" is checked.
## Steps
1. Confirm the source change is recorded as a decision. A rule the mesh enforces is
architecturally significant; if there is no record, run `hal-graduate` first.
architecturally significant; if there is no record, run `hq-graduate` first.
2. Derive the page: the **rules without the reasoning**. Section numbering is stable — the
orchestrator and the review fragments cite sections by number, so never renumber to tidy.
3. Publish it to the knowledge base under the constitution slug, replacing the body.
+2 -2
View File
@@ -1,7 +1,7 @@
# 00-META
The **northern star**. What HAL is, the environment it runs in, and what changes when it
works. Every research effort and design decision is checked against this folder.
The **northern star**. What the mesh is, the environment it runs in, and what changes when it
works — plus the engineering practice that holds across everything Novox builds. Every research effort and design decision is checked against this folder.
| File / folder | Purpose |
|------|---------|
+1 -1
View File
@@ -49,7 +49,7 @@ A **core** module supports an agent's *participation* — acting, remembering,
coordinating, or interfacing with the mesh.
A media server supports a human, but not their participation. It is therefore not a core
module. It is still a perfectly valid HAL module — the
module. It is still a perfectly valid mesh module — the
mesh installs it, provisions for it, brokers its capabilities and ships it through the
same pipeline. Entirely legitimate as a module, and no part of the mesh's own domain.
+1 -1
View File
@@ -57,4 +57,4 @@ YAML frontmatter (schemas in the section READMEs and playbooks). There are **no
files** and no decision ledger. **Every decision is a record in
[`02-DECISIONS`](../../02-DECISIONS/)** — if it is worth recording it is worth a record, and if
it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
are generated on demand by the `hal-status` skill and never written to disk.
are generated on demand by the `hq-status` skill and never written to disk.
@@ -49,6 +49,6 @@ Prose does not restate status. One place, and two is one too many.
## References
- [`.claude/skills/hal-status/SKILL.md`](../.claude/skills/hal-status/SKILL.md) — the
- [`.claude/skills/hq-status/SKILL.md`](../.claude/skills/hq-status/SKILL.md) — the
generator, including the inconsistencies it flags.
- [`02-DECISIONS/README.md`](README.md) — the hand-written index that drifted, and its removal.
+1 -1
View File
@@ -62,6 +62,6 @@ rather than guessing.
## Index
The index is **generated, not maintained** — run the `hal-status` skill, which reads the
The index is **generated, not maintained** — run the `hq-status` skill, which reads the
frontmatter of every record. A hand-written index drifts from the folder it describes, and
this one had already done so after a single addition.
+1 -1
View File
@@ -138,7 +138,7 @@ has to suit both:
| caller | wants |
|---|---|
| the coordinator | non-interactive, structured results it can record against a pipeline, a clean teardown, no prompts and no colour |
| someone working on HAL | readable output, the failing mesh **left standing** to open a shell into, and a way to re-run one assertion without repeating the whole delivery |
| someone working on the mesh | readable output, the failing mesh **left standing** to open a shell into, and a way to re-run one assertion without repeating the whole delivery |
Hence at least two verbs: one that runs to a verdict and tears down, and one that stands a
scenario up and leaves it there. The second is how a developer works *inside* a mesh —
+1 -1
View File
@@ -38,7 +38,7 @@ Status changes when **implementation state** changes, never because design text
`implemented` claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is `in-progress`.
Cross-cutting views are generated from this frontmatter by the `hal-status` skill and never
Cross-cutting views are generated from this frontmatter by the `hq-status` skill and never
written to disk.
## What belongs here
+4 -4
View File
@@ -1,15 +1,15 @@
# Agent instructions — Novox 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
This repository is the source of truth for Novox's mission, research, design and decisions —
today almost entirely those of **Novox Mesh**, its first product ([ADR 0028](02-DECISIONS/0028-hq-is-company-scoped.md)). 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
(`hq-new-research`, `hq-graduate`, `hq-new-issue`, `hq-diagnose`, `hq-amend-design`,
`hq-handoff`, `hq-sync-constitution`, `hq-status`); each defers to its playbook as
authoritative and adds only the mechanical scaffolding.
## Ground rules
+4 -4
View File
@@ -1,7 +1,7 @@
# HAL — HQ
# Novox HQ
The single source of truth for what the HAL mesh **is**, what it is **becoming**, and
why. Implementation lives in `modules/`; the reasoning behind it lives here.
The single source of truth for what Novox builds — what it **is**, what it is **becoming**,
and why. Today that is almost entirely **Novox Mesh**, the substrate everything else runs on. Implementation lives in `modules/`; the reasoning behind it lives here.
## Structure
@@ -78,7 +78,7 @@ particular installation, it is either a note in the wrong place or a disclosure.
## Why this is its own repository
It began inside the code repository, on the reasoning that HAL already has a mesh-native
It began inside the code repository, on the reasoning that the mesh already has a mesh-native
knowledge store and that adding a fourth knowledge system would repeat the mistake this
folder was created to fix.