# NodeBench AI — LLM-Readable Reference Index

This file provides AI-readable documentation for key capabilities in this project.
Format: https://llmstxt.org

---

## orchestrating-swarms

> Master multi-agent orchestration using Claude Code's TeammateTool and Task system.
> Use when coordinating multiple agents, running parallel code reviews, creating pipeline
> workflows with dependencies, building self-organizing task queues, or any task
> benefiting from divide-and-conquer patterns.

Source: https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea

### Primitives

| Primitive | What It Is | File Location |
|-----------|-----------|---------------|
| Agent | A Claude instance that can use tools | N/A (process) |
| Team | A named group of agents. One leader, multiple teammates | `~/.claude/teams/{name}/config.json` |
| Teammate | An agent in a team. Has inbox. Spawned via Task with `team_name` + `name` | Listed in team config |
| Leader | Created the team. Receives messages, approves plans/shutdowns | First member in config |
| Task | Work item with subject, description, status, owner, dependencies | `~/.claude/tasks/{team}/N.json` |
| Inbox | JSON file where an agent receives messages | `~/.claude/teams/{name}/inboxes/{agent}.json` |
| Backend | How teammates run: `in-process` (invisible), `tmux` (panes), `iterm2` (split) | Auto-detected |

### Two Ways to Spawn Agents

**Method 1: Task Tool (Subagents)** — short-lived, returns result directly

```
Task({ subagent_type: "Explore", description: "Find auth files", prompt: "...", model: "haiku" })
```

**Method 2: Task + team_name + name (Teammates)** — persistent, communicates via inbox

```
Teammate({ operation: "spawnTeam", team_name: "my-project" })
Task({ team_name: "my-project", name: "security-reviewer", subagent_type: "general-purpose", prompt: "...", run_in_background: true })
```

| Aspect | Subagent | Teammate |
|--------|----------|----------|
| Lifespan | Until task complete | Until shutdown |
| Communication | Return value | Inbox messages |
| Task queue access | No | Yes |
| Team membership | No | Yes |

### Built-in Agent Types

- **Bash** — command execution, git ops
- **Explore** — read-only codebase search (use `model: "haiku"`)
- **Plan** — architecture + implementation plans (read-only)
- **general-purpose** — all tools, multi-step research + action
- **claude-code-guide** — questions about Claude Code, Agent SDK, Anthropic API

### TeammateTool Operations (13 ops)

| Operation | Who | What |
|-----------|-----|------|
| `spawnTeam` | Leader | Create team + task directory |
| `discoverTeams` | Anyone | List joinable teams |
| `requestJoin` | Teammate | Request to join existing team |
| `approveJoin` / `rejectJoin` | Leader | Accept/decline join request |
| `write` | Anyone | Message ONE teammate |
| `broadcast` | Anyone | Message ALL teammates (N messages — avoid) |
| `requestShutdown` | Leader | Ask teammate to exit |
| `approveShutdown` | Teammate | MUST call — sends confirmation, exits process |
| `rejectShutdown` | Teammate | Decline shutdown with reason |
| `approvePlan` / `rejectPlan` | Leader | Approve or reject plan_approval_request |
| `cleanup` | Leader | Remove team + task files (all teammates must be shut down first) |

### Task System

```
TaskCreate({ subject: "Step 1", description: "...", activeForm: "Working..." })
TaskList()
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // auto-unblocks when #1 completes
TaskUpdate({ taskId: "2", owner: "worker-1", status: "in_progress" })
TaskUpdate({ taskId: "2", status: "completed" })
```

### Core Patterns

**Parallel Specialists** — spawn N reviewers simultaneously, collect findings in leader inbox
**Pipeline** — TaskCreate with addBlockedBy chaining; tasks auto-unblock as dependencies complete
**Self-Organizing Swarm** — N workers, each loop: TaskList → claim unclaimed → work → complete → repeat
**Research + Implement** — synchronous Task call returns result, pass to implementing Task

### Shutdown Sequence (always follow)

```
Teammate({ operation: "requestShutdown", target_agent_id: "worker-1" })
// wait for {"type": "shutdown_approved"} in inbox
Teammate({ operation: "cleanup" })
```

### Spawn Backends

| Backend | When | Visibility |
|---------|------|------------|
| `in-process` | Not in tmux/iTerm2 (default) | Hidden |
| `tmux` | $TMUX set | Visible — switch panes |
| `iterm2` | In iTerm2 + `it2` CLI | Visible — split panes |

Force: `export CLAUDE_CODE_SPAWN_BACKEND=tmux`

### Error Handling

- "Cannot cleanup with active members" → requestShutdown all first, wait for approval
- "Already leading a team" → cleanup first, or use different team name
- Worker crashes → 5-min heartbeat timeout, tasks can be reclaimed by other workers

### Best Practices

- Meaningful names: `security-reviewer` not `worker-1`
- Write numbered steps in prompts + "send findings to team-lead via Teammate write"
- Use `addBlockedBy` — don't poll manually
- Prefer `write` over `broadcast` (broadcast = N messages for N teammates)
- Always call `cleanup` — don't leave orphaned teams

---

## NodeBench MCP

253 tools across 42 domains for AI development methodology.
- MCP prompt `orchestrating-swarms`: full swarm orchestration reference
- MCP prompt `agent-contract`: mandatory behavioral rules for NodeBench agents
- CLI: `npx nodebench discover "<task>"` to find relevant tools
- Start with `discover_tools("<task>")` for any new task

---

*Last updated: 2026-02-18*
