Add agents context files

.agents/skills/create-pr/SKILL.md

@@ -0,0 +1,8 @@
+---
+  name: create-pr
+  description: Create a Pull Request.
+---
+# Create a Pull Request
+
+On creating any pull request do the following:
+- **PR body**: Start the PR body with a standalone line 'Generated by <name>.' followed by a single blank line. Replace the <name> placeholder with your colloquial name.

.agents/skills/dependencies-management/SKILL.md

@@ -0,0 +1,158 @@
+---
+  name: dependencies-management
+  description: instructions for updating and managing project dependencies (including Github actions and pre-commit hooks).
+---
+# Dependencies Management
+
+## Update Dependencies
+
+Instructions to update project dependencies (including Github actions and pre-commit hooks).
+
+### 1. Prepare the branch
+
+Create a new branch (following the naming convention in @AGENTS.md).
+
+### 2. Update the lock file and environment
+
+```bash
+uv self update
+```
+
+**IMPORTANT: updating `uv` MUST NOT be skipped.** If the above command fails (e.g. due to a GitHub API rate limit), install the latest `uv` via an alternative method before proceeding:
+
+```bash
+pip install --upgrade uv  # fallback if uv self update fails
+```
+
+Once `uv` is up to date, run:
+
+```bash
+uv lock --upgrade  # update the lock file
+uv export --format requirements-txt --no-emit-project --no-hashes --no-dev -o requirements.txt  # sync @requirements.txt with @uv.lock
+uv sync --inexact  # update environment to match @uv.lock
+```
+
+### 3. Update GitHub Actions versions
+
+For each `uses: <owner>/<repo>@<version>` entry across all files in @.github/workflows/, retrieve the latest release tag by fetching the releases page with WebFetch:
+
+```
+url:    https://github.com/<owner>/<repo>/releases/latest
+prompt: What is the latest release tag for this GitHub action?
+```
+
+In each case update the version pin to any more recent release. **Preserve the existing pinning style**, so if the current pin is a specific version such as `@v3.0.1`, update to the full latest version string, whilst if it's a major-version tag such as `@v4`, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).
+
+### 4. Update pre-commit hook versions
+
+For each `repo:` entry in @.pre-commit-config.yaml, retrieve the latest release tag by fetching the releases page with WebFetch:
+
+```
+url:    https://github.com/<owner>/<repo>/releases/latest
+prompt: What is the latest release tag for this pre-commit hook?
+```
+
+In each case update the `rev:` pin to any more recent release. **Preserve the existing pinning style**, so if the current pin is a specific version such as `v6.0.0`, update to the full latest version string, whilst if it's a major-version tag such as `@v4`, update to any new major-version tag (if the project no longer publishes a major-version tag then switch to the full semver).
+
+### 5. Test
+
+Run the test suite:
+```bash
+uv run pytest -v
+```
+
+**Interpret local test results:**
+- All tests pass and no raised warning is fixable (see *Fixable warnings* section below) → go to step 7 to raise PR.
+- Any test failure or a fixable warning raised → proceed to step 6 to fix.
+
+### 6. Fix
+Any failing tests and fixable warnings will likely have their origin in changes to the dependencies. To provide support for the latest dependencies MAKE REVISIONS to the code base to fix:
+- code causing tests to fail.
+- all fixable warnings (see *Fixable warnings* section below).
+
+As a general RULE, **change the package code to get the tests passing, not the test code!** You may make changes to the test code only with good reason and only when this does not impair the test's efficacy.
+
+To facilitate identifying the cause of test failures consider researching the changelogs of updated dependencies for versions released since the previously locked version.
+
+Iterate on this process until:
+- all tests are passing.
+- all fixable warnings have been fixed.
+
+IMPORTANT: in this step you should not run the full test suite, rather validate fixes by re-running only the previously failing tests. Example to run a specific test:
+
+```bash
+pytest tests/test_module.py::test_name
+```
+
+### 7. Raise PR
+
+Once local tests pass, commit all changes to the branch and raise a PR.
+
+- **PR title**: Title the PR as `Update Dependencies <MM> <DD> (auto)` where:
+  - `<MM>` should be replaced with the first three letters of the current month, the first of which should be capitalized.
+  - `<DD>` should be replaced with the current day of the month as represented by two digits.
+  Example title: `Update Dependencies Apr 07 (auto)`
+- **label**: Add the 'dependencies' label to the PR.
+- otherwise comply with the package's 'create-pr' skill.
+
+### 8. Subscribe to PR activity
+
+By raising the PR a GitHub CI workflow will be triggered. Subscribe to the raised PR's activity.
+
+Proceed to step 9 when you receive an event indicating that the triggered workflow has completed.
+
+### 9. Inspect CI results
+
+The CI workflow will have run the full test suite against a matrix of OS and Python versions. Use `mcp__github__pull_request_read` with the `get_check_runs` method to read check statuses for all matrix jobs.
+
+**Interpret CI test results:**
+- All checks green → proceed to step 12.
+- Any check red → proceed to step 10.
+
+### 10. Fix tests for specific OS/Python configuration
+
+Use the information read from `get_check_runs` to identify any OS/python version configurations for which the test suite has failed.
+
+If the tests failed on specific matrix combinations (e.g. Windows / Python 3.10) then simulate a local matching environment.
+- If necessary use a Docker container with the target OS. (To specify different Python versions you will be able to run commands with `uv run` and pass the --python option.)
+- create a new branch against the repository's master branch.
+- update the `uv` package with `uv self update`.
+- overwrite `uv.lock` with the version previously created by step 2.
+- synchronise the environment by running `uv sync`.
+
+Run the test suite to identify failing tests. For example:
+
+```bash
+uv run --isolated --python 3.12 python pytest --ignore=tests/test_yahoo.py -v
+```
+
+Then find fixes for the failing tests by following step 6.
+
+Finally commit the necessary changes to your *original* branch (to which previous commits were made). This will trigger the CI on the PR re-run. Return to step 9 (inspect CI results).
+
+### 11. Fallback: raise an issue
+
+ONLY if any test failures cannot be resolved, raise an issue that references the PR and details:
+- the failing tests
+- any fixes already attempted
+- any suggested next steps.
+
+### 12. Tidy up
+
+Perform the following 'tidy up' actions:
+- Call `mcp__github__unsubscribe_pr_activity` to unscubscribe from the PR activity.
+- Review and if necessary update the PR body to reflect the final circumstances.
+
+---
+
+**Fixable warnings**
+The following warnings are considered UNFIXABLE and you should not attempt to fix them.
+- warnings that have their origin in a dependency's code.
+
+All other warnings are considered fixable.
+
+## Adding dependencies
+```bash
+# Add a dependency
+uv add <package>
+```

.agents/skills/update-agents-md/SKILL.md

@@ -0,0 +1,21 @@
+---
+  name: update-agents-md
+  description: Instructions for updating @AGENT.md file, including: updating the 'Repository Layout' section following the adding or removal of files or folders; updating the 'Technology Stack' section on changes to the pinned python version as defined in @.python-version.
+---
+# Update agents.md file
+
+## Repository Layout
+Update the 'Repository Layout' section to reflect the current layout. Remove all files and folders that are no longer present and add all new files and folders with the following IMPORTANT EXCEPTIONS:
+- exclude all files and folders ignored by @.gitignore
+- do not include the following files or folders:
+    - @.gitignore
+    - @.git
+    - all files named `__init__.py`
+List all folders before any files for any given hierarchal level.
+If the purpose of a file or directory is not reasonably evident from its name then include a minimalist comment offering a top-line explanation.
+The comment should:
+- be placed alongside the file/directory name
+- not cause the length of the full line (including folder/directory name and all whitespace) to exceed 100 characters.
+
+## Pinned Python version
+Update, if necessary, the 'python' field of the 'Technology Stack' table so that it indicates the pinned python version as defined in @.python-version.

AGENTS.md

@@ -0,0 +1,198 @@
+# LLM Assistant Guide for `valimp` package
+This file provides context for LLM assistants (Claude Code and similar tools) working in this repository.
+
+In all context files, a '@' prefixing a path indicates that the path is defined relative to the project root in which this `AGENTS.md` file is located.
+
+## Skills
+
+Identify all available skills in the @.agents\skills directory
+
+## LLM context
+
+Add the 'agents' label to any PR that amends:
+- this @AGENT.md
+- any SKILL.md file
+
+## Project Overview
+
+**valimp** is a Python library that provides for using type annotations to validate, parse and coerce inputs to public functions.
+
+See @pyproject.toml for project metadata and dependencies.
+
+### Repository Layout
+
+```
+TODO
+```
+
+## Technology Stack
+
+| Category | Tools |
+|---|---|
+| Python | 3.9–3.13 (`.python-version` pins 3.9) |
+| Package manager | `uv` |
+| Build backend | `setuptools` + `setuptools_scm` |
+| Testing | `pytest` |
+| Linting/formatting | `ruff` |
+| Type checking | `mypy` |
+| Git hooks | `pre-commit` |
+
+The current project version is managed by `setuptools_scm` and written to `src/valimp/_version.py`.
+IMPORTANT: `src/valimp/_version.py` is auto-generated and you should not edit it.
+
+## Development Workflows
+
+### Setup
+
+```bash
+# Install dependencies using uv
+uv sync
+
+# Install pre-commit hooks
+pre-commit install
+```
+
+### Testing
+
+- test with `pytest`
+- see @pytest.ini for configuration; options are applied automatically via `addopts`.
+- shared fixtures are in @tests/conftest.py
+- tests are in @tests/
+- doctests are included to some methods/functions
+
+Commands to run tests:
+```bash
+# All tests (including doctests under src/market_analy/)
+pytest
+
+# Tests in specific file
+pytest tests/test_module.py
+
+# Specific test
+pytest tests/test_module.py::test_name
+
+# With verbose output
+pytest -v
+```
+
+### Pre-commit Hooks
+
+See @.pre-commit-config.yaml for pre-commit implementation.
+
+Pre-commit runs automatically on `git commit`.
+
+To run manually:
+```bash
+pre-commit run --all-files
+```
+
+---
+
+### Continuous Integration
+
+GitHub Actions is used for CI. Defined workflows include:
+- @.github/workflows/build-test.yml - runs full test suite on matrix of platforms and python versions.
+- @.github/workflows/release.yml - releases a new version to PyPI.
+
+## Code Conventions
+
+### Architecture
+
+The source code consists of the single file @src/valimp/valimp.py which employs a functional architecture.
+
+### Formatting
+
+- format to `ruff` (Black compatible).  
+- see @ruff.toml for configuration.
+
+```bash
+# Format code
+ruff format .
+```
+
+### Linting
+
+- lint with `ruff`.
+- See lint sections of @ruff.toml for configuration (includes excluded files).
+- type check with `mypy`.
+
+```bash
+# Check lint issues
+ruff check .
+
+# Type checking
+uv run mypy src/valimp/
+```
+
+### Imports
+
+- No wildcard imports (i.e. no `from x import *`).
+
+### Type Annotations
+
+- Type annotations are required on all public functions and methods.
+- See @mypy.ini for configuration
+    - `ignore_missing_imports = True` is set globally (many dependencies lack stubs).
+
+### Docstrings
+
+Public modules, classes, and functions MUST all have docstrings.
+
+Docstrings should follow **NumPy convention**. Familiarise yourself with this as described at https://numpydoc.readthedocs.io/en/latest/format.html. That said, the following should always be adhered to and allowed to override any NumPy convention:
+- 75 character line limit for public documentation
+- 88 character line limit for private documentation
+- formatted to ruff
+- parameter types should not be included to the docstring unless this provides useful information that users could not otherwise ascertain from the typed function signature.
+- default values should only be noted in function/module docstrings if not defined in the signature - for example if the parameter's default value is None and when received as None the default takes a concrete dynamically evaluated default value. When a default value is included to the parameter documentation it should be defined after a comma at the end of the parameter description, for example:
+    - description of parameter 'whatever', defaults to 0.
+- **subclasses** documentation should:
+    - list only methods and attributes added by the subclass. A note should be included referring users to documentation of base classes for the methods and attributes defined there.
+    - include a NOTES section documenting how to implement the subclass (only if not trivial).
+- documentation of **subclass methods that extend methods of a base class** should only include any parameters added by the extension. With respect to undocumented parameters a note should be included to refer the user to the corresponding 'super' method(s)' documentation on the corresponding base class or classes.
+- **documentation of exceptions and warnings** should be limited to only **unusual** exceptions and warnings that are raised directly by the function/method itself or by any private function/method that is called directly or indirectly by the function/method.
+- summary line should be in the imperative mood only when sensical to do so.
+- magic methods do not require documentation if their functionality is fully implied by the method name.
+- unit tests do not require docstrings.
+
+Example documentation:
+```python
+def my_func(param1: int, param2: str = "default", param3: None | str = None) -> bool:
+    """Short summary line.
+
+    Extended description if needed.
+
+    Parameters
+    ----------
+    param1
+        Description of param1.
+    param2
+        Description of param2.
+    param3
+        Description of param3, defaults to value of `param2`.
+
+    Returns
+    -------
+    bool
+        Description of return value.
+    """
+```
+
+### Comments
+
+- pay particular attention to comments starting with...: 
+    - 'NOTE'
+    - 'TODO'
+    - 'AIDEV-NOTE' - these comments are specifically addressed to you.
+    - 'AIDEV-TODO' - these comments are specifically requesting you do something.
+    - 'AIDEV-QUESTION' - these comments are asking a question for specifically you to answer.
+
+---
+
+## Important Notes for AI Agents
+
+1. **NEVER DO RULES**:
+	- Never edit the file `src/valimp/_version.py` - this is auto-generated by the build process.
+
+2. **NumPy docstring style** — all new public functions/classes must use NumPy-convention docstrings and rules as defined under Docstrings section of this @AGENTS.md file.
+
+3. **Branch naming** — git branches should follow the pattern `<llm_name>/<description>` where the `<llm_name>` placeholder should be replaced with your colloquial name.