Skip to content

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

Open
tamirdresher wants to merge 15 commits intobradygaster:mainfrom
tamirdresher:feat/communication-adapter
Open

feat: CommunicationAdapter — platform-agnostic agent-human communication#263
tamirdresher wants to merge 15 commits intobradygaster:mainfrom
tamirdresher:feat/communication-adapter

Conversation

@tamirdresher
Copy link
Contributor

@tamirdresher tamirdresher commented Mar 7, 2026

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

tamirdresher and others added 15 commits March 5, 2026 07:54
@tamirdresher
feat: add platform adapter for Azure DevOps support
dd3f5d7 
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>
@tamirdresher
chore: remove .squad runtime files from tracking
5b78288 
Remove .squad/.first-run and .squad/config.json that trigger branch guard.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tamirdresher
feat: add createWorkItem to PlatformAdapter interface
88ffb16 
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>
@tamirdresher
fix: update acceptance test expectations to match current CLI output
ee8cb50 
- 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>
@tamirdresher
fix: make Ralph platform-aware in coordinator prompt + auth docs
5502701 
- 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>
@tamirdresher
fix: update remaining acceptance test expectations
df7cff5 
- 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>
@tamirdresher
fix: replace execSync with execFileSync to prevent shell injection
20af91a 
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>
@tamirdresher
fix: escape WIQL values and hide bearer token from process args
5daf83e 
- 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>
@tamirdresher
fix: wire upstream command into CLI entry point
39ac72f 
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>
@tamirdresher
fix: skip GitHub workflows for ADO repos, add platform detection to init
a2818d2 
- 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>
@tamirdresher
feat: ADO configurable work item type, area/iteration paths, cross-pr…
0d3dca4 
…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>
@tamirdresher
docs: add blog post bradygaster#23 — Squad Goes Enterprise (ADO support)
9584557 
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>
@tamirdresher
fix: Ralph ADO config resolution — read ado section from .squad/confi…
1b5c63f 
…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>
@tamirdresher
fix: add ADO platform awareness to governance file (squad.agent.md)
b34c4d7 
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>
@tamirdresher
feat: CommunicationAdapter — platform-agnostic agent-human communicat…
767b315 
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tamirdresher