AI Agent Tools & Governance
Relevant source files
The following files were used as context for generating this wiki page:
AI Agent Tools & Governance defines the standards, directory structures, and behavioral constraints for AI coding assistants working on the nornir-infrahub repository. This framework ensures that AI agents like Claude Code or Codex operate within a portable, vendor-neutral environment while adhering to the project's technical "constitution."
The system relies on the Canonical OpsMill Agentic Structure, which centralizes agent-specific skills and context. This governance model prevents "agentic drift" between sibling repositories and enforces strict quality gates before any code is committed.
Canonical Agentic Layout
The project adopts a vendor-neutral layout for agent-consumed content. This structure separates durable human-facing rationale from executable agent skills.
The .agents Directory
The .agents/ directory serves as the single source of truth for all agent-consumed content. It contains spec-kit extensions, OpsMill-specific skills, and shared development utilities. This directory is engine-agnostic, meaning no specific tool name appears in its canonical path.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:15-17
Tool Adapters and Symlinks
To support specific tools without duplicating data, the project uses committed symlinks. For example, .claude/skills is a committed symlink pointing to ../.agents/skills. This ensures that Claude Code and spec-kit read from and write to the same byte-source, preventing divergence.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:18-20
Structure Diagram
This diagram illustrates how multiple agents access the same neutral source of truth through tool-specific adapters.
Project Constitution and Boundaries
The AGENTS.md file acts as a constitution that defines what AI agents must do, what they must ask about, and what they are strictly forbidden from doing.
Governance Rules
| Category | Requirement |
|---|---|
| Always Do | Run invoke format and invoke lint before committing. |
| Always Do | Preserve the task-plugin contract regarding host.data["InfrahubNode"]. |
| Always Do | Pin dependencies with both lower and upper bounds. |
| Ask First | Changing the public plugin API or InfrahubInventory entry point. |
| Ask First | Adding or removing dependencies in pyproject.toml. |
| Never Do | Push directly to the protected stable branch. |
| Never Do | Commit secrets or hardcode admin tokens. |
| Never Do | Disable lint or type gates to pass CI without inline justification. |
Sources: AGENTS.md:95-132, dev/guidelines/git-workflow.md:76-83
Shared Skills and Spec-kit Integration
The project utilizes spec-kit (version 0.11.9) to manage agent capabilities. Shared development skills are version-pinned via content hashes to ensure stability.
Shared Skills Management
Shared skills are sourced from opsmill/opsmill-skills and include utilities for committing, creating PRs, and monitoring pull requests. These are recorded in skills-lock.json to prevent silent updates.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:24-26, skills-lock.json:1-49
Skill Pining Example
The following snippet shows how a skill is pinned with a computedHash:
"commit": {
"source": "opsmill/opsmill-skills",
"sourceType": "github",
"skillPath": "opsmill-dev/skills/commit/SKILL.md",
"computedHash": "84c357ba427a6a7a9a6b1187d24ce9fd740f7dfb2127606f7f844afcf5ccacbb"
}
Sources: skills-lock.json:4-9
Automated Quality Gates
AI agents must execute a specific sequence of commands to validate their work. These commands are defined as invoke tasks and monitored by CI.
Mandatory Workflow Sequence
- Format: Execute
invoke formatto runruffandrumdl. - Lint: Execute
invoke lintto runyamllint,ruff,pylint,ty(type checking), andrumdl. - Test: Run
pytestfor unit tests. Integration tests (pytest -m integration) require Docker.
Sources: AGENTS.md:27-50, tasks.py:16-72, dev/guidelines/git-workflow.md:12-19
Linter Configuration
Linters are configured in pyproject.toml. The rumdl tool specifically manages Markdown linting, with specific rules disabled for generated documentation and agent instruction files.
Sources: pyproject.toml:139-166
Pre-commit Logic Flow
This diagram shows the validation process an agent must follow before a contribution is considered valid.
Summary of Governance Significance
The AI Agent Tools & Governance framework establishes a rigorous environment that treats AI agents as first-class, yet highly regulated, contributors. By centralizing logic in .agents/ and enforcing a project "constitution" via AGENTS.md, nornir-infrahub maintains high code quality and architectural consistency across all automated contributions.