Merge AnyIO defaults and inline tensor docs

python-project-defaults/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: python-project-defaults
-description: Apply repo-aligned Python defaults for greenfield modules, scaffolding, CLIs, libraries, and typed implementation work in projects that already use or are explicitly standardizing on uv, click, and comprehensive typing. Do not use for general code review or to migrate existing projects away from their current tooling unless requested.
+description: Apply repo-aligned Python defaults for greenfield modules, scaffolding, CLIs, libraries, async work, and typed implementation work in projects that already use or are explicitly standardizing on uv, anyio, click, comprehensive typing, basedpyright, and beartype. Do not use for general code review or to migrate existing projects away from their current tooling unless requested.
 ---
 
 # Python Project Defaults
@@ -13,16 +13,6 @@ Use this skill to apply the user's preferred Python defaults without turning an
 2. Existing repository conventions and verification workflow
 3. This skill
 
-These are defaults, not mandatory migrations.
-
-Do not switch a repository to `uv`, `click`, or `basedpyright` unless:
-
-- the repository already uses it
-- the task is greenfield or scaffolding
-- the user explicitly asks to standardize on it
-
-Skip this skill for general code review unless the user explicitly wants style-standardization feedback.
-
 ## Before Applying This Skill
 
 Check the local project first:
@@ -30,7 +20,9 @@ Check the local project first:
 - packaging and environment: `pyproject.toml`, `requirements*`, lockfiles, existing env tooling
 - task runner and verification flow: `Makefile`, `justfile`, `tox.ini`, `noxfile.py`, CI commands
 - CLI framework: `click`, `typer`, `argparse`, or no CLI
+- async model: `anyio`, `asyncio`, `trio`, or sync-only code
 - type checker: `basedpyright`, `pyright`, `mypy`, or no configured checker
+- runtime type checking: `beartype` or another established validator
 - data modeling patterns: `TypedDict`, `dataclass`, `pydantic`, `attrs`, ORM models
 
 If the repository already uses an alternative, keep it. Mirror the repo before introducing new tooling.
@@ -67,7 +59,31 @@ def run(config_path: Path) -> None:
     ...
 ```
 
-3. Treat typing as enforcement, not decoration.
+3. Prefer `anyio` for new async work.
+
+- If the repository already uses `anyio`, stay inside its task groups, cancellation scopes, timeout helpers, and streams.
+- If the task is greenfield async work with no established async model, prefer `anyio` over raw `asyncio`.
+- Do not rewrite established `asyncio`, `trio`, or synchronous code solely to match this preference.
+- For async CLIs that use `anyio`, keep a synchronous entrypoint that calls `anyio.run(...)`.
+
+```python
+from pathlib import Path
+
+import anyio
+import click
+
+
+@click.command()
+@click.argument("config_path", type=click.Path(path_type=Path))
+def main(config_path: Path) -> None:
+    anyio.run(run, config_path)
+
+
+async def run(config_path: Path) -> None:
+    ...
+```
+
+4. Treat typing as enforcement, not decoration.
 
 - Annotate public functions, methods, return values, and reusable internal helpers.
 - Use the repository's configured type checker. If the repo has no established checker and the task is greenfield, default to `basedpyright`.
@@ -82,30 +98,28 @@ runner = cast(Runner, registry[name])
 value = vendor_api.load(path)  # type: ignore[call-overload]
 ```
 
-## Verification
+5. Use `beartype` to catch type errors early at stable boundaries.
 
-Use the repository's existing verification workflow first.
+- Prefer `@beartype` on adapters, parsers, deserializers, service boundaries, and test-targeted helpers when the repository already uses it or the task is greenfield.
+- Use it by default when runtime validation will catch bad inputs earlier than static typing alone.
+- Avoid decorating the hottest inner loops unless the runtime cost is acceptable.
+- Only avoid `from __future__ import annotations` in modules that rely on runtime annotation inspection.
 
-Examples:
+```python
+from beartype import beartype
 
-- `make test`
-- `just test`
-- `tox -e py`
-- `nox -s tests`
-- `poetry run pytest`
-- `hatch run test`
-- the project's documented CI wrapper commands
 
-If no local workflow exists and the task is greenfield or already aligned with this stack, use this fallback order:
-
-1. `uv sync --dev`
-2. `uv run basedpyright`
-3. `uv run pytest`
-4. `uv run python -m <package_or_module>` or a CLI smoke test when relevant
+@beartype
+def parse_port(value: str) -> int:
+    return int(value)
+```
 
 ## Anti-Goals
 
 - Do not change a repository's package manager or lockfile format unless asked.
+- Do not replace an existing async model with `anyio` unless asked.
 - Do not replace an existing CLI framework with `click` unless asked.
+- Do not add `beartype` to hot paths blindly without considering cost.
 - Do not let style preferences override correctness, bug fixing, or the user's explicit task.
 - Do not treat this skill as a mandate to rewrite working code that already matches local conventions.
+