hemx/AGENTS.md

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
• Run the workout product exemplar with cargo run --bin hemx-workout-example and open http://127.0.0.1:3028; set HEMX_WORKOUT_ADDR=127.0.0.1:3030 if the default port is busy. Its durable visual direction and recovery expectations live in examples/workout/DESIGN.md. req: examples/001
• Generate and verify the Workout mobile release kit with HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout-mobile release and HEMX_WORKOUT_ORIGIN=https://workout.example.com cargo run -p hemx-xtask -- workout-mobile verify; Android/iOS SDKs and signing remain external blockers, not repo-owned secrets. req: examples/006
• 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.