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.
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.
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.
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.
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.
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.
/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).
/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.
/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.
/dx-estimate
Estimation results: hours per task, story points, affected AEM pages, and complexity breakdown. Uses an HTML comment signature for machine-readable detection.
/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.
/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.
/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.
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.
Comment Signatures
Quick reference for all ADO comment signatures -- used for idempotent updates and traceability.
| Skill | Signature | Posting Modes | Template |
|---|---|---|---|
/dx-req (DoR phase) | [DoRAgent] Definition of Ready Check | A: full | B: update | C: skip | dor-check.md.template |
/dx-req (share) | [DevPlan] Development Plan | A: full | B: update | share-plan.md.template |
/dx-req-dod | DoD Check: <Title> (ADO #<id>) | A: full | B: update | C: skip | dod-summary.md.template |
/dx-agent-re | [RE Agent] Requirements Analysis Complete | A: full post | re-summary.md.template |
/dx-estimate | <!— ai:role:estimation-agent —> | A: full post | inline |
/dx-bug-triage | (no fixed signature) | A: full post | inline |
/dx-bug-verify | [BugVerify] / [BugVerifyLocal] / [BugVerifyQA] | A: full post | inline |
/aem-qa-handoff | [QAHandoff] | A: full | B: update | qa-handoff.md.template |
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.
/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.
/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.
/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.
| Skill | Work Item Type | MCP Tool | Title Pattern |
|---|---|---|---|
/aem-qa | Bug | wit_create_work_item | [AI-QA] <description> |
/dx-agent-re | Task | wit_add_child_work_items | <task title> |
/dx-req-tasks | Task (batch) | wit_add_child_work_items + wit_update_work_items_batch | <FE/BE/Authoring task> |
/dx-req-dod | Task | wit_create_work_item | <fix description> |
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>.
/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.
/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>.
/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 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.
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.
/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.
When Does Each ADO Write Happen?
ADO writes mapped to the development lifecycle -- from story pickup to QA handoff.
/dx-req (DoR phase) /dx-req /dx-agent-re /dx-estimate /dx-req-tasks /dx-req-dod /aem-qa /aem-qa-handoff /dx-doc-gen /dx-req-tasks close ADO Write Summary
| Phase | Skill | ADO Write | Target |
|---|---|---|---|
| Requirements | /dx-req (DoR phase) | Comment | Story |
| Requirements | /dx-req (share) | Comment | Story |
| Requirements | /dx-agent-re | Comment + Tasks | Story |
| Planning | /dx-estimate | Comment | Story |
| Planning | /dx-req-tasks | Tasks + Updates | Story children |
| Bug Triage | /dx-bug-triage | Comment | Bug |
| Bug Verify | /dx-bug-verify | Comment | Bug |
| Quality | /dx-req-dod | Comment | Story |
| Quality | /dx-req-dod (fix) | Tasks | Story children |
| QA | /aem-qa | Bug creation | New Bug items |
| QA Handoff | /aem-qa-handoff | Comment | Story |
| Completion | /dx-req-tasks close | Update + Close | Story children |
| Documentation | /dx-doc-gen | Wiki page | ADO Wiki |
| Documentation | /dx-doc-retro | Wiki page | ADO Wiki |
| PR Reports | /dx-pr-review-report | Wiki page | ADO Wiki |
| PR Reports | /dx-pr-reviews-report | Wiki page | ADO Wiki |