team-builder

name	team-builder
description	Automated team creation from blueprints and templates. Validates blueprints, creates teams, spawns members, generates prompts, and assigns initial tasks.

Team Builder Skill

Create fully configured agent teams from blueprint JSON files. This skill automates the entire process: selecting a template, validating its structure, customizing it for a specific project, creating the team, generating prompts, spawning members, and assigning initial tasks with dependency ordering.

When to Use

• Starting a new project that needs a multi-agent team.
• Reusing a proven team configuration across similar projects.
• Standardizing team composition and workflows within an organization.
• Rapidly prototyping different team structures for a problem domain.

Blueprint Format

A blueprint is a JSON file containing four top-level sections:

{
  "template": {
    "name": "fullstack",
    "category": "software-dev",
    "description": "Full-stack web application team",
    "version": "1.0"
  },
  "team": {
    "name_pattern": "{project}-fullstack",
    "description": "Full-stack development team for {project}"
  },
  "members": [
    {
      "role": "team-lead",
      "agent_type": "architect-review",
      "model": "opus",
      "color": "green",
      "prompt_template": "You are the technical lead...",
      "responsibilities": ["Architecture decisions", "Code review"],
      "plan_mode_required": false
    }
  ],
  "workflow": {
    "phases": ["planning", "implementation", "review"],
    "task_templates": [
      {
        "subject": "Define architecture",
        "description": "Create the system architecture document",
        "assigned_to": "team-lead",
        "depends_on": []
      }
    ]
  }
}

Color Assignment

Colors indicate member rank within the team:

Position	Color	Typical Role
1st	green	Team Lead
2nd	yellow	Senior/Secondary
3rd	purple	Core Member
4th	orange	Core Member
5th	pink	Support Member

Every team must have exactly one member with the green color (the team lead).

Valid Agent Types

ai-engineer, api-documenter, architect-review, backend-architect, business-analyst, c-pro, cloud-architect, code-reviewer, content-marketer, context-manager, cpp-pro, customer-support, data-engineer, data-scientist, database-admin, database-optimizer, debugger, deployment-engineer, devops-troubleshooter, dx-optimizer, error-detective, frontend-developer, golang-pro, graphql-architect, incident-responder, ios-developer, java-pro, javascript-pro, legacy-modernizer, legal-advisor, ml-engineer, mlops-engineer, mobile-developer, network-engineer, payment-integration, performance-engineer, php-pro, prompt-engineer, python-pro, quant-analyst, risk-manager, rust-pro, sales-automator, search-specialist, security-auditor, sql-pro, terraform-specialist, test-automator, typescript-pro, ui-ux-designer, general-purpose

Valid Models

opus, sonnet

10-Step Team Creation Process

Step 1: Select Template

Choose or locate the blueprint JSON file that matches your project needs. Blueprints live in your workspace or a shared template repository.

Select a blueprint: blueprints/fullstack.json

Step 2: Validate Blueprint

Run the validation script to check the blueprint for structural errors, invalid agent types, missing fields, duplicate roles, and circular task dependencies.

python scripts/validate_blueprint.py blueprints/fullstack.json

The validator checks: required fields present, exactly one green lead, all agent types valid, all models valid, all colors valid, no empty prompts, no duplicate roles, all task assignments reference existing roles, and no circular dependencies. Fix any reported errors before proceeding.

Step 3: Customize for Project

Replace {project} placeholders in the blueprint with your actual project name. The build script handles this automatically when you supply the --project argument.

python scripts/build_team.py blueprints/fullstack.json --project myapp

This resolves {project}-fullstack to myapp-fullstack and Full-stack team for {project} to Full-stack team for myapp.

Step 4: Create Team (TeamCreate)

The build script outputs the tool call sequence. The first call creates the team itself:

Tool: TeamCreate
Arguments:
  name: myapp-fullstack
  description: Full-stack development team for myapp

Execute this call to establish the team container. Record the returned team ID for subsequent steps.

Step 5: Generate Enhanced Prompts

Run the prompt generator to produce final system prompts for each member. These combine the blueprint's prompt_template with responsibilities, team context, and communication guidelines.

python scripts/generate_prompts.py blueprints/fullstack.json --project myapp

Each generated prompt includes: the base template text, a responsibilities section, awareness of other team members, the project name, and standard communication protocols.

Step 6: Spawn Team Members

For each member defined in the blueprint, execute a spawn call. The build script outputs these in rank order (green first, then yellow, purple, orange, pink).

Tool: SpawnMember
Arguments:
  team_id: <team-id>
  role: team-lead
  agent_type: architect-review
  model: opus
  color: green
  prompt: <generated prompt from Step 5>

Repeat for every member. The lead is always spawned first so it can receive messages from subsequently spawned members.

Step 7: Create Tasks

For each task template in the workflow, create a task within the team:

Tool: TaskCreate
Arguments:
  team_id: <team-id>
  subject: Define architecture
  description: Create the system architecture document for myapp

Record each task's returned ID for dependency linking.

Step 8: Set Task Dependencies

Link tasks according to the depends_on fields. A task will not become actionable until all its dependencies are complete.

Tool: TaskSetDependency
Arguments:
  task_id: <task-id>
  depends_on: <dependency-task-id>

The build script outputs these in topological order to ensure all referenced dependencies exist before being linked.

Step 9: Assign Tasks

Assign each task to the member specified in assigned_to:

Tool: TaskAssign
Arguments:
  task_id: <task-id>
  assignee: team-lead

Tasks with unmet dependencies will remain in a blocked state until their prerequisites complete.

Step 10: Verify Team

Confirm the team is fully operational:

1. Check that all members are spawned and responsive.
2. Check that all tasks are created and assigned.
3. Check that dependency chains are correct and no tasks are orphaned.
4. Send an initial message to the team lead to begin the first workflow phase.

Complete Walkthrough Example

Suppose you have a project called acme-store and want a full-stack team. Here is the entire process from start to finish.

Validate the blueprint:

$ python scripts/validate_blueprint.py blueprints/fullstack.json
[PASS] Blueprint 'fullstack' is valid.
  Template: fullstack v1.0 (software-dev)
  Members: 4
  Tasks: 6
  Phases: planning, implementation, review

Generate the build plan:

$ python scripts/build_team.py blueprints/fullstack.json --project acme-store
=== Team Build Plan for 'acme-store' ===

Step 1: Create Team
  TeamCreate(name="acme-store-fullstack", description="Full-stack development team for acme-store")

Step 2: Spawn Members (4)
  [green]  team-lead       | architect-review | opus
  [yellow] backend-dev     | backend-architect | sonnet
  [purple] frontend-dev    | frontend-developer | sonnet
  [orange] test-engineer   | test-automator | sonnet

Step 3: Create Tasks (6)
  T1: "Define architecture"        -> team-lead      (no deps)
  T2: "Design API contracts"       -> backend-dev    (depends: T1)
  T3: "Build API endpoints"        -> backend-dev    (depends: T2)
  T4: "Build UI components"        -> frontend-dev   (depends: T2)
  T5: "Write integration tests"    -> test-engineer  (depends: T3, T4)
  T6: "Final review"               -> team-lead      (depends: T5)

Step 4: Set Dependencies
  T2 depends on T1
  T3 depends on T2
  T4 depends on T2
  T5 depends on T3, T4
  T6 depends on T5

Step 5: Assign Tasks
  T1 -> team-lead
  T2 -> backend-dev
  T3 -> backend-dev
  T4 -> frontend-dev
  T5 -> test-engineer
  T6 -> team-lead

Generate prompts:

$ python scripts/generate_prompts.py blueprints/fullstack.json --project acme-store
Generated prompt for 'team-lead' (architect-review) -> 847 chars
Generated prompt for 'backend-dev' (backend-architect) -> 792 chars
Generated prompt for 'frontend-dev' (frontend-developer) -> 814 chars
Generated prompt for 'test-engineer' (test-automator) -> 756 chars

Execute the plan by running the tool calls in the order the build script outputs them. After the final step, your acme-store-fullstack team is live and ready to begin the planning phase.

Helper Scripts

Script	Purpose
scripts/validate_blueprint.py	Validate blueprint JSON structure and semantics
scripts/build_team.py	Generate tool call sequence from blueprint
scripts/generate_prompts.py	Create enhanced prompts from templates

Tips

• Always validate before building. A malformed blueprint causes partial team creation that is tedious to clean up.
• Start with a small team (2-3 members) and scale up once the workflow is proven.
• Keep prompt templates under 300 words. The generator adds context automatically; overly long base prompts produce bloated final prompts.
• Use depends_on liberally. Explicit dependencies prevent agents from racing ahead on tasks whose inputs are not ready.
• Assign the team lead as the final reviewer in every workflow. This gives the lead visibility into all completed work.

Related Skills

• team-templates -- Source of pre-built blueprints to use with this skill
• team-architect -- Design custom team compositions when no template fits
• team-monitor -- Verify team health after creation with team_status.py
• team-lifecycle -- Understand the full creation-to-shutdown lifecycle