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

# User Guide

> Complete guide for using Synkra AIOX - the AI-Orchestrated System for Full Stack Development

## Quick Start

### Prerequisites

Before using AIOX, ensure you have:

* **Node.js** version 18.0.0 or higher
* **npm** version 8.0.0 or higher
* **Git** for version control
* An AI provider API key (Anthropic, OpenAI, or compatible)

### Installation

```bash theme={null}
# New project (Greenfield)
npx aiox-core init my-project

# Existing project (Brownfield)
cd existing-project
npx aiox-core install
```

### First Steps

```bash theme={null}
# Navigate to your project
cd my-project

# List available agents
aiox agents list

# Activate an agent
@dev

# Get help
*help
```

## Core Concepts

### Philosophy

> **"Structure is Sacred. Tone is Flexible."**

AIOX provides orchestrated structure while allowing flexibility in communication. This means:

* **Fixed:** Template positions, section order, metric formats, file structure, workflows
* **Flexible:** Status messages, vocabulary choices, emoji usage, personality, tone

### The AIOX Difference

| Traditional AI Dev            | AIOX                                    |
| ----------------------------- | --------------------------------------- |
| Uncoordinated agents          | 11 specialized agents with clear roles  |
| Inconsistent results          | Structured workflows with quality gates |
| Context lost between sessions | Persistent memory and learning          |
| Reinventing the wheel         | Reusable tasks, workflows, and squads   |

## Agents

AIOX includes 11 specialized agents, each with a distinct role and personality:

| Agent     | ID               | Archetype    | Responsibility          |
| --------- | ---------------- | ------------ | ----------------------- |
| **Dex**   | `@dev`           | Builder      | Code implementation     |
| **Quinn** | `@qa`            | Guardian     | Quality assurance       |
| **Aria**  | `@architect`     | Architect    | Technical architecture  |
| **Nova**  | `@po`            | Visionary    | Product backlog         |
| **Kai**   | `@pm`            | Balancer     | Product strategy        |
| **River** | `@sm`            | Facilitator  | Process facilitation    |
| **Zara**  | `@analyst`       | Explorer     | Business analysis       |
| **Dara**  | `@data-engineer` | Architect    | Data engineering        |
| **Felix** | `@devops`        | Optimizer    | CI/CD and operations    |
| **Uma**   | `@ux-expert`     | Creator      | User experience         |
| **Pax**   | `@aiox-master`   | Orchestrator | Framework orchestration |

### Agent Activation

```bash theme={null}
# Activate an agent using @ syntax
@dev                # Activate Dex (Developer)
@qa                 # Activate Quinn (QA)
@architect          # Activate Aria (Architect)
@aiox-master        # Activate Pax (Orchestrator)

# Agent commands use * prefix
*help               # Show available commands
*task <name>        # Execute specific task
*exit               # Deactivate agent
```

### Command Visibility Levels

Agent commands use visibility levels to control when they appear:

| Level   | Name  | Description                                 |
| ------- | ----- | ------------------------------------------- |
| `key`   | Key   | Critical commands shown in minimal greeting |
| `quick` | Quick | Essential commands shown in quick reference |
| `full`  | Full  | All commands shown in `*help` output        |

**Command Authority:**

Each command has exactly one authoritative agent owner. When multiple agents might handle similar tasks:

| Command        | Owner | Others Should...    |
| -------------- | ----- | ------------------- |
| `*create-prd`  | @pm   | Delegate to @pm     |
| `*create-epic` | @pm   | Delegate to @pm     |
| `*draft`       | @sm   | Use @sm for stories |
| `*develop`     | @dev  | Use @dev for code   |
| `*review`      | @qa   | Use @qa for review  |

## Tasks

Tasks are the primary entry point in AIOX. Everything is a task.

### Task-First Architecture

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

### Executing Tasks

```bash theme={null}
# Execute a specific task
*task develop-story --story=1.1

# List available tasks
aiox tasks list

# Get task help
*task --help
```

### Task Categories

| Category          | Examples                                |
| ----------------- | --------------------------------------- |
| **Development**   | develop-story, code-review, refactor    |
| **Quality**       | run-tests, validate-code, security-scan |
| **Documentation** | generate-docs, update-readme            |
| **Workflow**      | create-story, manage-sprint             |

## Workflows

Workflows orchestrate multiple tasks and agents for complex operations.

### Available Workflows

| Workflow                 | Use Case                | Agents Involved   |
| ------------------------ | ----------------------- | ----------------- |
| `greenfield-fullstack`   | New full-stack project  | All agents        |
| `brownfield-integration` | Add AIOX to existing    | dev, architect    |
| `fork-join`              | Parallel task execution | Multiple          |
| `organizer-worker`       | Delegated execution     | po, dev           |
| `data-pipeline`          | ETL workflows           | data-engineer, qa |

### Executing Workflows

```bash theme={null}
# Start a workflow
aiox workflow greenfield-fullstack

# With parameters
aiox workflow brownfield-integration --target=./existing-project
```

## Squads

Squads are modular teams of AI agents that extend AIOX functionality.

### What is a Squad?

A 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

```
Level 1: LOCAL        --> ./squads/           (Private)
Level 2: AIOX-SQUADS  --> github.com/SynkraAI (Public/Free)
Level 3: SYNKRA API   --> api.synkra.dev      (Marketplace)
```

### Using Squads

```bash theme={null}
# List available squads
aiox squads list

# Download a squad
aiox squads download etl-squad

# Create your own squad
@squad-creator
*create-squad my-custom-squad
```

## Basic Usage

### Project Structure

```
my-project/
├── .aiox-core/                # Framework configuration
│   ├── development/agents/    # Agent definitions
│   ├── development/tasks/     # Task workflows
│   ├── product/templates/     # Document templates
│   └── product/checklists/    # Validation checklists
├── docs/
│   ├── stories/               # Development stories
│   ├── architecture/          # System architecture
│   └── guides/                # User guides
├── squads/                    # Local squads
└── src/                       # Application source code
```

### Common Commands

```bash theme={null}
# AIOX Master Commands
*help                # Show available commands
*create-story        # Create new story
*task {name}         # Execute specific task
*workflow {name}     # Run workflow

# Development Commands
npm run dev          # Start development
npm test             # Run tests
npm run lint         # Check code style
npm run build        # Build project
```

### Story-Driven Development

1. **Create a story** - Use `*create-story` to define requirements
2. **Work from stories** - All development starts with a story in `docs/stories/`
3. **Update progress** - Mark checkboxes as tasks complete: `[ ]` --> `[x]`
4. **Track changes** - Maintain the File List section in the story
5. **Follow criteria** - Implement exactly what the acceptance criteria specify

## Configuration

### Main Configuration File

The primary configuration is in `.aiox-core/core/config/`:

```yaml theme={null}
# aiox.config.yaml
version: 2.1.0
projectName: my-project

features:
  - agents
  - tasks
  - workflows
  - squads
  - quality-gates

ai:
  provider: anthropic
  model: claude-3-opus

environment: development
```

### Environment Variables

```bash theme={null}
# AI Provider Configuration
ANTHROPIC_API_KEY=your-anthropic-api-key
# or
OPENAI_API_KEY=your-openai-api-key

# Framework Settings
NODE_ENV=development
AIOX_DEBUG=false
```

### IDE Integration

AIOX supports multiple IDEs. Configuration is synchronized across:

* Claude Code (`.claude/`)
* Cursor (`.cursor/`)
* VS Code (`.vscode/`)

```bash theme={null}
# Sync agents to your IDE
npm run sync:ide
```

## Best Practices

### 1. Start with Stories

Always create a story before implementing features:

```bash theme={null}
@aiox-master
*create-story
```

### 2. Use the Right Agent

Choose the appropriate agent for each task:

| Task                | Agent      |
| ------------------- | ---------- |
| Write code          | @dev       |
| Review code         | @qa        |
| Design system       | @architect |
| Define requirements | @po        |

### 3. Follow Quality Gates

AIOX implements 3-layer quality gates:

1. **Layer 1 (Local)**: Pre-commit hooks, linting, type checking
2. **Layer 2 (CI/CD)**: Automated tests, CodeRabbit review
3. **Layer 3 (Human)**: Architecture review, final approval

### 4. Keep Context

Maintain context through sessions by:

* Using story-driven development
* Updating progress checkboxes
* Documenting decisions in stories

### 5. Leverage Squads

Don't reinvent the wheel - check for existing squads:

```bash theme={null}
aiox squads search {keyword}
```

## Next Steps

### Learning Path

1. **Quick Start** - Follow this guide to get up and running
2. **First Project** - Create your first AIOX project
3. **Development Workflow** - Learn the story-driven development process
4. **Squads** - Extend functionality with squads

### Advanced Topics

* Quality Gates Guide
* Multi-Repo Strategy
* MCP Integration
* IDE Integration