Agent Skills: Spec-Kit Execution
Relevant source files
The following files were used as context for generating this wiki page:
Spec-Kit Execution defines the framework and specific capabilities used by AI coding agents to interact with the nornir-infrahub repository. It utilizes a vendor-neutral structure that centralizes agent instructions, version-pinned skills, and automated workflows to ensure consistent behavior across different AI tools like Claude Code or Codex.
The system adopts the Canonical OpsMill Agentic Structure, which separates the durable human-facing documentation in the dev/ directory from the executable agent content in the .agents/ directory. This alignment allows agents to share a single portable source of truth while maintaining repository-specific boundaries and workflows.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:10-25, AGENTS.md:1-5
Agentic Architecture and Layout
The repository organizes agent-related content into a hierarchical structure that prioritizes portability and prevents configuration drift.
The Single Source of Truth (.agents/)
All agent-consumed content lives under the .agents/skills/ directory. This directory is engine-agnostic and contains the raw skill definitions (e.g., SKILL.md files) that govern agent behavior. To maintain compatibility with specific tools, the repository uses committed symlinks. For example, .claude/skills is a symlink pointing to ../.agents/skills, ensuring that updates to the core skills automatically propagate to the Claude adapter.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:27-35, pyproject.toml:161-165
Spec-Kit Core and Extensions
The execution framework relies on spec-kit version 0.11.9, which introduces structured workflows and extensions.
- Core Skills: Includes
speckit-convergefor maintaining state and.specify/workflows/for task automation. - OpsMill Extensions: The repository installs the
opsmillextension (v1.1.0) and theagent-contextextension to provide specialized domain knowledge for Infrahub and Nornir integrations. - Shared Dev Skills: Seven shared skills (e.g.,
commit,pr,rebase) are pinned via content hashes inskills-lock.jsonto ensure stability.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:36-47, skills-lock.json:1-40
Interaction Flow Diagram
The following diagram illustrates how an AI agent accesses skills and instructions within the repository structure.
This diagram shows the path from initial agent entry points to the execution of specific Spec-Kit workflows.
Sources: CLAUDE.md:1-10, dev/adr/0001-adopt-canonical-agentic-structure.md:27-40
Skill Management and Constraints
Agent execution is governed by a set of "Always Do", "Ask First", and "Never Do" boundaries defined in AGENTS.md. These rules prevent agents from performing destructive actions or introducing breaking changes to the Nornir plugin contract.
Key Execution Boundaries
| Category | Action / Rule | Reference |
|---|---|---|
| Always Do | Run invoke format and invoke lint before committing changes. | AGENTS.md:73-74 |
| Always Do | Preserve the task-plugin contract by reading host.data["InfrahubNode"]. | AGENTS.md:78-79 |
| Ask First | Changing the public plugin API or the InfrahubInventory entry point. | AGENTS.md:85-86 |
| Ask First | Adding, removing, or bumping dependencies in pyproject.toml. | AGENTS.md:87-88 |
| Never Do | Push directly to the protected stable branch. | AGENTS.md:95 |
| Never Do | Commit secrets or hardcode tokens (use the test admin-token fixture). | AGENTS.md:96 |
Version Control and Locking
To prevent silent updates from breaking agent workflows, all shared skills are locked using content hashes.
"commit": {
"source": "opsmill/opsmill-skills",
"sourceType": "github",
"skillPath": "opsmill-dev/skills/commit/SKILL.md",
"computedHash": "84c357ba427a6a7a9a6b1187d24ce9fd740f7dfb2127606f7f844afcf5ccacbb"
}
Sources: skills-lock.json:4-9, dev/adr/0001-adopt-canonical-agentic-structure.md:44-47
Technical Execution Environment
Agents operate within a development environment managed by uv. They are expected to use invoke tasks for standard operations to ensure they follow the same quality gates as human contributors.
Available Tooling for Agents
- Linting: Agents must pass
ruff,pylint,ty(type checking),yamllint, andrumdl(markdown linting). - Testing: Unit tests are run via
pytest. Integration tests require Docker and are marked with@pytest.mark.integration. - Documentation: Reference documentation is generated from docstrings using
invoke generate-docs.
Sources: tasks.py:21-65, AGENTS.md:22-45, pyproject.toml:50-68
Spec-Kit Workflow Execution
Workflows are defined in .specify/workflows/ and executed through the spec-kit CLI or integrated agent skills. These workflows typically involve:
- Analysis: Evaluating the current state of the repository using
speckit-analyze. - Planning: Generating a structured plan via
speckit-plan. - Execution: Implementing changes and validating against
quality-gates. - Convergence: Ensuring the repository state matches the desired specification using
speckit-converge.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:36-40, CLAUDE.md:5-8
Summary of Agentic Layout
The Canonical Agentic Structure ensures that all agents, regardless of their underlying LLM or interface, interact with the repository using the same set of rules and tools.
This class diagram shows the relationships between the agent-executable directories and the human-facing reference layer.
Sources: dev/adr/0001-adopt-canonical-agentic-structure.md:27-52
Spec-Kit Execution serves as the operational backbone for AI agents, providing a stable, versioned, and constrained environment that protects the integrity of the Nornir-Infrahub integration while enabling high-velocity automated contributions.