Skip to content

ADR 0004 — Multi-package architecture with lockstep versions

Status: Accepted Date: 2026-08 Packages: all

Context

The SDK is split into focused distributions (core, providers, integrations, CLI, testing) rather than one package with optional extras. This shapes install UX and keeps framework/provider dependencies out of agentskills-core.

The cost is release coordination. Inter-package dependency floors can drift and produce import-time failures if one distribution resolves an older sibling.

Decision

Keep the multi-package architecture and enforce lockstep versioning.

  • Each package is independently published.
  • All packages share one release version per milestone.
  • Dependents require the matching agentskills-core floor for that release.
  • Release checks fail if versions or required floors drift.

Consequences

Good

  • Consumers install only what they need.
  • Core stays dependency-light and reusable.
  • Packaging boundaries match responsibility boundaries.

Costs

  • Release process is more complex than a monolith.
  • New packages must be wired into multiple scripts/workflows.
  • Version/floor checks are mandatory to avoid skew.

Alternatives considered

  • One package with extras: rejected for dependency bloat and weaker isolation between concerns.
  • Independent package versioning: rejected for current cadence and dependency coupling; lockstep keeps compatibility obvious before 1.0.

Decision history