The general-purpose reference for building experiment metadata management systems across high-energy physics, published as an OpenSpec Store: a standalone, registered OpenSpec repository whose common capability specifications any experiment can consume read-only — plus the workflow scaffolding (schema, skills, commands, subagents) that experiments install by template.
Content reaches an experiment repository through two independent channels:
- Specs flow through the store, read-only. A Store reference declaration injects the store's spec index into the experiment's artifact workflows; experiments cite shared specs without copying them, and keep their own specs, changes, and implementation in their own repositories.
- Workflow scaffolding replicates by versioned kit release. The kit is installed from a semantically versioned, checksum-verified GitHub release at bootstrap time; it never flows through the store.
dune-metadex is the first adopter, proving the mechanism end to end. The store currently launches with no common capability specs by design — the first is the immediate follow-up change — so early adopters connect to the workflow and grow with the store's first specs.
Takes a fresh experiment repository from nothing to a connected one: scaffolding installed, store registered, reference declared, doctor green, and spec-validation CI and the issue form in place per your host. The same steps were verified end to end on dune-metadex; the full explanation, an adopting-into-an-existing-repository variant, and an agent-assisted bootstrap prompt live in docs/setup.md.
-
Install the OpenSpec CLI (pinned to 1.16.0):
curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.16.0 sh -
Register the hep-metadex store (once per machine):
git clone https://github.com/DUNE/hep-metadex.git ~/openspec/hep-metadex openspec store register ~/openspec/hep-metadex --id hep-metadex
-
Initialize OpenSpec in your experiment repository (from its root, with your agent tool —
opencodehere):openspec init --tools opencode
-
Install the workflow scaffolding from a kit release. Fetch the latest release's bundle and checksums, verify, and extract into your repository — the bundle lays the kit out at its natural paths:
curl -fsSL -o SHA256SUMS https://github.com/DUNE/hep-metadex/releases/latest/download/SHA256SUMS bundle="$(awk '{print $2}' SHA256SUMS)" curl -fsSL -o "$bundle" "https://github.com/DUNE/hep-metadex/releases/latest/download/$bundle" sha256sum -c SHA256SUMS tar -xzf "$bundle"
The installed kit is
.agents/skills/,.opencode/(commands, skills, and agent definitions),openspec/schemas/intent-driven/,AGENTS.md,docs/intent-prompt-guidelines.md(referenced byAGENTS.md), the.metadex-kitversion file — the provenance stamp naming the release you installed — andKIT-MANIFEST.yaml, the kit's per-path bill of materials. Adopting into a repository that already has anAGENTS.md? Merge the kit's pointers into yours rather than overwriting it — the manifest marks it merge-guidance. -
Handle the host-conditional GitHub files: spec-validation CI and the issue form. The bundle carries
.github/workflows/validate.ymland.github/ISSUE_TEMPLATE/(change.ymlandconfig.yml) for GitHub hosts — step 4's extraction already placed them. GitHub-hosted: confirm both paths exist. Hosted elsewhere: remove the extracted.github/kit files and wire the equivalent gate into your own CI.The workflow runs
openspec validate --allover all specs and changes, gating onvalid: true(non-strict, per ADR-0003), with the OpenSpec CLI pinned to the version the release declares (recorded in.metadex-kit— currently 1.16.0). The issue form makes new issues open through the intent-material template — the six required sections plus the optional labeled additions, defined in the Writing Issues section of the guidelines doc copied in step 4 — with blank issues disabled. Repositories on other hosts wire the equivalent validation gate into their own CI and replicate the issue-authoring convention in their own issue tracker — the kit provides no implementation for other hosts (ADR-0005). -
Declare the Store reference in your
openspec/config.yaml— and never astore:line, which would route your planning into the central repository:schema: intent-driven references: - id: hep-metadex remote: https://github.com/DUNE/hep-metadex.git context: | Tech stack: <your real stack> We use conventional commits; every commit references its change's issue number as a (#N) subject suffix; Closes #N appears only in the archive-phase commit Domain: <your experiment's metadata management domain>
Stage rules mirror hep-metadex; see docs/setup.md for the full configuration and the worked example.
-
Verify the connection:
openspec doctor
The
hep-metadexreference reportsok. (On a machine where the store is not yet registered, doctor prints a pasteable clone-and-register fix citing the declared remote.)
From here, /opsx-new or /opsx-propose starts your first change, and the
store's spec index appears in every artifact workflow.
docs/usage.md covers change-time work, write-back to the
store, and the change lifecycle.
Stable locations; everything else links from here.
| Path | What lives there |
|---|---|
docs/ |
Adopter and maintainer documentation: setup, usage, governance, HSF affiliation, the maintainer guide (template provenance, divergence manifest, update-from-upstream), and intent-prompt guidelines |
CONTRIBUTING.md |
Contribution policy — issues, pull requests, conventional commits, glossary discipline |
adr/ |
Durable architectural decisions, newest last |
glossary/ |
Domain and technical terms with use-when/avoid guidance |
pyproject.toml, .python-version, uv.lock |
The maintainer toolchain — Python 3.14 managed by uv, used to maintain this repository itself; not part of the workflow scaffolding adopters copy (ADR-0006) |
zensical.toml, tools/, .github/workflows/docs.yml |
The documentation site build — Zensical on GitHub Pages, published from docs/ in place; repo-local like the maintainer toolchain, not part of what adopters copy (ADR-0007) |
.metadex-kit, KIT-MANIFEST.yaml, CHANGELOG.md, .github/workflows/release.yml |
The kit release channel — version identity (source-side release trigger, shipped provenance stamp), the kit's per-path bill of materials, the changelog sourcing release bodies, and the repo-local release workflow (ADR-0009) |
openspec/specs/ |
The store's published capability specifications |
openspec/changes/ |
In-flight changes; openspec/changes/archive/ holds completed ones |
LICENSE |
Apache-2.0 — a deliberate divergence from the template's MIT, recorded in the divergence manifest |
- Adopting an experiment: docs/setup.md then docs/usage.md.
- Contributing a change: CONTRIBUTING.md.
- Evaluating the project (HSF or otherwise): docs/governance.md and docs/hsf-affiliation.md.
- Maintaining this repository and its template relationship: docs/maintainer.md.