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.
• If implementation work does not change durable product obligations, acceptance, safety/recovery behavior, or verification duties, say REQUIREMENT IMPACT: none in the handoff and why.
• 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; include redgate lint when the change is meant to reduce requirement maintainability warnings.

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.
• Keep each requirement row to one checkable obligation; split oversized examples, escape hatches, or negative cases into separate IDs.
• 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 lint — show maintainability warnings such as missing rings and oversized requirement rows.
• 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 run -p hemx-xtask -- html-examples-smoke, cargo check --workspace, redgate health --strict. Use the xtask runner for full verification so jobs are capped from local CPU and memory; use the html_examples smoke for focused browser verification of the HTML pattern gallery. req: test/004 req: test/006
• Run the workout product exemplar with cargo run -p hemx-xtask -- workout dev 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
• Use the same Workout command surface for tests, production build, and mobile release: cargo run -p hemx-xtask -- workout test, cargo run -p hemx-xtask -- workout build, 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, store submission targets, 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.
• examples/html_examples is the copy-paste HTML pattern gallery for htmx-style examples; keep exact htmx URL slugs visible while translating behavior to boring .heml, generated resources, and server-owned Rust state. req: htmx_equivalents/001 req: htmx_equivalents/002 req: examples/001
• Use cargo run -p hemx-xtask -- app new PATH for the generic page/form/keyed-row/notice starter, and cargo run -p hemx-xtask -- app new --mobile PATH for the phone-first starter with host capabilities, recovery truth, and release-kit commands. req: ceremony/005 req: ceremony/006
• The public component-reuse explanation lives in docs/recipes/reusable-partials.md; do not grow a client component framework to explain partial composition.
• The stable public .heml authoring surface lives in docs/hemplate-syntax.md; Hemlate examples must use that real hemplate syntax, not Vue/Handlebars sketches.
• Optional .heml editor overlays must share authority with hemx-build diagnostics and docs/hemplate-syntax.md; hemx-lsp owns editor protocol glue for diagnostics/completion/hover and derive-known template facts, while VS Code/Cursor/Neovim keep normal HTML/tree-sitter tooling. Do not create a second template language, selector model, formatter, Rust type system, or custom editor framework. req: diagnostics/004 req: diagnostics/005 req: diagnostics/006
• JS runtime changes must preserve root-scoped lookup, fail-closed request handling, root-scoped error outlets, and tiny pending/failure/trigger-timing conventions without selectors, VDOM, expressions, or per-node listeners. req: runtime/005 req: convention/001 req: convention/003 req: convention/005 req: convention/007
• 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.