integration-design

Integration Design

Quick Start

Assume the Integration Architect Agent role from agents/integration-architect.md: clarify producers, consumers, business triggers, interface contracts, data ownership, integration pattern, operational behavior, security, failure handling, and support ownership.

Use templates/integration-design-template.md as the output structure. Replace placeholders and drafting guidance with concrete content; do not leave unanswered sections unless the unknown is explicitly marked as TBD or an open question.

Store generated integration designs under the consuming repository's private lab root in integrations/.

integrations/int-0001-<data-object>-from-<source>-to-<destination>.md
integrations/_integrations-overview.md

Each integration filename must start with int-, then a 4-digit sequence number, then the canonical data object, source, and destination:

int-0001-order-from-commerce-to-erp.md
int-0002-customer-from-crm-to-commerce.md

Start at int-0001. For new files, inspect existing integrations/int-*.md files, choose the next available 4-digit number, and preserve gaps unless the user explicitly asks to renumber.

Do not write real-company integration details into this public toolkit repository.

Required Inputs

• Integration name and business purpose
• Integration status, for example Proposed, In design, Approved, Implemented, or Deprecated
• Source system or producer
• Target system or consumer
• Main canonical data object
• Triggering event, process step, schedule, or user action
• Integration pattern: synchronous API, event-driven, batch, file transfer, messaging, or orchestration
• Payload, data object, schema, endpoint, topic, queue, file, or message contract
• Security, privacy, operational, and support constraints
• Failure handling, retry, idempotency, observability, and ownership expectations

Workflow

1. Ask which capability, target architecture, solution architecture design, epic, or ADR the integration supports.
2. Ask for the source system, target system, business trigger, integration pattern, and business data involved when not already provided.
3. Read related architecture documents when paths are provided.
4. Validate terminology against <private-lab-root>/GLOSSARY.md. If important terms, applications, data objects, jargon, deprecated terms, or words to avoid are missing or ambiguous, use ../ubiquitous-language/SKILL.md to update the private lab glossary before writing the design.
5. Determine the output path under <private-lab-root>/integrations/:
   • Create the folder if needed.
   • Scan existing files matching int-[0-9][0-9][0-9][0-9]-*.md.
   • Use the next available 4-digit sequence number, starting with 0001.
   • Derive <data-object> from the canonical data object being exchanged.
   • Derive <source> from the source system or producer.
   • Derive <destination> from the target system or consumer.
   • Build the filename as int-<4-digits>-<data-object>-from-<source>-to-<destination>.md.
6. Create or update the integration design from templates/integration-design-template.md. Preserve the two opening tables: the document metadata table first, followed by the Integration Overview table.
7. Populate the top metadata table with document tracking values from the template.
8. Populate the ## Integration Overview table with concise concrete values so agents can understand the integration status, purpose, source, destination, data object, trigger, pattern, and open-question count without reading the full document. Keep Purpose to one sentence under 25 words.
9. After writing the ## Integration Overview table and description, create a visual integration diagram:
   • Use the create-drawio-diagram skill and its templates/integration-design.drawio template.
   • Create a diagrams/ subfolder in the same folder as the integration design document.
   • Store the .drawio file and exported .svg file in that diagrams/ subfolder.
   • Use the same basename as the integration design Markdown file. For example, int-0001-product-from-pim-to-commerce.md, diagrams/int-0001-product-from-pim-to-commerce.drawio, and diagrams/int-0001-product-from-pim-to-commerce.svg.
   • Populate the diagram with the integration's confirmed source, destination, intermediate components, layer placement, application headers, and connector labels.
   • Do not add separate data-contract, payload, message, or file boxes to the diagram. Capture detailed contract and payload information in the ## Contract section instead.
   • Do not add monitoring, reconciliation, run-status, failed-record, stale-index, alerting, dashboard, or support components to the diagram. Capture those details in ## Security and Operations instead.
   • Route connectors on clear orthogonal lanes. No connector or connector label may overlap a component, application header, layer label, arrowhead, or another connector label.
   • Prefer vertical flow columns for direct layer-to-layer paths. Place related components above and below each other and connect them top-to-bottom where space allows.
   • Use horizontal placement for peer components, branches, alternatives, fan-out/fan-in paths, or same-layer handoffs, not for a simple linear layer-to-layer path.
   • Use a left-biased component layout: start components near the left content margin and grow the canvas to the right as more components or connector lanes are needed.
   • Leave enough horizontal room for labeled connectors: at least 160 px between connected component edges, or 220 px for longer connector labels.
   • Treat the canvas and layer bands as flexible. If the diagram is crowded, increase canvas width or height, increase layer width or height, spread components apart, shorten connector labels, or add explicit Draw.io waypoints before exporting.
   • Export the .drawio file to a same-basename .svg.
   • Run the create-drawio-diagram SVG sanitizer on the exported SVG so it uses color-scheme: light, has no light-dark(...) values, and includes a light background.
   • Embed the .svg directly in ## Integration Overview using the relative path diagrams/<same-basename>.svg.
10. Add ## Business Summary immediately after the diagram. Cover business outcome, operational impact, failure impact, and ownership before contract detail.
11. Populate ## Relevant Links with every confirmed related document, including capability overview, target architecture, solution architecture design, epic, ADR, or other integration designs. Use the linked document name as the Markdown link label.
12. Run the glossary compliance gate before finishing the integration design:

• Read <private-lab-root>/GLOSSARY.md.
• In the Glossary, find the Jargon section and its Avoid list.
• Search the generated integration design Markdown for each avoided word or phrase.
• Replace avoided wording with the preferred glossary term when one is available.
• If no preferred term is available, rewrite the sentence in plain language or add an open question rather than leaving the avoided wording in the design.
• Repeat the search after edits until no avoided terms remain, except inside explicit glossary references or quoted source text.

1. Run the check-readability skill before finishing:

• Assess the full integration design and update the top-table Readability Score value.
• Aim for a full-document Flesch Reading Ease score of 30 or higher.
• Assess the opening sections through ## Business Summary separately and aim for 40-50.
• If the opening score is below 40, simplify the opening sections first rather than removing necessary technical detail from later sections.

1. Update <private-lab-root>/integrations/_integrations-overview.md with the integration identifier, name, status, description, and count of open questions in the integration design.
2. Capture unresolved facts as open questions rather than inventing payloads, endpoints, schemas, retry rules, owners, or service-level expectations.
3. Link the integration design from the related target architecture, solution architecture design, capability overview, epic, or relevant links section when the related document exists and the user confirms the linkage. Whenever a link to the integration design is added to one of those documents, add the reciprocal link back to that document in the integration design's ## Relevant Links section.