legacy-integration

Stars5

Forks0

UpdatedApril 10, 2026 at 14:47

Use this skill when integrating AI agents with existing enterprise systems, legacy APIs, ERPs, CRMs, or when migrating from legacy to agent-based systems. Trigger when someone says 'we have existing systems the agent must use', 'we need to integrate with our ERP/CRM', 'legacy system has a different data model', 'how do we migrate gradually?', 'our legacy system is unstable', 'we need to call a SOAP service', 'agents and legacy systems must coexist'. Also trigger for: Anti-Corruption Layer, Saga pattern, Strangler Fig migration, REST adapter, message queue integration.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

clenci

clenci/arch-advisor

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name

legacy-integration

description

Legacy System Integration

Integration Pattern Selection

Requirement	Pattern
Real-time, strong consistency, request-response	REST adapter
Near-real-time, decoupled, async processing	Message Queue (RabbitMQ/Kafka)
Large batch, high volume, scheduled	File Transfer
Complete audit history, replay capability	Event Sourcing
Distributed transaction with rollback	Saga Pattern

Anti-Corruption Layer (ACL)

Always use an ACL when:

The legacy system's domain model differs from the agent's domain model
The legacy system has known bugs or behaviors that must be filtered
You do not want the agent's design to be influenced by legacy constraints

The ACL is a translation layer:

[Agent] ← [ACL: toDomain()] ← [Legacy System]
[Agent] → [ACL: toLegacy()] → [Legacy System]

toDomain(): maps legacy response to clean domain model toLegacy(): maps agent's request to legacy format

The ACL must also:

Normalize error codes to a consistent error taxonomy
Sanitize and validate legacy data before passing to agents
Log all translations for debugging

REST Adapter Pattern

Every REST adapter needs:

Retry with exponential backoff (for 5xx and network errors only — never retry 4xx)
Timeout (always finite — typically 10–30s per call)
Circuit breaker per endpoint or per downstream service
Error mapping to domain error types

async call(endpoint: string, payload: unknown): Promise<DomainResponse> {
  // retry: 3 attempts, backoff: 1s, 2s, 4s
  // timeout: 15s per attempt
  // circuit breaker: open after 5 failures in 60s
  // map HTTPError to DomainError
}

Saga Pattern for Distributed Transactions

Use when an operation spans multiple services and must be rolled back if any step fails.

Choreography Saga (event-driven):

Service A completes step → publishes event
Service B listens, completes its step → publishes event
If B fails: publishes failure event, A reverses its step

Orchestration Saga (central coordinator):

Coordinator calls Service A
Coordinator calls Service B
If B fails: Coordinator calls A's compensation

For agent systems: prefer orchestration — easier to trace and debug.

Compensation must be idempotent: compensations may run more than once (retries, failures). Ensure they are safe to repeat.

Strangler Fig Migration Pattern

Gradually replace a legacy system without a big-bang migration:

Phase 1 (10% → new system): route a small percentage to the new agent-based system; monitor closely Phase 2 (25%): expand if Phase 1 metrics are acceptable Phase 3 (50%): parallel operation; compare outcomes Phase 4 (100%): complete cutover; keep legacy in read-only for 30 days

Go/no-go criteria per phase:

Error rate < threshold (e.g., < 2%)
Latency P95 within target
Rollback plan: one config change reverts traffic to 0% on new system

Automated rollback: if error rate exceeds threshold for N minutes, automatically route 100% back to legacy.

Handling Unstable Legacy Systems

Add circuit breakers per legacy endpoint. When legacy is down:

Serve from cache if available (stale is better than error for read operations)
Queue write operations (if eventually consistent is acceptable)
Degrade gracefully: inform the user, do not crash the agent

Do not retry indefinitely. Set a maximum retry count and a dead-letter queue for failed operations.

Perguntas diagnósticas

Does the legacy system's data model match the agent's domain model, or is translation required?
Is the legacy system stable, or does it have a history of timeouts and errors?
Are there distributed transactions that span the agent and one or more legacy systems?
Is a gradual migration possible, or must the switch be all-at-once?
What is the acceptable behavior when the legacy system is unavailable?
Does the legacy system have rate limits or maintenance windows that affect the integration?

More from this repository

same repository

agent-internal-architecture

clenci/arch-advisor

Use this skill when designing the internal structure of a single agent, when discussing perception layers, decision layers, memory management, reflection loops, state management, or when someone says 'how should the agent be structured internally?', 'how do we handle memory?', 'should state be mutable or immutable?', 'we need the agent to self-improve its output', 'how do we chunk documents?', 'the agent needs to remember past interactions'. Also trigger for topics like LTM, STM, chunking strategy, critic-reviser, context window management.

2026-04-105

architecture-documentation

clenci/arch-advisor

Use this skill when documenting architectural decisions, creating ADRs, drawing C4 diagrams, writing RFCs, or presenting architecture to stakeholders. Trigger when someone says 'we need to document this decision', 'write an ADR', 'create a C4 diagram', 'how do we explain this to management?', 'we need an RFC', 'how do we communicate trade-offs?', 'design review', 'architecture presentation'. Also trigger for: Architecture Decision Records, C4 Model, trade-off analysis framework, design review, technical brief.

2026-04-105

data-memory-storage

clenci/arch-advisor

Use this skill when choosing storage systems, designing the data layer, deciding between databases, or designing agent memory. Trigger when someone says 'what database should we use?', 'where do we store agent state?', 'how do we persist memory between sessions?', 'we need vector storage for embeddings', 'how do we structure session data?', 'the agent needs to remember past conversations', 'we need to store user history', 'GDPR compliance for stored data'. Also trigger for: PostgreSQL, Redis, vector DB, Chroma, Pinecone, polyglot persistence, CQRS, Event Sourcing.

2026-04-105

integration-protocols

clenci/arch-advisor

Use this skill when designing how agents expose or consume tools and APIs, when discussing MCP servers, A2A communication, tool registries, or when someone says 'agents need to call external APIs', 'how should agents communicate with each other?', 'we need to expose tools to the LLM', 'designing agent-to-agent messaging', 'tool governance and access control', 'idempotent tool calls', 'MCP server implementation'. Also trigger for: Model Context Protocol, A2A patterns, tool design, RBAC for tools, distributed tracing between agents.

2026-04-105

llm-frameworks

clenci/arch-advisor

Use this skill when choosing between LangChain, LangGraph, CrewAI, Semantic Kernel, or custom implementation, when someone asks 'which framework should we use?', 'should we use LangGraph or LangChain?', 'is CrewAI a good fit?', 'should we build custom?', 'we need a framework for our agents', 'comparing LLM frameworks', or when evaluating framework trade-offs for agent orchestration. Also trigger for topics: LCEL, StateGraph, Crew, Semantic Kernel skills, framework migration.

2026-04-105

llm-selection-routing

clenci/arch-advisor

Use this skill when choosing which LLM to use, comparing providers, designing routing between models, handling LLM fallbacks, or optimizing LLM costs. Trigger when someone says 'which model should we use?', 'we need to choose between GPT-4 and Claude', 'how do we route to cheaper models for simple tasks?', 'we need fallback if OpenAI goes down', 'LLM costs are too high', 'we need multi-provider strategy', 'circuit breaker for LLM providers'. Also trigger for: model cascading, cost optimization, caching LLM responses, rate limiting.

2026-04-105

name

legacy-integration

description

Legacy System Integration

Integration Pattern Selection

Requirement	Pattern
Real-time, strong consistency, request-response	REST adapter
Near-real-time, decoupled, async processing	Message Queue (RabbitMQ/Kafka)
Large batch, high volume, scheduled	File Transfer
Complete audit history, replay capability	Event Sourcing
Distributed transaction with rollback	Saga Pattern

Anti-Corruption Layer (ACL)

Always use an ACL when:

The legacy system's domain model differs from the agent's domain model
The legacy system has known bugs or behaviors that must be filtered
You do not want the agent's design to be influenced by legacy constraints

The ACL is a translation layer:

[Agent] ← [ACL: toDomain()] ← [Legacy System]
[Agent] → [ACL: toLegacy()] → [Legacy System]

toDomain(): maps legacy response to clean domain model toLegacy(): maps agent's request to legacy format

The ACL must also:

Normalize error codes to a consistent error taxonomy
Sanitize and validate legacy data before passing to agents
Log all translations for debugging

REST Adapter Pattern

Every REST adapter needs:

Retry with exponential backoff (for 5xx and network errors only — never retry 4xx)
Timeout (always finite — typically 10–30s per call)
Circuit breaker per endpoint or per downstream service
Error mapping to domain error types

async call(endpoint: string, payload: unknown): Promise<DomainResponse> {
  // retry: 3 attempts, backoff: 1s, 2s, 4s
  // timeout: 15s per attempt
  // circuit breaker: open after 5 failures in 60s
  // map HTTPError to DomainError
}

Saga Pattern for Distributed Transactions

Use when an operation spans multiple services and must be rolled back if any step fails.

Choreography Saga (event-driven):

Service A completes step → publishes event
Service B listens, completes its step → publishes event
If B fails: publishes failure event, A reverses its step

Orchestration Saga (central coordinator):

Coordinator calls Service A
Coordinator calls Service B
If B fails: Coordinator calls A's compensation

For agent systems: prefer orchestration — easier to trace and debug.

Compensation must be idempotent: compensations may run more than once (retries, failures). Ensure they are safe to repeat.

Strangler Fig Migration Pattern

Gradually replace a legacy system without a big-bang migration:

Go/no-go criteria per phase:

Error rate < threshold (e.g., < 2%)
Latency P95 within target
Rollback plan: one config change reverts traffic to 0% on new system

Automated rollback: if error rate exceeds threshold for N minutes, automatically route 100% back to legacy.

Handling Unstable Legacy Systems

Add circuit breakers per legacy endpoint. When legacy is down:

Serve from cache if available (stale is better than error for read operations)
Queue write operations (if eventually consistent is acceptable)
Degrade gracefully: inform the user, do not crash the agent

Do not retry indefinitely. Set a maximum retry count and a dead-letter queue for failed operations.

Perguntas diagnósticas

Does the legacy system's data model match the agent's domain model, or is translation required?
Is the legacy system stable, or does it have a history of timeouts and errors?
Are there distributed transactions that span the agent and one or more legacy systems?
Is a gradual migration possible, or must the switch be all-at-once?
What is the acceptable behavior when the legacy system is unavailable?
Does the legacy system have rate limits or maintenance windows that affect the integration?