diff --git a/.copilot/mcp-config.json b/.copilot/mcp-config.json index ff2159ec1..50e82ac41 100644 --- a/.copilot/mcp-config.json +++ b/.copilot/mcp-config.json @@ -1,15 +1,16 @@ { "mcpServers": { - "EXAMPLE-trello": { + "azure-devops": { "command": "npx", "args": [ "-y", - "@trello/mcp-server" - ], - "env": { - "TRELLO_API_KEY": "${TRELLO_API_KEY}", - "TRELLO_TOKEN": "${TRELLO_TOKEN}" - } + "@azure-devops/mcp", + "msft-skilling" + ] + }, + "powerbi-remote": { + "type": "http", + "url": "https://api.fabric.microsoft.com/v1/mcp/powerbi" } } -} +} diff --git a/.squad/agents/eecom/history.md b/.squad/agents/eecom/history.md index 51f9021d5..46fb7dbf0 100644 --- a/.squad/agents/eecom/history.md +++ b/.squad/agents/eecom/history.md @@ -80,3 +80,11 @@ CLI completeness audit (2026-03-08) confirmed: 26 primary commands routed in cli **PR:** #417 opened targeting dev. +### PR Review Pattern — Description vs Diff Mismatch (2026-03-16) + +**Pattern:** Always verify PR body/title matches actual diff content before reviewing. Use `gh pr diff` + `gh api repos/{owner}/{repo}/pulls/{number}/files` to get file list, then cross-reference with PR description. + +**Learned from:** PR #434 review — body described "Agent-inclusive SDLC paper (~3,800 words)" but actual diff contained PAO external comms infrastructure (skills, templates, SQL schema). Branch name was `squad/agent-sdlc-paper` but no paper file in diff. Posted ⚠️ Needs Clarity review requesting alignment. + +**Review efficiency:** For docs PRs, check line count (`+394` lines) against "small, strategic" preference. PR #435 (agent on-disk anatomy) at 394 lines was borderline but justified for foundational concept doc. Flag verbosity concerns explicitly in review. + diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index cd735f17a..7232a31a8 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/`. + +### PR Review Patterns (2026-03-16) +**Scope discipline:** Apply "Squad Ships It" test rigorously — reject PRs mixing runtime code with IRL content (knowledge library, book material). **Verbosity threshold for docs:** Brady prefers small, strategic changes. Flag docs PRs >400-500 lines as "too verbose" — compress examples, remove redundancy, target 50-60% reduction. **Cross-branch pollution:** Watch for history files with 900+ lines from unrelated branches (Fenster history in a PAO PR = rebase artifact). **Worktree artifacts:** `.worktrees/` submodule commits are pollution, not features — flag for removal. **Infrastructure vs features:** Large infra PRs (PAO comms with templates, tests, audit) are appropriate if they establish new capabilities with proper gates. + diff --git a/.squad/agents/pao/history.md b/.squad/agents/pao/history.md index 71cdfefe3..b95a8ea94 100644 --- a/.squad/agents/pao/history.md +++ b/.squad/agents/pao/history.md @@ -29,3 +29,6 @@ External tool integrations require explicit "where to get it" guidance. Placehol ### Cross-Org Authentication Docs Problem/solution structure for multi-account auth: gh auth switch, Copilot instructions, Squad skill pattern. Cover credential helpers, EMU variations, common error messages. Cross-reference in troubleshooting and enterprise-platforms pages. +### Extensibility Guide Three-Layer Model +Created comprehensive extensibility guide showing users WHERE their change idea belongs. Three layers: Squad Core (coordinator/protocol), Squad Extension (marketplace plugins), Team Configuration (.squad/ files). Decision tree helps self-sorting. Used Claire's RFC #328 as worked example — sophisticated client-delivery workflow maps entirely to existing primitives (skills + ceremonies + directives) without core changes. Key principle: Squad core stays small. Most ideas are composition, not coordinator changes. Doc includes escalation signals, plugin build guide, concrete examples for each layer. + diff --git a/.squad/decisions/inbox/pao-extensibility-guide.md b/.squad/decisions/inbox/pao-extensibility-guide.md new file mode 100644 index 000000000..4bb073351 --- /dev/null +++ b/.squad/decisions/inbox/pao-extensibility-guide.md @@ -0,0 +1,60 @@ +# Decision: Three-layer extensibility model + +**Date:** 2026-03-16 +**Author:** PAO +**Context:** Claire's RFC #328 revealed users need guidance on WHERE their change ideas belong. + +## The model + +Squad uses a three-layer extensibility model: + +1. **Squad Core** — Coordinator behavior, routing, reviewer protocol, eager execution + - Changed by: Squad maintainers only + - Distributed via: npm releases + +2. **Squad Extension** — Reusable patterns (skills, ceremonies, workflows) + - Created by: Plugin authors + - Distributed via: Marketplace plugins + +3. **Team Configuration** — Decisions unique to THIS team + - Changed by: The team itself + - Lives in: `.squad/` files per-repo + +## Key principle + +**Squad core stays small. Most ideas are skills, ceremonies, or directives.** + +## Decision tree + +When someone has a change idea: +- Does it change HOW the coordinator routes work, spawns agents, or enforces core protocols? → Layer 1 (Core) +- Could OTHER teams benefit from this pattern? → Layer 2 (Extension/plugin) +- Is this unique to THIS team's process? → Layer 3 (Team config) + +## The Claire test + +Claire's RFC #328 proposed a sophisticated client-delivery workflow with discovery interviews, research sprints, and multi-round review. It FELT like a core feature. + +**Realization:** It maps entirely to existing primitives: +- Skills: `discovery-interview`, `research-sprint`, `evidence-bundler` +- Ceremonies: `plan-review`, `implementation-review` +- Directives: Multi-round review policy + +No core changes needed. It's a Layer 2 plugin. + +## Escalation signals + +You likely need a core change if: +- You need a new coordinator mode +- You need to change routing logic +- You need to change reviewer protocol +- You need global enforcement rules +- Your skill needs coordinator state data + +## Documentation + +Comprehensive guide at `docs/guide/extensibility.md` with decision tree, examples, plugin build instructions. + +## Applies to + +All team members, contributors, and users proposing changes. 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/guide/building-extensions.md b/docs/src/content/docs/guide/building-extensions.md new file mode 100644 index 000000000..15503f3c3 --- /dev/null +++ b/docs/src/content/docs/guide/building-extensions.md @@ -0,0 +1,126 @@ +# Building extensions + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +You've decided your idea is a Squad Extension (Layer 2). Now build one in five minutes. + +--- + +## What is an extension? + +An extension is a reusable collection of skills, ceremonies, and directives that any team can install. It lives outside Squad core, packaged as a GitHub repository or marketplace plugin. Extensions let you codify workflows (Claire's client-delivery pattern), domain expertise (Azure deployment strategies), or testing ceremonies that other teams benefit from. + +--- + +## Extension structure + +``` +my-extension/ +├── skills/ +│ ├── SKILL1.md +│ └── SKILL2.md +├── ceremonies/ +│ └── CEREMONY.md +├── directives/ +│ └── DIRECTIVE.md +└── README.md +``` + +--- + +## Build one + +**Step 1: Create a repo** + +```bash +mkdir my-extension +cd my-extension +git init +``` + +**Step 2: Add a skill** + +Create `skills/example-skill.md`: + +```markdown +# Example Skill + +**When to use:** You need to do X. + +## Context + +Brief problem statement. + +## Steps + +1. Do the first thing +2. Do the second thing +3. Done +``` + +**Step 3 (optional): Add a ceremony** + +Create `ceremonies/code-review.md` following Squad ceremony format (decision gate, verdicts, escalation). + +**Step 4: Write the README** + +Explain the problem, installation, and usage: + +```markdown +# My Extension + +Codifies client-delivery workflows for consulting teams. + +## Install + +squad plugin install github/my-org/my-extension + +## What's Inside + +- **discovery-interview** skill — clarify requirements +- **evidence-bundler** skill — collect test results +- **plan-review** ceremony — gate for approval +``` + +**Step 5: Test locally** + +Copy your extension directory into `.squad/skills/`, `.squad/ceremonies/`, and `.squad/directives/`. Load your Squad session and verify the skills appear and work as expected. + +--- + +## Share it + +Push to GitHub: + +```bash +git add . +git commit -m "Initial extension: my-extension" +git push +``` + +Register with a marketplace or pin directly by repository URL: + +``` +squad plugin install github/my-org/my-extension +``` + +--- + +## Real examples + +- **Claire's client-delivery workflow** ([RFC #328](https://github.com/bradygaster/squad/issues/328)) — discovery, research, multi-round review with evidence gates +- **Azure infrastructure patterns** — VM provisioning, Cosmos DB design, monitoring rules +- **Knowledge library skills** — document structured analysis, reference synthesis + +--- + +## Related docs + +- [Extensibility guide](./extensibility.md#decision-tree) — Where does your idea belong? (decision tree) +- [Plugin Marketplace](../features/plugins.md) — How teams discover and install your extension +- [Skills](../concepts/skills.md) — How to author reusable skills +- [Ceremonies](../concepts/ceremonies.md) — How to define decision gates and review rituals + +--- + +**Ready to share?** [Open a discussion](https://github.com/bradygaster/squad/discussions) in the Squad community. diff --git a/docs/src/content/docs/guide/extensibility.md b/docs/src/content/docs/guide/extensibility.md new file mode 100644 index 000000000..28bd0b0e2 --- /dev/null +++ b/docs/src/content/docs/guide/extensibility.md @@ -0,0 +1,141 @@ +# Extensibility guide + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + +Where does your change idea belong? Squad core, marketplace plugin, or team config? + +**Key principle:** Squad core stays small. Most ideas are skills, ceremonies, or directives. + +--- + +## The three layers + +| Layer | What lives here | Who changes it | Distribution | +|-------|----------------|----------------|--------------| +| **Squad Core** | Coordinator behavior, routing logic, reviewer protocol | Squad maintainers only | npm releases | +| **Squad Extension** | Reusable patterns (skills, ceremonies, workflows) | Plugin authors | Marketplace plugins | +| **Team Configuration** | Decisions unique to THIS team | The team itself | `.squad/` files | + +--- + +## Decision tree + +``` +┌─ Does it change HOW the coordinator routes, spawns, or enforces? +│ +├─ YES → Squad Core +│ └─ Examples: New coordinator modes, reviewer protocol changes +│ Action: Open an RFC issue +│ +└─ NO → Continue... + │ + ┌─ Could OTHER teams benefit? + │ + ├─ YES → Squad Extension (plugin) + │ └─ Examples: Client-delivery workflow, Azure skills, TDD ceremonies + │ Action: Build a plugin + │ + └─ NO → Team Configuration + └─ Examples: YOUR git workflow, YOUR build process, YOUR routing rules + Action: Update `.squad/` files +``` + +**Heuristic:** "Squad should..." → check if it's really "My team should..." or "Teams using X should...". + + + +--- + +## Worked example: Claire's RFC + +[Claire's RFC #328](https://github.com/bradygaster/squad/issues/328) proposed a sophisticated client-delivery workflow: discovery interviews, research sprints, multi-round review with `SHIP`/`NEEDS_WORK`/`BLOCKED` verdicts, evidence bundles. + +**The realization:** It maps entirely to existing Squad primitives. No core changes needed. + +**Where it belongs:** Layer 2 (Squad Extension) + +Claire's workflow is a reusable pattern any team could adopt — perfect as a marketplace plugin. + +**Plugin structure:** +``` +client-delivery-workflow/ +├── skills/ +│ ├── discovery-interview/ # Clarify requests, extract requirements +│ ├── research-sprint/ # Propose directions, score options +│ └── evidence-bundler/ # Collect test results, logs, screenshots +├── ceremonies/ +│ ├── plan-review.md # Gate: approve before implementation +│ └── implementation-review.md # Gate: verify evidence +└── directives/ + └── multi-round-review.md # Policy: 2 NEEDS_WORK rounds max +``` + +**Usage:** +```bash +squad plugin install github/awesome-copilot/client-delivery-workflow +``` + +**Lesson:** Most sophisticated workflows are compositions of primitives, not core features. + +--- + +## When to escalate to core + +You likely need a core change if: + +- **New coordinator mode** — Example: `validate` mode that runs checks before `assign` +- **Routing logic change** — Example: Route based on agent workload, not labels +- **Reviewer protocol change** — Example: Conditional approvals ("approved if tests pass") +- **Global enforcement rule** — Example: Block merges if evidence missing +- **Skill needs coordinator data** — Example: Access to agent spawn history + +You DON'T need core if: + +- **Workflow pattern** → Build a plugin (skills + ceremonies) +- **Domain expertise** → Write a skill +- **Team process** → Add a ceremony to `.squad/ceremonies.md` +- **Reusable templates** → Build a plugin +- **Configuring existing behavior** → Update `.squad/routing.md` + +--- + +## Quick start: Building a plugin + +1. Create a GitHub repo with `skills/`, `ceremonies/`, `directives/` directories +2. Add skills as `SKILL.md` files (frontmatter + context + steps) +3. Add ceremonies following Squad ceremony format +4. Write a README explaining problem/install/usage +5. Submit to marketplace (e.g., `github/awesome-copilot`) + +**Installation:** +```bash +squad plugin marketplace add github/awesome-copilot +squad plugin install github/awesome-copilot/your-plugin +``` + +**See [Plugin Marketplace docs](./../concepts/plugin-marketplace.md) for details.** + +--- + +## Summary + +1. **Start with the decision tree** — Most ideas are Layer 2 or 3 +2. **Default to team config** — Unique to your team? → `.squad/` +3. **Build a plugin if reusable** — Other teams benefit? → Package and share +4. **Escalate to core rarely** — Need coordinator/routing changes? → Open an RFC + +**When in doubt:** Start with team config. Copy-pasting to other teams? Promote to plugin. Plugins repeatedly hitting limits? Signal for 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..c43b1e40c 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', 'building-extensions']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];