Skip to main content
nexlem

Nexlem Stability Contract

This document classifies every consumer-facing surface of Nexlem into one of three tiers and states the deprecation policy for each tier. Consumers — both scripts automating against nexlem-sdk query and humans using /nexlem skill commands — can use this document to understand what they can depend on and what may change.

Scope: This contract covers the v2.2.0 surface. Surfaces not listed here carry no stability promise until explicitly classified in a future release.

Tier Definitions

TierMeaning
stableThe interface is frozen. Removing or breaking it requires a deprecation notice in the announcing release and removal no sooner than the next minor version (vN to vN+1).
evolvingThe interface may change between releases. Changes are documented in CHANGELOG.md. No formal deprecation window is required.
experimentalThe interface may change or be removed at any time without notice. Not suitable for automation.

SDK Queries (Machine/Wire Contract)

The nexlem-sdk query namespace is a machine/wire contract: scripts and automation pipelines depend on the JSON output shapes. The --json output shapes for stable-tier handlers are frozen by tests/unit/stable-sdk-shapes.test.ts — a failing test in that file means a breaking shape change has occurred.

NamespaceTierSince
nexlem-sdk query versionstablev2.2.0
nexlem-sdk query state.healthystablev2.2.0
nexlem-sdk query setup.checkstablev2.2.0
nexlem-sdk query skill.inventoryevolvingv2.2.0
nexlem-sdk query wizard.validateevolvingv2.2.0

Stable JSON output shapes (keys and types are frozen; values may vary):

  • nexlem-sdk query version → { "version": string }
  • nexlem-sdk query state.healthy → { "ok": boolean, "reason"?: string, "checks": Array<{ "name": string, "status": string, "detail"?: string }> }
  • nexlem-sdk query setup.check → { "ok": boolean, "reason"?: string, "checks": Array<{ "name": string, "status": string, "detail"?: string }> }

The golden-file tests that enforce these shapes live at: tests/unit/stable-sdk-shapes.test.ts

Any change to a stable handler's output shape that breaks those tests is a breaking change and must follow the stable deprecation policy below.

Skills Surface (Interactive User Commands)

The /nexlem skill commands are an interactive user surface: a human invokes them from Claude Code. The skills surface is classified separately from the SDK query surface because its consumers are humans, not scripts, and its guarantees are different.

All /nexlem skills are evolving as of v2.2.0. No skill is promoted to stable in the initial public release — the command surface has iterated significantly across milestones and freezing names now would be premature. Promotion to stable will be announced in a future release with a corresponding CHANGELOG entry.

Only top-level /nexlem commands are listed below — these match the 18 commands in the auto-generated docs/SKILLS.md. Flow files (e.g. campaign-create, calendar-planning) are internal sub-skills loaded on demand by a router skill; they are not directly invocable as /nexlem commands and so are not part of the skills surface contract.

Skill CommandTierSince
/nexlem backupevolvingv2.2.0
/nexlem calendarevolvingv2.2.0
/nexlem campaignevolvingv2.2.0
/nexlem contentevolvingv2.2.0
/nexlem helpevolvingv2.2.0
/nexlem initevolvingv2.2.0
/nexlem keywordsevolvingv2.2.0
/nexlem nextevolvingv2.2.0
/nexlem pipelineevolvingv2.2.0
/nexlem reconfigureevolvingv2.2.0
/nexlem runevolvingv2.2.0
/nexlem setupevolvingv2.2.0
/nexlem siloevolvingv2.2.0
/nexlem siteevolvingv2.2.0
/nexlem statusevolvingv2.2.0
/nexlem uninstallevolvingv2.2.0
/nexlem updateevolvingv2.2.0
/nexlem weekevolvingv2.2.0

Deprecation Policy

The deprecation policy is tied directly to the tier of the interface being changed. There is no universal deprecation timeline — the tier is the contract.

Stable tier

Breaking or removing a stable interface requires:

  1. A deprecation notice published in the release that announces the intended removal. The notice must describe what is changing, why, and what the replacement (if any) is.
  2. Removal no sooner than the next minor version (vN.x to vN+1.0). For example, a deprecation announced in v2.2.0 may not be removed until v2.3.0 at the earliest.

A "breaking change" to a stable SDK query means: removing a field, renaming a field, changing a field's type, or changing the query's exit codes in a way that breaks existing scripts. Adding new optional fields to a stable query response is NOT a breaking change.

Evolving tier

Interfaces in the evolving tier may change between releases. Changes must be documented in CHANGELOG.md with a clear description of what changed. No formal deprecation window is required, but best-effort advance notice is appreciated when feasible.

Experimental tier

Interfaces in the experimental tier may change or be removed at any time without notice or CHANGELOG entry. Do not build automation against experimental interfaces.

  • tests/unit/stable-sdk-shapes.test.ts — machine-checked contract for stable SDK query shapes
  • docs/SDK_REFERENCE.md — full documentation for all nexlem-sdk query handlers
  • docs/RELEASING.md — maintainer release process (cross-reference; deprecation policy lives here, not there)
  • CHANGELOG.md — per-release record of changes to evolving interfaces

Edit this page on GitHub