> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
@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

```bash theme={null}
@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`:

```yaml theme={null}
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

```bash theme={null}
@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

```bash theme={null}
@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

```bash theme={null}
@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/`:

````markdown theme={null}
# 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

```yaml theme={null}
name: casting-squad
version: 1.0.0
description: AI agents for casting workflow automation

author: Your Name <email@example.com>
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:**

```markdown theme={null}
# 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:**

```markdown theme={null}
# 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`:

```yaml theme={null}
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

```bash theme={null}
@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

```bash theme={null}
# Activate a squad agent
@casting-coordinator

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

# Check output
# Verify the task completes successfully
```

### Integration Testing

```bash theme={null}
# Run squad workflow
*run-workflow casting-workflow start

# Execute each step
# Verify handoffs between agents
```

### Validation Testing

```bash theme={null}
# 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:

````markdown theme={null}
# 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

```bash theme={null}
@casting-coordinator
*process-submission --file submission.pdf --priority high
```

### Schedule an audition

```bash theme={null}
@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)**

```bash theme={null}
@squad-creator
*publish-squad ./squads/casting-squad
```

This creates a PR to `SynkraAI/aiox-squads`.

**Option B: Synkra Marketplace**

```bash theme={null}
export SYNKRA_API_TOKEN="your-token"
*sync-squad-synkra ./squads/casting-squad --public
```

**Option C: Keep Private**

Add to `.gitignore`:

```gitignore theme={null}
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](./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