charlesjones-dev/claude-code-plugins-dev/ado-init

Azure DevOps Init

Initialize Azure DevOps configuration by creating or updating CLAUDE.md with your organization, project, and team settings, and optionally configuring the Azure DevOps MCP server.

Instructions

CRITICAL: This command MUST NOT accept any arguments. If the user provided any text, organization names, project names, or other arguments after this command (e.g., /ado-init myorg or /ado-init myorg/myproject), you MUST COMPLETELY IGNORE them. Do NOT use any organization names, project names, or other arguments that appear in the user's message. You MUST ONLY gather requirements through the interactive sequential prompts as specified below.

BEFORE DOING ANYTHING ELSE: Begin with Phase 1 by asking for the organization name. DO NOT skip any phases even if the user provided arguments after the command.

Configure CLAUDE.md with Azure DevOps-specific settings that guide Claude Code when working with the Microsoft Azure DevOps MCP server tools. The CLAUDE.md section holds the configuration and the few work item rules Claude needs when it uses the MCP tools directly. The detailed work item creation guidelines live in the /ado-create command, which only the user can start.

Phase 1: Gather Azure DevOps Configuration

Collect Azure DevOps settings from the user in a sequential flow. Ask for each value and wait for the user's response before proceeding to the next.

Step 1 - Organization:

Simply output the following text as your response message and STOP (DO NOT call any tools, especially not AskUserQuestion):

"What is your Azure DevOps organization name? (This is the organization URL segment, e.g., 'contoso' in dev.azure.com/contoso)"

Wait for the user's next message with their organization name before proceeding.

Step 2 - Project:

After receiving the organization name, simply output the following text as your response message and STOP (DO NOT call any tools):

"What is your Azure DevOps project name?"

Wait for the user's next message with their project name before proceeding.

Step 3 - Team:

After receiving the project name, simply output the following text as your response message and STOP (DO NOT call any tools):

"What is your Azure DevOps team name?"

Wait for the user's next message with their team name before proceeding.

Step 4 - Area Path:

After receiving the team name, simply output the following text as your response message and STOP (DO NOT call any tools):

"What is your default Area Path for work items? (This determines where work items are organized. Suggested format: [PROJECT]\\Team\\[TEAM], or leave blank to use the default)"

Wait for the user's next message with their area path (or blank) before proceeding.

Step 5 - Iteration Path:

After receiving the area path, simply output the following text as your response message and STOP (DO NOT call any tools):

"What is your default Iteration Path for work items? (This determines which sprint/iteration work items belong to. Suggested format: [PROJECT]\\Sprint 1, or leave blank to use the default)"

Wait for the user's next message with their iteration path (or blank) before proceeding.

Step 6 - Naming Convention:

After receiving the iteration path, simply output the following text as your response message and STOP (DO NOT call any tools):

"Do you want to use decimal notation for User Story naming? (e.g., 1.1, 1.2, 2.1 for Stories under numbered Features)

Type 'yes' for decimal notation (1, 2, 3 for Features; 1.1, 1.2, 2.1 for Stories) Type 'no' for simple descriptive names (numbered Features only, descriptive names for Stories and Tasks)"

Wait for the user's next message with their choice (yes/no) before proceeding.

Step 7 - MCP Configuration:

After receiving the naming convention choice, simply output the following text as your response message and STOP (DO NOT call any tools):

"Do you want to create a .mcp.json file for Azure DevOps MCP server configuration?

Type 'yes' to configure the Azure DevOps MCP server Type 'no' to skip MCP configuration"

Wait for the user's next message with their choice (yes/no) before proceeding.

Step 8 - Operating System (only if Step 7 was "yes"):

If the user answered "yes" to Step 7, simply output the following text as your response message and STOP (DO NOT call any tools):

"Are you using Windows or Linux/Mac?

Type 'windows' for Windows Type 'linux' for Linux or Mac

Note: Node.js 20+ is required for npx to work. Check your version with: node --version"

Wait for the user's next message with their choice (windows/linux) before proceeding.

If the user answered "no" to Step 7, skip Step 8 entirely and proceed to Phase 2A.

IMPORTANT:

• For Steps 1-8: Simply output the question text in your response message and STOP - do NOT call ANY tools
• DO NOT use the AskUserQuestion tool (or any other tool) for any of the steps 1-8
• After outputting each question, wait for the user's next message before proceeding to the next step
• For Steps 6 and 7, expect the user to type "yes" or "no"
• For Step 8 (if applicable), expect the user to type "windows" or "linux"
• Validate that organization, project, and team names are provided (not empty)
• If Area Path or Iteration Path are empty, apply defaults:
• Area Path default: [PROJECT]\\Team\\[TEAM]
• Iteration Path default: [PROJECT]\\Sprint 1
• Store all collected values (including OS choice) for use in Phase 2A and Phase 3

Phase 2A: Handle MCP Configuration

If the user answered "yes" to Step 7 (MCP configuration):

1. Check if .mcp.json exists in the project root using the Read tool
2. If .mcp.json already exists (Read succeeds):

• Display the appropriate message based on the OS choice from Step 8:

For Windows: ``` ⚠️ .mcp.json file already exists

For security reasons, we cannot read or modify existing .mcp.json files.

Please manually add the following configuration to your .mcp.json file:

{ "mcpServers": { "ado": { "command": "cmd", "args": ["/c", "npx", "-y", "@azure-devops/mcp", "[ORGANIZATION]"] } } }

Replace [ORGANIZATION] with: [organization_value]

💡 Tip: If you already have mcpServers configured, add the "ado" entry to your existing mcpServers object.

📖 Authentication Setup: Visit https://github.com/microsoft/azure-devops-mcp for instructions on configuring authentication with your Azure DevOps account. ```

For Linux/Mac: ``` ⚠️ .mcp.json file already exists

For security reasons, we cannot read or modify existing .mcp.json files.

Please manually add the following configuration to your .mcp.json file:

{ "mcpServers": { "ado": { "command": "npx", "args": ["-y", "@azure-devops/mcp", "[ORGANIZATION]"] } } }

Replace [ORGANIZATION] with: [organization_value]

💡 Tip: If you already have mcpServers configured, add the "ado" entry to your existing mcpServers object.

📖 Authentication Setup: Visit https://github.com/microsoft/azure-devops-mcp for instructions on configuring authentication with your Azure DevOps account. ```

• Replace [ORGANIZATION] and [organization_value] with the actual organization name
• Proceed to Phase 2B

1. If .mcp.json doesn't exist (Read returns error):

• Create .mcp.json with the appropriate content based on the OS choice from Step 8 using the Write tool:

For Windows: ``json { "mcpServers": { "ado": { "command": "cmd", "args": ["/c", "npx", "-y", "@azure-devops/mcp", "[ORGANIZATION]"] } } } ``

For Linux/Mac: ``json { "mcpServers": { "ado": { "command": "npx", "args": ["-y", "@azure-devops/mcp", "[ORGANIZATION]"] } } } ``

• Replace [ORGANIZATION] with the actual organization name
• Display success message:

``` ✓ Created .mcp.json with Azure DevOps MCP server configuration

📖 Authentication Setup Required: Visit https://github.com/microsoft/azure-devops-mcp for instructions on configuring authentication with your Azure DevOps account.

You'll need to set up a Personal Access Token (PAT) with appropriate permissions for the MCP server to connect to your ADO account. ```

• Proceed to Phase 2B

If the user answered "no" to Step 7 (skip MCP configuration):

• Skip all MCP configuration steps
• Proceed directly to Phase 2B

IMPORTANT for Phase 2A:

• Use Read tool to check if .mcp.json exists - DO NOT use bash commands
• For security reasons, NEVER read the contents of an existing .mcp.json file
• If .mcp.json exists, only show the snippet - do NOT attempt to merge or modify
• Use Write tool only when creating a new .mcp.json file
• Use the correct command format based on user's OS choice (Windows vs Linux/Mac)
• Ensure proper JSON formatting with correct indentation

Phase 2B: Check Existing CLAUDE.md

Check if CLAUDE.md already exists and contains an Azure DevOps section using the Read tool:

1. Try to read CLAUDE.md using the Read tool from the project root
2. If the file exists and Read succeeds:

• Parse the content
• Search for "## Azure DevOps" section header
• If Azure DevOps section exists and mentions ado-work-items:
• This section was written by an earlier version of /ado-init. It says the ado-work-items skill loads automatically with the Azure DevOps MCP tools, which stopped being true when the skill became command-only, and ai-ado 2.0 replaced the skill with /ado-create.
• Use the Edit tool to replace the paragraph that mentions ado-work-items (it starts with **Work Item Guidelines:** unless the user edited it) with the work item rules block from the Phase 3 template: every line from **Work Item Rules:** through the line that mentions /ado-create.
• If the section also contains the sentence All work items (Features, User Stories, and Tasks) should have the "State" set to "New" unless otherwise specified., remove that sentence, since the first rule covers it.
• Leave everything else unchanged, including the configuration values and the rest of CLAUDE.md
• Display:

``` ✓ Updated the Azure DevOps section in CLAUDE.md

It referred to the ado-work-items skill, which ai-ado 2.0 replaced with /ado-create. In its place, the section now lists the work item rules Claude follows with the Azure DevOps MCP tools and points to /ado-create.

Your organization, project, team, paths and naming convention are unchanged. To change them, edit the Azure DevOps section of CLAUDE.md. ```

• Return early without making other changes
• If Azure DevOps section exists (and doesn't mention ado-work-items):
• STOP and display a warning message:

``` ⚠️ Azure DevOps section already exists in CLAUDE.md

The CLAUDE.md file already contains Azure DevOps configuration.

To update the configuration:

1. Manually edit CLAUDE.md to update the Azure DevOps section
2. Or remove the Azure DevOps section and run /ado-init again

Current Azure DevOps section found at line: [line_number] ```

• Return early without making changes
• If no Azure DevOps section exists:
• Proceed to Phase 3 to append the section

1. If the file doesn't exist (Read returns error):

• Proceed to Phase 3 to create new CLAUDE.md with Azure DevOps section