Skip to content

Per-subsystem contributor docs#

Every significant folder has two READMEs:

  • IMPLEMENTATION_README — engineering memory: how it's wired, key symbols, extension points, invariants
  • LEARNING_README — conceptual model: why it exists, mental model, how it connects to the rest

5,400+ lines total across 15 files (8 IMPL + 7 LEARNING). Start with LEARNING, then IMPL when you need to modify.

These are the authoritative contributor docs. Customer-facing pages in ../how-to, ../concepts, etc. link back here for depth.

Seven subsystems#

Core#

Engine layer. Runs the agent loop. Every other subsystem depends on it.

  • ml_team/core/LEARNING_README.md — concepts
  • ml_team/core/IMPLEMENTATION_README.md — implementation
  • Files: agent_runner.py, permissions.py, permission_sources.py, permission_audit.py, hooks.py, shell_hook_runner.py, tool_executor.py, cron.py, cron_tasks.py, batch.py, batch_processors.py, plugin_loader.py, skill_registry.py, commands_registry.py, agents_registry.py, mcp_client.py, conversation_store.py, memory.py, org_memory.py, approval.py, context_compaction.py, evaluator.py, llm_client.py, retention.py, feature_flags.py, rag.py, guardrails.py, feedback.py, evaluation.py, state_graph.py, telemetry.py, orchestrator.py, graph_executor.py, team_factory.py, interfaces.py, types.py, logging_config.py

API#

FastAPI layer over core. Thin by design.

API routers#

17 router modules mounted on app.py.

Backends#

Orchestrator implementations. Swappable via core.interfaces.

Tools#

38 leaf tools. Plain Python functions with @tool decorator.

Config#

Declarative layer — dataclasses (Python) + YAML.

Dashboard#

Next.js 16 UI. TypeScript. App-router.

Tests#

Regression + bench + e2e.

  • ml_team/tests/IMPLEMENTATION_README.md — tests-only (no LEARNING for tests)
  • Structure:
  • test_*.py (30+ files, unit + integration)
  • bench/ — pytest-benchmark suites
  • e2e/ — end-to-end against a live stack

Doc-drift enforcement#

CI workflow .github/workflows/doc-drift.yml requires IMPL + LEARNING updates when code changes in one of these subsystems. 7 subsystems enforced: core, api, api/routers, backends, config, dashboard, tools. (tests/ is excluded — tests are their own docs.)

When you touch code in one of these folders, the CI check expects a corresponding README edit. Either:

  • Actually update the relevant README (preferred)
  • Edit MASTER_README.md at repo root (accepted as a product-level update)
  • Document why a README update isn't applicable in the PR description

Reading order#

Goal Order
Understand the platform MASTER_README → concepts/ here → LEARNING_README per subsystem
Make a targeted fix The relevant subsystem's IMPLEMENTATION_README
Propose an architectural change Read .project/decisions.md first, then draft a new ADR
Write a plugin ../concepts/tools-and-plugins.md → ../how-to/write-custom-tool.md + write-custom-agent.md

Next#