From 07c48658fe2c3c62cf4adcc49a3dc5a25fb8a17a Mon Sep 17 00:00:00 2001 From: Szymon Talaga Date: Fri, 21 Aug 2026 21:08:49 +0200 Subject: [PATCH 1/2] Agent Host changes for agents/check-copier-variables-agents-md --- template/AGENTS.md.jinja | 77 ++++++++++++++++++++++++++++++++++++ template/STYLE.md | 29 ++++++++++++++ template/devnotes/example.md | 17 ++++++++ 3 files changed, 123 insertions(+) create mode 100644 template/AGENTS.md.jinja create mode 100644 template/STYLE.md create mode 100644 template/devnotes/example.md diff --git a/template/AGENTS.md.jinja b/template/AGENTS.md.jinja new file mode 100644 index 0000000..49376b1 --- /dev/null +++ b/template/AGENTS.md.jinja @@ -0,0 +1,77 @@ +# {{ project_name }} agent guide + +## Project overview + +- Distribution: `{{ distribution_name }}` +- Import package: `{{ package_name }}` +- Source directory: `src/{{ package_name }}/` +- Tests: `tests/` +- Repository: {{ repository_url }} + +{{ project_description }} + +## Working conventions + +Read and follow [STYLE.md](STYLE.md) before changing Python code or tests. +`pyproject.toml` is the source of truth for dependency groups, Ruff, mypy, +pytest, and coverage configuration. + +Keep changes focused, preserve public behavior unless the task intentionally +changes it, and add or update tests for behavior changes. + +## Development notes + +Use `devnotes/` to record concise, task-specific context during development. +Read [devnotes/example.md](devnotes/example.md) before starting a note, and +replace it with notes that capture decisions, validation results, and useful +follow-up work. + +## Validation + +{% if tasks == "tox" -%} +Use tox to run the generated automation: + +```console +uvx tox -m checks +uvx tox -m tests +``` +{%- elif tasks == "nox" %} +Use the generated Nox script to run automation: + +```console +uv run noxfile.py -s lint +uv run noxfile.py -s typecheck +uv run noxfile.py -s tests +``` +{%- else %} +Run the appropriate dependency group directly: + +```console +uv run --group lint pre-commit run --all-files +uv run --group type mypy src tests +uv run --group test pytest +``` +{%- endif %} +{%- if docs %} + +## Documentation + +Documentation lives in `docs/`. Build it with the generated task runner before +submitting documentation changes. +{%- if tasks == "tox" %} + +```console +uvx tox -e docs +``` +{%- elif tasks == "nox" %} + +```console +uv run noxfile.py -s docs +``` +{%- else %} + +```console +uv run --group docs {{ "mkdocs" if docs == "mkdocs" else "zensical" }} build --strict +``` +{%- endif %} +{%- endif %} diff --git a/template/STYLE.md b/template/STYLE.md new file mode 100644 index 0000000..557282d --- /dev/null +++ b/template/STYLE.md @@ -0,0 +1,29 @@ +# Python style guide + +Follow the configured Ruff rules in `pyproject.toml`. This document specifies +the project conventions that complement those rules. + +## Code and documentation + +- Use double quotes for all strings. +- Add type hints to all code. +- Use NumPy-style docstrings only. +- Thoroughly document public classes and methods. +- Private classes, methods, globals, and similar implementation details may + have brief documentation or none when their purpose is clear from context. +- Make errors and warnings concise and informative. Avoid multi-sentence + messages unless a single sentence would sacrifice clarity. + +## Design + +- Prefer legible, concise, minimal code. +- Avoid unnecessary abstractions and large collections of private helpers. +- Inline very short helpers. +- Do not extract simple logic merely because it appears once or twice. Keep + such logic at its call sites when it is likely to need independent changes. + +## Tests + +- Keep test suites DRY and concise. +- Use pytest fixtures, parametrization, and mocks where they make tests more + readable or remove duplication. diff --git a/template/devnotes/example.md b/template/devnotes/example.md new file mode 100644 index 0000000..6b00ad0 --- /dev/null +++ b/template/devnotes/example.md @@ -0,0 +1,17 @@ +# Example development note + +## Goal + +Briefly state the task or investigation. + +## Decisions and findings + +- Record relevant constraints, decisions, and observations as work progresses. + +## Validation + +- List the checks run and their outcomes. + +## Follow-up + +- Note remaining work, risks, or questions for the next contributor. From 57e8ff64ea41c45bfcc80ae00bca09d89dcbd014 Mon Sep 17 00:00:00 2001 From: Szymon Talaga Date: Fri, 21 Aug 2026 21:11:55 +0200 Subject: [PATCH 2/2] Update AGENTS.md.jinja and pyproject.toml.jinja templates --- template/AGENTS.md.jinja | 4 ++-- template/pyproject.toml.jinja | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/template/AGENTS.md.jinja b/template/AGENTS.md.jinja index 49376b1..260f49d 100644 --- a/template/AGENTS.md.jinja +++ b/template/AGENTS.md.jinja @@ -56,8 +56,8 @@ uv run --group test pytest ## Documentation -Documentation lives in `docs/`. Build it with the generated task runner before -submitting documentation changes. +Documentation lives in `docs/`. Build it with the applicable command below +before submitting documentation changes. {%- if tasks == "tox" %} ```console diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index e96a14e..1138b2b 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -140,7 +140,7 @@ lint.per-file-ignores."tests/**" = [ lint.isort.required-imports = [ "from __future__ import annotations", ] -lint.pydocstyle.convention = "google" +lint.pydocstyle.convention = "numpy" lint.future-annotations = true [tool.codespell]