feat(backend): add event and coexistence patterns (#361)

Add outbox/inbox implementation, idempotent message handling, migration coexistence seams, evals, and exact specialist routing.\n\nAI-assisted: Jasper orchestrated implementation and verification with OpenCode.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>

backend-engineering/SKILL.md

@@ -1,31 +1,35 @@
 ---
 name: backend-engineering
-description: Design and implement backend services and APIs — REST, gRPC, GraphQL
-  endpoint patterns, service architecture (clean/hexagonal/layered), database access
-  patterns, integration and middleware design, error handling, and service-level
-  testing. Language and framework agnostic. Do not use for frontend, data engineering,
-  or platform infrastructure provisioning.
+description: Design and implement backend services and APIs — REST, gRPC, GraphQL,
+  event-driven handlers, transaction boundaries, outbox/inbox delivery, migration
+  coexistence, database access, integration, error handling, and service-level testing.
+  Use for application/domain/infrastructure implementation decisions. Language and
+  framework agnostic. Do not use for frontend, data engineering, platform provisioning,
+  API contract ownership, service decomposition strategy, or cross-system migration
+  planning.
 license: MIT
 metadata:
-  tags: backend, api, services, server, database, integration, middleware, query-optimization,
-    testing
+  tags: backend, api, services, server, database, integration, middleware, events, outbox,
+    inbox, idempotency, coexistence, query-optimization, testing
   source_repo: https://github.com/magnus919/hermes-profiles
 ---
 
 # Backend Engineering Methodology
 
-Backend engineering is the craft of building the server-side systems that power applications — APIs, services, data access, integrations, and the runtime behavior that makes the architecture real. This methodology covers the implementation patterns between architecture design (software-architecture-analysis) and quality validation (qa-methodology).
+Backend engineering is the craft of building the server-side systems that power applications — APIs, services, data access, integrations, and the runtime behavior that makes the architecture real. This methodology covers implementation after target design in `software-architecture` and before quality validation in `qa-methodology`; use `software-architecture-analysis` when the current system must first be reverse-engineered. It makes runtime boundaries, transaction behavior, message handling, and coexistence seams executable without taking ownership of the surrounding architecture or migration decision.
 
 ## The Backend Engineer's Domain
 
 | You own | You don't own |
 |---------|--------------|
-| API implementation — REST/gRPC/GraphQL endpoints, request validation, response formatting, error handling, middleware chains | API contract and service boundary design — that's the api-design-and-evolution |
-| Service logic — business rules, workflow orchestration, state management, background job processing | Deployment pipeline and infrastructure — that's the platform-engineer |
-| Database access patterns — query design, connection management, transaction boundaries, N+1 detection, pagination | Schema design and migrations — that's the data-architect / data-engineer |
-| Integration code — third-party API clients, webhook handlers, message queue consumers/producers | Code review and quality gates — that's the qa-methodology |
-| Observability instrumentation at the service level — structured logging, metrics, tracing hooks | Observability infrastructure — that's the SRE / platform-engineer |
-| Service-level tests — unit tests for business logic, integration tests for API contracts | Test strategy and automation — that's the QA-engineer |
+| API implementation — REST/gRPC/GraphQL endpoints, request validation, response formatting, error handling, middleware chains | API contracts belong to `api-design-and-evolution`; service decomposition and target boundaries belong to `software-architecture` |
+| Service logic — business rules, workflow orchestration, state management, background job processing | Deployment pipeline and infrastructure — that's `platform-engineering` |
+| Event-driven implementation — domain-event publication, outbox/inbox coordination, handler idempotency, replay and failure paths | Event contract ownership and delivery semantics — that's the api-design-and-evolution |
+| Migration seams inside a service — adapters, selectable paths, authority checks, and implementation handoffs | Cross-system migration lifecycle and cutover authority — that's the migration-engineering |
+| Database access patterns — query design, connection management, transaction boundaries, N+1 detection, pagination | Data-platform and model strategy belong to `data-architect`; schema and pipeline operations belong to `data-engineering` |
+| Integration code — third-party API clients, webhook handlers, message queue consumers/producers | Code review and quality gates — that's `qa-methodology` |
+| Observability instrumentation at the service level — structured logging, metrics, tracing hooks | Observability infrastructure and reliability policy belong to `platform-engineering` and `site-reliability-engineering` |
+| Service-level tests — unit tests for business logic, integration tests for API contracts | Test strategy and automation — that's `qa-methodology` |
 
 ## Reference Files
 
@@ -33,9 +37,12 @@ Backend engineering is the craft of building the server-side systems that power
 |-----------|-------------|
 | `references/api-patterns.md` | Designing or implementing API endpoints — resource modeling, versioning, pagination, error response formats, request validation |
 | `references/service-patterns.md` | Structuring service logic — clean/hexagonal/layered architecture, dependency injection, middleware composition, request lifecycle, background jobs |
+| `references/event-driven-service-implementation.md` | Implementing event-driven application flows — domain events, unit of work, transactional outbox/inbox, idempotent handlers, retry/replay, observability, and failure handling |
+| `references/migration-coexistence-patterns.md` | Keeping old and new implementations safe to run together — adapters, strangler handoffs, anti-corruption boundaries, dual paths, authority, and removal conditions |
 | `references/database-testing.md` | Database access patterns (connection pooling, query optimization, N+1 detection, pagination strategies, transaction boundaries, read/write splitting, replication lag) and service-level testing (unit testing business logic, integration testing API contracts with test containers/WireMock, contract testing with Pact, test fixtures, CI integration) |
 | `references/integration-patterns.md` | Integrating with external systems — retry with backoff, circuit breakers, idempotency keys, webhook verification, message queue consumers |
 | `references/error-handling.md` | Handling errors systematically — classification (client vs server), structured responses, exception handling patterns, observability correlation |
+| `references/source-index.md` | Provenance and ownership notes for this original synthesis; load when reviewing scope or source boundaries |
 
 ## Templates
 
@@ -52,6 +59,13 @@ Backend engineering is the craft of building the server-side systems that power
 
 ## Related Skills
 
+- [programming-principles](../programming-principles/SKILL.md) — DDD owns bounded contexts, aggregates, domain language, repositories, and domain-modeling guidance. This skill applies those decisions at implementation seams rather than duplicating that catalog.
+- [api-design-and-evolution](../api-design-and-evolution/SKILL.md) — owns event/message contracts, delivery semantics, compatibility, and consumer-facing API decisions.
+- [migration-engineering](../migration-engineering/SKILL.md) — owns cross-system migration classification, compatibility windows, reconciliation, cutover, recovery, deprecation, and cleanup. This skill only implements service-local coexistence seams.
+- [software-architecture](../software-architecture/SKILL.md) — owns service decomposition and target-boundary strategy; backend engineering implements an approved boundary.
+- [data-engineering](../data-engineering/SKILL.md) — owns schema migration and pipeline operations; application code may expose the repository or transaction interfaces those operations use.
+- [secure-software-engineering](../secure-software-engineering/SKILL.md) — owns threat modeling, authorization, secrets, untrusted inputs, and security acceptance evidence.
+- [release-engineering](../release-engineering/SKILL.md) — owns progressive delivery, artifact promotion, release gates, and rollback mechanics.
 - [postgres](../postgres/SKILL.md) — diagnosing the PostgreSQL side of a database problem: configuration review, index and query-plan issues, vacuum/bloat, backups/PITR, replication and failover. Application-level data access patterns stay here; engine-level operations route there.
 - [supabase](../supabase/SKILL.md) — building on Supabase: migrations, RLS, Auth, Storage, and Edge Functions. To measure an agent's Supabase task competence, use its [agent evals harness reference](../supabase/references/agent-evals.md).
 
@@ -66,3 +80,29 @@ Backend engineering is the craft of building the server-side systems that power
 **Design for failure, not just success** — Every external call can fail. Every database connection can drop. Every message can be duplicated. Idempotency, retry, and graceful degradation are not optimizations — they're requirements.
 
 **Test at the right level** — Business logic gets unit tests. API contracts get integration tests. Service boundaries get contract tests. Each level catches a different class of failure.
+
+## Implementation Decision Path
+
+1. Name the bounded context, aggregate/invariant boundary, and source of truth. Use
+   [programming-principles](../programming-principles/SKILL.md) for DDD choices rather
+   than rebuilding its catalog here.
+2. Put transport, broker, database, clock, and vendor concerns behind ports owned by
+   the application or domain-facing code. Let infrastructure implement those ports.
+3. For a command that changes durable state and emits a fact, load the aggregate,
+   invoke domain behavior, and commit state plus outbox records in one unit of work.
+   Do not hold that transaction open across network calls.
+4. For an incoming message, validate the envelope at the edge, deduplicate within the
+   consumer's authority, apply the handler, and acknowledge only after its durable
+   effects commit. Load the event reference for replay and poison-message decisions.
+5. If old and new paths coexist, record which path is authoritative for each operation,
+   how outputs are compared, and what evidence permits handoff or removal. Load the
+   migration reference for the implementation seam; route the migration lifecycle out.
+6. Add unit tests for domain/application behavior and boundary integration tests for
+   transaction, outbox, inbox, duplicate, retry, replay, and recovery behavior.
+
+## Exit Criteria
+
+This skill is complete when the implementation has explicit dependency direction,
+transaction and authority boundaries, classified failure/retry behavior, observable
+message or coexistence paths, focused tests for duplicate and failure cases, and clear
+links to the neighboring owner for every out-of-scope decision.