LLM Agent Workflows (SpecKit)
Relevant source files
The following files were used as context for generating this wiki page:
LLM Agent Workflows (SpecKit) provide a standardized framework for AI agents to interact with the infrahub-sync codebase. The system defines operating principles, development requirements, and safety protocols to ensure that Large Language Models (LLMs) like Claude or GitHub Copilot produce code that is consistent, typed, and safe for infrastructure synchronization.
The AGENTS.md file serves as the single source of truth for agent behavior, while platform-specific files like CLAUDE.md utilize SpecKit tags to provide additional technology context and current plan details.
Sources: AGENTS.md:1-5, CLAUDE.md:1-8, AGENTS.md:162-164
Agent Operating Principles
LLM agents must follow five core principles to maintain project integrity and safety:
- Plan → Ask → Act → Verify → Record: You must plan briefly, request missing context, perform the smallest change, verify locally, and record with concise notes.
- Read-only and Dry Runs by Default: You must prefer safe commands like
list,diff, andgeneratebefore executing async. Write operations require human approval. - Specific and Reversible Changes: You must provide small, scoped commits and avoid mixing large refactors with behavior changes.
- Pattern Matching: You must maintain consistency with existing CLI, adapter structures, and directory hierarchies.
- Idempotency and Safety: You must prioritize operations that are safe to re-run and never print or guess secrets.
Sources: AGENTS.md:10-18, dev/constitution.md:19-27
Required Development Workflow
Agents must execute specific quality gates in order before submitting code. These gates ensure formatting, linting, and type checking are satisfied.
Verification Cycle
The following diagram illustrates the standard loop an agent must follow for every task:
This diagram represents the "Plan → Ask → Act → Verify → Record" principle enforced for LLM agents.
Sources: AGENTS.md:10-12
Quality Gates and Tools
Agents utilize the following commands to validate contributions:
| Command | Purpose |
|---|---|
uv sync | Synchronizes the virtual environment and dependencies. |
uv run invoke format | Runs code formatters (Ruff). |
uv run invoke lint | Runs the full linting suite: Ruff, Pylint, Yamllint, and Ty. |
uv run ty check . | Executes type checking; must exit with code 0. |
uv run pytest -q | Runs unit tests for new features or bug fixes. |
Sources: AGENTS.md:37-60, pyproject.toml:44-62
CLI Sanity and Safety
Agents are prohibited from guessing or printing secrets. All credentials must be sourced from environment variables or secret managers. After modifying the codebase, agents must verify CLI behavior using safe commands.
Sources: AGENTS.md:83-85, dev/constitution.md:65-72
CLI Validation Steps
- Verify help output:
uv run infrahub-sync --help. - List available projects:
uv run infrahub-sync list --directory examples/. - Generate adapter code from YAML:
uv run infrahub-sync generate --name <name> --directory examples/.
Sources: AGENTS.md:46-51
Identification and Documentation
Agents must maintain transparency in their contributions through specific identification and documentation requirements.
- Self-Identification: Agents must identify themselves in commit messages or PRs (e.g.,
🤖 Generated with CopilotorCo-Authored-By: Claude Opus 4.6). - Changelog Management: Every pull request must include a news fragment under the
changelog/directory named<id>.<type>.md(e.g.,123.fixed.md). - Documentation Updates: Agents must update the
docs/directory for any user-visible changes, including CLI flags or configuration keys.
Sources: AGENTS.md:143-145, AGENTS.md:95-108, RELEASING.md:129-138
Adapter Development Guidelines
When agents generate new adapters, they must adhere to the Mixin contract and dependency rules.
This diagram shows the inheritance structure agents must follow, prioritizing the DiffSyncMixin to ensure consistent engine behavior.
Sources: dev/guidelines/writing-an-adapter.md:11-20, dev/guides/adding-an-adapter.md:42-55
- Mixin Order: The mixin must be declared before the DiffSync base class to ensure method resolution works correctly.
- Optional Dependencies: Upstream SDKs (e.g.,
pynetbox) must be treated as optional dependencies using# ty: ignore[unresolved-import].
Sources: dev/guidelines/writing-an-adapter.md:11-18, dev/guidelines/writing-an-adapter.md:67-75
Conclusion
The LLM Agent Workflows (SpecKit) ensure that AI-driven development remains safe and standards-compliant. By enforcing a Plan-Verify-Record cycle and requiring strict adherence to the project's quality gates, the system allows agents to contribute effectively to the infrahub-sync ecosystem while preventing production data corruption and secret leakage.