Developer Agent Commands

Relevant source files

The following files were used as context for generating this wiki page:

• .agents/commands/pr.md
• .agents/commands/rebase.md
• .agents/commands/create-issue.md
• dev/README.md
• dev/adr/0001-context-nuggets-pattern.md
• GPT.md
• dev/constitution.md

Developer Agent Commands are specialized AI agent instructions and reusable skills located within the .agents/ directory of the Infrahub MCP repository. These commands automate complex developer workflows such as creating GitHub issues, managing pull requests, and performing safe rebases, ensuring adherence to project standards and the Infrahub MCP Server Constitution.

Sources: dev/README.md, dev/adr/0001-context-nuggets-pattern.md, GPT.md

Architecture and Organization

The project follows the "Context Nuggets" pattern, which organizes documentation and agent instructions into small, focused files. This structure allows AI agents to load only relevant context, saving tokens and improving accuracy.

Command Directory Structure

• .agents/commands/: Contains the definition of reusable agent commands.
• .agents/skills/: Houses domain-specific skill guides for agents.
• Symlink Compatibility: The project uses symlinks (e.g., .claude/commands pointing to .agents/commands) to maintain a single source of truth across different AI tools like Claude Code.

Sources: dev/adr/0001-context-nuggets-pattern.md, dev/README.md

Documentation Flow

The system follows a specific document lifecycle where ideas transition into Architecture Decision Records (ADRs) or specifications, eventually becoming permanent knowledge or guidelines.

This diagram shows how architectural decisions and guidelines inform the creation of automated agent commands.
Sources: dev/README.md, dev/adr/0001-context-nuggets-pattern.md

Core Command Suite

The repository provides several primary commands to automate the development lifecycle.

Command	File Path	Purpose
create-issue	.agents/commands/create-issue.md	Transforms ideas into structured GitHub issues.
pr	.agents/commands/pr.md	Executes the full PR workflow (commit, analyze, document, create).
rebase	.agents/commands/rebase.md	Performs safe rebases onto the stable branch with conflict resolution.
speckit.extract	.agents/commands/speckit.extract.md	Extracts ADRs, knowledge, and guidelines from completed specs.

Sources: dev/README.md

Pull Request Workflow (pr)

The pr command automates the transition from local code changes to a submitted Pull Request. It enforces quality gates including linting, testing, and news fragment creation.

This sequence illustrates the automated steps taken by the agent when the pr command is invoked.
Sources: .agents/commands/pr.md, GPT.md, dev/constitution.md

Issue Creation (create-issue)

The create-issue command ensures that all new work is properly documented before implementation begins. It analyzes the current project state and structures a GitHub issue with clear objectives and technical context.

Key Actions:

1. Search the repository for related code or documentation.
2. Formulate a technical description.
3. Apply appropriate labels (e.g., added, fixed, housekeeping).
4. Submit the issue via the GitHub CLI.

Sources: .agents/commands/create-issue.md, GPT.md

Safe Rebase (rebase)

The rebase command facilitates synchronization with the stable branch. Project policy forbids force-pushing to stable, making safe rebase procedures critical.

Rebase Requirements:

• The agent must identify conflicts.
• The agent must resolve conflicts based on the project's Constitution.
• The agent must re-run tests (uv run pytest) after a successful rebase.

Sources: .agents/commands/rebase.md, dev/constitution.md, GPT.md

Quality Gates and Compliance

All commands are designed to respect the project's "Core Principles" defined in the Constitution.

• News Fragments: Commands interacting with the changelog must use towncrier to create fragments in changelog/.
• Identity: Agents must identify themselves in commits and Pull Requests.
• Automation Tools: Commands rely on uv for dependency management and invoke for linting tasks.

uv run invoke lint       # All linters (ruff, mypy, pylint, yaml)
uv run pytest            # Full test suite execution
uv run towncrier create  # News fragment creation

Sources: GPT.md, dev/constitution.md

Summary

Developer Agent Commands provide a standardized interface for AI agents to participate in the Infrahub MCP server development process. By centralizing these instructions in the .agents/ directory and linking them to the project's core principles and automated tooling, the project ensures high-quality contributions and consistent maintainability.