Skip to content
Skills Library
Programming · Tool integration

openspec-conformance

/openspec-conformance

Use when a repo OPTS INTO Uhstray's plans/development + plans/architecture conventions — the store-registration setup an adopting repo runs once, the house openspec/config.yaml rules, and the archive-time ADR promotion into plans/architecture/. Triggers on "openspec conformance", "register the openspec store", "plans/ layout", "promote an ADR", "openspec store setup", "conform openspec to plans". The single source of truth repo-kickstart (adoption) and pr-shepherd (archive, on adopted repos) both call.

Repository
huhhb ↗
Licence
MIT
Last repository change
11.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: promote-adr.ts

What it does and when to use it

Use when a repo OPTS INTO Uhstray's plans/development + plans/architecture conventions — the store-registration setup an adopting repo runs once, the house openspec/config.yaml rules, and the archive-time ADR promotion into plans/architecture/. Triggers on "openspec conformance", "register the openspec store", "plans/ layout", "promote an ADR", "openspec store setup", "conform openspec to plans". The single source of truth repo-kickstart (adoption) and pr-shepherd (archive, on adopted repos) both call.

Triggers from the description

openspec conformanceregister the openspec storeplans/ layoutpromote an ADRopenspec store setupconform openspec to plans
Original author description

Use when a repo OPTS INTO Uhstray's plans/development + plans/architecture conventions — the store-registration setup an adopting repo runs once, the house openspec/config.yaml rules, and the archive-time ADR promotion into plans/architecture/. Triggers on "openspec conformance", "register the openspec store", "plans/ layout", "promote an ADR", "openspec store setup", "conform openspec to plans". The single source of truth repo-kickstart (adoption) and pr-shepherd (archive, on adopted repos) both call.

How it works

  1. Setup (once per repo — what repo-kickstart runs)
  2. Validation — what openspec validate does and does not enforce
  3. Promotion (on archive — what pr-shepherd runs)
  4. Inception promotion (on architecture approval — what product-inception runs)
  5. Full detail
Original SKILL.md headings · 121 lines, 850 words
SKILL.md preview
---
name: openspec-conformance
description: Use when a repo OPTS INTO Uhstray's plans/development + plans/architecture conventions — the store-registration setup an adopting repo runs once, the house openspec/config.yaml rules, and the archive-time ADR promotion into plans/architecture/. Triggers on "openspec conformance", "register the openspec store", "plans/ layout", "promote an ADR", "openspec store setup", "conform openspec to plans". The single source of truth repo-kickstart (adoption) and pr-shepherd (archive, on adopted repos) both call.
---

# openspec-conformance

The one place that defines how OpenSpec conforms to Uhstray's planning
layout — a mechanism, not a mandate: the layout is OPT-IN per repo (LD-1;
adopted via `repo-kickstart` on repos we choose). `repo-kickstart` calls
the **Setup** section when a repo adopts; `pr-shepherd` calls the
**Promotion** section on archive — on adopted repos only (its own probe
skips-with-note elsewhere). buhhdy's `core-workflows` drives the change
lifecycle in between. Decision record: `buhhdy/README.md` → "Planning
Layout (OpenSpec conformance)".

**Change status has one home: the store.** `openspec list` reports a change's
name, status and task counts. Adopted repos keep no second, hand-maintained
register of the same facts — two records of one fact diverge, and the one
maintained by hand is the one that goes stale.

**Layout (what adopted repos use):**
- `plans/development/openspec/changes/<slug>/` — active changes (proposal, specs, design, tasks)
- `plans/architecture/` — the ADR store, **owned by `repo-memory`** (ADR-0003).
  OpenSpec writes specifications; this skill only carries the promotion mechanism

**Mechanism:** OpenSpec's native **store registration** relocates the root to
`plans/development` (verified live, openspec 1.6.0). A forked schema was
**rejected** — it can rename/re-template artifacts but cannot move the root. What
OpenSpec doesn't model — the index and ADRs — is carried as a promotion pattern.

**Ownership:** the ADR *records* belong to `repo-memory` — their shape, numbering
and lifecycle. This skill owns only the promotion mechanism that files one. OpenSpec
writes specifications, not decisions (ADR-0003).

## Setup (once per repo — what repo-kickstart runs)

`store register` needs an existing `openspec/` root, so **init then register**:

```bash
mkdir -p plans/development plans/architecture
( cd plans/development && openspec init --tools none )      # creates openspec/config.yaml
openspec store register plans/development --id <repo> --yes  # once per MACHINE; idempotent
```

- `<repo>` = the repository name (the store id). Commit the resulting
  `plans/development/.openspec-store/store.yaml` (`version` + `id`) — it keeps the
  id stable across machines. The machine registry
  (`~/.local/share/openspec/stores/registry.yaml`) is per-machine, so each machine
  runs the `register` line once; re-running is a no-op ("already registered").
- Seed the ADR home from `templates/` (copy, then fill placeholders):
  `templates/adr-NNN-slug.md` is the ADR shape the promoter emits.
- Add the house rules + `context:` to `plans/development/openspec/config.yaml`
  (block in `reference.md`).

From the repo root every OpenSpec command takes `--store <repo>` (root resolution
only walks ancestors — without the flag, commands at the repo root miss the nested
root). buhhdy uses the raw CLI (`openspec new change <slug> --store <repo>`, etc.).
The `/opsx:*` slash commands are an opt-in convenience — see `reference.md`.

## Validation — what `openspec validate` does and does not enforce

`openspec validate <slug> --store <repo>` is the deterministic schema gate. It
enforces the **spec** layer only: every requirement needs SHALL/MUST and **at
least one `#### Scenario:`** (Given/When/Then). A requirement with no scenario
fails with exit 1.

**A plan phase's validation gate is expressed as that scenario.** Each phase
delivers a capability; the capability's requirement MUST carry the scenario that
validates it, so a phase missing its gate = a requirement missing its scenario =
`openspec validate` errors. That is the structural check.

**Known limit (do not misreport):** `openspec validate` does **not** parse
`tasks.md` — no schema hook exists for it, and `config.yaml` `rules:` are
AI-authoring guidance, not enforced. The per-phase gate is enforced at the spec
layer above, plus buhhdy Workflow 1 step 5(b)'s reviewer judgment. Do not claim
validate checks tasks.md structure.

## Promotion (on archive — what pr-shepherd runs)

After `openspec archive <slug> --store <repo> --yes` (moves the change to
`openspec/changes/archive/<date>-<slug>/` and promotes specs to
`openspec/specs/`), promote the durable decisions:

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/openspec-conformance/promote-adr.ts" \
  <path-to-plans> <date-slug-dirname> --change-url <pr-or-change-url>
```

It extracts **only** the archived `design.md` `## Decisions` section into one
`## ADR-NNNN — <slug>` record appended to `plans/architecture/YYYY/YYYY-MM.md`,
plus a row in that year's `INDEX.md` and a line in `DECISIONS.md` (globally
sequential numbering; the template's field block + a link back to the archived
design). **That is the whole of it — the script owns decision records and their
two indexes, and nothing else.** It never copies the full design doc, and it
reads no change-status register in any mode: a promotion that failed on a
missing row made an unrelated file a precondition of writing a decision. A
change with no `## Decisions` promotes no ADR and exits 0. Offline check:
`node --test tests/test_openspec_conformance.test.ts`.

## Inception promotion (on architecture approval — what product-inception runs)

Same mechanism, different source and timing: the moment a human approves an
initiative's `plans/product/<slug>/architecture.md` (huhhb's
`product-inception` skill / buhhdy Workflow 0), promote its decisions
IMMEDIATELY — inception decisions are repo-level context Workflow 1's
`investigate` step must find before any epic is picked up:

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/openspec-conformance/promote-adr.ts" \
  <path-to-plans> --from <path-to-plans>/product/<slug>/architecture.md --slug <slug>
```

The `## Decisions`-section-only rule applies unchanged (the architecture doc
keeps its `AD-N` blocks under a literal `## Decisions` heading; nothing else
promotes). Same numbering sequence, same per-slug idempotency. No change-status
register is read or written in this mode or any other — change status lives in
the store, as stated above.

## Full detail

`reference.md` — the `config.yaml` house-rules block, the `/opsx:*` per-tool
verification, the end-to-end proof commands, idempotency detection for
repo-kickstart, and the future "extract to a standalone community package" path.
Files in this package (4)
  • SKILL.md 7 KB
  • promote-adr.ts 13 KB
  • reference.md 6 KB
  • templates/adr-NNN-slug.md 1 KB

Versions

The database has no other skills named openspec-conformance.

Database snapshot: 13.11.2026 · package version 926925eec9f2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90repo-kickstart
    Use when bootstrapping a repository — greenfield or brownfield — into Uhstray's standard development conventions, OpenSpec, and the two-store memory setup. Idempotent and non-destructive: safe to re-run, never overwrites existing docs. Triggers on "repo kickstart", "bootstrap…
  • 90openspec-bootstrap
    Use when setting up OpenSpec in a repo for the first time, or editing a repo's `openspec/config.yaml`
  • 90openspec-context
    Prepare an existing codebase for OpenSpec + Superpowers by writing the project context every proposal and plan will read (stack, commands, conventions, boundaries, the domains the code already has) into openspec/config.yaml. Use once when adopting OpenSpec on a brownfield repo,…
  • 96openspec-archive-change
    Archive a completed OpenSpec change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. Also use when the user says "openspec archive" or "opsx archive".
  • 100openspec-init
    Initialize OpenSpec in a project. Use when: user says 'init openspec', 'setup openspec', or asks to add OpenSpec to a project.
  • 96openspec-archive-change
    Archive a completed OpenSpec change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. Also use when the user says "openspec archive" or "opsx archive".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.