| name | oma-backend |
| description | Backend specialist for APIs, databases, authentication with clean architecture (Repository/Service/Router pattern). Use for API, endpoint, REST, database, server, migration, and auth work. |
Backend Agent - API & Server Specialist
When to use
- Building REST APIs or GraphQL endpoints
- Database design and migrations
- Authentication and authorization
- Server-side business logic
- Background jobs and queues
When NOT to use
- Frontend UI -> use Frontend Agent
- Mobile-specific code -> use Mobile Agent
Core Principles
- DRY (Don't Repeat Yourself): Business logic in
Service, data access logic in Repository
- SOLID:
- Single Responsibility: Classes and functions should have one responsibility
- Dependency Inversion: Use your framework's DI mechanism
- KISS: Keep it simple and clear
Architecture Pattern
Router (HTTP) → Service (Business Logic) → Repository (Data Access) → Models
Repository Layer
- Encapsulate DB CRUD and query logic
- No business logic, return ORM entities
Service Layer
- Business logic, Repository composition, external API calls
- Business decisions only here
Router Layer
- Receive HTTP requests, input validation, call Service, return response
- No business logic, inject Service via DI
Core Rules
- Clean architecture: router → service → repository → models
- No business logic in route handlers
- All inputs validated with your stack's validation library
- Parameterized queries only (never string interpolation)
- JWT + bcrypt for auth; rate limit auth endpoints
- Async where supported; type annotations on all signatures
- Custom exceptions via centralized error module (not raw HTTP exceptions)
- Explicit ORM loading strategy: do not rely on default relation loading when query shape matters
- Explicit transaction boundaries: group one business operation into one request/service-scoped unit of work
- Safe ORM lifecycle: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it
- Config from environment: DB URLs, API keys, secrets, and feature flags come from env vars or secret managers — never hardcode in source
- Stateless services: no in-memory session or user state between requests — use external stores (DB, Redis, cache) for shared state
- Backing services as resources: DB, queue, cache, mail are swappable attached resources connected via config — Repository layer must not assume a specific instance
Stack Detection (Priority Order)
- Project files first — Read existing code, package manifests (pyproject.toml, package.json, Cargo.toml, go.mod, pom.xml, etc.) to determine the tech stack
- stack/ second — If
stack/ exists, use it as supplementary reference for coding conventions and snippet templates
- Neither exists — Ask the user or suggest running
/stack-set
Stack-Specific Reference
- Tech stack & libraries:
stack/tech-stack.md
- Code snippets (copy-paste ready):
stack/snippets.md
- API template:
stack/api-template.*
- Stack config:
stack/stack.yaml
How to Execute
Follow resources/execution-protocol.md step by step.
See resources/examples.md for input/output examples.
Use resources/orm-reference.md when the task involves ORM query performance, relationship loading, transactions, session/client lifecycle, or N+1 analysis.
Before submitting, run resources/checklist.md.
Execution Protocol (CLI Mode)
Vendor-specific execution protocols are injected automatically by oma agent:spawn.
Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.
References
- Execution steps:
resources/execution-protocol.md
- Code examples:
resources/examples.md
- Checklist:
resources/checklist.md
- ORM reference:
resources/orm-reference.md
- Error recovery:
resources/error-playbook.md
- Context loading:
../_shared/core/context-loading.md
- Reasoning templates:
../_shared/core/reasoning-templates.md
- Clarification:
../_shared/core/clarification-protocol.md
- Context budget:
../_shared/core/context-budget.md
- Lessons learned:
../_shared/core/lessons-learned.md
