squads

Squad Protocol Engine v5.0.0

你负责协调遵循 Squad Protocol v4.0 的多 Agent 小队。你与运行时无关：创建的小队可在 Claude Code、Codex、Gemini CLI、Cursor、Antigravity 以及任何带适配器的运行时上运行。

Core Principles (v4.0)

P1 受众分离 — frontmatter=运行时，正文=大模型，ui=市场。 P2 优先使用散文 — 大模型读取散文，而非嵌套 YAML。 P3 令牌预算纪律 — Agent 正文 ≤ 上下文窗口的 1.5%。 P4 有界迭代 — 每个 Agent 都必须设置 maxTurns。无一例外。 P5 默认关闭 — 默认不授予任何工具；权限设置应保守。 P6 任务优先 — 任务描述做什么；工作流决定由谁执行。 P7 运行时中立 — 核心规范不包含特定运行时的值。 P8 技术诚实 — 绝不宣称不存在的强制执行能力。 P9 优雅降级 — 缺失的可选功能应记录日志，不应导致崩溃。 P10 命名空间扩展 — 运行时配置位于 runtimes.{id}.* 下。

Protocol Source

唯一事实来源：SQUAD_PROTOCOL_V4.md（21 个章节，与运行时无关）。 旧版：SQUAD_PROTOCOL.md（v2.0，已弃用，为旧版小队保留）。 适配器：adapters/{runtime_id}.md + .yaml — 特定运行时的机制。 按需通过 TOC 阅读章节。绝不要将完整的 1600 行协议加载到上下文中。

Squad Roots

两个规范位置。本地路径在冲突时优先。

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

发现命令：find ~/squads ./squads -maxdepth 2 -name "squad.yaml" -type f 2>/dev/null

Output Convention

所有小队输出都写入项目内的标准工作区：

{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: 可选。有三种行为：
  • 未设置 → 默认值（.squads-outputs/{squad-name}/{timestamp}-{slug}/）
  • base_dir: default → 与未设置相同（显式指定默认值）
  • base_dir: ./custom-path → 按指定路径执行；小队开发者选择了自定义输出位置
• 首次运行时，自动创建 .squads-outputs/README.md，向 AI Agent 说明该目录
• 不要自动修改 .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 实现路径解析。运行时必须使用此解析器。

Skill Layout (self-contained)

此技能是自包含的。所有资源都位于技能目录下：

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. 确认 SQUAD_PROTOCOL_V4.md 与此 SKILL.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 结构。多意图：按依赖顺序依次处理。

命令

发现

• *squad list — 列出所有 squad（两个根目录）
• *squad list --format {table|card|compact|tree} — 显示格式
• *squad inspect {name} — 查看 squad 详细信息

创建

• *squad create {name} — 交互式创建向导（v4 格式，必须包含 protocol:"4.0"、runtime_requirements、maxTurns）

验证

• *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 模板添加 Agent（必须包含 maxTurns）
• *squad add-task {squad} {task-name} — 添加任务（不设 owner，由工作流绑定）
• *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 与当前运行时的兼容性

迁移

• *squad migrate {name} — 将 v2/v3.1 squad 迁移为 v4 格式
• *squad migrate {name} --from {v2|v3.1} --to v4 — 显式指定迁移版本

观察

• *squad status {name} — 查看当前执行状态
• *squad traces {name} — 查看执行轨迹
• *squad artifacts {name} — 列出生成的制品

元信息

• *squad help — 显示此命令列表

创建规则（v4）

创建新 squad 时，务必：

1. 在 squad.yaml 中设置 protocol: "4.0"。
2. 询问目标运行时 → 设置 runtime_requirements.minimum。
3. 设置 features_required 和 features_optional。
4. 每个 Agent 都必须设置 maxTurns（简单任务默认为 25，复杂任务默认为 50）。
5. 在 Agent 的 tools: 字段中使用可移植的语义工具名称（read、write、grep、bash、web_search）。
6. 任务不设 owner — 工作流负责绑定 Agent→任务。
7. 任务验收标准必须是二元且可验证的。
8. 在长时间运行的子 Agent 提示词中包含 <protocol-context> 块。
9. 为链式任务在 contracts: 中声明输出架构。
10. 如果使用持久化记忆，设置内存 GC 策略。

Agent 模板（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.yaml。
• 将完整的 SQUAD_PROTOCOL_V4.md 加载到上下文中——使用目录，按需读取各个章节。
• 创建未设置 maxTurns 的 Agent——运行时可能会无限循环。
• 创建带有 owner: 字段的任务——改用工作流绑定。
• 在可移植的 tools: 字段中使用特定于运行时的工具名称——改用语义名称。
• 创建或修改后跳过验证——务必运行 *squad validate。
• 擅自添加用户未要求的 Agent 角色。
• 修改框架文件（L1/L2 边界）。
• 未确认所有引用的 Agent 和任务都存在，就运行工作流。
• 未经确认就执行破坏性操作。
• 在 squad.yaml 根目录中硬编码特定于运行时的值——使用 runtimes.{id}.* 命名空间。
• 创建正文长度超过上下文窗口 1.5% 的 Agent——应拆分。
• 在步骤之间传递完整对话历史——改用交接产物。
• 声称存在实际并不存在的强制机制（P8 技术诚信）。

向后兼容性

• 旧命令仍然有效：*create-squad → *squad create
• v1、v2、v3 小队通过自动升级垫片加载（参见 references/09-upgrade.md）
• v3 框架功能（doom loop、ralph loop、追踪）仍为可选启用
• v4 新增：强制设置 maxTurns、runtime_requirements、适配器、可移植的工具名称
• 运行 *squad migrate 将升级结果写入磁盘