agents md per service

md

# <service-name>

<One or two sentences: what this service owns and why it exists.>

## Stack

- Language/runtime: <e.g. Node 20 / Go 1.22 / Python 3.12>
- Framework: <e.g. Express, FastAPI, gRPC>
- Datastore: <e.g. Postgres via Prisma>
- Messaging: <e.g. Kafka, topic prefix `orders.*`>

## Build & test

- Install: `<command>`
- Run locally: `<command>`
- Unit tests: `<command>`
- Integration tests: `<command>`
- Lint / format: `<command>`

Always run tests before opening a PR. Don't report a task as done if tests are failing.

## Code layout

- `<src/routes/>` — entry points / API handlers
- `<src/db/>` — data access; no raw queries outside this directory
- `<src/events/>` — published and consumed event handlers
- <list the directories that actually matter here; delete the rest>

## Conventions

- <e.g. Conventional commits: `feat:`, `fix:`, `chore:`>
- <e.g. Any new or changed endpoint needs its OpenAPI spec updated in the same PR>
- <e.g. Feature flags via LaunchDarkly — never hardcode a rollout>

## This service in the larger system

This repo is one of 20+ services. It does not hold the full picture of any
cross-service feature on its own — `catalog-info.yaml` (this repo, root) is
the entry point for what this service exposes and depends on, and the
aggregated org service catalog is ground truth for who consumes what.

**Before changing a contract** — a field, an event shape, a status code —
check `catalog-info.yaml` for every service listed as a consumer downstream.
Default to additive changes (new fields optional, deprecate before removing)
unless a human has explicitly signed off on a breaking change.

## Deploy

- Pipeline: `<.github/workflows/deploy.yml>`
- Environments: `<e.g. staging → production>`
- Rollback: `<command or process>`

## Do not touch

- `<auto-generated files, legacy code, or anything owned by another team>`

## Org-wide conventions

<!-- org-conventions:start (synced from org/platform-conventions — edit there, not here) -->
<!-- org-conventions:end -->