diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index cd735f17a..9f4bdae37 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -25,3 +25,9 @@ Zero code changes. Skill files in templates/skills/, scripts in scripts/mesh/, d ### Sprint Prioritization Pattern Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA, (3) high-ROI features unblocking downstream work. Interleave stability (bugs/quality) with velocity (features) across sprint capacity. +### Agent On-Disk Anatomy Documentation +Developer concept doc clarifying the distributed identity model: runtime state (`.squad/agents/{name}/`), SDK infrastructure (`packages/squad-sdk/src/agents/`), and optional config overrides. Charter is DNA (parsed into agent prompt), history is append-only learnings, casting adds memorable names. Three conditions for active agent: charter.md exists, roster entry in team.md, routing rules. Alumni pattern preserves retired agents in `_alumni/`. Context flows via explicit artifacts (team.md, routing.md, decisions.md), not shared memory. SDK is generic runtime — all agent specificity lives in `.squad/`. + +### Doc Compression Patterns (2026-03-16) +**Surgical trimming:** When compressing verbose docs (298→152 lines, ~49%), cut who-writes-it/who-reads-it sections, redundant examples, over-explained flows. Keep essential anatomy and code structures. **Human and @copilot coverage:** Squad supports non-spawnable roster members: humans (👤 badge, no charter/history, coordinator waits for input) and @copilot (🤖 badge, uses copilot-instructions.md, capability profile, async via issue assignment). Both participate in routing and reviews. **Strategic docs:** Brady wants small, focused concept docs. Add new sections only when expanding coverage (human members, coding agents) — don't inflate with verbose explanations. + diff --git a/.worktrees/323-clarify-copilot-requirement b/.worktrees/323-clarify-copilot-requirement new file mode 160000 index 000000000..6e8a264d5 --- /dev/null +++ b/.worktrees/323-clarify-copilot-requirement @@ -0,0 +1 @@ +Subproject commit 6e8a264d51ac03dd3d6029159762c734bed020aa diff --git a/docs/src/content/docs/concepts/agent-on-disk.md b/docs/src/content/docs/concepts/agent-on-disk.md new file mode 100644 index 000000000..c17f4df8a --- /dev/null +++ b/docs/src/content/docs/concepts/agent-on-disk.md @@ -0,0 +1,211 @@ +# What It Means on Disk to Be a Squad Agent + +> Developer-oriented concept doc: the on-disk anatomy of a Squad agent + +## Overview + +A Squad agent is a **distributed identity** spanning three layers: + +1. **Runtime state** — `.squad/` directory (team-specific, git-committed) +2. **SDK infrastructure** — `packages/squad-sdk/src/agents/` (compiled code) +3. **Configuration** — `squad.config.ts` or `squad.config.json` (optional overrides) + +This doc explains how these layers work together to create spawnables agents (AI specialists), and how non-spawnables members (humans, @copilot) appear in the team roster. + +## AI Agent Directory Structure + +Each spawnable AI agent exists in `.squad/agents/{name}/`: + +``` +.squad/ +└── agents/ + ├── flight/ + │ ├── charter.md # Agent's identity, boundaries, voice + │ └── history.md # Append-only learnings (optional) + ├── capcom/ + │ └── charter.md + └── _alumni/ + └── verbal/ # Retired agents + └── charter.md +``` + +### Key Files + +#### `charter.md` — The Agent's DNA + +Compiled by the SDK at spawn time into the agent's system prompt. + +**Core sections:** +- **Identity** → name, role, expertise, style +- **What I Own** → responsibilities (plain text) +- **How I Work** → patterns, preferences, workflows +- **Boundaries** → what the agent handles vs. delegates +- **Model** → preferred model (e.g., `auto`, `gpt-4.1`, `claude-sonnet-4.6`) + +The charter is parsed into a `SquadCustomAgentConfig` object with: +- Full charter as system prompt +- Metadata (name, role, model preference) +- Team context (from `team.md`, `routing.md`, `decisions.md`) + +Personality and voice matter — agents have opinions. + +#### `history.md` — Append-Only Learnings + +Written by the agent after work. Read at spawn time. + +**Structure:** +- `## Core Context` — stable project facts +- `## Learnings` — accumulated patterns and decisions + +**What belongs:** +- Project patterns (e.g., "three-branch model") +- Domain knowledge (e.g., "boundary review heuristic") +- Cross-session learnings + +**What doesn't:** +- Transient task state (use SQL) +- Raw logs (use `.squad/log/`) +- Multi-agent decisions (use `.squad/decisions.md`) + +### Alumni — Retirement + +Retired agents move to `.squad/agents/_alumni/{name}/`. They cannot be spawned. Charters are preserved as read-only archives. + +## The Casting System (Optional) + +Squad assigns memorable names from fictional universes: + +- **`casting-registry.json`** — tracks allocated names, universes, timestamps +- **`casting-policy.json`** — defines available universes and capacity limits +- **`casting-history.json`** — immutable audit trail + +Names are not reused within the same universe. When a universe is exhausted, a new one is added to the policy. + +## How an AI Agent "Exists" + +An AI agent is **active** when: + +1. **Charter exists** — `.squad/agents/{name}/charter.md` is present +2. **Roster entry** — Agent listed in `team.md` with status `✅ Active` or `📋 Silent` +3. **Routing rules** — Agent appears in `routing.md` work assignments + +**Spawn flow:** + +``` +User request → Coordinator reads routing.md → Identifies agent +→ SDK reads charter.md, history.md → Compiles SquadCustomAgentConfig +→ Spawns agent → Agent runs → Writes to history.md +``` + +## Relationship to SDK Source Files + +The `.squad/` directory is **runtime state**, not code. The SDK provides the **infrastructure** to load, parse, and execute agents: + +| SDK Module | Purpose | +|------------|---------| +| `packages/squad-sdk/src/agents/charter-compiler.ts` | Parses `charter.md` into `SquadCustomAgentConfig` | +| `packages/squad-sdk/src/agents/history-shadow.ts` | Loads `history.md` and injects into agent context | +| `packages/squad-sdk/src/agents/lifecycle.ts` | Agent spawn, session management, termination | +| `packages/squad-sdk/src/agents/model-selector.ts` | Resolves `## Model` preference to actual model | +| `packages/squad-sdk/src/casting/` | Name allocation, registry management | + +**Key insight:** The SDK never hardcodes agent names or roles. It's a generic **agent runtime**. All specificity lives in `.squad/`. + +This means: +- You can add new agents without changing SDK code +- Multiple projects using the same SDK have different teams +- Agents can be dynamically added, retired, or renamed + +## Config Overrides + +The optional `squad.config.ts` file provides **overrides** for charter-based agents: + +```typescript +export default { + agents: { + flight: { + model: 'gpt-4.1', // Override charter + tools: ['read', 'write'], // Restrict tools + extraPrompt: 'Focus on performance.' // Append to charter + } + } +} +``` + +**Merge order:** Charter → Config → Team context → Final prompt + +Use cases: per-environment tuning, temporary restrictions, A/B testing. + +## Cross-Agent Context + +Agents don't share memory. Context flows via **explicit artifacts**: + +- **`team.md`** — Shared roster (who exists, what they do) +- **`routing.md`** — Work assignment rules (coordinator uses this) +- **`decisions.md`** — Canonical decisions log (shared memory) +- **`.squad/decisions/inbox/`** — Decision drop-box (agents write, Scribe merges) +- **`.squad/log/`** — Session summaries (auditing and debugging) + +## Human Team Members (👤) + +Squad supports **human members** in the roster: + +```markdown +| Name | Role | Status | Badge | +|------|------|--------|-------| +| dina | Product Manager | ✅ Active | 👤 Human | +``` + +**Key differences from AI agents:** +- **No charter** — Humans don't have `.squad/agents/{name}/charter.md` +- **No history** — Humans don't accumulate `history.md` +- **Not spawnable** — Coordinator presents work and waits for human input (asynchronous collaboration) +- **Participate in routing** — Routing rules can assign work to humans (e.g., "UX design → dina") +- **Code review** — Humans can be listed as required reviewers in routing + +Humans are roster members but operate asynchronously. The coordinator surfaces work to them and waits. + +## @copilot Coding Agent (🤖) + +Squad supports **@copilot** as a roster member: + +```markdown +| Name | Role | Status | Badge | +|------|------|--------|-------| +| @copilot | Coding Agent | ✅ Active | 🤖 Coding Agent | +``` + +**Key differences from AI agents:** +- **No charter** — @copilot uses `copilot-instructions.md` (injected via `.github/copilot-instructions.md`) +- **Not spawnable** — Works via GitHub issue assignment (asynchronous) +- **Creates `copilot/*` branches** — Opens draft PRs for review +- **Capability profile** — Has a 🟢/🟡/🔴 profile in `team.md` (e.g., 🟢 TypeScript, 🟡 Architecture, 🔴 Security audits) +- **Self-checks before starting** — Reads capability profile, only takes work it's suited for + +The coordinator routes work to @copilot by assigning issues. @copilot autonomously picks up work, performs capability checks, and opens PRs. + +## Key Takeaways + +1. **AI agents are directories** — `.squad/agents/{name}/` with `charter.md` +2. **Charter is source of truth** — identity, boundaries, voice +3. **History is optional** — recommended for repeated work +4. **Casting adds personality** — thematic names (Apollo 13, Ocean's Eleven) +5. **SDK is generic** — no agent-specific code in the runtime +6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md` +7. **Humans and @copilot are roster members** — but not spawnable + +## Developer Checklist: Creating a New AI Agent + +- [ ] Create `.squad/agents/{name}/` directory +- [ ] Write `charter.md` (use `.squad/templates/charter.md`) +- [ ] Add to `team.md` roster with status `✅ Active` +- [ ] Add to `routing.md` with work type assignments +- [ ] (Optional) Allocate name via casting system +- [ ] (Optional) Create `history.md` for persistent memory +- [ ] Test spawn: `squad spawn {name} "Hello, world"` + +--- + +**Author:** Flight +**Requested by:** Dina (via Brady) +**Date:** 2026-03-16 diff --git a/docs/src/content/docs/guide/extensibility.md b/docs/src/content/docs/guide/extensibility.md new file mode 100644 index 000000000..e830e0954 --- /dev/null +++ b/docs/src/content/docs/guide/extensibility.md @@ -0,0 +1,559 @@ +# Extensibility guide + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +When you have an idea to improve Squad, where does it belong? Should it live in Squad core, become a marketplace plugin, or just be team configuration in your `.squad/` directory? + +This guide helps you self-sort. Most ideas don't need core changes — they can be expressed as **skills**, **ceremonies**, or **directives** in your team's configuration or shared as plugins for others to use. + +--- + +## The three-layer extensibility model + +Squad is designed with a small core and large configuration surface. Here's how change ideas map to each layer: + +| Layer | What lives here | Who changes it | Distribution | +|-------|----------------|----------------|--------------| +| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol, eager execution, core orchestration | Squad maintainers only | npm releases | +| **Squad Extension** | Reusable patterns any team could adopt — skills, ceremonies, workflows | Plugin authors | Marketplace plugins | +| **Team Configuration** | Decisions unique to THIS team's process | The team itself | Per-repo `.squad/` files | + +**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives. + +--- + +## Decision tree: Where does your idea belong? + +Start here when you have a change idea: + +``` +┌─ Does your idea change HOW the coordinator routes work, +│ spawns agents, or enforces core protocols? +│ +├─ YES → Likely Squad Core +│ └─ Examples: +│ • New coordinator modes (triage, assign, execute) +│ • Changes to reviewer approval rules +│ • New agent spawning strategies +│ • Core orchestration protocol changes +│ └─ Action: Open an RFC issue to discuss with maintainers +│ +└─ NO → Continue... + │ + ┌─ Could OTHER teams benefit from this pattern? + │ + ├─ YES → Squad Extension (plugin) + │ └─ Examples: + │ • Reusable workflows (client-delivery, research sprints) + │ • Domain-specific skills (cloud platforms, testing strategies) + │ • Ceremony templates (design reviews, post-mortems) + │ └─ Action: Build a plugin, share in marketplace + │ + └─ NO → Team Configuration + └─ Examples: + • YOUR team's git workflow + • YOUR team's approval rules + • YOUR project's build process + • Agent charters specific to YOUR domain + └─ Action: Update `.squad/` files in your repo +``` + +**Quick heuristic:** If your idea starts with "Squad should...", check if it's really "My team should..." or "Teams using pattern X should...". That distinction determines the layer. + +--- + +## Layer 1: Squad Core + +**What lives here:** +- Coordinator modes (`triage`, `assign`, `execute`) +- Work routing logic (how issues are matched to agents) +- Reviewer protocol (how approvals work, blocking conditions) +- Eager execution behavior +- Agent spawning and lifecycle management +- Core orchestration protocol + +**Who changes it:** +Squad maintainers only. + +**When to propose a core change:** +- You need a NEW coordinator mode or routing strategy +- You need to change HOW reviewers approve work +- You need to add enforcement rules that all squads must follow +- Your idea changes the fundamental orchestration model + +**Examples of core changes:** +- ✅ Adding a `validate` coordinator mode that runs checks before `assign` +- ✅ Changing reviewer protocol to support conditional approvals +- ✅ Adding agent capability declarations to enable better routing +- ❌ Adding a specific workflow for your team (this is Layer 3) +- ❌ Creating a reusable research sprint pattern (this is Layer 2) + +**How to propose a core change:** +1. Open an RFC issue in the Squad repository +2. Explain the problem you're solving +3. Show why it can't be expressed as a skill, ceremony, or directive +4. Describe the proposed coordinator or protocol change +5. Wait for maintainer feedback before implementing + +--- + +## Layer 2: Squad Extensions (plugins) + +**What lives here:** +- Reusable skills any team could adopt +- Ceremony templates for common workflows +- Workflow patterns (planning loops, review cycles, research sprints) +- Domain-specific expertise (cloud platforms, testing, security) + +**Who creates them:** +Plugin authors — anyone in the community. + +**How they're distributed:** +Marketplace plugins via GitHub repositories (like `github/awesome-copilot`). + +**When to build a plugin:** +- Your idea solves a problem MANY teams face +- It's a pattern, not a one-off configuration +- You want to share it with the community +- It doesn't require coordinator changes + +**Examples of plugins:** +- ✅ `client-delivery-workflow` — discovery interviews, research sprints, multi-round review +- ✅ `azure-cloud-platform` — skills for Azure deployment, monitoring, cost optimization +- ✅ `tdd-workflow` — ceremony templates for test-driven development cycles +- ✅ `security-review-ceremony` — OWASP checklist, threat modeling, pen-test protocols +- ❌ YOUR team's specific git branch naming rules (this is Layer 3) +- ❌ Changes to how the coordinator spawns agents (this is Layer 1) + +**Plugin structure:** +``` +your-plugin/ +├── README.md # What it does, how to use it +├── skills/ +│ ├── skill-name/ +│ │ └── SKILL.md # Skill definition +├── ceremonies/ +│ └── ceremony-name.md # Ceremony template +└── directives/ + └── directive-name.md # Team directive template +``` + +**How to build and share a plugin:** +1. Create a GitHub repository for your plugin +2. Structure it with skills, ceremonies, or directives +3. Write clear documentation (what problem it solves, how to install, how to use) +4. Submit to a marketplace (e.g., `github/awesome-copilot`) +5. Teams install with: `squad plugin install {owner/repo/plugin-name}` + +**Installing a plugin:** +```bash +squad plugin marketplace add github/awesome-copilot +squad plugin install github/awesome-copilot/client-delivery-workflow +``` + +--- + +## Layer 3: Team Configuration + +**What lives here:** +- Skills specific to YOUR project +- Ceremonies unique to YOUR team's process +- Directives expressing YOUR team's decisions +- Agent charters for YOUR domain +- Routing rules for YOUR issue labels + +**Who changes it:** +The team itself — these are per-repo configuration files. + +**When to use team configuration:** +- This decision is unique to YOUR team +- Other teams wouldn't benefit from this pattern +- You're configuring existing Squad primitives, not adding new ones +- You're expressing team process, not changing core behavior + +**Examples of team configuration:** +- ✅ A skill for YOUR project's build system (`SKILL.md` in `.squad/skills/our-build-process/`) +- ✅ A ceremony for YOUR team's weekly planning meeting (`.squad/ceremonies.md`) +- ✅ Routing rules for YOUR issue labels (`.squad/routing.md`) +- ✅ Agent charters for YOUR domain experts (`.squad/agents/{name}/charter.md`) +- ❌ A reusable workflow pattern (this is Layer 2) +- ❌ Changes to coordinator routing logic (this is Layer 1) + +**How to add team configuration:** + +**Add a skill:** +```bash +mkdir -p .squad/skills/my-skill +cat > .squad/skills/my-skill/SKILL.md << 'EOF' +--- +name: "my-skill" +description: "What this skill does" +domain: "category" +confidence: "high" +source: "team-decision" +--- + +## Context +[Explain when to use this skill] + +## Steps +1. Do this +2. Then this +3. Finally this +EOF +``` + +**Add a ceremony:** +Edit `.squad/ceremonies.md` to add a new ceremony block: +```markdown +## My Team Meeting + +| Field | Value | +|-------|-------| +| **Trigger** | manual | +| **When** | before | +| **Condition** | weekly sprint planning | +| **Facilitator** | lead | +| **Participants** | all | +| **Time budget** | focused | +| **Enabled** | ✅ yes | + +**Agenda:** +1. Review last week's work +2. Assign this week's issues +3. Identify blockers +``` + +**Add a directive:** +Write to `.squad/decisions/inbox/{agent}-{slug}.md`: +```markdown +# Decision: Always use TypeScript strict mode + +**Context:** We've had runtime type errors slip through. + +**Decision:** All new code must use `"strict": true` in tsconfig.json. + +**Rationale:** Catches type errors at compile time, reduces production bugs. + +**Applies to:** All agents writing TypeScript. +``` + +The Scribe will merge it into `.squad/decisions.md`. + +--- + +## The Claire test: A worked example + +[Claire Novotny's RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow with discovery interviews, research sprints, multi-round review, and evidence-backed implementation gates. It felt like a big feature request. + +**The realization:** It maps ENTIRELY to existing Squad primitives. No core changes needed. + +### What Claire wanted + +- Discovery interviews before implementation +- Research sprints when the direction is unclear +- Multi-round plan review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts +- Evidence bundles proving implementation quality +- Local workflow artifacts (research briefs, scoring matrices, task graphs) + +### Where it actually belongs + +**Layer 2: Squad Extension (plugin)** + +Claire's workflow is a REUSABLE PATTERN any team could adopt. It's perfect as a marketplace plugin. + +**Plugin structure:** +``` +client-delivery-workflow/ +├── README.md +├── skills/ +│ ├── discovery-interview/SKILL.md +│ ├── research-sprint/SKILL.md +│ └── evidence-bundler/SKILL.md +├── ceremonies/ +│ ├── plan-review.md +│ └── implementation-review.md +└── directives/ + └── multi-round-review-policy.md +``` + +**Skills define the work:** +- `discovery-interview` — Clarify rough requests, extract requirements, produce a context pack +- `research-sprint` — Propose multiple directions, score them, recommend the best option +- `evidence-bundler` — Collect test results, logs, screenshots proving implementation quality + +**Ceremonies define the gates:** +- `plan-review` — Before implementation starts, reviewers approve or request changes +- `implementation-review` — After implementation, reviewers verify evidence and approve + +**Directives define the rules:** +- Multi-round review policy: up to 2 `NEEDS_WORK` rounds with the same author, forced reassignment on the 3rd rejection + +**How teams use it:** +```bash +# Install the plugin +squad plugin install github/awesome-copilot/client-delivery-workflow + +# The plugin adds skills, ceremonies, and directives to your team +# Agents automatically use them when appropriate +``` + +**What DOESN'T need core changes:** +- ❌ New coordinator modes (existing `assign` and `execute` modes work fine) +- ❌ New orchestration protocols (skills and ceremonies handle the workflow) +- ❌ Changes to reviewer approval rules (directives express the policy) + +**Lesson learned:** Most sophisticated workflows are COMPOSITIONS of primitives, not core features. + +--- + +## When to escalate to core + +Sometimes a change idea DOES need core work. Here are the signals: + +### You likely need a core change if: + +**1. You need a new coordinator mode** +- Example: A `validate` mode that runs checks before `assign` +- Why core: Coordinator modes are part of Squad's orchestration protocol + +**2. You need to change routing logic** +- Example: Route based on agent workload, not just labels +- Why core: Routing is a coordinator responsibility + +**3. You need to change reviewer protocol** +- Example: Support conditional approvals ("approved if tests pass") +- Why core: Reviewer approval is a core enforcement mechanism + +**4. You need to add global enforcement rules** +- Example: Block merges if required evidence is missing +- Why core: Enforcement rules are part of the orchestration protocol + +**5. Your skill needs data the coordinator doesn't expose** +- Example: Access to agent spawn history or routing decisions +- Why core: Skills run in agent context; they can't see coordinator state + +### You DON'T need a core change if: + +**1. You're defining a workflow pattern** +- ❌ Not core: "Discovery interview → research sprint → plan review → implementation" +- ✅ Solution: Express as a plugin with skills and ceremonies + +**2. You're adding domain expertise** +- ❌ Not core: "Azure deployment best practices" +- ✅ Solution: Write a skill or share a plugin + +**3. You're expressing team process** +- ❌ Not core: "Our team requires design reviews before multi-agent tasks" +- ✅ Solution: Add a ceremony to `.squad/ceremonies.md` + +**4. You're creating reusable templates** +- ❌ Not core: "A ceremony template for security reviews" +- ✅ Solution: Build a plugin with ceremony templates + +**5. You're configuring existing behavior** +- ❌ Not core: "Route issues labeled `bug` to our QA agent" +- ✅ Solution: Update `.squad/routing.md` + +--- + +## How to build a plugin + +Building a Squad plugin is straightforward. Plugins are just collections of skills, ceremonies, and directives packaged for reuse. + +### 1. Create a GitHub repository + +```bash +mkdir squad-plugin-my-workflow +cd squad-plugin-my-workflow +git init +``` + +### 2. Add a README + +Explain what problem your plugin solves, how to install it, and how to use it. + +```markdown +# My Workflow Plugin + +Adds discovery interviews, research sprints, and multi-round review to Squad teams. + +## Installation + +squad plugin marketplace add github/awesome-copilot +squad plugin install github/awesome-copilot/my-workflow + +## Usage + +When you assign work to your squad, agents will automatically: +1. Conduct discovery interviews to clarify requirements +2. Run research sprints when the direction is unclear +3. Gate implementation on plan approval +4. Collect evidence bundles proving quality +``` + +### 3. Add skills + +Create a `skills/` directory with one subdirectory per skill: + +``` +skills/ +├── discovery-interview/ +│ └── SKILL.md +├── research-sprint/ +│ └── SKILL.md +└── evidence-bundler/ + └── SKILL.md +``` + +Each `SKILL.md` follows the Squad skill format: +```markdown +--- +name: "discovery-interview" +description: "Clarify rough requests before implementation" +domain: "planning" +confidence: "high" +source: "plugin" +--- + +## Context +When a user's request is vague or incomplete, run a discovery interview. + +## Steps +1. Ask clarifying questions +2. Extract requirements +3. Produce a context pack +``` + +### 4. Add ceremonies + +Create a `ceremonies/` directory with one file per ceremony: + +``` +ceremonies/ +├── plan-review.md +└── implementation-review.md +``` + +Each ceremony follows the Squad ceremony format: +```markdown +## Plan Review + +| Field | Value | +|-------|-------| +| **Trigger** | auto | +| **When** | before | +| **Condition** | implementation starts | +| **Facilitator** | lead | +| **Participants** | all-relevant | +| **Time budget** | focused | +| **Enabled** | ✅ yes | + +**Agenda:** +1. Review solution plan +2. Review work plan +3. Approve or request changes +4. Verdict: SHIP, NEEDS_WORK, or BLOCKED +``` + +### 5. Add directives (optional) + +If your plugin includes team policy recommendations, add them to `directives/`: + +``` +directives/ +└── multi-round-review-policy.md +``` + +### 6. Share in a marketplace + +Submit your plugin to a marketplace repository (like `github/awesome-copilot`) via pull request. Maintainers will review and merge. + +**For detailed plugin authoring guidance, see the [Plugin Marketplace documentation](./../concepts/plugin-marketplace.md).** + +--- + +## Examples for each layer + +### Layer 1: Squad Core + +**Example 1: Add a `validate` coordinator mode** +- **Problem:** Before assigning work, teams want to run automated checks (lint, build, tests) +- **Why core:** This adds a new coordinator mode that runs BEFORE `assign` +- **Solution:** Core change required — new mode in coordinator + +**Example 2: Support conditional reviewer approvals** +- **Problem:** Reviewers want to say "approved IF tests pass" +- **Why core:** This changes the reviewer approval protocol +- **Solution:** Core change required — extend reviewer logic + +**Example 3: Route based on agent workload** +- **Problem:** Avoid overloading one agent by routing to the least-busy agent +- **Why core:** This changes routing logic in the coordinator +- **Solution:** Core change required — update routing algorithm + +### Layer 2: Squad Extensions (plugins) + +**Example 1: `client-delivery-workflow` plugin** +- **Problem:** Teams want discovery interviews, research sprints, multi-round review +- **Why plugin:** This is a reusable workflow pattern any team could adopt +- **Contents:** Skills (discovery, research, evidence), ceremonies (plan review, implementation review), directives (review policy) + +**Example 2: `azure-platform` plugin** +- **Problem:** Teams deploying to Azure need skills for infrastructure, monitoring, cost optimization +- **Why plugin:** This is domain-specific expertise many teams need +- **Contents:** Skills (deploy to AKS, set up Application Insights, optimize costs) + +**Example 3: `tdd-workflow` plugin** +- **Problem:** Teams practicing TDD want structured red-green-refactor cycles +- **Why plugin:** This is a reusable testing workflow +- **Contents:** Ceremony templates (test review, refactor review), skills (generate failing tests, refactor safely) + +### Layer 3: Team Configuration + +**Example 1: Add a skill for YOUR build system** +- **Problem:** Your project uses a custom build pipeline +- **Why team config:** This is specific to YOUR project, not reusable +- **Location:** `.squad/skills/our-build-process/SKILL.md` + +**Example 2: Add a ceremony for YOUR weekly planning** +- **Problem:** Your team has a weekly sprint planning meeting +- **Why team config:** This is YOUR team's process, not a generic pattern +- **Location:** `.squad/ceremonies.md` (add a new ceremony block) + +**Example 3: Route issues to YOUR QA agent** +- **Problem:** Issues labeled `bug` should go to your QA specialist +- **Why team config:** This is YOUR team's routing rule +- **Location:** `.squad/routing.md` (add a routing rule) + +**Example 4: Agent charter for YOUR domain** +- **Problem:** You have a domain expert (e.g., database specialist) +- **Why team config:** This charter is specific to YOUR project +- **Location:** `.squad/agents/{name}/charter.md` + +--- + +## Summary: Self-sorting your change idea + +1. **Start with the decision tree** — Most ideas are Layer 2 or Layer 3. +2. **Default to team configuration** — If it's unique to your team, put it in `.squad/`. +3. **Build a plugin if it's reusable** — If other teams would benefit, package it and share it. +4. **Escalate to core only when primitives aren't enough** — If you need new coordinator modes, routing logic, or enforcement rules, open an RFC. + +**Key insight:** Squad core is intentionally small. The power is in composition — skills, ceremonies, and directives can express sophisticated workflows without core changes. + +**When in doubt:** Start with team configuration. If you find yourself copy-pasting it to other teams, promote it to a plugin. If you find plugins repeatedly hitting the same limitation, that's a signal for a core change. + +--- + +## Related documentation + +- [Plugin Marketplace](./../concepts/plugin-marketplace.md) — How to browse, install, and share plugins +- [Skills](./../concepts/skills.md) — How to write skills for your team or plugins +- [Ceremonies](./../concepts/ceremonies.md) — How to define team meetings and gates +- [Routing](./../concepts/routing.md) — How to configure work assignment rules +- [Contributing](./contributing.md) — How to propose changes to Squad core + +--- + +**Questions?** [Open an issue](https://github.com/bradygaster/squad/issues/new) or join the discussion in the Squad community. diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 5d9adcee8..174ea3c44 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -17,7 +17,7 @@ const DIST_DIR = join(DOCS_DIR, 'dist'); // Expected content directories in src/content/docs/ const EXPECTED_GET_STARTED = ['choose-your-interface', 'first-session', 'installation', 'migration']; -const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq']; +const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq', 'extensibility']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];