feat: CommunicationAdapter — platform-agnostic agent-human communication

docs/blog/023-squad-goes-enterprise-azure-devops.md

@@ -0,0 +1,226 @@
+---
+title: "Squad Goes Enterprise — Azure DevOps, Area Paths, and Cross-Project Work Items"
+date: 2026-03-07
+author: "Tamir Dresher"
+wave: null
+tags: [squad, azure-devops, enterprise, platform-adapter, work-items, area-paths, iteration-paths]
+status: published
+hero: "Squad now speaks Azure DevOps natively — auto-detection, configurable work item types, area/iteration paths, and cross-project support for enterprise environments."
+---
+
+# Squad Goes Enterprise — Azure DevOps, Area Paths, and Cross-Project Work Items
+
+> Blog post #23 — How Squad learned to work with enterprise ADO environments where nothing is "standard."
+
+## The Problem
+
+GitHub repos have issues. Simple. One repo, one issue tracker, one set of labels.
+
+Enterprise Azure DevOps? Not so much. Your code might live in one project, your work items in another. Your org might use "Scenario" instead of "User Story." Your team's backlog is scoped by area paths. Your sprints use iteration paths. And there's no PAT to manage — you authenticate via `az login`.
+
+Squad needed to understand all of this. Not just "detect ADO" — actually *work* in enterprise ADO environments where every project has its own rules.
+
+## What Shipped
+
+### Platform Auto-Detection
+
+Squad reads your git remote URL and figures out where you are:
+
+```
+https://dev.azure.com/myorg/myproject/_git/myrepo     → azure-devops
+git@ssh.dev.azure.com:v3/myorg/myproject/myrepo        → azure-devops
+https://myorg.visualstudio.com/myproject/_git/myrepo    → azure-devops
+```
+
+No configuration needed. `squad init` detects ADO and:
+- Skips `.github/workflows/` generation (those don't run in ADO)
+- Writes `"platform": "azure-devops"` to `.squad/config.json`
+- Generates ADO-appropriate MCP config examples
+
+### Configurable Work Item Types
+
+Not every ADO project uses "User Story." Some use "Scenario," "Bug," or custom types locked down by org policy. Now you can configure it:
+
+```json
+{
+  "version": 1,
+  "platform": "azure-devops",
+  "ado": {
+    "defaultWorkItemType": "Scenario"
+  }
+}
+```
+
+Squad uses your configured type for all work item creation — Ralph triage, agent task creation, everything.
+
+### Area Paths — Route to the Right Team
+
+In enterprise ADO, area paths determine which team's backlog a work item appears in. A work item in `"MyProject\Frontend"` shows up on the Frontend team's board. One in `"MyProject\Platform"` goes to Platform.
+
+```json
+{
+  "ado": {
+    "areaPath": "MyProject\\Team Alpha"
+  }
+}
+```
+
+Now when Squad creates work items, they land on the right team's board — not lost in the root backlog.
+
+### Iteration Paths — Sprint Placement
+
+Same story for sprints. Enterprise teams plan in iterations, and work items need to appear in the right sprint:
+
+```json
+{
+  "ado": {
+    "iterationPath": "MyProject\\Sprint 5"
+  }
+}
+```
+
+### Cross-Project Work Items — The Enterprise Killer Feature
+
+Here's the one that matters most for large organizations: **your git repo and your work items might live in completely different ADO projects — or even different orgs.**
+
+Common pattern in enterprise:
+- **Code** lives in `Engineering/my-service` (locked-down project with strict CI)
+- **Work items** live in `Planning/team-backlog` (PM-managed project with custom process templates)
+
+Squad now supports this cleanly:
+
+```json
+{
+  "version": 1,
+  "platform": "azure-devops",
+  "ado": {
+    "org": "planning-org",
+    "project": "team-backlog",
+    "defaultWorkItemType": "Scenario",
+    "areaPath": "team-backlog\\Alpha Squad",
+    "iterationPath": "team-backlog\\2026-Q1\\Sprint 5"
+  }
+}
+```
+
+When `ado.org` or `ado.project` are set, Squad uses them for all work item operations (create, query, tag, comment) while continuing to use the git remote's org/project for repo operations (branches, PRs, commits).
+
+The WIQL queries, `az boards` commands, and Ralph's triage loop all respect this split.
+
+## The Full Config Reference
+
+All fields are optional. Omit any field to use the default.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `ado.org` | *(from git remote)* | ADO org for work items |
+| `ado.project` | *(from git remote)* | ADO project for work items |
+| `ado.defaultWorkItemType` | `"User Story"` | Type for new work items |
+| `ado.areaPath` | *(project default)* | Team backlog routing |
+| `ado.iterationPath` | *(project default)* | Sprint board placement |
+
+## Security — No PATs Needed
+
+Squad uses `az login` for authentication. No Personal Access Tokens to rotate, no secrets in config files. Your Azure CLI session handles everything.
+
+For environments where MCP tools are available, Squad also supports the Azure DevOps MCP server for richer API access:
+
+```json
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "npx",
+      "args": ["-y", "@azure/devops-mcp-server"]
+    }
+  }
+}
+```
+
+## Security Hardening
+
+The ADO adapter went through a thorough security review:
+
+- **Shell injection prevention** — All `execSync` calls replaced with `execFileSync` (args as arrays, not concatenated strings)
+- **WIQL injection prevention** — `escapeWiql()` helper doubles single-quotes in all user-supplied values
+- **Bearer token protection** — Planner adapter passes tokens via `curl --config stdin` instead of CLI args (invisible to `ps aux`)
+
+## What We Tested
+
+External integration testing against real ADO environments (WDATP, OS, SquadDemo projects):
+
+| Test | Result |
+|------|--------|
+| ADO project connectivity | ✅ |
+| Repo discovery | ✅ |
+| Branch creation | ✅ |
+| Git clone + push | ✅ |
+| Squad init (platform detection) | ✅ |
+| PR creation + auto-complete | ✅ |
+| PR read/list/comment | ✅ |
+| Commit search | ✅ |
+| Work item CRUD | ✅ |
+| WIQL tag queries | ✅ |
+| Cross-project work items | ✅ |
+
+The only blockers encountered were project-specific restrictions (locked-down work item types in WDATP) — not Squad bugs.
+
+## Ralph in ADO
+
+Ralph's coordinator prompt is now platform-aware. When running against ADO, Ralph uses WIQL queries instead of GitHub issue queries:
+
+```wiql
+SELECT [System.Id] FROM WorkItems 
+WHERE [System.Tags] Contains 'squad' 
+  AND [System.State] <> 'Closed'
+  AND [System.TeamProject] = 'team-backlog'
+ORDER BY [System.CreatedDate] DESC
+```
+
+The full triage → assign → branch → PR → merge loop works end-to-end with ADO.
+
+## Ralph + ADO: The Governance Fix
+
+The coordinator prompt (`squad.agent.md`) is what tells Ralph *where* to look for work. Previously, it only had GitHub commands — `gh issue list`, `gh pr list`. Even if the ADO adapter was perfect, Ralph would still scan GitHub because that's what the governance file told it to do.
+
+We fixed this at every level:
+- **MCP detection** — Added `azure-devops-*` to the tool prefix table so the coordinator recognizes ADO MCP tools
+- **Platform Detection section** — New section in the governance file explaining how to detect GitHub vs ADO from the git remote
+- **Issue Awareness** — Now shows both GitHub and ADO queries, with instructions to read `.squad/config.json` first
+- **Ralph Step 1** — Platform-aware scan with both GitHub and ADO command blocks, plus the critical instruction: *"Read `.squad/config.json` for the `ado` section FIRST — do NOT guess the ADO project from the repo name"*
+
+This is the kind of bug that's invisible in unit tests — the code works, but the governance prompt doesn't tell the coordinator to use it.
+
+## Getting Started
+
+```bash
+# 1. Install Squad
+npm install -g @bradygaster/squad-cli
+
+# 2. Clone your ADO repo
+git clone https://dev.azure.com/your-org/your-project/_git/your-repo
+cd your-repo
+
+# 3. Make sure az CLI is set up
+az login
+az extension add --name azure-devops
+
+# 4. Init Squad (auto-detects ADO)
+squad init
+
+# 5. Edit .squad/config.json if you need custom work item config
+# 6. Start working!
+```
+
+Full documentation: [Enterprise Platforms Guide](../features/enterprise-platforms.md)
+
+## What's Next
+
+- **Process template introspection** — Auto-detect available work item types from the ADO process template (#240)
+- **ADO webhook integration** — Real-time work item change notifications
+- **Azure Pipelines scaffolding** — Generate pipeline YAML during `squad init` for ADO repos
+
+---
+
+*The enterprise doesn't bend to your tools. Your tools bend to the enterprise. Squad now does.*
+
+PR: [#191 — Azure DevOps platform adapter](https://github.com/bradygaster/squad/pull/191)

docs/features/enterprise-platforms.md

@@ -120,7 +120,7 @@ Squad prefers MCP tools when available, falling back to `az` CLI when not.
 To explicitly check which platform Squad detects:
 
 ```typescript
-import { detectPlatform } from '@bradygaster/squad-sdk';
+import { detectPlatform } from '@bradygaster/squad/platform';
 
 const platform = detectPlatform('/path/to/repo');
 // Returns 'github', 'azure-devops', or 'planner'

packages/squad-sdk/src/platform/comms-ado-discussions.ts

@@ -0,0 +1,114 @@
+/**
+ * Azure DevOps Work Item Discussion communication adapter.
+ *
+ * Posts updates as work item comments and reads replies via `az boards`.
+ * Phone-capable via ADO mobile app.
+ *
+ * @module platform/comms-ado-discussions
+ */
+
+import { execFileSync } from 'node:child_process';
+import type { CommunicationAdapter, CommunicationChannel, CommunicationReply } from './types.js';
+
+const EXEC_OPTS: { encoding: 'utf-8'; stdio: ['pipe', 'pipe', 'pipe'] } = { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+/** Safely parse JSON output */
+function parseJson<T>(raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`Failed to parse JSON: ${(err as Error).message}\nRaw: ${raw}`);
+  }
+}
+
+export class ADODiscussionCommunicationAdapter implements CommunicationAdapter {
+  readonly channel: CommunicationChannel = 'ado-work-items';
+
+  constructor(
+    private readonly org: string,
+    private readonly project: string,
+  ) {}
+
+  private get orgUrl(): string {
+    return `https://dev.azure.com/${this.org}`;
+  }
+
+  async postUpdate(options: {
+    title: string;
+    body: string;
+    category?: string;
+    author?: string;
+  }): Promise<{ id: string; url?: string }> {
+    const prefix = options.author ? `**${options.author}:** ` : '';
+    const categoryTag = options.category ? ` [${options.category}]` : '';
+    const fullTitle = `[Squad${categoryTag}] ${options.title}`;
+    const comment = `${prefix}${options.body}`;
+
+    // Create a work item to serve as the discussion thread
+    const output = execFileSync('az', [
+      'boards', 'work-item', 'create',
+      '--type', 'Task',
+      '--title', fullTitle,
+      '--fields', `System.Tags=squad; squad:comms`,
+      '--discussion', comment,
+      '--org', this.orgUrl,
+      '--project', this.project,
+      '--output', 'json',
+    ], EXEC_OPTS);
+
+    const wi = parseJson<{
+      id: number;
+      _links?: { html?: { href?: string } };
+      url: string;
+    }>(output);
+
+    return {
+      id: String(wi.id),
+      url: wi._links?.html?.href ?? wi.url,
+    };
+  }
+
+  async pollForReplies(options: {
+    threadId: string;
+    since: Date;
+  }): Promise<CommunicationReply[]> {
+    // Read work item comments (discussion history)
+    const output = execFileSync('az', [
+      'boards', 'work-item', 'show',
+      '--id', options.threadId,
+      '--org', this.orgUrl,
+      '--project', this.project,
+      '--expand', 'all',
+      '--output', 'json',
+    ], EXEC_OPTS);
+
+    const wi = parseJson<{
+      id: number;
+      fields: Record<string, unknown>;
+      comments?: Array<{
+        id: number;
+        text: string;
+        createdDate: string;
+        createdBy: { displayName: string };
+      }>;
+    }>(output);
+
+    // ADO work item show doesn't include comments directly in basic output.
+    // The discussion is in the System.History field as HTML.
+    // For a production adapter, use the REST API for comments.
+    // This is a simplified implementation.
+    const history = wi.fields['System.History'] as string | undefined;
+    if (!history) return [];
+
+    return [{
+      author: 'ado-user',
+      body: history,
+      timestamp: new Date(),
+      id: `${options.threadId}-history`,
+    }];
+  }
+
+  getNotificationUrl(threadId: string): string | undefined {
+    return `${this.orgUrl}/${this.project}/_workitems/edit/${threadId}`;
+  }
+}