diff --git a/.changeset/dual-mode-capabilities.md b/.changeset/dual-mode-capabilities.md new file mode 100644 index 000000000..497aeda5c --- /dev/null +++ b/.changeset/dual-mode-capabilities.md @@ -0,0 +1,12 @@ +--- +'@bradygaster/squad-sdk': minor +--- + +Add dual-mode deployment support for capabilities routing. + +New features: +- `SQUAD_POD_ID` env var for pod-specific capability manifests +- `SQUAD_DEPLOYMENT_MODE` env var (`agent-per-node` | `squad-per-pod`) +- Pod-specific manifest loading: `.squad/machine-capabilities-{podId}.json` +- Fallback chain: pod-specific → shared → user-home → null (opt-in) +- New exports: `getDeploymentMode()`, `getPodId()`, `DeploymentMode` type diff --git a/.changeset/error-recovery-skill.md b/.changeset/error-recovery-skill.md new file mode 100644 index 000000000..ec48a85a3 --- /dev/null +++ b/.changeset/error-recovery-skill.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor +--- +feat: add error-recovery skill for standard agent failure recovery patterns \ No newline at end of file diff --git a/.changeset/iterative-retrieval-skill.md b/.changeset/iterative-retrieval-skill.md new file mode 100644 index 000000000..8a1e8fc4c --- /dev/null +++ b/.changeset/iterative-retrieval-skill.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor +--- +feat: add iterative-retrieval skill for structured max-3-cycle agent spawning \ No newline at end of file diff --git a/.changeset/notification-routing-skill.md b/.changeset/notification-routing-skill.md new file mode 100644 index 000000000..7f71556f3 --- /dev/null +++ b/.changeset/notification-routing-skill.md @@ -0,0 +1,6 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor +--- + +feat: add notification-routing skill for pub-sub channel routing \ No newline at end of file diff --git a/.changeset/ralph-two-pass-scan-skill.md b/.changeset/ralph-two-pass-scan-skill.md new file mode 100644 index 000000000..35a7ff21d --- /dev/null +++ b/.changeset/ralph-two-pass-scan-skill.md @@ -0,0 +1,4 @@ +--- +--- + +Add ralph-two-pass-scan skill — lightweight issue list scan before selective hydration, cutting Ralph's GitHub API calls by ~72% per round (resolves #596) diff --git a/.changeset/reflect-skill.md b/.changeset/reflect-skill.md new file mode 100644 index 000000000..1263013b1 --- /dev/null +++ b/.changeset/reflect-skill.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor +--- +feat: add reflect skill for in-session learning capture and mistake prevention \ No newline at end of file diff --git a/.changeset/retro-enforcement.md b/.changeset/retro-enforcement.md new file mode 100644 index 000000000..1cc4d4ee3 --- /dev/null +++ b/.changeset/retro-enforcement.md @@ -0,0 +1,12 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": patch +--- + +Add retro enforcement skill with Test-RetroOverdue and ceremonies template update. + +- New skill: retro-enforcement - coordinator integration pattern for automated retro cadence enforcement +- Action items tracked as GitHub Issues (not markdown checklists) +- Production data: 0% to 100% completion rate after switching formats +- Test-RetroOverdue PowerShell function detects overdue retros and blocks work queue +- Ceremonies template updated with enforcement-aware retrospective definition diff --git a/.changeset/tiered-memory.md b/.changeset/tiered-memory.md new file mode 100644 index 000000000..f2d2336b2 --- /dev/null +++ b/.changeset/tiered-memory.md @@ -0,0 +1,5 @@ +--- +"@bradygaster/squad-cli": minor +"@bradygaster/squad-sdk": minor +--- +feat: add tiered-memory skill for hot/cold/wiki agent context management \ No newline at end of file diff --git a/.changeset/watch-circuit-breaker.md b/.changeset/watch-circuit-breaker.md new file mode 100644 index 000000000..b9b335267 --- /dev/null +++ b/.changeset/watch-circuit-breaker.md @@ -0,0 +1,26 @@ +--- +"@bradygaster/squad-cli": minor +--- + +feat(watch): circuit breaker integration for rate limit protection (#515) + +Adds GitHub API rate limit protection to Ralph's watch command via +the Predictive Circuit Breaker from PR #518. + +**What changed (additive patch — existing flow untouched):** +- `gh-cli.ts`: Added `ghRateLimitCheck()` and `isRateLimitError()` helpers +- `watch.ts`: Added `CircuitBreakerState` type + persistence helpers +- `watch.ts`: Added `executeRound()` wrapper that gates the existing + `runCheck()` call through pre-flight quota checks +- `watch.ts`: Added `roundInProgress` flag to prevent overlapping rounds + +**Circuit breaker state machine:** +- CLOSED → OPEN: When traffic light is red or predictor says exhaustion imminent +- OPEN → HALF-OPEN: After cooldown expires (exponential: 2m → 4m → 8m → ... → 30m cap) +- HALF-OPEN → CLOSED: After 2 consecutive successful rounds +- HALF-OPEN → OPEN: On rate limit error during probe + +State persists to `.squad/ralph-circuit-breaker.json` across restarts. + +**Tests:** 16 new tests covering state transitions, race condition guard, +predictive integration, and `isRateLimitError` detection. diff --git a/.github/PR_REQUIREMENTS.md b/.github/PR_REQUIREMENTS.md new file mode 100644 index 000000000..966211a94 --- /dev/null +++ b/.github/PR_REQUIREMENTS.md @@ -0,0 +1,242 @@ +# PR Requirements — Squad Repository + +> **This file is the canonical source of truth for PR requirements.** +> Issue #106 tracks the PRD; this file is the versioned spec. +> Changes to this file must go through PR review (audit trail). + +--- + +## Definition of "User-Facing Change" + +A PR contains a **user-facing change** if it introduces a CRUD operation to the CLI or SDK layer that is exposed in TypeScript or true executable functionality. + +"User-facing" is anchored to two concrete package boundaries: +- **SDK layer**: `packages/squad-sdk/src/` exports exposed in `package.json` subpath exports +- **CLI layer**: `packages/squad-cli/src/cli/` commands and subcommands + +### CRUD Operations — What Counts as User-Facing + +| Operation | SDK Layer | CLI Layer | +|-----------|-----------|-----------| +| **Create** | New export added to `packages/squad-sdk/src/`; new subpath export added to `package.json` | New CLI command or subcommand added to `packages/squad-cli/src/cli/commands/` | +| **Read** | N/A — reading doesn't change the surface | N/A — reading doesn't change the surface | +| **Update** | Change to existing public API signature (parameters, return types, behavior) | Change to CLI command flags, behavior, or subcommand structure | +| **Delete** | Remove a previously public export from `package.json` | Remove a CLI command or subcommand | + +### What Is NOT User-Facing + +- `.squad/` state files (decisions, history, skills, templates) +- Internal refactors that don't change the public API surface +- Infrastructure (CI, GitHub Actions, workflows) +- Documentation-only changes +- Dependency updates that don't change API surface + +Why this matters: The requirement categories below apply conditionally to user-facing changes. Knowing what counts as user-facing prevents disputes about "does this need a CHANGELOG entry?" + +### Examples of "new module" + +- Adding a new directory under packages/squad-sdk/src/ (e.g., src/storage/, src/casting/) +- Adding a new subpath export to package.json (e.g., ./storage, ./casting) +- Adding a new CLI command file under packages/squad-cli/src/cli/commands/ + +### NOT a new module + +- Adding a new function to an existing module +- Refactoring internals without changing the public API surface +- Adding test files + +--- + +## PR Requirements by Category + +Requirements are ordered by review flow. All marked **REQUIRED** must be satisfied before merge. Some are automatically enforced (CI gates); others require human review. + +### a) Git Hygiene (REQUIRED — automated) + +- [ ] Commits reference the issue number: `Closes #N` or `Part of #N` in commit message +- [ ] No binary files or build artifacts committed (`dist/`, `node_modules/`, `.DS_Store`, etc.) +- [ ] No unrelated file changes (bleed check: only files needed for the stated goal) +- [ ] Clean commit history: logical commits or squashed to a single coherent commit +- [ ] No force-pushes to shared branches (`dev`, `main`) + +**Enforced by**: squad-ci.yml bleed check + git hooks + +### b) CI / Build (REQUIRED — automated) + +- [ ] Build passes: `npm run build` completes successfully +- [ ] All existing tests pass: `npm test` or `npm run test` +- [ ] No new build warnings introduced without justification in PR description +- [ ] Feature flags documented in code and CHANGELOG if gating new behavior + +**Enforced by**: GitHub Actions CI pipeline + +### c) Code Quality (REQUIRED — manual review for completeness, automated for linting) + +- [ ] All new public APIs have JSDoc/TSDoc comments +- [ ] No lint errors: `eslint` passes +- [ ] No type errors: `tsc --noEmit` passes +- [ ] Tests written for all new functionality +- [ ] All tests pass: `vitest` exits 0 + +**Enforced by**: eslint in CI + manual code review + +### d) Documentation (REQUIRED for user-facing changes — manual review) + +- [ ] CHANGELOG.md entry under `[Unreleased]` following Keep-a-Changelog format + - Example: `### Added — FeatureName (#N) — short description` + - Required when: a **user-facing change** (see "Definition of \"User-Facing Change\"") affects the SDK or CLI public surface (e.g., exports in `packages/squad-sdk/src/` or commands in `packages/squad-cli/src/cli/`) +- [ ] README.md section updated if adding a new feature or module to the SDK +- [ ] Docs feature page added under `docs/src/content/docs/features/` if adding a user-facing capability +- [ ] `docs/src/navigation.ts` updated if a new docs page is added +- [ ] Docs build test updated if a new feature page is added (`test/docs-build.test.ts`, run via `npm test`) + +**Enforced by**: Manual PR review (FIDO, Flight) + future automated checks in #104 + +### e) Package / Exports (REQUIRED for new modules — manual review) + +- [ ] `package.json` subpath exports updated when new modules are added + - Both types (`.d.ts`) and import (`.js`) entries required per export + - Example: the `/storage` export was missing from #640 until the audit caught it +- [ ] No accidental dependency additions: `package-lock.json` changes reviewed for unexpected deps +- [ ] No export regressions: existing exports remain present and functional + +**Enforced by**: Manual PR review + future export audit gate in #104 + +### f) Samples (REQUIRED when API changes — manual review) + +- [ ] Existing sample projects updated if the PR changes a public API they use +- [ ] New user-facing features include at least one sample demonstrating usage +- [ ] Sample README.md explains what the sample does and how to run it +- [ ] Samples build and run: `npm run build` in sample directory succeeds + +**Enforced by**: Manual PR review + #103 (Samples CI coverage) + +--- + +## Breaking Change Policy + +Any PR that changes the public API in a backward-incompatible way (removal, signature change, behavior change) must: + +- [ ] Document the breaking change in CHANGELOG.md under a `[BREAKING]` section +- [ ] Add a migration guide as a docs note in the affected feature page +- [ ] Update all sample projects to use the new API +- [ ] Include the migration path in the PR description (`## Breaking Changes` section) + +**Examples of breaking changes:** +- Removing an export that was previously public +- Changing function signature (parameter name, order, type) +- Changing CLI command name or subcommand structure +- Changing configuration file format in backward-incompatible way + +**Examples NOT breaking:** +- Adding new optional parameters +- Adding new exports +- Adding new subcommands (existing ones unchanged) +- Fixing documented behavior that was incorrect + +--- + +## Exception / Waiver Process + +Emergencies (security fixes, critical bugs) require flexibility. Any requirement can be waived if documented and approved. + +### How to Request a Waiver + +Add to PR description under a `## Waivers` section: + +``` +## Waivers + +- Item waived: (d) Documentation CHANGELOG entry +- Reason: Security fix needs urgent release (CVE-2024-XXXXX) +- Approval by: [Flight/FIDO to be stated in PR review comment] +``` + +### Waiver Approval Authority + +- **Flight (architecture decisions)**: Internal refactors, infrastructure, module reorganization +- **FIDO (quality decisions)**: Bug fixes, test improvements, samples, CI changes +- **Both**: External API changes, breaking changes + +### Waiver Approval Examples + +| Scenario | Waivable Items | Approver | +|----------|----------------|----------| +| Internal refactor (no API change) | Documentation, Samples | Flight | +| Security fix | Documentation, Samples (with follow-up issue) | FIDO | +| Test infrastructure change | Documentation, Exports, Samples | FIDO | +| CI/GitHub Actions update | Documentation, Exports, Samples | FIDO | +| Documentation-only change | Code Quality (tests), Exports, Samples | FIDO | +| Non-breaking SDK bugfix | Samples | FIDO | + +### Self-Waiving Is Not Allowed + +- Do NOT use skip labels without explicit reviewer approval in PR comments +- Do NOT remove requirements from checklist without documented waiver +- Do NOT claim "documentation will follow" without a tracked follow-up issue + +--- + +## Edge Case Exemptions + +Certain PR types are categorically exempt from specific requirements by nature. These are **NOT** waivers (no approval needed); they are structural exemptions. + +| PR Type | Exempt From | Reason | +|---------|-------------|--------| +| Internal refactor (no public API change) | (d) Docs, (f) Samples | No user-visible change | +| Test-only changes | (d) Docs, (e) Exports, (f) Samples | No production code changed | +| CI/GitHub Actions workflow changes | (d) Docs, (e) Exports, (f) Samples | Infrastructure only | +| Documentation-only changes | (c) Code Quality (tests), (e) Exports, (f) Samples | No code changes | +| Dependency bumps (routine maintenance) | (d) Docs feature page, (f) Samples | Routine dependency update | + +**Important**: Exemptions apply only when the PR genuinely affects NO code in the exempted categories. A PR touching both infrastructure AND public APIs is NOT exempt. + +--- + +## PR Size Guidelines + +| Size | Files Changed | Guidance | +|------|---------------|----------| +| Small | < 10 files | Preferred. Fast to review, easy to revert. | +| Medium | 10–20 files | Acceptable. Justify scope in PR description. | +| Large | > 20 files | Must be split or justified with written explanation. | +| Red flag | > 50 files | STOP — split the PR or get explicit written approval before proceeding. | + +For migration PRs (> 20 files): include test output summary in the PR description. + +--- + +## Known Limitations + +### 1. Enforceability Gap + +9 of 18 requirements are manual-only with no CI gate (README updates, docs page relevance, sample completeness, migration guide quality). Enforcement depends on consistent reviewer judgment. + +**Automation dependency**: 9 of 18 requirements are manual-only. Issue #104 (PR completeness gates) is the critical path to automated enforcement. Until #104 ships, this spec depends on reviewer discipline. + +**Mitigation**: Phase 4 (Flight/FIDO checklist) codifies consistent judgment. Regular enforcement audits catch drift. + +### 2. Theater Risk + +Calling something "REQUIRED" without automated enforcement creates appearance of rigor without substance. Phase 3 (#104) prioritizes high-leverage automated gates (CHANGELOG, exports, build). Manual-only items are clearly labeled. + +### 3. Silent Drift Risk + +This requirements file is the source of truth. CI gate scripts (#104) and reviewer checklists (#100) must be manually updated if requirements change. Quarterly review cycle to resync. + +### 4. Ambiguities + +- **"Module" definition**: new directory under `packages/squad-sdk/src/` or new export namespace. Refactoring existing module does not trigger export requirement. +- **"User-facing" detection for CHANGELOG**: Currently manual. #104 will implement export-diff detection. + +--- + +## Relationship to Other Issues + +| Issue | Role | +|-------|------| +| #100 (Review completeness) | Defines the review *process* — this file defines *what reviewers check against* | +| #103 (Samples CI coverage) | Implements the "samples" requirement category (f) | +| #104 (PR completeness gates) | Implements automated enforcement of REQUIRED items as CI gates | + +This file is the source of truth. #100 and #104 derive their checklists from it. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..d6203f561 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,30 @@ +### What + + +### Why + + +### How + + +### Testing + +- [ ] `npm run build` passes +- [ ] `npm test` passes (all tests green) +- [ ] For migration PRs (>20 files): test output summary included below + +### Docs + +- [ ] CHANGELOG.md entry (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed) +- [ ] README section updated (if new feature/module) +- [ ] Docs feature page (if new user-facing capability) + +### Exports + +- [ ] package.json subpath exports updated (if new module) + +### Breaking Changes + + +### Waivers + diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 2dfbd0645..655641842 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -95,7 +95,14 @@ The `union` merge driver keeps all lines from both sides, which is correct for a ## Team Mode -**⚠️ CRITICAL RULE: Every agent interaction MUST use the `task` tool to spawn a real agent. You MUST call the `task` tool — never simulate, role-play, or inline an agent's work. If you did not call the `task` tool, the agent was NOT spawned. No exceptions.** +**⚠️ CRITICAL RULE: You are a DISPATCHER, not a DOER. Every task that needs domain expertise MUST be dispatched to a specialist agent — never performed inline.** + +**DISPATCH MECHANISM (detect once per session, then use consistently):** +- **CLI:** `task` tool → use it with agent_type, mode, model, name, description, prompt +- **VS Code:** `runSubagent` tool → use it with the full agent prompt +- **Neither available:** work inline (fallback only — LAST RESORT) + +**If you wrote code, generated artifacts, or produced domain work without dispatching to an agent, you violated this rule. The coordinator ROUTES — it does not BUILD. No exceptions.** **On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Pass the team root into every spawn prompt as `TEAM_ROOT` and the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted. @@ -191,12 +198,12 @@ When spawning agents, include the role emoji in the `description` parameter to m 4. If no match, use 👤 as fallback **Examples:** -- `description: "🏗️ Keaton: Reviewing architecture proposal"` -- `description: "🔧 Fenster: Refactoring auth module"` -- `description: "🧪 Hockney: Writing test cases"` -- `description: "📋 Scribe: Log session & merge decisions"` +- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"` +- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"` +- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"` +- `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"` -The emoji makes task spawn notifications visually consistent with the launch table shown to users. +The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users. ### Directive Capture @@ -246,7 +253,11 @@ The routing table determines **WHO** handles work. After routing, use Response M | Ambiguous | Pick the most likely agent; say who you chose | | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work | -**Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain: +1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first. +2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work. + +If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. ### Consult Mode Detection @@ -314,6 +325,7 @@ After routing determines WHO handles work, select the response MODE based on tas agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -356,8 +368,8 @@ Before spawning an agent, determine which model to use. Check these layers in or | Task Output | Model | Tier | Rule | |-------------|-------|------|------| -| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. | -| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. | +| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. | | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. | | Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. | @@ -365,11 +377,11 @@ Before spawning an agent, determine which model to use. Check these layers in or | Role | Default Model | Why | Override When | |------|--------------|-----|---------------| -| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | -| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | +| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` | +| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | | Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku | | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku | -| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | +| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` | | Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) | | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — | | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) | @@ -378,7 +390,7 @@ Before spawning an agent, determine which model to use. Check these layers in or **Task complexity adjustments** (apply at most ONE — no cascading): - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents) - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps -- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) +- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines) - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced. @@ -388,9 +400,9 @@ Before spawning an agent, determine which model to use. Check these layers in or If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback. ``` -Premium: claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) -Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) -Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param) +Premium: claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (omit model param) ``` `(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works. @@ -408,12 +420,13 @@ Pass the resolved model as the `model` parameter on every `task` tool call: agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | ... ``` -Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default. +Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default. If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely. @@ -422,7 +435,7 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m When spawning, include the model in your acknowledgment: ``` -🔧 Fenster (claude-sonnet-4.5) — refactoring auth module +🔧 Fenster (claude-sonnet-4.6) — refactoring auth module 🎨 Redfoot (claude-opus-4.5 · vision) — designing color system 📋 Scribe (claude-haiku-4.5 · fast) — logging session ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal @@ -433,9 +446,9 @@ Include tier annotation only when the model was bumped or a specialist was chose **Valid models (current platform catalog):** -Premium: `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5` -Standard: `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview` -Fast/Cheap: `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` +Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `claude-opus-4.5` +Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gemini-3-pro-preview` +Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` ### Client Compatibility @@ -726,7 +739,7 @@ e. **Include worktree context in spawn:** ### How to Spawn an Agent -**You MUST call the `task` tool** with these parameters for every agent spawn: +**You MUST dispatch every agent spawn** via the platform's tool (`task` on CLI, `runSubagent` on VS Code): - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access) - **`mode`**: `"background"` (default) or omit for sync — see Mode Selection table above @@ -747,6 +760,7 @@ e. **Include worktree context in spawn:** agent_type: "general-purpose" model: "{resolved_model}" mode: "background" +name: "{name}" description: "{emoji} {Name}: {brief task summary}" prompt: | You are {Name}, the {Role} on this project. @@ -784,7 +798,9 @@ prompt: | Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. If .squad/identity/now.md exists, read it at spawn time. - If .squad/skills/ has relevant SKILL.md files, read them before working. + Check .copilot/skills/ for copilot-level skills (process, workflow, protocol). + Check .squad/skills/ for team-level skills (patterns discovered during work). + Read any relevant SKILL.md files before working. {only if MCP tools detected — omit entirely if none:} MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable. @@ -816,10 +832,10 @@ prompt: | **Never do any of these — they bypass the agent system entirely:** -1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending. -2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond. -3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. -4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right. +1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without dispatching via the platform's tool, that is NOT the agent. That is you (the Coordinator) pretending. +2. **Never simulate agent output.** Don't generate what you think an agent would say. Dispatch to the real agent and let it respond. +3. **Never skip dispatching (via `task` or `runSubagent`) for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn. +4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right. 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict. ### After Agent Work @@ -850,6 +866,7 @@ After each batch of agent work: agent_type: "general-purpose" model: "claude-haiku-4.5" mode: "background" +name: "scribe" description: "📋 Scribe: Log session & merge decisions" prompt: | You are the Scribe. Read .squad/agents/scribe/charter.md. @@ -858,13 +875,15 @@ prompt: | SPAWN MANIFEST: {spawn_manifest} Tasks (in order): - 1. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp. - 2. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp. - 3. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate. - 4. CROSS-AGENT: Append team updates to affected agents' history.md. - 5. DECISIONS ARCHIVE: If decisions.md exceeds ~20KB, archive entries older than 30 days to decisions-archive.md. - 6. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged. - 7. HISTORY SUMMARIZATION: If any history.md >12KB, summarize old entries to ## Core Context. + 0. PRE-CHECK: Stat decisions.md size and count inbox/ files. Record measurements. + 1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step. + 2. DECISION INBOX: Merge .squad/decisions/inbox/ → decisions.md, delete inbox files. Deduplicate. + 3. ORCHESTRATION LOG: Write .squad/orchestration-log/{timestamp}-{agent}.md per agent. Use ISO 8601 UTC timestamp. + 4. SESSION LOG: Write .squad/log/{timestamp}-{topic}.md. Brief. Use ISO 8601 UTC timestamp. + 5. CROSS-AGENT: Append team updates to affected agents' history.md. + 6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now. + 7. GIT COMMIT: git add .squad/ && commit (write msg to temp file, use -F). Skip if nothing staged. + 8. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized. Never speak to user. ⚠️ End with plain text summary after all tool calls. ``` @@ -1004,7 +1023,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not: ## Constraints - **You are the coordinator, not the team.** Route work; don't do domain work yourself. -- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response. +- **Always dispatch to agents via the platform's spawn tool (`task` on CLI, `runSubagent` on VS Code). Never work inline when a dispatch tool is available.** Every agent interaction requires a real dispatch — `task` tool call on CLI, `runSubagent` on VS Code — with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response. - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once. - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent." - **1-2 agents per question, not all of them.** Not everyone needs to speak. @@ -1285,3 +1304,15 @@ The GitHub Copilot coding agent (`@copilot`) can join the Squad as an autonomous - Capability profile (🟢/🟡/🔴) lives in team.md. Lead evaluates issues against it during triage. - Auto-assign controlled by `` in team.md. - Non-dependent work continues immediately — @copilot routing does not serialize the team. + +--- + +## ⚠️ Routing Enforcement Reminder + +You are Squad (Coordinator). Your ONE job is dispatching work to specialist agents. + +✅ You DO: Route, decompose, synthesize results, talk to the user +❌ You DO NOT: Write code, generate designs, create analyses, do domain work + +If you are about to produce domain artifacts yourself — STOP. +Dispatch to the right agent instead. Every time. No exceptions. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index ddc20f12c..f1528d90d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,6 +2,35 @@ You are working on a project that uses **Squad**, an AI team framework. When picking up issues autonomously, follow these guidelines. +## Git Safety — Mandatory Rules + +**These rules are non-negotiable. Violating them risks deleting production source code.** + +### Staging +- ❌ **NEVER** use `git add .` or `git add -A` — these stage unintended deletions from incomplete working trees +- ❌ **NEVER** use `git commit -a` — same risk +- ✅ **ALWAYS** stage specific files: `git add path/to/file1.ts path/to/file2.ts` +- ✅ **ALWAYS** review before committing: run `git diff --cached --stat` and verify the file count matches your intent + +### Pushing +- ❌ **NEVER** push directly to `dev` or `main` — always open a PR +- ❌ **NEVER** force push (`git push --force` or `--force-with-lease`) to shared branches +- ✅ **ALWAYS** work on a feature branch: `git checkout -b squad/{issue-number}-{slug}` +- ✅ **ALWAYS** open a PR: `gh pr create --base dev --draft` + +### Pre-Push Checklist +Before pushing any commit, verify: +1. `git diff --cached --stat` — file count matches intent (expect ≤10 files for most fixes) +2. `git diff --cached --diff-filter=D --name-only` — NO unintended deletions +3. `npm run build` — build succeeds with your changes +4. Commit message references the issue: `Closes #N` + +### Red Flags — STOP and Ask +If you see any of these, STOP immediately and comment on the issue asking for guidance: +- More than 20 files in your diff +- ANY file deletions you didn't explicitly intend +- Changes outside the scope of your assigned issue + ## Team Context Before starting work on any issue: diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml index f3c7d4884..d3003bb92 100644 --- a/.github/workflows/squad-ci.yml +++ b/.github/workflows/squad-ci.yml @@ -66,8 +66,719 @@ jobs: - name: Install Playwright browsers run: npx playwright install chromium --with-deps + - name: "🔒 Source tree canary check" + run: | + echo "Verifying critical source files exist..." + MISSING=0 + for f in \ + "packages/squad-sdk/src/index.ts" \ + "packages/squad-cli/src/cli/index.ts" \ + "packages/squad-sdk/package.json" \ + "packages/squad-cli/package.json"; do + if [ ! -f "$f" ]; then + echo "::error::MISSING critical file: $f" + MISSING=$((MISSING + 1)) + fi + done + if [ $MISSING -gt 0 ]; then + echo "::error::$MISSING critical source files missing — possible accidental deletion" + exit 1 + fi + echo "✅ All critical source files present" + + - name: "🔒 Large deletion guard" + if: github.event_name == 'pull_request' + run: | + DELETED=$(git diff --diff-filter=D --name-only origin/${{ github.base_ref }}...HEAD | wc -l) + echo "Files deleted in this PR: $DELETED" + if [ "$DELETED" -gt 50 ]; then + echo "::error::This PR deletes $DELETED files (threshold: 50). If intentional, add the 'large-deletion-approved' label." + LABELS=$(gh pr view ${{ github.event.pull_request.number }} --json labels --jq '.labels[].name' 2>/dev/null || echo "") + if echo "$LABELS" | grep -q "large-deletion-approved"; then + echo "✅ Large deletion approved via label" + else + exit 1 + fi + fi + env: + GH_TOKEN: ${{ github.token }} + - name: Build run: npm run build - name: Run tests run: npm test + + # ════════════════════════════════════════════════════════════════════════ + # Skip Labels Reference + # ──────────────────────────────────────────────────────────────────────── + # The following PR labels can be used to bypass specific health gates. + # Add them via the GitHub UI or `gh pr edit --add-label