0xrsydn/dotfiles
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
dotfiles/AGENTS.md

2.3 KiB
Raw Blame History

Repository Guidelines

Project Structure & Module Organization

  • flake.nix / flake.lock: entry point for nix-darwin + Home Manager; defines overlays and the macbook-pro host.
  • modules/darwin/: machine-level options (system.nix, homebrew.nix, devtools.nix). Extend these for hardware or OS-wide services only.
  • modules/home/rsydn/: Home Manager profile composed of programs/, shell/, and devtools/. User-level bundles belong here, including AI tooling.
  • .cache/: local build cache. Keep it out of Git.

Build, Test, and Development Commands

  • nix develop: enter the flake’s dev shell (bundles git, nixfmt-classic, etc.).
  • nix fmt: format all Nix sources using the flake’s formatter output.
  • XDG_CACHE_HOME=$PWD/.cache nix flake check: type-checks modules, overlays, and packages without polluting global caches.
  • darwin-rebuild --dry-run --flake .#macbook-pro: smoke-test activation scripts.
  • darwin-rebuild switch --flake .#macbook-pro: apply the configuration once validation passes.

Coding Style & Naming Conventions

  • Nix code: two-space indent, trailing commas, lower-kebab filenames (e.g., shell/nushell.nix).
  • Custom options live under the rsydn.* namespace; keep logical groupings (rsydn.aiTools, rsydn.devTools).
  • Run nix fmt before committing; avoid manual formatting tweaks that fight the formatter.

Testing Guidelines

  • nix flake check is mandatory before any PR; treat failures as regressions.
  • For substantial module changes, add darwin-rebuild --dry-run output to the PR discussion.
  • Pending automated tests should live beside the module they cover; name files after their option namespace (e.g., rsydn-ai-tools.nix).

Commit & Pull Request Guidelines

  • Commits: short, imperative subjects (replace zsh with nushell), one logical change per commit.
  • Include the exact validation commands run (nix flake check, dry-run output) in the PR body.
  • Reference related issues or TODOs; attach logs/screenshots if they clarify UI-facing changes (e.g., Ghostty themes).

AI Tooling & Shell Profile

  • AI CLIs are toggled via rsydn.aiTools; adjust packages and enable flags there rather than invoking installers manually.
  • Nushell is the default interactive shell. Any bootstrap scripts must be Nix-managed to avoid PATH drift.