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

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

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

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

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

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

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

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

### Analyzing Squads

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

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

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

### Strict Mode (for CI/CD)

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

```bash theme={null}
# List local squads
*list-squads
```

### Level 2: aiox-squads Repository (Public)

```bash theme={null}
@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](https://github.com/SynkraAI/aiox-squads).

### Level 3: Synkra Marketplace

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

## Using Squads

### Activating Squad Agents

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

```bash theme={null}
# Check squads directory exists
ls ./squads/

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

# Check resolution
@squad-creator
*list-squads
```

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

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

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

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