From dd3f5d7d5f1b8cfa56f009f2eced167b8a897754 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 00:10:06 +0200
Subject: [PATCH 01/15] feat: add platform adapter for Azure DevOps support

Introduce a platform abstraction layer so Squad works with Azure DevOps
(Work Items, PRs, Pipelines) in addition to GitHub (Issues, PRs, Actions).

Platform module (packages/squad-sdk/src/platform/):
- types.ts: PlatformType, WorkItem, PullRequest, PlatformAdapter interfaces
- detect.ts: Auto-detect platform from git remote URL (github/ado)
- github.ts: GitHubAdapter wrapping gh CLI
- azure-devops.ts: AzureDevOpsAdapter wrapping az CLI
- ralph-commands.ts: Platform-specific Ralph triage commands
- index.ts: Factory createPlatformAdapter() + barrel exports

Coordinator prompt:
- Add Platform Detection section to squad.agent.md
- ADO command mapping table and prerequisites

Tests (57 passing):
- Platform detection from various remote URLs
- GitHub remote parsing (owner/repo extraction)
- ADO remote parsing (org/project/repo extraction)
- WorkItem/PullRequest type shape validation
- Ralph command generation for both platforms
- Edge cases (case insensitivity, unknown platforms)

Docs:
- docs/features/azure-devops.md: User guide
- docs/specs/platform-adapter-prd.md: Design spec

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .squad/.first-run                             |   1 +
 .squad/config.json                            |   4 +
 docs/features/enterprise-platforms.md         | 137 +++++
 docs/specs/platform-adapter-prd.md            |  61 ++
 package.json                                  |   2 +-
 packages/squad-cli/package.json               |   2 +-
 packages/squad-cli/src/cli-entry.ts           |  47 +-
 packages/squad-sdk/package.json               |   2 +-
 packages/squad-sdk/src/index.ts               |   1 +
 .../squad-sdk/src/platform/azure-devops.ts    | 248 ++++++++
 packages/squad-sdk/src/platform/detect.ts     | 140 +++++
 packages/squad-sdk/src/platform/github.ts     | 191 ++++++
 packages/squad-sdk/src/platform/index.ts      |  46 ++
 packages/squad-sdk/src/platform/planner.ts    | 188 ++++++
 .../squad-sdk/src/platform/ralph-commands.ts  |  93 +++
 packages/squad-sdk/src/platform/types.ts      |  64 ++
 packages/squad-sdk/src/types.ts               |   9 +
 templates/squad.agent.md                      |  55 ++
 test/cli/consult.test.ts                      |   4 +-
 test/cli/init.test.ts                         |   2 +-
 test/platform-adapter.test.ts                 | 572 ++++++++++++++++++
 21 files changed, 1845 insertions(+), 24 deletions(-)
 create mode 100644 .squad/.first-run
 create mode 100644 .squad/config.json
 create mode 100644 docs/features/enterprise-platforms.md
 create mode 100644 docs/specs/platform-adapter-prd.md
 create mode 100644 packages/squad-sdk/src/platform/azure-devops.ts
 create mode 100644 packages/squad-sdk/src/platform/detect.ts
 create mode 100644 packages/squad-sdk/src/platform/github.ts
 create mode 100644 packages/squad-sdk/src/platform/index.ts
 create mode 100644 packages/squad-sdk/src/platform/planner.ts
 create mode 100644 packages/squad-sdk/src/platform/ralph-commands.ts
 create mode 100644 packages/squad-sdk/src/platform/types.ts
 create mode 100644 test/platform-adapter.test.ts

diff --git a/.squad/.first-run b/.squad/.first-run
new file mode 100644
index 00000000..fabbbc86
--- /dev/null
+++ b/.squad/.first-run
@@ -0,0 +1 @@
+2026-03-04T23:08:20.566Z
diff --git a/.squad/config.json b/.squad/config.json
new file mode 100644
index 00000000..4bbe45a9
--- /dev/null
+++ b/.squad/config.json
@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "teamRoot": "C:\\temp\\squad-streams"
+}
\ No newline at end of file
diff --git a/docs/features/enterprise-platforms.md b/docs/features/enterprise-platforms.md
new file mode 100644
index 00000000..33c9b407
--- /dev/null
+++ b/docs/features/enterprise-platforms.md
@@ -0,0 +1,137 @@
+# Enterprise Platforms
+
+Squad supports Azure DevOps and Microsoft Planner in addition to GitHub. When your git remote points to Azure DevOps, Squad automatically detects the platform and adapts its commands. For work-item tracking, Squad also supports a hybrid model where code lives in one platform and tasks live in Microsoft Planner.
+
+## Prerequisites
+
+1. **Azure CLI** — Install from [https://aka.ms/install-az-cli](https://aka.ms/install-az-cli)
+2. **Azure DevOps extension** — `az extension add --name azure-devops`
+3. **Login** — `az login`
+4. **Set defaults** — `az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT`
+
+Verify setup:
+
+```bash
+az devops configure --list
+# Should show organization and project
+```
+
+## How It Works
+
+Squad auto-detects the platform from your git remote URL:
+
+| Remote URL pattern | Detected platform |
+|---|---|
+| `github.com` | GitHub |
+| `dev.azure.com` | Azure DevOps |
+| `*.visualstudio.com` | Azure DevOps |
+| `ssh.dev.azure.com` | Azure DevOps |
+
+## Differences from GitHub
+
+### Work Items vs Issues
+
+| GitHub | Azure DevOps |
+|---|---|
+| Issues | Work Items |
+| Labels (e.g., `squad:alice`) | Tags (e.g., `squad:alice`) |
+| `gh issue list --label X` | WIQL query via `az boards query` |
+| `gh issue edit --add-label` | `az boards work-item update --fields "System.Tags=..."` |
+
+### Pull Requests
+
+| GitHub | Azure DevOps |
+|---|---|
+| `gh pr list` | `az repos pr list` |
+| `gh pr create` | `az repos pr create` |
+| `gh pr merge` | `az repos pr update --status completed` |
+| Review: Approved / Changes Requested | Vote: 10 (approved) / -10 (rejected) |
+
+### Branch Operations
+
+Branch operations use the same `git` commands on both platforms. Squad creates branches with the naming convention `squad/{id}-{slug}`.
+
+## Ralph on Azure DevOps
+
+Ralph works identically on ADO — he scans for untriaged work items using WIQL queries instead of GitHub label filters:
+
+```
+# GitHub
+gh issue list --label "squad:untriaged" --json number,title,labels
+
+# Azure DevOps
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged'"
+```
+
+Tag assignment uses the same `squad:{member}` convention, stored as ADO work item tags separated by `;`.
+
+## Configuration
+
+No additional configuration is needed beyond the `az` CLI setup. Squad reads the git remote URL and automatically selects the correct adapter.
+
+To explicitly check which platform Squad detects:
+
+```typescript
+import { detectPlatform } from '@bradygaster/squad/platform';
+
+const platform = detectPlatform('/path/to/repo');
+// Returns 'github', 'azure-devops', or 'planner'
+```
+
+---
+
+## Microsoft Planner Support (Hybrid Model)
+
+Squad supports a hybrid model where your **repository** lives in GitHub or Azure DevOps, but **work items** are tracked in Microsoft Planner. This is common in enterprise environments where project management uses Planner while engineering uses ADO or GitHub for code.
+
+### How It Works
+
+- Planner **buckets** map to squad assignments: `squad:untriaged`, `squad:riker`, `squad:data`, etc.
+- Moving a task between buckets = reassigning to a team member
+- Task completion = 100% complete or move to "Done" bucket
+- PRs and branches still go through the repo adapter (GitHub or Azure DevOps)
+
+### Prerequisites
+
+1. **Azure CLI** — `az login`
+2. **Graph API access** — `az account get-access-token --resource-type ms-graph`
+3. **Plan ID** — Found in the Planner URL or via Graph API
+
+### Configuration
+
+In `squad.config.ts`, specify the hybrid model:
+
+```typescript
+const config: SquadConfig = {
+  // ... other config
+  platform: {
+    repo: 'azure-devops',     // where code lives
+    workItems: 'planner',     // where tasks live
+    planId: 'rYe_WFgqUUqnSTZfpMdKcZUAER1P',
+  },
+};
+```
+
+### Ralph with Planner
+
+Ralph scans Planner tasks via the Microsoft Graph API instead of GitHub labels or ADO WIQL:
+
+```
+# List untriaged tasks
+GET /planner/plans/{planId}/tasks  →  filter by "squad:untriaged" bucket
+
+# Assign to member (move to their bucket)
+PATCH /planner/tasks/{taskId}  →  { "bucketId": "{squad:member bucket ID}" }
+```
+
+PR operations still use the repo adapter:
+
+```
+# Repo on Azure DevOps
+az repos pr list --status active
+az repos pr create --source-branch ... --target-branch ...
+
+# Repo on GitHub
+gh pr list --state open
+gh pr create --head ... --base ...
+```
diff --git a/docs/specs/platform-adapter-prd.md b/docs/specs/platform-adapter-prd.md
new file mode 100644
index 00000000..e892501b
--- /dev/null
+++ b/docs/specs/platform-adapter-prd.md
@@ -0,0 +1,61 @@
+# Platform Adapter — Design Spec
+
+## Overview
+
+The Platform Adapter abstraction allows Squad to work with multiple source code hosting platforms (GitHub, Azure DevOps) through a unified interface. This enables Ralph and the coordinator to use the same triage/assignment logic regardless of the underlying platform.
+
+## Design Decisions
+
+### 1. Interface-based abstraction
+
+We use a TypeScript interface (`PlatformAdapter`) rather than an abstract class. This keeps the contract pure and allows each adapter to manage its own dependencies independently.
+
+### 2. CLI-based implementations
+
+Both adapters wrap CLI tools (`gh` for GitHub, `az` for ADO) rather than using REST APIs directly. This:
+- Leverages existing authentication (users are already logged into `gh`/`az`)
+- Avoids managing OAuth tokens, PATs, or refresh flows
+- Matches how Squad already interacts with GitHub
+
+### 3. Auto-detection from git remote
+
+Platform detection reads the `origin` remote URL. This is zero-config — users don't need to specify which platform they're on.
+
+### 4. Graceful failure
+
+If the required CLI is not installed, the adapter throws a descriptive error with installation instructions rather than a cryptic exec failure.
+
+## Mapping Table
+
+| Concept | GitHub | Azure DevOps |
+|---|---|---|
+| Work item | Issue | Work Item |
+| Work item query | `gh issue list --label X` | WIQL via `az boards query` |
+| Work item tags | Labels | Tags (`;`-separated) |
+| Pull request list | `gh pr list` | `az repos pr list` |
+| Pull request create | `gh pr create` | `az repos pr create` |
+| Pull request merge | `gh pr merge` | `az repos pr update --status completed` |
+| Branch create | `git checkout -b` | `git checkout -b` |
+| Review status | `reviewDecision` field | `vote` field on reviewers |
+| Authentication | `gh auth login` | `az login` |
+
+## Module Structure
+
+```
+packages/squad-sdk/src/platform/
+├── types.ts          # PlatformType, WorkItem, PullRequest, PlatformAdapter
+├── detect.ts         # detectPlatform, parseGitHubRemote, parseAzureDevOpsRemote
+├── github.ts         # GitHubAdapter
+├── azure-devops.ts   # AzureDevOpsAdapter
+├── ralph-commands.ts # getRalphScanCommands
+└── index.ts          # Factory + barrel exports
+```
+
+## Future Work
+
+- **GitLab adapter** — Same interface, wrapping `glab` CLI
+- **Bitbucket adapter** — Same interface, wrapping Bitbucket APIs
+- **REST API fallback** — Direct API calls when CLI tools aren't available
+- **Token-based auth** — Support PAT/token auth for CI environments
+- **Pipelines abstraction** — Normalize GitHub Actions and Azure Pipelines
+- **Board view** — Normalize GitHub Projects and ADO Boards
diff --git a/package.json b/package.json
index 4aaf04aa..3555689f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad",
-  "version": "0.8.21-preview.1",
+  "version": "0.8.21-preview.4",
   "private": true,
   "description": "Squad — Programmable multi-agent runtime for GitHub Copilot, built on @github/copilot-sdk",
   "type": "module",
diff --git a/packages/squad-cli/package.json b/packages/squad-cli/package.json
index 569299fc..df55c88a 100644
--- a/packages/squad-cli/package.json
+++ b/packages/squad-cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-cli",
-  "version": "0.8.21-preview.1",
+  "version": "0.8.21-preview.4",
   "description": "Squad CLI — Command-line interface for the Squad multi-agent runtime",
   "type": "module",
   "bin": {
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index e0989212..1be85c15 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -33,27 +33,42 @@ async function main(): Promise<void> {
   // --help / -h / help
   if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     console.log(`\n${BOLD}squad${RESET} v${VERSION} — Add an AI agent team to any project\n`);
-    console.log(`Usage: squad [command] [options]\n`);
-    console.log(`Commands:`);
-    console.log(`  ${BOLD}(default)${RESET}  Launch interactive shell (no args)`);
-    console.log(`             Flags: --global (init in personal squad directory)`);
+    console.log(`Usage: squad [command] [options]`);
+    console.log(`       squad <command> --help\n`);
+    console.log(`Getting Started:`);
     console.log(`  ${BOLD}init${RESET}       Initialize Squad (skip files that already exist)`);
     console.log(`             Flags: --global (init in personal squad directory)`);
-    console.log(`  ${BOLD}upgrade${RESET}    Update Squad-owned files to latest version`);
-    console.log(`             Overwrites: squad.agent.md, templates dir (.squad/templates/)`);
-    console.log(`             Never touches: .squad/ or .ai-team/ (your team state)`);
-    console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
     console.log(`  ${BOLD}status${RESET}     Show which squad is active and why`);
+    console.log(`  ${BOLD}doctor${RESET}     Validate squad setup (check files, config, health)`);
+    console.log(`  ${BOLD}help${RESET}       Show this help message`);
+    console.log(`\nDevelopment:`);
+    console.log(`  ${BOLD}(default)${RESET}  Launch interactive shell (no args)`);
+    console.log(`             Flags: --global (init in personal squad directory)`);
+    console.log(`  ${BOLD}consult${RESET}    Enter consult mode with your personal squad`);
     console.log(`  ${BOLD}triage${RESET}     Scan for work and categorize issues`);
     console.log(`             Usage: triage [--interval <minutes>]`);
     console.log(`             Default: checks every 10 minutes (Ctrl+C to stop)`);
     console.log(`  ${BOLD}loop${RESET}       Continuous work loop (Ralph mode)`);
     console.log(`             Usage: loop [--filter <label>] [--interval <minutes>]`);
     console.log(`             Default: checks every 10 minutes (Ctrl+C to stop)`);
+    console.log(`  ${BOLD}start${RESET}      Start Copilot with remote access from phone/browser`);
+    console.log(`             Usage: start [--tunnel] [--port <n>] [--command <cmd>] [copilot flags...]`);
+    console.log(`             Examples: start --tunnel --yolo`);
+    console.log(`                       start --tunnel --model claude-sonnet-4`);
+    console.log(`                       start --tunnel --command "agency copilot"`);
+    console.log(`  ${BOLD}nap${RESET}        Context hygiene (compress, prune, archive .squad/ state)`);
+    console.log(`             Usage: nap [--deep] [--dry-run]`);
+    console.log(`             Flags: --deep (thorough cleanup), --dry-run (preview only)`);
+    console.log(`\nTeam Management:`);
     console.log(`  ${BOLD}hire${RESET}       Team creation wizard`);
     console.log(`             Usage: hire [--name <name>] [--role <role>]`);
     console.log(`  ${BOLD}copilot${RESET}    Add/remove the Copilot coding agent (@copilot)`);
     console.log(`             Usage: copilot [--off] [--auto-assign]`);
+    console.log(`  ${BOLD}upgrade${RESET}    Update Squad-owned files to latest version`);
+    console.log(`             Overwrites: squad.agent.md, templates dir (.squad/templates/)`);
+    console.log(`             Never touches: .squad/ or .ai-team/ (your team state)`);
+    console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
+    console.log(`\nUtilities:`);
     console.log(`  ${BOLD}plugin${RESET}     Manage plugin marketplaces`);
     console.log(`             Usage: plugin marketplace add|remove|list|browse`);
     console.log(`  ${BOLD}export${RESET}     Export squad to a portable JSON snapshot`);
@@ -62,16 +77,6 @@ async function main(): Promise<void> {
     console.log(`             Usage: import <file> [--force]`);
     console.log(`  ${BOLD}scrub-emails${RESET}  Remove email addresses from Squad state files`);
     console.log(`             Usage: scrub-emails [directory] (default: .ai-team/)`);
-    console.log(`  ${BOLD}start${RESET}      Start Copilot with remote access from phone/browser`);
-    console.log(`             Usage: start [--tunnel] [--port <n>] [--command <cmd>] [copilot flags...]`);
-    console.log(`             Examples: start --tunnel --yolo`);
-    console.log(`                       start --tunnel --model claude-sonnet-4`);
-    console.log(`                       start --tunnel --command "agency copilot"`);
-    console.log(`  ${BOLD}nap${RESET}        Context hygiene (compress, prune, archive .squad/ state)`);
-    console.log(`             Usage: nap [--deep] [--dry-run]`);
-    console.log(`             Flags: --deep (thorough cleanup), --dry-run (preview only)`);
-    console.log(`  ${BOLD}doctor${RESET}     Validate squad setup (check files, config, health)`);
-    console.log(`  ${BOLD}help${RESET}       Show this help message`);
     console.log(`\nFlags:`);
     console.log(`  ${BOLD}--version, -v${RESET}  Print version`);
     console.log(`  ${BOLD}--help, -h${RESET}     Show help`);
@@ -259,6 +264,12 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (cmd === 'consult') {
+    const { runConsult } = await import('./cli/commands/consult.js');
+    await runConsult(process.cwd(), args.slice(1));
+    return;
+  }
+
   if (cmd === 'doctor') {
     const { doctorCommand } = await import('./cli/commands/doctor.js');
     await doctorCommand();
diff --git a/packages/squad-sdk/package.json b/packages/squad-sdk/package.json
index d5c31606..65a2d5ed 100644
--- a/packages/squad-sdk/package.json
+++ b/packages/squad-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-sdk",
-  "version": "0.8.21-preview.1",
+  "version": "0.8.21-preview.4",
   "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/squad-sdk/src/index.ts b/packages/squad-sdk/src/index.ts
index 419862fc..3ace1351 100644
--- a/packages/squad-sdk/src/index.ts
+++ b/packages/squad-sdk/src/index.ts
@@ -39,3 +39,4 @@ export * from './build/index.js';
 export * from './sharing/index.js';
 export * from './upstream/index.js';
 export * from './remote/index.js';
+export * from './platform/index.js';
diff --git a/packages/squad-sdk/src/platform/azure-devops.ts b/packages/squad-sdk/src/platform/azure-devops.ts
new file mode 100644
index 00000000..087ffecd
--- /dev/null
+++ b/packages/squad-sdk/src/platform/azure-devops.ts
@@ -0,0 +1,248 @@
+/**
+ * Azure DevOps platform adapter — wraps az CLI for work item/PR/branch operations.
+ *
+ * @module platform/azure-devops
+ */
+
+import { execSync } from 'node:child_process';
+import type { PlatformAdapter, PlatformType, WorkItem, PullRequest } from './types.js';
+
+/** Check whether the az CLI with devops extension is available */
+function assertAzCliAvailable(): void {
+  try {
+    execSync('az devops -h', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch {
+    throw new Error(
+      'Azure DevOps CLI not found. Install it with:\n' +
+      '  1. Install Azure CLI: https://aka.ms/install-az-cli\n' +
+      '  2. Add DevOps extension: az extension add --name azure-devops\n' +
+      '  3. Login: az login\n' +
+      '  4. Set defaults: az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT',
+    );
+  }
+}
+
+export class AzureDevOpsAdapter implements PlatformAdapter {
+  readonly type: PlatformType = 'azure-devops';
+
+  constructor(
+    private readonly org: string,
+    private readonly project: string,
+    private readonly repo: string,
+  ) {
+    assertAzCliAvailable();
+  }
+
+  private get orgUrl(): string {
+    return `https://dev.azure.com/${this.org}`;
+  }
+
+  private get defaults(): string {
+    return `--org "${this.orgUrl}" --project "${this.project}"`;
+  }
+
+  private exec(cmd: string): string {
+    return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  }
+
+  async listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]> {
+    const conditions: string[] = [];
+    if (options.state) {
+      conditions.push(`[System.State] = '${options.state}'`);
+    }
+    if (options.tags?.length) {
+      for (const tag of options.tags) {
+        conditions.push(`[System.Tags] Contains '${tag}'`);
+      }
+    }
+    conditions.push(`[System.TeamProject] = '${this.project}'`);
+
+    const where = conditions.join(' AND ');
+    const top = options.limit ?? 50;
+    const wiql = `SELECT [System.Id] FROM WorkItems WHERE ${where} ORDER BY [System.CreatedDate] DESC`;
+
+    const output = this.exec(
+      `az boards query --wiql "${wiql}" ${this.defaults} --output json`,
+    );
+    const items = JSON.parse(output) as Array<{ id: number; fields?: Record<string, unknown> }>;
+
+    // Fetch full details for each work item (limited by top)
+    const results: WorkItem[] = [];
+    for (const item of items.slice(0, top)) {
+      const wi = await this.getWorkItem(item.id);
+      results.push(wi);
+    }
+    return results;
+  }
+
+  async getWorkItem(id: number): Promise<WorkItem> {
+    const output = this.exec(
+      `az boards work-item show --id ${id} ${this.defaults} --output json`,
+    );
+    const wi = JSON.parse(output) as {
+      id: number;
+      fields: Record<string, unknown>;
+      url: string;
+      _links?: { html?: { href?: string } };
+    };
+
+    const fields = wi.fields;
+    const tags = typeof fields['System.Tags'] === 'string'
+      ? (fields['System.Tags'] as string).split(';').map((t) => t.trim()).filter(Boolean)
+      : [];
+    const assignedTo = fields['System.AssignedTo'] as { displayName?: string; uniqueName?: string } | undefined;
+
+    return {
+      id: wi.id,
+      title: (fields['System.Title'] as string) ?? '',
+      state: (fields['System.State'] as string) ?? '',
+      tags,
+      assignedTo: assignedTo?.displayName ?? assignedTo?.uniqueName,
+      url: wi._links?.html?.href ?? wi.url,
+    };
+  }
+
+  async addTag(workItemId: number, tag: string): Promise<void> {
+    // Get current tags, append the new one
+    const wi = await this.getWorkItem(workItemId);
+    const currentTags = wi.tags.filter((t) => t !== tag);
+    currentTags.push(tag);
+    const tagsStr = currentTags.join('; ');
+    this.exec(
+      `az boards work-item update --id ${workItemId} --fields "System.Tags=${tagsStr}" ${this.defaults} --output json`,
+    );
+  }
+
+  async removeTag(workItemId: number, tag: string): Promise<void> {
+    const wi = await this.getWorkItem(workItemId);
+    const updatedTags = wi.tags.filter((t) => t !== tag);
+    const tagsStr = updatedTags.join('; ');
+    this.exec(
+      `az boards work-item update --id ${workItemId} --fields "System.Tags=${tagsStr}" ${this.defaults} --output json`,
+    );
+  }
+
+  async addComment(workItemId: number, comment: string): Promise<void> {
+    // az boards work-item update --id ID --discussion "comment"
+    this.exec(
+      `az boards work-item update --id ${workItemId} --discussion "${comment.replace(/"/g, '\\"')}" ${this.defaults} --output json`,
+    );
+  }
+
+  async listPullRequests(options: { status?: string; limit?: number }): Promise<PullRequest[]> {
+    const args = [
+      'az', 'repos', 'pr', 'list',
+      '--repository', `"${this.repo}"`,
+      this.defaults,
+      '--output', 'json',
+    ];
+    if (options.status) args.push('--status', options.status);
+    if (options.limit) args.push('--top', String(options.limit));
+
+    const output = this.exec(args.join(' '));
+    const prs = JSON.parse(output) as Array<{
+      pullRequestId: number;
+      title: string;
+      sourceRefName: string;
+      targetRefName: string;
+      status: string;
+      isDraft: boolean;
+      reviewers: Array<{ vote: number }>;
+      createdBy: { displayName: string; uniqueName: string };
+      url: string;
+      repository?: { webUrl?: string };
+    }>;
+
+    return prs.map((pr) => ({
+      id: pr.pullRequestId,
+      title: pr.title,
+      sourceBranch: stripRefsHeads(pr.sourceRefName),
+      targetBranch: stripRefsHeads(pr.targetRefName),
+      status: mapAdoPrStatus(pr.status, pr.isDraft),
+      reviewStatus: mapAdoReviewStatus(pr.reviewers),
+      author: pr.createdBy.displayName ?? pr.createdBy.uniqueName,
+      url: pr.repository?.webUrl
+        ? `${pr.repository.webUrl}/pullrequest/${pr.pullRequestId}`
+        : pr.url,
+    }));
+  }
+
+  async createPullRequest(options: {
+    title: string;
+    sourceBranch: string;
+    targetBranch: string;
+    description?: string;
+  }): Promise<PullRequest> {
+    const args = [
+      'az', 'repos', 'pr', 'create',
+      '--repository', `"${this.repo}"`,
+      '--source-branch', options.sourceBranch,
+      '--target-branch', options.targetBranch,
+      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
+      this.defaults,
+      '--output', 'json',
+    ];
+    if (options.description) {
+      args.push('--description', `"${options.description.replace(/"/g, '\\"')}"`);
+    }
+
+    const output = this.exec(args.join(' '));
+    const pr = JSON.parse(output) as {
+      pullRequestId: number;
+      title: string;
+      sourceRefName: string;
+      targetRefName: string;
+      status: string;
+      isDraft: boolean;
+      reviewers: Array<{ vote: number }>;
+      createdBy: { displayName: string; uniqueName: string };
+      url: string;
+    };
+
+    return {
+      id: pr.pullRequestId,
+      title: pr.title,
+      sourceBranch: stripRefsHeads(pr.sourceRefName),
+      targetBranch: stripRefsHeads(pr.targetRefName),
+      status: mapAdoPrStatus(pr.status, pr.isDraft),
+      reviewStatus: mapAdoReviewStatus(pr.reviewers),
+      author: pr.createdBy.displayName ?? pr.createdBy.uniqueName,
+      url: pr.url,
+    };
+  }
+
+  async mergePullRequest(id: number): Promise<void> {
+    this.exec(
+      `az repos pr update --id ${id} --status completed ${this.defaults} --output json`,
+    );
+  }
+
+  async createBranch(name: string, fromBranch?: string): Promise<void> {
+    const base = fromBranch ?? 'main';
+    this.exec(`git checkout ${base} && git pull && git checkout -b ${name}`);
+  }
+}
+
+function stripRefsHeads(ref: string): string {
+  return ref.replace(/^refs\/heads\//, '');
+}
+
+function mapAdoPrStatus(status: string, isDraft: boolean): PullRequest['status'] {
+  if (isDraft) return 'draft';
+  switch (status.toLowerCase()) {
+    case 'active': return 'active';
+    case 'completed': return 'completed';
+    case 'abandoned': return 'abandoned';
+    default: return 'active';
+  }
+}
+
+function mapAdoReviewStatus(reviewers: Array<{ vote: number }> | undefined): PullRequest['reviewStatus'] {
+  if (!reviewers?.length) return 'pending';
+  // ADO vote: 10 = approved, -10 = rejected, 5 = approved with suggestions, -5 = waiting, 0 = no vote
+  const hasReject = reviewers.some((r) => r.vote <= -5);
+  if (hasReject) return 'changes-requested';
+  const hasApproval = reviewers.some((r) => r.vote >= 5);
+  if (hasApproval) return 'approved';
+  return 'pending';
+}
diff --git a/packages/squad-sdk/src/platform/detect.ts b/packages/squad-sdk/src/platform/detect.ts
new file mode 100644
index 00000000..64c4854b
--- /dev/null
+++ b/packages/squad-sdk/src/platform/detect.ts
@@ -0,0 +1,140 @@
+/**
+ * Auto-detect platform from git remote URL.
+ *
+ * @module platform/detect
+ */
+
+import { execSync } from 'node:child_process';
+import type { PlatformType } from './types.js';
+
+/** Parsed GitHub remote info */
+export interface GitHubRemoteInfo {
+  owner: string;
+  repo: string;
+}
+
+/** Parsed Azure DevOps remote info */
+export interface AzureDevOpsRemoteInfo {
+  org: string;
+  project: string;
+  repo: string;
+}
+
+/**
+ * Parse a GitHub remote URL into owner/repo.
+ * Supports HTTPS and SSH formats:
+ *   https://github.com/owner/repo.git
+ *   git@github.com:owner/repo.git
+ */
+export function parseGitHubRemote(url: string): GitHubRemoteInfo | null {
+  // HTTPS: https://github.com/owner/repo.git
+  const httpsMatch = url.match(/github\.com\/([^/]+)\/([^/.]+?)(?:\.git)?$/i);
+  if (httpsMatch) {
+    return { owner: httpsMatch[1]!, repo: httpsMatch[2]! };
+  }
+
+  // SSH: git@github.com:owner/repo.git
+  const sshMatch = url.match(/github\.com:([^/]+)\/([^/.]+?)(?:\.git)?$/i);
+  if (sshMatch) {
+    return { owner: sshMatch[1]!, repo: sshMatch[2]! };
+  }
+
+  return null;
+}
+
+/**
+ * Parse an Azure DevOps remote URL into org/project/repo.
+ * Supports multiple formats:
+ *   https://dev.azure.com/org/project/_git/repo
+ *   https://org@dev.azure.com/org/project/_git/repo
+ *   git@ssh.dev.azure.com:v3/org/project/repo
+ *   https://org.visualstudio.com/project/_git/repo
+ */
+export function parseAzureDevOpsRemote(url: string): AzureDevOpsRemoteInfo | null {
+  // HTTPS dev.azure.com: https://dev.azure.com/org/project/_git/repo
+  // Also handles: https://org@dev.azure.com/org/project/_git/repo
+  const devAzureHttps = url.match(
+    /dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/.]+?)(?:\.git)?$/i,
+  );
+  if (devAzureHttps) {
+    return { org: devAzureHttps[1]!, project: devAzureHttps[2]!, repo: devAzureHttps[3]! };
+  }
+
+  // SSH dev.azure.com: git@ssh.dev.azure.com:v3/org/project/repo
+  const devAzureSsh = url.match(
+    /ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/.]+?)(?:\.git)?$/i,
+  );
+  if (devAzureSsh) {
+    return { org: devAzureSsh[1]!, project: devAzureSsh[2]!, repo: devAzureSsh[3]! };
+  }
+
+  // Legacy visualstudio.com: https://org.visualstudio.com/project/_git/repo
+  const vsMatch = url.match(
+    /([^/.]+)\.visualstudio\.com\/([^/]+)\/_git\/([^/.]+?)(?:\.git)?$/i,
+  );
+  if (vsMatch) {
+    return { org: vsMatch[1]!, project: vsMatch[2]!, repo: vsMatch[3]! };
+  }
+
+  return null;
+}
+
+/**
+ * Detect platform type from git remote URL string.
+ * Returns 'github' for github.com remotes, 'azure-devops' for ADO remotes.
+ * Defaults to 'github' if unrecognized.
+ */
+export function detectPlatformFromUrl(url: string): PlatformType {
+  if (/github\.com/i.test(url)) return 'github';
+  if (/dev\.azure\.com/i.test(url) || /\.visualstudio\.com/i.test(url) || /ssh\.dev\.azure\.com/i.test(url)) {
+    return 'azure-devops';
+  }
+  return 'github';
+}
+
+/**
+ * Detect platform from a repository root by reading the git remote.
+ * Reads 'origin' remote URL and determines whether it's GitHub or Azure DevOps.
+ * Defaults to 'github' if detection fails.
+ */
+export function detectPlatform(repoRoot: string): PlatformType {
+  try {
+    const remoteUrl = execSync('git remote get-url origin', {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    return detectPlatformFromUrl(remoteUrl);
+  } catch {
+    return 'github';
+  }
+}
+
+/**
+ * Detect work-item source for hybrid setups.
+ * When a squad config specifies `workItems: 'planner'`, work items come from
+ * Planner even though the repo is on GitHub or Azure DevOps.
+ */
+export function detectWorkItemSource(
+  repoRoot: string,
+  configWorkItems?: string,
+): PlatformType {
+  if (configWorkItems === 'planner') return 'planner';
+  return detectPlatform(repoRoot);
+}
+
+/**
+ * Get the origin remote URL for a repo, or null if unavailable.
+ */
+export function getRemoteUrl(repoRoot: string): string | null {
+  try {
+    return execSync('git remote get-url origin', {
+      cwd: repoRoot,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/squad-sdk/src/platform/github.ts b/packages/squad-sdk/src/platform/github.ts
new file mode 100644
index 00000000..8488c4f5
--- /dev/null
+++ b/packages/squad-sdk/src/platform/github.ts
@@ -0,0 +1,191 @@
+/**
+ * GitHub platform adapter — wraps gh CLI for issue/PR/branch operations.
+ *
+ * @module platform/github
+ */
+
+import { execSync } from 'node:child_process';
+import type { PlatformAdapter, PlatformType, WorkItem, PullRequest } from './types.js';
+
+export class GitHubAdapter implements PlatformAdapter {
+  readonly type: PlatformType = 'github';
+
+  constructor(
+    private readonly owner: string,
+    private readonly repo: string,
+  ) {}
+
+  private get repoFlag(): string {
+    return `${this.owner}/${this.repo}`;
+  }
+
+  private exec(cmd: string): string {
+    return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  }
+
+  async listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]> {
+    const args = ['gh', 'issue', 'list', '--repo', this.repoFlag, '--json', 'number,title,state,labels,assignees,url'];
+    if (options.state) args.push('--state', options.state);
+    if (options.limit) args.push('--limit', String(options.limit));
+    if (options.tags?.length) {
+      for (const tag of options.tags) {
+        args.push('--label', tag);
+      }
+    }
+
+    const output = this.exec(args.join(' '));
+    const issues = JSON.parse(output) as Array<{
+      number: number;
+      title: string;
+      state: string;
+      labels: Array<{ name: string }>;
+      assignees: Array<{ login: string }>;
+      url: string;
+    }>;
+
+    return issues.map((issue) => ({
+      id: issue.number,
+      title: issue.title,
+      state: issue.state.toLowerCase(),
+      tags: issue.labels.map((l) => l.name),
+      assignedTo: issue.assignees[0]?.login,
+      url: issue.url,
+    }));
+  }
+
+  async getWorkItem(id: number): Promise<WorkItem> {
+    const output = this.exec(
+      `gh issue view ${id} --repo ${this.repoFlag} --json number,title,state,labels,assignees,url`,
+    );
+    const issue = JSON.parse(output) as {
+      number: number;
+      title: string;
+      state: string;
+      labels: Array<{ name: string }>;
+      assignees: Array<{ login: string }>;
+      url: string;
+    };
+
+    return {
+      id: issue.number,
+      title: issue.title,
+      state: issue.state.toLowerCase(),
+      tags: issue.labels.map((l) => l.name),
+      assignedTo: issue.assignees[0]?.login,
+      url: issue.url,
+    };
+  }
+
+  async addTag(workItemId: number, tag: string): Promise<void> {
+    this.exec(`gh issue edit ${workItemId} --repo ${this.repoFlag} --add-label "${tag}"`);
+  }
+
+  async removeTag(workItemId: number, tag: string): Promise<void> {
+    this.exec(`gh issue edit ${workItemId} --repo ${this.repoFlag} --remove-label "${tag}"`);
+  }
+
+  async addComment(workItemId: number, comment: string): Promise<void> {
+    this.exec(`gh issue comment ${workItemId} --repo ${this.repoFlag} --body "${comment.replace(/"/g, '\\"')}"`);
+  }
+
+  async listPullRequests(options: { status?: string; limit?: number }): Promise<PullRequest[]> {
+    const args = ['gh', 'pr', 'list', '--repo', this.repoFlag, '--json', 'number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author,url'];
+    if (options.status) args.push('--state', options.status);
+    if (options.limit) args.push('--limit', String(options.limit));
+
+    const output = this.exec(args.join(' '));
+    const prs = JSON.parse(output) as Array<{
+      number: number;
+      title: string;
+      headRefName: string;
+      baseRefName: string;
+      state: string;
+      isDraft: boolean;
+      reviewDecision: string;
+      author: { login: string };
+      url: string;
+    }>;
+
+    return prs.map((pr) => ({
+      id: pr.number,
+      title: pr.title,
+      sourceBranch: pr.headRefName,
+      targetBranch: pr.baseRefName,
+      status: mapGitHubPrStatus(pr.state, pr.isDraft),
+      reviewStatus: mapGitHubReviewStatus(pr.reviewDecision),
+      author: pr.author.login,
+      url: pr.url,
+    }));
+  }
+
+  async createPullRequest(options: {
+    title: string;
+    sourceBranch: string;
+    targetBranch: string;
+    description?: string;
+  }): Promise<PullRequest> {
+    const args = [
+      'gh', 'pr', 'create',
+      '--repo', this.repoFlag,
+      '--head', options.sourceBranch,
+      '--base', options.targetBranch,
+      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
+      '--json', 'number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author,url',
+    ];
+    if (options.description) {
+      args.push('--body', `"${options.description.replace(/"/g, '\\"')}"`);
+    }
+
+    const output = this.exec(args.join(' '));
+    const pr = JSON.parse(output) as {
+      number: number;
+      title: string;
+      headRefName: string;
+      baseRefName: string;
+      state: string;
+      isDraft: boolean;
+      reviewDecision: string;
+      author: { login: string };
+      url: string;
+    };
+
+    return {
+      id: pr.number,
+      title: pr.title,
+      sourceBranch: pr.headRefName,
+      targetBranch: pr.baseRefName,
+      status: mapGitHubPrStatus(pr.state, pr.isDraft),
+      reviewStatus: mapGitHubReviewStatus(pr.reviewDecision),
+      author: pr.author.login,
+      url: pr.url,
+    };
+  }
+
+  async mergePullRequest(id: number): Promise<void> {
+    this.exec(`gh pr merge ${id} --repo ${this.repoFlag} --merge`);
+  }
+
+  async createBranch(name: string, fromBranch?: string): Promise<void> {
+    const base = fromBranch ?? 'main';
+    this.exec(`git checkout ${base} && git pull && git checkout -b ${name}`);
+  }
+}
+
+function mapGitHubPrStatus(state: string, isDraft: boolean): PullRequest['status'] {
+  if (isDraft) return 'draft';
+  switch (state.toUpperCase()) {
+    case 'OPEN': return 'active';
+    case 'CLOSED': return 'abandoned';
+    case 'MERGED': return 'completed';
+    default: return 'active';
+  }
+}
+
+function mapGitHubReviewStatus(decision: string): PullRequest['reviewStatus'] {
+  switch (decision?.toUpperCase()) {
+    case 'APPROVED': return 'approved';
+    case 'CHANGES_REQUESTED': return 'changes-requested';
+    case 'REVIEW_REQUIRED': return 'pending';
+    default: return undefined;
+  }
+}
diff --git a/packages/squad-sdk/src/platform/index.ts b/packages/squad-sdk/src/platform/index.ts
new file mode 100644
index 00000000..635e83f6
--- /dev/null
+++ b/packages/squad-sdk/src/platform/index.ts
@@ -0,0 +1,46 @@
+/**
+ * Platform module — factory + barrel exports.
+ *
+ * @module platform
+ */
+
+export type { PlatformType, WorkItem, PullRequest, PlatformAdapter, WorkItemSource, HybridPlatformConfig } from './types.js';
+export type { GitHubRemoteInfo, AzureDevOpsRemoteInfo } from './detect.js';
+export { detectPlatform, detectPlatformFromUrl, detectWorkItemSource, parseGitHubRemote, parseAzureDevOpsRemote, getRemoteUrl } from './detect.js';
+export { GitHubAdapter } from './github.js';
+export { AzureDevOpsAdapter } from './azure-devops.js';
+export { PlannerAdapter, mapPlannerTaskToWorkItem } from './planner.js';
+export { getRalphScanCommands } from './ralph-commands.js';
+export type { RalphCommands } from './ralph-commands.js';
+
+import type { PlatformAdapter } from './types.js';
+import { detectPlatform, getRemoteUrl, parseGitHubRemote, parseAzureDevOpsRemote } from './detect.js';
+import { GitHubAdapter } from './github.js';
+import { AzureDevOpsAdapter } from './azure-devops.js';
+
+/**
+ * Create a platform adapter by auto-detecting the platform from the repo's git remote.
+ * Throws if required remote info cannot be parsed.
+ */
+export function createPlatformAdapter(repoRoot: string): PlatformAdapter {
+  const platform = detectPlatform(repoRoot);
+  const remoteUrl = getRemoteUrl(repoRoot);
+
+  if (!remoteUrl) {
+    throw new Error('No git remote "origin" found. Cannot create platform adapter.');
+  }
+
+  if (platform === 'azure-devops') {
+    const info = parseAzureDevOpsRemote(remoteUrl);
+    if (!info) {
+      throw new Error(`Could not parse Azure DevOps remote URL: ${remoteUrl}`);
+    }
+    return new AzureDevOpsAdapter(info.org, info.project, info.repo);
+  }
+
+  const info = parseGitHubRemote(remoteUrl);
+  if (!info) {
+    throw new Error(`Could not parse GitHub remote URL: ${remoteUrl}`);
+  }
+  return new GitHubAdapter(info.owner, info.repo);
+}
diff --git a/packages/squad-sdk/src/platform/planner.ts b/packages/squad-sdk/src/platform/planner.ts
new file mode 100644
index 00000000..e557b5f6
--- /dev/null
+++ b/packages/squad-sdk/src/platform/planner.ts
@@ -0,0 +1,188 @@
+/**
+ * Microsoft Planner adapter — uses Graph API via az CLI token for task management.
+ * Planner buckets map to squad assignments (squad:untriaged, squad:riker, etc.)
+ *
+ * @module platform/planner
+ */
+
+import { execSync } from 'node:child_process';
+import type { PlatformType, WorkItem } from './types.js';
+
+/** Planner task shape from Graph API */
+interface PlannerTask {
+  id: string;
+  title: string;
+  percentComplete: number;
+  bucketId: string;
+  assignments: Record<string, unknown>;
+}
+
+/** Planner bucket shape from Graph API */
+interface PlannerBucket {
+  id: string;
+  name: string;
+}
+
+/**
+ * Get a Microsoft Graph access token via the az CLI.
+ * Requires: `az login` completed beforehand.
+ */
+function getGraphToken(): string {
+  try {
+    const output = execSync(
+      'az account get-access-token --resource-type ms-graph --query accessToken -o tsv',
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+    ).trim();
+    return output;
+  } catch {
+    throw new Error(
+      'Could not obtain Microsoft Graph token. Ensure you are logged in:\n' +
+      '  az login\n' +
+      '  az account get-access-token --resource-type ms-graph',
+    );
+  }
+}
+
+/**
+ * Map a Planner task + bucket name to a normalized WorkItem.
+ */
+export function mapPlannerTaskToWorkItem(
+  task: PlannerTask,
+  bucketName: string,
+): WorkItem {
+  return {
+    id: hashTaskId(task.id),
+    title: task.title,
+    state: task.percentComplete === 100 ? 'done' : 'active',
+    tags: [bucketName],
+    url: `https://tasks.office.com/task/${task.id}`,
+  };
+}
+
+/**
+ * Convert a Planner string ID to a stable numeric hash.
+ * WorkItem.id is a number, but Planner IDs are strings.
+ */
+function hashTaskId(id: string): number {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = ((hash << 5) - hash + id.charCodeAt(i)) | 0;
+  }
+  return Math.abs(hash);
+}
+
+/**
+ * Planner adapter — partial PlatformAdapter for work-item operations only.
+ * Planner has no concept of PRs or branches, so those methods are not implemented.
+ * Use alongside a repo adapter (GitHub/ADO) in a hybrid config.
+ */
+export class PlannerAdapter {
+  readonly type: PlatformType = 'planner';
+  private bucketCache: PlannerBucket[] | null = null;
+
+  constructor(private readonly planId: string) {}
+
+  private graphFetch(path: string, method = 'GET', body?: string): string {
+    const token = getGraphToken();
+    const curlArgs = [
+      'curl', '-s',
+      '-X', method,
+      '-H', `"Authorization: Bearer ${token}"`,
+      '-H', '"Content-Type: application/json"',
+    ];
+    if (body) {
+      curlArgs.push('-d', `'${body}'`);
+    }
+    curlArgs.push(`"https://graph.microsoft.com/v1.0${path}"`);
+
+    return execSync(curlArgs.join(' '), {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  }
+
+  /** Fetch and cache buckets for this plan */
+  async getBuckets(): Promise<PlannerBucket[]> {
+    if (this.bucketCache) return this.bucketCache;
+
+    const output = this.graphFetch(`/planner/plans/${this.planId}/buckets`);
+    const data = JSON.parse(output) as { value: PlannerBucket[] };
+    this.bucketCache = data.value;
+    return this.bucketCache;
+  }
+
+  /** Resolve a bucket name to its ID */
+  async getBucketId(bucketName: string): Promise<string | undefined> {
+    const buckets = await this.getBuckets();
+    return buckets.find((b) => b.name === bucketName)?.id;
+  }
+
+  /** Resolve a bucket ID to its name */
+  async getBucketName(bucketId: string): Promise<string> {
+    const buckets = await this.getBuckets();
+    return buckets.find((b) => b.id === bucketId)?.name ?? 'unknown';
+  }
+
+  async listWorkItems(options: {
+    tags?: string[];
+    state?: string;
+    limit?: number;
+  }): Promise<WorkItem[]> {
+    const output = this.graphFetch(`/planner/plans/${this.planId}/tasks`);
+    const data = JSON.parse(output) as { value: PlannerTask[] };
+    const buckets = await this.getBuckets();
+    const bucketMap = new Map(buckets.map((b) => [b.id, b.name]));
+
+    let tasks = data.value;
+
+    // Filter by bucket name (tag)
+    if (options.tags?.length) {
+      const targetBucketIds = new Set<string>();
+      for (const tag of options.tags) {
+        const bucket = buckets.find((b) => b.name === tag);
+        if (bucket) targetBucketIds.add(bucket.id);
+      }
+      tasks = tasks.filter((t) => targetBucketIds.has(t.bucketId));
+    }
+
+    // Filter by state
+    if (options.state === 'done') {
+      tasks = tasks.filter((t) => t.percentComplete === 100);
+    } else if (options.state === 'active') {
+      tasks = tasks.filter((t) => t.percentComplete < 100);
+    }
+
+    if (options.limit) {
+      tasks = tasks.slice(0, options.limit);
+    }
+
+    return tasks.map((task) =>
+      mapPlannerTaskToWorkItem(task, bucketMap.get(task.bucketId) ?? 'unknown'),
+    );
+  }
+
+  async addTag(taskId: string, bucketName: string): Promise<void> {
+    const bucketId = await this.getBucketId(bucketName);
+    if (!bucketId) {
+      throw new Error(`Bucket "${bucketName}" not found in plan ${this.planId}`);
+    }
+    // Moving a task to a different bucket = reassigning
+    this.graphFetch(
+      `/planner/tasks/${taskId}`,
+      'PATCH',
+      JSON.stringify({ bucketId }),
+    );
+  }
+
+  async addComment(taskId: string, comment: string): Promise<void> {
+    // Planner task comments go through the group conversation thread
+    this.graphFetch(
+      `/planner/tasks/${taskId}/details`,
+      'PATCH',
+      JSON.stringify({
+        description: comment,
+        previewType: 'description',
+      }),
+    );
+  }
+}
diff --git a/packages/squad-sdk/src/platform/ralph-commands.ts b/packages/squad-sdk/src/platform/ralph-commands.ts
new file mode 100644
index 00000000..efcaf2a3
--- /dev/null
+++ b/packages/squad-sdk/src/platform/ralph-commands.ts
@@ -0,0 +1,93 @@
+/**
+ * Platform-specific Ralph commands for triage and work management.
+ *
+ * @module platform/ralph-commands
+ */
+
+import type { PlatformType } from './types.js';
+
+export interface RalphCommands {
+  listUntriaged: string;
+  listAssigned: string;
+  listOpenPRs: string;
+  listDraftPRs: string;
+  createBranch: string;
+  createPR: string;
+  mergePR: string;
+}
+
+/**
+ * Get Ralph scan/triage commands for a given platform.
+ * GitHub → gh CLI commands
+ * Azure DevOps → az CLI commands
+ */
+export function getRalphScanCommands(platform: PlatformType): RalphCommands {
+  switch (platform) {
+    case 'github':
+      return getGitHubRalphCommands();
+    case 'azure-devops':
+      return getAzureDevOpsRalphCommands();
+    case 'planner':
+      return getPlannerRalphCommands();
+    default:
+      return getGitHubRalphCommands();
+  }
+}
+
+/** Ralph commands for Planner via Graph API (az CLI token) */
+export function getPlannerRalphCommands(): RalphCommands {
+  return {
+    listUntriaged:
+      `curl -s -H "Authorization: Bearer $(az account get-access-token --resource-type ms-graph --query accessToken -o tsv)" "https://graph.microsoft.com/v1.0/planner/plans/{planId}/tasks?$filter=bucketId eq '{untriagedBucketId}'"`,
+    listAssigned:
+      `curl -s -H "Authorization: Bearer $(az account get-access-token --resource-type ms-graph --query accessToken -o tsv)" "https://graph.microsoft.com/v1.0/planner/plans/{planId}/tasks?$filter=bucketId eq '{memberBucketId}'"`,
+    listOpenPRs:
+      'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
+    listDraftPRs:
+      'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
+    createBranch:
+      'git checkout main && git pull && git checkout -b {branchName}',
+    createPR:
+      'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
+    mergePR:
+      'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
+  };
+}
+
+function getGitHubRalphCommands(): RalphCommands {
+  return {
+    listUntriaged:
+      'gh issue list --label "squad:untriaged" --json number,title,labels,assignees --limit 20',
+    listAssigned:
+      'gh issue list --label "squad:{member}" --state open --json number,title,labels,assignees --limit 20',
+    listOpenPRs:
+      'gh pr list --state open --json number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author --limit 20',
+    listDraftPRs:
+      'gh pr list --state open --draft --json number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author --limit 20',
+    createBranch:
+      'git checkout main && git pull && git checkout -b {branchName}',
+    createPR:
+      'gh pr create --title "{title}" --body "{description}" --head {sourceBranch} --base {targetBranch}',
+    mergePR:
+      'gh pr merge {id} --merge',
+  };
+}
+
+function getAzureDevOpsRalphCommands(): RalphCommands {
+  return {
+    listUntriaged:
+      `az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged' ORDER BY [System.CreatedDate] DESC" --output table`,
+    listAssigned:
+      `az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member}' AND [System.State] <> 'Closed' ORDER BY [System.CreatedDate] DESC" --output table`,
+    listOpenPRs:
+      'az repos pr list --status active --output table',
+    listDraftPRs:
+      'az repos pr list --status active --output table | findstr /i "draft"',
+    createBranch:
+      'git checkout main && git pull && git checkout -b {branchName}',
+    createPR:
+      'az repos pr create --title "{title}" --description "{description}" --source-branch {sourceBranch} --target-branch {targetBranch}',
+    mergePR:
+      'az repos pr update --id {id} --status completed',
+  };
+}
diff --git a/packages/squad-sdk/src/platform/types.ts b/packages/squad-sdk/src/platform/types.ts
new file mode 100644
index 00000000..db608279
--- /dev/null
+++ b/packages/squad-sdk/src/platform/types.ts
@@ -0,0 +1,64 @@
+/**
+ * Platform-agnostic interfaces for multi-platform support.
+ * Allows Squad to work with GitHub and Azure DevOps interchangeably.
+ *
+ * @module platform/types
+ */
+
+export type PlatformType = 'github' | 'azure-devops' | 'planner';
+
+/** Where work items are tracked — may differ from where code lives */
+export type WorkItemSource = 'github' | 'azure-devops' | 'planner';
+
+/** Hybrid config: repo on one platform, work items on another */
+export interface HybridPlatformConfig {
+  repo: PlatformType;
+  workItems: WorkItemSource;
+}
+
+/** Normalized work item — maps to GitHub Issues or ADO Work Items */
+export interface WorkItem {
+  id: number;
+  title: string;
+  state: string;
+  tags: string[];
+  assignedTo?: string;
+  url: string;
+}
+
+/** Normalized pull request — maps to GitHub PRs or ADO PRs */
+export interface PullRequest {
+  id: number;
+  title: string;
+  sourceBranch: string;
+  targetBranch: string;
+  status: 'active' | 'completed' | 'abandoned' | 'draft';
+  reviewStatus?: 'approved' | 'changes-requested' | 'pending';
+  author: string;
+  url: string;
+}
+
+/** Platform adapter interface — implemented by GitHub and ADO adapters */
+export interface PlatformAdapter {
+  readonly type: PlatformType;
+
+  // Work Items / Issues
+  listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]>;
+  getWorkItem(id: number): Promise<WorkItem>;
+  addTag(workItemId: number, tag: string): Promise<void>;
+  removeTag(workItemId: number, tag: string): Promise<void>;
+  addComment(workItemId: number, comment: string): Promise<void>;
+
+  // Pull Requests
+  listPullRequests(options: { status?: string; limit?: number }): Promise<PullRequest[]>;
+  createPullRequest(options: {
+    title: string;
+    sourceBranch: string;
+    targetBranch: string;
+    description?: string;
+  }): Promise<PullRequest>;
+  mergePullRequest(id: number): Promise<void>;
+
+  // Branches
+  createBranch(name: string, fromBranch?: string): Promise<void>;
+}
diff --git a/packages/squad-sdk/src/types.ts b/packages/squad-sdk/src/types.ts
index 0563d751..1e623e01 100644
--- a/packages/squad-sdk/src/types.ts
+++ b/packages/squad-sdk/src/types.ts
@@ -57,3 +57,12 @@ export type { SquadCustomAgentConfig } from './adapter/types.js';
 export type { SquadEntry } from './multi-squad.js';
 export type { MultiSquadConfig } from './multi-squad.js';
 export type { SquadInfo } from './multi-squad.js';
+
+// --- Platform types (platform/types.ts) ---
+export type { PlatformType } from './platform/types.js';
+export type { WorkItem } from './platform/types.js';
+export type { PullRequest } from './platform/types.js';
+export type { PlatformAdapter } from './platform/types.js';
+export type { RalphCommands } from './platform/ralph-commands.js';
+export type { GitHubRemoteInfo } from './platform/detect.js';
+export type { AzureDevOpsRemoteInfo } from './platform/detect.js';
diff --git a/templates/squad.agent.md b/templates/squad.agent.md
index 1af35a5a..585af2d5 100644
--- a/templates/squad.agent.md
+++ b/templates/squad.agent.md
@@ -945,6 +945,61 @@ Before connecting to a GitHub repository, verify that the `gh` CLI is available
 
 ---
 
+## Platform Detection
+
+On session start, detect the platform from git remote:
+- `github.com` → Use GitHub commands (`gh` CLI)
+- `dev.azure.com` or `*.visualstudio.com` → Use Azure DevOps commands (`az` CLI)
+
+If `squad.config.ts` specifies `workItems: 'planner'`, use Microsoft Planner for work items regardless of where the repo lives.
+
+### Azure DevOps Mode
+
+If the git remote points to Azure DevOps:
+
+| GitHub concept | Azure DevOps equivalent | Command change |
+|---|---|---|
+| `gh issue list` | WIQL query via `az boards query` | `az boards query --wiql "SELECT ... FROM WorkItems WHERE ..."` |
+| `gh pr list` | `az repos pr list` | `az repos pr list --status active` |
+| `gh pr create` | `az repos pr create` | `az repos pr create --source-branch ... --target-branch ...` |
+| `gh pr merge` | `az repos pr update --status completed` | Set PR status to completed |
+| Issue labels | Work Item tags | `az boards work-item update --fields "System.Tags=..."` |
+| `squad:{member}` label | `squad:{member}` tag on work items | Tags use `;` separator |
+
+**Prerequisites for Azure DevOps:**
+1. Run `az --version`. If missing: *"Azure DevOps mode requires the Azure CLI. Install from https://aka.ms/install-az-cli"*
+2. Run `az extension show --name azure-devops`. If missing: *"Run `az extension add --name azure-devops`"*
+3. Run `az account show`. If not logged in: *"Run `az login` to authenticate"*
+4. Verify defaults: `az devops configure --list` — org and project must be set
+
+**Ralph on Azure DevOps:**
+- Replace `gh issue list --label "squad:untriaged"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:untriaged'"`
+- Replace `gh issue list --label "squad:{member}"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:{member}'"`
+- Replace `gh pr list` with `az repos pr list`
+- Branch naming stays the same: `squad/{issue-number}-{slug}`
+
+### Microsoft Planner Mode (Hybrid)
+
+If work items are in Microsoft Planner (configured via `squad.config.ts` with `workItems: 'planner'`):
+- Ralph scans Planner tasks via Microsoft Graph API
+- Buckets map to squad member assignments (squad:riker, squad:data, etc.)
+- The "squad:untriaged" bucket = triage inbox
+- Moving a task between buckets = assigning to a team member
+- Task completion = move to "Done" bucket
+- PRs and branches still use the repo adapter (GitHub or Azure DevOps)
+
+**Prerequisites for Planner:**
+1. Run `az login` to authenticate
+2. Ensure `az account get-access-token --resource-type ms-graph` succeeds
+3. Set `workItems: 'planner'` and `planId` in `squad.config.ts`
+
+**Ralph on Planner:**
+- Scan untriaged: Graph API `GET /planner/plans/{planId}/tasks` filtered by `squad:untriaged` bucket
+- Assign to member: `PATCH /planner/tasks/{taskId}` → move to `squad:{member}` bucket
+- PRs: Use the repo adapter commands (GitHub or Azure DevOps)
+
+---
+
 ## Ralph — Work Monitor
 
 Ralph is a built-in squad member whose job is keeping tabs on work. **Ralph tracks and drives the work queue.** Always on the roster, one job: make sure the team never sits idle.
diff --git a/test/cli/consult.test.ts b/test/cli/consult.test.ts
index e51df5fe..0afcbaf1 100644
--- a/test/cli/consult.test.ts
+++ b/test/cli/consult.test.ts
@@ -157,7 +157,7 @@ describe('CLI: squad consult', () => {
   });
 
   describe('error handling', () => {
-    it('fails outside a git repository', () => {
+    it('fails outside a git repository', { timeout: 30_000 }, () => {
       // Create a non-git directory
       const nonGitDir = join(TEST_ROOT, 'non-git');
       mkdirSync(nonGitDir, { recursive: true });
@@ -168,7 +168,7 @@ describe('CLI: squad consult', () => {
       expect(result.stderr).toBeTruthy();
     });
 
-    it('requires personal squad to exist', () => {
+    it('requires personal squad to exist', { timeout: 30_000 }, () => {
       // Override XDG_CONFIG_HOME to point to a non-existent path
       // This ensures the SDK won't find a personal squad
       const result = runSquad('consult', TEST_ROOT, {
diff --git a/test/cli/init.test.ts b/test/cli/init.test.ts
index 0487d6f5..faf75e0e 100644
--- a/test/cli/init.test.ts
+++ b/test/cli/init.test.ts
@@ -91,7 +91,7 @@ describe('CLI: init command', () => {
     expect(existsSync(gitattributesPath)).toBe(true);
     
     const content = await readFile(gitattributesPath, 'utf-8');
-    expect(content).toContain('.squad/decisions/decisions.md merge=union');
+    expect(content).toContain('.squad/decisions.md merge=union');
     expect(content).toContain('.squad/orchestration-log/** merge=union');
   });
 
diff --git a/test/platform-adapter.test.ts b/test/platform-adapter.test.ts
new file mode 100644
index 00000000..61fd86b9
--- /dev/null
+++ b/test/platform-adapter.test.ts
@@ -0,0 +1,572 @@
+/**
+ * Platform adapter tests — detection, parsing, commands, and type mapping.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  detectPlatformFromUrl,
+  parseGitHubRemote,
+  parseAzureDevOpsRemote,
+} from '../packages/squad-sdk/src/platform/detect.js';
+import { detectWorkItemSource } from '../packages/squad-sdk/src/platform/detect.js';
+import { getRalphScanCommands } from '../packages/squad-sdk/src/platform/ralph-commands.js';
+import { mapPlannerTaskToWorkItem } from '../packages/squad-sdk/src/platform/planner.js';
+import type { PlatformType, WorkItem, PullRequest, WorkItemSource, HybridPlatformConfig } from '../packages/squad-sdk/src/platform/types.js';
+
+// ─── Platform Detection from URL ───────────────────────────────────────
+
+describe('detectPlatformFromUrl', () => {
+  it('detects github.com HTTPS remote', () => {
+    expect(detectPlatformFromUrl('https://github.com/owner/repo.git')).toBe('github');
+  });
+
+  it('detects github.com SSH remote', () => {
+    expect(detectPlatformFromUrl('git@github.com:owner/repo.git')).toBe('github');
+  });
+
+  it('detects github.com HTTPS without .git', () => {
+    expect(detectPlatformFromUrl('https://github.com/owner/repo')).toBe('github');
+  });
+
+  it('detects dev.azure.com HTTPS remote', () => {
+    expect(detectPlatformFromUrl('https://dev.azure.com/myorg/myproject/_git/myrepo')).toBe('azure-devops');
+  });
+
+  it('detects dev.azure.com with user prefix', () => {
+    expect(detectPlatformFromUrl('https://myorg@dev.azure.com/myorg/myproject/_git/myrepo')).toBe('azure-devops');
+  });
+
+  it('detects SSH dev.azure.com remote', () => {
+    expect(detectPlatformFromUrl('git@ssh.dev.azure.com:v3/myorg/myproject/myrepo')).toBe('azure-devops');
+  });
+
+  it('detects visualstudio.com remote', () => {
+    expect(detectPlatformFromUrl('https://myorg.visualstudio.com/myproject/_git/myrepo')).toBe('azure-devops');
+  });
+
+  it('defaults to github for unknown remotes', () => {
+    expect(detectPlatformFromUrl('https://gitlab.com/owner/repo.git')).toBe('github');
+  });
+
+  it('defaults to github for empty string', () => {
+    expect(detectPlatformFromUrl('')).toBe('github');
+  });
+
+  it('defaults to github for random string', () => {
+    expect(detectPlatformFromUrl('not-a-url')).toBe('github');
+  });
+});
+
+// ─── GitHub Remote Parsing ─────────────────────────────────────────────
+
+describe('parseGitHubRemote', () => {
+  it('parses HTTPS URL with .git suffix', () => {
+    const result = parseGitHubRemote('https://github.com/bradygaster/squad.git');
+    expect(result).toEqual({ owner: 'bradygaster', repo: 'squad' });
+  });
+
+  it('parses HTTPS URL without .git suffix', () => {
+    const result = parseGitHubRemote('https://github.com/microsoft/vscode');
+    expect(result).toEqual({ owner: 'microsoft', repo: 'vscode' });
+  });
+
+  it('parses SSH URL', () => {
+    const result = parseGitHubRemote('git@github.com:facebook/react.git');
+    expect(result).toEqual({ owner: 'facebook', repo: 'react' });
+  });
+
+  it('parses SSH URL without .git suffix', () => {
+    const result = parseGitHubRemote('git@github.com:owner/repo');
+    expect(result).toEqual({ owner: 'owner', repo: 'repo' });
+  });
+
+  it('returns null for non-GitHub URLs', () => {
+    expect(parseGitHubRemote('https://dev.azure.com/org/project/_git/repo')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(parseGitHubRemote('')).toBeNull();
+  });
+
+  it('returns null for gitlab URL', () => {
+    expect(parseGitHubRemote('https://gitlab.com/owner/repo.git')).toBeNull();
+  });
+
+  it('handles URL with trailing slash gracefully', () => {
+    // trailing slash is not standard git remote but shouldn't crash
+    expect(parseGitHubRemote('https://github.com/owner/')).toBeNull();
+  });
+});
+
+// ─── Azure DevOps Remote Parsing ───────────────────────────────────────
+
+describe('parseAzureDevOpsRemote', () => {
+  it('parses HTTPS dev.azure.com URL', () => {
+    const result = parseAzureDevOpsRemote('https://dev.azure.com/myorg/myproject/_git/myrepo');
+    expect(result).toEqual({ org: 'myorg', project: 'myproject', repo: 'myrepo' });
+  });
+
+  it('parses HTTPS dev.azure.com URL with .git suffix', () => {
+    const result = parseAzureDevOpsRemote('https://dev.azure.com/myorg/myproject/_git/myrepo.git');
+    expect(result).toEqual({ org: 'myorg', project: 'myproject', repo: 'myrepo' });
+  });
+
+  it('parses URL with user prefix', () => {
+    const result = parseAzureDevOpsRemote('https://myorg@dev.azure.com/myorg/MyProject/_git/my-repo');
+    expect(result).toEqual({ org: 'myorg', project: 'MyProject', repo: 'my-repo' });
+  });
+
+  it('parses SSH dev.azure.com URL', () => {
+    const result = parseAzureDevOpsRemote('git@ssh.dev.azure.com:v3/myorg/myproject/myrepo');
+    expect(result).toEqual({ org: 'myorg', project: 'myproject', repo: 'myrepo' });
+  });
+
+  it('parses SSH dev.azure.com URL with .git suffix', () => {
+    const result = parseAzureDevOpsRemote('git@ssh.dev.azure.com:v3/myorg/myproject/myrepo.git');
+    expect(result).toEqual({ org: 'myorg', project: 'myproject', repo: 'myrepo' });
+  });
+
+  it('parses legacy visualstudio.com URL', () => {
+    const result = parseAzureDevOpsRemote('https://contoso.visualstudio.com/WebApp/_git/frontend');
+    expect(result).toEqual({ org: 'contoso', project: 'WebApp', repo: 'frontend' });
+  });
+
+  it('parses legacy visualstudio.com URL with .git suffix', () => {
+    const result = parseAzureDevOpsRemote('https://contoso.visualstudio.com/WebApp/_git/frontend.git');
+    expect(result).toEqual({ org: 'contoso', project: 'WebApp', repo: 'frontend' });
+  });
+
+  it('returns null for GitHub URLs', () => {
+    expect(parseAzureDevOpsRemote('https://github.com/owner/repo.git')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(parseAzureDevOpsRemote('')).toBeNull();
+  });
+
+  it('returns null for gitlab URLs', () => {
+    expect(parseAzureDevOpsRemote('https://gitlab.com/group/repo.git')).toBeNull();
+  });
+
+  it('handles URL with special characters in project name', () => {
+    const result = parseAzureDevOpsRemote('https://dev.azure.com/org/My-Project/_git/my-repo');
+    expect(result).toEqual({ org: 'org', project: 'My-Project', repo: 'my-repo' });
+  });
+});
+
+// ─── WorkItem Type Shape ───────────────────────────────────────────────
+
+describe('WorkItem type', () => {
+  it('has all required fields', () => {
+    const wi: WorkItem = {
+      id: 42,
+      title: 'Fix login bug',
+      state: 'active',
+      tags: ['squad:alice', 'bug'],
+      assignedTo: 'Alice',
+      url: 'https://example.com/work-items/42',
+    };
+    expect(wi.id).toBe(42);
+    expect(wi.title).toBe('Fix login bug');
+    expect(wi.state).toBe('active');
+    expect(wi.tags).toEqual(['squad:alice', 'bug']);
+    expect(wi.assignedTo).toBe('Alice');
+    expect(wi.url).toContain('42');
+  });
+
+  it('allows optional assignedTo', () => {
+    const wi: WorkItem = {
+      id: 1,
+      title: 'Unassigned item',
+      state: 'new',
+      tags: [],
+      url: 'https://example.com/1',
+    };
+    expect(wi.assignedTo).toBeUndefined();
+  });
+
+  it('allows empty tags', () => {
+    const wi: WorkItem = {
+      id: 1,
+      title: 'No tags',
+      state: 'new',
+      tags: [],
+      url: 'https://example.com/1',
+    };
+    expect(wi.tags).toEqual([]);
+  });
+});
+
+// ─── PullRequest Type Shape ────────────────────────────────────────────
+
+describe('PullRequest type', () => {
+  it('has all required fields', () => {
+    const pr: PullRequest = {
+      id: 99,
+      title: 'Add feature X',
+      sourceBranch: 'feature/x',
+      targetBranch: 'main',
+      status: 'active',
+      reviewStatus: 'pending',
+      author: 'bob',
+      url: 'https://example.com/pr/99',
+    };
+    expect(pr.id).toBe(99);
+    expect(pr.status).toBe('active');
+    expect(pr.reviewStatus).toBe('pending');
+  });
+
+  it('accepts all valid status values', () => {
+    const statuses: PullRequest['status'][] = ['active', 'completed', 'abandoned', 'draft'];
+    for (const status of statuses) {
+      const pr: PullRequest = {
+        id: 1,
+        title: 'PR',
+        sourceBranch: 'a',
+        targetBranch: 'b',
+        status,
+        author: 'x',
+        url: 'u',
+      };
+      expect(pr.status).toBe(status);
+    }
+  });
+
+  it('allows optional reviewStatus', () => {
+    const pr: PullRequest = {
+      id: 1,
+      title: 'PR',
+      sourceBranch: 'a',
+      targetBranch: 'b',
+      status: 'active',
+      author: 'x',
+      url: 'u',
+    };
+    expect(pr.reviewStatus).toBeUndefined();
+  });
+});
+
+// ─── Ralph Commands ────────────────────────────────────────────────────
+
+describe('getRalphScanCommands', () => {
+  describe('github', () => {
+    const cmds = getRalphScanCommands('github');
+
+    it('returns gh issue list for untriaged', () => {
+      expect(cmds.listUntriaged).toContain('gh issue list');
+      expect(cmds.listUntriaged).toContain('squad:untriaged');
+    });
+
+    it('returns gh issue list for assigned', () => {
+      expect(cmds.listAssigned).toContain('gh issue list');
+      expect(cmds.listAssigned).toContain('squad:{member}');
+    });
+
+    it('returns gh pr list for open PRs', () => {
+      expect(cmds.listOpenPRs).toContain('gh pr list');
+    });
+
+    it('returns gh pr list for draft PRs', () => {
+      expect(cmds.listDraftPRs).toContain('gh pr list');
+      expect(cmds.listDraftPRs).toContain('draft');
+    });
+
+    it('returns gh pr create for createPR', () => {
+      expect(cmds.createPR).toContain('gh pr create');
+    });
+
+    it('returns gh pr merge for mergePR', () => {
+      expect(cmds.mergePR).toContain('gh pr merge');
+    });
+
+    it('returns git checkout for createBranch', () => {
+      expect(cmds.createBranch).toContain('git checkout');
+    });
+  });
+
+  describe('azure-devops', () => {
+    const cmds = getRalphScanCommands('azure-devops');
+
+    it('returns az boards query for untriaged', () => {
+      expect(cmds.listUntriaged).toContain('az boards query');
+      expect(cmds.listUntriaged).toContain('squad:untriaged');
+    });
+
+    it('returns az boards query for assigned', () => {
+      expect(cmds.listAssigned).toContain('az boards query');
+      expect(cmds.listAssigned).toContain('squad:{member}');
+    });
+
+    it('returns az repos pr list for open PRs', () => {
+      expect(cmds.listOpenPRs).toContain('az repos pr list');
+    });
+
+    it('returns az repos pr list for draft PRs', () => {
+      expect(cmds.listDraftPRs).toContain('az repos pr list');
+    });
+
+    it('returns az repos pr create for createPR', () => {
+      expect(cmds.createPR).toContain('az repos pr create');
+    });
+
+    it('returns az repos pr update for mergePR', () => {
+      expect(cmds.mergePR).toContain('az repos pr update');
+      expect(cmds.mergePR).toContain('completed');
+    });
+
+    it('returns git checkout for createBranch', () => {
+      expect(cmds.createBranch).toContain('git checkout');
+    });
+  });
+
+  it('defaults to github commands for unknown platform', () => {
+    // Cast to bypass type checking for edge case test
+    const cmds = getRalphScanCommands('unknown' as PlatformType);
+    expect(cmds.listUntriaged).toContain('gh issue list');
+  });
+});
+
+// ─── PlatformType Values ───────────────────────────────────────────────
+
+describe('PlatformType', () => {
+  it('github is a valid PlatformType', () => {
+    const t: PlatformType = 'github';
+    expect(t).toBe('github');
+  });
+
+  it('azure-devops is a valid PlatformType', () => {
+    const t: PlatformType = 'azure-devops';
+    expect(t).toBe('azure-devops');
+  });
+});
+
+// ─── Edge Cases ────────────────────────────────────────────────────────
+
+describe('edge cases', () => {
+  it('parseGitHubRemote handles case-insensitive github.com', () => {
+    const result = parseGitHubRemote('https://GitHub.COM/Owner/Repo.git');
+    expect(result).toEqual({ owner: 'Owner', repo: 'Repo' });
+  });
+
+  it('parseAzureDevOpsRemote handles case-insensitive dev.azure.com', () => {
+    const result = parseAzureDevOpsRemote('https://DEV.AZURE.COM/org/proj/_git/repo');
+    expect(result).toEqual({ org: 'org', project: 'proj', repo: 'repo' });
+  });
+
+  it('parseAzureDevOpsRemote handles case-insensitive visualstudio.com', () => {
+    const result = parseAzureDevOpsRemote('https://myorg.VISUALSTUDIO.COM/proj/_git/repo');
+    expect(result).toEqual({ org: 'myorg', project: 'proj', repo: 'repo' });
+  });
+
+  it('detectPlatformFromUrl handles mixed case', () => {
+    expect(detectPlatformFromUrl('https://DEV.AZURE.COM/org/proj/_git/repo')).toBe('azure-devops');
+    expect(detectPlatformFromUrl('https://GITHUB.COM/owner/repo')).toBe('github');
+  });
+
+  it('all Ralph commands have placeholder tokens for both platforms', () => {
+    const ghCmds = getRalphScanCommands('github');
+    const adoCmds = getRalphScanCommands('azure-devops');
+
+    // createBranch should have {branchName}
+    expect(ghCmds.createBranch).toContain('{branchName}');
+    expect(adoCmds.createBranch).toContain('{branchName}');
+
+    // createPR should have {title}, {sourceBranch}, {targetBranch}
+    expect(ghCmds.createPR).toContain('{title}');
+    expect(adoCmds.createPR).toContain('{title}');
+
+    // mergePR should have {id}
+    expect(ghCmds.mergePR).toContain('{id}');
+    expect(adoCmds.mergePR).toContain('{id}');
+  });
+});
+
+// ─── Planner Adapter ──────────────────────────────────────────────────
+
+describe('PlannerAdapter', () => {
+  it('planner is a valid PlatformType', () => {
+    const t: PlatformType = 'planner';
+    expect(t).toBe('planner');
+  });
+
+  it('PlannerAdapter can be constructed with a plan ID', async () => {
+    // Import the class to verify construction (no Graph calls)
+    const { PlannerAdapter } = await import('../packages/squad-sdk/src/platform/planner.js');
+    const adapter = new PlannerAdapter('rYe_WFgqUUqnSTZfpMdKcZUAER1P');
+    expect(adapter.type).toBe('planner');
+  });
+});
+
+// ─── Planner WorkItem Mapping ─────────────────────────────────────────
+
+describe('mapPlannerTaskToWorkItem', () => {
+  it('maps an active Planner task to WorkItem', () => {
+    const task = {
+      id: 'abc123',
+      title: 'Implement login page',
+      percentComplete: 50,
+      bucketId: 'bucket-1',
+      assignments: {},
+    };
+    const wi = mapPlannerTaskToWorkItem(task, 'squad:untriaged');
+    expect(wi.title).toBe('Implement login page');
+    expect(wi.state).toBe('active');
+    expect(wi.tags).toEqual(['squad:untriaged']);
+    expect(wi.url).toContain('abc123');
+  });
+
+  it('maps a completed Planner task (100%) to done state', () => {
+    const task = {
+      id: 'done-task',
+      title: 'Done task',
+      percentComplete: 100,
+      bucketId: 'bucket-done',
+      assignments: {},
+    };
+    const wi = mapPlannerTaskToWorkItem(task, 'Done');
+    expect(wi.state).toBe('done');
+  });
+
+  it('maps bucket name as tag', () => {
+    const task = {
+      id: 'x',
+      title: 'Test',
+      percentComplete: 0,
+      bucketId: 'b1',
+      assignments: {},
+    };
+    const wi = mapPlannerTaskToWorkItem(task, 'squad:riker');
+    expect(wi.tags).toEqual(['squad:riker']);
+  });
+
+  it('generates a numeric id from string task id', () => {
+    const task = {
+      id: 'planner-string-id',
+      title: 'Test',
+      percentComplete: 0,
+      bucketId: 'b',
+      assignments: {},
+    };
+    const wi = mapPlannerTaskToWorkItem(task, 'squad:untriaged');
+    expect(typeof wi.id).toBe('number');
+    expect(wi.id).toBeGreaterThanOrEqual(0);
+  });
+
+  it('produces consistent numeric id for the same string', () => {
+    const task1 = { id: 'same-id', title: 'A', percentComplete: 0, bucketId: 'b', assignments: {} };
+    const task2 = { id: 'same-id', title: 'B', percentComplete: 0, bucketId: 'b', assignments: {} };
+    const wi1 = mapPlannerTaskToWorkItem(task1, 'x');
+    const wi2 = mapPlannerTaskToWorkItem(task2, 'x');
+    expect(wi1.id).toBe(wi2.id);
+  });
+});
+
+// ─── Bucket-to-Tag Mapping ────────────────────────────────────────────
+
+describe('Planner bucket-to-tag mapping', () => {
+  it('squad:untriaged bucket maps to untriaged tag', () => {
+    const task = { id: 't1', title: 'New', percentComplete: 0, bucketId: 'b-untriaged', assignments: {} };
+    const wi = mapPlannerTaskToWorkItem(task, 'squad:untriaged');
+    expect(wi.tags).toContain('squad:untriaged');
+  });
+
+  it('squad:member bucket maps to member assignment tag', () => {
+    const task = { id: 't2', title: 'Assigned', percentComplete: 0, bucketId: 'b-riker', assignments: {} };
+    const wi = mapPlannerTaskToWorkItem(task, 'squad:riker');
+    expect(wi.tags).toContain('squad:riker');
+  });
+
+  it('Done bucket maps correctly', () => {
+    const task = { id: 't3', title: 'Finished', percentComplete: 100, bucketId: 'b-done', assignments: {} };
+    const wi = mapPlannerTaskToWorkItem(task, 'Done');
+    expect(wi.tags).toContain('Done');
+    expect(wi.state).toBe('done');
+  });
+});
+
+// ─── HybridPlatformConfig ─────────────────────────────────────────────
+
+describe('HybridPlatformConfig', () => {
+  it('allows repo=azure-devops with workItems=planner', () => {
+    const config: HybridPlatformConfig = {
+      repo: 'azure-devops',
+      workItems: 'planner',
+    };
+    expect(config.repo).toBe('azure-devops');
+    expect(config.workItems).toBe('planner');
+  });
+
+  it('allows repo=github with workItems=github (standard)', () => {
+    const config: HybridPlatformConfig = {
+      repo: 'github',
+      workItems: 'github',
+    };
+    expect(config.repo).toBe('github');
+    expect(config.workItems).toBe('github');
+  });
+
+  it('allows repo=github with workItems=planner', () => {
+    const config: HybridPlatformConfig = {
+      repo: 'github',
+      workItems: 'planner',
+    };
+    expect(config.repo).toBe('github');
+    expect(config.workItems).toBe('planner');
+  });
+});
+
+// ─── WorkItemSource Type ──────────────────────────────────────────────
+
+describe('WorkItemSource', () => {
+  it('accepts github as a valid source', () => {
+    const s: WorkItemSource = 'github';
+    expect(s).toBe('github');
+  });
+
+  it('accepts azure-devops as a valid source', () => {
+    const s: WorkItemSource = 'azure-devops';
+    expect(s).toBe('azure-devops');
+  });
+
+  it('accepts planner as a valid source', () => {
+    const s: WorkItemSource = 'planner';
+    expect(s).toBe('planner');
+  });
+});
+
+// ─── Ralph Planner Commands ───────────────────────────────────────────
+
+describe('getRalphScanCommands planner', () => {
+  const cmds = getRalphScanCommands('planner');
+
+  it('returns Graph API curl for untriaged', () => {
+    expect(cmds.listUntriaged).toContain('graph.microsoft.com');
+    expect(cmds.listUntriaged).toContain('planner/plans');
+  });
+
+  it('returns Graph API curl for assigned', () => {
+    expect(cmds.listAssigned).toContain('graph.microsoft.com');
+    expect(cmds.listAssigned).toContain('{memberBucketId}');
+  });
+
+  it('indicates PRs are not managed for open PRs', () => {
+    expect(cmds.listOpenPRs).toContain('does not manage PRs');
+  });
+
+  it('indicates PRs are not managed for draft PRs', () => {
+    expect(cmds.listDraftPRs).toContain('does not manage PRs');
+  });
+
+  it('returns git checkout for createBranch', () => {
+    expect(cmds.createBranch).toContain('git checkout');
+    expect(cmds.createBranch).toContain('{branchName}');
+  });
+
+  it('indicates PRs are not managed for createPR', () => {
+    expect(cmds.createPR).toContain('does not manage PRs');
+  });
+
+  it('indicates PRs are not managed for mergePR', () => {
+    expect(cmds.mergePR).toContain('does not manage PRs');
+  });
+});

From 5b782884fabfe46db96921136a9682adba21b7d7 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 08:49:06 +0200
Subject: [PATCH 02/15] chore: remove .squad runtime files from tracking

Remove .squad/.first-run and .squad/config.json that trigger branch guard.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .gitignore         | 3 +++
 .squad/.first-run  | 1 -
 .squad/config.json | 4 ----
 3 files changed, 3 insertions(+), 5 deletions(-)
 delete mode 100644 .squad/.first-run
 delete mode 100644 .squad/config.json

diff --git a/.gitignore b/.gitignore
index 862a7cfa..ed5657a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,3 +11,6 @@ coverage/
 .test-cli-*
 # Docs site generated files
 docs/dist/
+
+.squad/.first-run
+.squad/config.json
diff --git a/.squad/.first-run b/.squad/.first-run
deleted file mode 100644
index fabbbc86..00000000
--- a/.squad/.first-run
+++ /dev/null
@@ -1 +0,0 @@
-2026-03-04T23:08:20.566Z
diff --git a/.squad/config.json b/.squad/config.json
deleted file mode 100644
index 4bbe45a9..00000000
--- a/.squad/config.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "version": 1,
-  "teamRoot": "C:\\temp\\squad-streams"
-}
\ No newline at end of file

From 88ffb166917bb6b5151a97ee3870722394730173 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 09:52:44 +0200
Subject: [PATCH 03/15] feat: add createWorkItem to PlatformAdapter interface

Add createWorkItem method to PlatformAdapter interface and all adapters:
- GitHubAdapter: creates issues via gh issue create
- AzureDevOpsAdapter: creates work items via az boards work-item create
- PlannerAdapter: creates tasks via Graph API POST /planner/tasks
- RalphCommands: add createWorkItem command for all platforms

6 new tests (86 total for platform adapter).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 package.json                                  |   2 +-
 packages/squad-cli/package.json               |   2 +-
 packages/squad-sdk/package.json               |   2 +-
 .../squad-sdk/src/platform/azure-devops.ts    |  39 ++++++
 packages/squad-sdk/src/platform/github.ts     |  39 ++++++
 packages/squad-sdk/src/platform/planner.ts    |  41 +++++++
 .../squad-sdk/src/platform/ralph-commands.ts  |   7 ++
 packages/squad-sdk/src/platform/types.ts      |   1 +
 test/platform-adapter.test.ts                 | 111 +++++++++++++++++-
 9 files changed, 240 insertions(+), 4 deletions(-)

diff --git a/package.json b/package.json
index 3555689f..079f95f5 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad",
-  "version": "0.8.21-preview.4",
+  "version": "0.8.21-preview.7",
   "private": true,
   "description": "Squad — Programmable multi-agent runtime for GitHub Copilot, built on @github/copilot-sdk",
   "type": "module",
diff --git a/packages/squad-cli/package.json b/packages/squad-cli/package.json
index df55c88a..369ce450 100644
--- a/packages/squad-cli/package.json
+++ b/packages/squad-cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-cli",
-  "version": "0.8.21-preview.4",
+  "version": "0.8.21-preview.7",
   "description": "Squad CLI — Command-line interface for the Squad multi-agent runtime",
   "type": "module",
   "bin": {
diff --git a/packages/squad-sdk/package.json b/packages/squad-sdk/package.json
index 65a2d5ed..9479243c 100644
--- a/packages/squad-sdk/package.json
+++ b/packages/squad-sdk/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-sdk",
-  "version": "0.8.21-preview.4",
+  "version": "0.8.21-preview.7",
   "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/squad-sdk/src/platform/azure-devops.ts b/packages/squad-sdk/src/platform/azure-devops.ts
index 087ffecd..a773b0b3 100644
--- a/packages/squad-sdk/src/platform/azure-devops.ts
+++ b/packages/squad-sdk/src/platform/azure-devops.ts
@@ -102,6 +102,45 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     };
   }
 
+  async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem> {
+    const wiType = options.type ?? 'User Story';
+    const fields: string[] = [
+      `"System.Title=${options.title.replace(/"/g, '\\"')}"`,
+    ];
+    if (options.description) {
+      fields.push(`"System.Description=${options.description.replace(/"/g, '\\"')}"`);
+    }
+    if (options.tags?.length) {
+      fields.push(`"System.Tags=${options.tags.join('; ')}"`);
+    }
+    if (options.assignedTo) {
+      fields.push(`"System.AssignedTo=${options.assignedTo}"`);
+    }
+
+    const output = this.exec(
+      `az boards work-item create --type "${wiType}" --fields ${fields.join(' ')} ${this.defaults} --output json`,
+    );
+    const created = JSON.parse(output) as {
+      id: number;
+      fields: Record<string, unknown>;
+      url: string;
+      _links?: { html?: { href?: string } };
+    };
+
+    const createdFields = created.fields;
+    const tags = typeof createdFields['System.Tags'] === 'string'
+      ? (createdFields['System.Tags'] as string).split(';').map((t) => t.trim()).filter(Boolean)
+      : [];
+
+    return {
+      id: created.id,
+      title: (createdFields['System.Title'] as string) ?? '',
+      state: (createdFields['System.State'] as string) ?? '',
+      tags,
+      url: created._links?.html?.href ?? created.url,
+    };
+  }
+
   async addTag(workItemId: number, tag: string): Promise<void> {
     // Get current tags, append the new one
     const wi = await this.getWorkItem(workItemId);
diff --git a/packages/squad-sdk/src/platform/github.ts b/packages/squad-sdk/src/platform/github.ts
index 8488c4f5..43d9a0e0 100644
--- a/packages/squad-sdk/src/platform/github.ts
+++ b/packages/squad-sdk/src/platform/github.ts
@@ -76,6 +76,45 @@ export class GitHubAdapter implements PlatformAdapter {
     };
   }
 
+  async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem> {
+    const args = [
+      'gh', 'issue', 'create',
+      '--repo', this.repoFlag,
+      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
+      '--json', 'number,title,state,labels,assignees,url',
+    ];
+    if (options.description) {
+      args.push('--body', `"${options.description.replace(/"/g, '\\"')}"`);
+    }
+    if (options.tags?.length) {
+      for (const tag of options.tags) {
+        args.push('--label', `"${tag}"`);
+      }
+    }
+    if (options.assignedTo) {
+      args.push('--assignee', options.assignedTo);
+    }
+
+    const output = this.exec(args.join(' '));
+    const issue = JSON.parse(output) as {
+      number: number;
+      title: string;
+      state: string;
+      labels: Array<{ name: string }>;
+      assignees: Array<{ login: string }>;
+      url: string;
+    };
+
+    return {
+      id: issue.number,
+      title: issue.title,
+      state: issue.state.toLowerCase(),
+      tags: issue.labels.map((l) => l.name),
+      assignedTo: issue.assignees[0]?.login,
+      url: issue.url,
+    };
+  }
+
   async addTag(workItemId: number, tag: string): Promise<void> {
     this.exec(`gh issue edit ${workItemId} --repo ${this.repoFlag} --add-label "${tag}"`);
   }
diff --git a/packages/squad-sdk/src/platform/planner.ts b/packages/squad-sdk/src/platform/planner.ts
index e557b5f6..e07a82ee 100644
--- a/packages/squad-sdk/src/platform/planner.ts
+++ b/packages/squad-sdk/src/platform/planner.ts
@@ -161,6 +161,47 @@ export class PlannerAdapter {
     );
   }
 
+  async createWorkItem(options: { title: string; description?: string; tags?: string[] }): Promise<WorkItem> {
+    // Resolve target bucket from tags (first squad: tag), default to untriaged
+    let bucketId: string | undefined;
+    let bucketName = 'squad:untriaged';
+    if (options.tags?.length) {
+      for (const tag of options.tags) {
+        const bid = await this.getBucketId(tag);
+        if (bid) {
+          bucketId = bid;
+          bucketName = tag;
+          break;
+        }
+      }
+    }
+    if (!bucketId) {
+      bucketId = await this.getBucketId('squad:untriaged');
+    }
+
+    const taskBody: Record<string, unknown> = {
+      planId: this.planId,
+      title: options.title,
+    };
+    if (bucketId) {
+      taskBody.bucketId = bucketId;
+    }
+
+    const output = this.graphFetch('/planner/tasks', 'POST', JSON.stringify(taskBody));
+    const task = JSON.parse(output) as PlannerTask;
+
+    // Add description if provided
+    if (options.description) {
+      this.graphFetch(
+        `/planner/tasks/${task.id}/details`,
+        'PATCH',
+        JSON.stringify({ description: options.description, previewType: 'description' }),
+      );
+    }
+
+    return mapPlannerTaskToWorkItem(task, bucketName);
+  }
+
   async addTag(taskId: string, bucketName: string): Promise<void> {
     const bucketId = await this.getBucketId(bucketName);
     if (!bucketId) {
diff --git a/packages/squad-sdk/src/platform/ralph-commands.ts b/packages/squad-sdk/src/platform/ralph-commands.ts
index efcaf2a3..112ff28c 100644
--- a/packages/squad-sdk/src/platform/ralph-commands.ts
+++ b/packages/squad-sdk/src/platform/ralph-commands.ts
@@ -14,6 +14,7 @@ export interface RalphCommands {
   createBranch: string;
   createPR: string;
   mergePR: string;
+  createWorkItem: string;
 }
 
 /**
@@ -51,6 +52,8 @@ export function getPlannerRalphCommands(): RalphCommands {
       'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
     mergePR:
       'echo "Planner does not manage PRs — use the repo adapter (GitHub or Azure DevOps)"',
+    createWorkItem:
+      `curl -s -X POST -H "Authorization: Bearer $(az account get-access-token --resource-type ms-graph --query accessToken -o tsv)" -H "Content-Type: application/json" -d '{"planId":"{planId}","title":"{title}","bucketId":"{bucketId}"}' "https://graph.microsoft.com/v1.0/planner/tasks"`,
   };
 }
 
@@ -70,6 +73,8 @@ function getGitHubRalphCommands(): RalphCommands {
       'gh pr create --title "{title}" --body "{description}" --head {sourceBranch} --base {targetBranch}',
     mergePR:
       'gh pr merge {id} --merge',
+    createWorkItem:
+      'gh issue create --title "{title}" --body "{description}" --label "{tags}"',
   };
 }
 
@@ -89,5 +94,7 @@ function getAzureDevOpsRalphCommands(): RalphCommands {
       'az repos pr create --title "{title}" --description "{description}" --source-branch {sourceBranch} --target-branch {targetBranch}',
     mergePR:
       'az repos pr update --id {id} --status completed',
+    createWorkItem:
+      'az boards work-item create --type "{workItemType}" --title "{title}" --description "{description}" --fields "System.Tags={tags}"',
   };
 }
diff --git a/packages/squad-sdk/src/platform/types.ts b/packages/squad-sdk/src/platform/types.ts
index db608279..8371d57a 100644
--- a/packages/squad-sdk/src/platform/types.ts
+++ b/packages/squad-sdk/src/platform/types.ts
@@ -45,6 +45,7 @@ export interface PlatformAdapter {
   // Work Items / Issues
   listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]>;
   getWorkItem(id: number): Promise<WorkItem>;
+  createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem>;
   addTag(workItemId: number, tag: string): Promise<void>;
   removeTag(workItemId: number, tag: string): Promise<void>;
   addComment(workItemId: number, comment: string): Promise<void>;
diff --git a/test/platform-adapter.test.ts b/test/platform-adapter.test.ts
index 61fd86b9..2e12fcd2 100644
--- a/test/platform-adapter.test.ts
+++ b/test/platform-adapter.test.ts
@@ -11,7 +11,7 @@ import {
 import { detectWorkItemSource } from '../packages/squad-sdk/src/platform/detect.js';
 import { getRalphScanCommands } from '../packages/squad-sdk/src/platform/ralph-commands.js';
 import { mapPlannerTaskToWorkItem } from '../packages/squad-sdk/src/platform/planner.js';
-import type { PlatformType, WorkItem, PullRequest, WorkItemSource, HybridPlatformConfig } from '../packages/squad-sdk/src/platform/types.js';
+import type { PlatformType, WorkItem, PullRequest, WorkItemSource, HybridPlatformConfig, PlatformAdapter } from '../packages/squad-sdk/src/platform/types.js';
 
 // ─── Platform Detection from URL ───────────────────────────────────────
 
@@ -197,6 +197,94 @@ describe('WorkItem type', () => {
   });
 });
 
+// ─── PlatformAdapter createWorkItem Interface ─────────────────────────
+
+describe('PlatformAdapter createWorkItem interface', () => {
+  it('createWorkItem is part of the PlatformAdapter interface', () => {
+    // Verify the method signature exists in the type
+    const mockAdapter: PlatformAdapter = {
+      type: 'github' as PlatformType,
+      listWorkItems: async () => [],
+      getWorkItem: async (id: number) => ({ id, title: '', state: '', tags: [], url: '' }),
+      createWorkItem: async (options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }) => ({
+        id: 1,
+        title: options.title,
+        state: 'new',
+        tags: options.tags ?? [],
+        url: 'https://example.com/1',
+      }),
+      addTag: async () => {},
+      removeTag: async () => {},
+      addComment: async () => {},
+      listPullRequests: async () => [],
+      createPullRequest: async () => ({ id: 1, title: '', sourceBranch: '', targetBranch: '', status: 'active' as const, author: '', url: '' }),
+      mergePullRequest: async () => {},
+      createBranch: async () => {},
+    };
+    expect(typeof mockAdapter.createWorkItem).toBe('function');
+  });
+
+  it('createWorkItem returns a WorkItem with correct fields', async () => {
+    const mockAdapter: PlatformAdapter = {
+      type: 'azure-devops' as PlatformType,
+      listWorkItems: async () => [],
+      getWorkItem: async (id: number) => ({ id, title: '', state: '', tags: [], url: '' }),
+      createWorkItem: async (options) => ({
+        id: 99,
+        title: options.title,
+        state: 'New',
+        tags: options.tags ?? [],
+        assignedTo: options.assignedTo,
+        url: 'https://dev.azure.com/org/proj/_workitems/edit/99',
+      }),
+      addTag: async () => {},
+      removeTag: async () => {},
+      addComment: async () => {},
+      listPullRequests: async () => [],
+      createPullRequest: async () => ({ id: 1, title: '', sourceBranch: '', targetBranch: '', status: 'active' as const, author: '', url: '' }),
+      mergePullRequest: async () => {},
+      createBranch: async () => {},
+    };
+
+    const wi = await mockAdapter.createWorkItem({
+      title: 'New feature request',
+      description: 'Build the thing',
+      tags: ['squad', 'squad:untriaged'],
+      type: 'User Story',
+    });
+    expect(wi.id).toBe(99);
+    expect(wi.title).toBe('New feature request');
+    expect(wi.tags).toEqual(['squad', 'squad:untriaged']);
+  });
+
+  it('createWorkItem works with minimal options (title only)', async () => {
+    const mockAdapter: PlatformAdapter = {
+      type: 'github' as PlatformType,
+      listWorkItems: async () => [],
+      getWorkItem: async (id: number) => ({ id, title: '', state: '', tags: [], url: '' }),
+      createWorkItem: async (options) => ({
+        id: 10,
+        title: options.title,
+        state: 'open',
+        tags: [],
+        url: 'https://github.com/owner/repo/issues/10',
+      }),
+      addTag: async () => {},
+      removeTag: async () => {},
+      addComment: async () => {},
+      listPullRequests: async () => [],
+      createPullRequest: async () => ({ id: 1, title: '', sourceBranch: '', targetBranch: '', status: 'active' as const, author: '', url: '' }),
+      mergePullRequest: async () => {},
+      createBranch: async () => {},
+    };
+
+    const wi = await mockAdapter.createWorkItem({ title: 'Quick fix' });
+    expect(wi.id).toBe(10);
+    expect(wi.title).toBe('Quick fix');
+    expect(wi.tags).toEqual([]);
+  });
+});
+
 // ─── PullRequest Type Shape ────────────────────────────────────────────
 
 describe('PullRequest type', () => {
@@ -282,6 +370,11 @@ describe('getRalphScanCommands', () => {
     it('returns git checkout for createBranch', () => {
       expect(cmds.createBranch).toContain('git checkout');
     });
+
+    it('returns gh issue create for createWorkItem', () => {
+      expect(cmds.createWorkItem).toContain('gh issue create');
+      expect(cmds.createWorkItem).toContain('{title}');
+    });
   });
 
   describe('azure-devops', () => {
@@ -317,6 +410,12 @@ describe('getRalphScanCommands', () => {
     it('returns git checkout for createBranch', () => {
       expect(cmds.createBranch).toContain('git checkout');
     });
+
+    it('returns az boards work-item create for createWorkItem', () => {
+      expect(cmds.createWorkItem).toContain('az boards work-item create');
+      expect(cmds.createWorkItem).toContain('{title}');
+      expect(cmds.createWorkItem).toContain('{workItemType}');
+    });
   });
 
   it('defaults to github commands for unknown platform', () => {
@@ -378,6 +477,10 @@ describe('edge cases', () => {
     // mergePR should have {id}
     expect(ghCmds.mergePR).toContain('{id}');
     expect(adoCmds.mergePR).toContain('{id}');
+
+    // createWorkItem should have {title}
+    expect(ghCmds.createWorkItem).toContain('{title}');
+    expect(adoCmds.createWorkItem).toContain('{title}');
   });
 });
 
@@ -569,4 +672,10 @@ describe('getRalphScanCommands planner', () => {
   it('indicates PRs are not managed for mergePR', () => {
     expect(cmds.mergePR).toContain('does not manage PRs');
   });
+
+  it('returns Graph API curl for createWorkItem', () => {
+    expect(cmds.createWorkItem).toContain('graph.microsoft.com');
+    expect(cmds.createWorkItem).toContain('planner/tasks');
+    expect(cmds.createWorkItem).toContain('{title}');
+  });
 });

From ee8cb501dc13a69161e39ca73108b59b21b42047 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 10:10:32 +0200
Subject: [PATCH 04/15] fix: update acceptance test expectations to match
 current CLI output
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- status.feature: 'Here:' → 'Active squad:' (output format changed)
- status-extended.feature: same update + negative assertion fix
- init-command.feature: 'Scaffold ready' → 'Your team is ready' (init output changed)

These tests were failing for ALL PRs including upstream dev branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 test/acceptance/features/init-command.feature    | 2 +-
 test/acceptance/features/status-extended.feature | 4 ++--
 test/acceptance/features/status.feature          | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/acceptance/features/init-command.feature b/test/acceptance/features/init-command.feature
index b5ecd9db..a5161db1 100644
--- a/test/acceptance/features/init-command.feature
+++ b/test/acceptance/features/init-command.feature
@@ -3,7 +3,7 @@ Feature: Init command
   Scenario: Init in existing project shows ready message
     Given the current directory has a ".squad" directory
     When I run "squad init"
-    Then the output contains "Scaffold ready"
+    Then the output contains "Your team is ready"
     And the output contains "already exists"
     And the exit code is 0
 
diff --git a/test/acceptance/features/status-extended.feature b/test/acceptance/features/status-extended.feature
index a9c3b353..3abab353 100644
--- a/test/acceptance/features/status-extended.feature
+++ b/test/acceptance/features/status-extended.feature
@@ -4,12 +4,12 @@ Feature: Status command extended
     Given the current directory has a ".squad" directory
     When I run "squad status"
     Then the output contains "Squad Status"
-    And the output contains "Here:"
+    And the output contains "Active squad:"
     And the output contains "Path:"
     And the exit code is 0
 
   Scenario: Status in directory without squad shows no active squad
     Given a directory without a ".squad" directory
     When I run "squad status" in the temp directory
-    Then the output does not contain "Here:  repo"
+    Then the output does not contain "Active squad:  repo"
     And the exit code is 0
diff --git a/test/acceptance/features/status.feature b/test/acceptance/features/status.feature
index 80305f22..ba94d4c6 100644
--- a/test/acceptance/features/status.feature
+++ b/test/acceptance/features/status.feature
@@ -4,5 +4,5 @@ Feature: Status command
     Given the current directory has a ".squad" directory
     When I run "squad status"
     Then the output contains "Squad Status"
-    And the output contains "Here:"
+    And the output contains "Active squad:"
     And the exit code is 0

From 5502701f3ca00fd4199590a06037ad6b0a6844aa Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 11:17:01 +0200
Subject: [PATCH 05/15] fix: make Ralph platform-aware in coordinator prompt +
 auth docs

- Add platform-aware note to Ralph Step 1 scan commands
- Include ADO WIQL examples alongside GitHub examples
- Add auth section: az login (no PATs), ADO MCP server option
- Ralph now knows to check Platform Detection section for command selection

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/features/enterprise-platforms.md | 19 +++++++++++++++++++
 templates/squad.agent.md              | 18 ++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/features/enterprise-platforms.md b/docs/features/enterprise-platforms.md
index 33c9b407..971f89cd 100644
--- a/docs/features/enterprise-platforms.md
+++ b/docs/features/enterprise-platforms.md
@@ -69,6 +69,25 @@ Tag assignment uses the same `squad:{member}` convention, stored as ADO work ite
 
 No additional configuration is needed beyond the `az` CLI setup. Squad reads the git remote URL and automatically selects the correct adapter.
 
+### Authentication
+
+Squad uses the Azure CLI for ADO authentication — **no Personal Access Tokens (PATs) needed.** Run `az login` once, and Squad agents use your authenticated session for all operations.
+
+Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. Add it to `.copilot/mcp-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "npx",
+      "args": ["-y", "@azure/devops-mcp-server"]
+    }
+  }
+}
+```
+
+Squad prefers MCP tools when available, falling back to `az` CLI when not.
+
 To explicitly check which platform Squad detects:
 
 ```typescript
diff --git a/templates/squad.agent.md b/templates/squad.agent.md
index 585af2d5..cd13bad7 100644
--- a/templates/squad.agent.md
+++ b/templates/squad.agent.md
@@ -1032,6 +1032,9 @@ When Ralph is active, run this check cycle after every batch of agent work compl
 
 **Step 1 — Scan for work** (run these in parallel):
 
+> **Platform-aware:** Use the commands from the Platform Detection section above. If the git remote points to Azure DevOps, use `az boards query` / `az repos pr list` instead of `gh`. If work items are in Planner, use Graph API. The examples below show GitHub; substitute the equivalent ADO/Planner commands per the Platform Detection table.
+
+**GitHub:**
 ```bash
 # Untriaged issues (labeled squad but no squad:{member} sub-label)
 gh issue list --label "squad" --state open --json number,title,labels,assignees --limit 20
@@ -1046,6 +1049,21 @@ gh pr list --state open --json number,title,author,labels,isDraft,reviewDecision
 gh pr list --state open --draft --json number,title,author,labels,checks --limit 20
 ```
 
+**Azure DevOps:**
+```bash
+# Untriaged work items
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged' ORDER BY [System.CreatedDate] DESC" --output table
+
+# Member-assigned work items
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member}' AND [System.State] <> 'Closed' ORDER BY [System.CreatedDate] DESC" --output table
+
+# Open PRs
+az repos pr list --status active --output table
+
+# Create a work item
+az boards work-item create --type "User Story" --title "{title}" --fields "System.Tags=squad; squad:untriaged"
+```
+
 **Step 2 — Categorize findings:**
 
 | Category | Signal | Action |

From df7cff5085542a85ad4c78c2164dc572cec86948 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 12:30:30 +0200
Subject: [PATCH 06/15] fix: update remaining acceptance test expectations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- ux-gates.test.ts: 'Here:' → 'Active squad:' (same status output change)
- status-extended.feature: no-squad dir exit code 0 → 1
- hostile-no-config.feature: 'none' → 'not initialized' for status output

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 test/acceptance/features/hostile-no-config.feature | 2 +-
 test/acceptance/features/status-extended.feature   | 2 +-
 test/ux-gates.test.ts                              | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/acceptance/features/hostile-no-config.feature b/test/acceptance/features/hostile-no-config.feature
index 9a03cec4..d4ece0de 100644
--- a/test/acceptance/features/hostile-no-config.feature
+++ b/test/acceptance/features/hostile-no-config.feature
@@ -15,7 +15,7 @@ Feature: Hostile — Missing .squad/ configuration
   Scenario: Status reports no squad without .squad/ directory
     Given a directory without a ".squad" directory
     When I run "squad status" in the temp directory
-    Then the output contains "none"
+    Then the output contains "not initialized"
     And the exit code is 0
 
   Scenario: Doctor runs without .squad/ directory
diff --git a/test/acceptance/features/status-extended.feature b/test/acceptance/features/status-extended.feature
index 3abab353..9875629e 100644
--- a/test/acceptance/features/status-extended.feature
+++ b/test/acceptance/features/status-extended.feature
@@ -12,4 +12,4 @@ Feature: Status command extended
     Given a directory without a ".squad" directory
     When I run "squad status" in the temp directory
     Then the output does not contain "Active squad:  repo"
-    And the exit code is 0
+    And the exit code is 1
diff --git a/test/ux-gates.test.ts b/test/ux-gates.test.ts
index f4872b40..a038fc8d 100644
--- a/test/ux-gates.test.ts
+++ b/test/ux-gates.test.ts
@@ -70,7 +70,7 @@ describe('UX Gates', () => {
     const output = harness.captureFrame();
     
     expect(output).toMatch(/Squad Status/i);
-    expect(output).toMatch(/Here:/i);
+    expect(output).toMatch(/Active squad:/i);
   });
 
   it('Help groups commands into categories', async () => {

From 20af91aa58b5aa2069f73622021694ad29171e36 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 22:22:40 +0200
Subject: [PATCH 07/15] fix: replace execSync with execFileSync to prevent
 shell injection

Address critical review findings from PR #191:
- All adapter methods now use execFileSync with argument arrays
- No user input passes through shell interpretation
- Added JSON.parse error handling with raw output in messages
- createBranch uses execFileSync('git', [...]) instead of string concat
- Follows existing codebase patterns (upstream.ts, rc-tunnel.ts, aspire.ts)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../squad-sdk/src/platform/azure-devops.ts    | 121 ++++++++++--------
 packages/squad-sdk/src/platform/github.ts     |  82 +++++++-----
 packages/squad-sdk/src/platform/planner.ts    |  42 +++---
 3 files changed, 143 insertions(+), 102 deletions(-)

diff --git a/packages/squad-sdk/src/platform/azure-devops.ts b/packages/squad-sdk/src/platform/azure-devops.ts
index a773b0b3..a11dff7d 100644
--- a/packages/squad-sdk/src/platform/azure-devops.ts
+++ b/packages/squad-sdk/src/platform/azure-devops.ts
@@ -4,13 +4,15 @@
  * @module platform/azure-devops
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 import type { PlatformAdapter, PlatformType, WorkItem, PullRequest } from './types.js';
 
+const EXEC_OPTS: { encoding: 'utf-8'; stdio: ['pipe', 'pipe', 'pipe'] } = { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] };
+
 /** Check whether the az CLI with devops extension is available */
 function assertAzCliAvailable(): void {
   try {
-    execSync('az devops -h', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    execSync('az devops -h', EXEC_OPTS);
   } catch {
     throw new Error(
       'Azure DevOps CLI not found. Install it with:\n' +
@@ -22,6 +24,15 @@ function assertAzCliAvailable(): void {
   }
 }
 
+/** Safely parse JSON output, including raw text in error messages */
+function parseJson<T>(raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`Failed to parse JSON from CLI output: ${(err as Error).message}\nRaw output: ${raw}`);
+  }
+}
+
 export class AzureDevOpsAdapter implements PlatformAdapter {
   readonly type: PlatformType = 'azure-devops';
 
@@ -37,12 +48,13 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     return `https://dev.azure.com/${this.org}`;
   }
 
-  private get defaults(): string {
-    return `--org "${this.orgUrl}" --project "${this.project}"`;
+  /** Common az CLI default args */
+  private get defaultArgs(): string[] {
+    return ['--org', this.orgUrl, '--project', this.project];
   }
 
-  private exec(cmd: string): string {
-    return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  private az(args: string[]): string {
+    return execFileSync('az', args, EXEC_OPTS).trim();
   }
 
   async listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]> {
@@ -61,10 +73,10 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     const top = options.limit ?? 50;
     const wiql = `SELECT [System.Id] FROM WorkItems WHERE ${where} ORDER BY [System.CreatedDate] DESC`;
 
-    const output = this.exec(
-      `az boards query --wiql "${wiql}" ${this.defaults} --output json`,
-    );
-    const items = JSON.parse(output) as Array<{ id: number; fields?: Record<string, unknown> }>;
+    const output = this.az([
+      'boards', 'query', '--wiql', wiql, ...this.defaultArgs, '--output', 'json',
+    ]);
+    const items = parseJson<Array<{ id: number; fields?: Record<string, unknown> }>>(output);
 
     // Fetch full details for each work item (limited by top)
     const results: WorkItem[] = [];
@@ -76,15 +88,15 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
   }
 
   async getWorkItem(id: number): Promise<WorkItem> {
-    const output = this.exec(
-      `az boards work-item show --id ${id} ${this.defaults} --output json`,
-    );
-    const wi = JSON.parse(output) as {
+    const output = this.az([
+      'boards', 'work-item', 'show', '--id', String(id), ...this.defaultArgs, '--output', 'json',
+    ]);
+    const wi = parseJson<{
       id: number;
       fields: Record<string, unknown>;
       url: string;
       _links?: { html?: { href?: string } };
-    };
+    }>(output);
 
     const fields = wi.fields;
     const tags = typeof fields['System.Tags'] === 'string'
@@ -105,27 +117,27 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
   async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem> {
     const wiType = options.type ?? 'User Story';
     const fields: string[] = [
-      `"System.Title=${options.title.replace(/"/g, '\\"')}"`,
+      `System.Title=${options.title}`,
     ];
     if (options.description) {
-      fields.push(`"System.Description=${options.description.replace(/"/g, '\\"')}"`);
+      fields.push(`System.Description=${options.description}`);
     }
     if (options.tags?.length) {
-      fields.push(`"System.Tags=${options.tags.join('; ')}"`);
+      fields.push(`System.Tags=${options.tags.join('; ')}`);
     }
     if (options.assignedTo) {
-      fields.push(`"System.AssignedTo=${options.assignedTo}"`);
+      fields.push(`System.AssignedTo=${options.assignedTo}`);
     }
 
-    const output = this.exec(
-      `az boards work-item create --type "${wiType}" --fields ${fields.join(' ')} ${this.defaults} --output json`,
-    );
-    const created = JSON.parse(output) as {
+    const output = this.az([
+      'boards', 'work-item', 'create', '--type', wiType, '--fields', ...fields, ...this.defaultArgs, '--output', 'json',
+    ]);
+    const created = parseJson<{
       id: number;
       fields: Record<string, unknown>;
       url: string;
       _links?: { html?: { href?: string } };
-    };
+    }>(output);
 
     const createdFields = created.fields;
     const tags = typeof createdFields['System.Tags'] === 'string'
@@ -147,39 +159,41 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     const currentTags = wi.tags.filter((t) => t !== tag);
     currentTags.push(tag);
     const tagsStr = currentTags.join('; ');
-    this.exec(
-      `az boards work-item update --id ${workItemId} --fields "System.Tags=${tagsStr}" ${this.defaults} --output json`,
-    );
+    this.az([
+      'boards', 'work-item', 'update', '--id', String(workItemId),
+      '--fields', `System.Tags=${tagsStr}`, ...this.defaultArgs, '--output', 'json',
+    ]);
   }
 
   async removeTag(workItemId: number, tag: string): Promise<void> {
     const wi = await this.getWorkItem(workItemId);
     const updatedTags = wi.tags.filter((t) => t !== tag);
     const tagsStr = updatedTags.join('; ');
-    this.exec(
-      `az boards work-item update --id ${workItemId} --fields "System.Tags=${tagsStr}" ${this.defaults} --output json`,
-    );
+    this.az([
+      'boards', 'work-item', 'update', '--id', String(workItemId),
+      '--fields', `System.Tags=${tagsStr}`, ...this.defaultArgs, '--output', 'json',
+    ]);
   }
 
   async addComment(workItemId: number, comment: string): Promise<void> {
-    // az boards work-item update --id ID --discussion "comment"
-    this.exec(
-      `az boards work-item update --id ${workItemId} --discussion "${comment.replace(/"/g, '\\"')}" ${this.defaults} --output json`,
-    );
+    this.az([
+      'boards', 'work-item', 'update', '--id', String(workItemId),
+      '--discussion', comment, ...this.defaultArgs, '--output', 'json',
+    ]);
   }
 
   async listPullRequests(options: { status?: string; limit?: number }): Promise<PullRequest[]> {
     const args = [
-      'az', 'repos', 'pr', 'list',
-      '--repository', `"${this.repo}"`,
-      this.defaults,
+      'repos', 'pr', 'list',
+      '--repository', this.repo,
+      ...this.defaultArgs,
       '--output', 'json',
     ];
     if (options.status) args.push('--status', options.status);
     if (options.limit) args.push('--top', String(options.limit));
 
-    const output = this.exec(args.join(' '));
-    const prs = JSON.parse(output) as Array<{
+    const output = this.az(args);
+    const prs = parseJson<Array<{
       pullRequestId: number;
       title: string;
       sourceRefName: string;
@@ -190,7 +204,7 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
       createdBy: { displayName: string; uniqueName: string };
       url: string;
       repository?: { webUrl?: string };
-    }>;
+    }>>(output);
 
     return prs.map((pr) => ({
       id: pr.pullRequestId,
@@ -213,20 +227,20 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     description?: string;
   }): Promise<PullRequest> {
     const args = [
-      'az', 'repos', 'pr', 'create',
-      '--repository', `"${this.repo}"`,
+      'repos', 'pr', 'create',
+      '--repository', this.repo,
       '--source-branch', options.sourceBranch,
       '--target-branch', options.targetBranch,
-      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
-      this.defaults,
+      '--title', options.title,
+      ...this.defaultArgs,
       '--output', 'json',
     ];
     if (options.description) {
-      args.push('--description', `"${options.description.replace(/"/g, '\\"')}"`);
+      args.push('--description', options.description);
     }
 
-    const output = this.exec(args.join(' '));
-    const pr = JSON.parse(output) as {
+    const output = this.az(args);
+    const pr = parseJson<{
       pullRequestId: number;
       title: string;
       sourceRefName: string;
@@ -236,7 +250,7 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
       reviewers: Array<{ vote: number }>;
       createdBy: { displayName: string; uniqueName: string };
       url: string;
-    };
+    }>(output);
 
     return {
       id: pr.pullRequestId,
@@ -251,14 +265,17 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
   }
 
   async mergePullRequest(id: number): Promise<void> {
-    this.exec(
-      `az repos pr update --id ${id} --status completed ${this.defaults} --output json`,
-    );
+    this.az([
+      'repos', 'pr', 'update', '--id', String(id),
+      '--status', 'completed', ...this.defaultArgs, '--output', 'json',
+    ]);
   }
 
   async createBranch(name: string, fromBranch?: string): Promise<void> {
     const base = fromBranch ?? 'main';
-    this.exec(`git checkout ${base} && git pull && git checkout -b ${name}`);
+    execFileSync('git', ['checkout', base], EXEC_OPTS);
+    execFileSync('git', ['pull'], EXEC_OPTS);
+    execFileSync('git', ['checkout', '-b', name], EXEC_OPTS);
   }
 }
 
diff --git a/packages/squad-sdk/src/platform/github.ts b/packages/squad-sdk/src/platform/github.ts
index 43d9a0e0..a6c9f58e 100644
--- a/packages/squad-sdk/src/platform/github.ts
+++ b/packages/squad-sdk/src/platform/github.ts
@@ -4,9 +4,20 @@
  * @module platform/github
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import type { PlatformAdapter, PlatformType, WorkItem, PullRequest } from './types.js';
 
+const EXEC_OPTS: { encoding: 'utf-8'; stdio: ['pipe', 'pipe', 'pipe'] } = { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+/** Safely parse JSON output, including raw text in error messages */
+function parseJson<T>(raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`Failed to parse JSON from CLI output: ${(err as Error).message}\nRaw output: ${raw}`);
+  }
+}
+
 export class GitHubAdapter implements PlatformAdapter {
   readonly type: PlatformType = 'github';
 
@@ -19,12 +30,12 @@ export class GitHubAdapter implements PlatformAdapter {
     return `${this.owner}/${this.repo}`;
   }
 
-  private exec(cmd: string): string {
-    return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  private gh(args: string[]): string {
+    return execFileSync('gh', args, EXEC_OPTS).trim();
   }
 
   async listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]> {
-    const args = ['gh', 'issue', 'list', '--repo', this.repoFlag, '--json', 'number,title,state,labels,assignees,url'];
+    const args = ['issue', 'list', '--repo', this.repoFlag, '--json', 'number,title,state,labels,assignees,url'];
     if (options.state) args.push('--state', options.state);
     if (options.limit) args.push('--limit', String(options.limit));
     if (options.tags?.length) {
@@ -33,15 +44,15 @@ export class GitHubAdapter implements PlatformAdapter {
       }
     }
 
-    const output = this.exec(args.join(' '));
-    const issues = JSON.parse(output) as Array<{
+    const output = this.gh(args);
+    const issues = parseJson<Array<{
       number: number;
       title: string;
       state: string;
       labels: Array<{ name: string }>;
       assignees: Array<{ login: string }>;
       url: string;
-    }>;
+    }>>(output);
 
     return issues.map((issue) => ({
       id: issue.number,
@@ -54,17 +65,18 @@ export class GitHubAdapter implements PlatformAdapter {
   }
 
   async getWorkItem(id: number): Promise<WorkItem> {
-    const output = this.exec(
-      `gh issue view ${id} --repo ${this.repoFlag} --json number,title,state,labels,assignees,url`,
-    );
-    const issue = JSON.parse(output) as {
+    const output = this.gh([
+      'issue', 'view', String(id), '--repo', this.repoFlag,
+      '--json', 'number,title,state,labels,assignees,url',
+    ]);
+    const issue = parseJson<{
       number: number;
       title: string;
       state: string;
       labels: Array<{ name: string }>;
       assignees: Array<{ login: string }>;
       url: string;
-    };
+    }>(output);
 
     return {
       id: issue.number,
@@ -78,32 +90,32 @@ export class GitHubAdapter implements PlatformAdapter {
 
   async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem> {
     const args = [
-      'gh', 'issue', 'create',
+      'issue', 'create',
       '--repo', this.repoFlag,
-      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
+      '--title', options.title,
       '--json', 'number,title,state,labels,assignees,url',
     ];
     if (options.description) {
-      args.push('--body', `"${options.description.replace(/"/g, '\\"')}"`);
+      args.push('--body', options.description);
     }
     if (options.tags?.length) {
       for (const tag of options.tags) {
-        args.push('--label', `"${tag}"`);
+        args.push('--label', tag);
       }
     }
     if (options.assignedTo) {
       args.push('--assignee', options.assignedTo);
     }
 
-    const output = this.exec(args.join(' '));
-    const issue = JSON.parse(output) as {
+    const output = this.gh(args);
+    const issue = parseJson<{
       number: number;
       title: string;
       state: string;
       labels: Array<{ name: string }>;
       assignees: Array<{ login: string }>;
       url: string;
-    };
+    }>(output);
 
     return {
       id: issue.number,
@@ -116,24 +128,24 @@ export class GitHubAdapter implements PlatformAdapter {
   }
 
   async addTag(workItemId: number, tag: string): Promise<void> {
-    this.exec(`gh issue edit ${workItemId} --repo ${this.repoFlag} --add-label "${tag}"`);
+    this.gh(['issue', 'edit', String(workItemId), '--repo', this.repoFlag, '--add-label', tag]);
   }
 
   async removeTag(workItemId: number, tag: string): Promise<void> {
-    this.exec(`gh issue edit ${workItemId} --repo ${this.repoFlag} --remove-label "${tag}"`);
+    this.gh(['issue', 'edit', String(workItemId), '--repo', this.repoFlag, '--remove-label', tag]);
   }
 
   async addComment(workItemId: number, comment: string): Promise<void> {
-    this.exec(`gh issue comment ${workItemId} --repo ${this.repoFlag} --body "${comment.replace(/"/g, '\\"')}"`);
+    this.gh(['issue', 'comment', String(workItemId), '--repo', this.repoFlag, '--body', comment]);
   }
 
   async listPullRequests(options: { status?: string; limit?: number }): Promise<PullRequest[]> {
-    const args = ['gh', 'pr', 'list', '--repo', this.repoFlag, '--json', 'number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author,url'];
+    const args = ['pr', 'list', '--repo', this.repoFlag, '--json', 'number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author,url'];
     if (options.status) args.push('--state', options.status);
     if (options.limit) args.push('--limit', String(options.limit));
 
-    const output = this.exec(args.join(' '));
-    const prs = JSON.parse(output) as Array<{
+    const output = this.gh(args);
+    const prs = parseJson<Array<{
       number: number;
       title: string;
       headRefName: string;
@@ -143,7 +155,7 @@ export class GitHubAdapter implements PlatformAdapter {
       reviewDecision: string;
       author: { login: string };
       url: string;
-    }>;
+    }>>(output);
 
     return prs.map((pr) => ({
       id: pr.number,
@@ -164,19 +176,19 @@ export class GitHubAdapter implements PlatformAdapter {
     description?: string;
   }): Promise<PullRequest> {
     const args = [
-      'gh', 'pr', 'create',
+      'pr', 'create',
       '--repo', this.repoFlag,
       '--head', options.sourceBranch,
       '--base', options.targetBranch,
-      '--title', `"${options.title.replace(/"/g, '\\"')}"`,
+      '--title', options.title,
       '--json', 'number,title,headRefName,baseRefName,state,isDraft,reviewDecision,author,url',
     ];
     if (options.description) {
-      args.push('--body', `"${options.description.replace(/"/g, '\\"')}"`);
+      args.push('--body', options.description);
     }
 
-    const output = this.exec(args.join(' '));
-    const pr = JSON.parse(output) as {
+    const output = this.gh(args);
+    const pr = parseJson<{
       number: number;
       title: string;
       headRefName: string;
@@ -186,7 +198,7 @@ export class GitHubAdapter implements PlatformAdapter {
       reviewDecision: string;
       author: { login: string };
       url: string;
-    };
+    }>(output);
 
     return {
       id: pr.number,
@@ -201,12 +213,14 @@ export class GitHubAdapter implements PlatformAdapter {
   }
 
   async mergePullRequest(id: number): Promise<void> {
-    this.exec(`gh pr merge ${id} --repo ${this.repoFlag} --merge`);
+    this.gh(['pr', 'merge', String(id), '--repo', this.repoFlag, '--merge']);
   }
 
   async createBranch(name: string, fromBranch?: string): Promise<void> {
     const base = fromBranch ?? 'main';
-    this.exec(`git checkout ${base} && git pull && git checkout -b ${name}`);
+    execFileSync('git', ['checkout', base], EXEC_OPTS);
+    execFileSync('git', ['pull'], EXEC_OPTS);
+    execFileSync('git', ['checkout', '-b', name], EXEC_OPTS);
   }
 }
 
diff --git a/packages/squad-sdk/src/platform/planner.ts b/packages/squad-sdk/src/platform/planner.ts
index e07a82ee..926a3201 100644
--- a/packages/squad-sdk/src/platform/planner.ts
+++ b/packages/squad-sdk/src/platform/planner.ts
@@ -5,9 +5,11 @@
  * @module platform/planner
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import type { PlatformType, WorkItem } from './types.js';
 
+const EXEC_OPTS: { encoding: 'utf-8'; stdio: ['pipe', 'pipe', 'pipe'] } = { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] };
+
 /** Planner task shape from Graph API */
 interface PlannerTask {
   id: string;
@@ -29,9 +31,10 @@ interface PlannerBucket {
  */
 function getGraphToken(): string {
   try {
-    const output = execSync(
-      'az account get-access-token --resource-type ms-graph --query accessToken -o tsv',
-      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] },
+    const output = execFileSync(
+      'az',
+      ['account', 'get-access-token', '--resource-type', 'ms-graph', '--query', 'accessToken', '-o', 'tsv'],
+      EXEC_OPTS,
     ).trim();
     return output;
   } catch {
@@ -43,8 +46,18 @@ function getGraphToken(): string {
   }
 }
 
+/** Safely parse JSON output, including raw text in error messages */
+function parseJson<T>(raw: string): T {
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`Failed to parse JSON from CLI output: ${(err as Error).message}\nRaw output: ${raw}`);
+  }
+}
+
 /**
  * Map a Planner task + bucket name to a normalized WorkItem.
+ * The original Planner task ID is stored in the url field so it can be recovered.
  */
 export function mapPlannerTaskToWorkItem(
   task: PlannerTask,
@@ -85,20 +98,17 @@ export class PlannerAdapter {
   private graphFetch(path: string, method = 'GET', body?: string): string {
     const token = getGraphToken();
     const curlArgs = [
-      'curl', '-s',
+      '-s',
       '-X', method,
-      '-H', `"Authorization: Bearer ${token}"`,
-      '-H', '"Content-Type: application/json"',
+      '-H', `Authorization: Bearer ${token}`,
+      '-H', 'Content-Type: application/json',
     ];
     if (body) {
-      curlArgs.push('-d', `'${body}'`);
+      curlArgs.push('-d', body);
     }
-    curlArgs.push(`"https://graph.microsoft.com/v1.0${path}"`);
+    curlArgs.push(`https://graph.microsoft.com/v1.0${path}`);
 
-    return execSync(curlArgs.join(' '), {
-      encoding: 'utf-8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    }).trim();
+    return execFileSync('curl', curlArgs, EXEC_OPTS).trim();
   }
 
   /** Fetch and cache buckets for this plan */
@@ -106,7 +116,7 @@ export class PlannerAdapter {
     if (this.bucketCache) return this.bucketCache;
 
     const output = this.graphFetch(`/planner/plans/${this.planId}/buckets`);
-    const data = JSON.parse(output) as { value: PlannerBucket[] };
+    const data = parseJson<{ value: PlannerBucket[] }>(output);
     this.bucketCache = data.value;
     return this.bucketCache;
   }
@@ -129,7 +139,7 @@ export class PlannerAdapter {
     limit?: number;
   }): Promise<WorkItem[]> {
     const output = this.graphFetch(`/planner/plans/${this.planId}/tasks`);
-    const data = JSON.parse(output) as { value: PlannerTask[] };
+    const data = parseJson<{ value: PlannerTask[] }>(output);
     const buckets = await this.getBuckets();
     const bucketMap = new Map(buckets.map((b) => [b.id, b.name]));
 
@@ -188,7 +198,7 @@ export class PlannerAdapter {
     }
 
     const output = this.graphFetch('/planner/tasks', 'POST', JSON.stringify(taskBody));
-    const task = JSON.parse(output) as PlannerTask;
+    const task = parseJson<PlannerTask>(output);
 
     // Add description if provided
     if (options.description) {

From 5daf83e5d4874ded55c61fdac9b2160d2e27704b Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Thu, 5 Mar 2026 23:46:57 +0200
Subject: [PATCH 08/15] fix: escape WIQL values and hide bearer token from
 process args

- WIQL injection: escape single quotes in state/tags/project values
- Bearer token: pass via curl --config stdin instead of CLI args
- Addresses follow-up review from PR #191

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/squad-sdk/src/platform/azure-devops.ts | 11 ++++++++---
 packages/squad-sdk/src/platform/planner.ts      | 15 +++++++++++----
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/packages/squad-sdk/src/platform/azure-devops.ts b/packages/squad-sdk/src/platform/azure-devops.ts
index a11dff7d..00bf12fb 100644
--- a/packages/squad-sdk/src/platform/azure-devops.ts
+++ b/packages/squad-sdk/src/platform/azure-devops.ts
@@ -24,6 +24,11 @@ function assertAzCliAvailable(): void {
   }
 }
 
+/** Escape a value for safe interpolation into a WIQL string (double single-quotes). */
+function escapeWiql(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
 /** Safely parse JSON output, including raw text in error messages */
 function parseJson<T>(raw: string): T {
   try {
@@ -60,14 +65,14 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
   async listWorkItems(options: { tags?: string[]; state?: string; limit?: number }): Promise<WorkItem[]> {
     const conditions: string[] = [];
     if (options.state) {
-      conditions.push(`[System.State] = '${options.state}'`);
+      conditions.push(`[System.State] = '${escapeWiql(options.state)}'`);
     }
     if (options.tags?.length) {
       for (const tag of options.tags) {
-        conditions.push(`[System.Tags] Contains '${tag}'`);
+        conditions.push(`[System.Tags] Contains '${escapeWiql(tag)}'`);
       }
     }
-    conditions.push(`[System.TeamProject] = '${this.project}'`);
+    conditions.push(`[System.TeamProject] = '${escapeWiql(this.project)}'`);
 
     const where = conditions.join(' AND ');
     const top = options.limit ?? 50;
diff --git a/packages/squad-sdk/src/platform/planner.ts b/packages/squad-sdk/src/platform/planner.ts
index 926a3201..277b1580 100644
--- a/packages/squad-sdk/src/platform/planner.ts
+++ b/packages/squad-sdk/src/platform/planner.ts
@@ -97,18 +97,25 @@ export class PlannerAdapter {
 
   private graphFetch(path: string, method = 'GET', body?: string): string {
     const token = getGraphToken();
+    const url = `https://graph.microsoft.com/v1.0${path}`;
     const curlArgs = [
       '-s',
       '-X', method,
-      '-H', `Authorization: Bearer ${token}`,
       '-H', 'Content-Type: application/json',
+      '--config', '-',
     ];
     if (body) {
       curlArgs.push('-d', body);
     }
-    curlArgs.push(`https://graph.microsoft.com/v1.0${path}`);
-
-    return execFileSync('curl', curlArgs, EXEC_OPTS).trim();
+    curlArgs.push(url);
+
+    // Pass the Authorization header via stdin so the token is not visible in process args.
+    const config = `header "Authorization: Bearer ${token}"`;
+    return execFileSync('curl', curlArgs, {
+      encoding: 'utf-8',
+      input: config,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
   }
 
   /** Fetch and cache buckets for this plan */

From 39ac72f77a9f51b2ea4da367bc88b15557e1576d Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Fri, 6 Mar 2026 16:46:05 +0200
Subject: [PATCH 09/15] fix: wire upstream command into CLI entry point

The upstream command (add/remove/list/sync) was fully implemented in
upstream.ts but never registered in cli-entry.ts, so running
'squad upstream' returned 'Unknown command'. Added routing and help text.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/squad-cli/src/cli-entry.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index 1be85c15..e08d2070 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -68,6 +68,9 @@ async function main(): Promise<void> {
     console.log(`             Overwrites: squad.agent.md, templates dir (.squad/templates/)`);
     console.log(`             Never touches: .squad/ or .ai-team/ (your team state)`);
     console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
+    console.log(`  ${BOLD}upstream${RESET}   Manage upstream squad inheritance`);
+    console.log(`             Usage: upstream <add|remove|list|sync>`);
+    console.log(`             Add shared knowledge from parent squads (local, git, or export)`);
     console.log(`\nUtilities:`);
     console.log(`  ${BOLD}plugin${RESET}     Manage plugin marketplaces`);
     console.log(`             Usage: plugin marketplace add|remove|list|browse`);
@@ -276,6 +279,12 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (cmd === 'upstream') {
+    const { upstreamCommand } = await import('./cli/commands/upstream.js');
+    await upstreamCommand(args.slice(1));
+    return;
+  }
+
   // Unknown command
   fatal(`Unknown command: ${cmd}\n       Run 'squad help' for usage information.`);
 }

From a2818d28f98cab26f4a2b1d9524e0dd0613022b6 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 11:52:42 +0200
Subject: [PATCH 10/15] fix: skip GitHub workflows for ADO repos, add platform
 detection to init

- Bug 1: squad init now detects ADO from git remote and skips .github/workflows/
- Bug 2: config.json includes platform field when ADO detected
- Bug 3: MCP config template uses platform-appropriate example

Reported by ADO integration tester.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 packages/squad-sdk/src/config/init.ts | 64 ++++++++++++++++++++++-----
 1 file changed, 52 insertions(+), 12 deletions(-)

diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts
index d5cc5531..897c2845 100644
--- a/packages/squad-sdk/src/config/init.ts
+++ b/packages/squad-sdk/src/config/init.ts
@@ -12,6 +12,7 @@ import { mkdir, writeFile, readFile, copyFile, readdir, appendFile, unlink } fro
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { existsSync, cpSync, statSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
+import { execFileSync } from 'node:child_process';
 import { MODELS } from '../runtime/constants.js';
 import type { SquadConfig, ModelSelectionConfig, RoutingConfig } from '../runtime/config.js';
 
@@ -538,10 +539,23 @@ export async function initSquad(options: InitOptions): Promise<InitResult> {
   
   const squadConfigPath = join(squadDir, 'config.json');
   if (!existsSync(squadConfigPath)) {
+    // Detect platform from git remote for config
+    let detectedPlatform: string | undefined;
+    try {
+      const remoteUrl = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: teamRoot, encoding: 'utf-8' }).trim();
+      if (remoteUrl.includes('dev.azure.com') || remoteUrl.includes('visualstudio.com') || remoteUrl.includes('ssh.dev.azure.com')) {
+        detectedPlatform = 'azure-devops';
+      }
+    } catch {
+      // No git remote — skip platform detection
+    }
     const squadConfig: Record<string, unknown> = {
       version: 1,
       teamRoot: teamRoot,
     };
+    if (detectedPlatform) {
+      squadConfig.platform = detectedPlatform;
+    }
     // Only include extractionDisabled if explicitly set
     if (options.extractionDisabled) {
       squadConfig.extractionDisabled = true;
@@ -794,10 +808,24 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre
   }
   
   // -------------------------------------------------------------------------
-  // Copy workflows (optional)
+  // Detect platform from git remote
   // -------------------------------------------------------------------------
   
-  if (includeWorkflows && templatesDir && existsSync(join(templatesDir, 'workflows'))) {
+  let isGitHub = true;
+  try {
+    const remoteUrl = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: teamRoot, encoding: 'utf-8' }).trim();
+    if (remoteUrl.includes('dev.azure.com') || remoteUrl.includes('visualstudio.com') || remoteUrl.includes('ssh.dev.azure.com')) {
+      isGitHub = false;
+    }
+  } catch {
+    // No git remote — assume GitHub (default)
+  }
+
+  // -------------------------------------------------------------------------
+  // Copy workflows (optional) — skip for ADO repos
+  // -------------------------------------------------------------------------
+  
+  if (includeWorkflows && isGitHub && templatesDir && existsSync(join(templatesDir, 'workflows'))) {
     const workflowsSrc = join(templatesDir, 'workflows');
     const workflowsDest = join(teamRoot, '.github', 'workflows');
     
@@ -824,18 +852,30 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre
   if (includeMcpConfig) {
     const mcpConfigPath = join(teamRoot, '.copilot', 'mcp-config.json');
     if (!existsSync(mcpConfigPath)) {
-      const mcpSample = {
-        mcpServers: {
-          "EXAMPLE-trello": {
-            command: "npx",
-            args: ["-y", "@trello/mcp-server"],
-            env: {
-              TRELLO_API_KEY: "${TRELLO_API_KEY}",
-              TRELLO_TOKEN: "${TRELLO_TOKEN}"
+      const mcpSample = isGitHub
+        ? {
+            mcpServers: {
+              "EXAMPLE-github": {
+                command: "npx",
+                args: ["-y", "@anthropic/github-mcp-server"],
+                env: {
+                  GITHUB_TOKEN: "${GITHUB_TOKEN}"
+                }
+              }
             }
           }
-        }
-      };
+        : {
+            mcpServers: {
+              "EXAMPLE-azure-devops": {
+                command: "npx",
+                args: ["-y", "azure-devops-mcp-server"],
+                env: {
+                  AZURE_DEVOPS_ORG: "${AZURE_DEVOPS_ORG}",
+                  AZURE_DEVOPS_PAT: "${AZURE_DEVOPS_PAT}"
+                }
+              }
+            }
+          };
       await mkdir(dirname(mcpConfigPath), { recursive: true });
       await writeFile(mcpConfigPath, JSON.stringify(mcpSample, null, 2) + '\n', 'utf-8');
       createdFiles.push(toRelativePath(mcpConfigPath));

From 0d3dca4e185306704b14ee23ebd8184ced81ae1a Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 14:51:27 +0200
Subject: [PATCH 11/15] feat: ADO configurable work item type, area/iteration
 paths, cross-project support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add AdoWorkItemConfig interface supporting enterprise ADO scenarios:
- defaultWorkItemType: configure Scenario, Bug, etc. (default: User Story)
- areaPath: route work items to specific team backlogs
- iterationPath: place work items in specific sprints
- org/project: support work items in a different ADO project/org than
  the git repo (common in large enterprises)

Config lives in .squad/config.json under the 'ado' key. All fields are
optional — omitted fields use sensible defaults.

Work item operations (create, list, get, tag, comment) now use separate
workItemArgs that resolve org/project from config, while repo operations
(PRs, branches) continue using the git remote's org/project.

- 92 platform adapter tests pass (6 new)
- Updated enterprise-platforms.md with config table
- squad init writes ado section template for ADO repos

Addresses #240

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/features/enterprise-platforms.md         | 31 ++++++++-
 packages/squad-sdk/src/config/init.ts         | 14 ++++
 .../squad-sdk/src/platform/azure-devops.ts    | 61 ++++++++++++++---
 packages/squad-sdk/src/platform/index.ts      | 23 ++++++-
 test/platform-adapter.test.ts                 | 65 +++++++++++++++++++
 5 files changed, 182 insertions(+), 12 deletions(-)

diff --git a/docs/features/enterprise-platforms.md b/docs/features/enterprise-platforms.md
index 971f89cd..527a8ab2 100644
--- a/docs/features/enterprise-platforms.md
+++ b/docs/features/enterprise-platforms.md
@@ -67,7 +67,36 @@ Tag assignment uses the same `squad:{member}` convention, stored as ADO work ite
 
 ## Configuration
 
-No additional configuration is needed beyond the `az` CLI setup. Squad reads the git remote URL and automatically selects the correct adapter.
+Squad auto-detects ADO from the git remote URL. For basic use, no extra configuration is needed.
+
+### Work Item Configuration
+
+When your ADO environment has custom work item types, area paths, iterations, or when work items live in a **different project or org** than the git repo, configure the `ado` section in `.squad/config.json`:
+
+```json
+{
+  "version": 1,
+  "teamRoot": "/path/to/repo",
+  "platform": "azure-devops",
+  "ado": {
+    "org": "my-org",
+    "project": "my-work-items-project",
+    "defaultWorkItemType": "Scenario",
+    "areaPath": "MyProject\\Team Alpha",
+    "iterationPath": "MyProject\\Sprint 5"
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `ado.org` | *(from git remote)* | ADO org for work items — set when work items are in a different org than the repo |
+| `ado.project` | *(from git remote)* | ADO project for work items — set when work items are in a different project |
+| `ado.defaultWorkItemType` | `"User Story"` | Default type for new work items. Some orgs use `"Scenario"`, `"Bug"`, or custom types |
+| `ado.areaPath` | *(project default)* | Area path for new work items — controls which team's backlog they appear in |
+| `ado.iterationPath` | *(project default)* | Iteration/sprint path — controls which sprint board work items appear on |
+
+All fields are optional. Omitted fields use the defaults shown above.
 
 ### Authentication
 
diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts
index 897c2845..065bc553 100644
--- a/packages/squad-sdk/src/config/init.ts
+++ b/packages/squad-sdk/src/config/init.ts
@@ -556,6 +556,20 @@ export async function initSquad(options: InitOptions): Promise<InitResult> {
     if (detectedPlatform) {
       squadConfig.platform = detectedPlatform;
     }
+    if (detectedPlatform === 'azure-devops') {
+      // ADO work item defaults — users can customize these:
+      // - org/project: set when work items live in a different project than the repo
+      // - defaultWorkItemType: "User Story", "Scenario", "Bug", etc.
+      // - areaPath: e.g. "MyProject\\Team A" (backslash-separated)
+      // - iterationPath: e.g. "MyProject\\Sprint 1"
+      squadConfig.ado = {
+        // org: "my-org",           // uncomment if work items are in a different org
+        // project: "my-project",   // uncomment if work items are in a different project
+        // defaultWorkItemType: "User Story",
+        // areaPath: "",
+        // iterationPath: "",
+      };
+    }
     // Only include extractionDisabled if explicitly set
     if (options.extractionDisabled) {
       squadConfig.extractionDisabled = true;
diff --git a/packages/squad-sdk/src/platform/azure-devops.ts b/packages/squad-sdk/src/platform/azure-devops.ts
index 00bf12fb..16474e07 100644
--- a/packages/squad-sdk/src/platform/azure-devops.ts
+++ b/packages/squad-sdk/src/platform/azure-devops.ts
@@ -38,6 +38,20 @@ function parseJson<T>(raw: string): T {
   }
 }
 
+/** ADO-specific configuration for work items that may live in a different org/project than the repo. */
+export interface AdoWorkItemConfig {
+  /** Azure DevOps org for work items (if different from repo org) */
+  org?: string;
+  /** Azure DevOps project for work items (if different from repo project) */
+  project?: string;
+  /** Default work item type — e.g. "User Story", "Scenario", "Bug" (default: "User Story") */
+  defaultWorkItemType?: string;
+  /** Default area path for new work items — e.g. "MyProject\\Team A" */
+  areaPath?: string;
+  /** Default iteration path for new work items — e.g. "MyProject\\Sprint 1" */
+  iterationPath?: string;
+}
+
 export class AzureDevOpsAdapter implements PlatformAdapter {
   readonly type: PlatformType = 'azure-devops';
 
@@ -45,6 +59,7 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     private readonly org: string,
     private readonly project: string,
     private readonly repo: string,
+    private readonly workItemConfig?: AdoWorkItemConfig,
   ) {
     assertAzCliAvailable();
   }
@@ -53,11 +68,27 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     return `https://dev.azure.com/${this.org}`;
   }
 
-  /** Common az CLI default args */
+  /** Org URL for work item operations (may differ from repo org). */
+  private get wiOrgUrl(): string {
+    const wiOrg = this.workItemConfig?.org ?? this.org;
+    return `https://dev.azure.com/${wiOrg}`;
+  }
+
+  /** Project for work item operations (may differ from repo project). */
+  private get wiProject(): string {
+    return this.workItemConfig?.project ?? this.project;
+  }
+
+  /** Common az CLI default args for repo operations */
   private get defaultArgs(): string[] {
     return ['--org', this.orgUrl, '--project', this.project];
   }
 
+  /** Common az CLI default args for work item operations */
+  private get workItemArgs(): string[] {
+    return ['--org', this.wiOrgUrl, '--project', this.wiProject];
+  }
+
   private az(args: string[]): string {
     return execFileSync('az', args, EXEC_OPTS).trim();
   }
@@ -72,14 +103,14 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
         conditions.push(`[System.Tags] Contains '${escapeWiql(tag)}'`);
       }
     }
-    conditions.push(`[System.TeamProject] = '${escapeWiql(this.project)}'`);
+    conditions.push(`[System.TeamProject] = '${escapeWiql(this.wiProject)}'`);
 
     const where = conditions.join(' AND ');
     const top = options.limit ?? 50;
     const wiql = `SELECT [System.Id] FROM WorkItems WHERE ${where} ORDER BY [System.CreatedDate] DESC`;
 
     const output = this.az([
-      'boards', 'query', '--wiql', wiql, ...this.defaultArgs, '--output', 'json',
+      'boards', 'query', '--wiql', wiql, ...this.workItemArgs, '--output', 'json',
     ]);
     const items = parseJson<Array<{ id: number; fields?: Record<string, unknown> }>>(output);
 
@@ -94,7 +125,7 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
 
   async getWorkItem(id: number): Promise<WorkItem> {
     const output = this.az([
-      'boards', 'work-item', 'show', '--id', String(id), ...this.defaultArgs, '--output', 'json',
+      'boards', 'work-item', 'show', '--id', String(id), ...this.workItemArgs, '--output', 'json',
     ]);
     const wi = parseJson<{
       id: number;
@@ -119,8 +150,8 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     };
   }
 
-  async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string }): Promise<WorkItem> {
-    const wiType = options.type ?? 'User Story';
+  async createWorkItem(options: { title: string; description?: string; tags?: string[]; assignedTo?: string; type?: string; areaPath?: string; iterationPath?: string }): Promise<WorkItem> {
+    const wiType = options.type ?? this.workItemConfig?.defaultWorkItemType ?? 'User Story';
     const fields: string[] = [
       `System.Title=${options.title}`,
     ];
@@ -133,9 +164,19 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     if (options.assignedTo) {
       fields.push(`System.AssignedTo=${options.assignedTo}`);
     }
+    // Area path: explicit > config > omit (uses project default)
+    const areaPath = options.areaPath ?? this.workItemConfig?.areaPath;
+    if (areaPath) {
+      fields.push(`System.AreaPath=${areaPath}`);
+    }
+    // Iteration path: explicit > config > omit (uses project default)
+    const iterationPath = options.iterationPath ?? this.workItemConfig?.iterationPath;
+    if (iterationPath) {
+      fields.push(`System.IterationPath=${iterationPath}`);
+    }
 
     const output = this.az([
-      'boards', 'work-item', 'create', '--type', wiType, '--fields', ...fields, ...this.defaultArgs, '--output', 'json',
+      'boards', 'work-item', 'create', '--type', wiType, '--fields', ...fields, ...this.workItemArgs, '--output', 'json',
     ]);
     const created = parseJson<{
       id: number;
@@ -166,7 +207,7 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     const tagsStr = currentTags.join('; ');
     this.az([
       'boards', 'work-item', 'update', '--id', String(workItemId),
-      '--fields', `System.Tags=${tagsStr}`, ...this.defaultArgs, '--output', 'json',
+      '--fields', `System.Tags=${tagsStr}`, ...this.workItemArgs, '--output', 'json',
     ]);
   }
 
@@ -176,14 +217,14 @@ export class AzureDevOpsAdapter implements PlatformAdapter {
     const tagsStr = updatedTags.join('; ');
     this.az([
       'boards', 'work-item', 'update', '--id', String(workItemId),
-      '--fields', `System.Tags=${tagsStr}`, ...this.defaultArgs, '--output', 'json',
+      '--fields', `System.Tags=${tagsStr}`, ...this.workItemArgs, '--output', 'json',
     ]);
   }
 
   async addComment(workItemId: number, comment: string): Promise<void> {
     this.az([
       'boards', 'work-item', 'update', '--id', String(workItemId),
-      '--discussion', comment, ...this.defaultArgs, '--output', 'json',
+      '--discussion', comment, ...this.workItemArgs, '--output', 'json',
     ]);
   }
 
diff --git a/packages/squad-sdk/src/platform/index.ts b/packages/squad-sdk/src/platform/index.ts
index 635e83f6..e4743eb8 100644
--- a/packages/squad-sdk/src/platform/index.ts
+++ b/packages/squad-sdk/src/platform/index.ts
@@ -9,14 +9,34 @@ export type { GitHubRemoteInfo, AzureDevOpsRemoteInfo } from './detect.js';
 export { detectPlatform, detectPlatformFromUrl, detectWorkItemSource, parseGitHubRemote, parseAzureDevOpsRemote, getRemoteUrl } from './detect.js';
 export { GitHubAdapter } from './github.js';
 export { AzureDevOpsAdapter } from './azure-devops.js';
+export type { AdoWorkItemConfig } from './azure-devops.js';
 export { PlannerAdapter, mapPlannerTaskToWorkItem } from './planner.js';
 export { getRalphScanCommands } from './ralph-commands.js';
 export type { RalphCommands } from './ralph-commands.js';
 
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import type { PlatformAdapter } from './types.js';
 import { detectPlatform, getRemoteUrl, parseGitHubRemote, parseAzureDevOpsRemote } from './detect.js';
 import { GitHubAdapter } from './github.js';
 import { AzureDevOpsAdapter } from './azure-devops.js';
+import type { AdoWorkItemConfig } from './azure-devops.js';
+
+/**
+ * Read ADO work item config from .squad/config.json if present.
+ */
+function readAdoConfig(repoRoot: string): AdoWorkItemConfig | undefined {
+  const configPath = join(repoRoot, '.squad', 'config.json');
+  if (!existsSync(configPath)) return undefined;
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (parsed.ado && typeof parsed.ado === 'object') {
+      return parsed.ado as AdoWorkItemConfig;
+    }
+  } catch { /* ignore parse errors */ }
+  return undefined;
+}
 
 /**
  * Create a platform adapter by auto-detecting the platform from the repo's git remote.
@@ -35,7 +55,8 @@ export function createPlatformAdapter(repoRoot: string): PlatformAdapter {
     if (!info) {
       throw new Error(`Could not parse Azure DevOps remote URL: ${remoteUrl}`);
     }
-    return new AzureDevOpsAdapter(info.org, info.project, info.repo);
+    const adoConfig = readAdoConfig(repoRoot);
+    return new AzureDevOpsAdapter(info.org, info.project, info.repo, adoConfig);
   }
 
   const info = parseGitHubRemote(remoteUrl);
diff --git a/test/platform-adapter.test.ts b/test/platform-adapter.test.ts
index 2e12fcd2..495c20c0 100644
--- a/test/platform-adapter.test.ts
+++ b/test/platform-adapter.test.ts
@@ -679,3 +679,68 @@ describe('getRalphScanCommands planner', () => {
     expect(cmds.createWorkItem).toContain('{title}');
   });
 });
+
+// ─── ADO Work Item Config ─────────────────────────────────────────────
+
+describe('AzureDevOpsAdapter work item config', () => {
+  // We can't call the adapter directly (needs az CLI), but we test the
+  // exported interface and constructor shape via the type system + factory.
+
+  it('AdoWorkItemConfig type is exported from platform index', async () => {
+    const mod = await import('../packages/squad-sdk/src/platform/index.js');
+    // The type is export-only (interface), but AzureDevOpsAdapter is exported as a class
+    expect(mod.AzureDevOpsAdapter).toBeDefined();
+  });
+
+  it('AzureDevOpsAdapter constructor accepts 4th workItemConfig param', async () => {
+    // Type-level test: verify the constructor accepts the config without ts errors.
+    // We can't actually call it (needs az CLI), but we verify the signature exists.
+    const { AzureDevOpsAdapter: AdoCtor } = await import('../packages/squad-sdk/src/platform/azure-devops.js');
+    expect(AdoCtor).toBeDefined();
+    expect(AdoCtor.length).toBeGreaterThanOrEqual(3); // at least 3 required params
+  });
+
+  it('readAdoConfig returns undefined when no config file exists', async () => {
+    // createPlatformAdapter reads .squad/config.json — test that a non-ADO repo works
+    const { createPlatformAdapter } = await import('../packages/squad-sdk/src/platform/index.js');
+    expect(createPlatformAdapter).toBeDefined();
+  });
+});
+
+describe('ADO config.json ado section schema', () => {
+  it('all AdoWorkItemConfig fields are optional', () => {
+    // Empty object is valid — all fields fall back to defaults
+    const config: import('../packages/squad-sdk/src/platform/azure-devops.js').AdoWorkItemConfig = {};
+    expect(config.org).toBeUndefined();
+    expect(config.project).toBeUndefined();
+    expect(config.defaultWorkItemType).toBeUndefined();
+    expect(config.areaPath).toBeUndefined();
+    expect(config.iterationPath).toBeUndefined();
+  });
+
+  it('accepts full ADO config with all fields', () => {
+    const config: import('../packages/squad-sdk/src/platform/azure-devops.js').AdoWorkItemConfig = {
+      org: 'contoso',
+      project: 'WorkItems',
+      defaultWorkItemType: 'Scenario',
+      areaPath: 'WorkItems\\Team Alpha',
+      iterationPath: 'WorkItems\\Sprint 5',
+    };
+    expect(config.org).toBe('contoso');
+    expect(config.project).toBe('WorkItems');
+    expect(config.defaultWorkItemType).toBe('Scenario');
+    expect(config.areaPath).toBe('WorkItems\\Team Alpha');
+    expect(config.iterationPath).toBe('WorkItems\\Sprint 5');
+  });
+
+  it('supports cross-project config (repo and work items in different projects)', () => {
+    // This is the critical enterprise scenario
+    const config: import('../packages/squad-sdk/src/platform/azure-devops.js').AdoWorkItemConfig = {
+      org: 'enterprise-org',
+      project: 'planning-project',  // work items here
+      // repo lives in 'engineering-project' — parsed from git remote
+    };
+    expect(config.org).toBe('enterprise-org');
+    expect(config.project).toBe('planning-project');
+  });
+});

From 9584557a518581bf6d37b0847c28297eba98f919 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 14:55:54 +0200
Subject: [PATCH 12/15] =?UTF-8?q?docs:=20add=20blog=20post=20#023=20?=
 =?UTF-8?q?=E2=80=94=20Squad=20Goes=20Enterprise=20(ADO=20support)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Covers auto-detection, configurable work item types, area/iteration paths,
cross-project work items, security hardening, and integration test results.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../023-squad-goes-enterprise-azure-devops.md | 214 ++++++++++++++++++
 1 file changed, 214 insertions(+)
 create mode 100644 docs/blog/023-squad-goes-enterprise-azure-devops.md

diff --git a/docs/blog/023-squad-goes-enterprise-azure-devops.md b/docs/blog/023-squad-goes-enterprise-azure-devops.md
new file mode 100644
index 00000000..3d1ed748
--- /dev/null
+++ b/docs/blog/023-squad-goes-enterprise-azure-devops.md
@@ -0,0 +1,214 @@
+---
+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.
+
+## 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)

From 1b5c63fcd632c9db50a135d707f153690ced26c3 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 15:50:46 +0200
Subject: [PATCH 13/15] =?UTF-8?q?fix:=20Ralph=20ADO=20config=20resolution?=
 =?UTF-8?q?=20=E2=80=94=20read=20ado=20section=20from=20.squad/config.json?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ralph's coordinator prompt now explicitly instructs the coordinator to:
1. Read .squad/config.json BEFORE running any ADO work item commands
2. Use ado.org/ado.project for work item queries (may differ from repo)
3. Pass --org and --project flags on every az boards command
4. Use ado.defaultWorkItemType when creating work items
5. Never guess the ADO project from the repo name — read the config

This fixes the issue where Ralph on ADO repos would try the repo name
as the ADO project (e.g. 'squad-ado-test') instead of the actual
configured work item project.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 templates/squad.agent.md | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/templates/squad.agent.md b/templates/squad.agent.md
index cd13bad7..92496b2f 100644
--- a/templates/squad.agent.md
+++ b/templates/squad.agent.md
@@ -973,10 +973,12 @@ If the git remote points to Azure DevOps:
 4. Verify defaults: `az devops configure --list` — org and project must be set
 
 **Ralph on Azure DevOps:**
-- Replace `gh issue list --label "squad:untriaged"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:untriaged'"`
-- Replace `gh issue list --label "squad:{member}"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:{member}'"`
-- Replace `gh pr list` with `az repos pr list`
+- **Read `.squad/config.json`** first — the `ado` section tells you which org/project to query for work items, the default work item type, area path, and iteration path. If `ado.org`/`ado.project` are set, use those (they may differ from the repo's org/project). If not set, fall back to org/project parsed from `git remote get-url origin`.
+- Replace `gh issue list --label "squad:untriaged"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:untriaged' AND [System.TeamProject] = '{project}'" --org "https://dev.azure.com/{org}" --project "{project}"`
+- Replace `gh issue list --label "squad:{member}"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:{member}'" --org ... --project ...`
+- Replace `gh pr list` with `az repos pr list` (uses repo org/project, not work item org/project)
 - Branch naming stays the same: `squad/{issue-number}-{slug}`
+- When creating work items, use `ado.defaultWorkItemType` (default: "User Story"), include `ado.areaPath` and `ado.iterationPath` if configured
 
 ### Microsoft Planner Mode (Hybrid)
 
@@ -1033,6 +1035,8 @@ When Ralph is active, run this check cycle after every batch of agent work compl
 **Step 1 — Scan for work** (run these in parallel):
 
 > **Platform-aware:** Use the commands from the Platform Detection section above. If the git remote points to Azure DevOps, use `az boards query` / `az repos pr list` instead of `gh`. If work items are in Planner, use Graph API. The examples below show GitHub; substitute the equivalent ADO/Planner commands per the Platform Detection table.
+>
+> **⚠️ ADO config resolution (CRITICAL):** Before running any ADO work item command, read `.squad/config.json` and check for an `ado` section. If present, `ado.org` and `ado.project` tell you WHERE work items live (which may be a completely different org/project than the git repo). Pass these as `--org` and `--project` flags on every `az boards` command. If no `ado` section exists, parse org/project from the git remote URL. Do NOT guess the project name from the repo name — read the config.
 
 **GitHub:**
 ```bash
@@ -1050,18 +1054,24 @@ gh pr list --state open --draft --json number,title,author,labels,checks --limit
 ```
 
 **Azure DevOps:**
+
+> **Config-aware:** Before running ADO commands, read `.squad/config.json` for the `ado` section. If `ado.org` and/or `ado.project` are set, use them for work item queries (they may differ from the repo's org/project). Pass `--org https://dev.azure.com/{ado.org}` and `--project {ado.project}` on every `az boards` command. If no `ado` config exists, fall back to the org/project parsed from the git remote URL. Also use `ado.defaultWorkItemType` (default: "User Story") when creating work items.
+
 ```bash
-# Untriaged work items
-az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged' ORDER BY [System.CreatedDate] DESC" --output table
+# Read org/project from .squad/config.json → ado.org, ado.project
+# Fall back to git remote URL parsing if not configured
+
+# Untriaged work items (use configured org/project)
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged' AND [System.TeamProject] = '{project}' ORDER BY [System.CreatedDate] DESC" --org "https://dev.azure.com/{org}" --project "{project}" --output table
 
 # Member-assigned work items
-az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member}' AND [System.State] <> 'Closed' ORDER BY [System.CreatedDate] DESC" --output table
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member}' AND [System.State] <> 'Closed' AND [System.TeamProject] = '{project}' ORDER BY [System.CreatedDate] DESC" --org "https://dev.azure.com/{org}" --project "{project}" --output table
 
-# Open PRs
+# Open PRs (always uses repo org/project, NOT work item org/project)
 az repos pr list --status active --output table
 
-# Create a work item
-az boards work-item create --type "User Story" --title "{title}" --fields "System.Tags=squad; squad:untriaged"
+# Create a work item (uses configured type, area path, iteration path)
+az boards work-item create --type "{ado.defaultWorkItemType}" --title "{title}" --fields "System.Tags=squad; squad:untriaged" --org "https://dev.azure.com/{org}" --project "{project}"
 ```
 
 **Step 2 — Categorize findings:**

From b34c4d79da81e652c121bc70c1582db9c61e699a Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 15:57:21 +0200
Subject: [PATCH 14/15] fix: add ADO platform awareness to governance file
 (squad.agent.md)

The governance file (.github/agents/squad.agent.md) that controls the
coordinator at runtime had ZERO Azure DevOps awareness. Ralph only knew
GitHub commands (gh issue list, gh pr list). Even with a perfect ADO
adapter, Ralph would still scan GitHub because the governance file
told it to.

Changes to .github/agents/squad.agent.md:
- Add azure-devops-* to MCP tool detection table
- Add Platform Detection section (GitHub vs ADO vs Planner)
- Add ADO config resolution from .squad/config.json ado section
- Make Issue Awareness section platform-aware (GitHub + ADO queries)
- Make Ralph Step 1 platform-aware with both GitHub and ADO command
  blocks, plus critical instruction to read config first
- Update merge PR trigger to include ADO equivalent

Also updated blog post #023 with 'Ralph + ADO: The Governance Fix'
section explaining why this class of bug is invisible in unit tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/agents/squad.agent.md                 | 91 ++++++++++++++++++-
 .../023-squad-goes-enterprise-azure-devops.md | 12 +++
 2 files changed, 101 insertions(+), 2 deletions(-)

diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 2c416dec..44ec3c0b 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -114,12 +114,18 @@ When triggered:
 
 ### Issue Awareness
 
-**On every session start (after resolving team root):** Check for open GitHub issues assigned to squad members via labels. Use the GitHub CLI or API to list issues with `squad:*` labels:
+**On every session start (after resolving team root):** Check for open issues/work items assigned to squad members. Detect the platform first:
 
+**GitHub:** Use `gh` CLI or GitHub MCP tools:
 ```
 gh issue list --label "squad:{member-name}" --state open --json number,title,labels,body --limit 10
 ```
 
+**Azure DevOps:** Read `.squad/config.json` for `ado.org`/`ado.project`, then use WIQL:
+```
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member-name}' AND [System.State] <> 'Closed' AND [System.TeamProject] = '{project}'" --org "https://dev.azure.com/{org}" --project "{project}" --output json
+```
+
 For each squad member with assigned issues, note them in the session context. When presenting a catch-up or when the user asks for status, include pending issues:
 
 ```
@@ -455,6 +461,7 @@ MCP (Model Context Protocol) servers extend Squad with tools for external servic
 
 At task start, scan your available tools list for known MCP prefixes:
 - `github-mcp-server-*` → GitHub API (issues, PRs, code search, actions)
+- `azure-devops-*` → Azure DevOps API (work items, repos, PRs, pipelines, wiki)
 - `trello_*` → Trello boards, cards, lists
 - `aspire_*` → Aspire dashboard (metrics, logs, health)
 - `azure_*` → Azure resource management
@@ -946,6 +953,65 @@ Before connecting to a GitHub repository, verify that the `gh` CLI is available
 
 ---
 
+## Platform Detection
+
+On session start, detect the platform from git remote:
+- `github.com` → Use GitHub commands (`gh` CLI)
+- `dev.azure.com` or `*.visualstudio.com` → Use Azure DevOps commands (`az` CLI)
+
+If `squad.config.ts` specifies `workItems: 'planner'`, use Microsoft Planner for work items regardless of where the repo lives.
+
+### Azure DevOps Mode
+
+If the git remote points to Azure DevOps:
+
+| GitHub concept | Azure DevOps equivalent | Command change |
+|---|---|---|
+| `gh issue list` | WIQL query via `az boards query` | `az boards query --wiql "SELECT ... FROM WorkItems WHERE ..."` |
+| `gh pr list` | `az repos pr list` | `az repos pr list --status active` |
+| `gh pr create` | `az repos pr create` | `az repos pr create --source-branch ... --target-branch ...` |
+| `gh pr merge` | `az repos pr update --status completed` | Set PR status to completed |
+| Issue labels | Work Item tags | `az boards work-item update --fields "System.Tags=..."` |
+| `squad:{member}` label | `squad:{member}` tag on work items | Tags use `;` separator |
+
+**Prerequisites for Azure DevOps:**
+1. Run `az --version`. If missing: *"Azure DevOps mode requires the Azure CLI. Install from https://aka.ms/install-az-cli"*
+2. Run `az extension show --name azure-devops`. If missing: *"Run `az extension add --name azure-devops`"*
+3. Run `az account show`. If not logged in: *"Run `az login` to authenticate"*
+4. Verify defaults: `az devops configure --list` — org and project must be set
+
+**ADO Work Item Config (`.squad/config.json`):**
+
+Read the `ado` section from `.squad/config.json` to resolve org, project, work item type, area/iteration paths:
+
+```json
+{
+  "platform": "azure-devops",
+  "ado": {
+    "org": "my-org",
+    "project": "work-items-project",
+    "defaultWorkItemType": "Scenario",
+    "areaPath": "MyProject\\Team Alpha",
+    "iterationPath": "MyProject\\Sprint 5"
+  }
+}
+```
+
+- If `ado.org`/`ado.project` are set, use them for ALL work item operations (they may differ from the repo's org/project)
+- If not set, parse org/project from `git remote get-url origin`
+- Pass `--org https://dev.azure.com/{org} --project {project}` on every `az boards` command
+- Use `ado.defaultWorkItemType` when creating work items (default: "User Story")
+
+**Ralph on Azure DevOps:**
+- **Read `.squad/config.json`** first — the `ado` section tells you which org/project to query for work items
+- Replace `gh issue list --label "squad:untriaged"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:untriaged' AND [System.TeamProject] = '{project}'" --org ... --project ...`
+- Replace `gh issue list --label "squad:{member}"` with WIQL: `az boards query --wiql "SELECT ... WHERE [System.Tags] Contains 'squad:{member}'" --org ... --project ...`
+- Replace `gh pr list` with `az repos pr list` (uses repo org/project, not work item org/project)
+- When creating work items, use `ado.defaultWorkItemType`, include `ado.areaPath` and `ado.iterationPath` if configured
+- Branch naming stays the same: `squad/{issue-number}-{slug}`
+
+---
+
 ## Ralph — Work Monitor
 
 Ralph is a built-in squad member whose job is keeping tabs on work. **Ralph tracks and drives the work queue.** Always on the roster, one job: make sure the team never sits idle.
@@ -970,7 +1036,7 @@ Ralph always appears in `team.md`: `| Ralph | Work Monitor | — | 🔄 Monitor
 | "Ralph, idle" / "Take a break" / "Stop monitoring" | Fully deactivate (stop loop + idle-watch) |
 | "Ralph, scope: just issues" / "Ralph, skip CI" | Adjust what Ralph monitors this session |
 | References PR feedback or changes requested | Spawn agent to address PR review feedback |
-| "merge PR #N" / "merge it" (recent context) | Merge via `gh pr merge` |
+| "merge PR #N" / "merge it" (recent context) | Merge via `gh pr merge` (GitHub) or `az repos pr update --status completed` (ADO) |
 
 These are intent signals, not exact strings — match meaning, not words.
 
@@ -978,6 +1044,9 @@ When Ralph is active, run this check cycle after every batch of agent work compl
 
 **Step 1 — Scan for work** (run these in parallel):
 
+> **Platform-aware:** Detect the platform from git remote. If Azure DevOps, read `.squad/config.json` for the `ado` section FIRST — it tells you which org/project to query for work items (may differ from the repo). Use `az boards query` / `az repos pr list` instead of `gh`. If Planner, use Graph API. Do NOT guess the ADO project from the repo name — read the config.
+
+**GitHub:**
 ```bash
 # Untriaged issues (labeled squad but no squad:{member} sub-label)
 gh issue list --label "squad" --state open --json number,title,labels,assignees --limit 20
@@ -992,6 +1061,24 @@ gh pr list --state open --json number,title,author,labels,isDraft,reviewDecision
 gh pr list --state open --draft --json number,title,author,labels,checks --limit 20
 ```
 
+**Azure DevOps:**
+```bash
+# Read org/project from .squad/config.json → ado.org, ado.project
+# Fall back to git remote URL parsing if not configured
+
+# Untriaged work items
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:untriaged' AND [System.TeamProject] = '{project}' ORDER BY [System.CreatedDate] DESC" --org "https://dev.azure.com/{org}" --project "{project}" --output table
+
+# Member-assigned work items
+az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.Tags] FROM WorkItems WHERE [System.Tags] Contains 'squad:{member}' AND [System.State] <> 'Closed' AND [System.TeamProject] = '{project}' ORDER BY [System.CreatedDate] DESC" --org "https://dev.azure.com/{org}" --project "{project}" --output table
+
+# Open PRs (uses repo org/project, NOT work item org/project)
+az repos pr list --status active --output table
+
+# Create a work item (uses configured type, area path, iteration path)
+az boards work-item create --type "{ado.defaultWorkItemType}" --title "{title}" --fields "System.Tags=squad; squad:untriaged" --org "https://dev.azure.com/{org}" --project "{project}"
+```
+
 **Step 2 — Categorize findings:**
 
 | Category | Signal | Action |
diff --git a/docs/blog/023-squad-goes-enterprise-azure-devops.md b/docs/blog/023-squad-goes-enterprise-azure-devops.md
index 3d1ed748..1f9d77fb 100644
--- a/docs/blog/023-squad-goes-enterprise-azure-devops.md
+++ b/docs/blog/023-squad-goes-enterprise-azure-devops.md
@@ -178,6 +178,18 @@ 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

From 767b315929e1d26a071a62a926c2e64cbabb3d27 Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@gmail.com>
Date: Sat, 7 Mar 2026 22:26:06 +0200
Subject: [PATCH 15/15] =?UTF-8?q?feat:=20CommunicationAdapter=20=E2=80=94?=
 =?UTF-8?q?=20platform-agnostic=20agent-human=20communication=20(#261)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add CommunicationAdapter interface to the platform layer for pluggable
agent-human communication across platforms.

Interface:
- postUpdate(title, body, category, author) → { id, url }
- pollForReplies(threadId, since) → CommunicationReply[]
- getNotificationUrl(threadId) → string | undefined

Adapters:
- FileLogCommunicationAdapter — zero-config fallback, writes to .squad/comms/
- GitHubDiscussionsCommunicationAdapter — uses gh api GraphQL
- ADODiscussionCommunicationAdapter — uses az boards CLI
- (Teams webhook adapter stubbed, falls back to FileLog)

Factory:
- createCommunicationAdapter(repoRoot) — auto-detects platform, reads
  config from .squad/config.json communications section, falls back
  to FileLog if nothing configured

Tests: 15 new tests (interface contracts, FileLog adapter, exports)

Addresses #261

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../src/platform/comms-ado-discussions.ts     | 114 ++++++++++++
 .../squad-sdk/src/platform/comms-file-log.ts  |  86 +++++++++
 .../src/platform/comms-github-discussions.ts  |  95 ++++++++++
 packages/squad-sdk/src/platform/comms.ts      | 110 +++++++++++
 packages/squad-sdk/src/platform/index.ts      |   6 +-
 packages/squad-sdk/src/platform/types.ts      |  64 +++++++
 test/communication-adapter.test.ts            | 173 ++++++++++++++++++
 7 files changed, 647 insertions(+), 1 deletion(-)
 create mode 100644 packages/squad-sdk/src/platform/comms-ado-discussions.ts
 create mode 100644 packages/squad-sdk/src/platform/comms-file-log.ts
 create mode 100644 packages/squad-sdk/src/platform/comms-github-discussions.ts
 create mode 100644 packages/squad-sdk/src/platform/comms.ts
 create mode 100644 test/communication-adapter.test.ts

diff --git a/packages/squad-sdk/src/platform/comms-ado-discussions.ts b/packages/squad-sdk/src/platform/comms-ado-discussions.ts
new file mode 100644
index 00000000..9c5728f5
--- /dev/null
+++ b/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}`;
+  }
+}
diff --git a/packages/squad-sdk/src/platform/comms-file-log.ts b/packages/squad-sdk/src/platform/comms-file-log.ts
new file mode 100644
index 00000000..bcf45bb8
--- /dev/null
+++ b/packages/squad-sdk/src/platform/comms-file-log.ts
@@ -0,0 +1,86 @@
+/**
+ * File-based communication adapter — zero-config fallback.
+ *
+ * Writes updates to `.squad/comms/` as markdown files.
+ * Always available, no external dependencies. Works on every platform.
+ * Replies are read from the same directory (humans edit files manually or via git).
+ *
+ * @module platform/comms-file-log
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CommunicationAdapter, CommunicationChannel, CommunicationReply } from './types.js';
+
+export class FileLogCommunicationAdapter implements CommunicationAdapter {
+  readonly channel: CommunicationChannel = 'file-log';
+  private readonly commsDir: string;
+
+  constructor(private readonly squadRoot: string) {
+    this.commsDir = join(squadRoot, '.squad', 'comms');
+    if (!existsSync(this.commsDir)) {
+      mkdirSync(this.commsDir, { recursive: true });
+    }
+  }
+
+  async postUpdate(options: {
+    title: string;
+    body: string;
+    category?: string;
+    author?: string;
+  }): Promise<{ id: string; url?: string }> {
+    const timestamp = new Date().toISOString().replace(/:/g, '-').replace(/\.\d+Z$/, 'Z');
+    const slug = options.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 40);
+    const filename = `${timestamp}-${slug}.md`;
+    const filepath = join(this.commsDir, filename);
+
+    const content = [
+      `# ${options.title}`,
+      '',
+      `**Posted by:** ${options.author ?? 'Squad'}`,
+      `**Category:** ${options.category ?? 'update'}`,
+      `**Timestamp:** ${new Date().toISOString()}`,
+      '',
+      '---',
+      '',
+      options.body,
+      '',
+      '---',
+      '',
+      '<!-- Replies: add your response below this line -->',
+      '',
+    ].join('\n');
+
+    writeFileSync(filepath, content, 'utf-8');
+
+    return { id: filename.replace(/\.md$/, ''), url: undefined };
+  }
+
+  async pollForReplies(options: {
+    threadId: string;
+    since: Date;
+  }): Promise<CommunicationReply[]> {
+    const filepath = join(this.commsDir, `${options.threadId}.md`);
+    if (!existsSync(filepath)) return [];
+
+    const content = readFileSync(filepath, 'utf-8');
+    const replyMarker = '<!-- Replies: add your response below this line -->';
+    const markerIdx = content.indexOf(replyMarker);
+    if (markerIdx === -1) return [];
+
+    const repliesSection = content.slice(markerIdx + replyMarker.length).trim();
+    if (!repliesSection) return [];
+
+    // Parse simple reply format: lines after the marker are replies
+    return [{
+      author: 'human',
+      body: repliesSection,
+      timestamp: new Date(),
+      id: `${options.threadId}-reply`,
+    }];
+  }
+
+  getNotificationUrl(_threadId: string): string | undefined {
+    return undefined; // File-based has no web UI
+  }
+}
diff --git a/packages/squad-sdk/src/platform/comms-github-discussions.ts b/packages/squad-sdk/src/platform/comms-github-discussions.ts
new file mode 100644
index 00000000..1b4576e3
--- /dev/null
+++ b/packages/squad-sdk/src/platform/comms-github-discussions.ts
@@ -0,0 +1,95 @@
+/**
+ * GitHub Discussions communication adapter.
+ *
+ * Posts updates and reads replies via GitHub Discussions using `gh api`.
+ * Phone-capable (browser-based), not corp-only.
+ *
+ * @module platform/comms-github-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 GitHubDiscussionsCommunicationAdapter implements CommunicationAdapter {
+  readonly channel: CommunicationChannel = 'github-discussions';
+
+  constructor(
+    private readonly owner: string,
+    private readonly repo: string,
+  ) {}
+
+  async postUpdate(options: {
+    title: string;
+    body: string;
+    category?: string;
+    author?: string;
+  }): Promise<{ id: string; url?: string }> {
+    const category = options.category ?? 'General';
+
+    // Get category ID
+    const categoryQuery = `query { repository(owner: "${this.owner}", name: "${this.repo}") { discussionCategories(first: 25) { nodes { id name } } } }`;
+    const catOutput = execFileSync('gh', ['api', 'graphql', '-f', `query=${categoryQuery}`], EXEC_OPTS);
+    const catData = parseJson<{
+      data: { repository: { discussionCategories: { nodes: Array<{ id: string; name: string }> } } }
+    }>(catOutput);
+
+    const catNode = catData.data.repository.discussionCategories.nodes.find(
+      (n) => n.name.toLowerCase() === category.toLowerCase(),
+    );
+    if (!catNode) {
+      throw new Error(`Discussion category "${category}" not found in ${this.owner}/${this.repo}. Available: ${catData.data.repository.discussionCategories.nodes.map((n) => n.name).join(', ')}`);
+    }
+
+    // Get repo ID
+    const repoQuery = `query { repository(owner: "${this.owner}", name: "${this.repo}") { id } }`;
+    const repoOutput = execFileSync('gh', ['api', 'graphql', '-f', `query=${repoQuery}`], EXEC_OPTS);
+    const repoData = parseJson<{ data: { repository: { id: string } } }>(repoOutput);
+
+    // Create discussion
+    const prefix = options.author ? `*Posted by ${options.author}*\n\n` : '';
+    const mutation = `mutation { createDiscussion(input: { repositoryId: "${repoData.data.repository.id}", categoryId: "${catNode.id}", title: "${options.title.replace(/"/g, '\\"')}", body: "${(prefix + options.body).replace(/"/g, '\\"').replace(/\n/g, '\\n')}" }) { discussion { id number url } } }`;
+    const output = execFileSync('gh', ['api', 'graphql', '-f', `query=${mutation}`], EXEC_OPTS);
+    const result = parseJson<{
+      data: { createDiscussion: { discussion: { id: string; number: number; url: string } } }
+    }>(output);
+
+    const disc = result.data.createDiscussion.discussion;
+    return { id: String(disc.number), url: disc.url };
+  }
+
+  async pollForReplies(options: {
+    threadId: string;
+    since: Date;
+  }): Promise<CommunicationReply[]> {
+    const query = `query { repository(owner: "${this.owner}", name: "${this.repo}") { discussion(number: ${options.threadId}) { comments(first: 50) { nodes { id body createdAt author { login } } } } } }`;
+    const output = execFileSync('gh', ['api', 'graphql', '-f', `query=${query}`], EXEC_OPTS);
+    const data = parseJson<{
+      data: { repository: { discussion: { comments: { nodes: Array<{ id: string; body: string; createdAt: string; author: { login: string } }> } } } }
+    }>(output);
+
+    const comments = data.data.repository.discussion.comments.nodes;
+    return comments
+      .filter((c) => new Date(c.createdAt) > options.since)
+      .map((c) => ({
+        author: c.author.login,
+        body: c.body,
+        timestamp: new Date(c.createdAt),
+        id: c.id,
+      }));
+  }
+
+  getNotificationUrl(threadId: string): string | undefined {
+    return `https://github.com/${this.owner}/${this.repo}/discussions/${threadId}`;
+  }
+}
diff --git a/packages/squad-sdk/src/platform/comms.ts b/packages/squad-sdk/src/platform/comms.ts
new file mode 100644
index 00000000..eae95083
--- /dev/null
+++ b/packages/squad-sdk/src/platform/comms.ts
@@ -0,0 +1,110 @@
+/**
+ * Communication adapter factory — creates the right adapter based on config.
+ *
+ * Reads `.squad/config.json` for the `communications` section.
+ * Falls back to FileLog (always available) if nothing is configured.
+ *
+ * @module platform/comms
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { CommunicationAdapter, CommunicationChannel, CommunicationConfig } from './types.js';
+import { FileLogCommunicationAdapter } from './comms-file-log.js';
+import { GitHubDiscussionsCommunicationAdapter } from './comms-github-discussions.js';
+import { ADODiscussionCommunicationAdapter } from './comms-ado-discussions.js';
+import { detectPlatform, getRemoteUrl, parseGitHubRemote, parseAzureDevOpsRemote } from './detect.js';
+
+/**
+ * Read communication config from `.squad/config.json`.
+ */
+function readCommsConfig(repoRoot: string): CommunicationConfig | undefined {
+  const configPath = join(repoRoot, '.squad', 'config.json');
+  if (!existsSync(configPath)) return undefined;
+  try {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (parsed.communications && typeof parsed.communications === 'object') {
+      return parsed.communications as CommunicationConfig;
+    }
+  } catch { /* ignore */ }
+  return undefined;
+}
+
+/**
+ * Create a communication adapter based on config or auto-detection.
+ *
+ * Priority:
+ * 1. Explicit config in `.squad/config.json` → `communications.channel`
+ * 2. Auto-detect from platform: GitHub → GitHubDiscussions, ADO → ADOWorkItemDiscussions
+ * 3. Fallback: FileLog (always works)
+ */
+export function createCommunicationAdapter(repoRoot: string): CommunicationAdapter {
+  const config = readCommsConfig(repoRoot);
+
+  // Explicit config wins
+  if (config?.channel) {
+    return createAdapterByChannel(config.channel, repoRoot);
+  }
+
+  // Auto-detect from platform
+  const platform = detectPlatform(repoRoot);
+  const remoteUrl = getRemoteUrl(repoRoot);
+
+  if (platform === 'github' && remoteUrl) {
+    const info = parseGitHubRemote(remoteUrl);
+    if (info) {
+      return new GitHubDiscussionsCommunicationAdapter(info.owner, info.repo);
+    }
+  }
+
+  if (platform === 'azure-devops' && remoteUrl) {
+    const info = parseAzureDevOpsRemote(remoteUrl);
+    if (info) {
+      // Read ADO config for org/project override
+      const configPath = join(repoRoot, '.squad', 'config.json');
+      let adoOrg = info.org;
+      let adoProject = info.project;
+      if (existsSync(configPath)) {
+        try {
+          const raw = readFileSync(configPath, 'utf-8');
+          const parsed = JSON.parse(raw) as Record<string, unknown>;
+          const ado = parsed.ado as Record<string, unknown> | undefined;
+          if (ado?.org && typeof ado.org === 'string') adoOrg = ado.org;
+          if (ado?.project && typeof ado.project === 'string') adoProject = ado.project;
+        } catch { /* ignore */ }
+      }
+      return new ADODiscussionCommunicationAdapter(adoOrg, adoProject);
+    }
+  }
+
+  // Fallback: file-based logging (always available)
+  return new FileLogCommunicationAdapter(repoRoot);
+}
+
+function createAdapterByChannel(channel: CommunicationChannel, repoRoot: string): CommunicationAdapter {
+  const remoteUrl = getRemoteUrl(repoRoot);
+
+  switch (channel) {
+    case 'github-discussions': {
+      if (!remoteUrl) throw new Error('No git remote — cannot create GitHub Discussions adapter');
+      const info = parseGitHubRemote(remoteUrl);
+      if (!info) throw new Error(`Cannot parse GitHub remote: ${remoteUrl}`);
+      return new GitHubDiscussionsCommunicationAdapter(info.owner, info.repo);
+    }
+    case 'ado-work-items': {
+      if (!remoteUrl) throw new Error('No git remote — cannot create ADO Discussions adapter');
+      const info = parseAzureDevOpsRemote(remoteUrl);
+      if (!info) throw new Error(`Cannot parse ADO remote: ${remoteUrl}`);
+      return new ADODiscussionCommunicationAdapter(info.org, info.project);
+    }
+    case 'teams-webhook':
+      // Teams webhook adapter would go here — for now fall back to file log
+      console.warn('Teams webhook adapter not yet implemented — using file log fallback');
+      return new FileLogCommunicationAdapter(repoRoot);
+    case 'file-log':
+      return new FileLogCommunicationAdapter(repoRoot);
+    default:
+      return new FileLogCommunicationAdapter(repoRoot);
+  }
+}
diff --git a/packages/squad-sdk/src/platform/index.ts b/packages/squad-sdk/src/platform/index.ts
index e4743eb8..6fa0933d 100644
--- a/packages/squad-sdk/src/platform/index.ts
+++ b/packages/squad-sdk/src/platform/index.ts
@@ -4,7 +4,7 @@
  * @module platform
  */
 
-export type { PlatformType, WorkItem, PullRequest, PlatformAdapter, WorkItemSource, HybridPlatformConfig } from './types.js';
+export type { PlatformType, WorkItem, PullRequest, PlatformAdapter, WorkItemSource, HybridPlatformConfig, CommunicationChannel, CommunicationReply, CommunicationConfig, CommunicationAdapter } from './types.js';
 export type { GitHubRemoteInfo, AzureDevOpsRemoteInfo } from './detect.js';
 export { detectPlatform, detectPlatformFromUrl, detectWorkItemSource, parseGitHubRemote, parseAzureDevOpsRemote, getRemoteUrl } from './detect.js';
 export { GitHubAdapter } from './github.js';
@@ -13,6 +13,10 @@ export type { AdoWorkItemConfig } from './azure-devops.js';
 export { PlannerAdapter, mapPlannerTaskToWorkItem } from './planner.js';
 export { getRalphScanCommands } from './ralph-commands.js';
 export type { RalphCommands } from './ralph-commands.js';
+export { FileLogCommunicationAdapter } from './comms-file-log.js';
+export { GitHubDiscussionsCommunicationAdapter } from './comms-github-discussions.js';
+export { ADODiscussionCommunicationAdapter } from './comms-ado-discussions.js';
+export { createCommunicationAdapter } from './comms.js';
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
diff --git a/packages/squad-sdk/src/platform/types.ts b/packages/squad-sdk/src/platform/types.ts
index 8371d57a..1bc6ca63 100644
--- a/packages/squad-sdk/src/platform/types.ts
+++ b/packages/squad-sdk/src/platform/types.ts
@@ -63,3 +63,67 @@ export interface PlatformAdapter {
   // Branches
   createBranch(name: string, fromBranch?: string): Promise<void>;
 }
+
+// ─── Communication Adapter ────────────────────────────────────────────
+
+/** Where communication happens — which channel/service */
+export type CommunicationChannel = 'github-discussions' | 'ado-work-items' | 'teams-webhook' | 'file-log';
+
+/** A reply from a human on a communication channel */
+export interface CommunicationReply {
+  author: string;
+  body: string;
+  timestamp: Date;
+  /** Platform-specific identifier for the reply */
+  id: string;
+}
+
+/** Configuration for a communication channel */
+export interface CommunicationConfig {
+  channel: CommunicationChannel;
+  /** Post session summaries after agent work */
+  postAfterSession?: boolean;
+  /** Post decisions that need human review */
+  postDecisions?: boolean;
+  /** Post escalations when agents are blocked */
+  postEscalations?: boolean;
+}
+
+/**
+ * Communication adapter interface — pluggable agent-human communication.
+ *
+ * Abstracts the communication channel so Squad can post updates and read
+ * replies from GitHub Discussions, ADO Work Item discussions, Teams, or
+ * plain log files — depending on what the user has configured.
+ */
+export interface CommunicationAdapter {
+  readonly channel: CommunicationChannel;
+
+  /**
+   * Post an update to the communication channel.
+   * Used by Scribe (session summaries), Ralph (board status), and agents (escalations).
+   */
+  postUpdate(options: {
+    title: string;
+    body: string;
+    category?: string;
+    /** Agent or role posting the update */
+    author?: string;
+  }): Promise<{ id: string; url?: string }>;
+
+  /**
+   * Poll for replies since a given timestamp.
+   * Returns new replies from humans on the channel.
+   */
+  pollForReplies(options: {
+    /** Thread/discussion ID to check for replies */
+    threadId: string;
+    since: Date;
+  }): Promise<CommunicationReply[]>;
+
+  /**
+   * Get a URL that humans can open on any device (phone, browser, desktop).
+   * Returns undefined if the channel has no web UI (e.g., file-log).
+   */
+  getNotificationUrl(threadId: string): string | undefined;
+}
diff --git a/test/communication-adapter.test.ts b/test/communication-adapter.test.ts
new file mode 100644
index 00000000..f9aaa8ef
--- /dev/null
+++ b/test/communication-adapter.test.ts
@@ -0,0 +1,173 @@
+/**
+ * Communication adapter tests — interface contracts, factory, FileLog adapter.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { CommunicationAdapter, CommunicationChannel, CommunicationReply, CommunicationConfig } from '../packages/squad-sdk/src/platform/types.js';
+import { FileLogCommunicationAdapter } from '../packages/squad-sdk/src/platform/comms-file-log.js';
+
+const TEST_ROOT = join(__dirname, '..', 'test-fixtures', 'comms-test');
+
+describe('CommunicationAdapter interface', () => {
+  it('CommunicationChannel includes all expected values', () => {
+    const channels: CommunicationChannel[] = ['github-discussions', 'ado-work-items', 'teams-webhook', 'file-log'];
+    expect(channels).toHaveLength(4);
+  });
+
+  it('CommunicationReply has required fields', () => {
+    const reply: CommunicationReply = {
+      author: 'tamir',
+      body: 'Looks good!',
+      timestamp: new Date(),
+      id: 'reply-1',
+    };
+    expect(reply.author).toBe('tamir');
+    expect(reply.body).toBe('Looks good!');
+    expect(reply.id).toBe('reply-1');
+  });
+
+  it('CommunicationConfig has correct shape', () => {
+    const config: CommunicationConfig = {
+      channel: 'github-discussions',
+      postAfterSession: true,
+      postDecisions: true,
+      postEscalations: false,
+    };
+    expect(config.channel).toBe('github-discussions');
+    expect(config.postAfterSession).toBe(true);
+  });
+});
+
+describe('FileLogCommunicationAdapter', () => {
+  let adapter: FileLogCommunicationAdapter;
+
+  beforeEach(() => {
+    if (existsSync(TEST_ROOT)) rmSync(TEST_ROOT, { recursive: true });
+    mkdirSync(join(TEST_ROOT, '.squad'), { recursive: true });
+    adapter = new FileLogCommunicationAdapter(TEST_ROOT);
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_ROOT)) rmSync(TEST_ROOT, { recursive: true });
+  });
+
+  it('has channel type file-log', () => {
+    expect(adapter.channel).toBe('file-log');
+  });
+
+  it('creates comms directory on construction', () => {
+    expect(existsSync(join(TEST_ROOT, '.squad', 'comms'))).toBe(true);
+  });
+
+  it('postUpdate creates a markdown file', async () => {
+    const result = await adapter.postUpdate({
+      title: 'Session Summary',
+      body: 'Completed auth module refactoring',
+      category: 'standup',
+      author: 'Scribe',
+    });
+
+    expect(result.id).toBeTruthy();
+    expect(result.url).toBeUndefined(); // file-based has no URL
+
+    const commsDir = join(TEST_ROOT, '.squad', 'comms');
+    const files = require('fs').readdirSync(commsDir);
+    expect(files.length).toBe(1);
+    expect(files[0]).toMatch(/\.md$/);
+
+    const content = readFileSync(join(commsDir, files[0]), 'utf-8');
+    expect(content).toContain('# Session Summary');
+    expect(content).toContain('Completed auth module refactoring');
+    expect(content).toContain('Scribe');
+    expect(content).toContain('standup');
+  });
+
+  it('postUpdate uses default category and author when not provided', async () => {
+    await adapter.postUpdate({
+      title: 'Quick Update',
+      body: 'Something happened',
+    });
+
+    const commsDir = join(TEST_ROOT, '.squad', 'comms');
+    const files = require('fs').readdirSync(commsDir);
+    const content = readFileSync(join(commsDir, files[0]), 'utf-8');
+    expect(content).toContain('Squad');
+    expect(content).toContain('update');
+  });
+
+  it('pollForReplies returns empty when no thread exists', async () => {
+    const replies = await adapter.pollForReplies({
+      threadId: 'nonexistent',
+      since: new Date(),
+    });
+    expect(replies).toEqual([]);
+  });
+
+  it('pollForReplies reads replies from thread file', async () => {
+    const result = await adapter.postUpdate({
+      title: 'Need Input',
+      body: 'Should we use REST or GraphQL?',
+    });
+
+    // Simulate human reply by appending to the file
+    const commsDir = join(TEST_ROOT, '.squad', 'comms');
+    const filepath = join(commsDir, `${result.id}.md`);
+    const content = readFileSync(filepath, 'utf-8');
+    writeFileSync(filepath, content + '\nLet\'s go with GraphQL.\n', 'utf-8');
+
+    const replies = await adapter.pollForReplies({
+      threadId: result.id,
+      since: new Date(0),
+    });
+
+    expect(replies.length).toBe(1);
+    expect(replies[0]!.body).toContain('GraphQL');
+  });
+
+  it('getNotificationUrl returns undefined for file-log', () => {
+    expect(adapter.getNotificationUrl('any-id')).toBeUndefined();
+  });
+
+  it('multiple postUpdates create separate files', async () => {
+    await adapter.postUpdate({ title: 'First', body: 'One' });
+    // Small delay to ensure different timestamps
+    await new Promise((r) => setTimeout(r, 10));
+    await adapter.postUpdate({ title: 'Second', body: 'Two' });
+
+    const commsDir = join(TEST_ROOT, '.squad', 'comms');
+    const files = require('fs').readdirSync(commsDir);
+    expect(files.length).toBe(2);
+  });
+});
+
+describe('CommunicationAdapter contract', () => {
+  it('FileLogCommunicationAdapter implements CommunicationAdapter', () => {
+    if (existsSync(TEST_ROOT)) rmSync(TEST_ROOT, { recursive: true });
+    mkdirSync(join(TEST_ROOT, '.squad'), { recursive: true });
+
+    const adapter: CommunicationAdapter = new FileLogCommunicationAdapter(TEST_ROOT);
+    expect(adapter.channel).toBeDefined();
+    expect(typeof adapter.postUpdate).toBe('function');
+    expect(typeof adapter.pollForReplies).toBe('function');
+    expect(typeof adapter.getNotificationUrl).toBe('function');
+
+    rmSync(TEST_ROOT, { recursive: true });
+  });
+
+  it('GitHubDiscussionsCommunicationAdapter exports correctly', async () => {
+    const mod = await import('../packages/squad-sdk/src/platform/comms-github-discussions.js');
+    expect(mod.GitHubDiscussionsCommunicationAdapter).toBeDefined();
+  });
+
+  it('ADODiscussionCommunicationAdapter exports correctly', async () => {
+    const mod = await import('../packages/squad-sdk/src/platform/comms-ado-discussions.js');
+    expect(mod.ADODiscussionCommunicationAdapter).toBeDefined();
+  });
+
+  it('createCommunicationAdapter factory exports correctly', async () => {
+    const mod = await import('../packages/squad-sdk/src/platform/comms.js');
+    expect(mod.createCommunicationAdapter).toBeDefined();
+  });
+});