# Multi Agent Focus

> Generic skill for self-organizing multi-agent teams that collaborate on an optimization problem. Agents discuss dimensions, form teams, run experiments, and adapt when stagnating. Uses AnonAPI posts for discussion and workspaces for shared state.

- Skill: `mims-harvard/multi-agent-focus` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add mims-harvard/multi-agent-focus`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mims-harvard/multi-agent-focus/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: mims-harvard (https://skillmd.com/u/mims-harvard)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mims-harvard/multi-agent-focus

---


# Multi-Agent Focus Area

A **focus area** is a group of AI agents collaborating on an optimization problem. Agents self-organize into teams, each attacking a different dimension of the problem.

## Core Concepts

| Concept | What it is | AnonAPI feature |
|---|---|---|
| **Workshop** | The focus area container — all agents subscribe | `POST /workshops` |
| **Main workspace** | Shared state: champion config, all results, cross-team knowledge | `POST /workspaces` |
| **Team workspace** | Team-internal state: queue, hypotheses, dead ends, strategy | One per team |
| **Posts** | Discussion: proposals, results, strategy debates, votes | `POST /posts` |
| **Workspace files** | Structured data with YAML frontmatter, versioned, searchable | `PUT /workspaces/{id}/files/{path}` |

## How It Works

```
1. BOOTSTRAP    — Monitor creates workshop + main workspace + kickoff post
2. DISCUSS      — All agents propose dimensions, debate, vote on teams
3. EXECUTE      — Teams run experiments in parallel, share results
4. ADAPT        — Stagnating teams restructure via discussion + vote
```

See `reference/PHASES.md` for detailed lifecycle.

## Agent Roles

| Role | Count per team | What they do |
|---|---|---|
| **Monitor** | 1 (global) | Bootstrap, facilitate team formation, monitor health |
| **GPU Agent** | 2 per team | Claim experiments, train models, record results |
| **Analyst** | 1 per team | Research mechanisms, propose experiments, prune dead ends |

See `templates/ROLE-MONITOR.md`, `templates/ROLE-GPU.md`, `templates/ROLE-ANALYST.md`, `templates/ROLE-TEAM.md`.

## Main Workspace — Initial Files

These files are created during bootstrap. Agents may create additional files as needed — other agents discover them via LIST.

```
champion.md                — Current best config (ESSENTIAL ANCHOR — always read)
results/{exp_id}.md        — One file per experiment result (write-once)
teams/roster.md            — Team assignments and workspace IDs (ESSENTIAL ANCHOR)
```

Additional files are created organically by agents (e.g., `knowledge/lr-schedules.md`). Use `GET /files` to discover what exists.

## Team Workspace — Initial Files

```
queue.md                   — Pending experiments + active claims (ESSENTIAL ANCHOR)
dead_ends.md               — Mechanisms ruled out by this team
strategy.md                — Current team approach
```

Agents may create additional files (analysis docs, hypothesis lists, etc.). Use descriptive paths — see `templates/ROLE-TEAM.md` § File Naming Convention.

## Coordination Model

- **Discovery over prescription** — agents LIST workspace files each cycle and decide what to read, rather than following hardcoded file checklists. See `templates/ROLE-TEAM.md` § File Discovery Protocol
- **Posts for discussion** — proposals get debated before entering a queue
- **Workspaces for state** — structured data with version history
- **Notifications for alerts** — `notify_agents` on post creation
- **PATCH for concurrency** — dot-notation frontmatter updates don't conflict
- **Client-side YAML parsing** — the API stores files as raw text. Agents must parse YAML frontmatter themselves (see `API-REFERENCE.md`)
- **Champion propagation** — orchestrator copies winning train.py to `{FOCUS_ROOT}/champion/train.py` after each KEEP. All GPU agents read from this canonical path

## Discussion-Before-Queuing Rule

Every experiment MUST start as a `[PROPOSAL]` post. At least 1 team member must comment before it enters the team queue. This ensures peer review of ideas before spending GPU time.

## Cross-Team Coordination

1. All results go to **main workspace** `results/` — visible to every team
2. **Near-misses** (delta < threshold) trigger cross-team joint experiments
3. **KEEP results** (new champion) update main `champion.md` — all teams rebase
4. Monitor posts periodic `[AUDIT]` summarizing all team progress

## Using This System

This system is **problem-agnostic**. The specific optimization problem is defined in a **task file** (a `TASK.md` inside the directory passed via `--task` to `launch.py`). The task defines:

- What metric to optimize
- How to run an experiment
- What the search space looks like
- Hardware constraints

To start a new focus area: read your task file, then follow `PHASES.md`.