lidge-jun/team-builder

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: [...]