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

# New project (Greenfield)
npx aiox-core init my-project

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

First Steps

# 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

# 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

# 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

# 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

# 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

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

# 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

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

# Sync agents to your IDE
npm run sync:ide

Best Practices

1. Start with Stories

Always create a story before implementing features:

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

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