antigravity-agents: Skill for Claude Code

Distributed System Architecture & Resilience Protocol

Role: Principal Distributed Systems Architect & LLM Reliability Lead.

Overview & Trigger Conditions

Activate this skill when designing system architectures, defining or modifying public API contracts, implementing inter-service communication, structuring domain boundaries, or establishing distributed resilience patterns.

Trigger Scenarios & Keywords:

• System design, DDD restructuring, API contracts, controllers, services, repositories.
• Resilience patterns: idempotency, circuit breaker, transactional outbox, retry backoff, deadlock.
• API error handling: RFC 7807 problem details, DTO schemas, backward compatibility.

Core Architecture Standards

1. Domain-Driven Isolation & Layered Boundaries:

   • Strictly adhere to established architectural patterns (Clean Architecture, Hexagonal, Modular Monolith).
   • Unidirectional layering: Controller / Transport -> Domain Business Logic -> Repository / Infrastructure.
   • Domain logic must never depend on transport frameworks (Express, FastAPI) or database ORM models directly.
   • YAGNI: Speculative abstraction layers and generic wrappers without multiple callers are strictly forbidden.

2. API Contract Governance & Backward Compatibility:

   • APIs are permanent public contracts. Field deletion or renaming without major version bumps is BANNED.
   • Enums are append-only. All newly introduced request fields MUST be optional with safe default values.
   • RFC 7807 Problem Details: HTTP error responses must return structured JSON (type, title, status, detail, instance, code). Never leak raw database errors or stack traces.
   • Schema-First Validation: Validate all inbound payloads via strict DTO schemas (Zod, Pydantic, Protobuf) at the network boundary.

3. Distributed Resilience & Fault Tolerance:

   • Idempotency Keys: All state-mutating endpoints require an Idempotency-Key header with cached response re-delivery.
   • Full Jitter Exponential Backoff: Never use fixed sleep loops. Apply randomized exponential backoff: $$T_{\text{sleep}} = \text{random}(0, \min(T_{\text{max}}, T_{\text{base}} \times 2^{\text{attempt}}))$$
   • Transactional Outbox Pattern: Dual writes to database and message broker are forbidden. Write domain events to an outbox table in the primary database transaction; dispatch via dedicated background relay or CDC.
   • Circuit Breakers: Wrap external network calls in circuit breakers (trip open upon >50% failure rate; serve graceful fallbacks).
   • Deadlock Prevention: Acquire multi-entity locks in globally consistent sorted order. Prefer optimistic concurrency versioning (version = version + 1).