Add AGENTS.md

[dsblank]

Summary

• Add AGENTS.md so agentic coding tools that look for the increasingly common AGENTS.md convention pick up this repo's contributor/agent guidelines.

Inspired by eduralph's
GEPS 049: Versioned Addon API surface and 2-axis lifecycle model,
which discusses tooling/process conventions for addon development — this
is a small, independent step in that direction: giving addon-repo agents a
clear, tool-agnostic set of guidelines to follow.

Test plan

• N/A — documentation-only change, no code affected.

[dsblank]

CC: @eduralph

I thought I'd start with my instructions. Feel free to update, replace, or merge.

[eduralph]

CC: @eduralph

I thought I'd start with my instructions. Feel free to update, replace, or merge.

Good, stuff - I'll pile on it

[dsblank]

All review comments addressed.

[hgohel]

@dsblank Does adding something like this make sense in this repo and/or Gramps core?

Do not attempt to build/run on Windows

Windows Development & Code Generation Boundaries

This project natively supports Linux, macOS, and Windows via the MSYS2 environment. It cannot be built or run directly on native Windows (CMD/PowerShell).

If you are executing inside a native Windows host environment, you must adhere to the following execution boundaries:

Allowed Actions

• Code Generation & Editing: You may freely write, refactor, and generate Python code, documentation, and configuration files.
• Static Analysis: You may run local linters (ruff, flake8) or formatters (black) if they are installed in your host Python environment.

Forbidden Actions (Do Not Attempt)

• Running Tests: Do not attempt to run pytest or any test suites natively on Windows. Tests rely on POSIX-specific behaviors and will fail.
• Running the Application: Do not attempt to execute the application or its build scripts on native Windows.
• Environment Setup: Do not attempt to install project dependencies via pip or poetry in a native Windows environment unless explicitly operating inside an MSYS2 shell.

Note for Agents: If you need to verify changes via tests or execution on a Windows machine, you must explicitly ask the user to run the commands inside an MSYS2 terminal or a Linux-based container/WSL environment and feed the output back to you.

[dsblank]

@hgohel asks:

Does adding something like this make sense in this repo and/or Gramps core?

I don't know enough about github actions or build commands to answer this question. Is it our own limitation, or something about github that makes it impossible to build under Windows?

[hgohel]

Is it our own limitation, or something about github that makes it impossible to build under Windows?

It's not a GitHub Actions constraint. It stems from the pre-requisites for Gramps. Gramps is documented to build only under MSYS2.

[dsblank]

@hgohel I see: you are making a distinction between "Windows" and "MSYS2" (maybe could be clarified in your suggested text).

[dsblank]

@hgohel Added a Windows Development section to AGENTS.md that makes the MSYS2 vs. native Windows distinction explicit:

• MSYS2 (the POSIX-like shell/toolchain Gramps's own Windows installer is built with) behaves like a Linux shell, so make.py and the unittest invocations documented elsewhere in AGENTS.md work normally there.
• Native Windows (bare cmd.exe/PowerShell, no MSYS2 or WSL underneath) is called out separately — the commands/env vars in this doc assume a POSIX shell and haven't been verified against it.
• On native Windows, an agent may still read/write/refactor addon code freely, but should not run this repo's tests or make.py there and report the result as a real pass/fail (since the tooling isn't validated in that environment), and should instead ask the user to run the command in MSYS2/WSL/a Linux container and share the output.

Kept it addons-source-specific (references make.py, unittest, GRAMPSPATH/GRAMPS_RESOURCES) rather than the more generic pytest/poetry wording, since those aren't part of this repo's toolchain.

[dsblank]

Thanks @hgohel!

@GaryGriffin I think this is ready to merge. We can (and should) make regular updates to this file as we find better was of prompting agents.

[hgohel]

Thank you @dsblank. The concise instructions you added are appropriate.