slhx agent
1ec68d400c
Define local/offline truth as commands, domain events, and projections rather than stored DOM patches or EffectBatch payloads; wire the techdemo through a local command-to-projection-to-effect flow; document that hemx-local is not a crate until reusable semantics are proven. req: local/001 req: local/002 req: local/003 req: local/004 req: examples/001
60 lines
4.4 KiB
Markdown
60 lines
4.4 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.
|
|
- Host capability adapters must stay at the `hemx-host` boundary: they may call host APIs and return host events, but they must not mutate DOM or own app/domain state. req: host/002
|
|
- Local/offline app behavior should be commands/events/projections; do not add `hemx-local`, stored DOM patches, or stored `EffectBatch` truth without a proven reusable contract. req: local/001 req: local/002
|
|
- Axum apps should serve and load the shared runtime through hemx-axum helpers such as `runtime_js_path()` and `runtime_js()`, not hard-coded `/hemx.js` URLs or app-owned cache-busting strings.
|