Creating Squads - Synkra AIOX

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:

What problem does this squad solve?
- Example: “Automate casting workflow for film production”
Who are the users?
- Example: “Casting directors, production managers”
What are the key workflows?
- Example: “Process submissions, schedule auditions, manage callbacks”
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:

Analyze your documentation
Extract domain concepts and workflows
Recommend agents with roles and responsibilities
Suggest tasks for each agent
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:

Squad name (validates kebab-case)
Description (what the squad does)
Author (your name and email)
License (MIT, Apache, etc.)
Template (basic, etl, agent-only, or none)
Agent names (comma-separated)
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

Review submission
Initial screening
Schedule audition
Conduct audition
Callback decision
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

Clear inputs/outputs - Document all parameters
Error handling - List all possible error states
Step-by-step - Break down the process
Checklist - Validation points
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 <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:

# 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

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

Development

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

Publishing

Validate strictly - Use --strict flag
Write good README - Usage examples and requirements
Choose appropriate license - MIT recommended
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

Getting Started

Development

Extensions

Documentation Index

​Overview

​Prerequisites

​Step 1: Planning Your Squad

​Define the Domain

​Research Existing Squads

​Step 2: Design with Squad Designer

​Gather Documentation

​Run the Designer

​Review the Blueprint

​Refine Recommendations

​Step 3: Create the Squad

​Option A: From Blueprint

​Option B: From Template

​Option C: Interactive Creation

​Step 4: Define Agents

​Agent File Structure

​schedule-audition

​Knowledge Base

​Submission Format

​Audition Process

​Task Best Practices

​Step 6: Configure the Squad

​Edit squad.yaml

​Config Files

​Step 7: Add Workflows (Optional)

​Step 8: Validate the Squad

​Common Validation Errors

​Step 9: Test the Squad

​Local Testing

​Integration Testing

​Validation Testing

​Step 10: Document the Squad

​README.md

​Usage

​Process a submission

​Schedule an audition

​Agents

​Requirements

​License

​Publish Options

​Best Practices

​Design

​Development

​Publishing

​Troubleshooting

​Next Steps

Overview

Prerequisites

Step 1: Planning Your Squad

Define the Domain

Research Existing Squads

Step 2: Design with Squad Designer

Gather Documentation

Run the Designer

Review the Blueprint

Refine Recommendations

Step 3: Create the Squad

Option A: From Blueprint

Option B: From Template

Option C: Interactive Creation

Step 4: Define Agents

Agent File Structure

schedule-audition

Knowledge Base

Submission Format

Audition Process

Task Best Practices

Step 6: Configure the Squad

Edit squad.yaml

Config Files

Step 7: Add Workflows (Optional)

Step 8: Validate the Squad

Common Validation Errors

Step 9: Test the Squad

Local Testing

Integration Testing

Validation Testing

Step 10: Document the Squad

README.md

Usage

Process a submission

Schedule an audition

Agents

Requirements

License

Publish Options

Best Practices

Design

Development

Publishing

Troubleshooting

Next Steps