azure-boards

name	azure-boards
description	Use Azure Boards through Microsoft Entra OAuth, PAT, or bearer-token auth for Work Item operations, AI Project Cockpit reporting, history/flow mining, comment intelligence, role-based delivery reports, process policy checks, and safe write-preview workflows.

Azure Boards

Use this skill when the user wants to work with Azure DevOps Boards, Work Items, project delivery status, process compliance, delivery risk, bottlenecks, comments, role-specific reporting, governance, or process policy analysis.

App Directory Review Notes

When preparing this plugin for OpenAI App Directory review, keep submission metadata conservative and evidence-backed:

1. Do not publish example support addresses, local repository URLs, development-only URLs, or Microsoft-owned documentation URLs as app-owned support, repository, privacy, terms, or website links.
2. Use deployment placeholders such as TODO_DEPLOY_HOSTED_MCP_URL or TODO_ENTRA_CLIENT_ID only in pre-submission artifacts when the real hosted MCP endpoint or Microsoft Entra client id is not known.
3. Do not fabricate privacy policy or terms URLs. Require publisher-owned privacy and terms pages before final submission.
4. Prefer individual Microsoft Entra login for app review. PAT and bearer-token modes are development or controlled automation options and must not require users to paste secrets into ChatGPT.
5. Confirm deployed MCP transport, OAuth registration, support contact, privacy policy, terms, screenshots, tool annotations, and output schemas before claiming App Directory readiness.

Authentication Guidance

1. Prefer the active configured mode reported by azure_boards_auth_status.
2. Use PAT mode when AZURE_BOARDS_PAT or AZURE_DEVOPS_PAT is configured.
3. Use existing bearer-token mode when AZURE_BOARDS_BEARER_TOKEN is configured.
4. Use Microsoft Entra OAuth device login when token env vars are not configured and user login is appropriate. Call azure_boards_login before data access.
5. Never print tokens, PATs, bearer tokens, device-code secrets, or token-cache contents.

Workflow

1. Check authentication with azure_boards_auth_status; call azure_boards_login only when OAuth login is needed.
2. Use azure_boards_query_work_items or azure_boards_get_work_item to gather board truth before making recommendations.
3. Prefer explainable AI tools for process and delivery insights, especially:
   • azure_boards_ai_delivery_risk_radar
   • azure_boards_ai_project_cockpit
   • azure_boards_ai_watchlist_report
   • azure_boards_ai_action_plan
   • azure_boards_ai_workflow_conformance
   • azure_boards_ai_sla_aging_monitor
   • azure_boards_ai_bottleneck_mining
   • azure_boards_ai_governance_score
   • azure_boards_ai_policy_gap_detector
   • azure_boards_ai_create_process_baseline
   • azure_boards_ai_process_drift_detection
   • azure_boards_ai_cost_of_delay_radar
   • azure_boards_ai_process_simulator
   • azure_boards_ai_capacity_forecast
   • azure_boards_ai_brief_export
   • azure_boards_ai_delivery_system_correlation
   • azure_boards_ai_wsjf_consistency_check
   • azure_boards_ai_business_value_estimate
   • azure_boards_ai_attachment_evidence_summary
   • azure_boards_ai_close_candidates
   • azure_boards_ai_parent_child_cleanup
   • azure_boards_ai_bulk_close_preview
   • azure_boards_ai_requirement_decision_cockpit
   • azure_boards_ai_evidence_first_requirement_review
   • azure_boards_ai_cio_requirement_risk_view
   • azure_boards_ai_portfolio_rationalization
   • azure_boards_ai_benefit_realization_tracking
   • azure_boards_ai_cost_avoidance_by_closure
   • azure_boards_ai_erp_domain_impact_scoring
   • azure_boards_ai_closure_governance_ledger

Safe Write-Preview Workflow

Use write-preview behavior for any create, update, comment, relation, assignment, state transition, tag, area, iteration, or policy-remediation action:

1. Gather the current Work Item data.
2. Produce a preview containing Work Item ids, fields or relations affected, old values, proposed values, and rationale.
3. Ask for confirmation when the requested write is not already explicit and exact.
4. Execute only the write-specific tool after confirmation.
5. Report completed changes, skipped changes, and Azure DevOps errors.

For bulk close work:

1. Always re-read current state, type, direct children, and parent relations before planning.
2. Use azure_boards_ai_bulk_close_preview before writing; it must include ids, current states, target states, child impact, comments, JSON Patch previews, skipped items, and risk.
3. Use azure_boards_apply_bulk_close_plan only when the preview is explicitly approved with approved:true and confirmPhrase: "APPLY_BULK_CLOSE".
4. Write the explanatory comment before the state transition.
5. After applying, re-query the relevant WIQL and report remaining counts.

Guardrails

• Do not invent project status. Use Azure Boards data or clearly label assumptions.
• Do not auto-assign owners, change states, or create audit evidence without user confirmation.
• Treat AI scores as decision support, not as authoritative process compliance findings.
• For executive summaries, include risks, evidence, and next actions grounded in Work Item fields, comments, and relations.
• For comment intelligence, distinguish direct evidence from inferred intent or sentiment.
• For role-based reports, avoid hiding uncertainty. Include missing data and policy/config assumptions.
• For process policy checks, do not treat local defaults as organization policy unless the user or config says so.
• Use azure_boards_package_health and azure_boards_auth_environment_check for diagnostics, but do not ask the user to paste secret values.
• Use azure_boards_ai_plan_approved_actions only after explicit approval; it prepares batches but still does not perform Azure DevOps writes.
• Use azure_boards_apply_bulk_close_plan only for a preview generated by azure_boards_ai_bulk_close_preview; never construct hidden bulk writes.
• Use azure_boards_apply_test_case_plan only for a preview generated by azure_boards_ai_generate_test_cases; require approved:true and confirmPhrase: "APPLY_TEST_CASE_PLAN".
• Use azure_boards_apply_traceability_plan only for a preview generated by azure_boards_ai_requirement_test_traceability; require approved:true and confirmPhrase: "APPLY_TRACEABILITY_PLAN".
• Treat decision, portfolio, CIO, steering-pack, policy-as-code, evidence-ledger, and Governance Operating System tools as advisory no-write tools. They can recommend, rank, simulate, draft rewrite patches, and export evidence previews, but only explicit write tools may change Azure Boards.
• Do not store PATs, bearer tokens, OAuth token caches, or live attachment extraction artifacts in plugin docs or local JSON reports.
• Remember Azure DevOps process quirks: Work Item comments use 7.1-preview, and Work Item batch fetches should not combine explicit fields with relation expansion.