Skip to content

Maintainer Guide

Maintainer-facing documentation for the hep-metadex repository itself: where its workflow setup came from, how it intentionally diverges from its template, and how to update from upstream without losing those divergences.

Adopters do not need this document to use the store or install the workflow scaffolding — see the README quick start and setup.md. This guide exists so the template relationship stays explicit and template syncs stay deliberate.

Template Provenance

This project's OpenSpec/OpenCode setup was installed on 2026-11-03 from intent-driven-template at commit b5bda460a2180a55fc508fdedc4ef058d95355db (2026-10-15), following its install guide. The bundled schema under openspec/schemas/intent-driven/ is a local copy of the intent-driven schema from the openspec-schemas repository. The shared lifecycle commands and skills under .opencode/ are OpenSpec CLI 1.16.0 versions, newer than the template's copies (generated by 1.14.0).

hep-metadex doubles as the workflow scaffolding template source: adopting experiments install these files by template (see setup.md), which makes the divergence manifest below the replication discipline for the whole family of repositories.

Intentional Divergences

The files below intentionally differ from upstream. Treat this table as the manifest when syncing with the template:

Area Divergence Reason
.opencode/commands/, .opencode/skills/ Shared commands and skills are CLI 1.16.0 versions (template ships 1.14.0); opsx-update and openspec-update-change exist only locally Avoided a downgrade; these files are CLI-owned, not template-owned
opencode.json Renamed to opencode.json.example Per-project OpenCode config is opt-in; global config is preferred
openspec/config.yaml Active context block (tech stack, conventional commits, HEP domain, subagent routing) and all stage rules enabled Project-specific configuration; designated customization point
openspec/schemas/intent-driven/templates/spec.md "business rule" placeholders changed to "domain rule" This is a high-energy physics domain, not a business domain; the local schema copy is the designated customization point
.agents/skills/glossary/ glossary/business.md convention renamed to glossary/domain.md (SKILL.md, README.md) HEP domain terms should not be filed under a "business" label; this is a fork of a vendored skill
.agents/skills/openspec-git-discipline/ The "Before propose" and "After propose" gates amended to require the <issue-number>-<change-slug> issue branch cut from main before a change's first commit Standing policy that change work reaches main only by pull-request merge — this is a fork of a vendored skill
.gitignore Minimal local file (template ships a broader one) Only openspec/.cache/ and .venv/ are needed so far
AGENTS.md Added a pointer to docs/intent-prompt-guidelines.md for intent-prompt authoring Project-specific contributor guidance; re-apply the pointer after a template sync
LICENSE Full Apache-2.0 license at the repository root instead of the template's MIT LICENSE.md Deliberate divergence: a cross-institution standards artifact needs the explicit patent grant and contribution terms — see ADR-0004
.github/workflows/validate.yml Spec-validation CI added (the template ships no CI); distributed with the workflow scaffolding — GitHub-hosted adopters copy this file at bootstrap (ADR-0005) Gates openspec validate --all on valid: true, non-strict, per ADR-0003; the OpenSpec CLI version is pinned in the workflow
.github/ISSUE_TEMPLATE/ Issue form added (the template ships none): the intent-material change form (change.yml) plus the config disabling blank issues (config.yml); distributed with the workflow scaffolding — GitHub-hosted adopters copy both at bootstrap (ADR-0008 routes host-conditional automation to .github/) Standardizes issue authoring on the intent-material template (#23); the form is the GitHub implementation of a host-neutral convention — repositories on other hosts replicate it natively
Not installed package.json, package-lock.json, skills-lock.json Outside the install guide's file list; do not add during a sync without a deliberate decision
pyproject.toml, uv.lock, .python-version Repo-local maintainer toolchain files the template never ships (ADR-0006) Outside the install guide's file list; do not add during a sync without a deliberate decision
zensical.toml, tools/, .github/workflows/docs.yml Repo-local documentation site tooling the template never ships (ADR-0007) Outside the install guide's file list; do not add during a sync without a deliberate decision

Drift Impact

  • Designated customization points (openspec/config.yaml, the local openspec/schemas/intent-driven/ copy): upstream changes must be reconciled manually. A naive copy loses the project-specific values listed above.
  • Vendored skill fork (.agents/skills/glossary/): a template sync that overwrites this directory silently reverts glossary/domain.md back to glossary/business.md. Re-apply the rename after updating, or merge upstream changes by hand.
  • Vendored skill fork (.agents/skills/openspec-git-discipline/): a template sync that overwrites this directory silently reverts the two amended gates ("Before propose" cuts the issue branch; "After propose" opens the planning PR from it). Hand-merge upstream changes into the skill and re-apply both gates after any sync.
  • CLI-generated files: never copy the template's versions of the shared commands and skills over the local ones — the template currently ships older (1.14.0) versions than the installed CLI (1.16.0) produced. Update these via the OpenSpec CLI instead.
  • README.md: project-owned documentation, not template-managed; a sync should not overwrite it.
  • Experiment repositories: the same manifest governs what adopting repositories install from here. When a divergence above changes a file that setup.md tells adopters to copy, the change note should say so, and adopters re-run the scaffolding install to pick it up.

Updating From Upstream

  1. Record the baseline. Before syncing, note the current upstream commit; after syncing, update the commit hash at the top of Template Provenance. Commit all local work first and sync on a branch.
  2. Never bulk-copy. Clone the template outside the repository, diff it against the project, and copy only files that changed upstream and are not listed in the divergence manifest.
  3. Update CLI-owned files via the CLI. Refresh the shared commands and skills under .opencode/ with the OpenSpec CLI (openspec --version to check), not from the template.
  4. Re-apply the manifest. After copying any template file, re-apply every affected divergence from the table above (config values, spec template wording, glossary rename).
  5. Validate before merging. Run openspec schema validate intent-driven, review the full git diff, and merge only when the result matches the manifest.

Repository Configuration

  • openspec/config.yaml selects the intent-driven schema and per-artifact rules (see usage.md for the stage table). Its context block injects project background (domain, tech stack, subagent routing) into every artifact workflow.
  • AGENTS.md enables OpenSpec git discipline: proposals land on main before apply, and implementation merges before archive.
  • .opencode/agent/ provides senior-dev, senior-qa, and adversarial author/reviewer subagents.
  • .agents/skills/ provides collaboration skills: grill-me, c4-diagrams, architectural-decision-records, test-driven-development, gherkin-authoring, glossary, spec-as-source, and more.
  • The kit's layers divide responsibility by the routing rule in ADR-0008: the schema for artifact structure inside changes, openspec/config.yaml rules for per-stage discipline, skills for agent-triggered discipline, commands for procedure automation, the intent-prompt guidelines doc for authoring guidance, and .github/ for host-conditional automation.
  • opencode.json.example is an optional stub for per-project OpenCode configuration. OpenCode reads your global config (~/.config/opencode/opencode.json), which applies to every project, so this repo ships no active opencode.json. Copy the stub to opencode.json only if you need repo-specific settings (e.g., the optional Superpowers plugin). The stub contains only the $schema reference for editor validation and configures nothing.