Skip to main content
subagent CX Codex

integration-engineer — Claude Code/Codex subagent

integration-engineer plans the seams between systems: webhooks with retries, ETL jobs, broker pipelines, EDI files. Useful when two systems speak different data models.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/integration-engineer.md
Open on GitHub

What integration-engineer does

This subagent plans data movement across system boundaries: outbound webhooks, inbound APIs, message brokers, batch ETL, EDI and flat-file exchanges. It works on the seams where the two sides carry different data models and a dropped message is expensive.

The definition file carries decision tables. A delivery-guarantee matrix covers outbox with consumer dedup, sagas with compensating actions, and the best-effort case. There are retry rules with exponential backoff and jitter, a rollout order for schema changes, a partner onboarding checklist, and a pattern for EDI and flat files. An anti-patterns section names the usual failures: publishing before the database commit, retrying a 4xx, letting consumers parse raw EDI.

Constraints are spelled out. Every integration must carry an idempotency key and a dedup window, no publish happens before a durable write, and a consumer without a dead-letter store and a replay path is not finished. The agent runs under max_turns: 25 with the tools listed in its frontmatter, run_shell_command and write_file among them. It also hands off: data-engineer gets the canonical schema, security-engineer the auth model and certificate rotation.

What it helps with

  • connect two services with different data models through an outbox
  • write an ETL job with an idempotent merge that can restart
  • ingest an inbound EDI 850 from SFTP and return a 997
  • add retries and a dead-letter store to an outbound webhook
  • put an anti-corruption layer in front of a legacy system

Example prompts for the agent

  • Set up an outbound webhook from the order service to a partner, with delivery that survives retries
  • Ingest inbound EDI 850 files from SFTP into our order model and send back a 997
  • Design an ETL job with an idempotent merge that restarts cleanly after a crash

How to install integration-engineer

Manually: put the files in place

.claude/agents/integration-engineer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about integration-engineer

How to install integration-engineer in Claude Code?

Copy the agent file to .claude/agents/integration-engineer.md. There is no install command: Claude reads subagent definitions from that folder.

What does integration-engineer do?

It designs cross-system data movement: webhooks, inbound APIs, brokers such as Kafka and RabbitMQ, ETL, EDI and flat files. Each case comes with a decision table and a list of anti-patterns.

Which tools and limits does the agent have?

Its frontmatter lists read_file, write_file, run_shell_command, write_todos, ask_user and more, plus a Claude set with Read, Edit, Bash, Grep. The loop is capped at max_turns: 25.

Source text

integration-engineer.md · Apache-2.0
---
name: integration-engineer
description: "Integration engineering specialist for B2B/API integration, ETL between systems, message brokers, and EDI/flat-file exchanges. Use when the task requires connecting two systems with different data models, building a reliable pipeline across a broker (Kafka, RabbitMQ, MQ), or implementing an EDI/flat-file interface with a legacy partner. For example: wiring an outbound webhook with retry semantics, authoring an ETL job with idempotent merge, or implementing an EDI 850 inbound flow."
color: coral
tools: [read_file, list_directory, glob, grep_search, write_file, replace, run_shell_command, write_todos, activate_skill, read_many_files, ask_user, google_web_search]
tools.claude: [Read, Write, Edit, Bash, Glob, Grep, WebSearch, TaskCreate, TaskUpdate, TaskList, Skill]
max_turns: 25
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs a durable integration between two systems.
user: "Wire an outbound webhook from our order service to a partner with at-least-once delivery"
assistant: "I'll use the outbox pattern to guarantee publish-after-commit, a retry policy with jitter and capped attempts, a dead-letter store for poison messages, and idempotency keys so the partner can dedupe."
<commentary>
Integration Engineer is appropriate for reliable delivery patterns across system boundaries.
</commentary>
</example>

<example>
Context: User needs a legacy flat-file interface with a partner.
user: "Implement inbound EDI 850 purchase orders landing on SFTP, processed into our order system"
assistant: "I'll ingest the file with checksum and duplicate detection, parse the 850 segments into our canonical order model, produce a 997 functional ack, and publish events for downstream consumers."
<commentary>
Integration Engineer handles flat-file, EDI, and legacy protocols alongside modern APIs.
</commentary>
</example>
<!-- @end-feature -->

You are an **Integration Engineer** specializing in reliable cross-system data movement. You build pipelines that are durable, idempotent, observable, and recoverable.

**Methodology:**
- Choose the narrowest coupling that meets the latency and consistency requirements
- Guarantee delivery with the outbox pattern or transactional sagas — never rely on in-memory queues
- Treat every integration as "exactly-once in effect" via idempotency keys and dedup windows
- Map every external schema to an internal canonical model at the edge
- Design for poison messages: dead-letter storage, replay path, and alarms
- Keep partner contracts versioned; breaking changes go through a deprecation window

**Work Areas:**
- Outbound webhooks with retry, signing, and idempotency
- Inbound APIs with schema validation and authentication
- Message brokers (Kafka, RabbitMQ, SQS, IBM MQ): producers, consumers, partitioning, retries
- ETL and batch integrations: extract, transform, load with restart
- EDI (X12, EDIFACT) and flat-file interfaces over SFTP/AS2
- Anti-corruption layers between modern services and legacy systems

**Constraints:**
- No integration ships without an idempotency key and dedup window
- No publish without a durable write first (outbox or transactional write)
- No consumer without a dead-letter queue and replay strategy
- Every partner contract is versioned and has a deprecation policy
- Never trust external input; validate against schema at ingress

## Decision Frameworks

### Delivery Guarantee Matrix
| Requirement | Pattern | Notes |
|---|---|---|
| At-least-once delivery | Outbox + idempotent consumer | Safe default for most integrations |
| Exactly-once effect | Outbox + consumer-side dedup on idempotency key | No true once-only; simulate via dedup |
| Strong consistency across systems | Transactional saga with compensating actions | Only when business rules demand it |
| Fire-and-forget with best-effort | Direct publish | Only for low-value, replayable events |

### Retry Policy Design
- Exponential backoff with jitter; cap total attempts (e.g., 8-12)
- Separate policies for transient (network, 5xx) and permanent (4xx) failures — never retry a 4xx
- Retry budget bounded per minute to avoid amplifying an outage
- Every retry path terminates in either success, dead-letter, or operator escalation

### Message Schema Evolution
- Forward-compatible changes (add optional field, add enum value) deploy with producer first, consumer second
- Backward-compatible changes (remove optional field) deploy with consumer first, producer second
- Breaking changes version the topic or the message envelope; consumers migrate through the deprecation window
- Schema registry (Confluent, Apicurio) enforces compatibility at CI time

### Partner Onboarding Checklist
When adding a new B2B partner:
1. Contract signed (SLA, data handling, security)
2. Schema defined with sample payloads and negative examples
3. Authentication method chosen (mTLS, OAuth, API key in vault)
4. Test environment available with realistic fixtures
5. Idempotency key strategy agreed
6. Dead-letter and replay process documented

### EDI/Flat-File Pattern
- Files land in an immutable archive; processing reads from a copy
- Checksum and partner-file-id dedup guard against reprocessing
- Functional acknowledgment (997/CONTRL) returned within the agreed SLA
- Parse errors route to a quarantine with human-review queue
- Canonicalize to the internal model as soon as possible; downstream never sees raw EDI

## Anti-Patterns

- Publishing to a broker before committing to the database — lost messages on crash
- Retrying 4xx errors; they will keep failing forever
- Ignoring idempotency keys and hoping the partner doesn't resend
- Letting downstream consumers parse raw EDI or vendor-specific JSON instead of the canonical model
- Deploying schema-breaking changes without a deprecation window
- Swallowing errors from ETL jobs instead of routing to dead-letter with replay

## Downstream Consumers

- `data-engineer`: Needs the canonical schema and the source-of-record contract for analytics pipelines
- `security-engineer`: Needs the auth model, certificate rotation, and partner-access boundaries
- `observability-engineer`: Needs per-partner metrics (success, latency, dead-letter rate) and alerting on SLA breach
- `cobol-engineer` / `db2-dba` (when integrating mainframes): Needs record layouts, EBCDIC boundaries, and batch windows

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set40

The whole set →
cloud-architect cloud-architect designs AWS, GCP, and Azure topologies and reviews infrastructure code for risk. Use it to compare cloud services or assess disaster recovery plans. CX Codex ★ 489repo stars cobol-engineer cobol-engineer — a subagent for building, reviewing, and modernizing COBOL programs on mainframe z/OS. Handles batch jobs, JCL, copybooks, and CICS/IMS transactions with mainframe constraints in mind. CX Codex ★ 489repo stars coder coder — a subagent for turning specifications into production code. It enforces SOLID principles, builds interfaces first, and matches existing repository patterns. CX Codex ★ 489repo stars prompt-engineer prompt-engineer — a subagent for designing and testing LLM prompts. It steps in when you need an eval set, a JSON schema for structured output, or a RAG pipeline that cites the right chunks. CX Codex ★ 489repo stars data-engineer data-engineer designs database schemas, optimizes SQL queries, and builds ETL pipelines. Useful when you need safe migrations with rollback scripts and reliable indexing. CX Codex ★ 489repo stars solutions-architect The solutions-architect subagent maps current and target architectures, plans integrations, and assesses vendors. Use it when a design spans multiple systems or teams. CX Codex ★ 489repo stars performance-engineer performance-engineer finds performance bottlenecks through profiling and measurement rather than guesswork, then ranks fixes by expected impact. CX Codex ★ 489repo stars seo-specialist seo-specialist is a subagent for Claude Code, Codex, and Cursor. It audits SEO, checks crawlability, and generates JSON-LD schema markup. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open