api-reference

API Reference

Complete reference for the AI-SDLC packages.

Orchestrator (@ai-sdlc/orchestrator)

The orchestrator runtime — CLI, agent runners, codebase analysis, and state store.

Module	Description
Runners	Agent runners (Claude Code, Copilot, Cursor, Codex, GenericLLM) and runner registry
Parallel Execution	Worktree pool, harness adapter, database branch adapter, subscription plan / ledger (RFC-0010)

SDK (@ai-sdlc/reference)

The TypeScript reference implementation, structured as a single package with 12 modules:

@ai-sdlc/reference
├── core/         — Types, validation, provenance, comparison
├── builders/     — Fluent resource builders for all 5 resource types
├── policy/       — Enforcement, autonomy, authorization, admission
├── adapters/     — Interface contracts, built-in + stub adapters
├── agents/       — Orchestration patterns, execution, memory, discovery
├── reconciler/   — Controller loop, diff, resource reconcilers
├── audit/        — Hash-chained audit log with pluggable sinks
├── metrics/      — Metric store, standard metrics, instrumentation
├── telemetry/    — OpenTelemetry tracing, structured logging
├── security/     — Sandbox, JIT credentials, kill switch, approvals
└── compliance/   — Regulatory framework mapping and checking

Import Patterns

All exports are available from the root:

import { validate, enforce, PipelineBuilder } from '@ai-sdlc/reference';

Module Reference

Module	Package	Description	Key Exports
Runners	@ai-sdlc/orchestrator	Agent runners and registry	ClaudeCodeRunner, CopilotRunner, CursorRunner, CodexRunner, GenericLLMRunner, RunnerRegistry, createRunnerRegistry
Core	@ai-sdlc/reference	Types, validation, provenance	validate, validateResource, createProvenance, API_VERSION
Builders	@ai-sdlc/reference	Fluent resource construction	PipelineBuilder, AgentRoleBuilder, QualityGateBuilder, AutonomyPolicyBuilder, AdapterBindingBuilder
Policy	@ai-sdlc/reference	Enforcement and authorization	enforce, evaluatePromotion, authorize, admitResource, parseDuration
Adapters	@ai-sdlc/reference	External tool integrations	IssueTracker, SourceControl, CIPipeline, createAdapterRegistry
Agents	@ai-sdlc/reference	Multi-agent orchestration	sequential, parallel, executeOrchestration, validateHandoff
Reconciler	@ai-sdlc/reference	Controller loop pattern	ReconcilerLoop, reconcileOnce, resourceFingerprint
Audit	@ai-sdlc/reference	Tamper-evident audit logging	createAuditLog, createFileSink, computeEntryHash
Metrics	@ai-sdlc/reference	Metric collection and querying	createMetricStore, STANDARD_METRICS
Telemetry	@ai-sdlc/reference	OpenTelemetry + structured logging	withSpan, createConsoleLogger, createBufferLogger
Security	@ai-sdlc/reference	Enterprise security primitives	Sandbox, KillSwitch, JITCredentialIssuer, ApprovalWorkflow
Compliance	@ai-sdlc/reference	Regulatory framework coverage	checkCompliance, checkAllFrameworks, getAllControlIds

Resource Types

Five core resource types, all sharing the same envelope:

Kind	Schema	Spec Reference
Pipeline	pipeline.schema.json	spec.md#5.1
AgentRole	agent-role.schema.json	spec.md#5.2
QualityGate	quality-gate.schema.json	spec.md#5.3
AutonomyPolicy	autonomy-policy.schema.json	spec.md#5.4
AdapterBinding	adapter-binding.schema.json	spec.md#5.5

Common definitions (metadata, conditions, secretRef, duration) are in common.schema.json.

Quick Start

import {
  PipelineBuilder,
  QualityGateBuilder,
  enforce,
  validateResource,
} from '@ai-sdlc/reference';

// Build a pipeline
const pipeline = new PipelineBuilder('my-pipeline')
  .addTrigger({ event: 'issue.assigned' })
  .addProvider('issueTracker', { type: 'linear' })
  .addStage({ name: 'implement', agent: 'code-agent' })
  .build();

// Validate it
const result = validateResource(pipeline);
console.log(result.valid); // true

// Build and enforce a quality gate
const gate = new QualityGateBuilder('standards')
  .addGate({
    name: 'coverage',
    enforcement: 'soft-mandatory',
    rule: { metric: 'line-coverage', operator: '>=', threshold: 80 },
  })
  .build();

const enforcement = enforce(gate, {
  authorType: 'ai-agent',
  repository: 'org/repo',
  metrics: { 'line-coverage': 85 },
});
console.log(enforcement.allowed); // true

Adapter Interfaces

See adapters.md for the full normative interface contracts.

Cross-Cutting Concerns

Topic	Reference	Spec
Cost governance	cost.md	RFC-0004