gt:azure-devops

What this skill does

# Azure DevOps Work Item Tool

Fetch, manage, and analyze Azure DevOps work items using `tools azure-devops`.

> **Time logging:** If the user wants to log time, sync Timely, or fill Clarity timesheets, stop here and invoke the `/gt:timelog` command. This skill only covers raw work-item operations.

## CLI Reference

```bash
tools azure-devops workitem <id|ids>             # Fetch work item(s)
tools azure-devops query <id|url|name>           # Fetch query results (supports name matching)
tools azure-devops query <id> --download-workitems  # Download all to files
tools azure-devops dashboard <id|url>            # Get dashboard queries
tools azure-devops list                          # List cached items
tools azure-devops workitem-create               # Create work item
tools azure-devops timelog configure             # Interactive: setup API key, user, allowed types
tools azure-devops timelog types                 # List available time types
tools azure-devops timelog list -w <id>          # List time logs for work item
tools azure-devops timelog add -w <id> -h <hrs>  # Log time entry (with precheck)
tools azure-devops timelog prepare-import add    # Stage entries for review before import
tools azure-devops timelog prepare-import list   # Review staged entries
tools azure-devops timelog prepare-import remove # Remove staged entry
tools azure-devops timelog prepare-import clear  # Clear all staged entries
tools azure-devops timelog import <file>         # Bulk import time logs (with precheck)
```

### Options

| Option | Description |
|--------|-------------|
| `--format ai\|md\|json` | Output format (default: ai) |
| `--force`, `--refresh` | Bypass cache |
| `--state <states>` | Filter by state (comma-separated) |
| `--severity <sev>` | Filter by severity (comma-separated) |
| `--download-workitems` | Download all items from query |
| `--category <name>` | Save to tasks/<category>/ |
| `--task-folders` | Save in tasks/<id>/ subfolder |
| `--attachments-from <datetime>` | Download attachments created after this date |
| `--attachments-to <datetime>` | Download attachments created before this date (default: now) |
| `--attachments-prefix <prefix>` | Only attachments starting with this name |
| `--attachments-suffix <suffix>` | Only attachments ending with this (e.g. .har) |
| `--output-dir <path>` | Custom directory for downloaded attachments |
| `--images` | Download inline images from description/comments |

### Output Paths

- **Tasks**: `.claude/azure/tasks/` → `<id>-<Slug-Title>.md`
- With `--category react19`: `.claude/azure/tasks/react19/<id>-<Slug>.md`
- With `--task-folders`: `.claude/azure/tasks/<id>/<id>-<Slug>.md`

### Attachment Output Paths

Attachments are downloaded when any `--attachments-*` filter flag is provided. Without filters, attachments are listed in output with a suggested download command.

- **Default**: Same folder as task file: `.claude/azure/tasks/<taskid>-<attachment-name>`
- With `--task-folders`: `.claude/azure/tasks/<id>/<taskid>-<attachment-name>`
- With `--output-dir /custom/path`: `/custom/path/<taskid>-<attachment-name>`

### Inline Image Output Paths

Inline images (screenshots embedded in description/comments HTML) are downloaded when `--images` is provided.

- **Default**: Same folder as task file: `.claude/azure/tasks/<taskid>-<imagename>.png`
- With `--task-folders`: `.claude/azure/tasks/<id>/<taskid>-<imagename>.png`
- Images are referenced in the `.md` file with relative paths

**Recommended**: Use `--task-folders --images` together to keep each work item's files organized in its own directory.

## Operations

### Fetch Work Items

```bash
tools azure-devops workitem 261575
tools azure-devops workitem 261575,261576,261577
tools azure-devops workitem 261575 --category react19
tools azure-devops workitem 261575 --force
```

### Fetch Query

The `--query` option supports three input formats:

1. **Query ID (GUID)**: `d6e14134-9d22-4cbb-b897-b1514f888667`
2. **Full URL**: `https://dev.azure.com/org/project/_queries/query/abc123`
3. **Query Name**: `"Otevřené bugy"` (fuzzy matching supported)

```bash
# By ID
tools azure-devops query d6e14134-9d22-4cbb-b897-b1514f888667

# By name (uses fuzzy matching to find the query)
tools azure-devops query "Open Bugs"
tools azure-devops query "Otevřené bugy"

# With filters
tools azure-devops query <id> --state Active,Development
tools azure-devops query "Active Tasks" --download-workitems --category react19
```

**Query Name Matching:**
- Exact matches are used immediately
- Fuzzy matching finds the closest query name if no exact match
- Shows alternatives if multiple similar queries exist
- Query list is cached for 1 day for fast lookups

### Analyze Work Items

When user says "analyze workitem/task X" or "analyze tasks from query Y":

1. Fetch work item(s) with images:
   ```bash
   tools azure-devops workitem <ids> --category <cat> --task-folders --images
   ```

2. Read the generated `.md` file for each work item

3. **Read inline images** - Check for image files next to the work item's `.md` file:
   ```bash
   ls $(dirname <path-to-workitem.md>)/<id>-*.{png,jpg,gif,jpeg} 2>/dev/null
   ```
   If images exist, use the **Read tool** to view each image file. This gives visual context for:
   - Bug screenshots showing the issue
   - Design mockups showing expected behavior
   - UI comparisons (current vs expected)

4. Spawn **Explore agent** (Task tool with `subagent_type: "Explore"`) for each:

   ```
   Analyze codebase for Azure DevOps work item:

   **#{id}: {title}**
   State: {state} | Severity: {severity}

   **Description:** {description}
   **Visual Context:** {describe what the inline images show, if any}
   **Comments:** {comments}

   Find:
   1. Relevant code files/components for this issue
   2. Current implementation and data flow
   3. Required changes
   4. Dependencies and related systems
   5. Complexity assessment

   Return: files found, current implementation, recommended approach, considerations, complexity (Low/Medium/High)
   ```

5. Write `.analysis.md` next to the work item file:
   - Work item: `.claude/azure/tasks/261575-Title.md`
   - Analysis: `.claude/azure/tasks/261575-Title.analysis.md`

### Analysis Document Format

```markdown
# Analysis: #{id} - {title}

**Analyzed**: {timestamp}
**Work Item**: {path to .md file}

## Summary
{1-2 sentence findings summary}

## Relevant Code
- `path/file.ts` - {purpose}

## Current Implementation
{How current code works}

## Recommended Approach
{Step-by-step plan}

## Considerations
- {Risks/considerations}

## Complexity: {Low|Medium|High}
{Reasoning}
```

## Examples

| User Request | Action |
|--------------|--------|
| "Get workitem 261575" | `tools azure-devops workitem 261575` |
| "Show query results for X" | `tools azure-devops query X` |
| "Show Open Bugs query" | `tools azure-devops query "Open Bugs"` |
| "Fetch Otevřené bugy" | `tools azure-devops query "Otevřené bugy"` |
| "Download React19 bugs" | `tools azure-devops query "React19 Bugs" --download-workitems --category react19` |
| "Analyze task 261575" | Fetch → Explore agent → Write .analysis.md |
| "Analyze all active bugs" | Fetch query with --download-workitems → Parallel Explore agents → Write .analysis.md files |
| "Download .har files from task 12345" | `tools azure-devops workitem 12345 --attachments-suffix .har` |
| "Get attachments from last hour for 12345" | Compute datetime 1h ago, then `tools azure-devops workitem 12345 --attachments-from "2026-02-12T10:00:00"` |
| "Download all attachments for task 12345" | `tools azure-devops workitem 12345 --attachments-from 2000-01-01` |
| "Get task 261575 with screenshots" | `tools azure-devops workitem 261575 --task-folders --images` |
| "Analyze bug with images" | Fetch with `--images` → Read images → Explore agent with visual context |

## Creating Work Items

The `--create` command supports multiple modes for creating new work items.

### CLI Reference

```bash
tools azure-devops w