Dev

README.md

@@ -5,15 +5,15 @@
 **AI agent teams for any project.** One command. A team that grows with your code.
 
 [![Status](https://img.shields.io/badge/status-alpha-blueviolet)](#status)
-[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad)
+[![Platform](https://img.shields.io/badge/platform-Copilot%20%7C%20Claude%20Code-blue)](#what-is-squad)
 
-> ⚠️ **Alpha Software** — Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in [CHANGELOG.md](CHANGELOG.md).
+> ⚠️ **Alpha Software** - Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
 ## What is Squad?
 
-Squad gives you an 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 get better the more you use them.
+Squad gives you an AI development team through **GitHub Copilot or Claude Code**. 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 get better the more you use them.
 
 It'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.
 
@@ -28,7 +28,7 @@ mkdir my-project && cd my-project
 git init
 ```
 
-**✓ Validate:** Run `git status` — you should see "No commits yet".
+**✓ Validate:** Run `git status` - you should see "No commits yet".
 
 ### 2. Install Squad
 
@@ -45,17 +45,23 @@ squad init
 gh auth login
 ```
 
-**✓ Validate:** Run `gh auth status` — you should see "Logged in to github.com".
+**✓ Validate:** Run `gh auth status` - you should see "Logged in to github.com".
 
-### 4. Open Copilot and go
+### 4. Open your provider and go
 
-```
+Use either provider path:
+
+```bash
+# GitHub Copilot CLI
 copilot --agent squad --yolo
+
+# Claude Code CLI
+claude --agent squad --dangerously-skip-permissions
 ```
 
-> **Why `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one.
+> **Permission flags:** Squad makes many tool calls in typical sessions. Use the provider-specific equivalent that matches your trust/sandbox settings.
 
-**In VS Code**, open Copilot Chat and select the **Squad** agent.
+**In VS Code**, open your chat provider (Copilot or Claude extension) and select the **Squad** agent.
 
 Then:
 
@@ -64,9 +70,19 @@ I'm starting a new project. Set up the team.
 Here's what I'm building: a recipe sharing app with React and Node.
 ```
 
-**✓ Validate:** Squad responds with team member proposals. Type `yes` to confirm — they're ready to work.
+**✓ Validate:** Squad responds with team member proposals. Type `yes` to confirm - they're ready to work.
+
+Squad proposes a team - each member named from a persistent thematic cast. You say **yes**. They're ready.
+
+## Runtime providers
+
+Squad supports both runtime providers as first-class paths:
 
-Squad proposes a team — each member named from a persistent thematic cast. You say **yes**. They're ready.
+- **Copilot:** `copilot --agent squad`
+- **Claude Code:** `claude --agent squad`
+
+Provider-specific flags, compatibility behavior, token mappings, and troubleshooting are documented in:
+- [`docs/runtime-providers.md`](docs/runtime-providers.md)
 
 ---
 
@@ -86,7 +102,7 @@ npm install -g @bradygaster/squad-cli@latest
 squad upgrade
 ```
 
-`squad upgrade` updates `squad.agent.md`, templates, and GitHub workflows to the latest versions. It never touches your `.squad/` team state — your agents, decisions, and history are always preserved.
+`squad upgrade` updates `squad.agent.md`, templates, and GitHub workflows to the latest versions. It never touches your `.squad/` team state - your agents, decisions, and history are always preserved.
 
 Use `--force` to re-apply updates even when your installed version already matches the latest.
 
@@ -96,19 +112,19 @@ Use `--force` to re-apply updates even when your installed version already match
 
 | Command | What it does |
 |---------|-------------|
-| `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 <path>` for dual-root mode |
+| `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 <path>` for dual-root mode |
 | `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/` → `.squad/` |
 | `squad status` | Show which squad is active and why |
 | `squad triage` | Watch issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval <minutes>` to set polling frequency (default: 10) |
-| `squad copilot` | Add/remove the Copilot coding agent (@copilot); use `--off` to remove, `--auto-assign` to enable auto-assignment |
+| `squad copilot` | Manage Copilot coding-agent integration (`@copilot`); for Claude runtime workflows, see `docs/runtime-providers.md` |
 | `squad doctor` | Check your setup and diagnose issues (alias: `heartbeat`) |
 | `squad link <team-repo-path>` | Connect to a remote team |
 | `squad shell` | Launch interactive shell explicitly |
 | `squad export` | Export squad to a portable JSON snapshot |
 | `squad import <file>` | Import squad from an export file |
 | `squad plugin marketplace add\|remove\|list\|browse` | Manage plugin marketplaces |
 | `squad upstream add\|remove\|list\|sync` | Manage upstream Squad sources |
-| `squad nap` | Context hygiene — compress, prune, archive; use `--deep` for aggressive compression, `--dry-run` to preview changes |
+| `squad nap` | Context hygiene - compress, prune, archive; use `--deep` for aggressive compression, `--dry-run` to preview changes |
 | `squad aspire` | Open Aspire dashboard for observability |
 | `squad scrub-emails [directory]` | Remove email addresses from Squad state files (default: `.squad/`) |
 
@@ -158,7 +174,7 @@ squad > McManus, write a blog post about our new feature
 squad > Build the login page
 ```
 
-The coordinator routes messages to the right agents. Multiple agents can work in parallel—you'll see progress in real-time.
+The coordinator routes messages to the right agents. Multiple agents can work in parallel-you'll see progress in real-time.
 
 ### What the Shell Does
 
@@ -172,43 +188,43 @@ For more details on shell usage, see the commands table above.
 
 ## Samples
 
-Eight working examples from beginner to advanced — casting, governance, streaming, Docker. See [samples/README.md](samples/README.md).
+Eight working examples from beginner to advanced - casting, governance, streaming, Docker. See [samples/README.md](samples/README.md).
 
 ---
 
-## Agents Work in Parallel— You Catch Up When You're Ready
+## Agents Work in Parallel- You Catch Up When You're Ready
 
-Squad doesn't work on a human schedule. When you give a task, the coordinator launches every agent that can usefully start — simultaneously.
+Squad doesn't work on a human schedule. When you give a task, the coordinator launches every agent that can usefully start - simultaneously.
 
 ```
 You: "Team, build the login page"
 
-  🏗️ Lead — analyzing requirements...          ⎤
-  ⚛️ Frontend — building login form...          ⎥ all launched
-  🔧 Backend — setting up auth endpoints...     ⎥ in parallel
-  🧪 Tester — writing test cases from spec...   ⎥
-  📋 Scribe — logging everything...             ⎦
+  🏗️ Lead - analyzing requirements...          ⎤
+  ⚛️ Frontend - building login form...          ⎥ all launched
+  🔧 Backend - setting up auth endpoints...     ⎥ in parallel
+  🧪 Tester - writing test cases from spec...   ⎥
+  📋 Scribe - logging everything...             ⎦
 ```
 
 When agents finish, the coordinator immediately chains follow-up work. If you step away, a breadcrumb trail is waiting when you get back:
 
-- **`decisions.md`** — every decision any agent made
-- **`orchestration-log/`** — what was spawned, why, and what happened
-- **`log/`** — full session history, searchable
+- **`decisions.md`** - every decision any agent made
+- **`orchestration-log/`** - what was spawned, why, and what happened
+- **`log/`** - full session history, searchable
 
 **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.
 
-**And it's all in git.** Anyone who clones your repo gets the team — with all their accumulated knowledge.
+**And it's all in git.** Anyone who clones your repo gets the team - with all their accumulated knowledge.
 
 ---
 
 ## What Gets Created
 
 ```
 .squad/
-├── team.md              # Roster — who's on the team
-├── routing.md           # Routing — who handles what
-├── decisions.md         # Shared brain — team decisions
+├── team.md              # Roster - who's on the team
+├── routing.md           # Routing - who handles what
+├── decisions.md         # Shared brain - team decisions
 ├── ceremonies.md        # Sprint ceremonies config
 ├── casting/
 │   ├── policy.json      # Casting configuration
@@ -227,7 +243,7 @@ When agents finish, the coordinator immediately chains follow-up work. If you st
 └── log/                 # Session history (searchable archive)
 ```
 
-**Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team — with the same cast.
+**Commit this folder.** Your team persists. Names persist. Anyone who clones gets the team - with the same cast.
 
 ### SDK-First Mode (New in Phase 1)
 
@@ -255,8 +271,8 @@ Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](d
 ## Monorepo Development
 
 Squad is a monorepo with two packages:
-- **`@bradygaster/squad-sdk`** — Core runtime and library for programmable agent orchestration
-- **`@bradygaster/squad-cli`** — Command-line interface that depends on the SDK
+- **`@bradygaster/squad-sdk`** - Core runtime and library for programmable agent orchestration
+- **`@bradygaster/squad-cli`** - Command-line interface that depends on the SDK
 
 ### Building
 
@@ -307,13 +323,21 @@ Changesets are resolved on the `main` branch; releases happen independently per
 
 ---
 
+## Runtime Providers
+
+Squad supports multiple AI coding agent backends through a unified provider interface. You can switch between GitHub Copilot and the Claude CLI without changing any orchestration code.
+
+- [Runtime Providers guide](docs/runtime-providers.md) - provider selection, compatibility matrix, error handling, and troubleshooting
+
+---
+
 ## SDK documentation
 
-The SDK provides programmatic control over agent orchestration — custom tools, hook pipelines, file-write guards, PII scrubbing, reviewer lockout, and event-driven monitoring.
+The SDK provides programmatic control over agent orchestration - custom tools, hook pipelines, file-write guards, PII scrubbing, reviewer lockout, and event-driven monitoring.
 
 - [SDK API reference](docs/src/content/docs/reference/sdk.md)
 - [Custom tools and hooks guide](docs/src/content/docs/reference/tools-and-hooks.md)
 - [Extensibility guide](docs/src/content/docs/guide/extensibility.md)
-- [Samples](samples/README.md) — eight working examples from beginner to advanced
+- [Samples](samples/README.md) - eight working examples from beginner to advanced
 
 For SDK installation: `npm install @bradygaster/squad-sdk`

docs/architecture/claude-runtime-execution-plan.md

@@ -0,0 +1,65 @@
+# Claude Runtime Migration Plan (Execution)
+
+## Objective
+Ship Claude Code support quickly with minimal code churn and low regression risk.
+
+## Principles
+- Additive changes only where possible.
+- Keep Copilot runtime as the baseline safety net.
+- Ship in thin vertical slices.
+
+## Workstreams
+
+### WS1 — Runtime Interface + Copilot Extraction (Owner: copilot-agent)
+- [ ] Add `RuntimeProvider` interface and shared runtime event types.
+- [ ] Wrap current Copilot adapter as `CopilotRuntimeProvider`.
+- [ ] Add runtime selection in config with default `copilot`.
+- [ ] Update coordinator bootstrap to resolve runtime provider from config.
+
+### WS2 — Claude Runtime MVP (Owner: copilot-agent + review)
+- [ ] Implement `ClaudeCodeRuntimeProvider` with session lifecycle and streaming hooks.
+- [ ] Map Claude runtime errors into existing normalized error taxonomy.
+- [ ] Add feature flags/capability flags for unsupported operations.
+
+### WS3 — Templates / Workflows Runtime-Aware (Owner: split with team)
+- [ ] Parameterize workflow labels/assignee conventions by runtime.
+- [ ] Add Claude-specific automation template variants where needed.
+- [ ] Keep existing Copilot templates unchanged by default.
+
+### WS4 — Skills / Hooks / Plugin Compatibility (Owner: split with team)
+- [ ] Identify Copilot-specific skill/path assumptions and isolate behind compatibility helpers.
+- [ ] Support runtime-specific instruction files (Copilot instructions vs CLAUDE.md pathing guidance).
+- [ ] Validate hook execution semantics under both runtimes.
+
+### WS5 — Testing + CI Matrix (Owner: copilot-agent)
+- [ ] Add provider contract tests.
+- [ ] Add Claude provider smoke tests.
+- [ ] Add runtime template rendering tests.
+- [ ] Add CI matrix for `RUNTIME=copilot` + `RUNTIME=claude-code`.
+
+## Milestones
+
+### M1 (Foundations)
+- Provider interface merged.
+- Copilot extraction merged.
+- All existing tests green.
+
+### M2 (Claude MVP)
+- Claude provider integrated.
+- Basic prompt-response flow validated locally.
+- Runtime toggle functional.
+
+### M3 (Operational Readiness)
+- Runtime-aware templates merged.
+- CI matrix green in both modes.
+- Docs updated for Claude setup and migration.
+
+## Decision Log (Initial)
+1. Do **not** rename `.copilot/*` globally in first phase.
+2. Keep `copilot` runtime default until Claude lane proves stable.
+3. Prefer runtime-tokenized templates over duplicated workflow stacks.
+
+## Definition of Done
+- Squad can run with Claude runtime selected and pass smoke tests.
+- Copilot mode remains regression-free.
+- Teams can opt in per repo with one config change.

docs/architecture/claude-runtime-rfc.md

@@ -0,0 +1,85 @@
+# RFC: Claude Code Runtime Support (Minimal-Change Path)
+
+## Status
+Draft (implementation starting)
+
+## Goal
+Add first-class Claude Code support to Squad while preserving existing Copilot behavior and minimizing churn.
+
+## Non-Goals
+- No wholesale rewrite of coordinator/routing logic.
+- No forced migration of existing Copilot users.
+- No redesign of `.squad` state model.
+
+## Constraints
+- Keep existing Copilot runtime green.
+- Introduce runtime-specific behavior behind explicit interfaces.
+- Favor additive changes over global renames.
+
+## Current State Summary
+Squad is currently deeply coupled to Copilot-specific surfaces:
+- Runtime adapter: `@github/copilot-sdk`
+- CLI/process commands: `copilot`, `copilot --acp`
+- Templates/workflows: `@copilot`, `squad:copilot`, `copilot-swe-agent`
+- Skills/MCP conventions: `.copilot/*`
+
+## Proposed Architecture
+Introduce a provider abstraction:
+
+```ts
+interface RuntimeProvider {
+  name: 'copilot' | 'claude-code';
+  startSession(opts: StartSessionOptions): Promise<RuntimeSession>;
+  send(sessionId: string, input: RuntimeInput): Promise<void>;
+  stream(sessionId: string, onEvent: (e: RuntimeEvent) => void): Promise<Unsubscribe>;
+  listModels?(): Promise<ModelInfo[]>;
+  shutdown(sessionId: string): Promise<void>;
+}
+```
+
+Implementations:
+- `CopilotRuntimeProvider` (adapter over existing behavior)
+- `ClaudeCodeRuntimeProvider` (new)
+
+## Minimal-Change Strategy
+1. **Extract, don’t rewrite** existing Copilot code into provider implementation.
+2. Keep coordinator APIs unchanged where possible.
+3. Add runtime selection config (`runtime.default`) with safe default = `copilot`.
+4. Make templates runtime-aware using tokenized variants (instead of duplicating whole trees).
+
+## Runtime Selection
+- Global config: `runtime.default: copilot | claude-code`
+- Optional per-agent override: `agent.runtime`
+- CLI overrides (future): `--runtime claude-code`
+
+## Compatibility Model
+- Existing repos remain valid.
+- Existing commands remain valid.
+- Copilot workflow templates unchanged unless runtime=claude-code selected.
+- New Claude templates generated only when explicitly requested.
+
+## Risks / Blockers
+1. Claude Code event/session semantics may differ from Copilot ACP behavior.
+2. GitHub assignment automation differs (`@copilot` conventions are not portable as-is).
+3. Runtime-specific docs/instructions files (`CLAUDE.md` vs Copilot instruction paths).
+
+## Validation Plan
+- Contract tests for `RuntimeProvider` lifecycle.
+- Matrix CI lanes:
+  - `RUNTIME=copilot` (must stay green)
+  - `RUNTIME=claude-code` (new lane)
+- E2E smoke:
+  - spawn session
+  - send prompt
+  - observe streamed response
+  - terminate cleanly
+
+## Deliverables (Phase 1)
+- Provider interface + Copilot extraction.
+- `runtime.default` config support.
+- No behavior regression for current users.
+
+## Deliverables (Phase 2)
+- Claude provider MVP.
+- Runtime-aware template rendering for issue routing/automation.
+- Initial Claude docs + setup guidance.