Retire the HAL name where it points forward #2
@@ -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
|
||||
+3
-3
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user