Skip to content

Architecture decision records

ADRs capture cross-package decisions that are expensive to re-litigate. Use them for architecture choices that constrain providers, integrations, release process, or public behavior.

Numbering and file names

  • Number sequentially: 0001, 0002, 0003, ...
  • Use a short slug: docs/adr/0009-meaningful-slug.md
  • Never renumber existing ADRs

Status values

  • Accepted for current decisions
  • Superseded by ADR XXXX when replaced
  • Superseded in part when a later release replaced one aspect and the rest still applies
  • Proposed for an in-flight decision

Template

# ADR XXXX — Short title

**Status:** Accepted
**Date:** YYYY-MM
**Packages:** `agentskills-core`, `agentskills-fs`

## Context

What changed, what constraints matter, and why this needed a decision.

## Decision

What we chose and the concrete rule.

## Consequences

### Good

- Benefits and why this is worth the trade.

### Costs

- Ongoing costs, coupling, or limitations.

## Alternatives considered

- Rejected option and why.

## Decision history

- Link to the issue or PR where the decision was made.

Index

  • ADR 0001 — MCP context provider packaging (superseded in v0.7)
  • ADR 0002 — Optional provider capabilities
  • ADR 0003 — Fully async provider interface
  • ADR 0004 — Multi-package lockstep versioning
  • ADR 0005 — Provider caching and invalidation
  • ADR 0006 — Exception taxonomy
  • ADR 0007 — Binary resource envelope (superseded in part)
  • ADR 0008 — Logging conventions
  • ADR 0009 — Native image content, opt-in (superseded in part)
  • ADR 0010 — Native Skills only, no legacy compatibility mode
  • ADR 0011 — Publication pipeline: verify, transform, refresh atomically