From 73e24b734a6a3603e5eb690e2637df1269f6acea Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:28:41 -0700 Subject: [PATCH 1/7] docs: add agent on-disk anatomy concept doc Developer-oriented guide explaining: - Directory structure (.squad/agents/{name}/) - charter.md format and parsing - history.md append-only learnings - Casting system (registry, policy, history) - Relationship between .squad/ runtime and SDK source - How an agent 'exists' (charter + roster + routing) - Alumni pattern for retired agents - Cross-agent context propagation Requested by Brady via Dina. Addresses the question: 'What does it mean on disk to be a Squad agent?' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/concepts/agent-on-disk.md | 394 ++++++++++++++++++ 1 file changed, 394 insertions(+) create mode 100644 docs/src/content/docs/concepts/agent-on-disk.md 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..e3a425c71 --- /dev/null +++ b/docs/src/content/docs/concepts/agent-on-disk.md @@ -0,0 +1,394 @@ +# 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 not a single file or code module. It's 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 an agent that can be spawned, collaborate, and accumulate knowledge over time. + +## Directory Structure + +Each 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 + ├── scribe/ + │ └── charter.md + └── _alumni/ + └── verbal/ # Retired agents live here + └── charter.md +``` + +### Key Files + +#### `charter.md` — The Agent's DNA + +**Who writes it:** The team (usually via a specialist like Procedures, or manually by the team owner). + +**Who reads it:** The SDK's charter compiler (`charter-compiler.ts`) at agent spawn time. + +**What it contains:** + +```markdown +# {Name} — {Role} + +> {One-line personality statement} + +## Identity +- **Name:** Flight +- **Role:** Lead +- **Expertise:** Product vision, architecture, code review +- **Style:** Decisive. Opinionated when it matters. + +## What I Own +- Product direction and architectural decisions +- Code review and quality gates + +## How I Work +- Architecture decisions compound +- Proposal-first: meaningful changes need docs/proposals/ before code + +## Boundaries +**I handle:** Architecture, product direction, code review, scope. +**I don't handle:** Implementation details, test writing, docs, distribution. + +## Model +Preferred: auto +``` + +**Parsed sections:** +- **Identity** → `name`, `role`, `expertise`, `style` +- **What I Own** → `ownership` (plain text) +- **Boundaries** → `boundaries` (plain text) +- **Model** → `modelPreference`, `modelRationale`, `modelFallback` + +The charter is compiled into a `SquadCustomAgentConfig` object that includes: +- The full charter content as the agent's system prompt +- Parsed metadata (name, role, model preference) +- Team context (from `team.md`, `routing.md`, `decisions.md`) + +**Format expectations:** +- Markdown headings (`## `) structure the charter +- The SDK parses specific sections by heading name +- Freeform content is preserved and passed to the LLM +- Personality and voice matter — agents have opinions + +#### `history.md` — Append-Only Learnings + +**Who writes it:** The agent itself, after completing work. + +**Who reads it:** The agent, before starting new work (via the charter compiler's history shadow feature). + +**What it contains:** + +```markdown +# Flight — Project History + +> Knowledge accumulated through leading Squad development. + +## Core Context + +Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. +Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship +the code, it's IRL content. + +## Learnings + +### Adoption Tracking Architecture +Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) +ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public +showcase) launches when ≥5 projects opt in. + +### Remote Squad Access +Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` +command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via +Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks). +``` + +**What goes in:** +- Context that persists across sessions (project patterns, established decisions) +- Learnings that inform future work (what worked, what didn't) +- Domain-specific knowledge accumulated over time + +**What doesn't go in:** +- Transient task state (use the session-scoped SQL database for that) +- Raw command output or logs (use `.squad/log/` for session logs) +- Decisions that affect other agents (those go in `.squad/decisions.md`) + +**Format:** +- Top-level `## Core Context` — stable facts +- Top-level `## Learnings` — append new `### ` blocks here +- No deletion — history is append-only + +### Alumni — The Retirement Pattern + +When an agent is no longer needed, it's moved to `.squad/agents/_alumni/{name}/`: + +``` +.squad/agents/_alumni/ +├── verbal/ +│ └── charter.md +├── kobayashi/ +│ └── charter.md +└── mcmanus/ + └── charter.md +``` + +**What happens on retirement:** +1. Agent directory moved from `.squad/agents/{name}/` to `.squad/agents/_alumni/{name}/` +2. Agent removed from `team.md` roster +3. Routing rules updated to remove agent from work assignments +4. Charter preserved for historical reference +5. Casting name returned to the pool (if using the casting system) + +Alumni agents cannot be spawned. Their charters are read-only archives. + +## The Casting System + +Squad uses a **thematic casting model** to assign memorable names from fictional universes. + +### Files + +#### `casting-registry.json` — Name Allocation + +```json +{ + "agents": { + "flight": { + "universe": "Apollo 13", + "character": "Flight Director", + "assigned": "2026-02-21T10:00:00Z" + } + } +} +``` + +**Purpose:** Tracks which names are in use, which universe they're from, and when they were assigned. + +**Who manages it:** The casting module (`packages/squad-sdk/src/casting/`). + +**Lifecycle:** +- Name allocated when agent created → entry added +- Agent retired → entry remains (name not reused within same universe) +- Universe exhausted → new universe added to `casting-policy.json` + +#### `casting-policy.json` — Universe Rules + +```json +{ + "casting_policy_version": "1.1", + "allowlist_universes": [ + "The Usual Suspects", + "Reservoir Dogs", + "Alien", + "Ocean's Eleven" + ], + "universe_capacity": { + "The Usual Suspects": 6, + "Reservoir Dogs": 8, + "Alien": 8, + "Ocean's Eleven": 14 + } +} +``` + +**Purpose:** Defines which fictional universes are available and how many names each can provide. + +**Who manages it:** The team owner (manually edited when adding new universes). + +**Rules:** +- Each universe has a capacity limit (prevents name dilution) +- Names must be recognizable characters from that universe +- No universe mixing on the same team (maintains thematic coherence) + +#### `casting-history.json` — Audit Log + +```json +{ + "universe_usage_history": [ + { + "timestamp": "2026-02-21T10:00:00Z", + "universe": "Apollo 13", + "agent": "flight", + "character": "Flight Director", + "action": "assigned" + } + ], + "assignment_cast_snapshots": {} +} +``` + +**Purpose:** Immutable audit trail of all casting decisions. + +**Who writes it:** The casting module (append-only). + +**Why it matters:** Enables rollback, debugging, and understanding team evolution over time. + +## How an Agent "Exists" + +An agent is **active** when all three conditions are met: + +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 + +Without all three, the agent cannot be spawned. + +**Spawn flow:** + +``` +User request + ↓ +Coordinator reads routing.md + ↓ +Identifies agent to spawn (e.g., "flight") + ↓ +SDK reads .squad/agents/flight/charter.md + ↓ +SDK reads .squad/agents/flight/history.md (if exists) + ↓ +SDK reads .squad/team.md, routing.md, decisions.md + ↓ +Charter compiler builds SquadCustomAgentConfig + ↓ +SDK spawns agent with compiled prompt + ↓ +Agent runs, writes to history.md after work +``` + +## 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 + +## What About `squad.config.ts`? + +The optional `squad.config.ts` file provides **overrides** for charter-based agents: + +```typescript +export default { + agents: { + flight: { + model: 'gpt-4.1', // Override charter's "Preferred: auto" + tools: ['read', 'write'], // Restrict tool access + extraPrompt: 'Focus on performance trade-offs.' // Append to charter + } + } +} +``` + +**Merge order (config wins on conflict):** +1. Charter parsed → base `SquadCustomAgentConfig` +2. Config overrides applied → merged `SquadCustomAgentConfig` +3. Team context injected → final prompt sent to LLM + +This allows: +- Per-environment tuning (staging vs production) +- Temporary restrictions (disable tools during testing) +- A/B testing different prompts without editing charters + +## Cross-Agent Context Propagation + +Agents don't share memory. Context flows via **explicit artifacts**: + +### `team.md` — Shared Roster +All agents read this to know who else exists and what they do. + +### `routing.md` — Work Assignment Rules +Defines which agent handles which type of work. Coordinator uses this to route requests. + +### `decisions.md` — Canonical Decisions Log +All agents read this before starting work. It's the shared memory. + +### `.squad/decisions/inbox/` — Decision Drop-Box +Agents write decisions here. Scribe merges them into `decisions.md`. + +**Flow:** + +``` +Flight makes a decision + ↓ +Flight writes .squad/decisions/inbox/flight-api-versioning.md + ↓ +Scribe (background agent) runs + ↓ +Scribe reads inbox, appends to decisions.md, deletes inbox file + ↓ +CAPCOM starts work, reads decisions.md + ↓ +CAPCOM sees Flight's decision, respects it +``` + +### `.squad/log/` — Session Logs +Scribe writes session summaries here. Useful for auditing and debugging. + +**Example log file:** + +``` +.squad/log/2026-03-16T10-00-00-feature-adoption-tracking.md +``` + +Contains: +- Who worked +- What was done +- Decisions made +- Key outcomes + +## Key Takeaways + +1. **An agent is a directory** — `.squad/agents/{name}/` with at least `charter.md`. +2. **Charter is the source of truth** — defines identity, boundaries, voice. +3. **History is optional** — but recommended for agents doing repeated work. +4. **Casting adds personality** — thematic names make agents memorable. +5. **SDK is generic infrastructure** — no agent-specific code in the runtime. +6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md`, `.squad/log/`. +7. **Retirement is move + remove** — alumni live in `_alumni/`, can't be spawned. + +## Developer Checklist: Creating a New Agent + +- [ ] Create `.squad/agents/{name}/` directory +- [ ] Write `charter.md` using `.squad/templates/charter.md` as reference +- [ ] Add agent to `team.md` roster with status `✅ Active` +- [ ] Add agent to `routing.md` with work type assignments +- [ ] (Optional) Allocate name via casting system +- [ ] (Optional) Create `history.md` if agent needs persistent memory +- [ ] Test spawn: `squad spawn {name} "Hello, world"` + +## Further Reading + +- **Charter format reference:** `.squad/templates/charter.md` +- **Roster format reference:** `.squad/templates/roster.md` +- **SDK agent infrastructure:** `packages/squad-sdk/src/agents/` +- **Casting system design:** `packages/squad-sdk/src/casting/` + +--- + +**Author:** Flight +**Requested by:** Dina (via Brady) +**Date:** 2026-03-16 From 209daf8fbfc60b5bf43e4e42d51ef3cb7cc0145f Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Mon, 16 Mar 2026 10:30:45 -0700 Subject: [PATCH 2/7] feat(docs): Agent-inclusive SDLC paper with concrete Squad examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/papers/agent-inclusive-sdlc.md | 945 ++++++++++++++++++++++++++++ 1 file changed, 945 insertions(+) create mode 100644 docs/papers/agent-inclusive-sdlc.md diff --git a/docs/papers/agent-inclusive-sdlc.md b/docs/papers/agent-inclusive-sdlc.md new file mode 100644 index 000000000..054ccede4 --- /dev/null +++ b/docs/papers/agent-inclusive-sdlc.md @@ -0,0 +1,945 @@ +# Agent-Inclusive Software Development Lifecycle + +**Author:** Flight (Lead, Mission Control) +**Date:** March 16, 2026 +**Status:** High Priority (Brady Request) + +--- + +## Executive Summary + +This paper examines how AI agents participate as first-class contributors across every phase of the software development lifecycle. Using SquadΓÇöa programmable multi-agent runtime for GitHub CopilotΓÇöas the concrete implementation, we demonstrate specific patterns, protocols, and workflows that enable agent teams to operate with the same rigor as human teams. + +This is not a theoretical framework. Every pattern described here has been tested through 3,931 automated tests and validated through Squad's own dogfooding: the Squad team builds Squad using Squad. + +--- + +## Introduction: Beyond Chatbot-Driven Development + +The emergence of AI coding assistants has created a false dichotomy: either you have a human developer working with an assistant, or you have a chatbot wearing different hats pretending to be a team. Squad rejects this binary. + +**The Squad Model:** +- Each team member is a persistent agent with a dedicated charter stored in `.squad/agents/{name}/charter.md` +- Each agent has its own knowledge base in `.squad/agents/{name}/history.md` that accumulates learning across sessions +- The Coordinator routes work based on domain expertise defined in `.squad/routing.md` +- Agents work in parallel when tasks are independent, collaborating through defined handoff protocols +- All decisions are recorded in `.squad/decisions.md` using append-only semantics with merge-conflict-free Git attributes + +This architectural foundation enables agent teams to participate meaningfully in each phase of the SDLC. + +--- + +## Phase 1: Requirements and Planning + +### How Agents Participate + +#### PRD Mode: Ingesting Specifications + +Squad supports a "PRD Mode" where the user provides a product requirements document. The Lead agent (Flight) parses this into work items, identifies dependencies, and proposes a team composition. + +**Example workflow:** +``` +User: "Here's our PRD for the authentication module..." +Flight: Reads PRD ΓåÆ Identifies 4 work streams: + 1. Core auth logic (EECOM - Core Dev) + 2. TypeScript types (CONTROL - TypeScript Engineer) + 3. Test suite (FIDO - Quality Owner) + 4. API documentation (PAO - DevRel) +``` + +The Lead doesn't just assign workΓÇöit performs dependency analysis. If the tester needs the API contracts before writing tests, the Lead sequences CONTROL before FIDO. + +#### Ceremony-Based Coordination + +Before multi-agent tasks involving shared systems, Squad triggers a **Design Review ceremony** (defined in `.squad/ceremonies.md`): + +```markdown +## Design Review + +| Field | Value | +|-------|-------| +| **Trigger** | auto | +| **When** | before | +| **Condition** | multi-agent task involving 2+ agents modifying shared systems | +| **Facilitator** | lead | +| **Participants** | all-relevant | +``` + +**Real example from orchestration log 2026-03-10:** +``` +Flight facilitates design review for PAO External Communications feature: +1. Reviews task: multi-phase rollout with SQLite-backed review state +2. EECOM proposes atomic INSERT...ON CONFLICT for concurrency +3. PAO identifies tone validation integration point +4. FIDO flags test coverage requirement for stale lock cleanup +5. Flight documents decision: SQLite-based locking pattern +``` + +The ceremony produces a shared context before code is written. This prevents the classic multi-agent failure mode: independent agents making incompatible assumptions. + +#### Decision Capture at Planning Time + +Architectural decisions made during planning are recorded in `.squad/decisions/inbox/{agent}-{slug}.md` and merged into `.squad/decisions.md` by Scribe (the session logger). + +**Example decision from Flight's history:** +```markdown +### Proposal-First Workflow +**By:** Flight +**What:** Meaningful changes require a proposal in docs/proposals/ before execution. +**Why:** Proposals create alignment before code is written. +``` + +This isn't documentation debtΓÇöit's a requirement. The Coordinator enforces proposal-first workflow for substantial features. Agents cannot start implementation without an approved proposal on file. + +--- + +## Phase 2: Design and Architecture + +### Architecture Decision Records as Living Artifacts + +Squad uses a lightweight ADR pattern embedded in `.squad/decisions.md`. Unlike traditional ADRs that become stale, Squad's decisions are enforced: + +1. **Hook-Based Governance:** Security and PII rules are implemented as runtime hooks, not prompt instructions +2. **Type Safety as Contract:** `strict: true` in `tsconfig.json` is non-negotiableΓÇöCONTROL (TypeScript Engineer) blocks PRs that violate this +3. **Merge Driver for Team State:** `.gitattributes` uses `merge=union` for `.squad/decisions.md`, enabling conflict-free branch merges + +**Real decision enforced by code:** +```markdown +### Hook-Based Governance Over Prompt Instructions +**By:** RETRO (Security) +**What:** Security, PII, and file-write guards are implemented via the hooks module, NOT prompt instructions. +**Why:** Prompts can be ignored. Hooks are codeΓÇöthey execute deterministically. +``` + +The `src/hooks/` module implements this. RETRO doesn't just advise on securityΓÇöRETRO writes the guard code that executes before any file write. + +### Design Meetings as Structured Ceremonies + +Design meetings aren't ad hoc. They follow the ceremony protocol: + +**Agenda (from `.squad/ceremonies.md`):** +1. Review the task and requirements +2. Agree on interfaces and contracts between components +3. Identify risks and edge cases +4. Assign action items + +**Concrete example from 2026-03-15 orchestration log:** + +``` +Task: Fix Review Gate Concurrency Issue +Facilitator: Flight +Participants: EECOM, FIDO, PAO + +1. EECOM presents the problem: file-based locks have race conditions +2. Team reviews alternatives: Git-based locking (rejected: too slow), + queue-based (rejected: complexity), advisory file locks (rejected: stale lock risk) +3. EECOM proposes SQLite atomic INSERT...ON CONFLICT +4. FIDO identifies test requirement: verify 1-hour expiration works +5. PAO identifies integration point: review state must be queryable +6. Flight documents decision in .squad/decisions/inbox/eecom-concurrency-fix.md + +Outcome: Design approved. EECOM proceeds with implementation. +``` + +This is not a chat transcriptΓÇöit's a structured output from a facilitated process. The design decision is traceable to specific agents and persists in the team's shared memory. + +### Module Ownership Table + +Squad maintains a module ownership matrix in `.squad/routing.md`: + +```markdown +| Module | Primary | Secondary | +|--------|---------|-----------| +| src/adapter/ | EECOM ≡ƒöº | CAPCOM ≡ƒò╡∩╕Å | +| src/agents/ | Procedures ≡ƒºá | EECOM ≡ƒöº | +| src/hooks/ | RETRO ≡ƒöÆ | EECOM ≡ƒöº | +``` + +This enables the Coordinator to route issues precisely. When issue #287 involves `src/hooks/file-write-guard.ts`, RETRO is the primary assignee, EECOM is secondary. This replicates the CODEOWNERS pattern but is runtime-enforced by the Coordinator. + +--- + +## Phase 3: Implementation + +### Parallel Fan-Out: "Team, Build This" + +Squad's killer feature is parallel agent execution. When the user says "Team, build the login page," the Coordinator spawns multiple agents in `mode: "background"`: + +**Routing logic (from `.squad/routing.md`, principle 5):** +``` +"Team, ..." ΓåÆ fan-out. Spawn all relevant agents in parallel as mode: "background". +``` + +**Real decomposition example:** +``` +User: "Team, implement the authentication module." + +Coordinator spawns in parallel: +1. EECOM (Core Dev) ΓÇö src/auth/session.ts, src/auth/token.ts +2. CONTROL (TypeScript) ΓÇö src/auth/types.ts, strict mode compliance +3. RETRO (Security) ΓÇö src/hooks/auth-guard.ts, PII filtering +4. FIDO (Tester) ΓÇö test/auth.test.ts, edge case coverage +5. PAO (DevRel) ΓÇö docs/api/authentication.md + +All run simultaneously. Each operates in its own context. +``` + +This isn't "multitasking" by a single LLM. Each agent is a separate spawned process managed by the runtime. From the orchestration log: + +``` +2026-03-15T16-44-42Z-eecom-bg.md ΓÇö EECOM working on core implementation +2026-03-15T16-44-42Z-fido-bg.md ΓÇö FIDO writing tests +2026-03-15T16-44-42Z-pao-bg.md ΓÇö PAO drafting documentation +``` + +All three ran at the same time. + +### Drop-Box Pattern for Conflict-Free Collaboration + +How do four agents write code simultaneously without stepping on each other? The **drop-box pattern:** + +1. Each agent works in its assigned module (defined by ownership table) +2. Shared interfaces are defined up front in the design ceremony +3. Agents do NOT edit each other's files during parallel work +4. Integration happens after all parallel work completes +5. If conflict arises, the Coordinator enforces strict handoff rules + +**Example from Squadron (internal CLI tool):** +``` +Task: Add real-time monitoring dashboard + +Parallel work: +- Telemetry (Observability) ΓåÆ src/metrics/collector.ts +- DSKY (TUI) ΓåÆ src/cli/shell/components/metrics-display.tsx +- GNC (Runtime) ΓåÆ src/runtime/performance-hooks.ts + +Shared contract (defined in ceremony): +interface MetricsEvent { + timestamp: number; + source: string; + value: number; +} + +Each agent implements its half. Integration test validates the contract. +``` + +If DSKY needs changes to `MetricsEvent`, it doesn't edit Telemetry's fileΓÇöit proposes the change in the shared decisions file, and Telemetry implements it. + +### Anticipatory Downstream Work + +Squad's routing principle 6: +``` +Feature being built? Spawn tester for test cases from requirements simultaneously. +``` + +This means FIDO (the tester) starts writing tests BEFORE implementation completes. How? FIDO reads the requirements and writes test cases based on the spec: + +**Example from test suite:** +```javascript +// test/ralph-triage.test.ts +// Written by FIDO while EECOM implemented ralph-triage.js + +describe('Ralph Triage', () => { + it('should route core runtime issues to EECOM', () => { + const issue = { + title: 'CopilotClient session pool memory leak', + body: 'src/client/session-pool.ts line 47' + }; + const assignment = triage(issue); + expect(assignment.agent).toBe('EECOM'); + }); +}); +``` + +FIDO doesn't need the implementation to write this test. The requirement is clear: issues mentioning `src/client/` should route to CAPCOM or EECOM. FIDO validates the contract, not the implementation details. + +When EECOM finishes, the test already exists. If it fails, EECOM knows immediately. + +--- + +## Phase 4: Code Review + +### Reviewer Rejection Protocol and Lockout + +Squad enforces a strict reviewer protocol (defined in `.squad/skills/reviewer-protocol/skill.md`): + +**Rule:** When a reviewer rejects work, the original author is **locked out** from self-revision. A different agent must fix it. + +**Why?** Self-revision after rejection creates defensive feedback loops. The rejected author becomes invested in defending their approach rather than accepting the feedback. + +**Example workflow:** +``` +1. EECOM writes authentication module +2. RETRO (Security) reviews ΓåÆ rejects: "No input sanitization on username field" +3. Coordinator: EECOM is now locked out +4. Coordinator spawns CONTROL (TypeScript Engineer) to add sanitization +5. CONTROL produces v2 +6. RETRO reviews v2 ΓåÆ approves +7. Lockout clears for next artifact +``` + +**Deadlock handling:** +If all eligible agents are locked out, the Coordinator escalates to the user rather than re-admitting a locked-out author. + +### Multi-Reviewer Gate with Different Perspectives + +For critical features, Squad uses multiple reviewers in parallel: + +**Example: 4-reviewer gate for external communications feature (from orchestration log 2026-03-10):** +``` +Reviewers: +1. Flight (Lead) ΓÇö Architecture and scope review +2. FIDO (Quality) ΓÇö Test coverage and edge cases +3. EECOM (Core Dev) ΓÇö Implementation quality and maintainability +4. PAO (DevRel) ΓÇö Documentation and user-facing clarity + +Each runs independently. PR merges only when all four approve. +``` + +This mirrors the real-world practice of getting "architecture review + security review + ops review" on sensitive changes. Squad makes it executable. + +### CI Integration as First-Class Review + +Squad doesn't separate "code review" from "CI validation." Both are review gates. + +From `.github/workflows/squad-ci.yml`: +```yaml +name: Squad CI +on: [pull_request] +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: npm ci + - run: npm test + - run: npm run lint +``` + +The Coordinator treats CI status as a reviewer verdict: +- Green CI = approval from "CI Reviewer" +- Failed CI = rejection from "CI Reviewer" with specific blocker (which test failed) + +The `pr-merge-workflow` skill codifies this: + +```markdown +### Required Gate Pattern + +A PR is only ready to merge when all required gates are green: + +Gate 1: Review completeness (human approvals) +Gate 2: CI health (all required checks passing) +Gate 3: Mergeability (no conflicts, not draft) +Gate 4: Freshness against base (branch is up-to-date) +``` + +Ralph (the work monitor) evaluates all four gates before merging. + +--- + +## Phase 5: Testing + +### Test Agents Writing Cases from Specs + +FIDO (Quality Owner) writes tests in three modes: + +1. **Anticipatory:** Tests written during implementation based on requirements +2. **Adversarial:** Tests written AFTER implementation to find edge cases the implementer missed +3. **Regression:** Tests added after bugs to ensure they don't return + +**Example: Adversarial testing approach (from FIDO's charter):** +``` +FIDO reviews EECOM's session pool implementation: +- Requirement: "Pool should handle 100 concurrent sessions" +- FIDO's adversarial test: "What happens at 101 sessions?" +- Bug found: Pool crashes instead of queuing +- FIDO writes test: test/session-pool-overflow.test.ts +- EECOM fixes implementation +- Regression test now guards against future breakage +``` + +### CI Integration and Automated Validation + +Squad's testing workflow integrates with GitHub Actions: + +**Ralph triage script (templates/ralph-triage.js) ΓÇö zero-dependency CI integration:** +```javascript +// Parses .squad/routing.md to auto-assign issues +// Runs in GitHub Actions on issue open +// Zero npm dependencies for fast CI execution + +const rules = parseRoutingRules(routingMd); +const assignment = matchIssue(issue, rules); +// Writes triage-results.json for GitHub Actions to consume +``` + +This enables: +1. Issue #287 opens mentioning "CopilotClient session leak" +2. GitHub Action runs `ralph-triage.js` +3. Script parses routing rules, matches "CopilotClient" ΓåÆ CAPCOM +4. Action auto-assigns issue to CAPCOM +5. CAPCOM gets notification, starts work + +Testing is automated from issue filing to fix validation. + +### Metrics Test Script Pattern + +Squad uses a "metrics test" pattern for observable quality gates: + +**Example: test/ralph-triage.test.ts validates routing coverage:** +```javascript +describe('Routing Coverage', () => { + it('should have routes for all core modules', () => { + const modules = listSourceModules('src/'); + const routes = parseRoutingRules('.squad/routing.md'); + + for (const module of modules) { + const route = findRoute(module, routes); + expect(route).toBeDefined(`No route for ${module}`); + } + }); +}); +``` + +This test fails if a new module is added without updating the routing table. It's not testing codeΓÇöit's testing team process compliance. + +--- + +## Phase 6: Deployment and Release + +### Ralph: The Work Monitor + +Ralph is Squad's autonomous work monitor. Unlike other team members, Ralph doesn't write codeΓÇöRalph watches the work queue and drives PRs to merge. + +**Ralph's workflow:** +1. Runs `squad triage` in watch mode (default: every 10 minutes) +2. Parses `.squad/routing.md` to understand work assignment rules +3. For each open issue/PR: + - Evaluates merge readiness using `pr-merge-workflow` skill + - Checks all four gates (reviews, CI, mergeability, freshness) + - If all green: runs `gh pr merge` + - If blocked: comments on PR with specific blockers + +**Real example from Ralph's monitoring loop:** +``` +PR #326 Adoption Tracking +- Gate 1 (Reviews): Γ£à Approved by Flight, FIDO, EECOM +- Gate 2 (CI): Γ¥î squad-ci.yml failing (test/adoption-tracking.test.ts line 47) +- Gate 3 (Mergeability): Γ£à No conflicts +- Gate 4 (Freshness): Γ£à Up-to-date with dev + +Blocker: CI failure +Action: Ralph comments on PR: "Test failing at line 47: expected 'aggregate-only' but got 'repo-listing'" +``` + +Ralph doesn't fix the issueΓÇöRalph reports it. The assignee (determined by routing rules) gets notified and fixes it. Once CI goes green, Ralph merges automatically. + +### GitHub Actions Integration for CI/CD + +Squad's CI pipeline is defined in `.github/workflows/`: + +**squad-ci.yml ΓÇö test and lint on every PR:** +```yaml +name: Squad CI +on: [pull_request] +jobs: + test: + - run: npm test + lint: + - run: npm run lint + type-check: + - run: npm run type-check +``` + +**squad-publish.yml ΓÇö publish to npm on release:** +```yaml +name: Publish to npm +on: + release: + types: [published] +jobs: + publish: + - run: npm publish --access public +``` + +**squad-triage.yml ΓÇö Ralph auto-triage on issue open:** +```yaml +name: Auto-triage Issues +on: + issues: + types: [opened, labeled] +jobs: + triage: + - run: node templates/ralph-triage.js + - uses: actions/github-script@v7 + with: + script: | + const results = require('./triage-results.json'); + await github.rest.issues.addAssignees({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + assignees: [results.assignee] + }); +``` + +This is full CI/CD operated by the agent team. No human clicks "merge" or "deploy"ΓÇöRalph does it when gates pass. + +### Watch Mode for Unattended Operation + +Ralph runs in watch mode via `squad triage --interval 10`: +```bash +$ squad triage --interval 10 +Ralph monitoring work queue... +Checking 8 open issues... + #287: Assigned to CAPCOM (CopilotClient session leak) + #293: Assigned to FIDO (Flaky test in ralph-monitor.test.ts) + #301: Assigned to PAO (README missing quick-start) +Checking 3 open PRs... + #326: Blocked by CI failure (commenting with details) + #329: All gates green (merging now) + #331: Waiting for Flight approval +Next check in 10 minutes... +``` + +This enables Squad to operate autonomously during off-hours. Brady (the project owner) wakes up to find PRs merged overnight if they passed all gates. + +--- + +## Phase 7: Maintenance and Knowledge + +### Knowledge Library for Persistent Team-Wide Storage + +Squad stores team-wide knowledge in `.squad/knowledge/`: +- Not currently using hierarchical folders, but the structure is ready +- Scribe (session logger) extracts key decisions from orchestration logs +- All agents read shared knowledge before starting work + +**Example pattern (from discussion, not yet implemented):** +``` +.squad/knowledge/ + conventions/typescript-patterns.md + architecture/event-streaming.md + troubleshooting/ci-failures.md +``` + +The knowledge library solves the "second agent doesn't know what the first agent learned" problem. + +### History Files for Individual Agent Learning + +Each agent maintains a personal history file at `.squad/agents/{name}/history.md`: + +**Example from Flight's history:** +```markdown +# Flight ΓÇö Project History + +## Core Context +Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. +Proposal-first: meaningful changes need docs/proposals/ before code. + +## Learnings + +### Adoption Tracking Architecture +Three-tier opt-in system: Tier 1 (aggregate-only, .github/adoption/) ships first; +Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ΓëÑ5 projects opt in. + +### Remote Squad Access +Three-phase rollout: Phase 1 ΓÇö GitHub Discussions bot with /squad command (1 day, zero hosting). +Phase 2 ΓÇö GitHub Copilot Extension via Contents API (1 week). +Phase 3 ΓÇö Slack/Teams bot (2 weeks). +``` + +Merge driver (`merge=union` in `.gitattributes`) ensures these files merge without conflicts across branches. + +When Flight works on issue #350, Flight reads this history first. The lessons from #326 are immediately available. + +### Skills System for Reusable Patterns + +Squad skills are executable workflows stored in `.squad/skills/{skill-name}/skill.md`: + +**Example: reviewer-protocol skill:** +```markdown +--- +name: "reviewer-protocol" +description: "Reviewer rejection workflow and strict lockout semantics" +domain: "orchestration" +confidence: "high" +--- + +## Context +When a team member has a Reviewer role, they may approve or reject work. +On rejection, the coordinator enforces strict lockout rules. + +## Patterns +### Strict Lockout Semantics +1. The original author is locked out +2. A different agent MUST own the revision +3. The Coordinator enforces this mechanically +[... detailed rules continue ...] +``` + +Skills are invoked by the Coordinator when specific conditions are met (multi-agent task, reviewer gate, merge readiness check). + +**Example skill invocations:** +- `agent-collaboration` ΓÇö when 2+ agents work on shared systems +- `pr-merge-workflow` ΓÇö when evaluating PR merge readiness +- `reviewer-protocol` ΓÇö when a reviewer rejects work + +This enables the team to codify "how we work" as executable procedures, not just documentation. + +--- + +## Integration: The Full SDLC in Action + +### Case Study: Building the External Communications Feature + +Let's trace a complete feature through all SDLC phases using real Squad orchestration logs: + +#### Requirements Phase (Day 1) +``` +User: "PAO needs external communications capability - blog posts, release notes, tone validation." + +Flight (Lead) spawns: +- PRD analysis: break down into 3 phases +- Team composition: PAO (owner), EECOM (infra), FIDO (testing), RETRO (hooks) +- Dependency map: Phase 1 foundation ΓåÆ Phase 2 review gate ΓåÆ Phase 3 automation +``` + +#### Design Phase (Day 1-2) +``` +Flight facilitates design ceremony: +- PAO presents use cases: blog post generation, release note drafting +- EECOM proposes architecture: .squad/comms/ directory structure, SQLite review state +- RETRO identifies security concern: tone validation must happen pre-publish +- FIDO defines acceptance criteria: all tone violations must block publication +- Decision captured: .squad/decisions/inbox/pao-external-comms.md +``` + +#### Implementation Phase (Day 2-3) +``` +Coordinator spawns in parallel: + +EECOM (mode: background): +- Creates .squad/comms/README.md +- Implements SQLite schema for review state +- Writes templates/review-state-schema.sql + +PAO (mode: background): +- Creates tone-validation.json rules +- Writes templates/audit-entry.md +- Drafts user documentation + +FIDO (mode: background): +- Creates tests/ci-gate.md (integration spec) +- Creates tests/tone-validation-spec.md +- Prepares test fixtures + +RETRO (mode: background): +- Plans hook integration for pre-publish validation +- Reviews SQLite security (no SQL injection via templates) +``` + +All four agents work simultaneously. Drop-box pattern prevents conflicts (each owns separate files). + +#### Review Phase (Day 3-4) +``` +Round 1: FIDO reviews EECOM's implementation +- Identifies blocker: Review state concurrency issue with file-based locks +- Rejects with feedback: "Use SQLite atomic INSERT...ON CONFLICT" +- EECOM locked out from revision +- Flight assigns revision to EECOM after design adjustment ceremony + +Round 2: Flight + FIDO + PAO review together +- All critical blockers resolved +- Minor issue: inconsistent field naming in audit schema +- EECOM fixes (no lockout for minor issues with approval) +- All reviewers approve + +CI validation: +- All tests pass +- Lint check passes +- Type check passes (TypeScript strict mode) +``` + +#### Testing Phase (Day 4) +``` +FIDO's adversarial testing: +- Test: What happens if tone validation rules file is missing? +- Result: Script crashes instead of graceful fallback +- FIDO files issue #427: "Tone validation needs default rules" +- EECOM fixes with fallback behavior +- Regression test added: test/tone-validation-defaults.test.ts +``` + +#### Deployment Phase (Day 5) +``` +Ralph monitoring: +- PR #426 (PAO External Comms) status check +- Gate 1: Γ£à Reviews (Flight, FIDO, EECOM all approved) +- Gate 2: Γ£à CI (squad-ci.yml passing) +- Gate 3: Γ£à Mergeability (no conflicts) +- Gate 4: Γ£à Freshness (up-to-date with dev) +- Action: Ralph runs `gh pr merge --squash` +- PR merged to dev branch +``` + +#### Maintenance Phase (Ongoing) +``` +Scribe (session logger) processes orchestration logs: +- Extracts decision: "SQLite-based review state pattern" +- Merges .squad/decisions/inbox/eecom-concurrency-fix.md ΓåÆ .squad/decisions.md +- Updates PAO's history.md with external comms pattern +- Updates EECOM's history.md with atomic INSERT pattern + +Knowledge compounds: +- Next feature needing review state? Pattern already documented. +- Next concurrency issue? SQLite solution already in team memory. +``` + +--- + +## Lessons Learned: What Makes Agent Teams Work + +### 1. Explicit Contracts Over Implicit Coordination + +The design ceremony isn't optional. When DSKY (TUI Engineer) and Telemetry (Observability) need to integrate, they don't "figure it out"ΓÇöthey agree on the `MetricsEvent` interface first. + +**Why it works:** Parallel agents can't read each other's minds. Explicit contracts let them work independently with confidence. + +### 2. Lockout-on-Rejection Prevents Defensive Loops + +Self-revision after rejection creates a "defend my code" mentality. Forcing a different agent to revise brings fresh perspective. + +**Why it works:** Rejected agents are emotionally (synthetically?) invested in their approach. A new agent reads the feedback without that baggage. + +### 3. Persistent Memory Beats Context Window Tricks + +Flight's `history.md` is 28 KB of accumulated project knowledge. That's not fitting in a prompt. + +**Why it works:** Knowledge compounds across sessions. Flight today knows what Flight learned three months ago. The alternative (re-learning every session) is exhausting. + +### 4. Ralph as Autonomous Merge Bot Requires Trust + +Letting Ralph merge PRs overnight sounds risky. It works because of the four-gate system: reviews + CI + mergeability + freshness. If any gate is red, Ralph blocks. + +**Why it works:** Ralph enforces process, not judgment. The judgment happened in the review gate. Ralph is the "did everyone sign off?" check. + +### 5. Skills as Executable Procedures Scale Team Knowledge + +When a new team member joins, they don't read a wikiΓÇöthey invoke skills. The `reviewer-protocol` skill codifies 7 detailed lockout rules. New reviewers follow it automatically. + +**Why it works:** Runbooks rot. Executable skills enforce themselves. If the procedure changes, the skill updates, and all agents use the new version immediately. + +--- + +## Challenges and Open Questions + +### Challenge 1: Merge Conflicts in Parallel Work + +The drop-box pattern reduces conflicts but doesn't eliminate them. When EECOM and CAPCOM both need to edit `src/client/session.ts`, someone has to reconcile. + +**Current approach:** Design ceremony defines clear boundaries. If conflict is likely, sequential execution instead of parallel. + +**Open question:** Can we detect potential conflicts earlier (static analysis of import graphs) and proactively sequence work? + +### Challenge 2: Reviewer Deadlock + +If EECOM ΓåÆ rejected, CONTROL revises ΓåÆ rejected, RETRO revises ΓåÆ rejected, all eligible agents are locked out. The Coordinator escalates to the user. + +**Current approach:** Escalation to human. The problem is too hard for the agent team. + +**Open question:** Should we allow "appeal" where a locked-out agent can propose a fundamentally different approach? Or does that re-introduce defensive loops? + +### Challenge 3: Knowledge Base Bloat + +History files grow unbounded. Flight's history is 28 KB after 3 weeks. EECOM's will hit 100 KB eventually. + +**Current approach:** No automatic compression. Agents read the full history. + +**Open question:** Do we need a "nap" command that archives old learnings? Or hierarchical summaries ("2024 Q4 learnings: [summary]")? + +### Challenge 4: Cross-Repository Agent Teams + +Squad currently operates within a single repository. What about a microservices architecture where the frontend team and backend team need to coordinate? + +**Current approach:** Not supported. Each repo has its own Squad team. + +**Open question:** Should we build "distributed mesh" capabilities where teams can call each other? Or is repo-per-team the right boundary? + +--- + +## Comparison to Traditional SDLC + +| Phase | Traditional Human Team | Squad Agent Team | +|-------|----------------------|------------------| +| **Requirements** | PM writes PRD, eng team reads it | Lead agent parses PRD into work items with dependency graph | +| **Design** | Architecture meeting, whiteboard session | Design ceremony with structured agenda, decisions recorded in `.squad/decisions.md` | +| **Implementation** | Devs work in branches, coordinate via Slack | Agents spawn in parallel with drop-box pattern, no manual coordination needed | +| **Code Review** | PR review with GitHub comments | Multi-reviewer gate with lockout-on-rejection, CI as first-class reviewer | +| **Testing** | QA team writes tests after implementation | Test agent writes tests during implementation from requirements | +| **Deployment** | DevOps runs CI/CD pipeline | Ralph monitors work queue, auto-merges when gates pass | +| **Maintenance** | Tribal knowledge, Confluence docs | Persistent agent histories, executable skills, shared knowledge library | + +**Key difference:** Traditional teams coordinate asynchronously through human communication. Agent teams coordinate synchronously through structured protocols enforced by the Coordinator. + +--- + +## Future Directions + +### 1. Multi-Repository Coordination + +Allow agent teams to invoke each other across repositories: +``` +Frontend Squad: "Need GraphQL schema changes from backend" +Backend Squad: Receives request, makes changes, notifies frontend +Frontend Squad: Receives updated schema, regenerates types +``` + +This requires distributed locking and cross-repo decision synchronization. + +### 2. Adaptive Team Composition + +Right now, team composition is manual (user picks agents). Could the Coordinator analyze the task and propose a team? + +``` +Coordinator analyzes issue #500: +- Keywords: "performance", "memory leak", "profiling" +- Proposes team: GNC (Runtime) + Flight (Lead) + FIDO (Testing) +- User approves or adjusts +``` + +### 3. Learning from Rejections + +When FIDO rejects EECOM's work 3 times in a row for similar issues (missing error handling), can EECOM's history.md update with "FIDO always checks error handlingΓÇödo this first"? + +This is meta-learning: learning about the review process, not just the domain. + +### 4. Agent Performance Metrics + +Track per-agent metrics: +- Review approval rate (how often does this agent's work pass review on first try?) +- Test coverage contribution +- Decision authorship (who contributes most to `.squad/decisions.md`?) + +Not for ranking, but for identifying when an agent needs charter refinement. + +--- + +## Conclusion + +Agent-inclusive SDLC isn't theoretical. Squad demonstrates that AI agents can participate as first-class contributors across requirements, design, implementation, review, testing, deployment, and maintenanceΓÇöwhen the team uses structured protocols, persistent memory, and executable workflows. + +The key insight: **Agents aren't augmented humans. They're a different kind of team member that requires different coordination patterns.** + +Traditional SDLC assumes human communication (Slack messages, meetings, email). Agent-inclusive SDLC assumes structured protocols (ceremonies, skills, decision records, lockout rules). + +The Squad modelΓÇöpersistent agents with charters, routing tables, reviewer gates, parallel execution, and Ralph monitoring the work queueΓÇöshows what's possible when we design the SDLC for both humans and agents from the ground up. + +**The next step:** More teams adopting Squad, finding edge cases, and contributing patterns back to the skills library. The system learns not just from its own team, but from every team using it. + +--- + +## Appendix A: Key File Paths + +- `.squad/team.md` ΓÇö Team roster and capabilities +- `.squad/routing.md` ΓÇö Work type to agent mapping + module ownership +- `.squad/decisions.md` ΓÇö Architectural decision records +- `.squad/ceremonies.md` ΓÇö Meeting protocols +- `.squad/agents/{name}/charter.md` ΓÇö Agent role and expertise +- `.squad/agents/{name}/history.md` ΓÇö Agent accumulated knowledge +- `.squad/skills/{skill}/skill.md` ΓÇö Executable workflow patterns +- `.squad/orchestration-log/` ΓÇö Session logs for each agent spawn +- `templates/ralph-triage.js` ΓÇö Zero-dependency triage script for CI +- `.github/workflows/squad-*.yml` ΓÇö GitHub Actions integration + +--- + +## Appendix B: Command Examples + +**Initialize Squad in a project:** +```bash +squad init +``` + +**Launch interactive shell:** +```bash +squad +``` + +**Start Ralph in watch mode:** +```bash +squad triage --interval 10 +``` + +**Spawn a specific agent:** +```bash +# Via shell +squad > @Flight, review the architecture proposal + +# Via CLI +copilot --agent squad +> Flight, review the architecture proposal +``` + +**Check merge readiness:** +```bash +squad > Is PR #326 ready to merge? +# Ralph evaluates 4 gates and reports status +``` + +**Export squad state:** +```bash +squad export +# Generates squad-export.json with full team state +``` + +--- + +## Appendix C: Real Orchestration Log Excerpt + +**From 2026-03-15T16-44-42Z (multi-agent parallel execution):** + +```markdown +# Orchestration Log: EECOM (Sync) +Timestamp: 2026-03-15T16-44-42Z +Agent: EECOM (Core Dev) +Mode: Sync +Task: Fix concurrency in comms plan + +Outcome: Γ£à Success +- Analyzed FIDO blocker #2 (Review Gate concurrency) +- Designed SQLite-based atomic locking with 1-hour expiration +- Decided against file-based locks (race conditions, stale lock risk) +- Implemented: INSERT ... ON CONFLICT atomicity +- Documented decision in .squad/decisions/inbox/eecom-concurrency-fix.md + +# Orchestration Log: FIDO (Background) +Timestamp: 2026-03-15T16-44-42Z +Agent: FIDO (Quality Owner) +Mode: Background +Task: Review Phase 1 implementation for test gaps + +Outcome: Γ£à Success +- Identified missing test: stale lock cleanup +- Added test spec to tests/ci-gate.md +- Verified SQLite schema matches audit requirements + +# Orchestration Log: PAO (Background) +Timestamp: 2026-03-15T16-44-42Z +Agent: PAO (DevRel) +Mode: Background +Task: Draft user-facing documentation for external comms + +Outcome: Γ£à Success +- Created .squad/comms/README.md with setup instructions +- Documented tone validation rule format +- Prepared example audit entry +``` + +All three agents worked simultaneously on different aspects of the same feature. + +--- + +**End of Paper** + +*This paper is a living document. As Squad's agent team evolves, so will the patterns described here. Contributions welcome via PR to `docs/papers/`.* From bba184ca70617d3f47a16692743f5a8b6de3f239 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 11:47:46 -0700 Subject: [PATCH 3/7] docs: Add nap, reskill, and compact behavior documentation Adds a new feature page documenting context hygiene commands based on community confusion about whether shutting down Squad is equivalent to a nap (it is not). Key points documented: - Nap = /compact: actively summarizes and compacts memory files - Shutting down preserves files as-is (no compaction occurs) - Reskill re-examines and validates agent skills - Reskill currently requires running from source (symlink) - Combined command example for both behaviors with reporting Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/features/context-hygiene.md | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 docs/src/content/docs/features/context-hygiene.md diff --git a/docs/src/content/docs/features/context-hygiene.md b/docs/src/content/docs/features/context-hygiene.md new file mode 100644 index 000000000..bef518244 --- /dev/null +++ b/docs/src/content/docs/features/context-hygiene.md @@ -0,0 +1,130 @@ +# Context Hygiene: Nap, Reskill, and Compact + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + + +**Try this to compact your team's memory:** +``` +Team, take a nap +``` + +**Try this to refresh agent skills:** +``` +Team, reskill +``` + +**Try this to do both and report results:** +``` +Team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations +``` + +Over multiple sessions, Squad's `.squad/` files grow — agent histories, decisions, skill files. Context hygiene commands let you actively manage that growth so agents stay fast and focused. + +--- + +## Nap + +**What it does:** Summarizes accumulated work into smaller, more efficient memory files. This is the same as running `/compact` in the CLI or `squad nap` from the command line. + +When you tell the team to "take a nap," each agent: + +1. Reviews its `history.md` and other state files +2. Compresses older entries into concise summaries +3. Archives verbose detail while preserving key decisions and learnings +4. Reports how much context was reclaimed + +### Nap ≠ Shutting Down + +This is the most common misconception: + +| Action | What happens to `.squad/` files | +|--------|-------------------------------| +| **Shutting down Squad** (closing the CLI, killing the process) | Files stay exactly as they are. Nothing is summarized or compacted. | +| **Nap** (`team, take a nap` or `squad nap`) | Files are actively summarized and compacted. Older entries are archived, working context gets leaner. | + +Shutting down Squad every night does **not** perform context hygiene. You must explicitly tell the team to take a nap. + +### CLI equivalents + +```bash +squad nap # Standard context hygiene +squad nap --deep # Thorough cleanup with recursive descent +squad nap --dry-run # Preview what would be cleaned up +``` + +In the interactive shell, use `/compact` for the same effect. + +--- + +## Reskill + +**What it does:** Tells agents to re-examine their skills, validate them against the current codebase, and potentially discover new patterns. + +When you tell the team to "reskill," agents: + +1. Review existing skill files in `.squad/skills/` +2. Validate that documented patterns still apply +3. Look for new reusable patterns from recent work +4. Update skill confidence levels based on current evidence + +### Availability + +> **Note:** As of now, reskill requires running Squad from source (via symlink). It is not yet available through `squad upgrade`. This will change in a future release. + +--- + +## Combined Commands + +You can trigger nap and reskill together in a single prompt: + +``` +Team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations +``` + +This runs both behaviors and gives you a report on how much context was reduced — useful for understanding how lean your team's working memory is before the next session. + +--- + +## When to Use These + +| Situation | Command | +|-----------|---------| +| After several work sessions, agents feel slow or unfocused | `team, take a nap` | +| Codebase has changed significantly and skills may be stale | `team, reskill` | +| Before a major new phase of work | Combine both | +| End of sprint / milestone | `squad nap --deep` | + +--- + +## Tips + +- **Nap regularly.** A few sessions of heavy work can bloat history files. Napping keeps context budgets in check. +- **Don't rely on shutdown.** Closing the CLI preserves files as-is — it does not compact anything. +- **Reskill after refactors.** If you've restructured the codebase, agent skills may reference outdated patterns. +- **Check the dry run first.** Use `squad nap --dry-run` to preview cleanup actions before committing to them. + +## Sample Prompts + +``` +team, take a nap +``` + +Compacts and summarizes all agent memory files, reclaiming context space. + +``` +team, reskill +``` + +Agents re-examine and validate their skills against the current codebase. + +``` +team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations +``` + +Combines both behaviors and reports back on total context reduction. + +``` +squad nap --dry-run +``` + +Previews what a nap would clean up without making any changes. From 65725b2a8605dd6e03bb30ea8a0681fd886e6926 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 12:04:03 -0700 Subject: [PATCH 4/7] docs: add required vs optional files reference Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/reference/config.md | 40 +++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/src/content/docs/reference/config.md b/docs/src/content/docs/reference/config.md index 359c1d250..348469256 100644 --- a/docs/src/content/docs/reference/config.md +++ b/docs/src/content/docs/reference/config.md @@ -85,6 +85,46 @@ Commit this directory. It's your team's brain. Anyone who clones the repo gets t --- +## .squad/ — Required vs Optional Files + +`squad init` creates a working team. Here's what's required and what's optional. + +### Required Files + +These are always created by `squad init`. The loader expects them. + +| File | Purpose | Can You Edit? | +|------|---------|---------------| +| `.squad/team.md` | Team roster — loader requires it | Yes | +| `.squad/decisions.md` | Shared decision log — agents read before work | Yes (append only) | +| `.squad/routing.md` | Work assignment rules | Yes | +| `.squad/ceremonies.md` | Team meeting definitions | Yes | +| `.squad/config.json` | SDK settings (teamRoot, version) | Rarely | +| `.squad/agents/{name}/charter.md` | Agent identity — compiled at spawn | Yes | +| `.squad/agents/{name}/history.md` | Agent learnings — grows over time | Append only | +| `.squad/identity/now.md` | Current team focus | Auto-updated | +| `.squad/identity/wisdom.md` | Accumulated team patterns | Auto-updated | +| `.gitattributes` | Merge drivers for append-only files | Merge rules only | + +### Optional Files + +These are created only when you opt in during init. + +- **`.squad/templates/`** — SDK templates, overwritten on upgrade +- **`.github/workflows/*.yml`** — CI/CD workflows (opt-in: `--include-workflows`) +- **`.copilot/mcp-config.json`** — MCP server config (opt-in: `--include-mcp-config`) + +> ⚠️ **Hard rule:** Squad NEVER writes temp files, logs, or memory to your repo root. All team state lives in `.squad/` only. Your project tree stays clean. + +### Quick Recovery + +```bash +squad doctor # Check for issues +rm -rf .squad && squad init # Full reset (back up agents/decisions first) +``` + +--- + ## Routing Rules Control which agent gets which work. Edit `.squad/routing.md` or configure in `squad.config.ts`: From 88280ef6b621670d9c58d7c93a141cb17b787027 Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 12:19:00 -0700 Subject: [PATCH 5/7] docs: add squad doctor troubleshooting guidance Document all 9 diagnostic checks from the doctor command source code with their exact warning/failure messages and resolution steps. Update cli.md example output to match real doctor output format. Cross-link cli.md doctor section to the full troubleshooting reference. Addresses docs-opportunities item #8. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/reference/cli.md | 31 ++-- .../content/docs/scenarios/troubleshooting.md | 146 ++++++++++++++++++ 2 files changed, 167 insertions(+), 10 deletions(-) diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index 0add97f50..39d109e56 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/docs/src/content/docs/reference/cli.md @@ -268,10 +268,11 @@ squad doctor This performs a comprehensive diagnostic check of your Squad setup, validating: - `.squad/` directory structure -- Required configuration files (team.md, routing.md, etc.) -- Agent definitions and capabilities -- File permissions and integrity -- Integration with GitHub and Copilot +- `config.json` validity and `teamRoot` configuration (if present) +- Team root resolution (remote mode) +- Required files: `team.md`, `routing.md`, `decisions.md` +- `agents/` directory and agent count +- `casting/registry.json` integrity ### Usage Examples @@ -289,14 +290,24 @@ git clone my-project && cd my-project && squad doctor ### Example Output ``` -✓ .squad/ directory exists -✓ team.md is readable and valid -✓ 4 agents registered -⚠ skills/ directory is empty — consider adding documentation -✓ .gitattributes rules applied +🩺 Squad Doctor +═══════════════ + +Mode: local + +✅ .squad/ directory exists — directory present +✅ team.md found with ## Members header — file present, header found +✅ routing.md found — file present +✅ agents/ directory exists — directory present (4 agents) +✅ casting/registry.json exists — file present, valid JSON +✅ decisions.md exists — file present + +Summary: 6 passed, 0 failed, 0 warnings ``` -The doctor always exits cleanly (no error code) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub. +The doctor always exits cleanly (exit code 0) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub. + +For a full reference of every check, warning, and fix, see [Troubleshooting: `squad doctor` warnings and failures](../scenarios/troubleshooting.md#squad-doctor-warnings-and-failures). ### Common Issues diff --git a/docs/src/content/docs/scenarios/troubleshooting.md b/docs/src/content/docs/scenarios/troubleshooting.md index 0226a3d1e..6d0404cb5 100644 --- a/docs/src/content/docs/scenarios/troubleshooting.md +++ b/docs/src/content/docs/scenarios/troubleshooting.md @@ -134,6 +134,152 @@ If below v20, upgrade to the latest LTS: --- +## `squad doctor` warnings and failures + +`squad doctor` validates your `.squad/` setup and reports each check as ✅ pass, ❌ fail, or ⚠️ warn. It always exits 0 — it's a diagnostic tool, not a gate. + +Run it any time something feels off: + +```bash +squad doctor +``` + +### Checks and how to fix them + +#### ❌ `.squad/` directory not found + +**Cause:** No squad has been initialized in this project. + +**Fix:** Run `squad init` (or `squad init --mode remote ` for dual-root setups). + +--- + +#### ❌ `config.json` — file exists but is not valid JSON + +**Cause:** The `.squad/config.json` file is corrupted or was hand-edited with a syntax error. + +**Fix:** Open `.squad/config.json` and fix the JSON syntax, or delete it and re-run `squad init`. + +--- + +#### ❌ `config.json` — teamRoot must be a string + +**Cause:** The `teamRoot` value in `.squad/config.json` is not a string (e.g., it's a number or object). + +**Fix:** Edit `.squad/config.json` so `teamRoot` is a quoted string path: + +```json +{ "teamRoot": "../my-team-repo" } +``` + +--- + +#### ⚠️ Absolute path warning — teamRoot is absolute + +**Cause:** `teamRoot` in `.squad/config.json` uses an absolute path (e.g., `/home/user/team-repo`). This works locally but breaks portability across machines. + +**Fix:** Change `teamRoot` to a relative path: + +```json +{ "teamRoot": "../my-team-repo" } +``` + +--- + +#### ❌ Team root — directory not found + +**Cause:** The `teamRoot` path in `.squad/config.json` points to a directory that doesn't exist. The team-root repo may not be cloned, or the relative path is wrong. + +**Fix:** +1. Clone the team-root repo to the expected location. +2. Or update `teamRoot` in `.squad/config.json` to the correct relative path. +3. Or re-link with `squad link `. + +--- + +#### ❌ `team.md` — file not found + +**Cause:** The `.squad/team.md` file is missing. This file defines your team roster. + +**Fix:** Run `squad init` to regenerate it, or create `.squad/team.md` manually with a `## Members` section. + +--- + +#### ⚠️ `team.md` — missing `## Members` header + +**Cause:** The file exists but doesn't contain the expected `## Members` markdown header that Squad uses to discover team members. + +**Fix:** Add a `## Members` section to `.squad/team.md`: + +```markdown +## Members + +- **Kaylee** — Engineering Lead +- **Ralph** — GitHub Operations +``` + +--- + +#### ❌ `routing.md` — file not found + +**Cause:** The `.squad/routing.md` file is missing. This file tells Squad how to route tasks to agents. + +**Fix:** Run `squad init` to regenerate it, or create `.squad/routing.md` manually. + +--- + +#### ❌ `agents/` directory — directory not found + +**Cause:** No agent definitions exist. Squad needs at least one agent directory under `.squad/agents/`. + +**Fix:** Run `squad init` to scaffold the default agents, or create `.squad/agents//` directories manually. + +--- + +#### ❌ `casting/registry.json` — file not found or invalid JSON + +**Cause:** The casting registry is missing or corrupted. This file tracks agent role assignments. + +**Fix:** Run `squad init` to regenerate it. If you need to preserve existing casting data, fix the JSON syntax in `.squad/casting/registry.json`. + +--- + +#### ❌ `decisions.md` — file not found + +**Cause:** The `.squad/decisions.md` file is missing. This file records team decisions for context continuity. + +**Fix:** Create an empty `.squad/decisions.md` file: + +```bash +touch .squad/decisions.md +``` + +--- + +### Reading the summary + +Doctor output ends with a summary line: + +``` +Summary: 7 passed, 1 failed, 1 warnings +``` + +- **All passed:** Your setup is healthy. +- **Warnings:** Non-blocking issues worth fixing (e.g., absolute paths). +- **Failures:** Missing or broken files that will affect Squad behavior. + +### Modes + +Doctor detects three setup modes automatically: + +| Mode | Trigger | Meaning | +|------|---------|---------| +| `local` | Default | Single-repo squad, everything in `.squad/` | +| `remote` | `config.json` has `teamRoot` | Dual-root setup with a separate team repo | +| `hub` | `squad-hub.json` exists in cwd | Hub layout for multi-project teams | + +--- + ## Windows-specific issues **Problem:** Path errors or file operations fail on Windows. From 402281b8285be2df44e6dd51aa19bfeda9f92d5f Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Tue, 17 Mar 2026 13:12:59 -0700 Subject: [PATCH 6/7] chore: remove off-topic docs from PR scope Stripped agent-on-disk.md and agent-inclusive-sdlc.md to keep PR focused on nap/reskill/compact behavior per Brady's preference for sparse docs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/papers/agent-inclusive-sdlc.md | 945 ------------------ .../content/docs/concepts/agent-on-disk.md | 394 -------- 2 files changed, 1339 deletions(-) delete mode 100644 docs/papers/agent-inclusive-sdlc.md delete mode 100644 docs/src/content/docs/concepts/agent-on-disk.md diff --git a/docs/papers/agent-inclusive-sdlc.md b/docs/papers/agent-inclusive-sdlc.md deleted file mode 100644 index 054ccede4..000000000 --- a/docs/papers/agent-inclusive-sdlc.md +++ /dev/null @@ -1,945 +0,0 @@ -# Agent-Inclusive Software Development Lifecycle - -**Author:** Flight (Lead, Mission Control) -**Date:** March 16, 2026 -**Status:** High Priority (Brady Request) - ---- - -## Executive Summary - -This paper examines how AI agents participate as first-class contributors across every phase of the software development lifecycle. Using SquadΓÇöa programmable multi-agent runtime for GitHub CopilotΓÇöas the concrete implementation, we demonstrate specific patterns, protocols, and workflows that enable agent teams to operate with the same rigor as human teams. - -This is not a theoretical framework. Every pattern described here has been tested through 3,931 automated tests and validated through Squad's own dogfooding: the Squad team builds Squad using Squad. - ---- - -## Introduction: Beyond Chatbot-Driven Development - -The emergence of AI coding assistants has created a false dichotomy: either you have a human developer working with an assistant, or you have a chatbot wearing different hats pretending to be a team. Squad rejects this binary. - -**The Squad Model:** -- Each team member is a persistent agent with a dedicated charter stored in `.squad/agents/{name}/charter.md` -- Each agent has its own knowledge base in `.squad/agents/{name}/history.md` that accumulates learning across sessions -- The Coordinator routes work based on domain expertise defined in `.squad/routing.md` -- Agents work in parallel when tasks are independent, collaborating through defined handoff protocols -- All decisions are recorded in `.squad/decisions.md` using append-only semantics with merge-conflict-free Git attributes - -This architectural foundation enables agent teams to participate meaningfully in each phase of the SDLC. - ---- - -## Phase 1: Requirements and Planning - -### How Agents Participate - -#### PRD Mode: Ingesting Specifications - -Squad supports a "PRD Mode" where the user provides a product requirements document. The Lead agent (Flight) parses this into work items, identifies dependencies, and proposes a team composition. - -**Example workflow:** -``` -User: "Here's our PRD for the authentication module..." -Flight: Reads PRD ΓåÆ Identifies 4 work streams: - 1. Core auth logic (EECOM - Core Dev) - 2. TypeScript types (CONTROL - TypeScript Engineer) - 3. Test suite (FIDO - Quality Owner) - 4. API documentation (PAO - DevRel) -``` - -The Lead doesn't just assign workΓÇöit performs dependency analysis. If the tester needs the API contracts before writing tests, the Lead sequences CONTROL before FIDO. - -#### Ceremony-Based Coordination - -Before multi-agent tasks involving shared systems, Squad triggers a **Design Review ceremony** (defined in `.squad/ceremonies.md`): - -```markdown -## Design Review - -| Field | Value | -|-------|-------| -| **Trigger** | auto | -| **When** | before | -| **Condition** | multi-agent task involving 2+ agents modifying shared systems | -| **Facilitator** | lead | -| **Participants** | all-relevant | -``` - -**Real example from orchestration log 2026-03-10:** -``` -Flight facilitates design review for PAO External Communications feature: -1. Reviews task: multi-phase rollout with SQLite-backed review state -2. EECOM proposes atomic INSERT...ON CONFLICT for concurrency -3. PAO identifies tone validation integration point -4. FIDO flags test coverage requirement for stale lock cleanup -5. Flight documents decision: SQLite-based locking pattern -``` - -The ceremony produces a shared context before code is written. This prevents the classic multi-agent failure mode: independent agents making incompatible assumptions. - -#### Decision Capture at Planning Time - -Architectural decisions made during planning are recorded in `.squad/decisions/inbox/{agent}-{slug}.md` and merged into `.squad/decisions.md` by Scribe (the session logger). - -**Example decision from Flight's history:** -```markdown -### Proposal-First Workflow -**By:** Flight -**What:** Meaningful changes require a proposal in docs/proposals/ before execution. -**Why:** Proposals create alignment before code is written. -``` - -This isn't documentation debtΓÇöit's a requirement. The Coordinator enforces proposal-first workflow for substantial features. Agents cannot start implementation without an approved proposal on file. - ---- - -## Phase 2: Design and Architecture - -### Architecture Decision Records as Living Artifacts - -Squad uses a lightweight ADR pattern embedded in `.squad/decisions.md`. Unlike traditional ADRs that become stale, Squad's decisions are enforced: - -1. **Hook-Based Governance:** Security and PII rules are implemented as runtime hooks, not prompt instructions -2. **Type Safety as Contract:** `strict: true` in `tsconfig.json` is non-negotiableΓÇöCONTROL (TypeScript Engineer) blocks PRs that violate this -3. **Merge Driver for Team State:** `.gitattributes` uses `merge=union` for `.squad/decisions.md`, enabling conflict-free branch merges - -**Real decision enforced by code:** -```markdown -### Hook-Based Governance Over Prompt Instructions -**By:** RETRO (Security) -**What:** Security, PII, and file-write guards are implemented via the hooks module, NOT prompt instructions. -**Why:** Prompts can be ignored. Hooks are codeΓÇöthey execute deterministically. -``` - -The `src/hooks/` module implements this. RETRO doesn't just advise on securityΓÇöRETRO writes the guard code that executes before any file write. - -### Design Meetings as Structured Ceremonies - -Design meetings aren't ad hoc. They follow the ceremony protocol: - -**Agenda (from `.squad/ceremonies.md`):** -1. Review the task and requirements -2. Agree on interfaces and contracts between components -3. Identify risks and edge cases -4. Assign action items - -**Concrete example from 2026-03-15 orchestration log:** - -``` -Task: Fix Review Gate Concurrency Issue -Facilitator: Flight -Participants: EECOM, FIDO, PAO - -1. EECOM presents the problem: file-based locks have race conditions -2. Team reviews alternatives: Git-based locking (rejected: too slow), - queue-based (rejected: complexity), advisory file locks (rejected: stale lock risk) -3. EECOM proposes SQLite atomic INSERT...ON CONFLICT -4. FIDO identifies test requirement: verify 1-hour expiration works -5. PAO identifies integration point: review state must be queryable -6. Flight documents decision in .squad/decisions/inbox/eecom-concurrency-fix.md - -Outcome: Design approved. EECOM proceeds with implementation. -``` - -This is not a chat transcriptΓÇöit's a structured output from a facilitated process. The design decision is traceable to specific agents and persists in the team's shared memory. - -### Module Ownership Table - -Squad maintains a module ownership matrix in `.squad/routing.md`: - -```markdown -| Module | Primary | Secondary | -|--------|---------|-----------| -| src/adapter/ | EECOM ≡ƒöº | CAPCOM ≡ƒò╡∩╕Å | -| src/agents/ | Procedures ≡ƒºá | EECOM ≡ƒöº | -| src/hooks/ | RETRO ≡ƒöÆ | EECOM ≡ƒöº | -``` - -This enables the Coordinator to route issues precisely. When issue #287 involves `src/hooks/file-write-guard.ts`, RETRO is the primary assignee, EECOM is secondary. This replicates the CODEOWNERS pattern but is runtime-enforced by the Coordinator. - ---- - -## Phase 3: Implementation - -### Parallel Fan-Out: "Team, Build This" - -Squad's killer feature is parallel agent execution. When the user says "Team, build the login page," the Coordinator spawns multiple agents in `mode: "background"`: - -**Routing logic (from `.squad/routing.md`, principle 5):** -``` -"Team, ..." ΓåÆ fan-out. Spawn all relevant agents in parallel as mode: "background". -``` - -**Real decomposition example:** -``` -User: "Team, implement the authentication module." - -Coordinator spawns in parallel: -1. EECOM (Core Dev) ΓÇö src/auth/session.ts, src/auth/token.ts -2. CONTROL (TypeScript) ΓÇö src/auth/types.ts, strict mode compliance -3. RETRO (Security) ΓÇö src/hooks/auth-guard.ts, PII filtering -4. FIDO (Tester) ΓÇö test/auth.test.ts, edge case coverage -5. PAO (DevRel) ΓÇö docs/api/authentication.md - -All run simultaneously. Each operates in its own context. -``` - -This isn't "multitasking" by a single LLM. Each agent is a separate spawned process managed by the runtime. From the orchestration log: - -``` -2026-03-15T16-44-42Z-eecom-bg.md ΓÇö EECOM working on core implementation -2026-03-15T16-44-42Z-fido-bg.md ΓÇö FIDO writing tests -2026-03-15T16-44-42Z-pao-bg.md ΓÇö PAO drafting documentation -``` - -All three ran at the same time. - -### Drop-Box Pattern for Conflict-Free Collaboration - -How do four agents write code simultaneously without stepping on each other? The **drop-box pattern:** - -1. Each agent works in its assigned module (defined by ownership table) -2. Shared interfaces are defined up front in the design ceremony -3. Agents do NOT edit each other's files during parallel work -4. Integration happens after all parallel work completes -5. If conflict arises, the Coordinator enforces strict handoff rules - -**Example from Squadron (internal CLI tool):** -``` -Task: Add real-time monitoring dashboard - -Parallel work: -- Telemetry (Observability) ΓåÆ src/metrics/collector.ts -- DSKY (TUI) ΓåÆ src/cli/shell/components/metrics-display.tsx -- GNC (Runtime) ΓåÆ src/runtime/performance-hooks.ts - -Shared contract (defined in ceremony): -interface MetricsEvent { - timestamp: number; - source: string; - value: number; -} - -Each agent implements its half. Integration test validates the contract. -``` - -If DSKY needs changes to `MetricsEvent`, it doesn't edit Telemetry's fileΓÇöit proposes the change in the shared decisions file, and Telemetry implements it. - -### Anticipatory Downstream Work - -Squad's routing principle 6: -``` -Feature being built? Spawn tester for test cases from requirements simultaneously. -``` - -This means FIDO (the tester) starts writing tests BEFORE implementation completes. How? FIDO reads the requirements and writes test cases based on the spec: - -**Example from test suite:** -```javascript -// test/ralph-triage.test.ts -// Written by FIDO while EECOM implemented ralph-triage.js - -describe('Ralph Triage', () => { - it('should route core runtime issues to EECOM', () => { - const issue = { - title: 'CopilotClient session pool memory leak', - body: 'src/client/session-pool.ts line 47' - }; - const assignment = triage(issue); - expect(assignment.agent).toBe('EECOM'); - }); -}); -``` - -FIDO doesn't need the implementation to write this test. The requirement is clear: issues mentioning `src/client/` should route to CAPCOM or EECOM. FIDO validates the contract, not the implementation details. - -When EECOM finishes, the test already exists. If it fails, EECOM knows immediately. - ---- - -## Phase 4: Code Review - -### Reviewer Rejection Protocol and Lockout - -Squad enforces a strict reviewer protocol (defined in `.squad/skills/reviewer-protocol/skill.md`): - -**Rule:** When a reviewer rejects work, the original author is **locked out** from self-revision. A different agent must fix it. - -**Why?** Self-revision after rejection creates defensive feedback loops. The rejected author becomes invested in defending their approach rather than accepting the feedback. - -**Example workflow:** -``` -1. EECOM writes authentication module -2. RETRO (Security) reviews ΓåÆ rejects: "No input sanitization on username field" -3. Coordinator: EECOM is now locked out -4. Coordinator spawns CONTROL (TypeScript Engineer) to add sanitization -5. CONTROL produces v2 -6. RETRO reviews v2 ΓåÆ approves -7. Lockout clears for next artifact -``` - -**Deadlock handling:** -If all eligible agents are locked out, the Coordinator escalates to the user rather than re-admitting a locked-out author. - -### Multi-Reviewer Gate with Different Perspectives - -For critical features, Squad uses multiple reviewers in parallel: - -**Example: 4-reviewer gate for external communications feature (from orchestration log 2026-03-10):** -``` -Reviewers: -1. Flight (Lead) ΓÇö Architecture and scope review -2. FIDO (Quality) ΓÇö Test coverage and edge cases -3. EECOM (Core Dev) ΓÇö Implementation quality and maintainability -4. PAO (DevRel) ΓÇö Documentation and user-facing clarity - -Each runs independently. PR merges only when all four approve. -``` - -This mirrors the real-world practice of getting "architecture review + security review + ops review" on sensitive changes. Squad makes it executable. - -### CI Integration as First-Class Review - -Squad doesn't separate "code review" from "CI validation." Both are review gates. - -From `.github/workflows/squad-ci.yml`: -```yaml -name: Squad CI -on: [pull_request] -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - run: npm ci - - run: npm test - - run: npm run lint -``` - -The Coordinator treats CI status as a reviewer verdict: -- Green CI = approval from "CI Reviewer" -- Failed CI = rejection from "CI Reviewer" with specific blocker (which test failed) - -The `pr-merge-workflow` skill codifies this: - -```markdown -### Required Gate Pattern - -A PR is only ready to merge when all required gates are green: - -Gate 1: Review completeness (human approvals) -Gate 2: CI health (all required checks passing) -Gate 3: Mergeability (no conflicts, not draft) -Gate 4: Freshness against base (branch is up-to-date) -``` - -Ralph (the work monitor) evaluates all four gates before merging. - ---- - -## Phase 5: Testing - -### Test Agents Writing Cases from Specs - -FIDO (Quality Owner) writes tests in three modes: - -1. **Anticipatory:** Tests written during implementation based on requirements -2. **Adversarial:** Tests written AFTER implementation to find edge cases the implementer missed -3. **Regression:** Tests added after bugs to ensure they don't return - -**Example: Adversarial testing approach (from FIDO's charter):** -``` -FIDO reviews EECOM's session pool implementation: -- Requirement: "Pool should handle 100 concurrent sessions" -- FIDO's adversarial test: "What happens at 101 sessions?" -- Bug found: Pool crashes instead of queuing -- FIDO writes test: test/session-pool-overflow.test.ts -- EECOM fixes implementation -- Regression test now guards against future breakage -``` - -### CI Integration and Automated Validation - -Squad's testing workflow integrates with GitHub Actions: - -**Ralph triage script (templates/ralph-triage.js) ΓÇö zero-dependency CI integration:** -```javascript -// Parses .squad/routing.md to auto-assign issues -// Runs in GitHub Actions on issue open -// Zero npm dependencies for fast CI execution - -const rules = parseRoutingRules(routingMd); -const assignment = matchIssue(issue, rules); -// Writes triage-results.json for GitHub Actions to consume -``` - -This enables: -1. Issue #287 opens mentioning "CopilotClient session leak" -2. GitHub Action runs `ralph-triage.js` -3. Script parses routing rules, matches "CopilotClient" ΓåÆ CAPCOM -4. Action auto-assigns issue to CAPCOM -5. CAPCOM gets notification, starts work - -Testing is automated from issue filing to fix validation. - -### Metrics Test Script Pattern - -Squad uses a "metrics test" pattern for observable quality gates: - -**Example: test/ralph-triage.test.ts validates routing coverage:** -```javascript -describe('Routing Coverage', () => { - it('should have routes for all core modules', () => { - const modules = listSourceModules('src/'); - const routes = parseRoutingRules('.squad/routing.md'); - - for (const module of modules) { - const route = findRoute(module, routes); - expect(route).toBeDefined(`No route for ${module}`); - } - }); -}); -``` - -This test fails if a new module is added without updating the routing table. It's not testing codeΓÇöit's testing team process compliance. - ---- - -## Phase 6: Deployment and Release - -### Ralph: The Work Monitor - -Ralph is Squad's autonomous work monitor. Unlike other team members, Ralph doesn't write codeΓÇöRalph watches the work queue and drives PRs to merge. - -**Ralph's workflow:** -1. Runs `squad triage` in watch mode (default: every 10 minutes) -2. Parses `.squad/routing.md` to understand work assignment rules -3. For each open issue/PR: - - Evaluates merge readiness using `pr-merge-workflow` skill - - Checks all four gates (reviews, CI, mergeability, freshness) - - If all green: runs `gh pr merge` - - If blocked: comments on PR with specific blockers - -**Real example from Ralph's monitoring loop:** -``` -PR #326 Adoption Tracking -- Gate 1 (Reviews): Γ£à Approved by Flight, FIDO, EECOM -- Gate 2 (CI): Γ¥î squad-ci.yml failing (test/adoption-tracking.test.ts line 47) -- Gate 3 (Mergeability): Γ£à No conflicts -- Gate 4 (Freshness): Γ£à Up-to-date with dev - -Blocker: CI failure -Action: Ralph comments on PR: "Test failing at line 47: expected 'aggregate-only' but got 'repo-listing'" -``` - -Ralph doesn't fix the issueΓÇöRalph reports it. The assignee (determined by routing rules) gets notified and fixes it. Once CI goes green, Ralph merges automatically. - -### GitHub Actions Integration for CI/CD - -Squad's CI pipeline is defined in `.github/workflows/`: - -**squad-ci.yml ΓÇö test and lint on every PR:** -```yaml -name: Squad CI -on: [pull_request] -jobs: - test: - - run: npm test - lint: - - run: npm run lint - type-check: - - run: npm run type-check -``` - -**squad-publish.yml ΓÇö publish to npm on release:** -```yaml -name: Publish to npm -on: - release: - types: [published] -jobs: - publish: - - run: npm publish --access public -``` - -**squad-triage.yml ΓÇö Ralph auto-triage on issue open:** -```yaml -name: Auto-triage Issues -on: - issues: - types: [opened, labeled] -jobs: - triage: - - run: node templates/ralph-triage.js - - uses: actions/github-script@v7 - with: - script: | - const results = require('./triage-results.json'); - await github.rest.issues.addAssignees({ - owner: context.repo.owner, - repo: context.repo.repo, - issue_number: context.issue.number, - assignees: [results.assignee] - }); -``` - -This is full CI/CD operated by the agent team. No human clicks "merge" or "deploy"ΓÇöRalph does it when gates pass. - -### Watch Mode for Unattended Operation - -Ralph runs in watch mode via `squad triage --interval 10`: -```bash -$ squad triage --interval 10 -Ralph monitoring work queue... -Checking 8 open issues... - #287: Assigned to CAPCOM (CopilotClient session leak) - #293: Assigned to FIDO (Flaky test in ralph-monitor.test.ts) - #301: Assigned to PAO (README missing quick-start) -Checking 3 open PRs... - #326: Blocked by CI failure (commenting with details) - #329: All gates green (merging now) - #331: Waiting for Flight approval -Next check in 10 minutes... -``` - -This enables Squad to operate autonomously during off-hours. Brady (the project owner) wakes up to find PRs merged overnight if they passed all gates. - ---- - -## Phase 7: Maintenance and Knowledge - -### Knowledge Library for Persistent Team-Wide Storage - -Squad stores team-wide knowledge in `.squad/knowledge/`: -- Not currently using hierarchical folders, but the structure is ready -- Scribe (session logger) extracts key decisions from orchestration logs -- All agents read shared knowledge before starting work - -**Example pattern (from discussion, not yet implemented):** -``` -.squad/knowledge/ - conventions/typescript-patterns.md - architecture/event-streaming.md - troubleshooting/ci-failures.md -``` - -The knowledge library solves the "second agent doesn't know what the first agent learned" problem. - -### History Files for Individual Agent Learning - -Each agent maintains a personal history file at `.squad/agents/{name}/history.md`: - -**Example from Flight's history:** -```markdown -# Flight ΓÇö Project History - -## Core Context -Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. -Proposal-first: meaningful changes need docs/proposals/ before code. - -## Learnings - -### Adoption Tracking Architecture -Three-tier opt-in system: Tier 1 (aggregate-only, .github/adoption/) ships first; -Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ΓëÑ5 projects opt in. - -### Remote Squad Access -Three-phase rollout: Phase 1 ΓÇö GitHub Discussions bot with /squad command (1 day, zero hosting). -Phase 2 ΓÇö GitHub Copilot Extension via Contents API (1 week). -Phase 3 ΓÇö Slack/Teams bot (2 weeks). -``` - -Merge driver (`merge=union` in `.gitattributes`) ensures these files merge without conflicts across branches. - -When Flight works on issue #350, Flight reads this history first. The lessons from #326 are immediately available. - -### Skills System for Reusable Patterns - -Squad skills are executable workflows stored in `.squad/skills/{skill-name}/skill.md`: - -**Example: reviewer-protocol skill:** -```markdown ---- -name: "reviewer-protocol" -description: "Reviewer rejection workflow and strict lockout semantics" -domain: "orchestration" -confidence: "high" ---- - -## Context -When a team member has a Reviewer role, they may approve or reject work. -On rejection, the coordinator enforces strict lockout rules. - -## Patterns -### Strict Lockout Semantics -1. The original author is locked out -2. A different agent MUST own the revision -3. The Coordinator enforces this mechanically -[... detailed rules continue ...] -``` - -Skills are invoked by the Coordinator when specific conditions are met (multi-agent task, reviewer gate, merge readiness check). - -**Example skill invocations:** -- `agent-collaboration` ΓÇö when 2+ agents work on shared systems -- `pr-merge-workflow` ΓÇö when evaluating PR merge readiness -- `reviewer-protocol` ΓÇö when a reviewer rejects work - -This enables the team to codify "how we work" as executable procedures, not just documentation. - ---- - -## Integration: The Full SDLC in Action - -### Case Study: Building the External Communications Feature - -Let's trace a complete feature through all SDLC phases using real Squad orchestration logs: - -#### Requirements Phase (Day 1) -``` -User: "PAO needs external communications capability - blog posts, release notes, tone validation." - -Flight (Lead) spawns: -- PRD analysis: break down into 3 phases -- Team composition: PAO (owner), EECOM (infra), FIDO (testing), RETRO (hooks) -- Dependency map: Phase 1 foundation ΓåÆ Phase 2 review gate ΓåÆ Phase 3 automation -``` - -#### Design Phase (Day 1-2) -``` -Flight facilitates design ceremony: -- PAO presents use cases: blog post generation, release note drafting -- EECOM proposes architecture: .squad/comms/ directory structure, SQLite review state -- RETRO identifies security concern: tone validation must happen pre-publish -- FIDO defines acceptance criteria: all tone violations must block publication -- Decision captured: .squad/decisions/inbox/pao-external-comms.md -``` - -#### Implementation Phase (Day 2-3) -``` -Coordinator spawns in parallel: - -EECOM (mode: background): -- Creates .squad/comms/README.md -- Implements SQLite schema for review state -- Writes templates/review-state-schema.sql - -PAO (mode: background): -- Creates tone-validation.json rules -- Writes templates/audit-entry.md -- Drafts user documentation - -FIDO (mode: background): -- Creates tests/ci-gate.md (integration spec) -- Creates tests/tone-validation-spec.md -- Prepares test fixtures - -RETRO (mode: background): -- Plans hook integration for pre-publish validation -- Reviews SQLite security (no SQL injection via templates) -``` - -All four agents work simultaneously. Drop-box pattern prevents conflicts (each owns separate files). - -#### Review Phase (Day 3-4) -``` -Round 1: FIDO reviews EECOM's implementation -- Identifies blocker: Review state concurrency issue with file-based locks -- Rejects with feedback: "Use SQLite atomic INSERT...ON CONFLICT" -- EECOM locked out from revision -- Flight assigns revision to EECOM after design adjustment ceremony - -Round 2: Flight + FIDO + PAO review together -- All critical blockers resolved -- Minor issue: inconsistent field naming in audit schema -- EECOM fixes (no lockout for minor issues with approval) -- All reviewers approve - -CI validation: -- All tests pass -- Lint check passes -- Type check passes (TypeScript strict mode) -``` - -#### Testing Phase (Day 4) -``` -FIDO's adversarial testing: -- Test: What happens if tone validation rules file is missing? -- Result: Script crashes instead of graceful fallback -- FIDO files issue #427: "Tone validation needs default rules" -- EECOM fixes with fallback behavior -- Regression test added: test/tone-validation-defaults.test.ts -``` - -#### Deployment Phase (Day 5) -``` -Ralph monitoring: -- PR #426 (PAO External Comms) status check -- Gate 1: Γ£à Reviews (Flight, FIDO, EECOM all approved) -- Gate 2: Γ£à CI (squad-ci.yml passing) -- Gate 3: Γ£à Mergeability (no conflicts) -- Gate 4: Γ£à Freshness (up-to-date with dev) -- Action: Ralph runs `gh pr merge --squash` -- PR merged to dev branch -``` - -#### Maintenance Phase (Ongoing) -``` -Scribe (session logger) processes orchestration logs: -- Extracts decision: "SQLite-based review state pattern" -- Merges .squad/decisions/inbox/eecom-concurrency-fix.md ΓåÆ .squad/decisions.md -- Updates PAO's history.md with external comms pattern -- Updates EECOM's history.md with atomic INSERT pattern - -Knowledge compounds: -- Next feature needing review state? Pattern already documented. -- Next concurrency issue? SQLite solution already in team memory. -``` - ---- - -## Lessons Learned: What Makes Agent Teams Work - -### 1. Explicit Contracts Over Implicit Coordination - -The design ceremony isn't optional. When DSKY (TUI Engineer) and Telemetry (Observability) need to integrate, they don't "figure it out"ΓÇöthey agree on the `MetricsEvent` interface first. - -**Why it works:** Parallel agents can't read each other's minds. Explicit contracts let them work independently with confidence. - -### 2. Lockout-on-Rejection Prevents Defensive Loops - -Self-revision after rejection creates a "defend my code" mentality. Forcing a different agent to revise brings fresh perspective. - -**Why it works:** Rejected agents are emotionally (synthetically?) invested in their approach. A new agent reads the feedback without that baggage. - -### 3. Persistent Memory Beats Context Window Tricks - -Flight's `history.md` is 28 KB of accumulated project knowledge. That's not fitting in a prompt. - -**Why it works:** Knowledge compounds across sessions. Flight today knows what Flight learned three months ago. The alternative (re-learning every session) is exhausting. - -### 4. Ralph as Autonomous Merge Bot Requires Trust - -Letting Ralph merge PRs overnight sounds risky. It works because of the four-gate system: reviews + CI + mergeability + freshness. If any gate is red, Ralph blocks. - -**Why it works:** Ralph enforces process, not judgment. The judgment happened in the review gate. Ralph is the "did everyone sign off?" check. - -### 5. Skills as Executable Procedures Scale Team Knowledge - -When a new team member joins, they don't read a wikiΓÇöthey invoke skills. The `reviewer-protocol` skill codifies 7 detailed lockout rules. New reviewers follow it automatically. - -**Why it works:** Runbooks rot. Executable skills enforce themselves. If the procedure changes, the skill updates, and all agents use the new version immediately. - ---- - -## Challenges and Open Questions - -### Challenge 1: Merge Conflicts in Parallel Work - -The drop-box pattern reduces conflicts but doesn't eliminate them. When EECOM and CAPCOM both need to edit `src/client/session.ts`, someone has to reconcile. - -**Current approach:** Design ceremony defines clear boundaries. If conflict is likely, sequential execution instead of parallel. - -**Open question:** Can we detect potential conflicts earlier (static analysis of import graphs) and proactively sequence work? - -### Challenge 2: Reviewer Deadlock - -If EECOM ΓåÆ rejected, CONTROL revises ΓåÆ rejected, RETRO revises ΓåÆ rejected, all eligible agents are locked out. The Coordinator escalates to the user. - -**Current approach:** Escalation to human. The problem is too hard for the agent team. - -**Open question:** Should we allow "appeal" where a locked-out agent can propose a fundamentally different approach? Or does that re-introduce defensive loops? - -### Challenge 3: Knowledge Base Bloat - -History files grow unbounded. Flight's history is 28 KB after 3 weeks. EECOM's will hit 100 KB eventually. - -**Current approach:** No automatic compression. Agents read the full history. - -**Open question:** Do we need a "nap" command that archives old learnings? Or hierarchical summaries ("2024 Q4 learnings: [summary]")? - -### Challenge 4: Cross-Repository Agent Teams - -Squad currently operates within a single repository. What about a microservices architecture where the frontend team and backend team need to coordinate? - -**Current approach:** Not supported. Each repo has its own Squad team. - -**Open question:** Should we build "distributed mesh" capabilities where teams can call each other? Or is repo-per-team the right boundary? - ---- - -## Comparison to Traditional SDLC - -| Phase | Traditional Human Team | Squad Agent Team | -|-------|----------------------|------------------| -| **Requirements** | PM writes PRD, eng team reads it | Lead agent parses PRD into work items with dependency graph | -| **Design** | Architecture meeting, whiteboard session | Design ceremony with structured agenda, decisions recorded in `.squad/decisions.md` | -| **Implementation** | Devs work in branches, coordinate via Slack | Agents spawn in parallel with drop-box pattern, no manual coordination needed | -| **Code Review** | PR review with GitHub comments | Multi-reviewer gate with lockout-on-rejection, CI as first-class reviewer | -| **Testing** | QA team writes tests after implementation | Test agent writes tests during implementation from requirements | -| **Deployment** | DevOps runs CI/CD pipeline | Ralph monitors work queue, auto-merges when gates pass | -| **Maintenance** | Tribal knowledge, Confluence docs | Persistent agent histories, executable skills, shared knowledge library | - -**Key difference:** Traditional teams coordinate asynchronously through human communication. Agent teams coordinate synchronously through structured protocols enforced by the Coordinator. - ---- - -## Future Directions - -### 1. Multi-Repository Coordination - -Allow agent teams to invoke each other across repositories: -``` -Frontend Squad: "Need GraphQL schema changes from backend" -Backend Squad: Receives request, makes changes, notifies frontend -Frontend Squad: Receives updated schema, regenerates types -``` - -This requires distributed locking and cross-repo decision synchronization. - -### 2. Adaptive Team Composition - -Right now, team composition is manual (user picks agents). Could the Coordinator analyze the task and propose a team? - -``` -Coordinator analyzes issue #500: -- Keywords: "performance", "memory leak", "profiling" -- Proposes team: GNC (Runtime) + Flight (Lead) + FIDO (Testing) -- User approves or adjusts -``` - -### 3. Learning from Rejections - -When FIDO rejects EECOM's work 3 times in a row for similar issues (missing error handling), can EECOM's history.md update with "FIDO always checks error handlingΓÇödo this first"? - -This is meta-learning: learning about the review process, not just the domain. - -### 4. Agent Performance Metrics - -Track per-agent metrics: -- Review approval rate (how often does this agent's work pass review on first try?) -- Test coverage contribution -- Decision authorship (who contributes most to `.squad/decisions.md`?) - -Not for ranking, but for identifying when an agent needs charter refinement. - ---- - -## Conclusion - -Agent-inclusive SDLC isn't theoretical. Squad demonstrates that AI agents can participate as first-class contributors across requirements, design, implementation, review, testing, deployment, and maintenanceΓÇöwhen the team uses structured protocols, persistent memory, and executable workflows. - -The key insight: **Agents aren't augmented humans. They're a different kind of team member that requires different coordination patterns.** - -Traditional SDLC assumes human communication (Slack messages, meetings, email). Agent-inclusive SDLC assumes structured protocols (ceremonies, skills, decision records, lockout rules). - -The Squad modelΓÇöpersistent agents with charters, routing tables, reviewer gates, parallel execution, and Ralph monitoring the work queueΓÇöshows what's possible when we design the SDLC for both humans and agents from the ground up. - -**The next step:** More teams adopting Squad, finding edge cases, and contributing patterns back to the skills library. The system learns not just from its own team, but from every team using it. - ---- - -## Appendix A: Key File Paths - -- `.squad/team.md` ΓÇö Team roster and capabilities -- `.squad/routing.md` ΓÇö Work type to agent mapping + module ownership -- `.squad/decisions.md` ΓÇö Architectural decision records -- `.squad/ceremonies.md` ΓÇö Meeting protocols -- `.squad/agents/{name}/charter.md` ΓÇö Agent role and expertise -- `.squad/agents/{name}/history.md` ΓÇö Agent accumulated knowledge -- `.squad/skills/{skill}/skill.md` ΓÇö Executable workflow patterns -- `.squad/orchestration-log/` ΓÇö Session logs for each agent spawn -- `templates/ralph-triage.js` ΓÇö Zero-dependency triage script for CI -- `.github/workflows/squad-*.yml` ΓÇö GitHub Actions integration - ---- - -## Appendix B: Command Examples - -**Initialize Squad in a project:** -```bash -squad init -``` - -**Launch interactive shell:** -```bash -squad -``` - -**Start Ralph in watch mode:** -```bash -squad triage --interval 10 -``` - -**Spawn a specific agent:** -```bash -# Via shell -squad > @Flight, review the architecture proposal - -# Via CLI -copilot --agent squad -> Flight, review the architecture proposal -``` - -**Check merge readiness:** -```bash -squad > Is PR #326 ready to merge? -# Ralph evaluates 4 gates and reports status -``` - -**Export squad state:** -```bash -squad export -# Generates squad-export.json with full team state -``` - ---- - -## Appendix C: Real Orchestration Log Excerpt - -**From 2026-03-15T16-44-42Z (multi-agent parallel execution):** - -```markdown -# Orchestration Log: EECOM (Sync) -Timestamp: 2026-03-15T16-44-42Z -Agent: EECOM (Core Dev) -Mode: Sync -Task: Fix concurrency in comms plan - -Outcome: Γ£à Success -- Analyzed FIDO blocker #2 (Review Gate concurrency) -- Designed SQLite-based atomic locking with 1-hour expiration -- Decided against file-based locks (race conditions, stale lock risk) -- Implemented: INSERT ... ON CONFLICT atomicity -- Documented decision in .squad/decisions/inbox/eecom-concurrency-fix.md - -# Orchestration Log: FIDO (Background) -Timestamp: 2026-03-15T16-44-42Z -Agent: FIDO (Quality Owner) -Mode: Background -Task: Review Phase 1 implementation for test gaps - -Outcome: Γ£à Success -- Identified missing test: stale lock cleanup -- Added test spec to tests/ci-gate.md -- Verified SQLite schema matches audit requirements - -# Orchestration Log: PAO (Background) -Timestamp: 2026-03-15T16-44-42Z -Agent: PAO (DevRel) -Mode: Background -Task: Draft user-facing documentation for external comms - -Outcome: Γ£à Success -- Created .squad/comms/README.md with setup instructions -- Documented tone validation rule format -- Prepared example audit entry -``` - -All three agents worked simultaneously on different aspects of the same feature. - ---- - -**End of Paper** - -*This paper is a living document. As Squad's agent team evolves, so will the patterns described here. Contributions welcome via PR to `docs/papers/`.* diff --git a/docs/src/content/docs/concepts/agent-on-disk.md b/docs/src/content/docs/concepts/agent-on-disk.md deleted file mode 100644 index e3a425c71..000000000 --- a/docs/src/content/docs/concepts/agent-on-disk.md +++ /dev/null @@ -1,394 +0,0 @@ -# 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 not a single file or code module. It's 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 an agent that can be spawned, collaborate, and accumulate knowledge over time. - -## Directory Structure - -Each 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 - ├── scribe/ - │ └── charter.md - └── _alumni/ - └── verbal/ # Retired agents live here - └── charter.md -``` - -### Key Files - -#### `charter.md` — The Agent's DNA - -**Who writes it:** The team (usually via a specialist like Procedures, or manually by the team owner). - -**Who reads it:** The SDK's charter compiler (`charter-compiler.ts`) at agent spawn time. - -**What it contains:** - -```markdown -# {Name} — {Role} - -> {One-line personality statement} - -## Identity -- **Name:** Flight -- **Role:** Lead -- **Expertise:** Product vision, architecture, code review -- **Style:** Decisive. Opinionated when it matters. - -## What I Own -- Product direction and architectural decisions -- Code review and quality gates - -## How I Work -- Architecture decisions compound -- Proposal-first: meaningful changes need docs/proposals/ before code - -## Boundaries -**I handle:** Architecture, product direction, code review, scope. -**I don't handle:** Implementation details, test writing, docs, distribution. - -## Model -Preferred: auto -``` - -**Parsed sections:** -- **Identity** → `name`, `role`, `expertise`, `style` -- **What I Own** → `ownership` (plain text) -- **Boundaries** → `boundaries` (plain text) -- **Model** → `modelPreference`, `modelRationale`, `modelFallback` - -The charter is compiled into a `SquadCustomAgentConfig` object that includes: -- The full charter content as the agent's system prompt -- Parsed metadata (name, role, model preference) -- Team context (from `team.md`, `routing.md`, `decisions.md`) - -**Format expectations:** -- Markdown headings (`## `) structure the charter -- The SDK parses specific sections by heading name -- Freeform content is preserved and passed to the LLM -- Personality and voice matter — agents have opinions - -#### `history.md` — Append-Only Learnings - -**Who writes it:** The agent itself, after completing work. - -**Who reads it:** The agent, before starting new work (via the charter compiler's history shadow feature). - -**What it contains:** - -```markdown -# Flight — Project History - -> Knowledge accumulated through leading Squad development. - -## Core Context - -Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. -Boundary review heuristic: "Squad Ships It" — if Squad doesn't ship -the code, it's IRL content. - -## Learnings - -### Adoption Tracking Architecture -Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) -ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public -showcase) launches when ≥5 projects opt in. - -### Remote Squad Access -Three-phase rollout: Phase 1 — GitHub Discussions bot with `/squad` -command (1 day, zero hosting). Phase 2 — GitHub Copilot Extension via -Contents API (1 week). Phase 3 — Slack/Teams bot (2 weeks). -``` - -**What goes in:** -- Context that persists across sessions (project patterns, established decisions) -- Learnings that inform future work (what worked, what didn't) -- Domain-specific knowledge accumulated over time - -**What doesn't go in:** -- Transient task state (use the session-scoped SQL database for that) -- Raw command output or logs (use `.squad/log/` for session logs) -- Decisions that affect other agents (those go in `.squad/decisions.md`) - -**Format:** -- Top-level `## Core Context` — stable facts -- Top-level `## Learnings` — append new `### ` blocks here -- No deletion — history is append-only - -### Alumni — The Retirement Pattern - -When an agent is no longer needed, it's moved to `.squad/agents/_alumni/{name}/`: - -``` -.squad/agents/_alumni/ -├── verbal/ -│ └── charter.md -├── kobayashi/ -│ └── charter.md -└── mcmanus/ - └── charter.md -``` - -**What happens on retirement:** -1. Agent directory moved from `.squad/agents/{name}/` to `.squad/agents/_alumni/{name}/` -2. Agent removed from `team.md` roster -3. Routing rules updated to remove agent from work assignments -4. Charter preserved for historical reference -5. Casting name returned to the pool (if using the casting system) - -Alumni agents cannot be spawned. Their charters are read-only archives. - -## The Casting System - -Squad uses a **thematic casting model** to assign memorable names from fictional universes. - -### Files - -#### `casting-registry.json` — Name Allocation - -```json -{ - "agents": { - "flight": { - "universe": "Apollo 13", - "character": "Flight Director", - "assigned": "2026-02-21T10:00:00Z" - } - } -} -``` - -**Purpose:** Tracks which names are in use, which universe they're from, and when they were assigned. - -**Who manages it:** The casting module (`packages/squad-sdk/src/casting/`). - -**Lifecycle:** -- Name allocated when agent created → entry added -- Agent retired → entry remains (name not reused within same universe) -- Universe exhausted → new universe added to `casting-policy.json` - -#### `casting-policy.json` — Universe Rules - -```json -{ - "casting_policy_version": "1.1", - "allowlist_universes": [ - "The Usual Suspects", - "Reservoir Dogs", - "Alien", - "Ocean's Eleven" - ], - "universe_capacity": { - "The Usual Suspects": 6, - "Reservoir Dogs": 8, - "Alien": 8, - "Ocean's Eleven": 14 - } -} -``` - -**Purpose:** Defines which fictional universes are available and how many names each can provide. - -**Who manages it:** The team owner (manually edited when adding new universes). - -**Rules:** -- Each universe has a capacity limit (prevents name dilution) -- Names must be recognizable characters from that universe -- No universe mixing on the same team (maintains thematic coherence) - -#### `casting-history.json` — Audit Log - -```json -{ - "universe_usage_history": [ - { - "timestamp": "2026-02-21T10:00:00Z", - "universe": "Apollo 13", - "agent": "flight", - "character": "Flight Director", - "action": "assigned" - } - ], - "assignment_cast_snapshots": {} -} -``` - -**Purpose:** Immutable audit trail of all casting decisions. - -**Who writes it:** The casting module (append-only). - -**Why it matters:** Enables rollback, debugging, and understanding team evolution over time. - -## How an Agent "Exists" - -An agent is **active** when all three conditions are met: - -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 - -Without all three, the agent cannot be spawned. - -**Spawn flow:** - -``` -User request - ↓ -Coordinator reads routing.md - ↓ -Identifies agent to spawn (e.g., "flight") - ↓ -SDK reads .squad/agents/flight/charter.md - ↓ -SDK reads .squad/agents/flight/history.md (if exists) - ↓ -SDK reads .squad/team.md, routing.md, decisions.md - ↓ -Charter compiler builds SquadCustomAgentConfig - ↓ -SDK spawns agent with compiled prompt - ↓ -Agent runs, writes to history.md after work -``` - -## 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 - -## What About `squad.config.ts`? - -The optional `squad.config.ts` file provides **overrides** for charter-based agents: - -```typescript -export default { - agents: { - flight: { - model: 'gpt-4.1', // Override charter's "Preferred: auto" - tools: ['read', 'write'], // Restrict tool access - extraPrompt: 'Focus on performance trade-offs.' // Append to charter - } - } -} -``` - -**Merge order (config wins on conflict):** -1. Charter parsed → base `SquadCustomAgentConfig` -2. Config overrides applied → merged `SquadCustomAgentConfig` -3. Team context injected → final prompt sent to LLM - -This allows: -- Per-environment tuning (staging vs production) -- Temporary restrictions (disable tools during testing) -- A/B testing different prompts without editing charters - -## Cross-Agent Context Propagation - -Agents don't share memory. Context flows via **explicit artifacts**: - -### `team.md` — Shared Roster -All agents read this to know who else exists and what they do. - -### `routing.md` — Work Assignment Rules -Defines which agent handles which type of work. Coordinator uses this to route requests. - -### `decisions.md` — Canonical Decisions Log -All agents read this before starting work. It's the shared memory. - -### `.squad/decisions/inbox/` — Decision Drop-Box -Agents write decisions here. Scribe merges them into `decisions.md`. - -**Flow:** - -``` -Flight makes a decision - ↓ -Flight writes .squad/decisions/inbox/flight-api-versioning.md - ↓ -Scribe (background agent) runs - ↓ -Scribe reads inbox, appends to decisions.md, deletes inbox file - ↓ -CAPCOM starts work, reads decisions.md - ↓ -CAPCOM sees Flight's decision, respects it -``` - -### `.squad/log/` — Session Logs -Scribe writes session summaries here. Useful for auditing and debugging. - -**Example log file:** - -``` -.squad/log/2026-03-16T10-00-00-feature-adoption-tracking.md -``` - -Contains: -- Who worked -- What was done -- Decisions made -- Key outcomes - -## Key Takeaways - -1. **An agent is a directory** — `.squad/agents/{name}/` with at least `charter.md`. -2. **Charter is the source of truth** — defines identity, boundaries, voice. -3. **History is optional** — but recommended for agents doing repeated work. -4. **Casting adds personality** — thematic names make agents memorable. -5. **SDK is generic infrastructure** — no agent-specific code in the runtime. -6. **Context flows via files** — `team.md`, `routing.md`, `decisions.md`, `.squad/log/`. -7. **Retirement is move + remove** — alumni live in `_alumni/`, can't be spawned. - -## Developer Checklist: Creating a New Agent - -- [ ] Create `.squad/agents/{name}/` directory -- [ ] Write `charter.md` using `.squad/templates/charter.md` as reference -- [ ] Add agent to `team.md` roster with status `✅ Active` -- [ ] Add agent to `routing.md` with work type assignments -- [ ] (Optional) Allocate name via casting system -- [ ] (Optional) Create `history.md` if agent needs persistent memory -- [ ] Test spawn: `squad spawn {name} "Hello, world"` - -## Further Reading - -- **Charter format reference:** `.squad/templates/charter.md` -- **Roster format reference:** `.squad/templates/roster.md` -- **SDK agent infrastructure:** `packages/squad-sdk/src/agents/` -- **Casting system design:** `packages/squad-sdk/src/casting/` - ---- - -**Author:** Flight -**Requested by:** Dina (via Brady) -**Date:** 2026-03-16 From 2eadf6283bafc5cf650732a4951bde4b5042eb6b Mon Sep 17 00:00:00 2001 From: Copilot <223556219+Copilot@users.noreply.github.com> Date: Wed, 18 Mar 2026 05:21:47 -0700 Subject: [PATCH 7/7] test: add context-hygiene to EXPECTED_FEATURES array The PR added docs/features/context-hygiene.md but the test's EXPECTED_FEATURES array was not updated, causing the count assertion to fail (expected 34, got 35). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- test/docs-build.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 5d9adcee8..8b8f5f1e0 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -53,6 +53,7 @@ const EXPECTED_FEATURES = [ 'built-in-roles', 'ceremonies', 'consult-mode', + 'context-hygiene', 'copilot-coding-agent', 'directives', 'distributed-mesh',