diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1f34c6d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,77 @@ +# Agent contract — Hyperlex + +You are working in **Hyperlex** (`Zero-State-LLC/Hyperlex`), a standalone +Hermes skill. This file is the canonical contract for Cursor, Claude, +Codex, Grok, and OpenClaw. Harness adapters (`CLAUDE.md`) only point here. + +`SKILL.md` is the Hermes runtime contract. Do not rewrite it unless an +accepted intent is explicitly the skill-contract change. Do not copy +Noema deploy-worker or pin workflows into this repo. + +## Intent + +Read the active `intent.md` under [`intent/`](intent/README.md) before +editing. Next stage is `spec.md` / plan — do not skip to code. + +If the change is non-trivial and no intent exists, draft one from +[`intent/_TEMPLATE.md`](intent/_TEMPLATE.md) and wait for a human to +accept it. Trivial docs and chore fixes do not need an intent file. + +## Commands + +| Task | Command | +|---|---| +| Offline demo | `python3 scripts/hyperlex.py demo` | +| Health | `python3 scripts/hyperlex.py check` then `doctor` | +| Smoke | `python3 scripts/hyperlex.py smoke` | +| Tests | `PYTHONPATH=src pytest -q` | +| Install dry-run | `bash install.sh --dry-run` | + +Do not invent commands. Prefer `${HERMES_SKILL_DIR}` in Hermes `terminal` +calls. Baseline work uses `--route offline` / `mock`. + +## Invariants + +- Brier only after operator settlement. Open analysis keeps `brier: null`. +- Phase 5 / simulate / phylogeny stay **SPECULATIVE**. +- Fail closed on missing outcomes. Label `OBSERVED` / `INFERRED` / + `SPECULATIVE` / `NOT_COMPUTABLE`. +- Do not invent numeric Brier, auto-settle, auto-register Hermes cron, or + rewrite historical receipt integrity. +- Hyperlex never imports Abraxas. Cron (`risk-schedule`) is advisory only. +- Do not invent CLI behavior `SKILL.md` does not name. +- Do not put secrets, tokens, or live credentials in the tree. +- Do not dispatch leftover Noema-shaped deploy or pin workflows. + +## Escalation + +If CI, tests, or validators look wrong — missing coverage, silent skips, +green-but-inert checks, or a suite that contradicts the skill contract: + +1. Open a bounded defect issue labeled `bug`. +2. Do **not** patch tests, fixtures, or CI to force green. +3. Do **not** weaken an assertion or rewrite `SKILL.md` to match a + broken path. + +A red honest check is better than a green lie. + +Owner-gated (human yes): operator settlement, live ingest, cron +registration, official Hermes hub submit, license/legal, and spend. +Agents do not buy things or publish the skill as official. + +## Team context + +Org and partner status is not this repo. When a task needs it, load +[Zero-State-LLC/agent-context](https://github.com/Zero-State-LLC/agent-context): + +1. `HANDOFF.md` +2. `STATUS.md` +3. `DECISIONS.md` only if a prior choice affects this task + +Clone: `gh repo clone Zero-State-LLC/agent-context ~/agent-context`. +Pull `--ff-only` before trusting a local copy. + +## Skills + +Name only skills that already exist. Do not invent skills or bots. +The Hermes skill in this repo is `hyperlex` (`SKILL.md`). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0390e52 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,2 @@ +Follow [AGENTS.md](AGENTS.md). That file is the only contributor and agent instruction source in this repository. +For a non-trivial change, read the active intent.md before editing. If none exists, draft intent.md and wait for human accept. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 063a1c0..01f6081 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,6 +5,9 @@ This repo is the single source of truth for **design and specification**. Implementation details belong in the engine package. Changes here should drive implementation. +Coding agents follow [`AGENTS.md`](AGENTS.md) (`CLAUDE.md` is a thin pointer +there). Non-trivial work starts with [`intent/`](intent/README.md). + ## How to Contribute 1. Open an issue or discussion first for significant changes. 2. Update relevant spec/roadmap file. diff --git a/README.md b/README.md index b5b0ac8..d619656 100644 --- a/README.md +++ b/README.md @@ -347,6 +347,8 @@ from hyperlex.compat.abraxas import to_brier_ledger_entry, list_hlx_runes | [docs/phase5.md](./docs/phase5.md) | Research simulation | | [docs/slang-lineages.md](./docs/slang-lineages.md) | Lineage methodology | | [docs/hermes-skill.md](./docs/hermes-skill.md) | Skill model | +| [AGENTS.md](./AGENTS.md) | Multi-agent SDLC contract (`CLAUDE.md` is a thin pointer here) | +| [intent/](./intent/README.md) | Intent template for non-trivial work; then spec.md / plan | Examples: `examples/cron/` · `examples/receipts/golden/` · `examples/calibration/` · `examples/slang-families/` · `examples/case-studies/` @@ -354,7 +356,7 @@ Examples: `examples/cron/` · `examples/receipts/golden/` · `examples/calibrati ## Contributing -See [CONTRIBUTING.md](./CONTRIBUTING.md). Keep the settlement rule and offline-first defaults intact. Prefer small, test-backed PRs. +See [CONTRIBUTING.md](./CONTRIBUTING.md). Agent contract: [`AGENTS.md`](AGENTS.md) (`CLAUDE.md` is a thin pointer there). Non-trivial work starts with [`intent/`](intent/README.md). Keep the settlement rule and offline-first defaults intact. Prefer small, test-backed PRs. ```bash PYTHONPATH=src pytest -q diff --git a/docs/README.md b/docs/README.md index d5716d1..b2b74f8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -25,6 +25,8 @@ Hyperlex is a **Hermes skill** (Python package repo). Relevant Abraxas wire shap - [ARCHITECTURE.md](architecture.md) - [DESIGN.md](design.md) - [SPEC.md](spec.md) +- [AGENTS.md](../AGENTS.md) — multi-agent SDLC contract (`CLAUDE.md` is a thin pointer there) +- [intent/](../intent/README.md) — intent template for non-trivial work; then spec.md / plan ## Examples - `examples/slang-families/` — Mermaid family trees diff --git a/intent/README.md b/intent/README.md new file mode 100644 index 0000000..c0f669c --- /dev/null +++ b/intent/README.md @@ -0,0 +1,23 @@ +# Intent files + +Non-trivial work starts here. Copy [`_TEMPLATE.md`](_TEMPLATE.md) to a dated, +scoped file (for example `intent/2026-09-04-short-slug.md`) and fill every +section before writing a spec, plan, or code. + +Do not invent a parallel process. After the intent is written, continue with +the flow this repo already uses: + +1. `intent.md` — problem, proposed outcome, constraints, verified vs assumed +2. `spec.md` / plan — existing `docs/` specs, `references/` contracts, and + `CONTRIBUTING.md` gates. Revise `SKILL.md` only when the accepted intent + is the Hermes contract itself. +3. Implementation in the allowed trees (skill payload, package, CLI, docs) +4. PR with honest `OBSERVED` / `INFERRED` / `SPECULATIVE` / `NOT_COMPUTABLE` + evidence + +Trivial docs, chore, and single-line fixes do not need an intent file. +`_TEMPLATE.md` is the blank form; do not fill it in place. + +An intent is not a spec, not a plan, and not implementation authority. It +does not authorize a `SKILL.md` rewrite, official Hermes hub publish, +operator settlement, extra bots, or leftover Noema deploy/pin jobs. diff --git a/intent/_TEMPLATE.md b/intent/_TEMPLATE.md new file mode 100644 index 0000000..8a52660 --- /dev/null +++ b/intent/_TEMPLATE.md @@ -0,0 +1,39 @@ +# Intent + +## Problem + +What is wrong, missing, or blocked? + +## Proposed outcome + +What does done look like? What is explicitly out of scope? + +## Affected users / systems + +Who or what is affected (Hermes operators, CLI, receipts, score log, +lineage, Phase 5 research, Pages archive, CI, …)? + +## Constraints / non-goals + +Hard limits: `SKILL.md` contract, settled-Brier-only, Phase 5 stays +SPECULATIVE, no Abraxas import, advisory cron only, no invented bots, +owner-gated settlement / live ingest / hub publish / legal / spend. +What this work will not decide. + +## Open questions + +What must be answered before or during the work? Who decides? + +## Verified / assumed claims + +- **Verified:** facts checked in this repo or on a green run. +- **Assumed:** beliefs not yet checked. Do not upgrade Assumed to Verified. + +| Claim | Label | Basis | +|---|---|---| +| \ | `OBSERVED` / `INFERRED` / `NOT_COMPUTABLE` | \ | + +## Author / date + +- Author: +- Date: