ai(rules[AGENTS]) Port asyncio/doctest guidelines from libvcs

why: Prepare for asyncio development with consistent patterns
what:
- Add critical doctest rules (executable tests, no SKIP workarounds)
- Add async doctest pattern with asyncio.run()
- Add Asyncio Development section with subprocess patterns
- Add async API conventions, testing patterns, and anti-patterns

Author: tony

AGENTS.md

@@ -225,6 +225,45 @@ type
 
 ### Doctest Guidelines
 
+**All functions and methods MUST have working doctests.** Doctests serve as both documentation and tests.
+
+**CRITICAL RULES:**
+- Doctests MUST actually execute - never comment out `asyncio.run()` or similar calls
+- Doctests MUST NOT be converted to `.. code-block::` as a workaround (code-blocks don't run)
+- If you cannot create a working doctest, **STOP and ask for help**
+
+**Available tools for doctests:**
+- `doctest_namespace` fixtures: `tmp_path`, `asyncio`
+- Ellipsis for variable output: `# doctest: +ELLIPSIS`
+- Update `conftest.py` to add new fixtures to `doctest_namespace`
+
+**`# doctest: +SKIP` is NOT permitted** - it's just another workaround that doesn't test anything. Use the fixtures properly.
+
+**Async doctest pattern:**
+```python
+>>> async def example():
+...     result = await some_async_function()
+...     return result
+>>> asyncio.run(example())
+'expected output'
+```
+
+**Using fixtures in doctests:**
+```python
+>>> from pathlib import Path
+>>> doc_path = tmp_path / "example.rst"  # tmp_path from doctest_namespace
+>>> doc_path.write_text(">>> 1 + 1\\n2")
+...
+```
+
+**When output varies, use ellipsis:**
+```python
+>>> import doctest_docutils
+>>> doctest_docutils.__file__  # doctest: +ELLIPSIS
+'.../doctest_docutils.py'
+```
+
+**Additional guidelines:**
 1. **Use narrative descriptions** for test sections rather than inline comments
 2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py`
 3. **Keep doctests simple and focused** on demonstrating usage
@@ -290,6 +329,119 @@ When stuck in debugging loops:
 3. **Document the issue** comprehensively for a fresh approach
 4. **Format for portability** (using quadruple backticks)
 
+## Asyncio Development
+
+### Async Subprocess Patterns
+
+**Always use `communicate()` for subprocess I/O:**
+```python
+proc = await asyncio.create_subprocess_shell(...)
+stdout, stderr = await proc.communicate()  # Prevents deadlocks
+```
+
+**Use `asyncio.timeout()` for timeouts:**
+```python
+async with asyncio.timeout(300):
+    stdout, stderr = await proc.communicate()
+```
+
+**Handle BrokenPipeError gracefully:**
+```python
+try:
+    proc.stdin.write(data)
+    await proc.stdin.drain()
+except BrokenPipeError:
+    pass  # Process already exited - expected behavior
+```
+
+### Async API Conventions
+
+- **Class naming**: Use `Async` prefix: `AsyncDocTestRunner`
+- **Callbacks**: Async APIs accept only async callbacks (no union types)
+- **Shared logic**: Extract argument-building to sync functions, share with async
+
+```python
+# Shared argument building (sync)
+def build_test_args(verbose: bool = False) -> dict[str, t.Any]:
+    args = {"verbose": verbose}
+    return args
+
+# Async method uses shared logic
+async def run_tests(self, verbose: bool = False) -> TestResults:
+    args = build_test_args(verbose)
+    return await self._run(**args)
+```
+
+### Async Testing
+
+**pytest configuration:**
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
+```
+
+**Async fixture pattern:**
+```python
+@pytest_asyncio.fixture(loop_scope="function")
+async def async_doc_runner(tmp_path: Path) -> t.AsyncGenerator[AsyncDocTestRunner, None]:
+    runner = AsyncDocTestRunner(path=tmp_path)
+    yield runner
+```
+
+**Parametrized async tests:**
+```python
+class DocTestFixture(t.NamedTuple):
+    test_id: str
+    doc_content: str
+    expected: list[str]
+
+DOC_FIXTURES = [
+    DocTestFixture("basic", ">>> 1 + 1\n2", ["pass"]),
+    DocTestFixture("failure", ">>> 1 + 1\n3", ["fail"]),
+]
+
+@pytest.mark.parametrize(
+    list(DocTestFixture._fields),
+    DOC_FIXTURES,
+    ids=[f.test_id for f in DOC_FIXTURES],
+)
+@pytest.mark.asyncio
+async def test_doctest(test_id: str, doc_content: str, expected: list) -> None:
+    ...
+```
+
+### Async Anti-Patterns
+
+**DON'T poll returncode:**
+```python
+# WRONG
+while proc.returncode is None:
+    await asyncio.sleep(0.1)
+
+# RIGHT
+await proc.wait()
+```
+
+**DON'T mix blocking calls in async code:**
+```python
+# WRONG
+async def bad():
+    subprocess.run(["python", "-m", "doctest", file])  # Blocks event loop!
+
+# RIGHT
+async def good():
+    proc = await asyncio.create_subprocess_shell(...)
+    await proc.wait()
+```
+
+**DON'T close the event loop in tests:**
+```python
+# WRONG - breaks pytest-asyncio cleanup
+loop = asyncio.get_running_loop()
+loop.close()
+```
+
 ## Sphinx/Docutils-Specific Considerations
 
 ### Directive Registration