agentleFS
mikeparcewskimikeparcewski/wicked-garden/skills/engineering/integration/SKILL.md

wicked-garden-engineering-integration

Skill9 starsChanged 7 months agoMITView on GitHub

Design API contracts, service boundaries, and integration patterns. Define how components and services communicate and interoperate.

The file

Files
SKILL.md

Integration Skill

Design robust, well-documented integration points between components and services.

Purpose

Define communication contracts:

  • API design (REST, GraphQL, gRPC)
  • Event schema definition
  • Integration pattern selection
  • Error handling and resilience

Process

1. Identify Integration Points

Map communication:

  • Component-to-component
  • Service-to-service
  • Client-to-server
  • External integrations
  • Event flows

2. Choose Pattern

Select approach:

  • Request/Response - Sync, immediate result
  • Publish/Subscribe - Async, one-to-many
  • Event Sourcing - Audit trail, replay
  • API Gateway - Unified entry point

3. Design Contracts

Define specifications:

  • OpenAPI for REST
  • GraphQL schemas
  • Protocol Buffers for gRPC
  • Event schemas (JSON Schema)

4. Plan Resilience

Handle failures:

  • Retry strategies
  • Circuit breakers
  • Timeouts
  • Fallback behaviors

Output

Creates in phases/design/:

design/
├── integration/
│   ├── overview.md
│   ├── api-specs/
│   │   ├── openapi.yaml
│   │   └── events.json
│   └── patterns.md

Integration Patterns

REST API

Resource-oriented, stateless, HTTP verbs. See REST API Fundamentals and Responses & Security.

GraphQL

Flexible queries, strong typing. See GraphQL guides in refs/ (graphql-graphql-basics.md, graphql-schema-design-patterns.md).

gRPC

High performance, service-to-service. See gRPC guides in refs/ (grpc-grpc-overview.md, grpc-implementation-examples.md).

Event-Driven

Async messaging, pub/sub. See event schema guides in refs/ (event-schemas-event-structure.md, event-schemas-best-practices.md).

Error Handling

Standard HTTP status codes:

  • 2xx: Success (200 OK, 201 Created, 204 No Content)
  • 4xx: Client errors (400, 401, 404, 409)
  • 5xx: Server errors (500, 503)

See error handling guides in refs/ (error-handling-error-response-format.md, error-handling-best-practices.md).

Resilience Patterns

  • Circuit Breaker - Prevent cascading failures
  • Retry with Backoff - Exponential retry delays
  • Timeouts - Fail fast on slow responses
  • Fallbacks - Graceful degradation

See resilience guides in refs/ (resilience-circuit-breaker-pattern.md, resilience-best-practices.md).

Versioning

Common strategies:

  • URL versioning: /api/v1/resources
  • Header versioning: Accept: application/vnd.api+json; version=1

See versioning guides in refs/ (versioning-versioning-strategies.md, versioning-migration-strategies.md).

Integration

With System Design

Takes component boundaries and defines:

  • Interfaces between components
  • Data contracts
  • Communication patterns

With Data Architecture

Coordinates on:

  • API data models
  • Event payloads
  • Serialization formats

Events

  • [arch:contract:defined:success] - API contract created
  • [arch:api:validated:success] - API spec validated
  • [arch:event:schema:defined:success] - Event schema documented

Tips

  1. API-First Design - Design before implementation
  2. Version from Start - Plan for evolution
  3. Document Well - Specs are executable docs
  4. Error Handling - Comprehensive error responses
  5. Idempotency - Make operations repeatable safely
  6. Security - Auth/authz from the beginning

Reference Materials

  • REST API:
    • Fundamentals
    • Responses & Security
  • GraphQL:
    • Basics
    • Query Examples
    • Schema Design
    • Error Handling
    • Best Practices
  • gRPC:
    • Overview
    • Implementation
    • Metadata & Headers
    • Testing
  • Event Schemas:
    • Event Structure
    • Naming Conventions
    • Best Practices
  • Error Handling:
    • Response Format
    • Error Classes (TS)
    • Retry Strategies
    • Best Practices
  • Resilience:
    • Circuit Breaker
    • Timeout & Bulkhead
    • Rate Limiting
    • Best Practices
  • Versioning:
    • Strategies
    • Migration
    • Breaking Changes
  • OpenAPI Template

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.