Squad Development Guide

EN | PT | ES

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

AIOX Squads: Equipes de AI agents trabalhando com você

What is a Squad?
Quick Start
Squad Architecture
Creating Squads
Squad Designer
Analyzing & Extending Squads (NEW)
Validating Squads
Publishing & Distribution
Migration from Legacy Format
Squad Loader & Resolution
Troubleshooting
FAQ

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 (TASK-FORMAT-SPEC-V1)
Workflows	Multi-step orchestrations
Config	Coding standards, tech stack, source tree
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 <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

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.

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 (basic, etl, agent-only)
`*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

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

Collect Documentation - Provide PRDs, specs, requirements
Domain Analysis - System extracts concepts, workflows, roles
Agent Recommendations - Review suggested agents
Task Recommendations - Review suggested tasks
Generate Blueprint - Save to .squad-design.yaml
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

After creating a squad, you can analyze its structure and extend it with new components using the *analyze-squad and *extend-squad commands.

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

Interactive Extend Flow

@squad-creator
*extend-squad my-squad

? What would you like to add?
  1. Agent - New agent persona
  2. Task - New task for an agent
  3. Workflow - Multi-step workflow
  4. Checklist - Validation checklist
  5. Template - Document template
  6. Tool - Custom tool (JavaScript)
  7. Script - Automation script
  8. Data - Static data file (YAML)

> 2

? Task name: process-data
? Which agent owns this task?
  1. lead-agent
  2. helper-agent
> 1
? Task description (optional): Process incoming data and generate output
? Link to story? (leave blank to skip): SQS-11

Creating task...
  Created: tasks/lead-agent-process-data.md
  Updated: squad.yaml (added to components.tasks)
  Validation: PASS

Next steps:
  1. Edit tasks/lead-agent-process-data.md
  2. Add entrada/saida/checklist
  3. Run: *validate-squad my-squad

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

Continuous Improvement Workflow

# 1. Analyze current state
*analyze-squad my-squad

# 2. Review suggestions and coverage metrics

# 3. Add missing components
*extend-squad my-squad --add task --name new-task --agent lead-agent
*extend-squad my-squad --add checklist --name quality-checklist

# 4. Re-analyze to verify improvement
*analyze-squad my-squad

# 5. Validate before use
*validate-squad my-squad

Programmatic Usage

const { SquadAnalyzer } = require('./.aiox-core/development/scripts/squad/squad-analyzer');
const { SquadExtender } = require('./.aiox-core/development/scripts/squad/squad-extender');

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

console.log('Coverage:', analysis.coverage);
console.log('Suggestions:', analysis.suggestions);

// Extend squad
const extender = new SquadExtender({ squadsPath: './squads' });
const result = await extender.addComponent('my-squad', {
  type: 'task',
  name: 'new-task',
  agentId: 'lead-agent',
  description: 'A new task',
  storyId: 'SQS-11',
});

console.log('Created:', result.filePath);
console.log('Manifest updated:', result.manifestUpdated);

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)

Programmatic Validation

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

const validator = new SquadValidator({ strict: false });
const result = await validator.validate('./squads/my-squad');

console.log(result);
// { valid: true, errors: [], warnings: [...], suggestions: [...] }

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

Migration from Legacy Format

Detecting Legacy Squads

Legacy squads use config.yaml instead of squad.yaml and may be missing:

aiox.type field
aiox.minVersion field
Task-first structure

Migration Command

@squad-creator

# Preview changes
*migrate-squad ./squads/legacy-squad --dry-run

# Execute migration
*migrate-squad ./squads/legacy-squad

# Verbose output
*migrate-squad ./squads/legacy-squad --verbose

Migration Steps

Backup - Creates .backup/pre-migration-{timestamp}/
Rename - config.yaml → squad.yaml
Add Fields - aiox.type, aiox.minVersion
Restructure - Organize into task-first layout
Validate - Run validation on migrated squad

Rollback

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

See Squad Migration Guide for detailed scenarios.

Squad Loader & Resolution

Resolution Chain

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}

Programmatic Usage

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

const loader = new SquadLoader({
  squadsPath: './squads',
  verbose: false
});

// Resolve squad path
const { path, manifestPath } = await loader.resolve('my-squad');

// Load manifest
const manifest = await loader.loadManifest('./squads/my-squad');

// List all local squads
const squads = await loader.listLocal();
// [{ name: 'my-squad', path: './squads/my-squad', manifestPath: '...' }]

Error Handling

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

try {
  await loader.resolve('non-existent');
} catch (error) {
  if (error instanceof SquadLoaderError) {
    console.error(`[${error.code}] ${error.message}`);
    console.log(`Suggestion: ${error.suggestion}`);
  }
}

Error Codes

Code	Description	Solution
`SQUAD_NOT_FOUND`	Squad directory not found	Create with `*create-squad`
`MANIFEST_NOT_FOUND`	No manifest file	Create `squad.yaml`
`YAML_PARSE_ERROR`	Invalid YAML syntax	Use YAML linter
`PERMISSION_DENIED`	File permission error	Check `chmod 644`

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 online or with:
npx js-yaml ./squads/my-squad/squad.yaml

Common issues:

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

Migration Failures

# Check backup exists
ls ./squads/my-squad/.backup/

# Restore and retry
cp -r ./squads/my-squad/.backup/pre-migration-*/. ./squads/my-squad/
*migrate-squad ./squads/my-squad --verbose

Publishing Errors

# Check GitHub authentication
gh auth status

# Check squad validation
*validate-squad my-squad --strict

# Check for naming conflicts
*download-squad --list | grep my-squad

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.

How do I update a published Squad?

Update version in squad.yaml (semver)
Run *validate-squad --strict
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: *sync-squad-synkra my-squad --private

What's the minimum AIOX version for Squads?

Squads require AIOX 2.1.0+. Set in manifest:

aiox:
  minVersion: "2.1.0"

How do I test my Squad before publishing?

# 1. Validate structure
*validate-squad my-squad --strict

# 2. Test locally
@my-agent  # Activate squad agent
*my-task   # Run squad task

# 3. Run squad tests (if defined)
npm test -- tests/squads/my-squad/

Related Resources

Getting Help

AIOX Squads: Equipes de AI agents trabalhando com você

Version: 2.1.0 | Updated: 2025-12-26 | Stories: SQS-8, SQS-11

Uh oh!

FilesExpand file tree

squads-guide.md

Latest commit

History

squads-guide.md

File metadata and controls

Squad Development Guide

Table of Contents

What is a Squad?

Distribution Levels

Official Squads

Quick Start

Prerequisites

Option 1: Guided Design (Recommended)

Option 2: Direct Creation

Squad Architecture

Directory Structure

Squad Manifest (squad.yaml)

Task-First Architecture

Creating Squads

Using @squad-creator Agent

Available Commands

Templates

Config Inheritance Modes

Squad Designer

Usage

Workflow

Blueprint Format

Analyzing & Extending Squads

Analyzing Squads

Analysis Output

Extending Squads

Interactive Extend Flow

Component Types

Continuous Improvement Workflow

Programmatic Usage

Validating Squads

Basic Validation

Strict Mode (for CI/CD)

Validation Checks

Validation Output

Programmatic Validation

Publishing & Distribution

Level 1: Local (Private)

Level 2: aiox-squads Repository (Public)

Level 3: Synkra Marketplace

Downloading Squads

Migration from Legacy Format

Detecting Legacy Squads

Migration Command

Migration Steps

Rollback

Squad Loader & Resolution

Resolution Chain

Programmatic Usage

Error Handling

Error Codes

Troubleshooting

"Squad not found"

Validation Errors

YAML Parse Errors

Migration Failures

Publishing Errors

FAQ

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

Can I use Squads from different sources together?

How do I update a published Squad?

Can Squads depend on other Squads?

How do I make a Squad private?

What's the minimum AIOX version for Squads?

How do I test my Squad before publishing?

Related Resources

Getting Help