squads

Squad Protocol Engine v5.0.0

Squad Protocol v4.0 に従って、複数のエージェントからなるチームをオーケストレーションします。ランタイムに依存しません。作成したチームは、Claude Code、Codex、Gemini CLI、Cursor、Antigravity、およびアダプターに対応するすべてのランタイムで動作します。

基本原則（v4.0）

P1 対象の分離 — frontmatter=ランタイム、body=LLM、ui=マーケットプレイス。 P2 構造より文章 — LLM が読むのは文章であり、ネストされた YAML ではありません。 P3 トークン予算の徹底 — エージェントの本文はコンテキストウィンドウの 1.5% 以下です。 P4 反復の制限 — すべてのエージェントに maxTurns を必ず指定します。例外はありません。 P5 フェイルクローズの既定値 — 既定ではツールを許可せず、権限は保守的に設定します。 P6 タスク優先 — タスクは WHAT を記述し、ワークフローは WHO を決定します。 P7 ランタイム中立性 — コア仕様にランタイム固有の値は含めません。 P8 技術的誠実さ — 存在しない強制機能をうたってはいけません。 P9 グレースフルデグラデーション — オプション機能がない場合は、クラッシュさせずにログに記録します。 P10 名前空間付き拡張 — ランタイム設定は runtimes.{id}.* の下に置きます。

プロトコルのソース

唯一の信頼できる情報源：SQUAD_PROTOCOL_V4.md（21 セクション、ランタイムに依存しません）。 レガシー版：SQUAD_PROTOCOL.md（v2.0、非推奨。レガシーなチームのために保持されています）。 アダプター：adapters/{runtime_id}.md + .yaml — ランタイム固有の仕組みです。 目次から必要なセクションを参照してください。1600 行のプロトコル全体をコンテキストに読み込んではいけません。

Squad のルート

正規の場所は 2 つあります。競合時はローカルが優先されます。

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

検出方法：find ~/squads ./squads -maxdepth 2 -name "squad.yaml" -type f 2>/dev/null

出力規約

すべてのチームの出力は、プロジェクト内の標準ワークスペースに書き込みます。

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

解決アルゴリズム：

1. プロジェクトルート：$SQUADS_PROJECT_ROOT 環境変数、または cwd() から .git/ まで上位ディレクトリをたどる方法、または cwd()
2. 出力ルート：{project-root}/.squads-outputs/
3. 実行ディレクトリ：{output-root}/{squad-name}/{ISO-timestamp}-{slug}/

ルール：

• スキルが実行時に既定のパスを解決します。チームは自動的にそのパスを継承します
• squad.yaml の output: は任意です。動作は 3 通りあります。
  • 未指定 → 既定値（.squads-outputs/{squad-name}/{timestamp}-{slug}/）
  • base_dir: default → 未指定の場合と同じ（明示的な既定値）
  • base_dir: ./custom-path → 指定された値を使用します。チームの開発者がカスタムの出力場所を選択しています
• 初回実行時に、AI エージェント向けにディレクトリを説明する .squads-outputs/README.md を自動作成します
• .gitignore は自動変更しません。プロジェクトごとにユーザーが決定します

パスの例：

• *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/

**ライフサイクル：**出力は中間生成物です。最終成果物はユーザーがプロジェクトの構成に移動します。古い実行結果は削除できます：rm -rf .squads-outputs/{squad}/{old-run}/

**環境変数：**実行時に、チームには解決済みの実行ディレクトリを指す $SQUAD_RUN_DIR が渡されます。すべての成果物はそこに書き込まれます。

リゾルバー：lib/output-resolver.js がパス解決を実装します。ランタイムは必ずこのリゾルバーを使用してください。

スキルのレイアウト（自己完結型）

このスキルは自己完結型です。すべてのリソースはスキルのディレクトリ内にあります。

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

初回の呼び出し

1. この SKILL.md と同じ場所に SQUAD_PROTOCOL_V4.md があることを確認します。
2. node>=18、python3>=3.8 を確認します。
3. ~/squads/ がない場合は作成します：mkdir -p ~/squads。
4. 次の内容を報告します：Squad Protocol Engine v5.0.0 ready. Protocol: v4.0. Roots: ~/squads (N), ./squads (M).

インテントの分類

ユーザー入力を分類 → 関連する参照ファイルのみを読み込む → 実行します。

インテント	キーワード	読み込む参照ファイル
DISCOVER	list, show, find, search, inspect, info, describe	references/01-discovery.md
CREATE	create, new, scaffold, generate, build squad	references/02-creation.md, references/05-schemas.md
VALIDATE	validate, check, verify, fix, repair, lint, audit	references/03-validation.md
ACTIVATE	activate, register, install, deps, enable	references/04-activation.md
MODIFY	add agent, remove, update, add task, add workflow	references/05-schemas.md
EXECUTE	run, execute, start, launch, resume, retry	references/06-workflows.md, references/07-execution.md
ADAPT	adapter, runtime, compatibility, feature matrix	references/08-runtime-contract.md, references/11-adapters-guide.md
UPGRADE	upgrade, migrate, convert, v4	references/09-upgrade.md
OBSERVE	state, status, traces, artifacts, flow, runs	references/07-execution.md

重要なルール： 実行する前に参照ファイルを読み込んでください。スクワッドの構造を推測してはいけません。複数のインテントがある場合は、依存関係の順序に従って順番に処理してください。

コマンド

検索

• *squad list — すべてのスクワッドを一覧表示します（両方のルート）
• *squad list --format {table|card|compact|tree} — 表示形式
• *squad inspect {name} — スクワッドの詳細を表示します

作成

• *squad create {name} — 対話型作成ウィザード（protocol:"4.0"、runtime_requirements、maxTurnsが必須のv4形式）

検証

• *squad validate {name} — 18項目のブロッキングチェック（コア＋アダプター）
• *squad validate {name} --report — AI向けの修正ガイダンス
• *squad validate {name} --fix — 一般的な問題を自動修正します
• *squad validate {name} --runtime {id} — 指定したアダプターに対して検証します

有効化

• *squad activate {name} — 検証＋依存関係の確認＋アダプターの検証＋登録
• *squad deactivate {name} — 登録を解除し、ソースは保持します

変更

• *squad add-agent {squad} {agent-name} — v4テンプレートでエージェントを追加します（maxTurnsは必須）
• *squad add-task {squad} {task-name} — タスクを追加します（担当者なし。ワークフローで割り当てます）
• *squad add-workflow {squad} {workflow-name} — DAGを含むワークフローを追加します
• *squad remove {squad} {component} — コンポーネントを削除します

実行

• *squad run {name} — デフォルトのワークフローを実行します
• *squad run {name} --workflow {wf} — 指定したワークフローを実行します
• *squad run {name} --runtime {id} — 指定したランタイムを強制的に使用します
• *squad resume {name} — チェックポイントから再開します

アダプター

• *squad adapters — 利用可能なランタイムアダプターを一覧表示します
• *squad adapters inspect {runtime} — アダプターの機能マトリクスを表示します
• *squad runtime — 現在のランタイムを検出します
• *squad compat {squad} — 現在のランタイムとのスクワッドの互換性を確認します

移行

• *squad migrate {name} — v2/v3.1のスクワッドをv4形式に移行します
• *squad migrate {name} --from {v2|v3.1} --to v4 — 移行元と移行先を明示して移行します

状態の確認

• *squad status {name} — 現在の実行状態
• *squad traces {name} — 実行トレース
• *squad artifacts {name} — 生成された成果物の一覧

その他

• *squad help — このコマンド一覧を表示します

作成ルール（v4）

新しいスクワッドを作成するときは、必ず次のルールに従ってください。

1. squad.yamlにprotocol: "4.0"を設定します。
2. 対象ランタイムを確認し、runtime_requirements.minimumを設定します。
3. features_requiredとfeatures_optionalを設定します。
4. すべてのエージェントにmaxTurnsを設定します（単純なものはデフォルトで25、複雑なものは50）。
5. エージェントのtools:フィールドには、移植性のあるセマンティックなツール名（read、write、grep、bash、web_search）を使用します。
6. タスクに担当者を設定してはいけません。ワークフローでエージェントをタスクに割り当てます。
7. タスクの受け入れ基準は、二値で検証可能なものにする必要があります。
8. 長時間実行されるサブエージェントのプロンプトには、<protocol-context>ブロックを含めます。
9. チェーン化されたタスクの出力スキーマをcontracts:で宣言します。
10. 永続メモリを使用する場合は、メモリのGCポリシーを設定します。

エージェントテンプレート（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}

アンチパターン

絶対にしてはいけないこと：

• squad の構造を推測しないでください。必ず最初に squad.yaml を読みます。
• SQUAD_PROTOCOL_V4.md 全体をコンテキストに読み込まないでください。目次を確認し、必要に応じてセクションを読みます。
• maxTurns を指定せずにエージェントを作成しないでください。ランタイムが無限ループする可能性があります。
• owner: フィールドを使ってタスクを作成しないでください。代わりにワークフローのバインディングを使います。
• ポータブルな tools: フィールドで、ランタイム固有のツール名を使わないでください。代わりにセマンティック名を使います。
• 作成後や変更後の検証を省略しないでください。必ず *squad validate を実行します。
• ユーザーから依頼されていないエージェントの役割を作らないでください。
• フレームワークのファイルを変更しないでください（L1/L2 の境界）。
• 参照されるすべてのエージェントとタスクが存在することを確認せずに、ワークフローを実行しないでください。
• 確認を取らずに破壊的な操作を実行しないでください。
• squad.yaml のルートにランタイム固有の値をハードコードしないでください。runtimes.{id}.* 名前空間を使います。
• 本文がコンテキストウィンドウの 1.5% を超えるエージェントを作成しないでください。代わりに分割します。
• ステップ間で会話履歴全体を渡さないでください。代わりにハンドオフ成果物を使います。
• 実際には存在しない強制機能を主張しないでください（P8 技術的誠実性）。

下位互換性

• 以前のコマンドも引き続き動作します：*create-squad → *squad create
• v1、v2、v3 の squad は、自動アップグレード shim を介して読み込まれます（references/09-upgrade.md を参照）
• v3 ハーネス機能（doom loop、ralph loop、トレース）は引き続きオプトインです
• v4 で追加：必須の maxTurns、runtime_requirements、アダプター、ポータブルなツール名
• アップグレードをディスクに反映するには、*squad migrate を実行します