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

chore: update AGENTS.md

Browse source
This commit is contained in:
Rasyidan Akbar F. 2025-10-01 11:04:12 +07:00
commit 3b89f0610c
1 changed files with 22 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

44
AGENTS.md
View file

@ -1,33 +1,33 @@
# 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.
- `flake.nix`/`flake.lock` drive the entire nix-darwin + Home Manager configuration; `macbook-pro` is the only declared host.
- `modules/darwin/` contains device-level modules (`system.nix`, `homebrew.nix`, `devtools.nix`). Keep OS services and hardware toggles here.
- `modules/home/rsydn/` provides the Home Manager profile. Subdirectories `programs/`, `shell/`, and `devtools/` house user apps, Nushell/theming, and language/AI bundles.
- Secrets belong under `secrets/*.sops.yaml`; decrypted payloads are emitted into `~/.config/secrets/` at activation. The cached build outputs in `.cache/` stay untracked.
## 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.
## Build, Test & Development Commands
- `nix develop` — enter the flake dev shell with `git`, `nixfmt-classic`, and Age/SOPS helpers.
- `nix fmt` — format every Nix file via the flake’s formatter; run after edits to modules or overlays.
- `XDG_CACHE_HOME=$PWD/.cache nix flake check` — lint and type-check all modules without touching the global cache.
- `darwin-rebuild --dry-run --flake .#macbook-pro` — validate activation steps and surface breaking changes.
- `darwin-rebuild switch --flake .#macbook-pro` — apply the configuration once checks succeed.
## 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.
- Nix sources use two-space indents, trailing commas, and lower-kebab filenames (`shell/nushell.nix`).
- Custom options live in the `rsydn.*` namespace (`rsydn.aiTools`, `rsydn.devTools`). Extend existing option sets instead of scattering ad-hoc attributes.
- Prefer declarative package toggles over ad-hoc installers; Nushell, AI CLIs, and prompts are all Home Manager managed.
## 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`).
- Run `nix flake check` before every PR or local switch; treat failures as blockers.
- Capture key outputs (e.g., `darwin-rebuild --dry-run`) for substantial module changes and share in review threads.
- If you add reusable logic, colocate regression tests beside the module using the `<option-name>.nix` pattern (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).
- Use short, imperative commit subjects (`add nushell env path hook`); keep each commit scoped to one logical change.
- Document validation steps in the PR body (`nix flake check`, dry-run logs) and reference related issues or TODOs.
- Include screenshots or terminal snippets when modifying shells, prompts, or visual tooling to show the resulting UI.
## 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.
## Security & Configuration Tips
- Age keys live at `~/.config/sops/age/keys.txt`; Home Manager generates them if absent. Do not commit decrypted files from `~/.config/secrets/`.
- To access a secret, read the managed file (e.g., `open ~/.config/secrets/openai-api-key | str trim`) and scope the value with `with-env` instead of exporting it globally.