Scaling Your Agent Army

From 3 Agents to 30

Small agent teams (3-5) work well for single projects. But as your ambitions grow — multiple repos, cross-functional tasks, 24/7 automation — you need to scale deliberately. Adding agents without structure creates chaos, not productivity.

The key insight: scaling agents is like scaling a team of humans. You need clear roles, communication protocols, shared knowledge, and a way to onboard new members without disrupting existing workflows.

Team Topology Design

Organize agents into purpose-driven teams, not a flat pool:

• Platform team: Infrastructure agents (DevOps, CI/CD, monitoring) — serve all other teams
• Stream-aligned teams: Feature agents (coder, tester, reviewer) — one per product/service
• Enabling team: Specialist agents (security auditor, performance optimizer) — consulted by stream teams
• Complicated subsystem team: Domain experts (ML pipeline, database migration) — own complex areas

This mirrors the Team Topologies framework used by high-performing engineering organizations. Each team has clear boundaries and interaction modes.

Knowledge Sharing Between Agents

Agents in isolation reinvent the wheel. Knowledge sharing prevents this:

• Shared knowledge base: All agents read from the same knowledge-base.md — one source of truth
• Experience sharing: Completed task lessons flow to shared-experiences.jsonl for cross-session learning
• Skill inheritance: New agents inherit the full skill library (1,730+) from day one
• Claude Peers: Active agents can message each other in real-time for coordination

Capability Registries

As your agent count grows, you need a registry — a searchable index of what each agent can do. This enables dynamic routing: incoming tasks get matched to the most capable agent automatically.

A capability registry contains for each agent:

• Name and role — what the agent is called and its primary function
• Skills — which SKILL.md files it has access to
• Confidence areas — task types it handles well (with accuracy scores)
• Availability — is it running, idle, or busy?
• Cost tier — which model it uses (Haiku for simple, Opus for complex)

Adding New Specialists

When you identify a gap in your agent army, follow this protocol:

1. Define the role: Write a clear identity block (name, expertise, constraints)
2. Assign skills: Select relevant SKILL.md files from the library
3. Set boundaries: Define what files/tools the agent can and cannot touch
4. Test in isolation: Run the agent on sample tasks before adding to the team
5. Register capabilities: Add the agent to the capability registry
6. Wire routing: Update the router to dispatch matching tasks to the new agent
7. Monitor performance: Track success rate for the first 20 tasks, adjust if needed

Practical Exercise

Design a 10-agent organization for your project:

1. Draw the team topology — which agents belong to which team type?
2. Write a capability registry entry for each agent (role, skills, confidence areas)
3. Define the routing rules — which task types go to which agent?
4. Identify knowledge-sharing pathways — how do agents learn from each other?
5. Plan for growth — what agents would you add next and why?