azure-devops-cli: handle long comments on Windows (#2061) (#2140)

* azure-devops-cli: handle long comments on Windows (#2061)

On Windows 'az' is a cmd.exe batch wrapper capped at ~8191 characters,
so a long --discussion / --description value silently truncates or
fails. Document three verified ways out so the coding agent doesn't
waste 3-5 turns falling back to raw token retrieval and REST:

1. azps.ps1 in PowerShell on Windows. Same Azure CLI, invoked through
   the Python entry point with no cmd.exe length cap. Pair with
   'Get-Content -Raw' so the body lives in a variable, not on the
   command line.

2. Native --file-path flags where Azure CLI offers them. Applies to
   'az devops wiki page create' and 'az devops wiki page update', both
   documented with --encoding.

3. 'az devops invoke --in-file' as the universal escape hatch for
   commands with no --file-path (work-item --discussion, PR
   --description). Documented example posts to the work item
   comments REST endpoint with api-version 7.0-preview.3.

The earlier draft suggested the Azure CLI '@<file>' convention as a
generic substitute for inline string args. The official docs only
document it for JSON parameters and the CLI source uses
'get_file_json' specifically, so the claim is removed and replaced
with an explicit warning not to rely on it for plain string args.

Files touched:
- skills/azure-devops-cli/SKILL.md: new 'Posting long comments on
  Windows' section with shell-detection table and three verified
  options.
- skills/azure-devops-cli/references/boards-and-iterations.md: short
  pointer at each --discussion example back to SKILL.md, plus an
  inline PowerShell snippet.

Closes #2061.

* azure-devops-cli: move long-comments guidance to reference file (#2061 review)

aaronpowell asked for the Windows long-comments section to live as a
reference file rather than inline in SKILL.md, so the token weight
isn't always loaded into the agent's context.

- Move the "Posting long comments on Windows" section to a new
  references/long-comments-on-windows.md verbatim.
- Strip the section from SKILL.md (56 fewer lines in the always-loaded
  surface).
- Add the new file to the Reference Files table in SKILL.md with a
  one-line "when to read" hint covering --discussion, --description,
  and --content failures on Windows.
- Update the two pointer comments in references/boards-and-iterations.md
  to point at the new reference file instead of the SKILL.md section.

docs/README.skills.md regenerated by 'npm run build' to pick up the
new reference file in the skill's bundled assets column.

skills/azure-devops-cli/SKILL.md

@@ -92,3 +92,4 @@ Read the relevant reference file based on the user's task. Each file contains co
 | `references/org-and-security.md` | Projects, teams, users, permissions, wikis | Projects, Extensions, Teams, Users, Security groups/permissions, Service endpoints, Wikis, Admin |
 | `references/advanced-usage.md` | Output formatting, JMESPath queries | Output formats, JMESPath queries (basic + advanced), Global args, Common params, Git aliases |
 | `references/workflows-and-patterns.md` | Automation scripts, best practices, error handling | Common workflows, Best practices, Error handling, Scripting patterns, Real-world examples |
+| `references/long-comments-on-windows.md` | Long `--discussion`, `--description`, or `--content` values failing on Windows | The `cmd.exe` 8191 char cap on `az.cmd`, shell detection, and three verified workarounds (`azps.ps1`, native `--file-path`, `az devops invoke --in-file`) |

skills/azure-devops-cli/references/boards-and-iterations.md

@@ -56,6 +56,10 @@ az boards work-item create \
   --type Bug \
   --discussion "Initial investigation completed"
 
+# For a long --discussion body on Windows, see references/long-comments-on-windows.md.
+# Short version: use azps.ps1 in PowerShell, or fall back to 'az devops invoke'
+# with --in-file when no native --file-path flag is available.
+
 # Open in browser after creation
 az boards work-item create --title "Bug" --type Bug --open
 ```
@@ -85,6 +89,14 @@ az boards work-item update \
   --id {work-item-id} \
   --discussion "Work in progress"
 
+# Long comment on Windows: read the body into a PowerShell variable and call
+# azps.ps1 instead of az.cmd, or fall back to 'az devops invoke' with --in-file.
+# Full guidance in references/long-comments-on-windows.md.
+#
+# PowerShell example:
+#   $body = Get-Content -Raw .\comment.md
+#   azps.ps1 boards work-item update --id 1234 --discussion $body
+
 # Update with custom fields
 az boards work-item update \
   --id {work-item-id} \

skills/azure-devops-cli/references/long-comments-on-windows.md

@@ -0,0 +1,54 @@
+# Posting Long Comments and Bodies on Windows
+
+On Windows the `az` command resolves to `az.cmd`, a batch wrapper invoked by `cmd.exe`. The whole command line is capped at ~8191 characters, so a long `--discussion`, `--description`, or `--content` value can be silently truncated or fail. Detect the shell before composing a long argument and route accordingly. Skipping this is the most common reason the agent burns 3-5 turns falling back to raw token retrieval and REST calls.
+
+## Detect the shell first
+
+| Environment | Signal | Action |
+|---|---|---|
+| PowerShell on Windows | `$IsWindows -eq $true` and `$PSVersionTable.PSVersion` is set | Use `azps.ps1` (see below) |
+| PowerShell on macOS / Linux | `$IsWindows -eq $false` | Plain `az` is fine, no cmd.exe wrapper |
+| bash / zsh / sh | `$BASH_VERSION` or `$ZSH_VERSION` set, or `uname` works | Plain `az` is fine, no cmd.exe wrapper |
+| Windows `cmd.exe` | `%ComSpec%` ends in `cmd.exe`, no `$PSVersionTable` | Use `azps.ps1` if PowerShell is installed, otherwise see `az devops invoke` fallback below |
+
+## Option 1: `azps.ps1` (PowerShell on Windows)
+
+`azps.ps1` ships with the Azure CLI installer and invokes the Python entry point directly. No `cmd.exe` length cap.
+
+```powershell
+# Read the long body into a variable and pass it through. No quoting headaches.
+$body = Get-Content -Raw .\comment.md
+azps.ps1 boards work-item update --id 1234 --discussion $body
+```
+
+## Option 2: dedicated `--file-path` flag where Azure CLI offers one
+
+Some commands have a native file flag and you should prefer it over any inline body:
+
+- `az devops wiki page create` and `az devops wiki page update` take `--file-path` (with optional `--encoding`).
+- Use it on any shell, including Windows.
+
+```bash
+az devops wiki page create --path 'My page' --wiki myproject --file-path ./page.md --encoding utf-8
+```
+
+## Option 3: `az devops invoke` fallback
+
+When no `--file-path` exists (work-item `--discussion`, PR `--description`) and you're not in PowerShell, post the body via the underlying REST API. `az devops invoke` runs inside the Python entry point, so it isn't subject to the `cmd.exe` cap either, and it takes the request body from a file with `--in-file`:
+
+```bash
+# Post a long discussion comment to work item 1234.
+# REST: POST /{project}/_apis/wit/workItems/{id}/comments?api-version=7.0-preview.3
+az devops invoke \
+  --area wit --resource comments \
+  --route-parameters project={project} workItemId=1234 \
+  --api-version 7.0-preview.3 \
+  --http-method POST \
+  --in-file ./comment.json
+```
+
+Where `comment.json` is `{ "text": "<long markdown body>" }`. This is the universal escape hatch when neither `azps.ps1` nor `--file-path` is available. `az devops invoke` itself accepts `--in-file` natively.
+
+## Don't rely on `@<file>` for plain string args
+
+The Azure CLI `@<file>` convention is documented for JSON parameters (see [the official quoting guide](https://learn.microsoft.com/en-us/cli/azure/use-azure-cli-successfully-quoting)). It is not guaranteed to expand plain string args like `--discussion` or `--description`, so don't reach for it as a substitute for the three options above.