Main

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 applicable command below
+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 %}

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.

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.

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]