ADR conventions for superbuild consumers
Superbuild workspaces that mount this repository at tools/ai-rules/ use Architecture Decision Records (ADRs) for significant decisions at the consumer repository level (for example superbuild layout, migration choices, documentation sites).
Canonical specification
ADR format, lifecycle, editing rules, and commit conventions are defined by A2C — not duplicated here.
Use the a2c-workflow tag or commit that matches your team's pinned tooling when following these
links; develop URLs below are convenience pointers, not a floating contract.
| Topic | Canonical source |
|---|---|
| ADR README (format, status, supersession, commits) | a2c-workflow docs/adr/README.md |
| ADR template | a2c-workflow templates/adr/adr-template.md |
| Editing evolution | a2c-workflow rules/08-adr-editing-evolution.md |
ADR commits (adr(...) vs maintenance) | a2c-workflow rules/03-adr-commits.md |
External web sources ([web:NNN]) | a2c-workflow rules/15-web-source-tags.md |
Superbuild-workflow and A2C are different workflows (migration/CMake policy vs product architecture-first). They share one ADR contract so humans and AI agents use the same filenames, sections, and immutability rules.
Where ADRs live
| Repository role | ADR directory | Examples |
|---|---|---|
Superbuild consumer (e.g. esysrepo_dev) | docs/adr/ at superbuild root | Doc sites, manifest layout, CI deploy |
Product submodule (e.g. src/esysrepo) | docs/adr/ in that Git repo | Manifest model, sync, CLI, APIs |
Each Git repository has its own ADR sequence. Cross-link between repos by URL; do not merge indexes.
ADR-0000 in consumer repos
| Consumer | ADR-0000 records |
|---|---|
| Superbuild workspace | Adopt superbuild-workflow at tools/ai-rules/ (revision pin) |
| A2C-governed product repo | Adopt A2C workflow version X.Y.Z — see a2c-workflow reuse |
Do not mix these meanings in a single ADR-0000.
Validation (optional)
If a2c-cli is installed in the superbuild dev environment:
a2c list adrs --json
a2c validate
a2c_core.load_adrs() is workflow-agnostic: it reads docs/adr/*.md using the shared filename and status conventions.
Future eai-supmig doctor checks may report ADR issues using the same parser.
Bootstrap template
eai-supinit / eai-supmig bootstrap scaffolds a consumer ADR pack under docs/adr/:
| File | Role |
|---|---|
README.md | Scope + pointer to A2C canonical rules |
INDEX.md | Navigation (starts with ADR-0000) |
adr-template.md | Copy for new decisions |
0000-adopt-superbuild-workflow.md | Adoption record (submodule or manifest-sync variant) |
ADR-0000 mount mode: submodule when bootstrap uses --with-ai-rules; otherwise
manifest (.esysrepo.manifest.xml already lists tools/ai-rules).
The ADR body template stays aligned with A2C (templates/adr/adr-template.md); consumer
pack lives under templates/consumer/docs/adr/.
New decisions use commit type adr(...); typo or link fixes on Accepted ADRs use
docs(adr): or fix(adr): per A2C rules above.
Related
- governance.md — what belongs in this repo vs consumers
- repository-layout.md — expected
tools/ai-rules/mount - Root
AGENTS.mdin this repository — agent entry point