Azure DevOps Workflow Agent Rules
Project Context
You are using Azure DevOps for project management (Boards), source control (Repos), CI/CD (Pipelines), and artifact management (Artifacts). All work is tracked, all changes go through PRs, and all deployments go through pipelines.
Work Item Linking
- Use `AB#<ID>` syntax in commit messages and PR descriptions to link work items to GitHub commits.
- Place `AB#` references in the PR title and body for maximum linking visibility in Azure Boards.
- Format: `AB#1234: feat(auth): implement OAuth2 login` — issue key first, then conventional commit.
- Multiple references: `AB#123 AB#456: implement user export and audit logging`.
- Work item status automatically transitions when PRs are merged if Azure DevOps automation rules are configured.
Work Item Structure
- Work item hierarchy: Epic → Feature → User Story → Task.
- Write Epics as business goals: `User account management`.
- Write Features as capabilities: `Password reset flow`.
- Write User Stories as outcomes: `User can reset password via email`.
- Write Tasks as implementable units of 4–8 hours: `Implement /api/auth/reset-password POST endpoint`.
- Write acceptance criteria in Given/When/Then format for every User Story.
- Use Area Paths to organize work by team or component; use Iteration Paths to schedule sprint work.
Branch Naming
- Pattern: `<type>/<work-item-id>-<short-description>`.
- Types: `feature/`, `bugfix/`, `hotfix/`, `refactor/`, `release/`.
- Examples: `feature/1234-oauth-login`, `bugfix/5678-null-reference-crash`.
- Always include the work item ID for automatic linking in the Azure DevOps development panel.
- Use lowercase with hyphens — no spaces or special characters in branch names.
Branch Policies
- Require a minimum of 2 reviewer approvals for merges to `main` and `release/*` branches.
- Prohibit the most recent pusher from approving their own changes.
- Reset all reviewer votes when new commits are pushed to the PR.
- Require linked work items on all PRs targeting `main` — reject PRs without AB# references.
- Require all PR comment threads to be resolved before merging.
- Require build validation — the CI pipeline must succeed before any merge is allowed.
- Use squash merge to main to keep linear history; use merge commit for release branches.
Azure Pipelines
- Use YAML pipelines (`azure-pipelines.yml`) committed to the repository — avoid the classic visual editor.
- Structure pipelines with stages: `Build → Test → Security Scan → Deploy:Staging → Deploy:Production`.
- Use pipeline templates in a shared repository for reusable build, test, and deploy step sequences.
- Store secrets in Azure Key Vault and reference via variable groups — never hardcode secrets in YAML.
- Run independent jobs in parallel: unit tests, integration tests, and linting should not be sequential.
- Use environments with approval gates for production deployments: required reviewer must approve before the stage runs.
- Use `resources.repositories` to reference shared pipeline templates from other repositories.
YAML Pipeline Structure
- Define `trigger:` and `pr:` sections explicitly — avoid triggering on all branches without intent.
- Set `pool: vmImage: ubuntu-22.04` explicitly rather than floating `ubuntu-latest` for reproducibility.
- Use `variables:` groups per stage to isolate staging and production configuration.
- Use `condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))` to restrict deploy jobs.
- Set `timeoutInMinutes: 30` on every job to prevent hung agents from blocking the queue.
- Use `continueOnError: false` on all production deployment steps — fail loudly on errors.
WIQL Queries
- Active items: `[System.AssignedTo] = @Me AND [System.State] NOT IN ('Closed', 'Done', 'Removed')`.
- Current sprint: `[System.IterationPath] = @CurrentIteration('[Team]\My Team')`.
- High-priority bugs: `[System.WorkItemType] = 'Bug' AND [Microsoft.VSTS.Common.Priority] <= 2 AND [System.State] != 'Closed'`.
- Stale items: `[System.ChangedDate] < @Today - 30 AND [System.State] NOT IN ('Closed', 'Done')`.
- Use `@Me`, `@Today`, `@CurrentIteration`, and `@Project` macros for dynamic personal queries.
- Save common queries and pin them to the team board for quick daily access.
Boards Configuration
- Choose the Agile process template for most software teams — it uses Story/Bug/Task/Epic hierarchy.
- Set WIP limits per board column: alert when exceeded, block at 2x the limit.
- Configure swimlanes for priority tiers or team members in large teams.
- Use the Cumulative Flow Diagram (CFD) to identify bottlenecks in the workflow stages.
- Review the Sprint Burndown daily during standups — a flat line indicates blocked or unreported work.
Automation
- Auto-transition parent User Stories to Active when a child Task moves to Active.
- Auto-complete parent Feature when all child User Stories are Done.
- Escalate bugs unresolved for 10 days at Normal priority to High automatically.
- Use Service Hooks to post Slack or Teams notifications on PR creation and deployment events.
- Test automation rules on a sandbox project before applying to active team boards.
Definition of Done
- Code follows conventions and passes linting.
- Work item linked via `AB#` in branch name, commits, and PR description.
- Unit tests written and all pipeline checks pass.
- Code review approved by at least two reviewers.
- All PR comment threads resolved before merge.
- Feature deployed to staging and verified against acceptance criteria.
- Work item transitioned to Done or Resolved automatically or manually.
- Documentation updated for any user-facing changes.
Azure DevOps
