Architectural Decision Records
Relevant source files
The following files were used as context for generating this wiki page:
Architectural Decision Records (ADRs) capture point-in-time decisions regarding the design, structure, and standards of the nornir-infrahub repository. These records provide a durable, human-facing rationale for significant changes that impact how AI agents and human contributors interact with the codebase. ADRs are stored in the dev/adr/ directory and serve as an internal reference that is separate from the published documentation site.
Sources: dev/adr/README.md:1-3, dev/adr/0001-adopt-canonical-agentic-structure.md:62-64, dev/guidelines/documentation.md:10-12
Record Standards and Format
The project adopts the Markdown Architectural Decision Records (MADR) format to maintain consistency across technical documentation. Each record follows a strict naming convention to ensure chronological order and discoverability.
Sources: dev/adr/README.md:3-12
Naming Conventions
Files must be named using a zero-padded 4-digit sequence followed by a lowercase, kebab-case summary. The prefixes adr- or ADR- are explicitly forbidden in the filename to maintain a clean structure.
Sources: dev/adr/README.md:5-12
| Requirement | Format Example | Notes |
|---|---|---|
| Sequence | 0001, 0002 | Must be 4 digits |
| Title | use-uv-for-python | Lowercase kebab-case |
| Prefix | None | Do not use adr- |
MADR Structure
A standard ADR in this repository includes the following sections to provide full context for the decision:
- Status: Current state of the decision (e.g., Accepted).
- Date: When the decision was ratified.
- Source: Reference to the Pull Request where the decision was discussed.
- Context: The technical problem or drift that necessitated the change.
- Decision: The specific action taken to resolve the context.
- Consequences: The resulting benefits and trade-offs.
- Alternatives Considered: Other paths that were rejected and why.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:3-85
Ratified Decisions
ADR-001: Canonical OpsMill Agentic Structure
This record established the vendor-neutral layout for agent-consumed content. It aligned nornir-infrahub with other OpsMill repositories by centralizing AI skills and creating a dedicated internal reference layer.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:1-12
Implementation of the .agents/ Layer
ADR-001 defines .agents/ as the single source of truth for all agent-consumed content, including spec-kit skills and shared opsmill-dev skills. To prevent duplication and drift, tool-specific directories like .claude/skills are implemented as committed symlinks pointing to the vendor-neutral .agents/skills directory.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:23-38
The dev/ Reference Layer
A major outcome of ADR-001 was the formalization of the dev/ directory. This layer holds architecture knowledge, guidelines, and ADRs that explain the "why" behind the code, separating executable skills from human-facing documentation.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:58-64
The following diagram illustrates the relationship between the vendor-neutral source and tool-specific adapters as defined in ADR-001.
Decision Lifecycle
Decisions recorded in ADRs are often reflected in other parts of the project lifecycle, such as the CHANGELOG.md and AGENTS.md constitution.
Integration with Development Workflow
When a significant architectural change occurs, such as the migration of build tools or the adoption of new agentic structures, a fragment is typically added to the changelog. Housekeeping sections in the changelog explicitly reference ADR numbers to link releases to their architectural rationales.
Sources: CHANGELOG.md:46-56
Project Constitution
The project maintains a "Constitution" mentioned in AGENTS.md. ADRs serve as the durable record of decisions that enforce specific boundaries, such as the requirement to keep changes focused on bridging Nornir and Infrahub and rejecting scope creep.
Sources: AGENTS.md:112-116, dev/adr/0001-adopt-canonical-agentic-structure.md:62-64
ADR Inventory
| ID | Title | Primary Focus | Ratification Date |
|---|---|---|---|
| 0001 | Adopt Canonical Agentic Structure | Alignment of .agents/ and dev/ directories | 2026-06-29 |
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:1-5
ADRs ensure that the project remains consistent as it evolves, providing future developers and AI agents with the context needed to maintain the system without violating core design principles.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:66-70