arminnaimi_agent-team-orchestration/references/team-setup.md

Team Setup

How to define agents, assign roles, select models, and isolate workspaces.

Define Roles First, Then Agents

Start with the work, not the agents. List the types of work, then create roles to cover them.

Minimal team (2 agents):

Orchestrator — routes tasks, tracks state
Builder      — executes work

Standard team (3-4 agents):

Orchestrator — routes, prioritizes, reports to stakeholders
Builder      — produces artifacts (code, docs, configs)
Reviewer     — verifies quality, catches gaps
Ops          — scheduled tasks, health checks, mechanical work

Rule: One agent, one primary role. An agent can do secondary work, but its role determines what it's optimized for.

Model Selection Per Role

Match model cost to the cognitive demands of the role.

Role	Needs	Model tier
Orchestrator	Judgment, prioritization, multi-context reasoning	Top tier (e.g., Claude Opus, GPT-4.5)
Builder	Code generation, following specs, producing artifacts	Mid-to-top tier depending on complexity
Reviewer	Critical analysis, catching edge cases, feasibility	Top tier — reviewers catch what builders miss
Ops	Following templates, running scripts, dispatching	Cheapest reliable model (e.g., GPT-4o-mini, Haiku)

Don't waste expensive models on mechanical work. Cron-based standups, file organization, and template-following tasks don't need frontier reasoning.

Workspace Isolation

Each agent operates in its own workspace to prevent interference.

/workspace/
├── agents/
│   ├── builder/          — Builder's personal workspace
│   │   └── SOUL.md       — Builder's identity and instructions
│   ├── reviewer/         — Reviewer's personal workspace
│   │   └── SOUL.md
│   └── ops/
│       └── SOUL.md
├── shared/               — Shared across all agents
│   ├── specs/            — Requirements and specifications
│   ├── artifacts/        — Build outputs
│   ├── reviews/          — Review notes and feedback
│   └── decisions/        — Architecture and product decisions

Rules:

• Agents read/write their own workspace freely
• Agents write deliverables to /shared/ — never to personal workspaces
• Agents can read any shared directory
• Orchestrator can read all workspaces for oversight

Identity Files (SOUL.md)

Each agent gets a SOUL.md that defines:

1. Role and scope — What this agent does and doesn't do
2. Communication style — How it writes comments, reports, asks questions
3. Boundaries — What requires escalation vs. autonomous action
4. Team context — Who else is on the team and how to interact with them

Example SOUL.md for a builder agent:

# SOUL.md — Builder

I build what the specs say. My job is execution, not product decisions.

## Scope
- Implement features per approved specs
- Write tests for what I build
- Document non-obvious decisions in code comments
- Hand off with clear verification steps

## Boundaries
- Spec unclear? Ask the orchestrator, don't guess
- Architecture change needed? Propose it, don't just do it
- Blocked for >10 minutes? Comment on the task and move on

## Handoff Format
Every completed task includes:
1. What I changed and why
2. File paths for all artifacts
3. How to test/verify
4. Known limitations

Adding a New Agent

1. Create the workspace directory
2. Write its SOUL.md
3. Update the team protocol with its role
4. Verify it has the capabilities it needs (browser, tools, API access)
5. Start with a small task to validate the setup before loading it into the rotation