Turn a collaboration SOP into importable multica import materials. Reference implementation:aidlc-multica/agents/task-build/。
Task List
Copy and check off during execution:
- [ ] 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 / 本地对话）
Optimize an existing squad: first read references/optimization-playbook.md, then modify the files → import → verify with a new issue.
Form-factor Selection
| Form | Directory | File Count | When to Use |
|---|---|---|---|
| Standalone Agent | agents/<slug>/ |
2-piece set | Single stage, or the Agent internally manages multiple modes |
| Squad | squads/<name>/ |
3-piece set + optional companion copilot | Multi-stage SOP requiring captain routing / human review gates; if the scenario also needs high-frequency human-AI interaction (brainstorming, exploration, revision, etc.), see the “Squad Collaboration Entity” section below and deliver together agents/<scene>-copilot/ |
| Autopilot | autopilots/<name>/ |
1+ piece set | Scheduled/Webhook triggered, bound to an Agent for execution |
Reusable Agents are first defined in agents/ ; the squad squad.yaml 's agents[] is referenced bysame name,runtime / model / skills must be consistent. Autopilot agents[] likewise (assignee_type: agent embeds the Agent definition inline).
Do nottreat *-copilot as a fourth option alongside the table above—it iswithin the squad scenario's high-frequency companion Agent (Skills carrier), designed and delivered together with the squad.
Squad Collaboration Entity and *-copilot
When choosing “Squad” and the scenario requires high-frequency human-AI interaction(such as brainstorming, exploration, repeated revision—not limited to shaping), deliver as a collaboration entity:low-frequency Squad + high-frequency *-copilot. Align with the practice document “collaboration entity,” not a separate orchestration system.
协作体 = 人 + *-copilot（Skills 载体） + Squad（Leader + Workers）
高频：人驱动 copilot → 结论落盘 commit
低频：assign Squad → Leader 派 Worker
*-copilot(squad companion) |
Leader / Worker | |
|---|---|---|
| Essence | Agent(only a carrier for bound Skills) | Agent (routing specialist / stage specialist) |
| Driver | Human(IDE + workdir conversation selects Skill) | Leader(state machine dispatches tasks) |
| Typical Scenarios | Brainstorming, exploration, clarification, revision, etc. requiring back-and-forth dialogue | Determine stage, dispatch tasks, execute, write Comment |
| Placement | agents/<scene>-copilot/; indicate the companion in the squad documentation |
squad.yaml roster |
What it is / is not: it is a special Agent in the squad scenario, a Skills carrier;it is nota standalone form-factor option,it is not Leader / Worker，it is notyet another Squad. Do not use daemon task dispatch to drive the copilot.
Companion Discipline：
- The name must end with
-copilot; typicalruntime: cursor; mounts multiple Skills for the scenario - The squad README /
squad-instructionsmay state “this scenario's copilot =xxx-copilot」；must notwrite intosquad.yaml→agents[]/members - Handoff: after high-frequency conclusions are persisted to disk and committed,
multica issue assign --squad
Getting Started(Injected bound Skill set):
multica workdir issue start <issue-id> --agent "<scene>-copilot" --runtime cursor
multica workdir agent switch --agent "<另一套-copilot>" --runtime cursor
Instruction writing approach: Clearly state “human-driven, which Skills are mounted, artifact persistence and Evidence Gaps, and key decisions require human approval.”Do notapply the Worker template (silent exit / mode state machine / @captain)—the existing assets/agent-instruction-template.md leans Worker; copilot should streamline on its own according to the above.
Red line: Write conclusions to a file and commit before assign; do not write the copilot into the squad state machine; after a Worker delivers, exit silently to avoid mutual @ loops with humans.
Platform prerequisites (summary)
- Squad is a routing object and does not execute tasks; issue assignment, mention, and autopilot all land on
leader_id, and do not fan out to all members. squad-instructions.mdinjects Leader andeach member prompt—write team-wide commonalities here, and role boundaries in eachagent-instructions/*.md。- Agent
descriptionis a directory summary and does not enter runtime;instructions+ bound skills are the behavioral contract. - Assignment, comments, mention, status changes, and import all have side effects; verify with a new issue, and do not trial-and-error on production issues.
For the complete contract see references/multica-platform-context.md; for platform fact-checking, prioritize .cursor/skills/multica-squads、.cursor/skills/multica-creating-agents、.cursor/skills/multica-working-on-issues。
Directory structure
Standalone Agent
agents/<slug>/
├── agent.yaml
├── avatar.png # 可选
└── agent-instructions/<slug>.md
Squad(for collaboration scenarios, a companion agents/<scene>-copilot/may be created separately; the structure is the same as a Standalone Agent and it does not enter the roster below)
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
| Put in Skill | Put in Instruction |
|---|---|
| reusable across squadsgeneral methodologies | platform commands, metadata key, comment templates |
| artifact structure and DoD (unrelated to grouping) | state machine, routing rules, gate implementation |
| qualification conditions, steps, and decision logic | specific Agent names, squad-specific SOP |
Decision: “If switched to another squad / platform, does it still hold?” If yes → Skill; if no → Instruction.Do notcreate a separate Skill for a single work item or a squad-specific process.
Worker baseline references aidlc-multica/shared/worker-loop-base.md, do not repeat. Squad companion copilot does not reference this Worker baseline.
Template files
Read on demand assets/ and copy to the target directory:
| File | Purpose |
|---|---|
| agent-yaml-template.yaml | Standalone Agent / Squad companion *-copilot declaration |
| agent-instruction-template.md | Standalone Agent / multi-mode Worker (copilot should not copy the Worker structure) |
| squad-yaml-template.yaml | Squad grouping declaration |
| squad-instructions-template.md | Team-wide shared guidance |
| leader-router-template.md | Captain routing instruction |
| worker-instruction-template.md | Single-stage Worker |
| autopilot-yaml-template.yaml | Autopilot（triggers + agent） |
| avatars-manifest.example.yaml | avatar generation checklist |
Skill directory specification:aidlc-multica/skills/README.md
Writing order
独立 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 → 验证（手动触发一次）
Sync command
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>
Model selection
When writing squad.yaml / agent.yaml :first define runtime, then filter according to models.json 's runtime_constraints Filter model。
| runtime | available model protocol |
|---|---|
claude |
anthropic |
codex / daemon and other execution-type |
openai |
cursor |
does not support specifying a gateway model (squad companion *-copilot commonly used) |
SSOT：references/models.json; decision tree:references/model-cost-matrix.md。
In-depth reference
| Topic | File |
|---|---|
| Platform collaboration contract | references/multica-platform-context.md |
| Squad Optimization Methodology | references/optimization-playbook.md |
| Avatar Generation | references/avatar-generation.md |
| Model Pricing and Constraints | references/models.json |
| Human Usage Instructions and Prompt Examples | README.md |