Creating Squads

Step-by-step guide to creating custom squads for domain-specific AI agents

Overview

This guide walks you through creating a custom squad from scratch, from initial planning to validation and deployment.

Prerequisites

• AIOX project initialized
• Basic understanding of AIOX agents and tasks
• Domain knowledge for your squad’s purpose

Step 1: Planning Your Squad

Define the Domain

Before creating a squad, answer these questions:

1. What problem does this squad solve?

   • Example: “Automate casting workflow for film production”

2. Who are the users?

   • Example: “Casting directors, production managers”

3. What are the key workflows?

   • Example: “Process submissions, schedule auditions, manage callbacks”

4. What agents are needed?

   • Example: “Casting coordinator, audition scheduler, talent evaluator”

Research Existing Squads

@squad-creator

# Search for similar squads
*download-squad --list

# Check if your domain is already covered

Don’t reinvent the wheel - extend existing squads if possible.

Step 2: Design with Squad Designer

Gather Documentation

Collect all relevant documentation:

• Product requirements documents (PRDs)
• Technical specifications
• User stories
• Process diagrams
• Domain glossaries

Run the Designer

@squad-creator

# Design from documentation
*design-squad --docs ./docs/prd/casting-system.md --domain casting

The designer will:

1. Analyze your documentation
2. Extract domain concepts and workflows
3. Recommend agents with roles and responsibilities
4. Suggest tasks for each agent
5. Generate a blueprint file (.squad-design.yaml)

Review the Blueprint

Open .squad-design.yaml:

metadata:
  domain: casting
  created: 2025-12-26T10:00:00Z
  source_docs:
    - ./docs/prd/casting-system.md

recommended_agents:
  - name: casting-coordinator
    role: Coordinates casting workflows
    responsibilities:
      - Manage submissions
      - Schedule auditions
      - Track callbacks
    confidence: 0.92

  - name: talent-evaluator
    role: Evaluates talent submissions
    responsibilities:
      - Review headshots and resumes
      - Assess fit for roles
      - Provide recommendations
    confidence: 0.88

recommended_tasks:
  - name: process-submission
    description: Process actor submission
    agent: casting-coordinator
    inputs:
      - Headshot
      - Resume
      - Demo reel
    outputs:
      - Submission record
      - Initial evaluation
    confidence: 0.88

  - name: schedule-audition
    description: Schedule audition for actor
    agent: casting-coordinator
    inputs:
      - Actor ID
      - Available slots
    outputs:
      - Audition appointment
      - Calendar event
    confidence: 0.85

Refine Recommendations

Edit the blueprint to:

• Add missing agents
• Remove unnecessary agents
• Adjust agent responsibilities
• Add custom tasks
• Modify task inputs/outputs

Step 3: Create the Squad

Option A: From Blueprint

@squad-creator

# Create from your refined blueprint
*create-squad casting-squad --from-design

This creates:

./squads/casting-squad/
├── squad.yaml              # Generated manifest
├── README.md               # Generated documentation
├── LICENSE                 # MIT license (default)
├── agents/
│   ├── casting-coordinator.md
│   └── talent-evaluator.md
├── tasks/
│   ├── casting-coordinator-process-submission.md
│   └── casting-coordinator-schedule-audition.md
├── config/
│   ├── coding-standards.md
│   ├── tech-stack.md
│   └── source-tree.md
└── workflows/
    └── .gitkeep

Option B: From Template

@squad-creator

# Create from basic template
*create-squad casting-squad --template basic

# Or from ETL template
*create-squad data-squad --template etl

# Or agent-only (no tasks)
*create-squad simple-squad --template agent-only

Option C: Interactive Creation

@squad-creator

# Interactive prompts
*create-squad casting-squad

You’ll be asked:

1. Squad name (validates kebab-case)
2. Description (what the squad does)
3. Author (your name and email)
4. License (MIT, Apache, etc.)
5. Template (basic, etl, agent-only, or none)
6. Agent names (comma-separated)
7. Config inheritance (extend, override, none)

Step 4: Define Agents

Agent File Structure

Each agent is a markdown file in agents/:

# Casting Coordinator

**Role:** Coordinates casting workflows and manages submissions

**Personality:** Organized, detail-oriented, proactive

**Archetype:** Coordinator

---

## Responsibilities

- Manage actor submissions
- Schedule auditions
- Track callbacks and decisions
- Coordinate with production team

## Commands

### process-submission

**Usage:** `*process-submission --file submission.pdf`

**Description:** Process a new actor submission

**Parameters:**
- `--file` (required): Path to submission file
- `--priority` (optional): Priority level (high, medium, low)

**Example:**
```bash
*process-submission --file actors/john-doe.pdf --priority high

schedule-audition

Usage: *schedule-audition --actor-id ID --slot DATETIME

Description: Schedule an audition for an actor

Knowledge Base

Submission Format

Standard submission includes:

• Headshot (JPG/PNG, max 5MB)
• Resume (PDF)
• Demo reel link (optional)
• Contact information

Audition Process

1. Review submission
2. Initial screening
3. Schedule audition
4. Conduct audition
5. Callback decision
6. Final selection

### Key Sections

1. **Title** - Agent name
2. **Role** - What the agent does
3. **Personality** - How the agent communicates
4. **Archetype** - Agent category (coordinator, analyst, builder, etc.)
5. **Responsibilities** - Specific duties
6. **Commands** - Available agent commands
7. **Knowledge Base** - Domain-specific information

## Step 5: Create Tasks

### Task File Structure

Tasks follow [TASK-FORMAT-SPECIFICATION-V1](../architecture/task-format-spec):

```markdown
# Process Submission

**Owner:** casting-coordinator
**Version:** 1.0
**Story:** SQS-12

---

## Summary

Process a new actor submission, validate completeness, and create a submission record.

## Entrada (Input)

**Required:**
- `submission_file` (String): Path to submission PDF
- `actor_name` (String): Full name of actor

**Optional:**
- `priority` (String): Priority level (default: "medium")
- `notes` (String): Additional notes

## Saída (Output)

**Success:**
- `submission_id` (String): Unique submission identifier
- `status` (String): "processed" | "incomplete" | "rejected"
- `record` (Object): Submission record object

**Errors:**
- `INVALID_FILE`: File not found or unreadable
- `MISSING_REQUIRED`: Missing required information
- `DUPLICATE`: Submission already exists

## Steps

1. **Validate submission file**
   - Check file exists and is readable
   - Verify file format (PDF)
   - Check file size (< 10MB)

2. **Extract information**
   - Parse actor name
   - Extract contact information
   - Parse resume data
   - Extract demo reel link

3. **Check for duplicates**
   - Search existing submissions by actor name
   - Compare submission dates

4. **Create submission record**
   - Generate unique submission ID
   - Store in database
   - Update actor profile

5. **Notify stakeholders**
   - Send confirmation email to actor
   - Alert casting director of new submission

## Checklist

- [ ] File validation passed
- [ ] All required fields extracted
- [ ] No duplicate submission found
- [ ] Record created in database
- [ ] Confirmation email sent

## Dependencies

**Tasks:**
- None (entry point task)

**Files:**
- `src/services/submission-processor.js`
- `src/models/submission.js`

**External:**
- Email service (SendGrid)
- Database (PostgreSQL)

## Notes

- Submissions older than 6 months are archived
- Priority affects queue position
- Demo reels are optional but recommended

Task Best Practices

1. Clear inputs/outputs - Document all parameters
2. Error handling - List all possible error states
3. Step-by-step - Break down the process
4. Checklist - Validation points
5. Dependencies - What this task needs

Step 6: Configure the Squad

Edit squad.yaml

name: casting-squad
version: 1.0.0
description: AI agents for casting workflow automation

author: Your Name <[e-mail]>
license: MIT
slashPrefix: casting

aiox:
  minVersion: "2.1.0"
  type: squad

components:
  agents:
    - casting-coordinator.md
    - talent-evaluator.md
  tasks:
    - casting-coordinator-process-submission.md
    - casting-coordinator-schedule-audition.md
    - talent-evaluator-evaluate-talent.md
  workflows:
    - casting-workflow.yaml
  checklists: []
  templates:
    - submission-report.md
  tools: []
  scripts: []

config:
  extends: extend
  coding-standards: config/coding-standards.md
  tech-stack: config/tech-stack.md
  source-tree: config/source-tree.md

dependencies:
  node:
    - pdf-parse
    - nodemailer
  python: []
  squads: []

tags:
  - casting
  - film-production
  - talent-management

Config Files

Customize configuration in config/:

coding-standards.md:

# Casting Squad Coding Standards

## File Naming

- Submissions: `submission-{actor-name}-{date}.pdf`
- Reports: `report-{type}-{date}.md`

## Data Validation

- All actor names must be validated
- Email addresses must be verified
- Phone numbers must follow format: +1-XXX-XXX-XXXX

## Error Handling

- Always validate inputs
- Provide clear error messages
- Log all errors to system

tech-stack.md:

# Casting Squad Tech Stack

## Core Technologies

- **Runtime:** Node.js 18+
- **Database:** PostgreSQL 14+
- **Email:** SendGrid API
- **Storage:** AWS S3

## Libraries

- `pdf-parse` - PDF extraction
- `nodemailer` - Email sending
- `pg` - PostgreSQL client

Step 7: Add Workflows (Optional)

Create workflows/casting-workflow.yaml:

workflow:
  id: casting-workflow
  name: Complete Casting Workflow
  version: "1.0"
  description: "End-to-end casting process from submission to selection"
  type: generic

  phases:
    - phase_1: Submission Processing
    - phase_2: Initial Screening
    - phase_3: Audition Scheduling
    - phase_4: Audition & Callback
    - phase_5: Final Selection

  sequence:
    - step: process_submission
      phase: 1
      agent: casting-coordinator
      action: Process actor submission
      task: process-submission
      next: screen_submission

    - step: screen_submission
      phase: 2
      agent: talent-evaluator
      action: Screen submission for role fit
      task: evaluate-talent
      next: schedule_audition

    - step: schedule_audition
      phase: 3
      agent: casting-coordinator
      action: Schedule audition appointment
      task: schedule-audition
      next: conduct_audition

Step 8: Validate the Squad

@squad-creator

# Run validation
*validate-squad casting-squad

# Run strict validation (for CI/CD)
*validate-squad casting-squad --strict

Common Validation Errors

Error: “Invalid squad name”

• Solution: Use kebab-case (lowercase with hyphens)
• Example: casting-squad not CastingSquad

Error: “Missing required fields in manifest”

• Solution: Add missing fields to squad.yaml
• Required: name, version, description, aiox.type, aiox.minVersion

Error: “Task file does not follow TASK-FORMAT-SPEC-V1”

• Solution: Review task format specification
• Ensure all required sections present

Error: “Agent file not found”

• Solution: Check components.agents in squad.yaml
• Verify file exists in agents/ directory

Step 9: Test the Squad

Local Testing

# Activate a squad agent
@casting-coordinator

# Test a command
*process-submission --file test-submission.pdf

# Check output
# Verify the task completes successfully

Integration Testing

# Run squad workflow
*run-workflow casting-workflow start

# Execute each step
# Verify handoffs between agents

Validation Testing

# Test error handling
*process-submission --file nonexistent.pdf
# Should show: "INVALID_FILE: File not found"

# Test required parameters
*process-submission
# Should show: "Missing required parameter: submission_file"

Step 10: Document the Squad

README.md

Create comprehensive documentation:

# Casting Squad

AI agents for automating casting workflows in film and TV production.

## Features

- Automated submission processing
- Intelligent talent evaluation
- Audition scheduling
- Callback tracking

## Installation

```bash
@squad-creator
*download-squad casting-squad

Usage

Process a submission

@casting-coordinator
*process-submission --file submission.pdf --priority high

Schedule an audition

@casting-coordinator
*schedule-audition --actor-id A123 --slot "2025-01-15 10:00"

Agents

• Casting Coordinator - Manages submissions and scheduling
• Talent Evaluator - Evaluates actor fit for roles

Requirements

• Node.js 18+
• PostgreSQL 14+
• SendGrid API key

License

MIT

## Step 11: Publish the Squad

### Prepare for Publishing

```bash
# Final validation
*validate-squad casting-squad --strict

# Version check
# Ensure version follows semver: 1.0.0

Publish Options

Option A: GitHub (Public)

@squad-creator
*publish-squad ./squads/casting-squad

This creates a PR to SynkraAI/aiox-squads.

Option B: Synkra Marketplace

export SYNKRA_API_TOKEN="your-token"
*sync-squad-synkra ./squads/casting-squad --public

Option C: Keep Private

Add to .gitignore:

squads/casting-squad/

Best Practices

Design

1. Start with documentation - Use Squad Designer
2. Keep agents focused - One clear responsibility per agent
3. Create comprehensive tasks - Cover all workflows
4. Test early and often - Validate as you build

Development

1. Follow task format - Adhere to TASK-FORMAT-SPEC-V1
2. Document thoroughly - Clear README and examples
3. Version semantically - Use semver (x.y.z)
4. Handle errors gracefully - Clear error messages

Publishing

1. Validate strictly - Use --strict flag
2. Write good README - Usage examples and requirements
3. Choose appropriate license - MIT recommended
4. Tag appropriately - Help users find your squad

Troubleshooting

See the Squads Guide for common issues and solutions.

Next Steps

• Custom Workflows - Create multi-step workflows
• Advanced Tasks - Build complex task orchestrations
• Squad Testing - Write tests for your squad
• Community - Share your squad with others