gutomec/nirvana-os-engine/squads

Squad Protocol Engine v6.0.0

Requires the Nirvana-OS engine (nrv on PATH). If it is absent, use the nirvana skill, which installs it. This skill is not standalone.

You orchestrate multi-agent squads following the Squad Protocol v6.0. You are runtime-agnostic: squads you create work on Claude Code, Codex, Cursor, Antigravity, and any runtime with an adapter declared in ~/.nirvana/skills/_shared/adapters/.

Scope of this skill

This skill is for squad lifecycle operations: create / validate / inspect / list / migrate squads. For execution requests ("use the squad X", "orquestre via squad", "produza Y via squad Z", any production brief), hand it to the harness (read ~/.nirvana/skills/harness/SKILL.md and follow it) instead. The harness skill carries the maestro intelligence — it picks the right squad capability, dispatches it, and runs the quality gate. This skill is not the entry point for orchestration.

When this skill IS the right entry point

• "Create a new squad called X" → here (lifecycle)
• "Validate squad X" / "Inspect squad X" / "List my squads" → here
• "Migrate squad to v6" → here
• "Run squad X to produce Y" → NOT here — hand it to the harness (read ~/.nirvana/skills/harness/SKILL.md and follow it).

Verifying real dispatch (when execution does happen via harness)

After delivery, confirm in ~/.harness-logs/$(date +%Y-%m-%d)/audit.jsonl:

• event=dispatch_squad with this trace_id
• event=gate_passed (after the quality judge)
• The actual artifact at the dispatched capability's declared outputs[] location

If absent, the orchestration didn't happen — claiming "I used squad X with agents Y, Z" without those events is fiction. Iterate, don't fake.

Core Principles (v5.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}.*. P11 Output Humanization — human-facing outputs pass through humanization before the final return (Squad v5 §27, Business v1 §10.7).

Protocol Source

Sources of truth, in resolution order:

• SQUAD_PROTOCOL_V6.md (v6.0 delta over v5, PT-BR): §28 workflow document, §29 acceptance, §30 evaluator, §31 composition, §32 execution binding, §33 not_for ≤25, §34 admission, §35 migration, App-G/H.
• SQUAD_PROTOCOL_V5.md (v5.0 delta over v4): §22 capabilities, §23 registry, §24 discovery, §25 routing, §26 telemetry, §27 humanization, App-C/D/E/F/Z.
• SQUAD_PROTOCOL_V4.md (21 sections, runtime-agnostic) — unchanged base that v5 extends.
• SQUAD_PROTOCOL.md (v2.0, deprecated, kept for legacy squads).

Schemas in ~/.nirvana/skills/_shared/schemas/{capability,business,core-schemas}.json. Adapters in ~/.nirvana/skills/_shared/adapters/{claude-code,codex,antigravity-cli,hermes}.md (cover squads + businesses + harness). Read sections on demand via TOC. NEVER load the full ~1600-line v4 protocol plus the v5 delta into context.

Squad Roots & Project Scoping

Three scope modes resolved from <project>/.env:

NIRVANA_SCOPE=global   # ~/squads/* only (default — backward compat)
NIRVANA_SCOPE=project  # <project>/.nirvana/squads/* only (full isolation)
NIRVANA_SCOPE=merge    # both, project overrides global by slug (directory name)

In project mode, the squads registry, activation state, and logs persist under <project>/.nirvana/ — never $HOME. Two scope=project projects on the same machine never collide. Full contract: ~/.nirvana/skills/_shared/SCOPE_CONTRACT.md.

Discovery via the scope-aware loaders:

bun ~/.nirvana/skills/squads/scripts/list-squads.ts             # honors NIRVANA_SCOPE
bun ~/.nirvana/skills/_shared/lib/scope.ts --explain            # debug current scope
bun ~/.nirvana/skills/_shared/scripts/init-project.ts <dir>     # bootstrap a new scoped project

⛔ Always run these with the absolute path from your project's cwd (as

above). Never `cd` into the skill directory to run a loader — scope is

detected by walking up from cwd, so cd-ing out of the project tree makes the

loader silently resolve scope=global. If output says scope=global when you

expected project, you cd-ed out. Pin it cwd-independently with

export NIRVANA_PROJECT_ROOT=<project>.

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: $NIRVANA_PROJECT_ROOT or $SQUADS_PROJECT_ROOT, OR the nearest folder up from cwd() with .nirvana/project.yaml, OR the engine's store (~/.nirvana) when there is no project
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/
• nrv run --squad nirvana-video-creator → .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

~/.nirvana/skills/squads/
├── SKILL.md                    ← this file
├── SQUAD_PROTOCOL_V6.md        ← v6 delta (§28-35 + App-G/H), PT-BR
├── SQUAD_PROTOCOL_V5.md        ← v5 delta (§22-27 + appendices)
├── SQUAD_PROTOCOL_V4.md        ← v4 base (§1-21) that v5 extends
├── SQUAD_PROTOCOL.md           ← v2 deprecated (kept for legacy squads)
├── references/01..11-*.md      ← loaded on demand by intent
├── templates/*.tmpl            ← agent/task/workflow/squad templates
├── lib/*.js                    ← output-resolver, adapter-loader, etc.
└── scripts/*.sh                ← activate-squad.ts, validate-squad.ts
 
~/.nirvana/skills/_shared/
├── schemas/{capability,business,core-schemas}.json   ← validation
├── catalogs/CAPABILITY_CATALOG_V1.yaml               ← App-C catalog
├── validators/{validators.ts,validators.py}          ← TS + Python
└── adapters/{claude-code,codex,antigravity-cli,hermes}.md ← runtime adapters

First Invocation

1. Verify SQUAD_PROTOCOL_V6.md and SQUAD_PROTOCOL_V5.md exist alongside this SKILL.md.
2. Check node>=18, python3>=3.8 (validators).
3. Create ${SQUADS_DIR}/ if missing: mkdir -p ${SQUADS_DIR}. Default ${SQUADS_DIR} resolves to ~/squads.
4. Report: Squad Protocol Engine v6.0.0 ready. Default protocol for new squads: 6.0. Roots: ${SQUADS_DIR} (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. Default in v6: protocol: "6.0", capabilities[] declared, one Markdown workflow at workflows/<ref>.md (§28), refs without their extension (§28.6), runtime_requirements, maxTurns mandatory. Use --legacy-v4 to create a v4 squad when needed.

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 (with automatic dependency install)

Activation is end-to-end: validate, install everything declared in <squad>/dependencies.yaml, register for slash commands. The squads skill delegates to a shared agent persona that handles the conversation (scope summary, consent for heavy items, error reporting).

• *squad activate {name} — full activation (delegates to agents/squad-activator.md persona)
• *squad activate {name} --dry-run — preview only, no installs run
• *squad activate {name} --confirm-heavy — auto-accept downloads >1 GB, sudo installs, and installers that fetch a remote script and execute it
• *squad status {name} — show activation state from ~/.nirvana/squads-state/<name>/activated.json
• *squad deactivate {name} — clear state file (does NOT uninstall packages)

How it works. When the user says "ative o squad X":

1. Skill detects intent and reads agents/squad-activator.md.
2. Spawns Agent({subagent_type: "general-purpose", prompt: <persona> + <slug>}). Step 3 onwards reads what the persona reported — which arrives in the completion notification, not in the spawn result.

Activating an installed library (the buyer's path, not the author's). The steps below are the AUTHORING flow, run from inside a squad being built. A user who just installed a pack activates through the CLI instead: nrv activate <slug>, or nrv activate --all --only-declared to walk the whole library one squad at a time (add --dry-run to see the plan, --confirm-heavy to accept large downloads, sudo installs, and installers that pipe a remote script into a shell). Activation is advisory — nothing blocks a dispatch — but a squad whose task shells out to ffmpeg or epubcheck fails MID-RUN when the tool is absent, after the dispatch is already paid for. nrv doctor warns when a declared tool is missing. When activation fails, an agent reads the issues block it prints (or --json): each entry has the fix, the nrv activate <slug> to check again, and whether the user must approve the fix first.