ado-genai — Tools to convert Azure DevOps Wiki pages into Work Items

Summary

This repository contains documentation, prompt templates, and helper instructions to convert Azure DevOps wiki pages into User Stories and Tasks. The artifacts here are designed to be used by an assistant (or manually) to create backlog items from structured wiki content.

What's included

• .github/
  • copilot-custom-instructions.md — team guidance for Copilot suggestions and PR/testing expectations.
  • repro-wiki-to-workitems.prompt.md — interactive prompt template to convert a wiki page into work items.
  • prompts-README.md — how to use the prompt file safely and effectively.
• docs/
  • repro-wiki-to-workitems.md — reproducible runbook and PowerShell examples. -- Other notes
• Wiki pages in the target project were updated (README and TABLE OF CONTENTS) to include TOC links.

Quick start

1. Read .github/prompts-README.md to learn how to run the prompt interactively.
2. Copy the prompt in .github/repro-wiki-to-workitems.prompt.md into your assistant (or use a script) and answer the questions.
3. Confirm proposed User Stories and Tasks before they are created in Azure DevOps.

Safety & auth

• Use a PAT or Service Principal with the minimum required scopes. Never paste secrets in public chat sessions.

Run the interactive PowerShell script

We provided an interactive PowerShell helper script that runs the prompt flow and creates work items via the Azure DevOps REST API.

1. Open PowerShell (pwsh) and set your Personal Access Token (recommended) as an environment variable:

$env:AZDO_PAT = 'YOUR_PERSONAL_ACCESS_TOKEN'

2. Run the script and follow the interactive prompts:

pwsh .\scripts\repro-wiki-to-workitems.ps1

Notes about the script:

• The script will fetch the wiki page, parse sections into candidate stories, and ask you to approve/edit/skip each candidate.
• The script will only create work items after you explicitly confirm the final creation step.
• You can provide a PAT interactively if you don't want to set AZDO_PAT.

Using the prompt directly

If you prefer to use the prompt directly with an assistant (ChatGPT, Copilot Chat, etc.):

1. Open .github/repro-wiki-to-workitems.prompt.md and copy the prompt text into your assistant session.
2. Answer the interactive questions (project, wiki path, split method, approvals).
3. Approve proposed stories and tasks before any creation action.

Security and best practices

• Never paste your PAT into public chat or logs. Use environment variables or secure prompts.
• Test the script in a sandbox project before running against production.
• If your organization uses a custom process template, you may need to adjust field names (story type, acceptance criteria field, etc.) in the script.

Run the Node CLI

We also scaffolded a minimal Node.js CLI that performs the same interactive flow and calls the Azure DevOps REST APIs.

1. Install dependencies from the repository root:

npm install

2. Run the CLI locally:

node ./src/cli.js

3. Optional: run as an installed command using npx (no global install required):

npx node ./src/cli.js

4. Optional: install globally for a system command:

npm install -g .
ado-genai

Notes:

• The CLI will prompt for a PAT if AZDO_PAT is not set. Prefer setting AZDO_PAT as an environment variable for non-interactive runs:

$env:AZDO_PAT = 'YOUR_PERSONAL_ACCESS_TOKEN'

• As with the PowerShell script, review and approve proposed stories and tasks before creation.
• I can add a --dry-run flag to the CLI to print the REST payloads instead of sending them; tell me if you'd like that.