Spec Stewardship
Overview
The spine is only valuable if its specs stay well maintained, groomed, and preserved. This
skill owns the care of the living specs after epic-planning has
authored an EPIC and PLAN: moving a change through its lifecycle, merging its deltas into the
durable truth, grooming that truth, and keeping the cheap orientation index honest.
It does not author EPICs/PLANs (that is epic-planning) and does not define the schema or
conventions (those live in spine/) — it runs them.
The change lifecycle (maps to /opsx — see spine/workflows.md)
author in openspec/changes/<id>/ (epic-planning: proposal.md + design.md + tasks.md + specs/ deltas)
→ implement /opsx:apply (TDD; the implementer skill drives this)
→ verify /opsx:verify (change satisfies its specs)
→ sync / archive /opsx:sync | /opsx:archive
archive validates the deltas, merges them into openspec/specs/<cap>/spec.md
(RENAMED → REMOVED → MODIFIED → ADDED), then moves the change to
openspec/changes/archive/<date>-<id>/
- Archive is deterministic — keep it out of the LLM-generation path. Run
openspec validate --strict first; archive blocks on invalid deltas.
- After archive, run
make fix-spec-links. The archive copies a delta's relative links into
specs/ verbatim, so a delta nested deeper than its merged home leaves over-deep ../ links.
The auto-fixer recomputes the depth; the validator's broken_links check is the safety net.
- Seed inputs survive.
changes/<id>/inputs/ is preserved with the archived change — never
deleted or groomed (traceability).
Grooming the durable specs/
- The durable truth is
openspec/specs/<capability>/spec.md — the merged, machine-validated specs.
- Grooming happens at archive review: fix a freshly-created spec's
Purpose placeholder, keep
capability names coherent, and ensure no requirement lost detail in a MODIFIED delta (a common
pitfall — MODIFIED must carry the full updated requirement, not a fragment).
- Brownfield changes are delta-only:
propose the delta → apply → archive. Do not rewrite
the whole spec; express the change as ADDED/MODIFIED/REMOVED/RENAMED.
The orientation index (memory) — keep it honest, don't let it pretend to be truth
Per the spine decision (spine/epic-change-memory-mapping.md):
- Truth =
openspec/specs/. There is no bespoke MEMORY.md-as-truth.
- Orientation =
openspec/config.yaml's context: field (OpenSpec's native sink, injected into
every artifact's instructions). Keep it short and current.
- If a generated digest is ever wanted, regenerate it deterministically from
specs/ + open
changes into context: (like codegen, with a CI sync-check) — never hand-curate a parallel
index that silently diverges. Building that generator is deferred until it is proven needed.
The Rule of Divergence (stewardship view)
When reality and spec disagree, fix the spec, not by quietly editing code:
- PLAN-level wrongness → revise the PLAN (back to
epic-planning).
- EPIC-level wrongness (the bet is invalid) → a deliberate, logged re-shape or a superseding new
change — never a silent rewrite of a frozen, shaped EPIC.
Boundary & Related Skills
Owns: the post-authoring lifecycle and care of the living specs — change archive, delta→specs/
merge, grooming the durable store, brownfield delta conventions, and the orientation-index policy.
Delegates: authoring the EPIC/PLAN → epic-planning; the schema +
conventions → spine/; implementation → external implementer/TDD;
scoring the PLAN → clarity-gate.
Related: epic-planning, clarity-gate, bdd-gherkin.
1---2name: spec-stewardship3description: Steward the living specification spine after an EPIC is authored — the EPIC↔change lifecycle, archiving completed changes, grooming the durable specs/ store, and keeping the orientation index in sync. Use when finishing/archiving a change, merging spec deltas into the truth, grooming or reviewing the living specs, or refreshing project context/memory. Trigger on "archive this change", "groom the specs", "sync the spec deltas", "what's the lifecycle of a change", "regenerate the memory index", "merge into specs". For authoring the EPIC/PLAN use epic-planning; for the schema/conventions see the spine docs.4license: Apache 2.05---67# Spec Stewardship89## Overview1011The spine is only valuable if its specs stay **well maintained, groomed, and preserved**. This12skill owns the **care of the living specs** after [`epic-planning`](../epic-planning/SKILL.md) has13authored an EPIC and PLAN: moving a change through its lifecycle, merging its deltas into the14durable truth, grooming that truth, and keeping the cheap orientation index honest.1516It does **not** author EPICs/PLANs (that is `epic-planning`) and does **not** define the schema or17conventions (those live in [`spine/`](../../spine/README.md)) — it *runs* them.1819## The change lifecycle (maps to `/opsx` — see [`spine/workflows.md`](../../spine/workflows.md))2021```22author in openspec/changes/<id>/ (epic-planning: proposal.md + design.md + tasks.md + specs/ deltas)23 → implement /opsx:apply (TDD; the implementer skill drives this)24 → verify /opsx:verify (change satisfies its specs)25 → sync / archive /opsx:sync | /opsx:archive26 archive validates the deltas, merges them into openspec/specs/<cap>/spec.md27 (RENAMED → REMOVED → MODIFIED → ADDED), then moves the change to28 openspec/changes/archive/<date>-<id>/29```3031- **Archive is deterministic** — keep it out of the LLM-generation path. Run32 `openspec validate --strict` first; archive blocks on invalid deltas.33- **After archive, run `make fix-spec-links`.** The archive copies a delta's relative links into34 `specs/` verbatim, so a delta nested deeper than its merged home leaves over-deep `../` links.35 The auto-fixer recomputes the depth; the validator's `broken_links` check is the safety net.36- **Seed inputs survive.** `changes/<id>/inputs/` is preserved with the archived change — never37 deleted or groomed (traceability).3839## Grooming the durable `specs/`4041- The durable truth is `openspec/specs/<capability>/spec.md` — the merged, machine-validated specs.42- Grooming happens **at archive review**: fix a freshly-created spec's `Purpose` placeholder, keep43 capability names coherent, and ensure no requirement lost detail in a MODIFIED delta (a common44 pitfall — MODIFIED must carry the full updated requirement, not a fragment).45- Brownfield changes are **delta-only**: `propose` the delta → `apply` → `archive`. Do not rewrite46 the whole spec; express the change as ADDED/MODIFIED/REMOVED/RENAMED.4748## The orientation index (memory) — keep it honest, don't let it pretend to be truth4950Per the spine decision ([`spine/epic-change-memory-mapping.md`](../../spine/epic-change-memory-mapping.md)):5152- **Truth = `openspec/specs/`.** There is no bespoke `MEMORY.md`-as-truth.53- **Orientation = `openspec/config.yaml`'s `context:` field** (OpenSpec's native sink, injected into54 every artifact's instructions). Keep it short and current.55- If a generated digest is ever wanted, **regenerate it deterministically** from `specs/` + open56 changes **into `context:`** (like codegen, with a CI sync-check) — never hand-curate a parallel57 index that silently diverges. Building that generator is deferred until it is proven needed.5859## The Rule of Divergence (stewardship view)6061When reality and spec disagree, fix the **spec**, not by quietly editing code:6263- PLAN-level wrongness → revise the PLAN (back to `epic-planning`).64- EPIC-level wrongness (the bet is invalid) → a deliberate, logged **re-shape** or a superseding new65 change — never a silent rewrite of a frozen, shaped EPIC.6667## Boundary & Related Skills6869**Owns:** the post-authoring **lifecycle and care** of the living specs — change archive, delta→`specs/`70merge, grooming the durable store, brownfield delta conventions, and the orientation-index policy.71**Delegates:** authoring the EPIC/PLAN → [`epic-planning`](../epic-planning/SKILL.md); the schema +72conventions → [`spine/`](../../spine/README.md); implementation → external `implementer`/TDD;73scoring the PLAN → [`clarity-gate`](../clarity-gate/SKILL.md).74**Related:** `epic-planning`, `clarity-gate`, `bdd-gherkin`.
meaningfy-ws