AI Agent Integration & Workflows
Relevant source files
The following files were used as context for generating this wiki page:
AI agent integration provides structured facts and automated workflows to guide Large Language Models (LLMs) and automation tools through development tasks. This system ensures that agents adhere to project standards while performing operations such as code generation, bug investigation, and documentation updates.
The architecture relies on a "portable router" strategy. This strategy places essential repository facts in entry-point files, which then link to deep-dive technical documentation in the dev/ directory.
Sources: AGENTS.md:5-9, dev/README.md:9-16
Agent Knowledge Architecture
The project organizes agent context into three primary tiers to ensure information relevance and reduce token overhead.
Tier 1: Repository Entry Point
AGENTS.md serves as the primary router. It contains high-level facts, tech stack versions, and core commands. Every agent session begins by reading this file to understand the environment.
Sources: AGENTS.md:1-25
Tier 2: Domain Context
Specific directories contain their own AGENTS.md files to provide localized context:
- Plugins Context:
plugins/AGENTS.mddetails boilerplate requirements, argument specifications (INFRAHUB_ARG_SPEC), and import patterns. - Testing Context:
tests/AGENTS.mdexplains Docker-based execution, mocking patterns, and test types (Sanity, Unit, Integration).
Sources: plugins/AGENTS.md:1-20, tests/AGENTS.md:1-20
Tier 3: Binding Principles
The dev/constitution.md file defines the authoritative principles that agents must follow. It includes non-negotiable boundaries, such as mandatory SDK wrappers and specific Python boilerplate.
Sources: dev/constitution.md:1-15, dev/constitution.md:98-115
Agent Workflow Orchestration
The following diagram illustrates how an agent traverses the documentation and executes commands to fulfill a development request.
This diagram shows the flow from a user request through the agent's context-gathering phase to specific workflow execution.
Sources: AGENTS.md:5-15, dev/README.md:50-56
Automated Agent Commands
Agents utilize specific command definitions located in ../.agents/commands/. These files provide step-by-step instructions for complex workflows.
| Command | Purpose | Reference File |
|---|---|---|
add-module | Scaffolds a new Ansible module with documentation and stubs. | add-module.md |
fix-bug | Guides the agent through investigation and fix verification. | fix-bug.md |
speckit.specify | Initiates the feature specification process. | speckit.md |
speckit.plan | Generates implementation plans based on specs. | speckit.md |
speckit.implement | Executes the code changes defined in a plan. | speckit.md |
Sources: dev/README.md:50-56
Constitutional Boundaries for Agents
Agents must comply with the "Boundaries" section of the repository constitution. These rules prevent common automation errors and maintain collection integrity.
Mandatory Actions
- Boilerplate: Include
__metaclass__ = typeandfrom __future__ importin every plugin file. - SDK Access: Use
InfrahubclientWrapperfor all API calls; never useInfrahubClientSyncdirectly. - Security: Mark all token parameters with
no_log=True. - Documentation: Regenerate reference docs using
invoke generate-docafter changing docstrings.
Prohibited Actions
- Async SDK: Never use async SDK methods; the collection is synchronous only.
- Hardcoding: Never hardcode credentials; use environment variable fallbacks (
INFRAHUB_ADDRESS,INFRAHUB_API_TOKEN). - Manual Edits: Never hand-edit files in
docs/docs/references/plugins/.
Sources: dev/constitution.md:98-115, plugins/AGENTS.md:85-100
Spec-Kit Integration
The spec-kit workflow facilitates rigorous feature design and implementation. Agents use the .specify/ directory to manage feature life cycles.
This sequence shows the interaction between the agent and the spec-kit tooling to ensure features are specified before implementation.
Sources: dev/constitution.md:25-35, CLAUDE.md:3-8
AI agent integration ensures that automated contributors operate with the same context and constraints as human developers. By centralizing repository facts and enforcing constitutional boundaries, the project maintains high code quality and documentation accuracy during automated workflows.