Skip to content

Repository files navigation

hep-metadex

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:

  1. 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.
  2. 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.

Quick Start

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.

  1. Install the OpenSpec CLI (pinned to 1.16.0):

    curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.16.0 sh
  2. 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
  3. Initialize OpenSpec in your experiment repository (from its root, with your agent tool — opencode here):

    openspec init --tools opencode
  4. 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 by AGENTS.md), the .metadex-kit version file — the provenance stamp naming the release you installed — and KIT-MANIFEST.yaml, the kit's per-path bill of materials. Adopting into a repository that already has an AGENTS.md? Merge the kit's pointers into yours rather than overwriting it — the manifest marks it merge-guidance.

  5. Handle the host-conditional GitHub files: spec-validation CI and the issue form. The bundle carries .github/workflows/validate.yml and .github/ISSUE_TEMPLATE/ (change.yml and config.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 --all over all specs and changes, gating on valid: 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).

  6. Declare the Store reference in your openspec/config.yaml — and never a store: 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.

  7. Verify the connection:

    openspec doctor

    The hep-metadex reference reports ok. (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.

Repository Map

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

Who This Is For

Releases

Packages

Contributors

Languages