team-builder

name	team-builder
description	Interactive agent picker for composing and dispatching parallel teams from agent persona files.

Team Builder

Interactive menu for browsing and composing agent teams on demand. Works with flat or domain-subdirectory agent collections.

When to Use

• Multiple agent personas (markdown files) available and you want to pick which ones to use
• Composing an ad-hoc team from different domains (e.g., Security + SEO + Architecture)
• Browsing available agents before deciding

Prerequisites

Agent files are markdown files containing a persona prompt (identity, rules, workflow, deliverables). The first # Heading is used as the agent name and the first paragraph as the description.

Both flat and subdirectory layouts are supported:

Subdirectory layout — domain inferred from folder name:

agents/
├── engineering/
│   ├── security-engineer.md
│   └── software-architect.md
├── marketing/
│   └── seo-specialist.md
└── sales/
    └── discovery-coach.md

Flat layout — domain inferred from shared filename prefixes (2+ files sharing a prefix = domain; unique prefixes → "General"). The algorithm splits at the first -, so multi-word domains should use the subdirectory layout.

Configuration

Agent directories are probed in order and results merged:

1. ./agents/**/*.md + ./agents/*.md — project-local agents
2. Global agents directory — shared agents

Project-local agents take precedence over global agents with the same name.

How It Works

Step 1: Discover Available Agents

Glob agent directories. For each file:

• Subdirectory layout: extract domain from parent folder
• Flat layout: group by filename prefix (2+ shared = domain, unique = "General")
• Extract agent name from # Heading (fallback: filename → title-case)
• Extract one-line summary from first paragraph

If no agent files found, report which paths were checked and stop.

Step 2: Present Domain Menu

Available agent domains:
1. Engineering — Software Architect, Security Engineer
2. Marketing — SEO Specialist
3. Sales — Discovery Coach, Outbound Strategist

Pick domains or name specific agents (e.g., "1,3" or "security + seo"):

Step 3: Handle Selection

Accept flexible input:

• Numbers: "1,3" selects all agents from those domains
• Names: "security + seo" fuzzy-matches against discovered agents
• "all from engineering" selects every agent in that domain

If more than 5 agents selected, ask the user to narrow down (max 5 per team).

Step 4: Spawn Agents in Parallel

1. Read each selected agent's markdown file
2. Prompt for task description if not already provided
3. Spawn all agents in parallel (general-purpose, independent — no inter-agent communication)
4. Note any failures inline and continue with successful results

Step 5: Synthesize Results

Collect outputs and present a unified report:

• Results grouped by agent
• Synthesis: agreements, conflicts/tensions, recommended next steps

If only 1 agent selected, skip synthesis and present output directly.

Rules

• Dynamic discovery only. New files in the directory auto-appear. No hardcoded agent lists.
• Max 5 agents per team. More produces diminishing returns. Enforce at selection time.
• Parallel dispatch. All agents run simultaneously via parallel tool calls for independent work.

Example

User: team builder

Claude:
Available agent domains:
1. Engineering (2) — Software Architect, Security Engineer
2. Marketing (1) — SEO Specialist

Pick domains or name specific agents:

User: security + seo

Claude:
Selected: Security Engineer + SEO Specialist
What should they work on?

User: Review my Next.js e-commerce site before launch

[Both agents spawn in parallel]

Claude:
## Security Engineer Findings
- [findings...]

## SEO Specialist Findings
- [findings...]

## Synthesis
Both agree on: [...]
Tension: Security recommends CSP that blocks inline styles, SEO needs inline schema markup.
Next steps: [...]