bradygaster/squad: Ein dateibasiertes KI-Agententeam für GitHub Copilot

Agenten als Dateien: was Squad unter .squad/ ablegt

Squad aus dem Repository bradygaster/squad beschreibt sich als ein von Menschen geleitetes KI-Agententeam für jedes Projekt, mit dem Hinweis, dass die beste Erfahrung über GitHub Copilot entsteht. Die Kernidee: Ein Team aus Spezialisten für Frontend, Backend, Tests und Leitung lebt als Dateien im Repository, besteht über Sitzungen hinweg, kennt die Codebasis und teilt Entscheidungen. Der Autor stellt klar, dass Squad kein Chatbot mit mehreren Hüten ist. Jedes Teammitglied läuft in einem eigenen Kontext, liest nur sein eigenes Wissen und schreibt zurück, was es gelernt hat, damit die Arbeit prüfbar bleibt.

Menschen bleiben für Prioritäten, Freigaben und finale Änderungen zuständig; das Werkzeug übernimmt Koordination, Wiederholung und parallele Ausführung. Das Projekt ist in TypeScript geschrieben, MIT-lizenziert, zählt rund 3.100 Sterne und veröffentlichte im August 2026 die Version v0.13.1. Die README markiert es ausdrücklich als Alpha-Software, in der sich APIs und CLI-Befehle zwischen Releases ändern können.

Quickstart von git init bis copilot --agent squad --yolo

Der Schnellstart beginnt mit einem Projektverzeichnis: mkdir my-project && cd my-project, dann git init, geprüft mit git status, das No commits yet melden sollte. Danach installiert man die CLI global mit npm install -g @bradygaster/squad-cli und ruft squad init auf. Wer es eilig hat, nimmt squad init --preset default und bekommt ein vorkonfiguriertes Team samt Mitgliedern, Charters und Routing-Regeln sofort; ohne Flag führt ein geführter Schritt-für-Schritt-Aufbau zum Ergebnis. Die Validierung fragt, ob die Datei .squad/team.md entstanden ist.

Anschließend verbindet man sich mit gh auth login bei GitHub, nötig für Issues, Pull Requests und den Watch-Modus, geprüft über gh auth status. Der Start läuft dann über copilot --agent squad --yolo. Das Flag --yolo sorgt dafür, dass Copilot nicht jeden einzelnen Tool-Aufruf zur Bestätigung vorlegt, denn ein typischer Squad-Aufruf macht viele davon. In VS Code genügt es, im Copilot Chat den Squad-Agenten auszuwählen. Beschreibt man danach das Vorhaben, etwa eine Rezept-App mit React und Node, antwortet Squad mit Teamvorschlägen, die man mit yes bestätigt.

Ralph, der Watch-Modus: squad triage als Issue-Schleife

Der Befehl squad triage, Aliasse watch und loop, startet eine Polling-Schleife, die im Repo nach Issues sucht, sie einsammelt und dem Team zuordnet. Mit --interval lässt sich das Abfrageintervall in Minuten einstellen, standardmäßig alle 10 Minuten. Ohne --execute bleibt es beim automatischen Triage; mit --execute setzt der Lauf echte Copilot-Agenten auf die Issues ab, konfigurierbar über --agent-cmd, --copilot-flags und --auth-user.

Für Störungen beschreibt die README eine vierstufige Erholungsstrategie: Circuit-Breaker zurücksetzen, Authentifizierung erneut prüfen, git pull ausführen und falls nötig eine Pause von 30 Minuten einlegen. Der Status der Schleife lässt sich mit --health abfragen, Diagnosedaten landen über --log-file in einer Datei. Beendet wird der Modus, indem man die Sentinel-Datei .squad/ralph-stop anlegt, dann stoppt die Schleife sauber. Für Laufzeithygiene gibt es zusätzlich squad nap, das Kontext komprimiert, aufräumt und archiviert, mit --dry-run zur Vorschau und --deep für aggressives Kürzen.

squad upgrade, externalize und der Satz aus 17 Befehlen

Squad verwaltet seinen eigenen Dateibestand mit einem Upgrade-Zweischritt: npm install -g @bradygaster/squad-cli@latest aktualisiert die CLI, danach bringt squad upgrade die vom Projekt verwalteten Dateien wie squad.agent.md, Templates und GitHub-Workflows auf den neuesten Stand. Dabei greift es nie in den Teamstatus unter .squad/ ein, Agents, Entscheidungen und Verlauf bleiben erhalten; mit --force lässt sich der Stand erneut aufspielen, mit --self aktualisiert sich das CLI-Paket selbst.

Der komplette Befehlssatz umfasst 17 Kommandos. squad status zeigt an, welches Squad aktiv ist und warum, squad doctor, Alias heartbeat, prüft die Einrichtung, squad link verbindet ein Projekt mit einem entfernten Team-Repository. squad export erzeugt einen portablen JSON-Schnappschuss, squad import liest ihn zurück. Bemerkenswert ist squad externalize, das den Zustand .squad/ außerhalb des Arbeitsbaums ablegt, damit er Branch-Wechsel überlebt, zurückholt wird es mit squad internalize. Die interaktive Shell, ausgelöst durch squad ohne Argumente, ist laut README veraltet; empfohlen wird stattdessen copilot --agent squad.

SDK und Squad.Agents.AI: zwei Wege für TypeScript und .NET

Das Repository ist ein Monorepo mit zwei npm-Paketen: @bradygaster/squad-sdk als Kern-Runtime und @bradygaster/squad-cli als Befehlszeile. Für die lokale Entwicklung klont man das Repo, führt npm install über die npm-Workspaces aus, dann npm run build, zuerst das SDK, danach die CLI. Der direkte Aufruf läuft über node ./packages/squad-cli/dist/cli-entry.js init, mit npm run dev:link wird der Befehl squad global auf den lokalen Build gelegt.

Das SDK bietet programmatische Kontrolle über die Orchestrierung, einschließlich eigener Tools, Hook-Pipelines, Schreibschutz für Dateien, PII-Bereinigung und einer Reviewer-Sperre. Ein SDK-First-Modus erlaubt es, ein Team in TypeScript über eine squad.config.ts zu definieren und mit squad build Markdown zu erzeugen; die README räumt allerdings bekannte Fehler ein und empfiehlt für die Produktion den Markdown-First-Weg. Für .NET gibt es die Vorschau des NuGet-Pakets Squad.Agents.AI unter src/Squad.Agents.AI, das einen Squad-basierten AIAgent in die Abhängigkeitsinjektion registriert und als 0.1.0-preview markiert ist.

Alpha-Grenzen von Squad und die Markdown-First-Alternative

Die README warnt zweimal: APIs und CLI-Befehle können sich zwischen Releases ändern, dokumentiert werden Breaking Changes im CHANGELOG.md. Mit 112 offenen Issues ist die Baustelle sichtbar, und der Default-Branch des Repos heißt dev, was die Experimentierphase zusätzlich unterstreicht. Wer Squad übernimmt, sollte die Version festpinnen und bei jedem Update den Changelog gegenlesen, statt den Upgradepfad blind zu laufen.

Die konkrete Alternative liegt im Moduswahl selbst: Statt des SDK-First-Wegs mit squad.config.ts empfiehlt die README für produktive Nutzung Markdown-First, also Teamdefinition direkt in den Markdown-Dateien, die squad init anlegt. Der Unterschied ist die Quelle der Wahrheit: Im SDK-Modus erzeugt Code die Markdown-Dateien, im Markdown-First-Modus sind die Dateien selbst der Zustand, den man mit Git versionskontrolliert und in Reviews prüft. Für Teams, die Ohne Copilot arbeiten, eignet sich Squad ohnehin nur eingeschränkt, da Agentenausführung und Chat-Anbindung auf dem Copilot-Stack aufsetzen.

Redaktionelles Fazit

Squad eignet sich für Entwickler, die Copilot-gestützte Teamarbeit mit festen Rollen und prüfbarem Verlauf im eigenen Repository organisieren wollen und mit einer Alpha-Phase samt Versionswechseln leben können. Weniger geeignet ist es für Teams, die stabile APIs verlangen oder Copilot nicht einsetzen wollen. Vor dem Start sollte man mit squad doctor die Einrichtung prüfen und danach in .squad/team.md und routing.md kontrollieren, welche Rollen und Weiterleitungsregeln tatsächlich angelegt wurden.

Offizielle Quellen

1. Official documentation
2. Official README
3. Project repository
4. Release notes