feat: CommunicationAdapter — platform-agnostic agent-human communication by tamirdresher · Pull Request #263 · bradygaster/squad

tamirdresher · 2026-03-07T20:27:07Z

feat: CommunicationAdapter — platform-agnostic agent-human communication

Summary

Adds a CommunicationAdapter interface to the platform layer, enabling pluggable agent-human communication across GitHub, Azure DevOps, Teams, and file-based logging.

Problem

Squad agents need to communicate with humans (session summaries, decisions, escalations). Currently this is ad-hoc — no unified abstraction. Different platforms have different communication surfaces (GitHub Discussions, ADO Work Item comments, Teams channels).

Related: #261, #242 (Dina/Brady discussion about phone-capable, platform-agnostic comms)

Solution

Interface (`types.ts`)

interface CommunicationAdapter {
  readonly channel: CommunicationChannel;
  postUpdate(options: { title, body, category?, author? }): Promise<{ id, url? }>;
  pollForReplies(options: { threadId, since }): Promise<CommunicationReply[]>;
  getNotificationUrl(threadId): string | undefined;
}

Adapters (4 implementations)

Adapter	Phone-capable	Corp-only	Status
FileLogCommunicationAdapter	Via git	No	Full (zero-config fallback)
GitHubDiscussionsCommunicationAdapter	Yes (browser)	No	Full (uses gh api GraphQL)
ADODiscussionCommunicationAdapter	Yes (ADO mobile)	Depends	Full (uses az boards CLI)
Teams Webhook	Yes (Teams mobile)	Yes	Stubbed (falls back to FileLog)

Factory

createCommunicationAdapter(repoRoot) auto-detects platform and reads .squad/config.json for explicit channel config.

Dependencies

Based on feature/azure-devops-support (PR #191) — depends on ADO adapter types and detect.ts.

Testing

15 new tests — interface contracts, FileLog adapter (post, poll, multi-post), export verification.

Files

packages/squad-sdk/src/platform/types.ts — CommunicationAdapter interface + types
packages/squad-sdk/src/platform/comms-file-log.ts — FileLog adapter
packages/squad-sdk/src/platform/comms-github-discussions.ts — GitHub Discussions adapter
packages/squad-sdk/src/platform/comms-ado-discussions.ts — ADO adapter
packages/squad-sdk/src/platform/comms.ts — Factory + config reader
packages/squad-sdk/src/platform/index.ts — Barrel exports
test/communication-adapter.test.ts — 15 tests

Addresses #261

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>

Remove .squad/.first-run and .squad/config.json that trigger branch guard. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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>

- 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>

Address critical review findings from PR bradygaster#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>

- 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 bradygaster#191 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- 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>

…oject support 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 bradygaster#240 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

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>

…g.json 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>

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 bradygaster#23 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>

…ion (bradygaster#261) 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 bradygaster#261 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher · 2026-03-08T14:38:31Z

@copilot please review this CommunicationAdapter implementation — check the interface design, FileLog adapter tests, and whether the factory auto-detection logic is sound.

Resolve conflicts from squash merge of bradygaster#191 into main. Kept bradygaster#263 communication adapter types (types.ts, index.ts, enterprise-platforms.md). Took main's bug fixes (init.ts case-insensitive matching, github.ts CLI fixes, detect.ts WorkItemSource type, ralph-commands.ts query syntax). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ng (bradygaster#259, bradygaster#260, bradygaster#261, bradygaster#262, bradygaster#263, bradygaster#264) - Add sendMessage/stream/close session trace spans with TTFT events (bradygaster#259) - Enhance tool spans with agent.name, sanitized args, result.length (bradygaster#260) - Wire token usage metrics into StreamingPipeline (bradygaster#261) - Wire agent performance metrics into lifecycle managers (bradygaster#262) - Wire session pool metrics into SquadClient (bradygaster#263) - Wire response latency metrics into StreamingPipeline (bradygaster#264) - Add 54 new tests (otel-metrics, metric-wiring, session-traces) - Build clean, 1940 tests passing across 68 files Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher and others added 12 commits March 8, 2026 15:56

chore: remove .squad runtime files from tracking

b7dbb05

Remove .squad/.first-run and .squad/config.json that trigger branch guard. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher force-pushed the feat/communication-adapter branch from 767b315 to c2550a4 Compare March 8, 2026 14:03

bradygaster merged commit 2f93944 into bradygaster:main Mar 8, 2026
1 check failed

tamirdresher mentioned this pull request Mar 8, 2026

feat: CommunicationAdapter — platform-agnostic agent-human communication #261

Closed

10 tasks

EmmittJ mentioned this pull request Mar 9, 2026

Question: what's the intended role of the platform/communication adapter layer? #294

Closed

jackbatzner mentioned this pull request Mar 24, 2026

PRD: ADO-Driven Squadding — Full Azure DevOps Support #581

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: CommunicationAdapter — platform-agnostic agent-human communication#263

feat: CommunicationAdapter — platform-agnostic agent-human communication#263
bradygaster merged 13 commits intobradygaster:mainfrom
tamirdresher:feat/communication-adapter

tamirdresher commented Mar 7, 2026

Uh oh!

tamirdresher commented Mar 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tamirdresher commented Mar 7, 2026

Summary

Problem

Solution

Interface (types.ts)

Adapters (4 implementations)

Factory

Dependencies

Testing

Files

Uh oh!

tamirdresher commented Mar 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Interface (`types.ts`)