From b4779ad6d42b267a2bb41de4e1cd9c07814dc675 Mon Sep 17 00:00:00 2001 From: Tamir Dresher Date: Sun, 8 Mar 2026 18:28:33 +0200 Subject: [PATCH] docs: add release notes blog #026 + remove duplicate ADO blog #023 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add blog #026 covering ADO adapter, CommunicationAdapter, SubSquads, and security hardening (matches Brady's release blog format) - Remove docs/blog/023-squad-goes-enterprise-azure-devops.md (duplicate of 025 — caused double entry on docs site) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../023-squad-goes-enterprise-azure-devops.md | 226 ------------------ .../blog/026-whats-new-ado-comms-subsquads.md | 151 ++++++++++++ 2 files changed, 151 insertions(+), 226 deletions(-) delete mode 100644 docs/blog/023-squad-goes-enterprise-azure-devops.md create mode 100644 docs/blog/026-whats-new-ado-comms-subsquads.md diff --git a/docs/blog/023-squad-goes-enterprise-azure-devops.md b/docs/blog/023-squad-goes-enterprise-azure-devops.md deleted file mode 100644 index 1f9d77fbc..000000000 --- a/docs/blog/023-squad-goes-enterprise-azure-devops.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -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. - -## 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 -# 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) diff --git a/docs/blog/026-whats-new-ado-comms-subsquads.md b/docs/blog/026-whats-new-ado-comms-subsquads.md new file mode 100644 index 000000000..d55b109fa --- /dev/null +++ b/docs/blog/026-whats-new-ado-comms-subsquads.md @@ -0,0 +1,151 @@ +--- +title: "What's New: Azure DevOps Adapter, CommunicationAdapter, SubSquads, and Security Hardening" +date: 2026-03-08 +author: "Tamir Dresher" +wave: 7 +tags: [squad, azure-devops, enterprise, platform-adapter, communication, subsquads, security] +status: published +hero: "Squad goes enterprise with native Azure DevOps support, adds a CommunicationAdapter for platform-agnostic agent-human messaging, renames Workstreams to SubSquads, and ships critical security hardening across all platform adapters." +--- + +# What's New: Azure DevOps Adapter, CommunicationAdapter, SubSquads, and Security Hardening + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +> _This batch adds first-class Azure DevOps support, a pluggable communication layer, the community-voted SubSquads rename, and security fixes that prevent shell injection, WIQL injection, and bearer token exposure. 5 PRs merged, 153 new tests, 4 issues closed._ + +--- + +## What Shipped + +### 1. Azure DevOps Platform Adapter — The Enterprise Feature + +Squad now works natively with Azure DevOps. When your git remote points to `dev.azure.com` or `*.visualstudio.com`, Squad auto-detects the platform and adapts everything. + +**PlatformAdapter interface** — unified API for GitHub, ADO, and Planner: + +```typescript +interface PlatformAdapter { + listWorkItems(options): Promise; + createWorkItem(options): Promise; + createPullRequest(options): Promise; + mergePullRequest(id): Promise; + createBranch(name, fromBranch?): Promise; + // ... addTag, removeTag, addComment +} +``` + +Three adapters ship with the same interface: +- **AzureDevOpsAdapter** — `az boards` CLI for work items, `az repos` for PRs +- **GitHubAdapter** — `gh` CLI wrapper +- **PlannerAdapter** — Microsoft Graph API for hybrid work-item tracking + +**Configurable work items** via `.squad/config.json`: + +```json +{ + "platform": "azure-devops", + "ado": { + "org": "my-org", + "project": "planning-project", + "defaultWorkItemType": "Scenario", + "areaPath": "MyProject\\Team Alpha", + "iterationPath": "MyProject\\Sprint 5" + } +} +``` + +All fields are optional. Cross-project support means your work items can live in a completely different ADO org/project than your git repo. + +**Ralph on ADO** — the governance file (`squad.agent.md`) now includes a Platform Detection section, ADO WIQL commands for Ralph's scan cycle, and instructions to read `.squad/config.json` before any ADO command. + +**Docs:** [Enterprise Platforms Guide](../features/enterprise-platforms.md) | [Blog #025](025-squad-goes-enterprise-azure-devops.md) + +### 2. CommunicationAdapter — Agent-Human Messaging + +A new pluggable interface for agent-human communication. Scribe can post session summaries, Ralph can post board status, agents can escalate when blocked — all through a platform-appropriate channel. + +```typescript +interface CommunicationAdapter { + postUpdate(options): Promise<{ id: string; url?: string }>; + pollForReplies(options): Promise; + getNotificationUrl(threadId): string | undefined; +} +``` + +Four adapters: + +| Adapter | Phone-capable | Setup | +|---------|:---:|---| +| **FileLog** | Via git | Zero-config fallback | +| **GitHub Discussions** | ✅ Browser | Auto-detected | +| **ADO Work Item Discussions** | ✅ ADO mobile | Auto-detected | +| **Teams Webhook** | ✅ Teams mobile | Stubbed (Phase 2) | + +Factory auto-detects platform: `createCommunicationAdapter(repoRoot)`. + +### 3. SubSquads — The Community-Voted Rename + +Workstreams → SubSquads. The community decided. + +- CLI: `squad subsquads` (with `workstreams` and `streams` as deprecated aliases) +- Types: `SubSquadDefinition`, `SubSquadConfig`, `ResolvedSubSquad` +- Old names kept as `@deprecated` re-exports for backward compatibility +- Config file stays at `.squad/streams.json` (file rename deferred) + +### 4. Security Hardening + +Every platform adapter went through a community-driven 5-model security review (thanks [@wiisaacs](https://github.com/wiisaacs)): + +| Fix | What it prevents | +|-----|-----------------| +| `execSync` → `execFileSync` | Shell injection via user input | +| `escapeWiql()` helper | WIQL injection (SQL-style) in ADO queries | +| `curl --config stdin` | Bearer token invisible to `ps aux` | +| Case-insensitive detection | Mixed-case ADO URLs now detected correctly | +| Cross-platform draft filter | `findstr` → JMESPath (macOS/Linux compat) | +| PR status mapping | `active`→`open` for `gh` CLI compatibility | +| `gh issue create` fix | No `--json` flag — parse URL from stdout | + +### 5. ESM Runtime Patch + Secret Guardrails (Brady) + +- Runtime `Module._resolveFilename` intercept for Node 24+ ESM compatibility +- 5-layer secret defense architecture +- `.squad/skills/secret-handling/SKILL.md` team reference +- 59 TDD security hook tests +- Charter hardening for Trejo (Git & Release) and Drucker (CI/CD) + +--- + +## Quick Stats + +- ✅ 5 PRs merged (#191, #263, #268, #272, #266) +- ✅ 153 new tests (92 platform + 15 comms + 46 SubSquads) +- ✅ 59 security tests (Brady's sprint) +- ✅ 4 issues closed (#240, #261, #271, #273) +- ✅ Security review: 7 code fixes from 10 review comments +- ✅ External integration testing: 10/13 ADO tests passed + +--- + +## Breaking Changes + +None. All changes are additive. Repos without ADO remotes work exactly as before. Old `workstreams`/`streams` names still work as deprecated aliases. + +--- + +## Contributors + +- **[@tamirdresher](https://github.com/tamirdresher)** — ADO adapter, CommunicationAdapter, SubSquads rename, security fixes, docs, blog +- **[@wiisaacs](https://github.com/wiisaacs)** — 5-model security review with test validation +- **[@dfberry](https://github.com/dfberry)** — CommunicationAdapter requirements, tiered deployment proposal +- **[@bradygaster](https://github.com/bradygaster)** — ESM fix, secret guardrails sprint, SubSquads merge, architecture guidance + +--- + +## What's Next + +- **Process template introspection** — auto-detect ADO work item types (#240) +- **Teams webhook adapter** — full CommunicationAdapter implementation (#261) +- **Pre-existing test stabilization** — fix 14 flaky/environment-dependent tests (#273) +- **Persistent Ralph** — `squad watch` heartbeat improvements (#236)