Multica Agent & Squad 脚手架

将协作 SOP 落成可 multica import 的物料。参考实现：aidlc-multica/agents/task-build/。

任务清单

执行时复制并勾选：

- [ ] 1. 选型（独立 Agent / 小队 / Autopilot）
- [ ] 2. 复制 assets 模版到 aidlc-multica/agents/ 或 squads/ 或 autopilots/
- [ ] 3. 填写 YAML + instructions（共性 → squad-instructions；角色边界 → agent-instructions）
- [ ] 3b. （选小队且需与 AI 高频互动）配套 agents/<scene>-copilot/：绑 Skills，不进 squad.yaml 路由
- [ ] 4. 判定 Skill vs Instruction，仅可复用方法论抽 Skill
- [ ] 5. （可选）生成头像 → references/avatar-generation.md
- [ ] 6. multica import 同步（--dry-run 预览；小队与配套 copilot 分别 import）
- [ ] 7. 新 issue 跑 happy path 验证（低频 assign Squad；高频 copilot 用 issue start / 本地对话）

优化现有小队：先读 [references/optimization-playbook.md](references/optimization-playbook.md)，再改文件 → import → 新 issue 验证。

形态选择

可复用 Agent 先在 agents/ 定义；小队 squad.yaml 的 agents[] 按同名引用，runtime / model / skills 须一致。Autopilot agents[] 同理（assignee_type: agent 时内嵌 Agent 定义）。

不要把 *-copilot 当成与上表并列的第四种选型——它是小队场景内的高频配套 Agent（Skills 载体），跟小队一起设计、一起交付。

小队协作体与 *-copilot

选「小队」且该场景需要人与 AI 高频互动（如脑暴、探索、反复改稿——不限于塑形）时，按协作体交付：**低频 Squad + 高频 *-copilot**。对齐实践文「协作体」，不是另起一套编排。

协作体 = 人 + *-copilot（Skills 载体） + Squad（Leader + Workers）
高频：人驱动 copilot → 结论落盘 commit
低频：assign Squad → Leader 派 Worker

| | *-copilot（小队配套） | Leader / Worker | |--|------------------------|-----------------| | 本质 | Agent（仅为绑定 Skills 的载体） | Agent（路由专精 / 阶段专精） | | 驱动方 | 人（IDE + workdir 对话选用 Skill） | Leader（状态机派活） | | 典型场景 | 脑暴、探索、澄清、改稿等需来回对话 | 判阶段、派活、执行、写 Comment | | 落点 | agents/<scene>-copilot/；在小队文档标明配套 | squad.yaml roster |

是什么 / 不是什么：是小队场景里的特殊 Agent、Skills 载体；不是独立选型形态，不是 Leader / Worker，不是又一个 Squad。勿用 daemon 派活驱动副驾。

配套纪律：

• 命名必须以 -copilot 结尾；典型 runtime: cursor；挂载该场景多 Skill
• 小队 README / squad-instructions 可写「本场景副驾 = xxx-copilot」；不得写入 squad.yaml → agents[] / members
• 交接：高频结论落盘并 commit 后 multica issue assign --squad

起手（注入绑定的 Skill 集合）：

multica workdir issue start <issue-id> --agent "<scene>-copilot" --runtime cursor
multica workdir agent switch --agent "<另一套-copilot>" --runtime cursor

Instruction 写法：写清「人驱动、挂载哪些 Skill、产物落盘与 Evidence Gaps、关键判断过人」。不要套 Worker 模板（沉默退出 / 模式状态机 / @队长）——现有 assets/agent-instruction-template.md 偏 Worker，copilot 按上文自行精简。

红线：结论写入文件并 commit 再 assign；勿把副驾写进小队状态机；Worker 交付后沉默退出，避免与人互相 @ 成环。

平台前提（摘要）

• Squad 是路由对象，不执行任务；issue 分配、mention、autopilot 均落到 leader_id，不会 fan-out 全部成员。
• squad-instructions.md 注入 Leader 与每个成员 prompt——全队共性写此处，角色边界写各 agent-instructions/*.md。
• Agent description 是目录摘要，不进运行时；instructions + 绑定 skills 才是行为契约。
• 分配、评论、mention、改状态、import 均有副作用；验证用新 issue，生产 issue 勿试错。

完整契约见 [references/multica-platform-context.md](references/multica-platform-context.md)；平台事实核对优先参考 .cursor/skills/multica-squads、.cursor/skills/multica-creating-agents、.cursor/skills/multica-working-on-issues。

目录结构

独立 Agent

agents/<slug>/
├── agent.yaml
├── avatar.png                     # 可选
└── agent-instructions/<slug>.md

小队（协作体场景可另建配套 agents/<scene>-copilot/，结构同独立 Agent，不进下方 roster）

squads/<name>/
├── squad.yaml
├── squad-instructions.md          # 全队共享：状态机、协作规范、共性上下文；可注明配套副驾名
├── avatar.png / avatars.yaml      # 可选
├── avatars/                       # 可选
└── agent-instructions/
    ├── leader-<slug>-router.md
    └── worker-<slug>.md

# 同场景配套（可选，不进 squad.yaml agents[]）
agents/<scene>-copilot/
├── agent.yaml
└── agent-instructions/<scene>-copilot.md

Autopilot

autopilots/<name>/
├── autopilot.yaml
├── agent-instructions/<slug>.md    # assignee_type=agent 时
└── skills/<skill-name>/SKILL.md

Skill vs Instruction

判定：「换一个小队 / 平台还成立吗？」成立 → Skill；不成立 → Instruction。不要为单次工作项或本小队专属流程单独建 Skill。

Worker 基线引用 aidlc-multica/shared/worker-loop-base.md，不重复。小队配套 copilot 不引用该 Worker 基线。

模版文件

按需读取 [assets/](assets/) 并复制到目标目录：

Skill 目录规范：aidlc-multica/skills/README.md

编写顺序

独立 Agent：agent.yaml → agent-instructions → （可选）头像 → 确认 skills/ → import → 验证
小队：       squad.yaml → squad-instructions → agent-instructions
             →（需与 AI 高频互动）agents/<scene>-copilot/ → （可选）头像 → import 小队 + import 副驾 → 验证
Autopilot：  autopilot.yaml → agent-instructions → skills/ → import → 验证（手动触发一次）

同步命令

multica agent import --dir <agent-dir>              # 独立 Agent 或小队配套 *-copilot
multica squad import --dir <squad-dir>              # 小队；删了本地 skill 时加 --prune-skills
multica autopilot import --dir <autopilot-dir>
# 均支持 --dry-run 预览、--force 跳过确认
multica squad export <name-or-id> --dir <dir>       # 备份/迁移
multica autopilot export <name-or-id> --dir <dir>

模型选型

写入 squad.yaml / agent.yaml 时：先定 runtime，再按 models.json 的 runtime_constraints 过滤 model。

SSOT：[references/models.json](references/models.json)；决策树：[references/model-cost-matrix.md](references/model-cost-matrix.md)。

深入参考