Azure DevOps AI-Powered CLI

An intelligent command-line interface and library for Azure DevOps work item management, powered by specialized Claude agents for automated work item generation, validation, and project workflow management.

✨ Features

• 🤖 AI-Powered Work Item Generation - Specialized Claude agents for creating user stories, features, tasks, and bugs
• 📋 Rich Template Library - Pre-built templates for common project patterns (web apps, APIs, mobile apps)
• ✅ Schema Validation - Validate work item JSON against Azure DevOps schema before creation
• 🔄 Bulk Operations - Create entire project hierarchies from JSON files
• 💻 Dual Usage - Use as CLI tool or import as library in your projects
• 🎯 Project-Scoped - Each project can have its own Azure DevOps configuration and scope
• 📊 Interactive Explorer - Browse and manage work items in an interactive tree view
• ⚡ Smart Caching - Efficient caching system for improved performance

🚀 Quick Start

Installation

# Install as project dependency
npm install devops-issues-cli

# Or install globally
npm install -g devops-issues-cli

Initialize AI Agents in Your Project

# Set up Claude agents and templates in your project
npx devops-ai-init

# This creates:
./claude-agents/        # Claude agent files for AI-powered generation
./devops-templates/     # JSON templates for common scenarios
.env.example           # Configuration template
AZURE_DEVOPS_AI.md     # Documentation and workflow guide

Configure Azure DevOps

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your Azure DevOps settings

Required environment variables:

• AZ_DEVOPS_ORG - Your Azure DevOps organization URL
• AZ_DEVOPS_PROJECT - Your project name
• AZ_DEVOPS_PAT - Your Personal Access Token
• AZ_DEVOPS_USER - Your user email or display name
• AZ_DEVOPS_ROOT_ISSUE_ID - (Optional) Filter by Epic/Feature ID for project scope

Important: All work items require a parent work item ID. This ensures proper hierarchy and prevents orphaned items in Azure DevOps.

🤖 AI-Powered Workflow

1. Generate Work Items with Claude

Use the specialized Claude agents to generate work items:

# List available agents
npx devops-issues agents list

# Show specific agent details
npx devops-issues agents show --agent userStory

Example Claude conversation:

User: "Help me break down the user authentication feature into user stories"
Claude: [Uses user-story-agent.md to create detailed, INVEST-compliant user stories]

Note: All generated templates require a parentId in the metadata section. Make sure to replace "PARENT_WORK_ITEM_ID" with an actual Epic, Feature, or other parent work item ID before creating work items.

2. Validate and Create

# Validate generated JSON
npx devops-issues validate user-stories.json

# Preview before creating
npx devops-issues bulk-create user-stories.json --preview

# Create in Azure DevOps
npx devops-issues bulk-create user-stories.json

3. Generate from Templates

# List available templates
npx devops-issues templates list

# Generate from template with customization
npx devops-issues templates generate --template webApp

📚 Usage

CLI Commands

# Interactive mode (default)
devops-issues

# List work items
devops-issues list --state Active --type "User Story"

# Explore in tree view
devops-issues explore

# Create single work item
devops-issues create [parentId] [title]

# Validate JSON file
devops-issues validate workitems.json

# Template management
devops-issues templates list
devops-issues templates show --template userStory
devops-issues templates generate --template apiProject

# Claude agents
devops-issues agents list
devops-issues agents show --agent userStory

# Cache management
devops-issues cache refresh

Library Usage

import { AzureDevOpsClient, setup, createFromTemplate } from 'devops-issues-cli';

// Quick setup
const { client, cache } = await setup({
  orgUrl: 'https://dev.azure.com/yourorg',
  project: 'YourProject',
  pat: 'your-pat',
  user: '[email protected]',
  rootIssueId: 12345  // Optional project scope
});

// Get work items
const workItems = await client.getAssignedWorkItems();

// Create from template
const workItemData = createFromTemplate('userStory', {
  metadata: { areaPath: 'MyProject\\MyArea' }
});

// Bulk create
await client.bulkCreateWorkItems(workItemData);

🎯 Project Integration Patterns

Development Workflow Integration

// package.json scripts
{
  "scripts": {
    "devops:list": "devops-issues list --state Active",
    "devops:create": "devops-issues create",
    "devops:sync": "devops-issues cache refresh",
    "feature:plan": "devops-issues templates generate --template feature"
  }
}

CI/CD Pipeline Integration

# .github/workflows/release.yml
- name: Create release tasks
  run: |
    npx devops-issues bulk-create .devops/release-tasks.json
    npx devops-issues list --type Task --state New > release-tasks.txt

📋 Available Claude Agents

Work Item Generation Agents

• user-story-agent - Creates INVEST-compliant user stories with acceptance criteria
• feature-agent - Bridges Epics and User Stories with proper scope definition
• task-agent - Breaks down User Stories into implementable tasks
• bug-agent - Creates detailed bug reports with reproduction steps

Development Support Agents

• analyzer-agent - Code quality and architecture analysis
• programmer-agent - Implementation following project patterns
• validator-agent - Quality assurance and testing
• research-agent - Information discovery and investigation
• documentation-agent - Technical writing and documentation

Orchestration System

• orchestrator - Coordinates multiple agents for complex workflows

📁 Template Library

Work Item Templates

• userStory - Basic user story with tasks
• feature - Feature with multiple user stories
• epic - Large epic with features and stories
• bug - Detailed bug report template

Project Templates

• webApp - Complete web application project structure
• api - REST API development project
• mobileApp - Mobile application project

🔧 Configuration

Environment Variables

# Required
AZ_DEVOPS_ORG=https://dev.azure.com/yourorganization
AZ_DEVOPS_PROJECT=YourProjectName
AZ_DEVOPS_PAT=your_personal_access_token
[email protected]

# Optional - Project scoping
AZ_DEVOPS_ROOT_ISSUE_ID=12345  # Epic/Feature ID to scope work items

# Optional - Performance tuning
CACHE_TTL=3600
CACHE_MAX_SIZE=1000

Project-Specific Configuration

Each project can have its own Azure DevOps scope by setting AZ_DEVOPS_ROOT_ISSUE_ID to an Epic or Feature ID. This filters all operations to only show work items under that hierarchy, perfect for multi-project organizations.

📖 Documentation

• Bulk Create Guide - Detailed bulk creation documentation
• Field Compatibility Guide - Azure DevOps field mappings
• AI Workflow Guide - Complete AI-powered workflow documentation

🤝 Contributing

Contributions welcome! This project benefits from:

• New Claude agent prompts for specialized work item types
• Additional project templates for different domains
• Enhanced validation rules and quality checks
• Integration examples for different development workflows

📄 License

MIT License - feel free to use in your projects and organizations.

🔗 Links

• Azure DevOps Documentation
• Claude AI - For AI-powered work item generation
• Work Item Types