Skip to content

user-guide.md

Latest commit

 

History

History
487 lines (342 loc) · 12.3 KB

user-guide.md

File metadata and controls

487 lines (342 loc) · 12.3 KB

AIOX User Guide

EN

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

Version: 2.1.0 Last Updated: 2026-01-28

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

Agent Context

When an agent is active:

  • Follow that agent's specific persona and expertise
  • Use the agent's designated workflow patterns
  • Maintain the agent's perspective throughout the interaction

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

How visibility works:

commands:
  - name: help
    visibility: [full, quick, key]  # Always shown
    description: "Show available commands"

  - name: create-prd
    visibility: [full, quick]       # Shown in quick reference
    description: "Create product requirements"

  - name: session-info
    visibility: [full]              # Only in full help
    description: "Show session details"

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 story creation
*develop @dev Use @dev for implementation
*review @qa Use @qa for code review

See the Command Authority Matrix for the complete mapping.

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

Official Squads

Squad Description
etl-squad Data collection and transformation
creator-squad Content generation utilities

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

Troubleshooting

Common Issues

Agent won't activate

# Check agent exists
ls .aiox-core/development/agents/

# Verify configuration
aiox doctor

Task execution fails

# Check task definition
cat .aiox-core/development/tasks/{task-name}.md

# Run with verbose output
*task {name} --verbose

Memory/context issues

# Clear cache
rm -rf .aiox-core/core/cache/*

# Rebuild index
aiox rebuild

Getting Help

Next Steps

Learning Path

  1. Quick Start - Follow this guide to get up and running
  2. Agent Reference - Learn about each agent's capabilities: Agent Reference Guide
  3. Architecture - Understand the system: Architecture Overview
  4. Squads - Extend functionality: Squads Guide

Advanced Topics

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}

Related Documentation

Synkra AIOX User Guide v4.2.11