Spec-Driven Integration (SDI)¶
Spec-Driven Integration (SDI) is a methodology for designing, operating, and governing integrations between systems — derived from the broader principles of Spec-Driven Development (SDD) and applied specifically to the integration domain.
Where SDD addresses the gap between intent and implementation in software, SDI addresses the equivalent gap in integration: the distance between what a system should expose or consume and how that contract is actually implemented and maintained. As organizations accumulate dozens or hundreds of API endpoints — internal services, third-party providers, AI model APIs, agent orchestration surfaces — that gap becomes the primary source of fragility, duplication, and operational cost.
SDI treats this not as a tooling problem, but as a specification problem.
The Integration Problem¶
Modern integration is characterized by three compounding challenges:
- API sprawl: Systems expose endpoints that are inconsistently shaped, poorly documented, and duplicated across teams and contexts.
- Context fragmentation: AI-driven workflows depend on access to the right data, in the right shape, at the right time — but integration layers are often too coarse or too opaque to provide this reliably.
- Drift between intent and behavior: Integration logic is encoded in code, configuration, and institutional knowledge rather than in durable, inspectable artifacts. As systems evolve, intent diverges from behavior invisibly.
SDI addresses these challenges by making the specification the primary integration artifact — not a byproduct.
Core Principles¶
Specifications as the Lingua Franca
The integration specification is the single source of truth. It defines what is consumed from upstream systems, how inputs and outputs are shaped and composed, and what is re-exposed downstream. Maintaining an integration means evolving its specification. Everything else is derived.
Executable Specifications
A specification is only valuable if it is precise, complete, and unambiguous enough to produce working integrations directly. SDI rejects the idea that specifications are documentation written after the fact. When a specification cannot be executed as-is, the gap is a signal of incompleteness — not an invitation for interpretation.
Continuous Refinement
Integration consistency is not validated at a single gate. Specifications are continuously analyzed for ambiguity, internal contradiction, and gaps — ideally with AI assistance — throughout their lifecycle. This surfaces intent mismatches early, before they reach production.
Research-Driven Context
Specifications are informed by research, not intuition. Decisions about how to shape upstream consumption, how to model domain concepts, and how to expose integration surfaces should be grounded in technical context, operational constraints, and organizational requirements — gathered as part of the specification process itself.
Bidirectional Feedback
Production behavior feeds back into specification evolution. Metrics, incidents, and real-world usage patterns are inputs for refining specifications — not just signals for operational teams. The specification remains a living artifact, not a snapshot.
Branching for Exploration
A single specification can give rise to multiple integration variants, each optimized for a different target: performance, cost, consumer type, or context granularity. Exploration and experimentation happen at the specification level, not in the implementation layer.
Implementation Approaches¶
SDI as a methodology is tool-agnostic, but it requires concrete artifacts to be effective: a specification format expressive enough to capture integration intent, and a runtime capable of executing that specification without translation.
In practice, SDI organizes these artifacts around the capability — a self-contained, specification-defined unit of business value. Capabilities are authored as declarative specifications, executed by a runtime engine that reads them directly (no code generation), grouped into runtime cells called ships, and federated into fleets for enterprise-wide governance.
The capability model — its four dimensions, the engine that runs it, and the ship/fleet topology that scales it — is described in detail in Capability-driven AI integration.
The SDI Workflow
Together, these layers define a concrete SDI workflow:
- Specify — Author a capability specification that captures the integration intent.
- Validate — Analyze the spec for completeness, consistency, and ambiguity before execution.
- Execute — Run the engine against the specification; no code generation or compilation required.
- Refine — Evolve the specification based on production feedback, consumer requirements, or AI-assisted analysis.
This cycle keeps the specification as the primary artifact throughout — ensuring that what is deployed always reflects documented intent.
SDI and AI Integration¶
SDI is particularly well-suited to the demands of AI-driven architectures. Context engineering — shaping, filtering, composing and securing data for AI model consumption — is fundamentally an integration problem. Agent orchestration surfaces, such as MCP servers and tool-based APIs, require exactly the kind of right-sized, semantically coherent integration boundaries that SDI is designed to produce.
When specifications are the primary artifact, AI agents can reason about integrations, propose refinements, and validate consistency — treating the specification as a structured, inspectable contract rather than opaque runtime behavior.
A Deterministic Foundation for Agents
AI agents are powerful reasoning engines, but they are non-deterministic by nature — their outputs vary across invocations, they can hallucinate plausible-but-wrong API contracts, and they have no built-in mechanism to guarantee that a tool call today behaves the same as it did yesterday. This is acceptable for generation tasks; it is unacceptable for integration, where correctness, repeatability, and auditability are non-negotiable.
SDI addresses this by placing a deterministic layer beneath the agent. The capability specification defines — precisely and immutably for a given version — what data is consumed, how it is shaped, and what contract is exposed. The engine executes that specification without interpretation. There is no room for the runtime to invent a field, guess a mapping, or silently change a response shape. What the spec declares is what the agent receives.
This deterministic foundation reduces two categories of risk that compound in agent-driven architectures:
- Drift risk: When integration logic lives in code maintained by multiple teams — or worse, in prompts and agent memory — behavior drifts invisibly over time. SDI anchors integration behavior to a versioned, diffable artifact. If the spec has not changed, the integration has not changed. Drift becomes visible as a spec delta, not as a mysterious production incident.
- Hallucination risk: Agents tasked with calling APIs or composing tool outputs can fabricate parameter names, assume response structures, or invent error-handling paths that do not exist. When integrations are mediated by a spec-driven engine, the agent operates against a declared contract — not against its own inference of what the API might return. The specification constrains the agent to reality.
Together, these properties enable operational governance of AI: organizations can audit what an agent can access, review what transformations are applied, version-control every change, and enforce approval workflows — all through the specification. Governance shifts from monitoring opaque agent behavior after the fact to controlling the integration contracts agents depend on before deployment. The specification becomes the governance surface.
Deterministic Linting for Agent-Generated Specs
The same agents that consume capabilities are increasingly the ones writing them. Capability specifications are now produced inside generate-validate-retry loops, where an LLM proposes a spec, a deterministic checker validates it, and the agent iterates on the feedback. In that loop, the validator is the only component that does not drift between runs — and therefore the only one that can guarantee the spec is actually shippable.
Schema validation alone is insufficient at this scale. A capability can be schema-valid yet structurally broken: a baseUri with a trailing slash, two adapters bound to the same port, an input declared but never referenced in any step, a call pointing at a non-existent operation. These flaws parse cleanly, pass JSON Schema, and only surface at runtime — exactly the failure mode SDI is meant to prevent. Deterministic linting closes that gap with composable layers — well-formedness, schema-model, ruleset, and format-aware checks — applied uniformly to every spec, whether authored by a human or emitted by an agent.
For SDI, and especially for capability-driven AI integration, this layer is not optional. It is what makes specifications trustable artifacts in an agent-driven workflow: the deterministic counterweight to non-deterministic authoring. In the Naftiko stack, Polychro fills this role — embeddable in agent loops via its MCP server, runnable in CI via its CLI or GitHub Action, and aware of capability domain invariants out of the box.