ADO Integration

Every skill that writes to Azure DevOps -- comments, work items, and wiki pages. A complete map of what the AI posts and where.

Overview

What Gets Written to ADO

Skills write three types of data to ADO: comments on work items, new work items (Bugs & Tasks), and wiki pages.

Work Item Comments

Structured markdown comments posted to stories and bugs. Each skill uses a unique signature tag (e.g., [DoRAgent], [DevPlan]) for idempotent updates — re-running a skill updates the existing comment instead of creating duplicates.

Comments

Work Item Creation

Creates child work items under stories: Task items for sprint planning and Bug items from QA verification. All created items are linked as children of the parent story.

Creation

Wiki Pages

Technical documentation and PR review reports published to the ADO Wiki under sprint-organized paths. Generated from spec files, retroactively from PRs, or from code review findings. Also supports Confluence.

Wiki

Safety Model

All ADO writes use format: “markdown” (never HTML). Comments are append-only — ADO MCP doesn’t support editing existing comments, so skills post update comments instead. Most skills ask for user confirmation before posting. Bug creation always requires human approval.

Comments

Work Item Comments

Each skill posts a structured comment with a unique signature tag. Signatures enable idempotent updates -- the skill checks for existing comments before posting.

/dx-req (DoR phase)

Definition of Ready checklist with interactive checkboxes. BAs can check items directly in ADO, then re-run DoR to update the scorecard. Three modes: full post, update, or skip if unchanged.

[DoRAgent] dor-check.md.template

/dx-req (share phase)

Short development plan for the team: scope (S/M/L) and 3-5 bullets on what will change. Suitable for pasting into Teams. Posted before development starts — no wiki link (wiki is generated post-implementation).

[DevPlan] share-plan.md.template

/dx-req-dod

Definition of Done validation results. Checks PR status, approving reviews, resolved threads, child tasks, tests, build, secrets, and accessibility. Posts pass/fail verdict with score.

DoD Check: dod-summary.md.template

/dx-agent-re

Requirements Engineering summary. Structured requirements spec with task breakdown, identified risks, and effort estimates. Posted after the RE agent analyzes the story.

[RE Agent] re-summary.md.template

/dx-estimate

Estimation results: hours per task, story points, affected AEM pages, and complexity breakdown. Uses an HTML comment signature for machine-readable detection.

ai:role:estimation-agent

/dx-bug-triage

Clarification questions posted when a bug description is ambiguous. Asks for missing reproduction steps, expected behavior, or environment details to unblock investigation.

(clarification)

/dx-bug-verify

Bug verification evidence. Before mode: confirms the bug is reproducible on QA (screenshots, console errors). After mode: confirms the fix works on local AEM. QA mode: confirms the fix is deployed and working on QA post-merge.

[BugVerify] [BugVerifyQA]

/aem-qa-handoff

Short QA handoff pointer: QA page URLs (author + publisher), prerequisites, what changed (3-5 bullets), and a link to the wiki page for full details. QA has test plans for detailed verification — the comment is a notification, not a test script.

[QAHandoff] qa-handoff.md.template

Comment Templates

Templates live in dx-core/data/templates/ado-comments/. Each template defines the markdown structure, placeholder tokens, and signature line. The signature line always ends with an ISO timestamp for traceability.

Reference

Comment Signatures

Quick reference for all ADO comment signatures -- used for idempotent updates and traceability.

SkillSignaturePosting ModesTemplate
/dx-req (DoR phase)[DoRAgent] Definition of Ready CheckA: full | B: update | C: skipdor-check.md.template
/dx-req (share)[DevPlan] Development PlanA: full | B: updateshare-plan.md.template
/dx-req-dodDoD Check: <Title> (ADO #<id>)A: full | B: update | C: skipdod-summary.md.template
/dx-agent-re[RE Agent] Requirements Analysis CompleteA: full postre-summary.md.template
/dx-estimate<!— ai:role:estimation-agent —>A: full postinline
/dx-bug-triage(no fixed signature)A: full postinline
/dx-bug-verify[BugVerify] / [BugVerifyLocal] / [BugVerifyQA]A: full postinline
/aem-qa-handoff[QAHandoff]A: full | B: updateqa-handoff.md.template
Work Items

Work Item Creation

Skills that create new Bugs and Tasks in ADO, linked as children of the parent story.

/aem-qa

Creates Bug work items when QA verification finds UI/functional issues on AEM. Each bug includes: repro steps, expected vs actual behavior, severity (High/Medium), screenshot evidence, and page URL. Always asks for human confirmation before creating.

Bug [AI-QA] prefix

/dx-agent-re

The Requirements Engineering agent creates child Task work items under the parent story. Each task has a title, description, type classification (FE/BE/Authoring), and is linked as a child of the story.

Task child items

/dx-req-tasks

Batch-creates child Task work items with hour estimates. Sets Original Estimate and Remaining Work fields. With close argument: moves Remaining Work to Completed Work, zeros remaining, and sets state to Closed. Full task lifecycle: create → close.

Task (batch) estimates close

/dx-req-dod

Creates Task work items for failed Definition of Done criteria that cannot be auto-fixed. Auto-fixes what it can (tests, docs, changelog), then creates ADO Tasks for the rest.

Task fix items
SkillWork Item TypeMCP ToolTitle Pattern
/aem-qaBugwit_create_work_item[AI-QA] <description>
/dx-agent-reTaskwit_add_child_work_items<task title>
/dx-req-tasksTask (batch)wit_add_child_work_items + wit_update_work_items_batch<FE/BE/Authoring task>
/dx-req-dodTaskwit_create_work_item<fix description>
Wiki

Wiki Documentation

Skills that publish technical documentation and PR review reports to the ADO Wiki (or Confluence).

/dx-doc-gen

Generates wiki page structured as a demo walkthrough: Summary, Design Reference (Figma), What Changed and Why, QA Verification (URLs), Dialog Changes (screenshot), Frontend Preview (screenshot), Figma Comparison (side-by-side), Authoring Guide, Files Changed. Screenshots use repo-relative paths for committing. Posts to ADO Wiki under <wiki-doc-root>/<Sprint>/<id>-<slug>.

wiki post-implementation

/dx-doc-retro

Generates documentation retroactively for stories that shipped without docs. Fetches the ADO story, finds linked PRs, searches the codebase for changes, and produces wiki-ready documentation. No spec files needed.

wiki retroactive

/dx-pr-review-report

Generates a categorized report from a single PR review — groups comments by category (accessibility, bug, functionality, regression), tracks patch resolution, and posts to ADO Wiki under <wiki-pr-review-root>/<ticket>.

wiki PR review

/dx-pr-reviews-report

Generates categorized reports for multiple PR reviews in batch — lists reviewed PRs, generates a report for each, and posts all to ADO Wiki. Ideal for sprint review summaries and tech lead dashboards.

wiki batch

Wiki Configuration

Wiki paths are configured in .ai/config.yaml:
scm.wiki-doc-root — technical docs (used by /dx-doc-gen, /dx-doc-retro)
scm.wiki-pr-review-root — PR review reports (used by /dx-pr-review-report, /dx-pr-reviews-report)
Both support Confluence as an alternative — configured via tracker.provider.

Updates

Work Item Updates

Skills that modify existing work item fields (estimates, assignments).

/dx-req-tasks (create)

After creating child Task items, updates their estimation fields: Original Estimate and Remaining Work. Uses batch update for efficiency. Also sets assignment if configured.

wit_update_work_items_batch

/dx-req-tasks close

Closes all open child tasks after development: moves Remaining Work into Completed Work, zeros remaining, sets state to Closed. Checks implement.md to verify all steps are done before closing. Sprint burndown and capacity stay accurate.

wit_update_work_items_batch
Timeline

When Does Each ADO Write Happen?

ADO writes mapped to the development lifecycle -- from story pickup to QA handoff.

Development Lifecycle ADO Writes
DoR Check Comment
/dx-req (DoR phase)
Dev Plan Comment
/dx-req
RE Agent Comment + Tasks
/dx-agent-re
Estimation Comment + Updates
/dx-estimate
Task Split Tasks + Estimates
/dx-req-tasks
DoD Check Comment
/dx-req-dod
QA Agent Bugs
/aem-qa
QA Handoff Comment + Wiki link
/aem-qa-handoff
Docs Wiki page (demo)
/dx-doc-gen
Task Close Close + time
/dx-req-tasks close

ADO Write Summary

PhaseSkillADO WriteTarget
Requirements/dx-req (DoR phase)CommentStory
Requirements/dx-req (share)CommentStory
Requirements/dx-agent-reComment + TasksStory
Planning/dx-estimateCommentStory
Planning/dx-req-tasksTasks + UpdatesStory children
Bug Triage/dx-bug-triageCommentBug
Bug Verify/dx-bug-verifyCommentBug
Quality/dx-req-dodCommentStory
Quality/dx-req-dod (fix)TasksStory children
QA/aem-qaBug creationNew Bug items
QA Handoff/aem-qa-handoffCommentStory
Completion/dx-req-tasks closeUpdate + CloseStory children
Documentation/dx-doc-genWiki pageADO Wiki
Documentation/dx-doc-retroWiki pageADO Wiki
PR Reports/dx-pr-review-reportWiki pageADO Wiki
PR Reports/dx-pr-reviews-reportWiki pageADO Wiki
KAI by Dragan Filipovic