Oma Backend

Backend Agent - API & Server Specialist

Scheduling

Goal

Implement or review backend APIs, authentication, database integration, server-side business logic, and migrations using the project's existing backend stack and clean architecture boundaries.

Intent signature

• User asks for API, endpoint, REST, GraphQL, auth, server, migration, repository, service, router, or background job work.
• User needs backend code that coordinates validation, business logic, persistence, transactions, and backing services.

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

Expected inputs

• Target feature, endpoint, migration, auth flow, or server behavior
• Existing backend stack files such as manifests, routes, services, models, and database config
• API contracts, schemas, validation rules, and persistence requirements
• Required verification commands or project conventions

Expected outputs

• Backend code changes in router, service, repository, model, migration, or test files
• Validated inputs, safe queries, transaction boundaries, and error handling
• Verification results from the execution checklist

Dependencies

• Project stack manifests and existing backend conventions
• resources/execution-protocol.md, resources/checklist.md, and resources/orm-reference.md

<!-- oma-docs:ignore-start -->

• Optional stack/stack.yaml, stack/tech-stack.md, snippets, and API templates

<!-- oma-docs:ignore-end -->

• Database, queue, cache, mail, auth, or external API resources configured through environment or secret managers

Control-flow features

• Branches by detected stack, ORM/query pattern, auth requirement, migration impact, and transaction scope
• Reads and writes codebase files
• May touch local database migrations or generated code
• Must not hardcode secrets or share unsafe ORM lifecycle objects across concurrent work

Structural Flow

Entry

• Detect the backend stack from project files first.
• Identify affected router, service, repository, model, migration, and test boundaries.
• Load stack-specific references only when needed.

Scenes

• PREPARE: Determine stack, architecture boundaries, and acceptance criteria.
• ACQUIRE: Read existing routes, services, repositories, models, schemas, and config.
• ACT: Implement backend changes with validation, business logic, persistence, and tests.
• VERIFY: Run relevant lint, type, test, migration, and checklist commands.
• FINALIZE: Report changed behavior, verification, and unresolved risks.

Transitions

• If stack files exist, follow them before generic guidance.
• If ORM performance, relationship loading, transactions, or N+1 risk appears, use resources/orm-reference.md.
• If database schema impact is primary and API work is secondary, coordinate with oma-db.
• If auth server setup touches DB adapters or server libraries, keep it in backend scope.

Failure and recovery

• If stack cannot be determined, ask the user or suggest running /stack-set.
• If verification fails, fix root cause before handoff.
• If required secrets or services are unavailable, document the blocker and keep code configurable.

Exit

• Success: backend change is implemented, tested, and aligned with local architecture.
• Partial success: blocker, missing dependency, or verification gap is explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence |

|--------|---------------|----------|

| Detect stack and conventions | READ | Manifests, stack files, existing code |

| Select implementation boundary | SELECT | Router/service/repository pattern |

| Validate inputs and schemas | VALIDATE | Stack validation library |

| Implement business logic | WRITE | Service layer code |

| Implement persistence | WRITE | Repository/model/migration code |

| Call external/backing services | CALL_TOOL | DB, queue, cache, auth, or API clients |

| Run verification | CALL_TOOL | Tests, typecheck, lint, migrations |

| Report result | NOTIFY | Final summary |

Tools and instruments

• Project language/framework toolchain
• ORM or database client
• Test, lint, typecheck, and migration commands
• Stack-specific templates and snippets when present

Canonical workflow path

rg --files
rg "route|router|service|repository|model|schema|migration" .

<!-- oma-docs:ignore-start -->

Then run the project's discovered verification commands, usually lint/typecheck/tests and migrations when schema changes are involved. Prefer stack/stack.yaml verify: commands when present.

<!-- oma-docs:ignore-end -->

Resource scope

| Scope | Resource target |

|-------|-----------------|

| CODEBASE | Backend source, tests, schemas, migrations |

| LOCAL_FS | Stack references and generated artifacts |

| PROCESS | Test, lint, typecheck, migration commands |

| CREDENTIALS | Environment-managed DB URLs, API keys, secrets |

| NETWORK | External APIs or backing services when required |

Preconditions

• Target behavior and affected backend boundary are identifiable.
• Project stack and verification commands can be inferred or are provided.
• Required credentials remain outside source code.

Effects and side effects

• Mutates backend source files, tests, and possibly migrations.
• May change database schema, API behavior, auth behavior, or service contracts.
• May require generated clients or migration artifacts.

Guardrails

• 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 + Argon2id for auth (bcrypt acceptable for legacy compatibility); 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

10. Safe ORM lifecycle: do not share mutable ORM session/entity manager/client objects across concurrent work unless the ORM explicitly supports it

11. Config from environment, with graceful fallback: DB URLs, API keys, secrets, and feature flags come from env vars or secret managers; never hardcode in source. When integrating a third-party API (OpenAI, Anthropic, Stripe, etc.), write BOTH paths: (a) real call when the env key is present, (b) deterministic local fallback when absent, marked with // TODO(oma-deferred): integrate <vendor> when key is provisioned. Fallback-only leaves the spec unmet; real-call-only breaks demos when the key is missing

12. Stateless services: no in-memory session or user state between requests; use external stores (DB, Redis, cache) for shared state

13. 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

• 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

<!-- oma-docs:ignore-start -->

• Stack manifest (SSOT): stack/stack.yaml: structured declaration (language, framework, orm) and verify: contract consumed by oma verify backend. Schema: variants/stack.schema.json.
• Tech stack narrative: stack/tech-stack.md: human-readable reference only; stack.yaml wins on conflict.
• Code snippets (copy-paste ready): stack/snippets.md
• API template: stack/api-template.*

<!-- oma-docs:ignore-end -->

References

Follow resources/execution-protocol.md step by step.

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.

Vendor-specific execution protocols are injected automatically by oma agent:spawn.

Source files live under ../_shared/runtime/execution-protocols/{vendor}.md.

• Execution steps: resources/execution-protocol.md
• Checklist: resources/checklist.md
• ORM reference: resources/orm-reference.md
• Error recovery: resources/error-playbook.md
• Context loading: ../_shared/core/context-loading.md
• Clarification: ../_shared/core/clarification-protocol.md
• Context budget: ../_shared/core/context-budget.md
• Lessons learned: ../_shared/core/lessons-learned.md
• Observability handoff: ../oma-observability/SKILL.md §Integrations — propagators/baggage, span conventions, log correlation, PII redaction