Summary

The Azure DevOps integration has 11 backing files totaling 1,798 lines, 20+ MCP tools, and 6 distinct workflows with zero dedicated user documentation. The GitHub Backlog Manager, a comparable integration, has 7 documentation pages (609 lines) for 5 backing files (1,191 lines).

Backing File Inventory

MCP Tool Surface (20+ tools)

• Work items: create_work_item, add_child_work_items, update_work_items_batch, work_items_link, add_artifact_link, get_work_item, my_work_items, get_work_items_for_iteration, get_query_results_by_id
• Search: search_workitem
• Repositories: create_pull_request, update_pull_request, update_pull_request_reviewers
• Linking: link_work_item_to_pull_request
• Identity: get_identity_ids
• Pipelines: get_builds, get_build_status, get_build_log, get_build_log_by_id, get_build_changes, update_build_stage, get_build_definitions

Key Workflows

1. PR creation (574 lines): 7-phase protocol with work item discovery, reviewer identification, 5 confirmation gates
2. Work item discovery (132 lines): 3 paths (user-centric, artifact-driven, search-based)
3. Work item planning (328 lines): Template definitions for planning file sets
4. Work item CRUD (152 lines): Batch operations with hierarchy awareness
5. Build monitoring (156 lines): Pipeline status, logs, stage management
6. PRD-to-WIT analysis (100 lines): 5-phase PRD analysis agent

Documentation Ratio Comparison

Current ADO Documentation Presence

ADO integration appears only as brief mentions within:

• docs/agents/README.md (one table row, "Planned" status)
• docs/getting-started/install.md (mentions ADO workflows exist)
• docs/getting-started/mcp-configuration.md (MCP server configuration)
• docs/architecture/ai-artifacts.md (references ADO PR protocol as example)

Recommended Documentation Structure

Mirror the GitHub Backlog Manager documentation pattern:

docs/agents/ado-integration/
├── README.md                    # Overview, prerequisites, architecture diagram
├── why-ado-integration.md       # Value proposition
├── work-item-discovery.md       # Three discovery paths, planning output
├── pull-request-creation.md     # 7-phase workflow, gates system
├── build-monitoring.md          # Pipeline status, logs, stage management
├── work-item-management.md      # CRUD, hierarchy rules, batch processing
└── using-together.md            # Composing with RPI and GitHub Backlog

Estimated: 7 pages at ~85 lines average = ~595 lines, bringing the documentation ratio to ~0.41.

Acceptance Criteria

• docs/agents/ado-integration/README.md created with overview, prerequisites, architecture
• Per-workflow guide pages created for each of the 6 key workflows
• using-together.md documents cross-system composition with RPI and GitHub Backlog
• docs/agents/README.md updated from "Planned" to link to new documentation
• Mermaid diagrams included for workflow visualization where appropriate