[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74842":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},74842,"squad","bradygaster\u002Fsquad","bradygaster","Squad: AI agent teams for any project","https:\u002F\u002Fbradygaster.github.io\u002Fsquad\u002F",null,"TypeScript",2788,423,31,85,0,21,71,227,63,109.88,"MIT License",false,"dev",true,[],"2026-06-12 04:01:16","# Squad\n\n[English](README.md) | [中文](README.zh.md)\n\n**Human-led AI agent teams for any project.** One command. A team that helps you move faster with your code.\n\n[![Status](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-alpha-blueviolet)](#status)\n[![Platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-GitHub%20Copilot-blue)](#what-is-squad)\n\n> ⚠️ **Alpha Software** — Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in [CHANGELOG.md](CHANGELOG.md).\n\n---\n\n## What is Squad?\n\nSquad gives you a human-directed AI development team through GitHub Copilot. Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and help you move faster without giving up oversight.\n\nSquad is a productivity tool for humans, not a replacement for engineers, reviewers, or decision-makers. People stay accountable for priorities, approvals, and final changes; Squad helps with coordination, repetition, and parallel execution.\n\nIt's not a chatbot wearing hats. Each team member runs in its own context, reads only its own knowledge, and writes back what it learned so the work stays inspectable.\n\n> **Responsible AI stance** — Squad is built to amplify a human operator with GitHub Copilot, not to remove humans from the loop. Use it to delegate faster, review better, and keep governance close to the code.\n\n---\n\n## Quick Start\n\n### 1. Create your project\n\n```bash\nmkdir my-project && cd my-project\ngit init\n```\n\n**✓ Validate:** Run `git status` — you should see \"No commits yet\".\n\n### 2. Install Squad\n\n```bash\nnpm install -g @bradygaster\u002Fsquad-cli\nsquad init\n```\n\n**✓ Validate:** Check that `.squad\u002Fteam.md` was created in your project.\n\n### 3. Authenticate with GitHub (for Issues, PRs, and Ralph)\n\n```bash\ngh auth login\n```\n\n**✓ Validate:** Run `gh auth status` — you should see \"Logged in to github.com\".\n\n### 4. Open Copilot and go\n\n```\ncopilot --agent squad --yolo\n```\n\n> **Why `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one.\n\n**In VS Code**, open Copilot Chat and select the **Squad** agent.\n\nThen:\n\n```\nI'm starting a new project. Set up the team.\nHere's what I'm building: a recipe sharing app with React and Node.\n```\n\n**✓ Validate:** Squad responds with team member proposals. Type `yes` to confirm — they're ready to work.\n\nSquad proposes a team — each member named from a persistent thematic cast. You say **yes**. They're ready.\n\n---\n\n## Upgrading\n\nUpgrading Squad is a two-step process.\n\n**Step 1: Update the CLI binary**\n\n```bash\nnpm install -g @bradygaster\u002Fsquad-cli@latest\n```\n\n**Step 2: Update Squad-owned files in your project**\n\n```bash\nsquad upgrade\n```\n\n`squad upgrade` updates `squad.agent.md`, templates, and GitHub workflows to the latest versions. It never touches your `.squad\u002F` team state — your agents, decisions, and history are always preserved.\n\nUse `--force` to re-apply updates even when your installed version already matches the latest.\n\n---\n\n## Local Development Installation\n\nTo install and run Squad from source for development:\n\n```bash\n# Clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Fbradygaster\u002Fsquad.git\ncd squad\n\n# Install dependencies (npm workspaces)\nnpm install\n\n# Build the project (SDK first, then CLI)\nnpm run build\n\n# Run the CLI directly\nnode .\u002Fpackages\u002Fsquad-cli\u002Fdist\u002Fcli-entry.js init\n\n# Or link it globally for convenience\nnpm run dev:link\n```\n\nAfter `npm run dev:link`, the `squad` command will be available globally and will use your local build. To update after code changes, re-run `npm run build` to recompile.\n\n---\n\n## All Commands (17 commands)\n\n| Command | What it does |\n|---------|-------------|\n| `squad init` | **Init** — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: `hire`; use `--global` to init in personal squad directory, `--mode remote \u003Cpath>` for dual-root mode |\n| `squad upgrade` | Update Squad-owned files to latest; never touches your team state; use `--global` to upgrade personal squad, `--migrate-directory` to rename `.ai-team\u002F` → `.squad\u002F` |\n| `squad upgrade --self` | Update the Squad CLI package itself; add `--insider` for dev-channel prerelease builds |\n| `squad status` | Show which squad is active and why |\n| `squad triage` | **Watch mode** — poll for issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval \u003Cminutes>` to set polling frequency (default: 10); with `--execute` dispatch Copilot agents; use `--agent-cmd`, `--copilot-flags`, `--auth-user` to customize agent execution; `--health` shows watch status; `--log-file` for diagnostics |\n| `squad copilot` | Add\u002Fremove the Copilot coding agent (@copilot); use `--off` to remove, `--auto-assign` to enable auto-assignment |\n| `squad doctor` | Check your setup and diagnose issues (alias: `heartbeat`) |\n| `squad link \u003Cteam-repo-path>` | Connect to a remote team |\n| `squad externalize` | Move `.squad\u002F` state outside the working tree; survives branch switches; use `--key \u003Cname>` for custom project key |\n| `squad internalize` | Move externalized state back into `.squad\u002F` |\n| `squad shell` | **Deprecated** — Launch interactive shell explicitly. Use `copilot --agent squad` instead. |\n| `squad export` | Export squad to a portable JSON snapshot |\n| `squad import \u003Cfile>` | Import squad from an export file |\n| `squad plugin marketplace add\\|remove\\|list\\|browse` | Manage plugin marketplaces |\n| `squad upstream add\\|remove\\|list\\|sync` | Manage upstream Squad sources |\n| `squad nap` | Context hygiene — compress, prune, archive; use `--deep` for aggressive compression, `--dry-run` to preview changes |\n| `squad aspire` | Open Aspire dashboard for observability |\n| `squad scrub-emails [directory]` | Remove email addresses from Squad state files (default: `.squad\u002F`) |\n\n---\n\n## Watch Mode — Ralph's Automated Polling\n\nRalph continuously polls for work and dispatches agents to handle it. Watch mode helps a human team stay responsive — Ralph automates triage, execution handoffs, and monitoring, then escalates back to people when judgment or approval is needed.\n\n### Quick Start\n\n```bash\n# Monitor for issues (triage mode — no execution)\nnpx @bradygaster\u002Fsquad-cli watch\n\n# Monitor and auto-execute against actionable issues\nnpx @bradygaster\u002Fsquad-cli watch --execute --interval 5\n\n# With custom agent runner and copilot flags\nnpx @bradygaster\u002Fsquad-cli watch --execute \\\n  --agent-cmd \"agency copilot\" \\\n  --copilot-flags \"--yolo --autopilot --mcp mail --agent squad\" \\\n  --auth-user myaccount\n\n# Run watch with diagnostics\nnpx @bradygaster\u002Fsquad-cli watch --execute --log-file .\u002Fwatch.log --verbose\n\n# Check health of running watch process\nnpx @bradygaster\u002Fsquad-cli watch --health\n```\n\n### Key Flags\n\n| Flag | Description |\n|------|-------------|\n| `--execute` | Enable agent execution (spawn Copilot sessions for actionable issues) |\n| `--interval N` | Poll every N minutes (default: 10) |\n| `--agent-cmd` | Custom agent command (default: `gh copilot`) |\n| `--copilot-flags` | Flags passed to the agent runner (e.g., `--yolo --autopilot`) |\n| `--auth-user` | GitHub\u002FAzure DevOps account to use for agent auth |\n| `--log-file` | Mirror output to file for later review and diagnostics |\n| `--verbose` | Show extra diagnostic output (auth probes, callbacks, pulls) |\n| `--health` | Show status of running watch: PID, uptime, auth readiness, capabilities |\n| `--overnight-start HH:MM` | Pause watch during off-hours (e.g., `--overnight-start 18:00`) |\n| `--overnight-end HH:MM` | Resume watch at this time (e.g., `--overnight-end 08:00`) |\n| `--notify-level` | Control output verbosity (`all` \u002F `important` \u002F `none`, default: `important`) |\n| `--state-backend` | Persistence strategy (`git-notes` or `orphan-branch`, default: in-memory) |\n\n### How Watch Decides What to Execute\n\nRalph uses an **agent-delegated selection pattern**:\n\n1. Ralph scans for triage-eligible issues (unassigned, labeled, etc.)\n2. Ralph builds a context snapshot: issue list, squad state, recent decisions\n3. Ralph writes this context to a **temp file** using the `-p \u003Cpath>` flag\n4. Ralph invokes the agent with that file: `gh copilot -p context.md`\n5. The agent **decides which issue to work on** and **how**\n6. Ralph monitors execution, logs results, updates issue status\n\nThis design keeps the polling loop lean while letting agents handle issue selection automatically under the team's rules, review gates, and escalation policy.\n\n### Issue Selection & Escalation\n\nRalph provides a rich prompt scaffold to the agent:\n\n```\n## Work Context\n\n### Available Issues (prioritized)\n- #42 Urgent bug in auth (P0)\n- #89 Performance review pending (P1)\n- #123 Docs update (P2)\n\n### Why These Issues Matter\n...context from decision archive...\n\n### Success Criteria\n- Tests pass\n- Changes match team conventions\n- PR linked to issue\n\n### When to Escalate\nIf blocker detected → pause, log, notify humans\n```\n\nAgents see **full context** and can decide intelligently rather than blindly executing random work.\n\n### Error Recovery (4-Tier Escalation)\n\nWatch includes a tiered remediation strategy:\n\n1. **Tier 1 — Circuit Breaker Reset**: Clear and retry\n2. **Tier 2 — Auth Reprobe**: Re-verify credentials\n3. **Tier 3 — Git Pull**: Update local state\n4. **Tier 4 — Pause 30m**: Back off for human intervention\n\nThis prevents watch from spamming the same failure endlessly.\n\n### State Backends\n\nWatch can persist its state in different ways:\n\n```bash\n# Default: in-memory (loses state on restart)\nsquad watch --execute\n\n# Persist to git-notes (survives restarts, no new branches)\nsquad watch --execute --state-backend git-notes\n\n# Persist to orphan branch (isolated history, easy to prune)\nsquad watch --execute --state-backend orphan-branch\n```\n\n### Graceful Shutdown\n\nTo stop a running watch process gracefully:\n\n```bash\n# Create sentinel file\ntouch .squad\u002Fralph-stop\n\n# Watch will finish current round and exit cleanly\n# Logs final state, cleans scratch dirs\n```\n\n### Cleanup\n\nWatch automatically prunes stale artifacts:\n- Scratch directories older than 7 days\n- Log files older than 30 days\n- Orphaned orchestration state\n\n### Monitoring Watch\n\nCheck on a running watch:\n\n```bash\nsquad watch --health\n```\n\nOutput example:\n```\nRalph Watch Status\n\nPID: 12345\nUptime: 2h 15m\nLast Poll: 2 minutes ago\n\nAuth: Ready (account: myaccount@github.com)\nCapabilities: Issue triage, PR review, ADO sync\n\nNext Poll: 14:35 (in 3 minutes)\nRound: 42 \u002F 1200\n```\n\n---\n\n## Interactive Shell\n\n> ⚠️ **Deprecated:** The interactive shell (`squad` with no arguments) has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fcopilot\u002Fgithub-copilot-in-the-cli) instead.\n>\n> ```bash\n> copilot --agent squad\n> ```\n>\n> See [Choose your interface](docs\u002Fsrc\u002Fcontent\u002Fdocs\u002Fget-started\u002Fchoose-your-interface.md) for current options.\n\nTired of typing `squad` followed by a command every time? Enter the interactive shell.\n\n### Entering the Shell\n\n```bash\nsquad\n```\n\nNo arguments. Just `squad`. You'll get a prompt:\n\n```\nsquad >\n```\n\nYou're now connected to your team. Talk to them.\n\n### Shell Commands\n\nAll shell commands start with `\u002F`:\n\n| Command | What it does |\n|---------|-------------|\n| `\u002Fstatus` | Check your team and what's happening |\n| `\u002Fhistory` | See recent messages |\n| `\u002Fagents` | List all team members |\n| `\u002Fsessions` | List saved sessions |\n| `\u002Fresume \u003Cid>` | Restore a past session |\n| `\u002Fversion` | Show version |\n| `\u002Fclear` | Clear the screen |\n| `\u002Fhelp` | Show all commands |\n| `\u002Fquit` | Exit the shell (or Ctrl+C) |\n\n### Talking to Agents\n\nUse `@AgentName` (case-insensitive) or natural language with a comma:\n\n```\nsquad > @Keaton, analyze the architecture of this project\nsquad > McManus, write a blog post about our new feature\nsquad > Build the login page\n```\n\nThe coordinator routes messages to the right agents. Multiple agents can work in parallel—you'll see progress in real-time.\n\n### What the Shell Does\n\n- **Real-time visibility:** See agents working, decisions being recorded, blockers as they happen\n- **Message routing:** Describe what you need; the coordinator figures out who should do it\n- **Parallel execution:** Multiple agents work simultaneously on independent tasks\n- **Session persistence:** If an agent crashes, it resumes from checkpoint; you never lose context\n- **Decision logging:** Every decision is recorded in `.squad\u002Fdecisions.md` for the whole team to see\n\nFor more details on shell usage, see the commands table above.\n\n## Samples\n\nEight working examples from beginner to advanced — casting, governance, streaming, Docker. See [samples\u002FREADME.md](samples\u002FREADME.md).\n\n---\n\n## Agents Work in Parallel — You Stay in Control\n\nSquad helps one human coordinate more work at once. When you give a task, the coordinator launches every agent that can usefully start — simultaneously — while you keep priorities, review, and final decisions.\n\n```\nYou: \"Team, build the login page\"\n\n  🏗️ Lead — analyzing requirements...          ⎤\n  ⚛️ Frontend — building login form...          ⎥ all launched\n  🔧 Backend — setting up auth endpoints...     ⎥ in parallel\n  🧪 Tester — writing test cases from spec...   ⎥\n  📋 Scribe — logging everything...             ⎦\n```\n\nWhen agents finish, the coordinator records follow-up work and leaves a breadcrumb trail so you can review what happened with full context:\n\n- **`decisions.md`** — every decision any agent made\n- **`orchestration-log\u002F`** — what was spawned, why, and what happened\n- **`log\u002F`** — full session history, searchable\n\n**Knowledge compounds across sessions.** Every time an agent works, it writes lasting learnings to its `history.md`. After a few sessions, agents know your conventions, your preferences, your architecture. They stop asking questions they've already answered.\n\n**And it's all in git.** Anyone who clones your repo gets the team — with all their accumulated knowledge.\n\n---\n\n## What Gets Created\n\n```\n.squad\u002F\n├── team.md              # Roster — who's on the team\n├── routing.md           # Routing — who handles what\n├── decisions.md         # Shared brain — team decisions\n├── ceremonies.md        # Sprint ceremonies config\n├── casting\u002F\n│   ├── policy.json      # Casting configuration\n│   ├── registry.json    # Persistent name registry\n│   └── history.json     # Universe usage history\n├── agents\u002F\n│   ├── {name}\u002F\n│   │   ├── charter.md   # Identity, expertise, voice\n│   │   └── history.md   # What they know about YOUR project\n│   └── scribe\u002F\n│       └── charter.md   # Silent memory manager\n├── skills\u002F              # Compressed learnings from work\n├── identity\u002F\n│   ├── now.md           # Current team focus\n│   └── wisdom.md        # Reusable patterns\n└── log\u002F                 # Session history (searchable archive)\n```\n\n**Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast.\n\n### SDK-First Mode (New in Phase 1)\n\n> ⚠️ **Experimental.** SDK-first mode is under active development and has known bugs. Use markdown-first (the default) for production teams.\n\nPrefer TypeScript? You can define your team in code instead of markdown. Create a `squad.config.ts` with builder functions, run `squad build`, and the `.squad\u002F` files are generated automatically.\n\n```typescript\n\u002F\u002F squad.config.ts\nimport { defineSquad, defineTeam, defineAgent } from '@bradygaster\u002Fsquad-sdk';\n\nexport default defineSquad({\n  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),\n  agents: [\n    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-4' }),\n    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),\n  ],\n});\n```\n\nRun `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs\u002Fsrc\u002Fcontent\u002Fdocs\u002Fsdk-first-mode.md) for full documentation.\n\n---\n\n## Monorepo Development\n\nSquad is a monorepo with two packages:\n- **`@bradygaster\u002Fsquad-sdk`** — Core runtime and library for programmable agent orchestration\n- **`@bradygaster\u002Fsquad-cli`** — Command-line interface that depends on the SDK\n\n### Building\n\n```bash\n# Install dependencies (npm workspaces)\nnpm install\n\n# Build TypeScript to dist\u002F\nnpm run build\n\n# Build CLI bundle (dist\u002F + esbuild → cli.js)\nnpm run build:cli\n\n# Watch mode for development\nnpm run dev\n```\n\n### Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Watch mode\nnpm run test:watch\n```\n\n### Linting\n\n```bash\n# Type check (no emit)\nnpm run lint\n```\n\n### Publishing\n\nSquad uses [changesets](https:\u002F\u002Fgithub.com\u002Fchangesets\u002Fchangesets) for independent versioning across packages:\n\n```bash\n# Add a changeset\nnpx changeset add\n\n# Validate changesets\nnpm run changeset:check\n```\n\nChangesets are resolved on the `main` branch; releases happen independently per package.\n\n---\n\n## SDK documentation\n\nThe SDK provides programmatic control over agent orchestration — custom tools, hook pipelines, file-write guards, PII scrubbing, reviewer lockout, and event-driven monitoring.\n\n- [SDK API reference](docs\u002Fsrc\u002Fcontent\u002Fdocs\u002Freference\u002Fsdk.md)\n- [Custom tools and hooks guide](docs\u002Fsrc\u002Fcontent\u002Fdocs\u002Freference\u002Ftools-and-hooks.md)\n- [Extensibility guide](docs\u002Fsrc\u002Fcontent\u002Fdocs\u002Fguide\u002Fextensibility.md)\n- [Samples](samples\u002FREADME.md) — eight working examples from beginner to advanced\n\nFor SDK installation: `npm install @bradygaster\u002Fsquad-sdk`\n","Squad 是一个通过 GitHub Copilot 为任何项目提供由人类指导的 AI 开发团队的工具。其核心功能包括根据项目描述自动生成前端、后端、测试和领导角色的专业团队成员，这些成员以文件形式存在于仓库中，能够跨会话持续学习代码库，并促进开发效率提升。技术上采用 TypeScript 编写，支持与 GitHub Copilot 的深度集成，使开发者能够在保持对项目的控制权的同时加速开发流程。适用于需要快速构建或扩展开发力量的各种软件工程项目，尤其是在面对复杂度高、迭代速度快的应用场景时尤为有效。",2,"2026-06-11 03:51:03","high_star"]