slhx agent
c33500440e
Rename the tracked product identity, crate/package names, Rust paths/macros, generated artifacts, runtime files, public attributes, examples, docs, requirements, and tests from slhx to hemx without compatibility shims. Verified with cargo run -p hemx-xtask -- test, cargo test -p hemx-derive --test compile_fail, cargo test -p hemx-js, cargo test -p hemx-axum, cargo test -p hemx-v0-examples, cargo check --workspace, redgate list, redgate refs, redgate health --strict, git diff --check, and git grep/ls-files legacy-name audits. req: misc/001 req: codegen/001 req: component/004 req: runtime/001
57 lines
3.9 KiB
Markdown
57 lines
3.9 KiB
Markdown
# hemx — AGENTS.md
|
|
|
|
## Purpose
|
|
|
|
This file tells coding agents how to work in this repository. It is a durable operating contract, not a generated inventory.
|
|
|
|
Keep it stable. Prefer pointers to canonical sources over copied structure, file lists, metrics, architecture maps, command inventories, or status snapshots.
|
|
|
|
## Agent workflow
|
|
|
|
- Start from product intent and requirements; inspect code only after the target behavior is clear.
|
|
- Read `REQUIREMENTS.md` before changing behavior.
|
|
- If behavior changes, update `REQUIREMENTS.md` in the same change.
|
|
- Cite relevant requirements in code, tests, or docs as `req: <component>/001`.
|
|
- Do not add citation-only padding to satisfy tooling; cite only where the requirement constrains the text.
|
|
- Use requirement tags consistently: stable area tags like `[parser]`, `[auth]`, `[ui]`; temporary planning tags like `[bootstrap]`, `[mvp]`, or `[milestone-1]` only while they are useful.
|
|
- Run `redgate list`, `redgate refs`, and `redgate health` when requirements change.
|
|
|
|
## Git workflow
|
|
|
|
- Commit complete, coherent slices only; do not commit broken work or temporary debug output.
|
|
- Use Conventional Commits: `type(scope): summary`.
|
|
- Keep commit subjects readable; requirement IDs do not have to be in the subject.
|
|
- Every behavior-changing or requirement-changing commit should cite relevant requirement IDs in the commit body or trailers using `req: <component>/001`.
|
|
- Use commit history for evolution: `git log --grep 'req: parser/012'` should find the commits that changed that behavior.
|
|
- Use the current tree for state: `REQUIREMENTS.md`, citations, tests, and `redgate health` describe what is true now.
|
|
- Before committing requirement or behavior changes, run relevant tests and `redgate health --strict`.
|
|
|
|
## Requirements-first TDD
|
|
|
|
- Write requirements as desired behavior, not as a snapshot of current behavior.
|
|
- First split intent into broad error classes: what can go wrong, and what outcome must hold.
|
|
- Test the largest risky classes before narrow examples.
|
|
- Add adversarial tests for malformed, hostile, ambiguous, missing, duplicated, and boundary inputs.
|
|
- Do not over-codify existing behavior while direction is still moving.
|
|
- Add narrow concrete tests only after requirements converge into a stable direction.
|
|
|
|
## Redgate CLI
|
|
|
|
- `redgate list` — show requirements as TSV.
|
|
- `redgate refs` — show `req:` citations found in the repo.
|
|
- `redgate health` — show uncited requirements, duplicate IDs, and stale citations.
|
|
- `redgate health --strict` — fail on hard errors: empty requirements, duplicate IDs, or stale citations.
|
|
- `redgate agents` — print this starter template; review, shrink, and edit before committing.
|
|
|
|
## Local guidance
|
|
|
|
- Add only durable style, ownership, gotchas, and at most a few stable commands agents should actually run.
|
|
- Prefer links or pointers to canonical sources over copied lists.
|
|
- Avoid project trees, architecture maps, generated inventories, current file sizes, issue lists, TODO inventories, and other snapshots that will rot.
|
|
- Stable commands: `cargo run -p hemx-xtask -- test`, `cargo check --workspace`, `redgate health --strict`. Use the xtask runner for full verification so jobs are capped from local CPU and memory. req: test/004
|
|
- hemx core stays small: effects, typed ids, registries, and wire schema only.
|
|
- Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates.
|
|
- Public examples and beginner APIs should use generated resources and `IntoEffect`, not raw ids or runtime opcodes.
|
|
- Hemlate examples must use real hemplate syntax, not Vue/Handlebars sketches: `{+ expr +}` for escaped text, `{+= expr =+}` only for trusted/rendered HTML, `+attr="expr"` for dynamic attributes, and Rust-shaped `h-if`, `h-for`, `h-match`, `h-case` directives (`h-case="_"` is the default arm).
|
|
- JS runtime changes must preserve root-scoped lookup and avoid selectors, VDOM, expressions, and per-node listeners.
|