backend-services - SKILL.md Agent Skill

name: backend-services description: Backend services for AWCMS-Micro and EmDash plugins/APIs. Use when implementing API routes, service layers, route handlers, plugin hooks, auth/RBAC/ABAC, serializers, storage, queues, Cloudflare Workers runtime behavior, or server-side integration.

Backend Services

Use this skill for backend implementation in AWCMS-Micro plugins, EmDash-compatible services, API routes, hooks, and Cloudflare/Node runtime integration.

Priority Sources

Prefer the local Claude/EmDash skill and repository guidance in this order:

awcmsmicro-dev/AGENTS.md for EmDash backend route, handler, auth, CSRF, pagination, error, storage, caching, and environment rules.
awcmsmicro-dev/skills/creating-plugins/SKILL.md for plugin descriptors, definePlugin(), hooks, routes, capabilities, sandboxed/trusted execution, storage, KV, and publishing constraints.
awcmsmicro-dev/skills/emdash-cli/SKILL.md for operational CLI behavior around schema, content, seed export, media, and automation.
Root AGENTS.md, docs/awcms-micro-implementation-boundaries.md, and project governance docs for downstream boundaries.
Cloudflare Workers docs/skills when changing Workers runtime, bindings, Durable Objects, Queues, D1, R2, or Wrangler config.

Boundary Rules

Keep AWCMS-Micro product behavior inside approved plugin/template boundaries.
Do not add SIKESRA-specific or project-specific behavior to EmDash core unless an issue explicitly justifies upstream work.
Use patch overlays only for narrow downstream source-level overrides that must survive rebuilds.
Record active patch overlays in docs/upstream-sync/DIVERGENCE_LOG.md.

API And Handler Rules

Keep route files thin; put business logic in service/handler layers.
Return typed result envelopes where the target project already uses them.
Do not expose raw error.message to clients. Map failures to stable error codes and safe messages.
Never add GET handlers for state-changing operations.
State-changing admin/API calls must respect EmDash CSRF expectations such as X-EmDash-Request: 1 where applicable.
List endpoints should return { items, nextCursor? }, not bare arrays, unless the existing contract says otherwise.

Auth And Security

Use trusted EmDash identity from request/session context; do not trust client-provided identity headers for authorization decisions.
Use permission/capability checks rather than role-string shortcuts where the codebase provides permission helpers.
Keep public APIs aggregate-only and public-safe for sensitive domains like SIKESRA.
Validate request bodies with schemas; do not cast request.json() directly into trusted types.
For plugin sandbox compatibility, avoid Node built-ins in code that must run inside isolates.

Integration Rules

Connect UI, API routes, service layer, serializers, and database/repository layer through typed contracts.
Keep serializers responsible for public-safe masking and response shape stability.
Prefer Web APIs and platform bindings that work in both Cloudflare and Node targets when the feature must be portable.

Verification

Use the closest relevant checks:

pnpm typecheck
package/plugin-specific pnpm test
route-focused Vitest filters where available
bash scripts/validate-awcmsmicro-boundaries.sh for rebuild safety
SIKESRA: pnpm --filter @awcms-micro/plugin-sikesra awcms:sikesra:validate-after-emdash-sync