agent-team-factory
CLAUDE.md0 starsChanged 4 months agoMITView on GitHub
AI team builder for Claude Code. You describe a domain, it produces a complete agent team: CLAUDE.md, agents, skills, protocols, memory, comms infrastructure. Everything needed to stand up a working multi-agent "floor" in Claude Code (or any Claude-Code- compatible agent harness). - Generated floors conform to standards/floor-spec.md — the canonical floor anatomy (floor-size declaration, freshness stamp, authority ladder, comms, memory caps, activation, lifecycle). Its Conformance Checklist is the acceptance test for any build-team output. - Generated skills conform to standards/skill-authoring.md…
In this repository5 other files it gives its agents.
- audit-teamSkill
- build-agentSkill
- build-pipelineSkill
- build-skillSkill
- build-teamSkill
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 59
Use when the team has multiple peer divisions (DESK), sequential stages (PIPELINE), or distinct functional groups that each need their own …
- Distinctive: line 91
Use when the team is a single functional unit where splitting into divisions would be artificial.
- Distinctive: line 120
How to choose: If the team has genuinely distinct playbooks per sub-group (e.g., Equities desk vs.
- Distinctive: line 136
Orchestrator-worker, not bag-of-agents: Every team has a coordinator.
- Distinctive: line 137
File ownership prevents conflicts: No two agents write the same files.
- Distinctive: line 141
Red team on every division: Read-only adversarial review.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Team Factory
AI team builder for Claude Code. You describe a domain, it produces a complete agent team: CLAUDE.md, agents, skills, protocols, memory, comms infrastructure. Everything needed to stand up a working multi-agent "floor" in Claude Code (or any Claude-Code- compatible agent harness).
Standards (apply to everything the factory generates)
- Generated floors conform to
standards/floor-spec.md— the canonical floor anatomy (floor-size declaration, freshness stamp, authority ladder, comms, memory caps, activation, lifecycle). Its Conformance Checklist is the acceptance test for anybuild-teamoutput. - Generated skills conform to
standards/skill-authoring.md— trigger-bearing frontmatter, 200-line cap, no hardcoded absolute paths, self-edit changelog.
How to Use
Tell Claude what you need:
- "Build me a legal team"
- "Build me a customer support floor with 4 tiers"
- "Build me an ETL pipeline team"
- "I need a 3-person content review team"
Claude asks questions about your domain, then generates every file.
Skills
| Skill | Purpose | Trigger |
build-team | Full team from scratch. Intake, architecture, generate, review, deliver. | "build me a team", "create a floor", "set up a [domain] team" |
build-agent | Single agent definition with YAML frontmatter, mandate, files, dependencies. | "add an agent", "create a [role] agent", "I need a new specialist" |
build-skill | Single skill file from 5 archetypes (Task, Pipeline, Parallel, Command, Activation). | "create a skill", "build a skill for [task]", "new skill" |
build-pipeline | Pipeline orchestrator with stages, gates, kill conditions, state persistence. | "build a pipeline", "create a [N]-stage workflow", "pipeline for [domain]" |
audit-team | Audit an existing team for role clarity, staleness, contradictions, orphans. | "audit this team", "check my agents", "review the floor" |
Research Library
Eight research documents inform every build. Consult them during design, not after. See
research/README.md for the full index.
| Document | Consult When | Key Content |
research/decision-engine.md | Any specific threshold or numeric rule is needed | Consolidated quantitative rules across 10 decision areas, full decision tree, escalation triggers |
research/agent-architecture-playbook.md | Choosing org pattern, defining agents, designing comms | 4 architecture patterns, agent definition template, quality control, memory tiers |
research/team-design-blueprint.md | Designing divisions, handoffs, red team, hierarchy | 3 org patterns, handoff system, red team protocol, peer review gates |
research/skill-design-mastery.md | Writing any skill file | 5 archetypes, 8 design rules, anti-patterns, sizing guide, composition patterns |
research/memory-learning-guide.md | Setting up memory, learning loops, state persistence | Memory types, storage patterns, learning protocols, feedback loops, templates |
research/tool-integration-playbook.md | Connecting MCP servers, external tools, databases | MCP primitives, FastMCP templates, tool assignment, server design patterns |
research/case-study-compendium.md | Validating design decisions, avoiding known failures | 9 case studies (4 anonymized production + 5 external), cross-cutting patterns, common failure modes |
research/anti-pattern-gallery.md | Reviewing a design for known failure modes | 10 concrete bad-build examples with empirical evidence and counter-measures |
What Gets Produced
A complete team build generates one of two structures depending on team size:
Multi-Division Structure (2+ divisions / desks / stages)
Use when the team has multiple peer divisions (DESK), sequential stages (PIPELINE), or distinct functional groups that each need their own playbook and memory.
[team-name]/
CLAUDE.md # Workspace orientation (identity, divisions, lifecycle, priorities)
.claude/
agents/ # Agent definitions (YAML frontmatter + mandate)
skills/ # Skill files (5 archetypes)
rules/ # Shared protocols (desk-protocol, domain standards)
comms/
wire.md # Real-time alerts
board.md # Persistent task state
channels/ # Per-division + all-hands discussion
handoffs/ # Cross-division transfers with ACK/NACK
kill-log.md # Killed items with root cause and lessons
pattern-library.md # Proven patterns and anti-patterns
skill-changelog.md # Agent self-edit audit trail
divisions/
[desk-name]/
CLAUDE.md # Division playbook
memory/ # MEMORY.md, decisions, failures, patterns, learning-ledger
inbox/ # Incoming work
outbox/ # Completed deliverables
protocols/ # kill-switch, escalation-matrix, decision-log, failure-registry, session-closeExample: examples/legal-team/ uses this structure (legal is a single division but the
pattern scales to many).
Single-Team Structure (one cohesive team, no sub-divisions)
Use when the team is a single functional unit where splitting into divisions would be artificial. Smaller teams (4-7 agents) often land here.
[team-name]/
CLAUDE.md # Team orientation (identity, roster, workflow)
.claude/
agents/ # Agent definitions
skills/ # Skill files
rules/ # Shared protocols (optional for small teams)
comms/
wire.md # Real-time alerts
board.md # Persistent task state
channels/
all-hands.md # Cross-role discussion
[team-domain].md # Domain-specific discussion (e.g., dev.md, sales.md)
protocols/ # escalation-matrix, session-close (minimum)
memory/
MEMORY.md # Team memory (learnings, patterns, non-issues)
outbox/ # Completed deliverables (add if agents produce saved artifacts)
inbox/ # Incoming work queue (add only if external work arrives here)Examples: examples/dev-team/ and examples/sales-team/ use this structure. Both add
outbox/ because their agents save dated deliverables (proposals, test reports, deploy
reports); sales-team/ also adds inbox/ for the SDR's incoming lead queue. Neither
directory is mandatory for a single-team build -- add them only if an agent's Files
Owned section actually references them.
How to choose: If the team has genuinely distinct playbooks per sub-group (e.g., Equities desk vs. FX desk, or Research stage vs. Compliance stage), use multi-division. Otherwise use single-team. Artificial divisions waste structure; real divisions demand it.
Templates
Pre-built fill-in templates in templates/:
- Workspace & division:
workspace-claude.md,division-claude.md,desk-protocol.md,agent-definition.md,memory-template.md - Skills (5 archetypes):
skill-task.md,skill-pipeline.md,skill-parallel-spawn.md,skill-command.md,skill-activation.md - Protocols:
protocol-kill-switch.md,protocol-escalation-matrix.md,protocol-decision-log.md,protocol-failure-registry.md,protocol-session-close.md - Comms:
comms-wire.md(alert feed),comms-board.md(task board),comms-channel.md(per-division/all-hands)
Design Principles
- Orchestrator-worker, not bag-of-agents. Every team has a coordinator. Flat networks amplify errors 17x (DeepMind, 2025).
- File ownership prevents conflicts. No two agents write the same files.
- Gates are binary. PASS or BLOCK. Never advisory.
- Backward propagation. Failures flow upstream with corrective actions.
- Peer review before stage transitions. Unanimous approval. No single-agent sign-off.
- Red team on every division. Read-only adversarial review. Separation of creation from critique.
- Memory with caps. MEMORY.md at 150 lines, SKILL.md at 200 lines. Prune or archive.
- Self-evolution. Agents update their own skills. Changes logged. Orchestrator reviews periodically.
Examples
Three examples in examples/ showing the patterns in action:
legal-team/-- 6-agent legal department with contract review pipeline. Canonical complete example with full comms, protocols, memory, divisions, and skills.dev-team/-- 7-agent engineering team with sprint workflow. CLAUDE.md + agents + comms + protocols + memory.sales-team/-- 6-agent sales team with 5-stage deal pipeline. CLAUDE.md + agents + comms + protocols + memory.
Parallel Fan-Out Note
For any multi-item batch (N ≥ 2 posts, audits, reviews, analyses, cleanups), spawn one top-level agent per item, running in parallel, rather than routing the batch through a single orchestrator that processes items serially or via internal sub-agents invisible to the user.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

