Add AGENTS.md, dotnet/mise wrapper scripts, migrate yaks to yx

2026-09-10 18:12:50 +01:00
parent 42b3c502a1
commit 7e38f67e0b
7 changed files with 90 additions and 153 deletions
@@ -0,0 +1,49 @@
+# AGENTS.md
+
+Exercise repo: illustrating the transition from DB-backed domain classes
+(`DbBase` inheritance) to plain domain objects + DTOs + mappers.
+Diagrams: `before-after-dto.mmd`, `after-dto.mmd` (source sketch:
+`before-after-dto-sketch.png`).
+
+## Running dotnet
+
+dotnet SDK 10 is installed **via mise** (see `mise.toml`). It is NOT on PATH in
+agent/sandbox shells, and SDK 10 additionally fails without
+`DOTNET_CLI_HOME` in some shells. Always use the wrappers:
+
+```sh
+scripts/dotnet.sh build db-subclass-to-dto.sln
+scripts/dotnet.sh test db-subclass-to-dto.sln
+scripts/run-tests.sh          # full test suite, from repo root
+```
+
+The wrappers cd to the repo root (the test runner must run from the parent
+directory of the test project), export `DOTNET_CLI_HOME`, and invoke
+`mise exec -- dotnet ...`. Do not call bare `dotnet`.
+
+## Yaks (task management with yx)
+
+Tasks are managed with the `yx` CLI; yaks live in git (event store), snapshot
+in `.yaks/` (gitignored). Work one yak at a time:
+
+```sh
+yx list                        # all yaks and states
+yx show "<yak name>"           # full yak context (the task instructions)
+yx start "<yak name>"          # set state to wip
+yx done "<yak name>"           # set state to done (only after acceptance
+                               # criteria pass and changes are committed)
+```
+
+- The yak context in `yx show` is the authoritative task description; follow
+  its acceptance criteria before `yx done`.
+- Children block their parent: do prerequisites (nested under a yak) first.
+- Add new tasks: `yx add "<name>"` (nest with `--under "<parent>"`).
+- If yx complains `.yaks is not gitignored`, keep `.yaks` in `.gitignore`.
+
+## Conventions
+
+- Target framework: net10.0 (SDK pinned by mise).
+- Tests: xUnit, one `tests/BeforeAfter.Tests/` project.
+- No EF Core / SQLite / AutoMapper — the DB layer is a small hand-rolled fake
+  (pure managed code, cross-platform).
+- Commit per yak with a message referencing the yak.