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.