Squad System

Organize AI agents into specialized teams for any domain beyond software development

What are Squads?

Squads are modular teams of AI agents that extend AIOX functionality to any domain. Each squad is a self-contained package with specialized agents, workflows, and tools.

The AIOX framework works in any domain through natural language. Squads package domain expertise into reusable agent teams.

Squad Architecture

A squad is a complete package containing:

Agents

Domain-specific AI personas with specialized knowledge

Tasks

Executable workflows following TASK-FORMAT-SPEC-V1

Workflows

Multi-step orchestrations linking tasks together

Config

Coding standards, tech stack, directory structure

Templates

Document generation templates for common outputs

Tools

Custom integrations and utilities

Directory Structure

./squads/my-squad/
├── squad.yaml              # Manifest (required)
├── README.md               # Documentation
├── LICENSE                 # License file
├── config/
│   ├── coding-standards.md # Code style rules
│   ├── tech-stack.md       # Technologies used
│   └── source-tree.md      # Directory structure
├── agents/
│   └── specialist.md       # Agent definitions
├── tasks/
│   └── workflow-task.md    # Task definitions
├── workflows/
│   └── process.yaml        # Multi-step workflows
├── checklists/
│   └── quality.md          # Validation checklists
├── templates/
│   └── report.md           # Document templates
├── tools/
│   └── custom-tool.js      # Custom integrations
├── scripts/
│   └── setup.js            # Utility scripts
└── data/
    └── reference.json      # Static data files

Squad Manifest

Every squad has a squad.yaml manifest file:

# Required fields
name: my-squad                    # kebab-case, unique identifier
version: 1.0.0                    # Semantic versioning
description: What this squad does

# Metadata
author: Your Name <[e-mail]>
license: MIT
slashPrefix: my                   # Command prefix for IDE

# AIOX compatibility
aiox:
  minVersion: "2.1.0"
  type: squad

# Components declaration
components:
  agents:
    - specialist.md
  tasks:
    - workflow-task.md
  workflows: []
  checklists: []
  templates: []
  tools: []
  scripts: []

# Configuration inheritance
config:
  extends: extend                 # extend | override | none
  coding-standards: config/coding-standards.md
  tech-stack: config/tech-stack.md
  source-tree: config/source-tree.md

# Dependencies
dependencies:
  node: []                        # npm packages
  python: []                      # pip packages
  squads: []                      # Other squads

# Discovery tags
tags:
  - domain-specific
  - automation

Task-First Architecture

Squads follow a task-first architecture where tasks are the primary entry point:

Tasks must follow TASK-FORMAT-SPECIFICATION-V1.

Creating Squads

Quick Start

1. Activate Squad Creator

   @squad-creator
   
2. Create Squad

   # Interactive creation
   *create-squad my-domain-squad
   
   # Or from template
   *create-squad my-squad --template etl
   
3. Validate

   *validate-squad my-domain-squad
   

Available Templates

Template	Use Case
basic	Simple squad with one agent and task
etl	Data extraction, transformation, loading
agent-only	Squad with agents, no tasks

Squad Designer (Recommended)

The Squad Designer analyzes your documentation and recommends agents and tasks:

1. Design from Documentation

   @squad-creator
   *design-squad --docs ./docs/prd/my-project.md
   
2. Review Recommendations

   The system analyzes your docs and suggests:

   • Agents (with confidence scores)
   • Tasks (linked to agents)
   • Workflows (multi-step processes)
3. Create from Blueprint

   *create-squad my-squad --from-design
   

Blueprint Format

# .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
    confidence: 0.92

recommended_tasks:
  - name: process-submission
    description: Process actor submission
    agent: casting-coordinator
    confidence: 0.88

Analyzing & Extending Squads

Analyze Squad Structure

@squad-creator

# Basic analysis
*analyze-squad my-squad

# Verbose output
*analyze-squad my-squad --verbose

# Export as markdown
*analyze-squad my-squad --format markdown

Analysis Output:

=== Squad Analysis: my-squad ===

Overview
  Name: my-squad
  Version: 1.0.0
  Author: Your Name

Components
  agents/ (2)
    - lead-agent.md
    - helper-agent.md
  tasks/ (3)
    - lead-agent-task1.md
    - lead-agent-task2.md
    - helper-agent-task1.md
  workflows/ (0) <- Empty

Coverage
  Agents: [#####-----] 50% (1/2 with tasks)
  Tasks: [########--] 80% (3 tasks)
  Directories: [##--------] 25% (2/8 populated)

Suggestions
  1. [!] Add tasks for helper-agent
  2. [*] Create workflows for common sequences
  3. [-] Add checklists for validation

Extend Existing Squad

Add Agent

@squad-creator
*extend-squad my-squad --add agent --name analytics-agent

Component Types

Type	Directory	Extension	Description
agent	agents/	.md	Agent persona definition
task	tasks/	.md	Executable task workflow
workflow	workflows/	.yaml	Multi-step orchestration
checklist	checklists/	.md	Validation checklist
template	templates/	.md	Document generation template
tool	tools/	.js	Custom tool integration
script	scripts/	.js	Utility automation script
data	data/	.yaml	Static data configuration

Configuration Inheritance

Squads can inherit or override core AIOX configuration:

Inheritance Modes

extend

Add squad rules to core AIOX rules

config:
  extends: extend

• Core rules remain active
• Squad rules supplement
• Best for specialized extensions

override

Replace core rules with squad rules

config:
  extends: override

• Core rules disabled
• Squad rules only
• Best for completely different domains

none

Standalone configuration

config:
  extends: none

• No inheritance
• Fully self-contained
• Best for independent squads

Validating Squads

Basic Validation

@squad-creator
*validate-squad my-squad

Strict Mode (CI/CD)

*validate-squad my-squad --strict

Treats warnings as errors.

Validation Checks

Manifest Schema

Validates squad.yaml against JSON Schema:

• Required fields present
• Valid semver version
• Correct AIOX type

Directory Structure

Ensures required folders exist:

• agents/
• tasks/
• Config files referenced in manifest

Task Format

Verifies tasks follow TASK-FORMAT-SPEC-V1:

• Required sections present
• Valid YAML frontmatter
• Agent linkage correct

Agent Definitions

Checks agents have required fields:

• Name, role, commands
• Valid persona structure
• No circular dependencies

Squad Distribution

Squads can be distributed at three levels:

Level 1: Local (Private)

Squads in ./squads/ are automatically available:

*list-squads

Level 2: GitHub (Public)

Publish to the community:

@squad-creator

# Validate first
*validate-squad my-squad --strict

# Publish to GitHub
*publish-squad ./squads/my-squad

Creates a PR to SynkraAI/aiox-squads.

Level 3: Marketplace

Sync to Synkra API:

# Set up authentication
export SYNKRA_API_TOKEN="your-token"

# Sync to marketplace
*sync-squad-synkra ./squads/my-squad --public

Downloading Squads

@squad-creator

# List available squads
*download-squad --list

# Download specific squad
*download-squad etl-squad

# Download specific version
*download-squad etl-squad@2.0.0

Official Squads

Squad	Version	Description
etl-squad	2.0.0	Data collection and transformation
creator-squad	1.0.0	Content generation utilities
hybrid-ops	1.0.0	Human-agent hybrid operations

Migration from Legacy

Migrate old squad formats to the new standard:

1. Detect Legacy Format

   Legacy squads use config.yaml instead of squad.yaml

2. Preview Migration

   @squad-creator
   *migrate-squad ./squads/legacy-squad --dry-run
   
3. Execute Migration

   *migrate-squad ./squads/legacy-squad
   

   Automatic backup created in .backup/pre-migration-{timestamp}/

4. Validate Result

   *validate-squad legacy-squad --strict
   

Rollback

# Restore from backup
cp -r ./squads/my-squad/.backup/pre-migration-*/. ./squads/my-squad/

Programmatic Usage

JavaScript API

const { SquadLoader, SquadValidator, SquadAnalyzer, SquadExtender } = 
  require('./.aiox-core/development/scripts/squad');

// Load squad
const loader = new SquadLoader({ squadsPath: './squads' });
const { path, manifestPath } = await loader.resolve('my-squad');
const manifest = await loader.loadManifest(path);

// Validate squad
const validator = new SquadValidator({ strict: false });
const result = await validator.validate('./squads/my-squad');
console.log(result); // { valid: true, errors: [], warnings: [] }

// Analyze squad
const analyzer = new SquadAnalyzer({ squadsPath: './squads' });
const analysis = await analyzer.analyze('my-squad');
console.log('Coverage:', analysis.coverage);

// Extend squad
const extender = new SquadExtender({ squadsPath: './squads' });
const added = await extender.addComponent('my-squad', {
  type: 'task',
  name: 'new-task',
  agentId: 'lead-agent',
  description: 'A new task'
});
console.log('Created:', added.filePath);

Use Cases Beyond Development

Creative Writing

Agents for plot development, character design, world-building

Business Strategy

Market analysis, competitor research, strategic planning

Education

Curriculum design, lesson planning, assessment creation

Healthcare

Patient care workflows, medical documentation, research

Legal

Contract analysis, case research, document drafting

Entertainment

Casting coordination, production planning, script analysis

Best Practices

Start with Squad Designer

Let the system analyze your documentation and recommend structure:

*design-squad --docs ./docs/requirements.md

Use Task-First Design

Define what users want to accomplish (tasks) before creating agents.

Validate Early and Often

*validate-squad my-squad --strict

Run after every significant change.

Version Semantically

Follow semantic versioning:

• MAJOR: Breaking changes
• MINOR: New features
• PATCH: Bug fixes

Document Thoroughly

Include comprehensive README with:

• Purpose and use cases
• Installation instructions
• Example workflows
• Troubleshooting

Troubleshooting

Squad Not Found

# Check squads directory
ls ./squads/

# Verify manifest
cat ./squads/my-squad/squad.yaml

# List recognized squads
@squad-creator
*list-squads

Validation Errors

# Get detailed errors
*validate-squad my-squad --verbose

Common fixes:

• name: Must be kebab-case
• version: Must be semver (x.y.z)
• aiox.type: Must be “squad”
• aiox.minVersion: Must be valid semver

YAML Parse Errors

# Validate YAML syntax
npx js-yaml ./squads/my-squad/squad.yaml

Common issues:

• Incorrect indentation (use 2 spaces)
• Missing quotes around special characters
• Tabs instead of spaces

Related Documentation

Custom Agents

Learn to create custom agent definitions

ADE System

Integrate ADE capabilities into squads

IDE Integration

Set up squads in your IDE

Agent Commands

Full @squad-creator command reference