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

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

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)