forge-idiomatic-engineer

SKILL.md

Forge Idiomatic Engineer

Full-stack Rust framework. Single binary, PostgreSQL-backed. Axum + Tokio + SQLx. Macros generate runtime wiring and frontend bindings; each handler must be registered in src/main.rs (macros alone do not wire it in).

Compile-Loop Hard Rules

These cause hours of wasted debugging if missed. Internalize before writing code.

SQLX_OFFLINE=true is mandatory for any cargo check / cargo build you run by hand. CI sets it globally. Without it, sqlx tries to validate every sqlx::query!() against your live DATABASE_URL — including queries inside published forge-runtime crate files you cannot edit — and you get a wall of "column does not exist" errors in third-party code. The simplest fix is eval "$(forge env)" in your shell rc; otherwise export SQLX_OFFLINE=true by hand.

forge check auto-prepares the offline cache. It detects when src/ is newer than .sqlx/ and runs cargo sqlx prepare --workspace before the rest of the pipeline, so you don't need to think about prepare ordering. (For raw cargo check, you still need to run forge migrate prepare after editing any sqlx::query!().) Pass --no-prepare in CI where the cache should already be correct.

forge migrate prepare hard-fails if cargo-sqlx is missing. Install with cargo install sqlx-cli --no-default-features --features postgres and re-run.

All forge commands walk up to find forge.toml. Run them from any subdirectory; the resolved root is printed at start. No need to cd first.

If anything in the compile loop feels off, run forge doctor first. It checks rustc, cargo-sqlx, SQLX_OFFLINE, DATABASE_URL reachability, Docker, frontend tooling, forge.toml syntax, .sqlx/ freshness, and that the latest migration file isn't empty in one shot.

A passing cargo sqlx prepare is a passing compile. Don't run forge check purely to "confirm" what prepare just proved — prepare invokes a full cargo check internally. Run forge check only when you have new edits since the last prepare, or to exercise the rest of the validation suite (registration, schema, clippy).

Session Start: Read Once, Trust Memory

Run bash docs/skills/forge-idiomatic-engineer/scripts/orient.sh first. The script walks up to find forge.toml, then prints a structured dump: project name + auth mode + frontend, environment readiness (SQLX_OFFLINE, DATABASE_URL, cargo-sqlx, Docker), .sqlx/ cache freshness, the contents of src/main.rs / src/functions/mod.rs / src/schema/mod.rs, every registered handler grouped by kind, the latest migration, reactivity-enabled tables, and concrete NEXT action hints. One invocation replaces five separate reads.