Squads Guide

Complete guide for creating, validating, publishing, and managing Squads in AIOX

What is a Squad?

Squads are modular teams of AI agents that extend AIOX functionality. Each squad is a self-contained package containing:

Component	Purpose
Agents	Domain-specific AI personas
Tasks	Executable workflows
Workflows	Multi-step orchestrations
Config	Coding standards, tech stack
Templates	Document generation templates
Tools	Custom tool integrations

Distribution Levels

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

Official Squads

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

Quick Start

Prerequisites

• Node.js 18+
• AIOX project initialized (.aiox-core/ exists)
• Git for version control

Option 1: Guided Design (Recommended)

# Activate squad-creator agent
@squad-creator

# Design squad from your documentation
*design-squad --docs ./docs/prd/my-project.md

# Review recommendations, then create
*create-squad my-squad --from-design

# Validate before use
*validate-squad my-squad

Option 2: Direct Creation

@squad-creator

# Create with interactive prompts
*create-squad my-domain-squad

# Or specify template
*create-squad my-squad --template etl

Squad Architecture

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/
│   └── 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)

# 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:
    - 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

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)

Creating Squads

Using @squad-creator Agent

# Activate the agent
@squad-creator

# View all commands
*help

Available Commands

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
*design-squad	Design squad from documentation
*analyze-squad {name}	Analyze squad structure
*extend-squad {name}	Add components to existing squad

Templates

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

Config Inheritance Modes

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

Squad Designer

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

Usage

@squad-creator

# Interactive design
*design-squad

# Design from specific files
*design-squad --docs ./docs/prd/requirements.md ./docs/specs/api.md

# Specify domain context
*design-squad --domain casting --docs ./docs/

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

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

Analyzing Squads

@squad-creator

# Basic analysis
*analyze-squad my-squad

# Include file details
*analyze-squad my-squad --verbose

# Save to markdown file
*analyze-squad my-squad --format markdown

# Output as JSON
*analyze-squad my-squad --format json

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
  checklists/ (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 (currently has only 1)
  2. [*] Create workflows for common sequences
  3. [-] Add checklists for validation

Next: *extend-squad my-squad

Extending Squads

Add new components to existing squads with automatic manifest updates:

@squad-creator

# Interactive mode (guided)
*extend-squad my-squad

# Direct mode - Add agent
*extend-squad my-squad --add agent --name analytics-agent

# Add task with agent linkage
*extend-squad my-squad --add task --name process-data --agent lead-agent

# Add workflow with story reference
*extend-squad my-squad --add workflow --name daily-processing --story SQS-11

# Add all component types
*extend-squad my-squad --add template --name report-template
*extend-squad my-squad --add tool --name data-validator
*extend-squad my-squad --add checklist --name quality-checklist
*extend-squad my-squad --add script --name migration-helper
*extend-squad my-squad --add data --name config-data

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

Validating Squads

Basic Validation

@squad-creator
*validate-squad my-squad

Strict Mode (for CI/CD)

*validate-squad my-squad --strict

Treats warnings as errors.

Validation Checks

Check	Description
Manifest Schema	squad.yaml against JSON Schema
Directory Structure	Required folders exist
Task Format	Tasks follow TASK-FORMAT-SPEC-V1
Agent Definitions	Agents have required fields
Dependencies	Referenced files exist

Validation Output

Validating squad: my-squad
═══════════════════════════

✅ Manifest: Valid
✅ Structure: Complete
✅ Tasks: 3/3 valid
✅ Agents: 2/2 valid
⚠️ Warnings:
   - README.md is minimal (consider expanding)

Summary: VALID (3 warnings)

Publishing & Distribution

Level 1: Local (Private)

Squads in ./squads/ are automatically available to your project.

# List local squads
*list-squads

Level 2: aiox-squads Repository (Public)

@squad-creator

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

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

This creates a PR to SynkraAI/aiox-squads.

Level 3: Synkra Marketplace

# 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

Using Squads

Activating Squad Agents

# Activate a squad agent
@my-squad-agent

# Use squad commands
*my-squad-task

Squad Resolution

The Squad Loader resolves squads in this order:

1. Local     → ./squads/{name}/
2. npm       → node_modules/@aiox-squads/{name}/
3. Workspace → ../{name}/ (monorepo)
4. Registry  → api.synkra.dev/squads/{name}

Best Practices

Squad Design

1. Keep squads focused - One domain per squad
2. Define clear agents - Each agent has distinct responsibilities
3. Create comprehensive tasks - Cover all common workflows
4. Document thoroughly - Include README and examples

Squad Creation

1. Start with design - Use *design-squad for better planning
2. Validate early - Run *validate-squad frequently
3. Test locally - Use squad before publishing
4. Version semantically - Follow semver (x.y.z)

Squad Usage

1. Check compatibility - Verify aiox.minVersion
2. Review dependencies - Install required packages
3. Read documentation - Check README.md
4. Report issues - Help improve community squads

Troubleshooting

”Squad not found”

# Check squads directory exists
ls ./squads/

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

# Check resolution
@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

FAQ

What’s the difference between a Squad and AIOX core?

Squads are domain-specific extensions. AIOX core is the framework for general software development.

Can I use Squads from different sources together?

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

How do I update a published Squad?

1. Update version in squad.yaml (semver)
2. Run *validate-squad --strict
3. Re-publish: *publish-squad or *sync-squad-synkra

Can Squads depend on other Squads?

Yes, declare in dependencies.squads:

dependencies:
  squads:
    - etl-squad@^2.0.0

How do I make a Squad private?

• Level 1: Keep in ./squads/ (not committed) - add to .gitignore
• Level 3: Sync with --private flag

Next Steps

• Creating Squads - Step-by-step squad creation guide
• Custom Workflows - Build workflows for your squad
• Task Format Spec - Learn the task format specification
• Publishing Guide - Share your squad with the community