Contributing to Agentic InfraOps

Thank you for your interest in contributing! Agentic InfraOps revolutionizes how IT Pros build Azure environments through coordinated AI agents.

This file is the quick contributor entrypoint. The canonical, detailed contributor workflow (branch protection, PR flow, automation, versioning) is:

Development Workflow Guide

🎯 What We’re Looking For

High-Priority Contributions

Agent Improvements
- Enhancements to existing agents (.github/agents/*.agent.md)
- Better prompts and handoff patterns
- Additional validation checks
Documentation
- Workflow improvements (docs/workflow.md)
- Better examples and use cases
- Troubleshooting guides
Best Practices
- Bicep and Terraform patterns and templates
- Azure Verified Module usage examples (Bicep and AVM-TF)
- Security and compliance guidance
⬆️ Back to Top## 📋 Contribution Guidelines

Before You Start

Check existing issues - Someone might already be working on it
Open an issue - Discuss your idea before investing time

Branching and PRs (Canonical)

This repo uses a protected main branch. Contributions land via pull requests with required checks and review.

Workflow details: Development Workflow Guide
Agent workflow details: Agent Workflow Reference

Branch Naming Convention

All branches must use an approved prefix that indicates the change domain. This is enforced by lefthook pre-push hooks and GitHub Actions CI.

Prefix	Scope	Example
`docs/`	Documentation (`docs/`, `mkdocs.yml`, `README.md`)	`docs/update-workflow-guide`
`agents/`	Agent definitions (`.github/agents/`, `agent-registry.json`)	`agents/improve-conductor`
`skills/`	Skill files (`.github/skills/`, `skill-affinity.json`)	`skills/add-tf-patterns`
`infra/`	Infrastructure code (`infra/bicep/`, `infra/terraform/`)	`infra/add-private-endpoints`
`scripts/`	Validation scripts (`scripts/`, `package.json`)	`scripts/fix-h2-sync`
`instructions/`	Instruction files (`.github/instructions/`)	`instructions/update-bicep`
`fix/`	Bug fixes (cross-cutting, any files)	`fix/session-state-schema`
`feat/`	New features (cross-cutting, any files)	`feat/azure-skills-integration`
`chore/`	Maintenance, deps, tooling (cross-cutting)	`chore/update-lefthook`
`ci/`	CI/CD workflows (cross-cutting)	`ci/add-branch-enforcement`
`refactor/`	Code refactoring (cross-cutting)	`refactor/simplify-handoffs`
`perf/`	Performance improvements (cross-cutting)	`perf/faster-validation`
`test/`	Test additions/updates (cross-cutting)	`test/add-e2e-terraform`
`build/`	Build system changes (cross-cutting)	`build/update-node-deps`
`revert/`	Reverting previous changes (cross-cutting)	`revert/broken-lint-rule`

Branch Scope Enforcement

Domain-scoped branches (docs/, agents/, skills/, infra/, scripts/, instructions/) are restricted to modifying files within their domain. This prevents accidental cross-cutting changes in narrow-scope branches.

Cross-cutting branches (feat/, fix/, chore/, ci/, refactor/, perf/, test/, build/, revert/) may modify any files.

Domain Prefix	Allowed File Paths
`docs/`	`docs/`, `mkdocs.yml`, `README.md`, `CONTRIBUTING.md`, `CHANGELOG.md`
`agents/`	`.github/agents/`, `.github/agent-registry.json`
`skills/`	`.github/skills/`, `.github/skill-affinity.json`
`infra/`	`infra/`
`scripts/`	`scripts/`, `package.json`
`instructions/`	`.github/instructions/`

Enforcement Mechanisms

Branch naming and scope are enforced at three levels:

Local (lefthook pre-push) — instant feedback before push via scripts/validate-branch-naming.sh and scripts/validate-branch-scope.sh
CI (GitHub Actions) — the branch-enforcement.yml workflow validates naming and scope on every PR to main
GitHub Rulesets — optional server-side enforcement configured in repository Settings → Rules → Rulesets

Code Standards

Bicep:

// Use consistent naming conventions
// Include parameter descriptions
// Add output values
// Follow Azure naming best practices

Terraform:

# Use consistent naming conventions (CAF)
# Variables in variables.tf with descriptions and validation
# Outputs in outputs.tf
# AVM-TF modules preferred over raw resources
# Provider pinned to ~> 4.0 (AzureRM)

Documentation Standards

Use clear, concise language
Include code examples
Document prerequisites
Use Mermaid for explanatory diagrams in Markdown; use Excalidraw for architecture artifacts

Markdown Linting

This repository uses markdownlint for consistent formatting.

Running the linter:

# Check for issues
npm run lint:md

# Check links (docs/ only)
npm run lint:links

# Auto-fix issues
npm run lint:md:fix

⬆️ Back to Top## 🚀 Contribution Process

1. Fork & Clone

Note: For using Agentic InfraOps, create your own repo from the Accelerator template instead. The instructions below are for contributing back to this upstream project.

git clone https://github.com/YOUR-USERNAME/azure-agentic-infraops.git
cd azure-agentic-infraops
git remote add upstream https://github.com/jonathan-vella/azure-agentic-infraops.git

2. Create a Branch

Use an approved prefix (see Branch Naming Convention above):

git checkout -b feat/your-feature-name
# or
git checkout -b fix/issue-description
# or domain-scoped:
git checkout -b docs/update-workflow-guide

3. Make Your Changes

Follow the guidelines above
Test any Bicep changes with bicep build and bicep lint
Test any Terraform changes with terraform fmt -check, terraform validate, and npm run validate:terraform
Validate markdown and links with npm run lint:md and npm run lint:links

For the full local-to-PR flow, see:

Development Workflow Guide

4. Commit & Push

git add .
git commit -m "feat: add diagram generator improvements"
git push origin feature/your-feature-name

Note: commit message format is enforced by hooks and CI.

⬆️ Back to Top## 📝 Commit Message Format (Required)

This repository uses Conventional Commits with automated enforcement. Commit messages are validated by commitlint before each commit.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Type	Description	Version Bump
`feat`	New feature	Minor (1.x.0)
`fix`	Bug fix	Patch (1.0.x)
`docs`	Documentation only changes	None
`style`	Code style (formatting, semicolons)	None
`refactor`	Code refactoring (no functional change)	None
`perf`	Performance improvements	None
`test`	Adding or updating tests	None
`build`	Build system or dependencies	None
`ci`	CI/CD configuration	None
`chore`	Maintenance tasks	None
`revert`	Reverting a previous commit	None

Breaking Changes

For breaking changes, add ! after the type or include BREAKING CHANGE: in the footer:

# Breaking change indicator
git commit -m "feat!: redesign agent workflow architecture"

# Or with footer
git commit -m "feat: new output structure

BREAKING CHANGE: agent outputs now go to agent-output/ folder"

Breaking changes trigger a major version bump (x.0.0).

Examples

# Feature (minor version bump)
git commit -m "feat: add terraform validation agent"
git commit -m "feat(bicep): add diagnostic settings module"

# Bug fix (patch version bump)
git commit -m "fix: correct resource naming in Key Vault module"
git commit -m "fix(docs): update broken quickstart links"

# No version bump
git commit -m "docs: update workflow documentation"
git commit -m "chore: update dev container configuration"
git commit -m "refactor: simplify agent handoff logic"

Validation

Commits are automatically validated by the commit-msg hook. If your commit message doesn’t follow the format, you’ll see a helpful error with examples.

5. Create Pull Request

Go to your fork on GitHub
Click “New Pull Request”
Fill out the PR template
Link related issues

⬆️ Back to Top## 📝 Pull Request Checklist

Before submitting:

Code follows repository standards
Documentation updated if needed
Markdown files pass linting (npm run lint:md)
Docs links pass checks (npm run lint:links)
Bicep templates validate (bicep build + bicep lint) if applicable
Terraform configs validate (terraform validate + terraform fmt -check) if applicable
No hardcoded secrets or subscription IDs
Links work correctly

⬆️ Back to Top## 🤝 Community Standards

Code of Conduct

Be respectful and inclusive
Welcome newcomers
Focus on constructive feedback
No harassment or discrimination

Getting Help

Questions: GitHub Discussions
Issues: GitHub Issues

⬆️ Back to Top## 📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for helping improve the Azure infrastructure workflow! 🚀

⬆️ Back to Top