---
sidebar_position: 7
title: Agent Teams
---

# Agent Teams

How hatch3r agent definitions integrate with Claude Code Agent Teams (multi-agent orchestration).

## Agent-to-Teammate Mapping

Hatch3r's canonical agent definitions (bundled `agents/` content, surfaced in your repo as each adapter's generated agent files — e.g. `.cursor/agents/`, `.claude/agents/`, `.github/agents/`) map directly to teammate spawn prompts.

| Hatch3r Concept | Agent Teams Equivalent |
|-----------------|----------------------|
| Agent definition (canonical `agents/*.md`) | Teammate spawn prompt |
| Agent `description` frontmatter | Teammate role summary |
| Agent content body | Teammate system instructions |
| Skill (`SKILL.md`) | Context file referenced in spawn prompt |
| Rule (canonical `rules/*.md`) | Included in teammate instructions or referenced |

## Spawn Prompt Best Practices

When spawning a teammate from a hatch3r agent definition:

1. **Include the agent content verbatim** as the teammate's role definition. Don't summarize -- the full instructions ensure consistent behavior.
2. **Reference skills explicitly** -- tell the teammate to read specific `SKILL.md` files.
3. **State the task goal clearly** at the top of the spawn prompt, before the agent instructions.
4. **Set output expectations** -- specify what the teammate should return (file paths modified, summary, test results).

Example spawn prompt:

```
You are the hatch3r-implementer agent. Your task is to implement the
feature described in issue #42.

Read .claude/skills/hatch3r-feature/SKILL.md for the implementation workflow.
Read .claude/rules/hatch3r-code-standards.md for coding conventions.

Focus on: src/api/ and src/services/
Do not modify: tests/, docs/, config/
```

## File Boundary Assignment

Teammates work best with explicit file boundaries to avoid conflicts:

- **Assign non-overlapping directories** to each teammate
- **Use the agent's natural scope** -- `hatch3r-testability` owns `src/__tests__/`, `hatch3r-docs-writer` owns `docs/`
- **Specify boundaries in the spawn prompt** with both include and exclude paths
- **Shared files** (types, configs) should be assigned to one primary teammate

## Context Passing Between Teammates

Teammates operate independently. Pass context explicitly:

- **Task context** -- include the issue body, requirements, or relevant excerpts
- **Codebase context** -- list the key files the teammate needs to read
- **Cross-teammate results** -- if B depends on A's output, spawn A first, include A's results in B's prompt
- **Project conventions** -- reference the generated bridge instruction file (`CLAUDE.md` for Claude Code) and specific rules files

## Limitations

| Limitation | Workaround |
|------------|------------|
| Teammates don't inherit conversation history | Include all context in the spawn prompt |
| No direct communication between teammates | Orchestrate through the parent agent |
| No real-time shared file changes | Spawn teammates sequentially when they share file scope |
| Independent context windows | Keep spawn prompts focused; reference files instead of inlining |
| No shared memory | Write coordination state to a file that subsequent teammates read |

## Recommended Team Patterns

**Sequential pipeline** -- for dependent work:

1. Spawn `hatch3r-implementer` with file scope
2. Collect results, spawn `hatch3r-testability` with implementation summary
3. Collect results, spawn `hatch3r-reviewer` with full diff

**Parallel fan-out** -- for independent work:

1. Spawn `hatch3r-implementer` for `src/api/` changes
2. Spawn `hatch3r-implementer` for `src/ui/` changes (different files)
3. Spawn `hatch3r-docs-writer` for documentation updates
