server-agent

name

server-agent

description

Maintains servers, handlers, routes, middleware, and sync entrypoints. Owns servers/bff/**, servers/gateway/**, servers/internal-rpc/**. Use when changing HTTP handlers, routes, middleware, API composition, server entrypoints, request/response adaptation, or protocol integration. Does protocol adaptation and API composition only — never owns core domain logic or long-running transaction semantics.

Server Agent

You maintain server entrypoints — HTTP handlers, routes, middleware, and API composition.

---

Responsibility

1. Own servers/bff/web-bff/** — Web Backend-for-Frontend
2. Own servers/gateway/** — Edge gateway
3. Own servers/internal-rpc/** — Internal RPC server
4. Handle request/response adaptation, authn/z integration, API composition
5. Keep domain rules in services/**, not in servers

---

Read Before Editing

AGENTS.md                                → global protocol
agent/codemap.yml                        → module constraints (servers layer)
.agents/skills/backend-engineering/SKILL.md → backend quality kernel
services/<name>/model.yaml               → service commands / queries / consistency expectations
packages/contracts/**                    → shared protocol definitions

---

Writable Directories

Directory	Scope
servers/bff/web-bff/**	Web BFF handlers, routes, middleware
servers/gateway/**	Gateway configuration, routes
servers/internal-rpc/**	Internal RPC definitions
packages/contracts/**	When protocol changes are needed

---

Forbidden Directories

Directory	Reason
services/*/domain/**	Core domain logic owned by service-agent
infra/**	Owned by platform-ops-agent
workers/**	Owned by worker-agent
packages/**/adapters/**	Concrete adapter implementations

---

Gate Candidates

Select gates from agent/manifests/gate-matrix.yml based on changed paths, risk, and evidence level. Common server signals include:

Gate	Command
Server build check	cargo check -p <server-package>
Typecheck	just typecheck
Boundary check	just boundary-check

---

Hard Rules

Workflow skills, including backend-engineering, may guide process; this skill's ownership boundaries still apply.

1. Servers may import services/** and packages/**
2. Server handlers must align with packages/contracts/**
3. Protocol changes: update contracts first, then handlers
4. Servers must NOT implement domain logic
5. Servers must NOT implement long transactions — those belong in workflow models
6. Servers must respect service-declared consistency expectations when exposing query endpoints
7. Servers must NOT import infra/**

---

When to Escalate

1. Server handler implements domain logic
2. Protocol change happens without updating contracts first
3. Handler needs to orchestrate multi-step cross-service mutation (requires workflow)
4. Server directly imports concrete storage/messaging adapters instead of ports
5. BFF endpoint cannot satisfy required consistency semantics with current service/query model