> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  The AIOX framework works in **any domain** through natural language. Squads package domain expertise into reusable agent teams.
</Info>

## Squad Architecture

A squad is a complete package containing:

<CardGroup cols={2}>
  <Card title="Agents" icon="robot">
    Domain-specific AI personas with specialized knowledge
  </Card>

  <Card title="Tasks" icon="list-check">
    Executable workflows following TASK-FORMAT-SPEC-V1
  </Card>

  <Card title="Workflows" icon="diagram-project">
    Multi-step orchestrations linking tasks together
  </Card>

  <Card title="Config" icon="gear">
    Coding standards, tech stack, directory structure
  </Card>

  <Card title="Templates" icon="file-lines">
    Document generation templates for common outputs
  </Card>

  <Card title="Tools" icon="wrench">
    Custom integrations and utilities
  </Card>
</CardGroup>

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

```yaml theme={null}
# 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:
    - 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:

```mermaid theme={null}
graph LR
    A[User Request] --> B[Task]
    B --> C[Agent Execution]
    C --> D[Output]
    B --> E[Workflow]
    E --> C
```

Tasks must follow [TASK-FORMAT-SPECIFICATION-V1](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/docs/standards/TASK-FORMAT-SPECIFICATION-V1.md).

## Creating Squads

### Quick Start

<Steps>
  <Step title="Activate Squad Creator">
    ```bash theme={null}
    @squad-creator
    ```
  </Step>

  <Step title="Create Squad">
    ```bash theme={null}
    # Interactive creation
    *create-squad my-domain-squad

    # Or from template
    *create-squad my-squad --template etl
    ```
  </Step>

  <Step title="Validate">
    ```bash theme={null}
    *validate-squad my-domain-squad
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="Design from Documentation">
    ```bash theme={null}
    @squad-creator
    *design-squad --docs ./docs/prd/my-project.md
    ```
  </Step>

  <Step title="Review Recommendations">
    The system analyzes your docs and suggests:

    * Agents (with confidence scores)
    * Tasks (linked to agents)
    * Workflows (multi-step processes)
  </Step>

  <Step title="Create from Blueprint">
    ```bash theme={null}
    *create-squad my-squad --from-design
    ```
  </Step>
</Steps>

### Blueprint Format

```yaml theme={null}
# .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

```bash theme={null}
@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

<CodeGroup>
  ```bash Add Agent theme={null}
  @squad-creator
  *extend-squad my-squad --add agent --name analytics-agent
  ```

  ```bash Add Task theme={null}
  *extend-squad my-squad --add task --name process-data --agent lead-agent
  ```

  ```bash Add Workflow theme={null}
  *extend-squad my-squad --add workflow --name daily-processing
  ```

  ```bash Interactive Mode theme={null}
  *extend-squad my-squad
  # Guided prompts for component type and details
  ```
</CodeGroup>

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

<Tabs>
  <Tab title="extend">
    **Add squad rules to core AIOX rules**

    ```yaml theme={null}
    config:
      extends: extend
    ```

    * Core rules remain active
    * Squad rules supplement
    * Best for specialized extensions
  </Tab>

  <Tab title="override">
    **Replace core rules with squad rules**

    ```yaml theme={null}
    config:
      extends: override
    ```

    * Core rules disabled
    * Squad rules only
    * Best for completely different domains
  </Tab>

  <Tab title="none">
    **Standalone configuration**

    ```yaml theme={null}
    config:
      extends: none
    ```

    * No inheritance
    * Fully self-contained
    * Best for independent squads
  </Tab>
</Tabs>

## Validating Squads

### Basic Validation

```bash theme={null}
@squad-creator
*validate-squad my-squad
```

### Strict Mode (CI/CD)

```bash theme={null}
*validate-squad my-squad --strict
```

Treats warnings as errors.

### Validation Checks

<AccordionGroup>
  <Accordion title="Manifest Schema">
    Validates `squad.yaml` against JSON Schema:

    * Required fields present
    * Valid semver version
    * Correct AIOX type
  </Accordion>

  <Accordion title="Directory Structure">
    Ensures required folders exist:

    * `agents/`
    * `tasks/`
    * Config files referenced in manifest
  </Accordion>

  <Accordion title="Task Format">
    Verifies tasks follow TASK-FORMAT-SPEC-V1:

    * Required sections present
    * Valid YAML frontmatter
    * Agent linkage correct
  </Accordion>

  <Accordion title="Agent Definitions">
    Checks agents have required fields:

    * Name, role, commands
    * Valid persona structure
    * No circular dependencies
  </Accordion>
</AccordionGroup>

## Squad Distribution

Squads can be distributed at three levels:

```mermaid theme={null}
graph TD
    A[Level 1: Local] --> B[./squads/]
    C[Level 2: GitHub] --> D[github.com/SynkraAI/aiox-squads]
    E[Level 3: Marketplace] --> F[api.synkra.dev]
    
    B --> G[Private]
    D --> H[Public/Free]
    F --> I[Marketplace]
```

### Level 1: Local (Private)

Squads in `./squads/` are automatically available:

```bash theme={null}
*list-squads
```

### Level 2: GitHub (Public)

Publish to the community:

```bash theme={null}
@squad-creator

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

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

Creates a PR to [SynkraAI/aiox-squads](https://github.com/SynkraAI/aiox-squads).

### Level 3: Marketplace

Sync to Synkra API:

```bash theme={null}
# Set up authentication
export SYNKRA_API_TOKEN="your-token"

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

### Downloading Squads

```bash theme={null}
@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](https://github.com/SynkraAI/aiox-squads/tree/main/etl)         | 2.0.0   | Data collection and transformation |
| [creator-squad](https://github.com/SynkraAI/aiox-squads/tree/main/creator) | 1.0.0   | Content generation utilities       |
| [hybrid-ops](https://github.com/SynkraAI/aiox-hybrid-ops-pedro-valerio)    | 1.0.0   | Human-agent hybrid operations      |

## Migration from Legacy

Migrate old squad formats to the new standard:

<Steps>
  <Step title="Detect Legacy Format">
    Legacy squads use `config.yaml` instead of `squad.yaml`
  </Step>

  <Step title="Preview Migration">
    ```bash theme={null}
    @squad-creator
    *migrate-squad ./squads/legacy-squad --dry-run
    ```
  </Step>

  <Step title="Execute Migration">
    ```bash theme={null}
    *migrate-squad ./squads/legacy-squad
    ```

    Automatic backup created in `.backup/pre-migration-{timestamp}/`
  </Step>

  <Step title="Validate Result">
    ```bash theme={null}
    *validate-squad legacy-squad --strict
    ```
  </Step>
</Steps>

### Rollback

```bash theme={null}
# Restore from backup
cp -r ./squads/my-squad/.backup/pre-migration-*/. ./squads/my-squad/
```

## Programmatic Usage

### JavaScript API

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Creative Writing" icon="pen-fancy">
    Agents for plot development, character design, world-building
  </Card>

  <Card title="Business Strategy" icon="briefcase">
    Market analysis, competitor research, strategic planning
  </Card>

  <Card title="Education" icon="graduation-cap">
    Curriculum design, lesson planning, assessment creation
  </Card>

  <Card title="Healthcare" icon="heart-pulse">
    Patient care workflows, medical documentation, research
  </Card>

  <Card title="Legal" icon="gavel">
    Contract analysis, case research, document drafting
  </Card>

  <Card title="Entertainment" icon="film">
    Casting coordination, production planning, script analysis
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Start with Squad Designer">
    Let the system analyze your documentation and recommend structure:

    ```bash theme={null}
    *design-squad --docs ./docs/requirements.md
    ```
  </Accordion>

  <Accordion title="Use Task-First Design">
    Define what users want to accomplish (tasks) before creating agents.
  </Accordion>

  <Accordion title="Validate Early and Often">
    ```bash theme={null}
    *validate-squad my-squad --strict
    ```

    Run after every significant change.
  </Accordion>

  <Accordion title="Version Semantically">
    Follow semantic versioning:

    * MAJOR: Breaking changes
    * MINOR: New features
    * PATCH: Bug fixes
  </Accordion>

  <Accordion title="Document Thoroughly">
    Include comprehensive README with:

    * Purpose and use cases
    * Installation instructions
    * Example workflows
    * Troubleshooting
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Squad Not Found">
    ```bash theme={null}
    # Check squads directory
    ls ./squads/

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

    # List recognized squads
    @squad-creator
    *list-squads
    ```
  </Accordion>

  <Accordion title="Validation Errors">
    ```bash theme={null}
    # 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
  </Accordion>

  <Accordion title="YAML Parse Errors">
    ```bash theme={null}
    # 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
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Custom Agents" icon="robot" href="/advanced/custom-agents">
    Learn to create custom agent definitions
  </Card>

  <Card title="ADE System" icon="brain-circuit" href="/advanced/ade">
    Integrate ADE capabilities into squads
  </Card>

  <Card title="IDE Integration" icon="code" href="/advanced/ide-integration">
    Set up squads in your IDE
  </Card>

  <Card title="Agent Commands" icon="terminal" href="/agents/squad-creator">
    Full @squad-creator command reference
  </Card>
</CardGroup>