From 524ef7550528aed14958f9aa89ea2619ee845ede Mon Sep 17 00:00:00 2001 From: Hassan Abedi Date: Thu, 23 Apr 2026 13:43:01 +0200 Subject: [PATCH] Update the `AGENTS.md` and make it more robust to change --- AGENTS.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 69ed569..205e1e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,18 +42,23 @@ Quick examples: ## Repository Layout -- `01-devshell/`, `02-*/`, `NN-/`: self-contained numbered examples. Each directory is a flake root. -- `notes/`: prose companions numbered to match reading order. - - `001-glossary.md`: vocabulary reference. - - `002-nix-primer.md`: the Nix language and store model. - - `003-flakes.md`: flake anatomy, schema, and common patterns. +- `NN-/`: self-contained numbered examples. Each matching top-level directory is a flake root. +- `notes/NNN-*.md`: prose companions numbered to match reading order. + - Lower note numbers cover shared foundations such as the glossary, the Nix language, and flakes. + - Later note numbers may cover specific example tracks or cross-example guides. - `Makefile`: discovery-based helpers that run formatting, linting, and `nix flake check` across all examples. - `AGENTS.md`: this file. - `.pre-commit-config.yaml`, `.editorconfig`, `.gitattributes`, `.gitignore`: repository hygiene. - `pyproject.toml`: Python environment metadata used only to install `pre-commit`. -New examples follow `NN-/` where `NN` is a two-digit ordinal. Topics grow roughly from simpler to more involved: dev shell, package, -multi-system, NixOS module, home-manager, overlay. +New examples follow `NN-/` where `NN` is a two-digit ordinal. + +Do not assume the directory list or note list in this file is exhaustive. The repository is expected to grow over time, and agents should discover the +current layout from the filesystem when needed. + +Example ordering should still feel like a readable path from simpler to more involved, but the repository may branch into themed subtracks, for example +Nix and flake outputs, Haskell with Nix, or future ecosystem-specific tracks. Keep each example focused on one concept even when the broader sequence +branches. ## Example Layout Constraints @@ -104,6 +109,9 @@ Example scopes that are good first tasks: - Add a short section to `notes/003-flakes.md` referencing a newly added example. - Convert an existing example from a hand-rolled `forAllSystems` to `flake-utils`, or vice versa, with a comment explaining the tradeoff. +When the repository contains multiple themed tracks, "the nearest existing example" means the nearest example in the relevant track, not necessarily the +numerically closest directory overall. + ## Testing Expectations - This repository has no runtime test suite; "tests" are `nix flake check` outcomes and successful builds of each example's default output. @@ -152,6 +160,7 @@ Use this review format: - If two examples disagree on a convention, prefer the newer one and update the older example in a dedicated commit. - When uncertain whether a concept deserves its own example, start by expanding the notes; promote to an example once the idea stabilizes. - Keep presentational prose in `notes/`. Keep runnable material in numbered directories. Do not cross the streams. +- Prefer layout guidance based on naming patterns and discovery, not hard-coded counts of examples or notes. If you need the current tree, inspect it. - Keep user-facing naming consistent with the repository name: `nix-playground`. The directory spelling `nix-playgraound` is intentional and should not be "fixed".