steer: Instructions file for Codex

Dev Environment

This repo includes flake.nix. Run commands directly by default. Only use the Nix devshell when a command fails due to missing dependencies that are expected to be provided by the devshell (for example, nix develop -c <command>).

Commands

Run just commands directly first. If one fails due to missing deps, retry it inside nix develop.

# Default
just check
just test
just build

# Fallback when deps are missing
nix develop --command just check
nix develop --command just test
nix develop --command just build

# For multiple commands (fallback)
nix develop --command sh -c "just check && just test"

Using the devshell this way keeps the environment consistent without requiring an interactive shell session.

When to use which command

• just pre-commit - Runs clippy, format check, and tests. Use before committing to verify code is ready.
• just fix - Auto-fixes all issues (cargo fix, clippy fix, formatting). Use to resolve lint/format errors.
• just check - Runs cargo check --all-features. Fast type checking without full compilation.
• just clippy - Runs cargo clippy --all-features with warnings as errors. Use for lint checking.
• just test - Runs cargo test --all-features. Use after making functional changes.
• just build - Runs cargo build --all-features. Use when you need a full build.
• just fmt - Runs cargo fmt --all. Use to format code.
• just ci - Runs nix flake check, which is comprehensive but slow. Agents should almost never need this. It's primarily for CI pipelines and final verification before merging.

Version Control

This project uses jj (Jujutsu) for version control.

Create new commits frequently as checkpoints during development. Small, incremental commits make it easier to track progress, revert problematic changes, and understand the evolution of the codebase. Don't wait until a feature is complete—commit working states along the way.

Commits

Follow the conventional commits format.