README
¶
spec-lifecycle
A standalone SDD primitive: a staged, human-gated, spec-driven issue lifecycle built on OpenSpec as the artifact runtime.
One GitHub issue ↔ one change folder, moving through refine → design → plan, each stage a fresh agent session emitting a human-approved artifact. Gates are durable file records (approval-state.json, deviation.json) — this primitive writes them; any enforcement engine (an orchestrator, CI) reads and blocks. On completion, the change's structured spec delta folds deterministically into the living spec (openspec/specs/), with a replay guard verifying the projection never drifts from its event log.
Companion primitive to adr-sourced-constitution — the same event-sourcing invariants (append-only events, derived projections, tool-only writes, verifiable fidelity), applied to the functional what instead of the architectural how.
Status: design — pending review. See spec-lifecycle.md for the full specification.
Shape
- Layer 1 —
lifecycleCLI (Go, deterministic, no LLM):init·approve·status·guard - Layer 2 — agent-agnostic skills (SKILL.md standard): stage conduct, bug repro-first flow, archive discipline
- Layer 3 — integrations: a custom OpenSpec schema (
kentra), the constitution seam, engine/CI record consumers
MIT.
Documentation
¶
Overview ¶
Package lifecycle is spec-lifecycle's module-root library package. Its only job is embedding the repo's single-source Layer-2 skill bundles (skills/) so `lifecycle init` (internal/scaffold) can fan them out into a target repo's agent-skill trees (implementation-plan.md §2.9 step g, §3, §9.2). The same skills/ directory is also directly consumable by out-of-band tooling (e.g. `npx skills add kentra-io/spec-lifecycle`); embedding it makes the CLI self-contained — the fanned-out copies are real files, never symlinks. Mirrors the sibling adr-sourced-constitution primitive's own root embed.go exactly (implementation-plan.md §2.12).
The embed directive must live in a package whose directory is an ancestor of skills/. skills/ sits at the repo root (the layout the plan pins and the path the npx tooling expects), so the embedding package is this root library package rather than an internal one; internal/scaffold consumes SkillsFS through it.
M6 ships the five bundles as MINIMAL VALID skills — correct SKILL.md frontmatter and a body that points at the right verbs/docs, with an explicit note that the real prompt-engineered bodies land in M7 (implementation-plan.md §8's milestone map). Do not mistake these stubs for the finished skill content.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var SkillsFS embed.FS
SkillsFS holds the skills/ tree: one skills/<name>/SKILL.md per skill.
Functions ¶
This section is empty.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
lifecycle
command
Command lifecycle is the CLI for spec-lifecycle: a staged, gated issue lifecycle in the OpenSpec on-disk format, reimplemented as a single static Go binary (no Node, no `openspec` runtime — see implementation-plan.md §0.5/"Option B").
|
Command lifecycle is the CLI for spec-lifecycle: a staged, gated issue lifecycle in the OpenSpec on-disk format, reimplemented as a single static Go binary (no Node, no `openspec` runtime — see implementation-plan.md §0.5/"Option B"). |
|
internal
|
|
|
approve
Package approve is the gate writer: `lifecycle approve --stage <s>` (spec-lifecycle.md §5, implementation-plan.md §2.6).
|
Package approve is the gate writer: `lifecycle approve --stage <s>` (spec-lifecycle.md §5, implementation-plan.md §2.6). |
|
archive
Package archive implements `lifecycle archive <change>` (spec-lifecycle.md §6.2, implementation-plan.md §2.5): the 5-step pipeline that turns an approved change folder into a permanent projection update — gate-check, conflict-check, pre-image digests, native fold + relocate, post-image digests + monotonic-seq ledger append — plus a cheap post-write self-check.
|
Package archive implements `lifecycle archive <change>` (spec-lifecycle.md §6.2, implementation-plan.md §2.5): the 5-step pipeline that turns an approved change folder into a permanent projection update — gate-check, conflict-check, pre-image digests, native fold + relocate, post-image digests + monotonic-seq ledger append — plus a cheap post-write self-check. |
|
atomicwrite
Package atomicwrite writes a file such that a concurrent reader — or a crash — never observes a half-written result: the bytes are written to a temp file in the *same directory* as the target, flushed, and then atomically moved into place (implementation-plan.md §3, "Atomic writes").
|
Package atomicwrite writes a file such that a concurrent reader — or a crash — never observes a half-written result: the bytes are written to a temp file in the *same directory* as the target, flushed, and then atomically moved into place (implementation-plan.md §3, "Atomic writes"). |
|
config
Package config loads and validates lifecycle.yml (spec-lifecycle.md §10, implementation-plan.md §2.10): the project config `lifecycle init` writes and every command reads, at repo root, sibling of openspec/.
|
Package config loads and validates lifecycle.yml (spec-lifecycle.md §10, implementation-plan.md §2.10): the project config `lifecycle init` writes and every command reads, at repo root, sibling of openspec/. |
|
constitution
Package constitution is a thin exec wrapper around the sibling adr-sourced-constitution primitive's `constitution` binary (spec-lifecycle.md §7, implementation-plan.md §2.7).
|
Package constitution is a thin exec wrapper around the sibling adr-sourced-constitution primitive's `constitution` binary (spec-lifecycle.md §7, implementation-plan.md §2.7). |
|
guard
Package guard implements `lifecycle guard` (spec-lifecycle.md §6.3, implementation-plan.md §2.4): the deterministic, no-LLM fidelity check that the archive ledger (internal/archive's ledger.jsonl), the archived changes it describes (openspec/changes/archive/**), and the live projection (openspec/specs/**) all still agree with each other.
|
Package guard implements `lifecycle guard` (spec-lifecycle.md §6.3, implementation-plan.md §2.4): the deterministic, no-LLM fidelity check that the archive ledger (internal/archive's ledger.jsonl), the archived changes it describes (openspec/changes/archive/**), and the live projection (openspec/specs/**) all still agree with each other. |
|
scaffold
Package scaffold implements `lifecycle init`'s side of the build: it authors the managed pointer blocks in agent-instruction files (CLAUDE.md, AGENTS.md) and fans the embedded Layer-2 skills out into a repo's agent-skill trees, keeping both drift-protected via openspec/.state (implementation-plan.md §2.9, §2.12, §5/§6 of the mirrored constitution plan).
|
Package scaffold implements `lifecycle init`'s side of the build: it authors the managed pointer blocks in agent-instruction files (CLAUDE.md, AGENTS.md) and fans the embedded Layer-2 skills out into a repo's agent-skill trees, keeping both drift-protected via openspec/.state (implementation-plan.md §2.9, §2.12, §5/§6 of the mirrored constitution plan). |
|
schema
Package schema embeds the natively-owned kentra-spec-lifecycle schema descriptor (spec-lifecycle.md §4, implementation-plan.md §2.2): the artifact set (proposal -> specs -> design -> tasks), its requires: DAG, and the four artifact templates (spec-lifecycle.md §4's stage/content table; the tasks.md template carries §4.2's milestone/validation-contract grammar verbatim).
|
Package schema embeds the natively-owned kentra-spec-lifecycle schema descriptor (spec-lifecycle.md §4, implementation-plan.md §2.2): the artifact set (proposal -> specs -> design -> tasks), its requires: DAG, and the four artifact templates (spec-lifecycle.md §4's stage/content table; the tasks.md template carries §4.2's milestone/validation-contract grammar verbatim). |
|
spec
Package spec is the format engine: the pure-Go, parse/render half of spec-lifecycle's reimplementation of the OpenSpec on-disk format (implementation-plan.md §0.5, §2.3; spec-lifecycle.md §6.1), pinned to the grammar of `@fission-ai/openspec` v1.5.0 (commit 546224e).
|
Package spec is the format engine: the pure-Go, parse/render half of spec-lifecycle's reimplementation of the OpenSpec on-disk format (implementation-plan.md §0.5, §2.3; spec-lifecycle.md §6.1), pinned to the grammar of `@fission-ai/openspec` v1.5.0 (commit 546224e). |
|
status
Package status implements `lifecycle status` (spec-lifecycle.md §5/§9.1, implementation-plan.md §2.6): the read-only gate-state reporter over the records internal/approve writes.
|
Package status implements `lifecycle status` (spec-lifecycle.md §5/§9.1, implementation-plan.md §2.6): the read-only gate-state reporter over the records internal/approve writes. |
|
testutil
Package testutil holds shared test guards for OS-dependent filesystem behavior.
|
Package testutil holds shared test guards for OS-dependent filesystem behavior. |
|
validate
Package validate implements the custom-artifact structural checks spec-lifecycle.md §3.3 wires into each gate's pre-check ("lifecycle validate --stage <s>") and implementation-plan.md §2.3 assigns to M2.
|
Package validate implements the custom-artifact structural checks spec-lifecycle.md §3.3 wires into each gate's pre-check ("lifecycle validate --stage <s>") and implementation-plan.md §2.3 assigns to M2. |