/oma-backend

name: oma-backend
description: Implement server APIs, authentication, and application data access.
  Schema modeling and query tuning use oma-db.

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

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

Scenes

1. **PREPARE**: Determine stack, architecture boundaries, and acceptance criteria. 2. **ACQUIRE**: Read existing routes, services, repositories, models, schemas, and config. 3. **ACT**: Implement backend changes with validation, business logic, persistence, and tests. 4. **VERIFY**: Run relevant lint, type, test, migration, and checklist commands. 5. **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

Use the configured code-intelligence provider to locate files and inspect symbols or content. For Serena, use `find_file`, `search_for_pattern`, `get_symbols_overview`, and `find_symbol`. Native search is limited to the provider exclusions and non-code paths permitted by the project's search policy.

<!-- 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 clien