Skip to content

squads-overview.md

Latest commit

 

History

History
326 lines (237 loc) · 9.74 KB

squads-overview.md

File metadata and controls

326 lines (237 loc) · 9.74 KB
Raw

Squads Overview

EN

Introduction to AIOX Squads - modular teams of AI agents that extend framework functionality.

Version: 2.1.0 Last Updated: 2026-01-28

What are Squads?

Squads are modular teams of AI agents that extend AIOX functionality for specific domains or use cases. Each squad is a self-contained package that can be installed, shared, and composed with other squads.

AIOX Squads: AI agent teams working with you

Key Characteristics

Characteristic Description
Modular Self-contained packages with all dependencies
Composable Multiple squads can work together
Shareable Publish to repository or marketplace
Extensible Build on top of existing squads
Versionable Semantic versioning for compatibility

Squad vs. Traditional Agents

Traditional Agents AIOX Squads
Individual agents Coordinated team of agents
Single-purpose Domain-focused workflows
Manual configuration Packaged with config
Copy-paste reuse Install and use
No standardization TASK-FORMAT-SPEC-V1

Squad Structure

A squad contains all the components needed for a specific domain:

./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/
│   └── my-agent.md         # Agent definitions
├── tasks/
│   └── my-task.md          # Task definitions (task-first!)
├── workflows/
│   └── my-workflow.yaml    # Multi-step workflows
├── checklists/
│   └── review-checklist.md # Validation checklists
├── templates/
│   └── report-template.md  # Document templates
├── tools/
│   └── custom-tool.js      # Custom tool integrations
├── scripts/
│   └── setup.js            # Utility scripts
└── data/
    └── reference-data.json # Static data files

Squad Manifest (squad.yaml)

Every squad requires a 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 <email@example.com>
license: MIT
slashPrefix: my # Command prefix for IDE

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

# Components declaration
components:
  agents:
    - my-agent.md
  tasks:
    - my-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

Creating a Squad

Using @squad-creator Agent

# Activate the squad creator agent
@squad-creator

# Option 1: Guided design (recommended)
*design-squad --docs ./docs/prd/my-project.md

# Option 2: Direct creation
*create-squad my-squad

# Option 3: From template
*create-squad my-squad --template etl

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 Workflow

  1. Collect Documentation - Provide PRDs, specs, requirements
  2. Domain Analysis - System extracts concepts, workflows, roles
  3. Agent Recommendations - Review suggested agents
  4. Task Recommendations - Review suggested tasks
  5. Generate Blueprint - Save to .squad-design.yaml
  6. Create from Blueprint - *create-squad my-squad --from-design

Available Squads

Official Squads

Squad Version Description Repository
etl-squad 2.0.0 Data collection and transformation aiox-squads/etl
creator-squad 1.0.0 Content generation utilities aiox-squads/creator

Distribution Levels

┌─────────────────────────────────────────────────────────────┐
│                    SQUAD DISTRIBUTION                        │
├─────────────────────────────────────────────────────────────┤
│  Level 1: LOCAL        --> ./squads/           (Private)    │
│  Level 2: AIOX-SQUADS  --> github.com/SynkraAI (Public)     │
│  Level 3: SYNKRA API   --> api.synkra.dev      (Marketplace)│
└─────────────────────────────────────────────────────────────┘

Installing Squads

# List available squads
aiox squads list

# Download from official repository
*download-squad etl-squad

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

# List local squads
*list-squads

Best Practices

1. Follow Task-First Architecture

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

User Request --> Task --> Agent Execution --> Output
                  │
             Workflow (if multi-step)

Tasks must follow TASK-FORMAT-SPECIFICATION-V1.

2. Use Config Inheritance Wisely

Mode Behavior
extend Add squad rules to core AIOX rules
override Replace core rules with squad rules
none Standalone configuration

3. Validate Before Publishing

# Validate squad structure
*validate-squad my-squad

# Strict mode (for CI/CD)
*validate-squad my-squad --strict

4. Document Your Squad

Include comprehensive documentation:

  • README.md with usage examples
  • Clear agent descriptions
  • Task input/output specifications
  • Workflow diagrams

5. Version Appropriately

Use semantic versioning:

  • Major (X.0.0): Breaking changes
  • Minor (0.X.0): New features, backward compatible
  • Patch (0.0.X): Bug fixes

Squad Commands Reference

Command Description
*create-squad {name} Create new squad with prompts
*create-squad {name} --template {type} Create from template
*create-squad {name} --from-design Create from design blueprint
*validate-squad {name} Validate squad structure
*list-squads List all local squads
*download-squad {name} Download from repository
*design-squad Design squad from documentation
*analyze-squad {name} Analyze squad structure
*extend-squad {name} Add components to squad
*publish-squad {path} Publish to repository

Next Steps

Related Documentation

FAQ

What's the difference between a Squad and legacy AIOX squad formats?

Squads are the standard format in AIOX 2.1+ with:

  • Task-first architecture
  • JSON Schema validation
  • Three-level distribution
  • Better tooling (@squad-creator)

Can I use Squads from different sources together?

Yes. The Squad Loader resolves from multiple sources. Local squads take precedence.

Can Squads depend on other Squads?

Yes, declare in dependencies.squads:

dependencies:
  squads:
    - etl-squad@^2.0.0

What's the minimum AIOX version for Squads?

Squads require AIOX 2.1.0+. Set in manifest:

aiox:
  minVersion: '2.1.0'

AIOX Squads: AI agent teams working with you

Version: 2.1.0 | Updated: 2026-01-28