chore: update agents.md

Author: phi-friday

.agents/skills/socketio-stub-updater/SKILL.md

@@ -98,6 +98,23 @@ git diff <OLD_TAG>..<NEW_TAG> -- 'src/socketio/*.py' | grep -E '^\+.*def |^\-.*d
 
 For each identified change, update the corresponding `.pyi` file:
 
+### Generic Type Parameters
+
+This repository targets Python 3.12+. Prefer PEP 695 syntax for generic stubs instead of adding direct `TypeVar` or `ParamSpec` declarations:
+
+```python
+from collections.abc import Callable
+
+class Result[T]:
+    def unwrap(self) -> T: ...
+
+def decorator[**P, T](func: Callable[P, T]) -> Callable[P, T]: ...
+```
+
+Use direct `TypeVar`/`ParamSpec` only when required by syntax limitations. In particular, keep direct `TypeVar(..., default=...)` for type parameter defaults because default values in type parameter syntax require Python 3.13+.
+
+Name PEP 695 parameters without leading underscores (`T`, `P`). If a direct `TypeVar`/`ParamSpec` is required, use underscored variables such as `_T` or `_P`.
+
 ### Adding New Function
 
 ```python

.agents/skills/socketio-stub-updater/references/REFERENCE.md

@@ -67,28 +67,37 @@ def process(data: str | bytes | list[int]) -> str | bytes | list[int]: ...
 
 ### Generic Types
 
-```python
-from typing import TypeVar, Generic
-from collections.abc import Callable, Iterator
+Prefer Python 3.12 type parameter syntax for generic stubs:
 
-T = TypeVar("T")
-T_co = TypeVar("T_co", covariant=True)
+```python
+from collections.abc import Callable
 
-class Container(Generic[T]):
+class Container[T]:
     def get(self) -> T: ...
     def set(self, value: T) -> None: ...
 
 # Callable types
 def apply(func: Callable[[int, str], bool], x: int, y: str) -> bool: ...
 
-# With ParamSpec for decorators
-from typing import ParamSpec, Concatenate
+# Decorators can use ParamSpec syntax without a direct ParamSpec declaration
+def decorator[**P, T](func: Callable[P, T]) -> Callable[P, T]: ...
+```
 
-P = ParamSpec("P")
+Use direct `TypeVar`/`ParamSpec` only when the 3.12 type parameter syntax cannot express the type. The most common required case in this repository is `default=`, because type parameter defaults are only syntax-supported in Python 3.13+:
 
-def decorator(func: Callable[P, T]) -> Callable[P, T]: ...
+```python
+from typing import Generic, Literal
+from typing_extensions import TypeVar
+
+_IsAsyncio = TypeVar("_IsAsyncio", bound=bool, default=Literal[False])
+
+class BaseNamespace(Generic[_IsAsyncio]): ...
 ```
 
+Naming convention:
+- PEP 695 syntax: use `T`, `P` (not `_T`, `_P`)
+- Direct `TypeVar`/`ParamSpec`: use `_T`, `_P`
+
 ## Module Organization
 
 ### `__init__.pyi` Pattern
@@ -276,8 +285,10 @@ from typing import (
     overload,
 )
 
-# Use typing_extensions for ParamSpec, TypeVar (for compatibility)
-from typing_extensions import ParamSpec, TypeVar
+# Prefer Python 3.12 type parameter syntax for generics.
+# Import TypeVar/ParamSpec from typing_extensions only when direct declarations
+# are required, such as TypeVar(..., default=...).
+from typing_extensions import TypeVar
 
 # Absolute imports from socketio modules
 from socketio._types import CustomType  # Internal types
@@ -292,7 +303,6 @@ from typing import Any, overload
 from socketio._types import HandlerType, Namespace
 from socketio.base_server import BaseServer
 ```
-```
 
 ## Deprecation Handling
 

AGENTS.md

@@ -32,6 +32,35 @@ src/
 3. Use `as` syntax for re-exports: `from mod import X as X`
 4. Define internal types in `_types.pyi`
 5. Avoid `Incomplete` - use concrete types
+6. Prefer Python 3.12 type parameter syntax over direct `TypeVar`/`ParamSpec` declarations unless direct declarations are required
+
+### Generic Type Parameters
+
+This repository targets Python 3.12+. Prefer PEP 695 type parameter syntax for new generic stubs:
+
+```python
+from collections.abc import Callable
+
+class Box[T]:
+    def get(self) -> T: ...
+
+def decorator[**P, T](func: Callable[P, T]) -> Callable[P, T]: ...
+```
+
+Use direct `TypeVar`/`ParamSpec` only when the 3.12 syntax cannot express the type. The main required case is a type parameter default, because default values for type parameters are only supported by syntax in Python 3.13+:
+
+```python
+from typing import Generic, Literal
+from typing_extensions import TypeVar
+
+_IsAsyncio = TypeVar("_IsAsyncio", bound=bool, default=Literal[False])
+
+class BaseNamespace(Generic[_IsAsyncio]): ...
+```
+
+Naming convention:
+- PEP 695 syntax: use non-underscored names (`T`, `P`), not `_T`/`_P`
+- Direct `TypeVar`/`ParamSpec`: keep underscored variables (`_T`, `_P`)
 
 **⚠️ Updating Stubs**: For stub updates or new module additions, use the `socketio-stub-updater` skill located in `.agents/skills/socketio-stub-updater/SKILL.md`