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 with an explicit redgate ring field; shorten near-limit rows or split oversized examples, escape hatches, or negative cases into separate stable IDs while preserving the original ID's main intent.
• 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; when fixing one row in a section, normalize nearby rows with the same warning if it stays a requirement-only cleanup.
• 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
• Example behavior tests should prefer hemx_test generated-resource assertions over raw slot constants or raw effect/payload matching. req: test/008
• 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/008
• 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 req: examples/011
• hemx core stays small: effects, typed ids, registries, and wire schema only; keep features in core only when they fit typed resources plus EffectBatch ops. req: laws/001
• Routing, auth, sessions, transport, transitions, sync, and storage belong in integration/user crates.
• Public examples and beginner APIs should use templates plus Rust, generated component APIs, resources, and IntoEffect, not atoms, raw ids, selectors, wire formats, runtime opcodes, manual registries, $OUT_DIR includes, or raw effect constructors; keep advanced layers out of starters. req: canonical_authoring/001 req: canonical_authoring/004 req: canonical_authoring/006 req: canonical_authoring/010 req: canonical_authoring/015 req: dx/001 req: dx/002 req: dx/010 req: component/003 req: component/004 req: progressive_disclosure/001 req: progressive_disclosure/002 req: progressive_disclosure/003
• Typed partial swaps should stay expressed as generated target plus rendered partial plus swap kind, not selector-driven rerendering; HTTP, page navigation, push, and island behavior adapt around that loop, and docs should layer new primitives progressively. req: canonical_authoring/002 req: canonical_authoring/014 req: modes/001 req: progressive_disclosure/004 req: page_swap/001 req: page_swap/002 req: page_swap/003
• 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, not HTMX syntax or selector targeting. Boost containers enhance same-origin descendants only and preserve native external/download/new-tab behavior. req: htmx_equivalents/001 req: htmx_equivalents/003 req: htmx_equivalents/005 req: examples/007 req: page_swap/007 req: page_swap/008
• 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; do not treat it as a mobile framework or store-submission bot. req: ceremony/005 req: ceremony/006 req: ceremony/007
• 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. hemx-build consumes hemplate Surface facts and must not grow an independent .heml parser or CSS-path identity model. req: surface/001 req: surface/002 req: surface/003 req: surface/004 req: surface/005 req: surface/006 req: surface/007 req: surface/008 req: surface/009 req: surface/010
• 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
• Opaque island JavaScript is a leaf adapter for high-frequency local behavior only; it must not introduce a component runtime, client state graph, VDOM, or second UI model. req: canonical_authoring/017
• 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, stored EffectBatch truth, or a core client state graph without a proven reusable contract. req: canonical_authoring/018 req: canonical_authoring/019 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.