AI-SDLC Adapter Layer Specification

Document type: Normative Status: Draft Spec version: v1alpha1

Table of Contents

1. Introduction
2. Interface Contracts
3. Infrastructure Adapters
4. Adapter Registration
5. Adapter Discovery
6. Configuration and Secret Handling
7. Custom Distribution Builder

1. Introduction

The adapter layer provides tool-agnostic integration by defining typed interface contracts for each integration category. Following Terraform's provider model, each adapter is a standalone module implementing one or more interfaces. Swapping one tool for another (e.g., Linear for Jira, GitHub for GitLab) requires changing only the type field in the AdapterBinding resource — pipeline definitions remain unchanged.

2. Interface Contracts

Every adapter MUST implement at least one of the following interface contracts. Each contract defines the methods an adapter MUST provide.

2.1 IssueTracker

Adapters for issue and project management tools (e.g., Linear, Jira, GitHub Issues).

listIssues(filter: IssueFilter): Issue[]
getIssue(id: string): Issue
createIssue(input: CreateIssueInput): Issue
updateIssue(id: string, input: UpdateIssueInput): Issue
transitionIssue(id: string, transition: string): Issue
watchIssues(filter: IssueFilter): EventStream<IssueEvent>

IssueFilter:

Issue:

2.2 SourceControl

Adapters for source code management platforms (e.g., GitHub, GitLab, Bitbucket).

createBranch(input: CreateBranchInput): Branch
createPR(input: CreatePRInput): PullRequest
mergePR(id: string, strategy: MergeStrategy): MergeResult
getFileContents(path: string, ref: string): FileContent
listChangedFiles(prId: string): ChangedFile[]
setCommitStatus(sha: string, status: CommitStatus): void
watchPREvents(filter: PRFilter): EventStream<PREvent>

MergeStrategy: One of merge, squash, rebase.

PullRequest:

CommitStatus:

2.3 CIPipeline

Adapters for continuous integration systems (e.g., GitHub Actions, GitLab CI, Jenkins).

triggerBuild(input: TriggerBuildInput): Build
getBuildStatus(id: string): BuildStatus
getTestResults(buildId: string): TestResults
getCoverageReport(buildId: string): CoverageReport
watchBuildEvents(filter: BuildFilter): EventStream<BuildEvent>

TestResults:

CoverageReport:

2.4 CodeAnalysis

Adapters for static analysis and security scanning tools (e.g., SonarQube, Semgrep, CodeQL).

runScan(input: ScanInput): ScanResult
getFindings(scanId: string): Finding[]
getSeveritySummary(scanId: string): SeveritySummary

Finding:

SeveritySummary:

2.5 Messenger

Adapters for communication platforms (e.g., Slack, Microsoft Teams).

sendNotification(input: NotificationInput): void
createThread(input: ThreadInput): Thread
postUpdate(threadId: string, message: string): void

NotificationInput:

2.6 DeploymentTarget

Adapters for deployment platforms (e.g., Kubernetes, AWS, Vercel).

deploy(input: DeployInput): Deployment
getDeploymentStatus(id: string): DeploymentStatus
rollback(id: string): Deployment
watchDeploymentEvents(filter: DeployFilter): EventStream<DeployEvent>

DeploymentStatus:

3. Infrastructure Adapters

In addition to the six SDLC interface contracts above, the adapter layer defines five infrastructure adapter interfaces for runtime concerns. These follow the same AdapterBinding resource model and adapter registry — the distinction is informative, not structural.

SDLC adapters integrate with external development tools (issue trackers, source control, CI systems). Infrastructure adapters abstract runtime concerns (audit storage, sandboxing, secret management, memory persistence, event delivery) so that deployments can swap backends without modifying pipeline definitions.

3.1 AuditSink

Adapters for audit log storage, querying, and lifecycle management.

write(entry: AuditEntry): void
query?(filter: AuditFilter): AuditEntry[]
rotate?(): void
close?(): void

An adapter MUST implement write(). The query(), rotate(), and close() methods are OPTIONAL — backends that do not support querying or rotation MAY omit them.

AuditEntry: See spec.md for the full audit entry schema including tamper-evident hash chain fields.

3.2 Sandbox

Adapters for agent task isolation (e.g., Docker, Firecracker, GitHub Codespaces).

isolate(taskId: string, constraints: SandboxConstraints): string
destroy(sandboxId: string): void
getStatus(sandboxId: string): SandboxStatus

All three methods are MUST-implement. SandboxConstraints includes maxMemoryMb, maxCpuPercent, networkPolicy, timeoutMs, and allowedPaths. SandboxStatus is one of: idle, running, terminated, error.

3.3 SecretStore

Adapters for secret resolution and management (e.g., environment variables, Vault, AWS Secrets Manager).

get(name: string): string | undefined
getRequired(name: string): string
set?(name: string, value: string, ttl?: number): void
delete?(name: string): void

An adapter MUST implement get() and getRequired(). The set() and delete() methods are OPTIONAL — read-only stores (e.g., environment variables) MAY omit them. getRequired() MUST throw when the secret is not found.

3.4 MemoryStore

Persistence backend for the five-tier agent memory model. The tier interfaces (WorkingMemory, LongTermMemory, etc.) remain unchanged — MemoryStore is the storage layer underneath them.

read(key: string): unknown | undefined
write(key: string, value: unknown): void
delete(key: string): void
list(prefix?: string): string[]

All four methods are MUST-implement. This is a simple key-value interface that can be backed by files, Redis, DynamoDB, or any other storage system.

3.5 EventBus

Adapters for event publication and subscription (e.g., in-process EventEmitter, NATS, Kafka, cloud pub/sub).

publish(topic: string, payload: unknown): void
subscribe(topic: string, handler: (payload: unknown) => void): Unsubscribe

Both methods are MUST-implement. subscribe() returns an unsubscribe function. Implementations SHOULD deliver events asynchronously.

4. Adapter Registration

Every adapter MUST include a metadata.yaml file at its root. This file declares the adapter's identity, capabilities, and compatibility.

name: linear
displayName: "Linear Issue Tracker"
description: "Adapter for Linear project management"
version: "1.2.0"
stability: beta
interfaces:
  - IssueTracker@v1
owner: "@reliable-genius/adapters-team"
repository: "https://github.com/ai-sdlc-framework/adapter-linear"
specVersions: ["v1alpha1"]
dependencies:
  runtime: ">=0.1.0"

Required metadata fields:

5. Adapter Discovery

Adapters MUST be discoverable from one of three sources:

5.1 Registry

The primary discovery mechanism. Adapters are published to a registry and referenced by name and version:

registry.ai-sdlc.io/adapters/<name>@<version>

Implementations MUST resolve registry references to their metadata and download the adapter.

5.2 Local Directory

For development and testing, adapters MAY be loaded from a local directory:

./adapters/<name>/

The directory MUST contain a valid metadata.yaml file.

5.3 Git Reference

Adapters MAY be referenced by git repository and version tag:

github.com/org/adapter-name@version

Implementations SHOULD cache git-referenced adapters locally after initial resolution.

6. Configuration and Secret Handling

Adapter configuration is declared in the AdapterBinding resource's spec.config field. This field is an open object (additionalProperties: true) to accommodate adapter-specific configuration.

6.1 Secret References

Sensitive configuration values (API keys, tokens) MUST NOT be embedded directly in resource definitions. Instead, they MUST use the secret reference pattern:

config:
  apiKey:
    secretRef: linear-api-key
  teamId: "ENG"

Implementations MUST resolve secretRef values at runtime from a configured secret store. The secret resolution mechanism is implementation-defined but MUST support at least environment variables.

6.2 Configuration Validation

Adapters SHOULD provide a JSON Schema for their config object. When provided, implementations SHOULD validate adapter configuration against this schema during resource admission.

7. Custom Distribution Builder

Following OpenTelemetry's Collector Builder pattern, implementations MAY provide a builder tool that assembles custom distributions from a manifest declaring the desired set of adapters.

# builder-manifest.yaml
spec_version: v1alpha1
adapters:
  - name: linear
    version: "1.2.0"
  - name: github
    version: "2.0.0"
  - name: semgrep
    version: "1.0.0"
  - name: slack
    version: "1.1.0"
output:
  name: my-ai-sdlc
  version: "1.0.0"

The builder manifest MUST declare:

This enables organizations to build minimal, auditable distributions containing only the adapters they need.