Adding A New Task Or Service

August 31, 2026 · View on GitHub

This page is the map, not the full instructions — the authoritative, up-to-date steps live in the root AGENTS.md, which both human contributors and coding agents follow. Read the relevant section there before starting; this page just tells you which section to read and where it fits relative to everything else in docs/developer/.

Before You Start

  1. Follow Local Development so make lint-check, make mypy, and make test pass on a clean tree. Then read AGENTS.md for the services -> tasks -> core dependency direction, script/image discovery, and code conventions.
  2. Read Architecture: Services Overview and Architecture: Artifact Contract so you know where a new stage fits in the stage order and what it's allowed to read or write in a scene.
  3. If you're adding VLM/LLM behavior, also read Architecture: Model Client Architecture.

Adding A Task Package

Task packages hold reusable annotation behavior and depend only on core. Follow "Adding a New Task" in AGENTS.md: duplicate packages/tasks/example_task/, keep the same structure and README shape as that template, register it by running make sync (the workspace glob picks it up automatically — no manual registration step).

Adding A Service

Services package a task (or several) as a CLI and container. Follow "Adding a New Service" in AGENTS.md: duplicate services/example_service/, register its entrypoint under [project.scripts] so it's discoverable from make run, and register its image under [tool.build.images] so it's discoverable from make build.

Once your service exists, add its own step-by-step page under docs/user-guide/services/ following the existing pages there (what it does, prerequisites, numbered run steps, verify, troubleshoot) so operators can find and run it the same way they find every other service.

  • Local Development — contributor checks, templates, and image registration
  • AGENTS.md — code conventions, testing, CI/CD, and the full command reference (make lint, make mypy, make test, make check)
  • skills/ — task-shaped agent guidance, including workflow-stage-integration for implementing or reviewing a single new stage or service end to end
  • Package And Service Index — every existing task/service README, for finding a close analog to model yours on