feat: CommunicationAdapter — platform-agnostic agent-human communication

[tamirdresher]

CommunicationAdapter — Platform-agnostic agent-human communication

Problem

Squad agents need to communicate with humans (status updates, decisions, escalations, questions). Currently this is ad-hoc — some users use Teams webhooks, some rely on GitHub issue comments, ADO users have Work Item discussions. There is no unified abstraction.

Related discussion: #242 (Dina wants phone-capable comms, Brady wants no GitHub lock-in).

Proposal

Add a CommunicationAdapter interface to the platform layer, alongside the existing PlatformAdapter:

interface CommunicationAdapter {
  postUpdate(channel: string, message: string, options?: { format?: "text" | "card" }): Promise<void>;
  pollForReplies(channel: string, since: Date): Promise<Reply[]>;
  getNotificationUrl(channel: string): string;
}

Implementations

Adapter	Phone-capable	Corp-only	Setup	Notes
GitHubDiscussionsAdapter	Yes (browser)	No	Zero	Uses gh api or GitHub MCP. Categories map to signal types.
ADOWorkItemDiscussionAdapter	Yes (ADO mobile)	Depends	Zero	Comment threads on work items. Already have az CLI wiring.
TeamsWebhookAdapter	Yes (Teams mobile)	Yes	Low	Outbound via webhook, inbound via WorkIQ polling or Power Automate.
FileLogAdapter (fallback)	Via git client	No	Zero	Writes to .squad/log/ — always available, lowest common denominator.

Integration Points

• Scribe posts session summaries to the configured channel after significant work
• Ralph posts board status during idle-watch check-ins
• Coordinator posts escalations when agents are blocked
• Agents can post decisions that need async human review
• Config in .squad/config.json under a communications key

Prototype

A working Teams webhook + WorkIQ polling prototype exists (tested on a separate machine). The pattern:

• Outbound: POST to Teams webhook URL (plain text, not adaptive cards for mobile copy-ability)
• Inbound: WorkIQ MCP tool polls Teams channel for replies matching a unique thread ID
• Deduplication via message timestamp tracking

Acceptance Criteria

• CommunicationAdapter interface in packages/squad-sdk/src/platform/types.ts
• GitHubDiscussionsAdapter implementation
• ADOWorkItemDiscussionAdapter implementation (leverages existing ADO adapter)
• TeamsWebhookAdapter implementation (from prototype)
• FileLogAdapter fallback (always available)
• Scribe integration — posts to channel after agent batches
• Config schema in .squad/config.json
• squad init offers channel setup as optional post-init step
• Docs: communication channel setup per platform
• Phone-capable: all adapters except FileLog work on mobile

Non-Goals (for this issue)

• Push notifications from platform to Squad (Phase 2 — Power Automate / Bot Framework)
• Cross-squad communication aggregation (belongs in Feature: Tiered Squad Deployment — Hub Repos, Companion Repos, and Meta-Hub for Clean Production Repos #242 meta-hub)
• Real-time chat (Squad is async-first)