lda-wf/AGENTS.md

Agent Guide

Runtime And Syntax

• Python baseline is 3.14 (requires-python = ">=3.14").
• Python 3.14 syntax is allowed. Do not rewrite valid new syntax just because it looks unusual.
• Example: Parentheses-Free Exceptions (PEP 758).

Code Organization

• Prefer focused packages/modules over large flat files when adding new areas.
• Preserve current package boundaries. If unsure, check docs/project_map.md and docs/source_architecture.md.
• Put related files in folders from the start when the area is likely to grow. Example: prefer src/pack/foo/bar.py over adding many unrelated src/pack/foo_bar.py files.
• Do not add compatibility treatment for unused things. Compatibility is for real callers, real persisted data, or documented external contracts. If a symbol/format has no production callers and no real stored data, prefer removing or migrating it cleanly over preserving ghost behavior.

Tests

• Prefer pytest tmp_path for test-local filesystem state.
• Avoid fixed paths under local_temp_root() unless the test explicitly needs cross-process persistence and cleans up after itself.
• Prefer async def test_x() with pytest-asyncio over def test_x(): async def scenario(): ...; asyncio.run(scenario()).
• Prefer field-level assertions like actual["field"] == expected["field"] over whole-object equality unless extra fields are intentionally forbidden.
• Scope test runs. This repo is large; broad test commands can be slow.

Verification Commands

uv run pytest -q
uv run ruff check
uv run ruff format
uv run basedpyright --level error

Use uv run --env-file .env pytest -q when live MCP-backed tests need local environment configuration.

Docs

• Before editing docs, read docs/AGENTS.md.
• docs/current_roadmap.md is the live roadmap.
• If docs mention a partial implementation, add a short comment or docstring at the code seam too. Future agents see code before they see old plans.

Comments And Docstrings

• Add comments/docstrings around weird or non-obvious logic.
• Add docstrings explaining compound return types that otherwise say little, for example tuple[list[str], Any].
• Polish common helper docs if you keep using the helper.

Skills And Tools

• Skills can be useful but can overstate urgency. Use judgment.
• Serena is useful for symbol discovery and rename-like navigation. Prefer built-in edit tools for ordinary file edits.
• If an MCP tool is irrelevant to the project or clutters available tools, mention it so it can be disabled.