ADR-019: Lifecycle procedures are agent-portable - Claude skills are the reference form


Status	Accepted
Date	2026-07-29
Author	Łukasz Bodurka
Tags	agents, skills, portability, manifest

Context

The manifest required .claude/skills and scripts/spec for the core profile, citing rules that never mention them: the CI-gate rule mandates that the guards gate CI, and the clarify rule mandates passing the gate - neither says a repo must carry a Claude-format skill directory. The practical consequence was worse than the citation gap: a team whose agent tooling is Cursor, Copilot or Windsurf could not reach drift 0 without committing another vendor's agent layout, which undercuts the "stack-agnostic Layer 1" positioning. Yet dropping the requirement entirely would gut the standard's core promise - the lifecycle procedures (the spec loop, backlog capture, pre-PR review, version updates) are the standard as executable behavior, and a repo without them has the documents but not the practice.

Options considered

A - Make the skills optional (required: false). Honest about vendors, but a compliant repo could then carry no executable procedures at all - the loop the standard exists for becomes a suggestion.
B - Ship the procedures for every agent vendor. Multiplies maintenance by the number of vendors, each with its own format churn; the standard would spend its energy tracking vendor formats instead of the method. Premature today.
C - One reference implementation, mandatory port (chosen). The procedures themselves become normative; the shipped Claude form is the reference; any other agent setup ports them - strictly and completely - to its own mechanism.

Decision

Option C. Concretely:

A new spec rule (R22) makes the lifecycle procedures normative: they MUST ship in the repo in a form the repo's coding agent can execute.
.claude/skills/ plus scripts/spec/ is the reference implementation - the paved road, shipped in the tree, required by the manifest.
A repo whose agent tooling is not Claude MUST port the shipped skills to its agent's own instruction mechanism (e.g. .agents/skills) - strictly, file by file, gates included - before claiming compliance. The manifest's altPaths accepts the ported location, so self-verify counts either form.
A partial port is drift, not a variant: the port carries every procedure and every gate, or the repo is not aligned.
The manifest entries for .claude/skills and scripts/spec cite R22 - the rule they actually enforce.

Consequences

Positive: the citation gap closes (every manifest entry names a rule that really demands it); non-Claude teams have a legal, verifiable path to drift 0; the procedures stay normative instead of becoming optional decoration.
Negative: "strictly and completely" is review-verified, not mechanical - self-verify can check the ported directory exists, not that the port is faithful; the port is real work for a non-Claude team, and it is on them to keep it current when the reference skills move.

Revisit when

A second agent format stabilizes enough (adoption + spec stability) that shipping it alongside the Claude form costs less than every adopter porting individually - then option B returns for that one format.