src/agent_optimizer/ contains the importable Python package and CLI entrypoint. Core areas are split by responsibility: contracts/ defines shared payload types, control_plane/ coordinates planning and review, control_plane/planning_engine/ compiles instructions into SPEC DAGs, data_plane/ handles runtime execution artifacts, and feedback/ stores audit and memory logic. benchmarks/, web/, and code_agent/ are formal subsystems under the package. tests/ contains pytest coverage, with optimizer-specific tests under tests/planning_engine/ and fixtures in tests/fixtures/. Design notes and reference material live in docs/; binary assets are under docs/assets/.
python -m pip install -e ".[dev]"installs the package in editable mode with pytest.python -m pytest -qruns the full local test suite.python -m pytest -m "not integration" -qskips live API integration tests.DEEPSEEK_API_KEY=... python -m pytest -m integration -qruns DeepSeek-backed tests.agent-optimizer plan --instruction "Build a runnable simulated plan."exercises the installed CLI.python -m agent_optimizer --helpruns the CLI from the source tree.
When a user explicitly authorizes subagents, prefer a coordinator workflow: split the work into clear, non-overlapping subtasks, delegate independent implementation or exploration to subagents, and keep the main agent focused on task boundaries, coordination, and final acceptance checks. Give each subagent a concise responsibility, file or module ownership when code changes are involved, and a required final report containing changed files, implementation summary, tests run, and remaining risks or blockers.
The main agent should avoid redoing delegated work unless integration or safety requires it. Review returned summaries, touched files, and test results at a practical level, then integrate findings and report only the high-signal outcome to the user. Keep tightly coupled or immediate critical-path work local when delegation would slow progress or create avoidable merge conflicts.
Use Python 3.11+ idioms, 4-space indentation, type hints, and from __future__ import annotations as shown in existing modules. Prefer dataclasses for structured models and to_dict() helpers for JSON-serializable outputs. Use snake_case for modules, functions, and variables; PascalCase for classes. No formatter or linter is configured in pyproject.toml, so match nearby style and keep modules focused.
The project uses pytest with tests as the configured test path and src on PYTHONPATH. Name files test_<area>.py and tests test_<behavior>(). Add focused unit tests near the code being changed, and use @pytest.mark.integration only for tests that require live DeepSeek credentials. There is no configured coverage threshold; prioritize behavior around planning, contracts, runtime artifacts, and error paths.
Recent history uses short, imperative subjects such as Add Lachesis README logo and Refactor runtime architecture boundaries. Keep commits scoped and avoid bundling generated runtime files. Pull requests should explain behavior changes, list test commands run, mention required environment variables, and include sample CLI output or payload changes when planner reports or contracts change.
Do not commit API keys, local runtime directories, caches, virtual environments, or generated reports. Configure DeepSeek integration with DEEPSEEK_API_KEY; optional overrides are DEEPSEEK_BASE_URL and DEEPSEEK_MODEL.