agent-collab-framework

name	agent-collab-framework
description	Build a high-quality, reusable multi-agent collaboration framework for any new project, including agent roles, tool scoping, delegation triggers, verification gates, and self-iteration rules.

Agent Collaboration Framework

Use this skill when setting up or refactoring a multi-agent collaboration system for a new project.

Quick Start

1. Collect inputs (scope, modules, docs, build/test commands, tool constraints).
2. Choose coordination mode (rapid vs planned).
3. Define a 3-layer architecture (orchestration, specialists, categories).
4. Create agent configs with minimal tools per role.
5. Define auto-triggers, escalation rules, and delegation matrix.
6. Add verification gates and evidence requirements.
7. Add self-iteration rules and an iteration agent.

Inputs You Must Collect

• Project brief and scope
• Module list and critical flows
• Build/test command(s)
• Documentation sources (requirements, config, permissions)
• Tooling constraints (what agents are allowed to do)

Core Workflow (Reusable)

1) Coordination Mode

• Rapid: single module, low risk, <=3 files.
• Planned: cross-module, payment/auth/permissions/AI, or >3 files.

2) Role Boundaries (Non-negotiable)

• Orchestrator: plan, delegate, verify, integrate only.
• Specialists: analyze, report, propose; no edits unless explicitly allowed.
• Executors: implement tasks only when delegated.

3) Delegation Triggers

• External docs/APIs: Librarian.
• Unknown paths or 2+ modules: Explore.
• Requirements conflict/ambiguity: Requirements-Guardian + Metis + Prometheus + Momus.
• Cloud functions/APIs: CloudFunction-Guardian.
• Data permissions: Data-Permission-Guardian.
• Pre-delivery: Build-Guardian.
• Repeated failure: Oracle.

4) Verification Gates

• Build/compile check must pass.
• Cloud functions: try-catch + timeout + retry.
• Permissions validated.
• Requirements aligned.

5) Evidence Requirements

Each subagent output must include:

• Files changed
• Key changes
• Tests and expected results
• Evidence location

6) Self-Iteration

• Add Iteration-Guardian to propose skill/workflow improvements.
• Enforce user confirmation before modifying skills or workflow.

Concrete Build Steps (Template)

A. Create AGENTS.md Index

Include:

• Architecture layers
• Agent list with roles
• Auto-triggers and delegation matrix
• Verification gates and evidence requirements
• Default workflow
• Iteration and improvement loop

B. Create Agent Configs

Use principle-based prompts and reference docs, avoid hardcoding project-specific details inside agents.

Agent set (baseline):

• Orchestrators: Sisyphus, Atlas, Prometheus
• Specialists: Librarian, Explore, Oracle, Metis, Momus, Hephaestus
• Guardians: Requirements, Data-Permission, CloudFunction, Build, Iteration
• Executor: Sisyphus-Junior

C. Add Iteration Rules

• Trigger: same issue repeats 3 times, or user requests improvement
• Output: proposal with scope, expected benefit, and rollback plan
• Constraint: must ask user confirmation before editing skills

Tool Scoping (Minimal by Role)

Use the smallest tool set that enables the role:

• Orchestrator: ask questions, read, search, delegate
• Explorer: read + search only
• Librarian: web fetch + read + search
• Guardians: read + search; Build-Guardian adds run-in-terminal
• Executors: read + search + edit + run-in-terminal
• Oracle: read + search only

Agent File Format (VS Code)

Each agent file must start with front matter:

---

description: 'One-line role description'

tools: [toolA, toolB, toolC]

---

Then the role content. Do not wrap in code fences.

Deliverables

1. AGENTS.md index with layers, triggers, verification gates, and workflow.
2. Agent configs for each role, principle-based, not overly detailed.
3. Iteration rules that enable skills to improve over time.

Acceptance Checklist

• Orchestrator does not implement code.
• Specialists are advisory unless authorized.
• Minimal tools per role.
• Triggers and escalation rules are explicit.
• Verification gates are mandatory.
• Iteration workflow exists with user confirmation.