### Local Development Setup

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/016-pat-secure-storage/quickstart.md

Provides the necessary npm commands to install dependencies, build the project, and run the new authentication command locally.

```bash
npm install              # ensures @napi-rs/keyring is present (already in package.json)
npm run build            # tsup bundle
node dist/cli.js auth    # try the new command
npm test                 # full unit suite
npm run lint
```

--------------------------------

### End-to-End Agent Loop Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/024-azdo-pipeline/quickstart.md

An example demonstrating a full agent loop: starting a pipeline, waiting for its completion, and handling success or failure by retrieving run details.

```bash
RID=$(azdo pipeline start <def_id> --branch "$(git branch --show-current)" --json | jq .id)
if azdo pipeline wait "$RID"; then echo "green"; else azdo pipeline get-run-detail "$RID"; fi
```

--------------------------------

### Install and Build Project

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/002-get-item-command/quickstart.md

Clone the repository, install dependencies, and build the project.

```bash
git checkout 002-get-item-command
npm install
npm run build
```

--------------------------------

### Concurrent User Story Development Example (Bash)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/005-md-field-commands/tasks.md

Demonstrates a concurrent development strategy for multiple user stories (US1 and US2) after foundational setup. It outlines parallel streams of work and subsequent sequential tasks.

```bash
# After T001 (setup) + T002 (foundational), both streams can run simultaneously:

# Stream A (US1 - get-md-field):
T003 + T004 (parallel) → T005 → T006 → T007

# Stream B (US2 - set-md-field):
T008 → T009

# Then sequentially: T010 (US3) → T011 (US4) → T012 + T013 (parallel polish)
```

--------------------------------

### Parallel Tasks: Setup Phase

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/006-auto-md-display/tasks.md

Demonstrates two setup tasks that modify different files and can be executed in parallel.

```bash
# These two tasks modify different files and can run in parallel:
Task T001: "Add markdown?: boolean to CliConfig in src/types/work-item.ts"
Task T002: "Add markdown setting to SETTINGS array in src/services/config-store.ts"
```

--------------------------------

### Dependency Management Best Practice

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Do not assume tools are installed. Always list explicit dependencies and installation instructions.

```markdown
✗ Don't assume tools are installed:
  "Use the pdf library"

✓ Do list dependencies:
  "Install first: pip install pypdf
   Then: from pypdf import PdfReader"
```

--------------------------------

### Install azdo-cli

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/README.md

Install the azdo-cli globally using npm.

```bash
npm install -g azdo-cli
```

--------------------------------

### Run Full Integration Suite with Keyring Setup

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/tests/integration/README.md

Execute the complete integration test suite, including GNOME Keyring setup for headless environments. This requires credentials.

```bash
# Full suite including GNOME Keyring setup for headless environments
npm run test:integration:full
```

--------------------------------

### Setup Keyring Script (Unchanged)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/018-oauth-login/plan.md

The setup-keyring.sh script remains unchanged and is used for provisioning the CI keyring.

```text
scripts/setup-keyring.sh                          # No change — already provisions CI keyring
```

--------------------------------

### Progressive Disclosure: Quick Start + Advanced

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

A markdown structure for a skill that separates a quick start guide from advanced configuration and performance tuning references.

```markdown
# My Skill

## Quick Start (for 80% of use cases)
[simple, common workflow]

## Advanced Configuration
For configuration options, see [references/config.md](references/config.md)

## Performance Tuning
For optimization details, see [references/performance.md](references/performance.md)
```

--------------------------------

### Base CLI Setup with Bundler

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/AGENTS.md

Provides the base setup for the azdo-cli, utilizing TypeScript, Node.js LTS, commander.js, and the tsup bundler.

```typescript
import { build } from "tsup";
```

--------------------------------

### Start a Pipeline

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/README.md

Manually start a pipeline run, specifying the branch and any necessary parameters.

```bash
azdo pipeline start 12 --branch develop --parameter env=staging
```

--------------------------------

### Evaluating Triggering - Should Trigger Examples

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Provides examples of user queries that should correctly trigger a specific skill, focusing on relevant financial analysis tasks.

```markdown
- "Help me analyze our Q4 financial results"
- "Create a budget projection for next year"
- "Review our expense trends"
- "Compare our performance to competitors"
```

--------------------------------

### Manage Markdown Fields

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/commands.md

Examples for getting and setting markdown content for a specific field in a work item. Content can be provided directly, from a file, or piped from stdin.

```bash
azdo get-md-field 12345 System.Description
azdo set-md-field 12345 System.Description "# Title\n\nSome **bold** text"
azdo set-md-field 12345 System.Description --file ./description.md
cat description.md | azdo set-md-field 12345 System.Description
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/development.md

Clone the azdo-cli repository and install its npm dependencies.

```bash
git clone https://github.com/alkampfergit/azdo-cli.git
cd azdo-cli
npm install
```

--------------------------------

### New OAuth App Registration Guide

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/018-oauth-login/plan.md

A new markdown guide, oauth-app-registration.md, is added under the docs/ directory to provide instructions for registering OAuth applications. This guide is intended for both maintainers and end users.

```text
docs/oauth-app-registration.md                 # NEW — FR-015 markdown guide (audiences: maintainer + end users)
```

--------------------------------

### Start GNOME Keyring Daemon and Set Environment Variables

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/linux-credential-store.md

Start the GNOME Keyring daemon with the secrets component and export the necessary environment variables. Add these lines to your shell's startup script for automatic startup.

```bash
eval $(gnome-keyring-daemon --start --components=secrets)
export GNOME_KEYRING_CONTROL GNOME_KEYRING_PID
```

--------------------------------

### Clone and Install AzDO CLI Dependencies

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/001-azdo-cli-base/quickstart.md

Clone the repository, checkout the specified branch, and install project dependencies using npm.

```bash
git clone <repo-url>
cd azdo-cli
git checkout 001-azdo-cli-base

npm install
```

--------------------------------

### SKILL.md Markdown Body Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Demonstrates the Markdown body of a SKILL.md file, containing instructions and task steps.

```markdown
# Financial Analysis

## Step 1: Data Collection
Fetch financial statements from the available sources...

## Step 2: Ratio Analysis
Calculate key financial ratios:
- Profitability ratios (ROE, ROA, profit margin)
- Liquidity ratios (current ratio, quick ratio)
...
```

--------------------------------

### Reference File Organization Structure

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Example directory structure for organizing skill reference files.

```markdown
my-skill/
├── SKILL.md
├── references/
│   ├── quick-reference.md     (1-page cheat sheet)
│   ├── api-complete.md        (full API docs)
│   ├── advanced-patterns.md   (complex scenarios)
│   └── troubleshooting.md     (all errors)
```

--------------------------------

### GET /pullRequests/{prId} Request Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/017-pr-comments-threads/contracts/api-calls.md

This is an example of a GET request to retrieve a specific pull request by its ID. It includes the necessary headers for API version, content type, and authorization.

```http
GET /pullRequests/{prId}?api-version=7.1
Accept: application/json
Authorization: Basic <pat-b64>
```

--------------------------------

### Initial Authentication and Configuration

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/016-pat-secure-storage/quickstart.md

Demonstrates the initial state with no PAT, how to set a persistent default organization, and the first-time authentication process.

```bash
# No PAT anywhere yet.
$ unset AZDO_PAT
$ azdo work-item get 1234
Could not resolve an Azure DevOps organization. Options (in priority order):
  1. Pass --org <name> on the command line.
  2. Run this command from a git repo whose origin remote is an Azure DevOps URL.
  3. Run `azdo config set org <name>` once to set a persistent default.

# Setting a persistent default:
$ azdo config set org mycompany

# Auth for that org:
$ azdo auth
Opening https://dev.azure.com/mycompany/_usersSettings/tokens ...
Enter your Azure DevOps PAT: abcde**********vwxyz
PAT stored for org mycompany in macos-keychain.

# Now commands work without re-prompting:
$ azdo work-item get 1234
{...}
```

--------------------------------

### Get Project ID API

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/023-pr-comments-status/research.md

This API endpoint is used to retrieve the project's GUID, which is required for the policy evaluation artifactId. The project GUID is cached for the duration of the command.

```http
GET .../_apis/projects/{projectNameOrId}?api-version=7.1   → .id (GUID)
```

--------------------------------

### Skill Description with Negative Triggers

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Provides an example of how to use negative triggers to prevent over-invocation and guide Claude to simpler skills when appropriate.

```yaml
description: >
  Advanced data analysis for CSV files. Use for statistical modeling, 
  regression, clustering. Do NOT use for simple data exploration 
  (use data-viz skill instead).
```

--------------------------------

### Get Attachment Display: Short Output

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/014-work-item-attachments/contracts/download-attachment-cli.md

Example of the short output when listing attachments for a work item using the --short option.

```bash
Attachments: 2
```

--------------------------------

### Get Attachment Display: Full Output

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/014-work-item-attachments/contracts/download-attachment-cli.md

Example of the full output when listing attachments for a work item without the --short option.

```bash
Attachments:
  design.png (102.4 KB)
  requirements.docx (45.2 KB)
```

--------------------------------

### Path Conventions Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Demonstrates the correct use of forward slashes for paths in skill configurations, ensuring cross-platform compatibility.

```yaml
✓ references/guide.md
✓ scripts/helper.py
✓ templates/report.json

✗ references\guide.md
✗ scripts\helper.py
```

--------------------------------

### Markdown Structure for Skill Documentation

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Organize skill documentation using a standard Markdown structure for clarity and scannability. This includes sections for overview, quick start, detailed workflow, examples, troubleshooting, and advanced features.

```markdown
# Skill Name

## Overview
One-paragraph explanation of what the skill enables.

## Quick Start
The fastest path to success for common use cases.

## Detailed Workflow
Step-by-step instructions for the full process.

## Examples
2-3 concrete examples showing real-world usage.

## Troubleshooting
Common errors and how to fix them.

## Advanced Features
Optional advanced capabilities (with reference links).
```

--------------------------------

### Customer Onboarding Sequential Workflow with Validation

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Illustrates a sequential workflow for customer onboarding, emphasizing step-by-step execution with validation checks after critical actions like account creation and payment setup.

```markdown
# Customer Onboarding

## Step 1: Validate Input
Check that all required fields are provided:
- Customer name
- Email address
- Company name

## Step 2: Create Account
Run: `mcp-tool create_customer --name "$NAME" --email "$EMAIL"`
Verify: Confirm account created with ID returned

## Step 3: Setup Payment
Run: `mcp-tool setup_payment --customer-id "$CUSTOMER_ID"`
Verify: Payment method successfully added

## Step 4: Send Confirmation
Run: `mcp-tool send_email --template welcome --to "$EMAIL"`
Result: Welcome email sent
```

--------------------------------

### Get Policy Evaluations API

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/023-pr-comments-status/research.md

This API endpoint is used to fetch policy evaluations for a pull request, which are necessary to display 'green checks' that are not reported by the Status API. It requires an artifactId that includes the project GUID.

```http
GET .../{project}/_apis/policy/evaluations
    ?artifactId=vstfs:///CodeReview/CodeReviewId/{projectId}/{prId}
    &api-version=7.1
```

--------------------------------

### Confirm Entry-Point Docs for Login/OAuth

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/020-auth-docs-sync/quickstart.md

Verify that README.md and docs/commands.md mention 'azdo auth login' and its OAuth default.

```bash
grep -n "auth login" README.md docs/commands.md
```

--------------------------------

### SKILL.md YAML Frontmatter Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Shows the required YAML frontmatter for a SKILL.md file, including skill name and description.

```yaml
---
name: financial-analysis
description: >
  Analyze financial statements and create models with sensitivity analysis.
  Use when analyzing company financials, creating investment memos,
  or modeling scenarios.
---
```

--------------------------------

### Project Structure Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/005-md-field-commands/plan.md

Illustrates the directory structure for the markdown field commands feature, including specification and implementation-related files.

```text
specs/005-md-field-commands/
├── plan.md              # This file
├── spec.md              # Feature specification
├── research.md          # Phase 0 research findings
├── data-model.md        # Phase 1 data model
├── quickstart.md        # Phase 1 quickstart guide
├── contracts/
│   └── cli-commands.md  # CLI command contracts
├── checklists/
│   └── requirements.md  # Spec quality checklist
└── tasks.md             # Phase 2 output (created by /speckit.tasks)
```

--------------------------------

### Install Node HTML Markdown

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/005-md-field-commands/quickstart.md

Install the node-html-markdown package using npm. This is a zero-dependency HTML-to-markdown converter.

```bash
npm install node-html-markdown
```

--------------------------------

### List All CLI Configuration Values (JSON)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/003-cli-settings/contracts/cli-contract.md

Displays all currently configured settings in JSON format, suitable for machine parsing.

```bash
azdo config list --json
```

--------------------------------

### List All CLI Configuration Values (Human-readable)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/003-cli-settings/contracts/cli-contract.md

Displays all currently configured settings in a human-readable table format.

```bash
azdo config list
```

--------------------------------

### Create a User Story from a file

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/009-work-item-create-type/contracts/cli-contract.md

Example of creating a User Story work item by referencing a local markdown file.

```bash
# Create a User Story from a file
azdo upsert --type "User Story" --file ./story.md
```

--------------------------------

### Initiate PAT Login

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/018-oauth-login/quickstart.md

Start the login process using a Personal Access Token (PAT). The CLI will prompt for the PAT, which should be minted with specific scopes for security.

```bash
./dist/index.js auth login --org <O> --use-pat
```

--------------------------------

### Install GNOME Keyring and libsecret

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/linux-credential-store.md

Install the necessary packages for GNOME Keyring and libsecret on Debian/Ubuntu, Fedora/RHEL, or Arch Linux.

```bash
# Debian / Ubuntu
sudo apt-get install gnome-keyring libsecret-1-0

# Fedora / RHEL
sudo dnf install gnome-keyring libsecret

# Arch
sudo pacman -S gnome-keyring libsecret
```

--------------------------------

### Invalid Frontmatter Example (XML Tags)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Shows an example of invalid YAML frontmatter that includes XML tags, which are not permitted.

```yaml
✗ description: >
  Use <important>this</important> for data
  
✓ description: >
  Use this for data, and remember to validate
```

--------------------------------

### Parallel Tasks for User Story 1

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/020-auth-docs-sync/tasks.md

These tasks, T003 and T004, should be launched in parallel after the foundational setup (T002) is complete. They involve updating the README.md and docs/commands.md files respectively.

```text
# After T002, launch both entry-point edits together:
Task T003: Update authentication summary in README.md
Task T004: Update auth rows in docs/commands.md
```

--------------------------------

### Build and Run AzDO CLI Locally

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/001-azdo-cli-base/quickstart.md

Build the CLI into a single bundled file and run it locally without global installation to check version or help.

```bash
npm run build

node dist/index.js --version
node dist/index.js --help
```

--------------------------------

### azdo pr comments Filtered-to-empty Message Example (Code-Related)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/023-pr-comments-status/contracts/cli-commands.md

Example message displayed when the `--code-related-only` filter results in no comment threads being shown.

```text
No code-related comment threads for pull request #123.
```

--------------------------------

### Evaluating Triggering - Should NOT Trigger Examples

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Provides examples of user queries that should not trigger a specific skill, covering unrelated topics to refine trigger specificity.

```markdown
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "How do I bake cookies?"
```

--------------------------------

### Good Composability Example for Skills

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Demonstrates how a brand guidelines skill can effectively work with other skills like presentation creation and document writing.

```text
A `brand-guidelines` skill works with:
- `presentation-creation` skill
- `document-writing` skill
- `design-review` skill
- `social-media-content` skill
```

--------------------------------

### Running Integration Tests

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/016-pat-secure-storage/quickstart.md

Shows how to execute integration tests for the authentication feature, specifying the test target and mentioning the requirements for running them.

```bash
AZDO_INTEGRATION=1 npm test -- tests/integration/auth.integration.test.ts
```

--------------------------------

### Add Markdown Comment (Test Example)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/013-comments-markdown/spec.md

This is an example command for testing the addition of a markdown-formatted comment. It uses bold text to demonstrate markdown formatting.

```bash
azdo comments add <id> "**bold text**" --markdown
```

--------------------------------

### Read Work Item Examples

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/commands.md

Demonstrates how to read a work item by ID, retrieve a short version, or fetch specific fields. Also shows how to render rich-text fields as markdown.

```bash
# Read a work item (full / short / with extra fields)
azdo get-item 12345
azdo get-item 12345 --short
azdo get-item 12345 --fields "System.Tags,Microsoft.VSTS.Common.Priority"

# Convert rich-text fields to markdown
azdo get-item 12345 --markdown
```

--------------------------------

### Project Structure: Documentation

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/001-azdo-cli-base/plan.md

Illustrates the directory structure for documentation files related to the AzDO CLI base implementation.

```text
specs/001-azdo-cli-base/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
│   └── cli-interface.md
└── tasks.md             # Phase 2 output (/speckit.tasks command)
```

--------------------------------

### Start Pipeline Run

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/024-azdo-pipeline/quickstart.md

Manually start a pipeline run for a given definition, specifying the branch and optional parameters. Extracts the run ID from JSON output.

```bash
azdo pipeline start <def_id> --branch develop
```

```bash
azdo pipeline start <def_id> --branch develop --parameter env=staging --json | jq .id
```

--------------------------------

### Folder Naming Rules Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Illustrates correct and incorrect folder naming conventions, emphasizing kebab-case and avoiding spaces or special characters.

```table
| Rule | Example |
|---|---|
| **kebab-case only** | `financial-analysis` ✓ / `Financial-Analysis` ✗ / `financial_analysis` ✗ |
| **No spaces** | `code-review` ✓ / `code review` ✗ |
| **No special characters** | `pdf-processor` ✓ / `pdf@processor` ✗ |
| **Lowercase** | `brand-guidelines` ✓ / `Brand-Guidelines` ✗ |
```

--------------------------------

### Work Item JSON Output Shape Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/commands.md

Example of the JSON structure returned for work item operations, including action, ID, type, and fields.

```json
{
  "action": "created",
  "id": 12345,
  "workItemType": "User Story",
  "fields": {
    "System.Title": "Improve markdown import UX"
  }
}
```

--------------------------------

### Path Formatting Best Practice

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/Claude_Skills_Complete_Guide.md

Use forward slashes for paths in instructions, as they work universally. Avoid Windows-style backslashes.

```markdown
✗ Don't use Windows paths:
  instructions/step.md (wrong: backslashes)

✓ Do use forward slashes:
  instructions/step.md (right: works everywhere)
```

--------------------------------

### Work Item Task Document Format Example

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/docs/commands.md

Example of the markdown format for defining work item fields like Title, Assigned To, State, and Description.

```md
---
Title: Improve markdown import UX
Assigned To: user@example.com
State: New
Tags: cli; markdown
Priority: null
---

## Description

Implement a single-command task import flow.

## Acceptance Criteria

- Supports create when no ID is passed
- Supports update when an ID is passed
```

--------------------------------

### azdo pr comments Filtered-to-empty Message Example (Unresolved)

Source: https://github.com/alkampfergit/azdo-cli/blob/develop/specs/023-pr-comments-status/contracts/cli-commands.md

Example message displayed when the `--exclude-resolved` or `--hide-resolved` filter results in no comment threads being shown.

```text
No unresolved comment threads for pull request #123.
```