ADR-009: Skills are lifecycle or transition - and transition skills never ship


Status	Accepted (2026-07-22)
Date	2026-07-21 (revised 2026-07-22 while Proposed)
Author	Łukasz Bodurka
Tags	skills, dist, lifecycle, adoption

Context

The skills are two different kinds of thing. Some ARE the ways of working - a repo uses spec-impact or pre-pr-review on every change, for life. Others exist only to get a repo TO the standard - align-to-standards, onboard-repo, modernize, greenfield-start - they are the standard repo's own utility, not the target repo's process.

dist/ initially shipped all thirteen as one undifferentiated set. The owner's call (2026-07-22): that is a separation error - dist/ is the resulting repository, and conversion machinery does not belong in the result. The decisive proof: greenfield-start runs before the target repo even exists - it cannot possibly be a file inside it.

Options considered

A - No distinction (initial state). Simplest; but every aligned repo permanently carries scaffolding, and an agent reading its .claude/skills/ sees one-shot conversion machinery presented as daily process.
B - Transition skills never ship; they run from the standard repo (chosen). The transition is always driven by an agent pointing at the standard ("align this repo to <standard>@<version>") - so the transition skills execute from the standard's checkout/fetch, exactly like greenfield-start already must. The target repo only ever receives what it keeps.
C - Ship both, classify, clean up at aligned (the first draft of this record). Works, but ships debris only to delete it later, needs a reliable cleanup, and re-materialization logic in update-to-version. Complexity purchased for nothing option B does not already give.

Decision

Option B. Classes:

Lifecycle (ship, stay forever): spec-analyze, spec-converge, spec-impact, spec-reconcile, spec-update, add-to-backlog, backlog-from-specs, pre-pr-review, update-to-version (recurring maintenance - it keeps the repo on the standard).
Transition (never shipped): align-to-standards, onboard-repo, modernize, greenfield-start. They live in the standard repo only (skills/), are guarded source-only by reflect.mjs, and run in the agent's context when the user points a repo at the standard.

SKILL-1 shrinks accordingly: no cleanup-of-skills machinery is needed; self-verify just flags transition skills if found inside an aligned repo (a hand-copy mistake).

Consequences

Positive: dist/ is purely "what the target repo keeps"; no cleanup logic, no re-materialization; the utility-vs-skeleton separation the owner asked for is structural, not procedural.
Negative: a transition needs the standard repo reachable (fetch/degit) - already true of align/update by design; offline transition of an air-gapped repo requires bringing the standard checkout along.

Confirmation

standard/.claude/skills/ contains exactly the lifecycle set named in the class table (root AGENTS.md - eleven since the engine extraction, ADR-015); tree-check fails if a transition skill leaks into the tree; self-verify flags transition skills found in a consuming repo. (2026-07-22 note: the original confirmation said "exactly nine in dist/" - the count and the paths moved with ADR-014/ADR-015; the class rule is unchanged. The lifecycle set is now the 11-skill spec-* family (analyze/converge/backlog-from-specs folded away), the leak guard is tree-check.mjs, and modernize lives as adoption's plan-then-refactor pass.)

Revisit when

Skills gain a plugin/marketplace distribution (then nothing may need shipping in dist/), or a real air-gapped adoption case appears.

ADR-008 (three zones - this is the zones rule applied to skills), ADR-010 (lifecycle; its ephemeral class covers plan/tasks and idea docs - transition skills are simply never in the target at all), SKILL-1 in backlog.md.