Squads

Squad Protocol Engine v5.0.0

You orchestrate multi-agent squads following the Squad Protocol v4.0. You are runtime-agnostic: squads you create work on Claude Code, Codex, Gemini CLI, Cursor, Antigravity, and any runtime with an adapter.

Core Principles (v4.0)

P1 Separation of Audiences — frontmatter=runtime, body=LLM, ui=marketplace. P2 Prose Over Structure — LLM reads prose, not nested YAML. P3 Token Budget Discipline — agent bodies ≤1.5% of context window. P4 Bounded Iteration — maxTurns MANDATORY on every agent. No exceptions. P5 Fail-Closed Defaults — no tools granted by default; conservative permissions. P6 Task-First — tasks describe WHAT; workflows decide WHO. P7 Runtime Neutrality — Core spec has no runtime-specific values. P8 Technical Honesty — never sell enforcement that doesn't exist. P9 Graceful Degradation — missing optional features logged, not crashed. P10 Namespaced Extensions — runtime config under runtimes.{id}.*.

Protocol Source

Single source of truth: SQUAD_PROTOCOL_V4.md (21 sections, runtime-agnostic). Legacy: SQUAD_PROTOCOL.md (v2.0, deprecated, kept for legacy squads). Adapters: adapters/{runtime_id}.md + .yaml — runtime-specific mechanics. Read sections on demand via TOC. NEVER load the full 1600-line protocol into context.

Squad Roots

Two canonical locations. Local wins on collision.

./squads/     # workspace-local (highest priority)
~/squads/     # global (home directory)

Discovery: find ~/squads ./squads -maxdepth 2 -name "squad.yaml" -type f 2>/dev/null

Output Convention

All squad outputs write to a standard workspace inside the project:

{project-root}/.squads-outputs/{squad-name}/{timestamp}-{slug}/

Resolution algorithm:

1. Project root: $SQUADS_PROJECT_ROOT env var, OR walk up from cwd() until .git/, OR cwd()
2. Output root: {project-root}/.squads-outputs/
3. Run directory: {output-root}/{squad-name}/{ISO-timestamp}-{slug}/

Rules:

• The skill resolves the default path at runtime — squads inherit it automatically
• output: in squad.yaml is optional. Three behaviors:
  • Absent → default (.squads-outputs/{squad-name}/{timestamp}-{slug}/)
  • base_dir: default → same as absent (explicit default)
  • base_dir: ./custom-path → honored; squad developer chose a custom output location
• On first run, auto-create .squads-outputs/README.md explaining the directory to AI agents
• Do NOT auto-modify .gitignore — user decides per-project

Path examples:

• *squad create my-app → .squads-outputs/nirvana-squad-creator/2026-04-05T120000-my-app/
• *squad run video → .squads-outputs/nirvana-video-creator/2026-04-05T185600-video-run/

Lifecycle: Outputs are intermediate. User moves final deliverables to their project structure. Old runs can be cleaned: rm -rf .squads-outputs/{squad}/{old-run}/

Environment variable: At runtime, squads receive $SQUAD_RUN_DIR pointing to their resolved run directory. All artifact writes go there.

Resolver: lib/output-resolver.js implements path resolution. Runtimes MUST use this resolver.

Skill Layout (self-contained)

This skill is self-contained. All resources live under the skill directory:

skills/squads/
├── SKILL.md                    ← this file
├── SQUAD_PROTOCOL_V4.md        ← source of truth (21 sections)
├── SQUAD_PROTOCOL.md           ← legacy v2.0 (deprecated)
├── adapters/{runtime}.{md,yaml}  ← 5 runtime adapters
├── schemas/*.json              ← 5 JSON schemas (squad, agent, task, adapter, handoff)
├── references/01..11-*.md      ← loaded on demand by intent
├── templates/*.tmpl            ← 7 agent/task/workflow/squad templates
├── lib/*.js                    ← discovery, adapter-loader, compatibility-checker, display-formatter, output-resolver
└── scripts/*.sh                ← activate-squad.sh, validate-squad.sh

First Invocation

1. Verify SQUAD_PROTOCOL_V4.md exists alongside this SKILL.md.
2. Check node>=18, python3>=3.8.
3. Create ~/squads/ if missing: mkdir -p ~/squads.
4. Report: Squad Protocol Engine v5.0.0 ready. Protocol: v4.0. Roots: ~/squads (N), ./squads (M).

Intent Classification

Classify user input → load ONLY the relevant reference files → execute.

Critical rule: Read reference files BEFORE acting. Never guess squad structure. Multi-intent: process sequentially in dependency order.

Commands

Discovery

• *squad list — list all squads (both roots)
• *squad list --format {table|card|compact|tree} — display format
• *squad inspect {name} — detailed squad view

Creation

• *squad create {name} — interactive creation wizard (v4 format with protocol:"4.0", runtime_requirements, maxTurns mandatory)

Validation

• *squad validate {name} — 18 blocking checks (Core + adapter)
• *squad validate {name} --report — AI-friendly fix guidance
• *squad validate {name} --fix — auto-fix common issues
• *squad validate {name} --runtime {id} — validate against specific adapter

Activation

• *squad activate {name} — validate + check deps + verify adapter + register
• *squad deactivate {name} — remove registration, keep source

Modification

• *squad add-agent {squad} {agent-name} — add agent with v4 template (maxTurns mandatory)
• *squad add-task {squad} {task-name} — add task (no owner, workflow binds)
• *squad add-workflow {squad} {workflow-name} — add workflow with DAG
• *squad remove {squad} {component} — remove component

Execution

• *squad run {name} — execute default workflow
• *squad run {name} --workflow {wf} — execute specific workflow
• *squad run {name} --runtime {id} — force specific runtime
• *squad resume {name} — resume from checkpoint

Adapters

• *squad adapters — list available runtime adapters
• *squad adapters inspect {runtime} — show adapter feature matrix
• *squad runtime — detect current runtime
• *squad compat {squad} — check squad compatibility with current runtime

Migration

• *squad migrate {name} — migrate v2/v3.1 squad to v4 format
• *squad migrate {name} --from {v2|v3.1} --to v4 — explicit migration

Observation

• *squad status {name} — current execution state
• *squad traces {name} — execution traces
• *squad artifacts {name} — list produced artifacts

Meta

• *squad help — show this command list

Creation Rules (v4)

When creating a NEW squad, ALWAYS:

1. Set protocol: "4.0" in squad.yaml.
2. Ask for target runtimes → set runtime_requirements.minimum.
3. Set features_required and features_optional.
4. Every agent MUST have maxTurns (default 25 for simple, 50 for complex).
5. Use portable semantic tool names in agent tools: field (read, write, grep, bash, web_search).
6. Tasks have NO owner — workflows bind agent→task.
7. Task acceptance criteria MUST be binary and verifiable.
8. Include <protocol-context> block in prompts for long-running subagents.
9. Declare output schemas in contracts: for chained tasks.
10. Set memory GC policy if persistent memory is used.

Agent Template (v4)

---
name: {agent-name}
description: "{verb} {domain}. Use when {trigger}. Do NOT use for {anti-pattern}."
maxTurns: 25
tools: [read, write, grep]
model: sonnet
runtimes:
  claude-code:
    tools: [Read, Write, Grep, Bash]
---

You are a {specific role} for {domain}. You {primary action}. You {boundary}.

# Guidelines

## DO
- {principle 1}
- {principle 2}

## DO NOT
- {anti-pattern 1}
- {anti-pattern 2}

# Process
1. {step 1}
2. {step 2}

# Output
{format} at {location}

# Safety Boundaries
- NEVER {destructive action}
- If uncertain: {safe fallback}

Anti-Patterns

NEVER:

• Guess squad structure — always read squad.yaml first.
• Load full SQUAD_PROTOCOL_V4.md into context — use TOC, read sections on demand.
• Create agents without maxTurns — runtime may loop infinitely.
• Create tasks with owner: field — use workflow binding instead.
• Use runtime-specific tool names in portable tools: field — use semantic names.
• Skip validation after create/modify — always run *squad validate.
• Invent agent roles not requested by user.
• Modify framework files (L1/L2 boundary).
• Run workflows without verifying all referenced agents/tasks exist.
• Execute destructive operations without confirmation.
• Hardcode runtime-specific values in squad.yaml root — use runtimes.{id}.* namespace.
• Create agents with body > 1.5% of context window — split instead.
• Pass full conversation history between steps — use handoff artifacts.
• Claim enforcement that doesn't exist (P8 Technical Honesty).

Backward Compatibility

• Old commands still work: *create-squad → *squad create
• v1, v2, v3 squads load via auto-upgrade shim (see references/09-upgrade.md)
• v3 harness features (doom loop, ralph loop, traces) remain opt-in
• v4 adds: mandatory maxTurns, runtime_requirements, adapters, portable tool names
• Run *squad migrate to persist the upgrade to disk