agentleFS
AgentJDrewAgentJDrew/agent-team-factory/CLAUDE.md

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…

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
  1. Distinctive:

    Use when the team has multiple peer divisions (DESK), sequential stages (PIPELINE), or distinct functional groups that each need their own …

    line 59
  2. Distinctive:

    Use when the team is a single functional unit where splitting into divisions would be artificial.

    line 91
  3. Distinctive:

    How to choose: If the team has genuinely distinct playbooks per sub-group (e.g., Equities desk vs.

    line 120
  4. Distinctive:

    Orchestrator-worker, not bag-of-agents: Every team has a coordinator.

    line 136
  5. Distinctive:

    File ownership prevents conflicts: No two agents write the same files.

    line 137
  6. Distinctive:

    Red team on every division: Read-only adversarial review.

    line 141

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 any build-team output.
  • 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

SkillPurposeTrigger
build-teamFull team from scratch. Intake, architecture, generate, review, deliver."build me a team", "create a floor", "set up a [domain] team"
build-agentSingle agent definition with YAML frontmatter, mandate, files, dependencies."add an agent", "create a [role] agent", "I need a new specialist"
build-skillSingle skill file from 5 archetypes (Task, Pipeline, Parallel, Command, Activation)."create a skill", "build a skill for [task]", "new skill"
build-pipelinePipeline orchestrator with stages, gates, kill conditions, state persistence."build a pipeline", "create a [N]-stage workflow", "pipeline for [domain]"
audit-teamAudit 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.

DocumentConsult WhenKey Content
research/decision-engine.mdAny specific threshold or numeric rule is neededConsolidated quantitative rules across 10 decision areas, full decision tree, escalation triggers
research/agent-architecture-playbook.mdChoosing org pattern, defining agents, designing comms4 architecture patterns, agent definition template, quality control, memory tiers
research/team-design-blueprint.mdDesigning divisions, handoffs, red team, hierarchy3 org patterns, handoff system, red team protocol, peer review gates
research/skill-design-mastery.mdWriting any skill file5 archetypes, 8 design rules, anti-patterns, sizing guide, composition patterns
research/memory-learning-guide.mdSetting up memory, learning loops, state persistenceMemory types, storage patterns, learning protocols, feedback loops, templates
research/tool-integration-playbook.mdConnecting MCP servers, external tools, databasesMCP primitives, FastMCP templates, tool assignment, server design patterns
research/case-study-compendium.mdValidating design decisions, avoiding known failures9 case studies (4 anonymized production + 5 external), cross-cutting patterns, common failure modes
research/anti-pattern-gallery.mdReviewing a design for known failure modes10 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-close

Example: 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

  1. Orchestrator-worker, not bag-of-agents. Every team has a coordinator. Flat networks amplify errors 17x (DeepMind, 2025).
  2. File ownership prevents conflicts. No two agents write the same files.
  3. Gates are binary. PASS or BLOCK. Never advisory.
  4. Backward propagation. Failures flow upstream with corrective actions.
  5. Peer review before stage transitions. Unanimous approval. No single-agent sign-off.
  6. Red team on every division. Read-only adversarial review. Separation of creation from critique.
  7. Memory with caps. MEMORY.md at 150 lines, SKILL.md at 200 lines. Prune or archive.
  8. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.