RobinNorberg/omc-ado-setup

OMC ADO Setup

Configure Azure DevOps integration for the current project. Detects the ADO org and project from the git remote URL, verifies authentication, and writes .omcp/config.json with all required settings.

When this skill is invoked, immediately execute the workflow below. Do not only restate or summarize these instructions back to the user.

Trigger Patterns

• "setup ado"
• "configure azure devops"
• "ado setup"
• "connect to azure devops"
• "omc-ado-setup"

Prerequisites

Before running the main workflow, verify all prerequisites are present. If any fail, report the issue and stop with actionable remediation steps.

Check 1: az CLI installed

az --version 2>&1 | head -1

If this fails: tell the user to install the Azure CLI from https://aka.ms/installazurecli.

Check 2: azure-devops extension installed

az extension show --name azure-devops --query name -o tsv 2>&1

If output is not azure-devops: run az extension add --name azure-devops to install it.

Check 3: az authentication status

az account show --query "{name:name, id:id, tenantId:tenantId}" -o json 2>&1

If this fails or returns an error: tell the user to run az login and retry.

Check 4: az devops configured defaults

az devops configure --list 2>&1

Show the output to the user so they can see existing defaults (org, project).

---

Step 1: Detect ADO Remote

Inspect the git remote URL to determine if the repo is hosted on Azure DevOps.

git remote -v 2>&1

Azure DevOps remote URLs follow these patterns:

• https://dev.azure.com/{org}/{project}/_git/{repo}
• https://{org}.visualstudio.com/{project}/_git/{repo}
• [email protected]:v3/{org}/{project}/{repo}

Parse the remote URL to extract:

• org — the ADO organization name
• project — the ADO project name
• repo — the repository name

If no ADO remote is detected, inform the user and ask whether they want to configure manually (prompt for org, project, repo values).

---

Step 2: Probe Existing Configuration

Check if .omcp/config.json already exists:

cat .omcp/config.json 2>/dev/null || echo "NOT_FOUND"

If it exists and contains ado settings, ask the user whether to update or keep the existing configuration (use AskUserQuestion).

---

Step 3: Verify ADO Connection

Confirm the detected org and project are accessible with the current authentication:

az devops project show --project "{project}" --org "https://dev.azure.com/{org}" --query "{id:id, name:name, state:state}" -o json 2>&1

If this fails, the user may need to configure their PAT or re-authenticate:

# Option: configure a PAT
az devops configure --defaults organization=https://dev.azure.com/{org}

---

Step 4: Discover Optional Settings

Ask the user (via AskUserQuestion) for optional configuration. Defaults are shown in brackets.

Question: "Configure optional ADO settings? (Press Enter to accept defaults)"

For each item, probe the available values from ADO to help the user choose:

Work Item Type

az boards work-item type list --project "{project}" --org "https://dev.azure.com/{org}" --query "[].name" -o tsv 2>&1

Common values: User Story, Bug, Task, Issue. Default: User Story.

Area Path

az boards area project list --project "{project}" --org "https://dev.azure.com/{org}" --query "children[].path" -o tsv 2>&1

Default: {project} (root area).

Iteration Path

az boards iteration project list --project "{project}" --org "https://dev.azure.com/{org}" --query "children[].path" -o tsv 2>&1

Default: {project} (root iteration, i.e. no sprint filter).

---

Step 5: Write .omcp/config.json

Create or update the config file. Preserve any existing non-ADO keys.

First, ensure the .omcp/ directory exists:

mkdir -p .omcp

Write .omcp/config.json using the Write (or Edit) tool. The schema is:

{
  "ado": {
    "org": "https://dev.azure.com/{org}",
    "project": "{project}",
    "repo": "{repo}",
    "workItemType": "User Story",
    "areaPath": "{project}",
    "iterationPath": "{project}",
    "configuredAt": "{ISO timestamp}"
  }
}

Configuration Schema Reference

| Key | Type | Description | |-----|------|-------------| | ado.org | string | Full org URL: https://dev.azure.com/{org} | | ado.project | string | ADO project name (case-sensitive) | | ado.repo | string | ADO repository name | | ado.workItemType | string | Default work item type for queries (e.g. User Story) | | ado.areaPath | string | Area path filter (e.g. MyProject\TeamA) | | ado.iterationPath | string | Iteration path filter (e.g. MyProject\Sprint 5) | | ado.configuredAt | string | ISO 8601 timestamp of when setup ran |

Example output

{
  "ado": {
    "org": "https://dev.azure.com/contoso",
    "project": "Widgets",
    "repo": "widgets-api",
    "workItemType": "User Story",
    "areaPath": "Widgets\\Backend",
    "iterationPath": "Widgets\\Sprint 22",
    "configuredAt": "2026-03-09T12:00:00Z"
  }
}

---

Step 6: Verify Connection

Run a smoke test by listing the most recent 5 work items assigned to the current user:

az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.TeamProject] = '{project}' ORDER BY [System.ChangedDate] DESC" --project "{project}" --org "https://dev.azure.com/{org}" -o table 2>&1 | head -20

If the query returns results: report success and show the items. If the query fails with an auth error: suggest az login or PAT configuration. If the query returns 0 items: that is normal — confirm setup is complete.

---

Step 7: Report and Next Steps

Report a summary of what was configured:

ADO Setup Complete

Organization : https://dev.azure.com/{org}
Project      : {project}
Repository   : {repo}
Work Item Type: {workItemType}
Area Path    : {areaPath}
Iteration    : {iterationPath}
Config file  : .omcp/config.json

Next steps:
  /oh-my-copilot:omc-ado-triage   — run a full triage of work items and PRs

---

Error Reference

| Error | Likely cause | Fix | |-------|-------------|-----| | az: command not found | Azure CLI not installed | Install from https://aka.ms/installazurecli | | ERROR: Please run 'az login' | Not authenticated | Run az login | | Extension 'azure-devops' not installed | Missing extension | Run az extension add --name azure-devops | | ResourceNotFound on project show | Wrong org/project | Verify the remote URL and re-run | | TF400813: Resource not available | PAT missing or expired | Create a PAT in ADO → User Settings → Personal Access Tokens |