Skip to main content

​
10-Minute Quick Path

Use this exact flow if you are new:

​
Step 1: Install AIOX

# New project
npx aiox-core init my-first-project
cd my-first-project

# Existing project
# cd existing-project
# npx aiox-core install

​
Step 2: Pick Your IDE Activation Path

  • Claude Code: /agent-name
  • Gemini CLI: /aiox-menu then /aiox-<agent>
  • Codex CLI: /skills then aiox-<agent-id>
  • Cursor/Copilot/AntiGravity: follow constraints in IDE integration docs

​
Step 3: Validate First Value

First value is achieved when all 3 conditions are true:
  1. You activate one AIOX agent
  2. You receive a valid greeting/activation response
  3. You run one starter command (*help or equivalent) and get useful output
PASS rule: Complete all 3 conditions in ≤ 10 minutes.

​
Installation

​
Prerequisites

  • Node.js version 18.0.0 or higher (v20+ recommended)
  • npm version 9.0.0 or higher
  • Git (optional, but recommended)

​
Quick Installation

# Create a new project
npx aiox-core init my-first-project

# Navigate to your project
cd my-first-project

# Start using AIOX agents in your IDE
# (see Step 2 above for IDE-specific activation)

​
Installation Options

# 1. Create new project with custom template
npx aiox-core init my-project --template enterprise

# 2. Install in existing project
cd existing-project
npx aiox-core install

# 3. Force installation in non-empty directory
npx aiox-core init my-project --force

# 4. Skip dependency installation (manual install later)
npx aiox-core init my-project --skip-install

​
Project Structure

After installation, your project will include: 
my-first-project/
├── .aiox-core/                 # AIOX framework core
│   ├── core/                   # Orchestration, memory, config
│   ├── data/                   # Knowledge base, entity registry
│   ├── development/            # Agents, tasks, templates, scripts
│   └── infrastructure/         # CI/CD templates, validation scripts
├── .claude/                    # Claude Code integration (if enabled)
├── .codex/                     # Codex CLI integration (if enabled)
├── .gemini/                    # Gemini CLI integration (if enabled)
├── docs/                       # Documentation
│   └── stories/                # Development stories
├── packages/                   # Shared packages
├── tests/                      # Test suites
└── package.json                # Project dependencies

​
Configuration

AIOX configuration lives in .aiox-core/core/config/. The installer handles initial setup.

​
Verify Installation

npx aiox-core doctor

​
Configure AI Provider

Create a .env file in your project root: 
# For Anthropic (Claude)
ANTHROPIC_API_KEY=your-api-key-here

# OR for OpenAI (GPT)
OPENAI_API_KEY=your-api-key-here

# Framework settings
NODE_ENV=development
AIOX_DEBUG=false

​
Basic Commands

​
Agent Activation

AIOX agents are activated through your IDE. Once activated, agents respond to commands prefixed with *: 
# Universal commands (work in any agent)
*help                    # Show available commands for this agent
*guide                   # Show detailed usage guide
*session-info            # Display current session details
*exit                    # Exit agent mode

# Agent-specific examples
@dev *help               # Developer agent commands
@qa *review STORY-42     # QA agent reviews a story
@pm *create-epic         # PM agent creates an epic
@sm *draft               # Scrum Master drafts a story

​
Available Agents

AgentNameFocus
@devDexCode implementation, bug fixes
@qaQuinnTesting, quality gates, code review
@architectAriaSystem design, technical decisions
@pmBobPRDs, strategy, roadmap
@poPaxBacklog, story validation
@smRiverStory creation, sprint planning
@analystAlexResearch, competitive analysis
@data-engineerDaraDatabase design, migrations
@ux-design-expertUmaUI/UX design, accessibility
@devopsGageGit operations, CI/CD, deployments
@aiox-master-Framework orchestration

​
Your First Workflow

Let’s create a simple feature using the story-driven development process:

​
1. Create a Story

# Activate the Scrum Master
@sm

# Create a new story
*draft
The SM will guide you through creating a development story with:
  • Story ID and title
  • Description
  • Acceptance criteria
  • Tasks

​
2. Validate the Story

# Activate the Product Owner
@po

# Validate the story
*validate-story-draft
The PO runs a 10-point validation checklist.

​
3. Implement the Feature

# Activate the Developer
@dev

# Start implementation
*develop
Dex will:
  • Read the story file
  • Implement the code
  • Write tests
  • Update progress checkboxes

​
4. Review and QA

# Activate QA
@qa

# Review the implementation
*review STORY-ID
Quinn will:
  • Run quality gates
  • Check test coverage
  • Validate acceptance criteria

​
5. Push Changes (Optional)

# Activate DevOps
@devops

# Push to remote
*push

​
IDE Compatibility

Not all IDEs support AIOX features equally.
IDE/CLIStatusActivation Method
Claude CodeWorks/agent-name commands
Gemini CLIWorks/aiox-menu then /aiox-<agent>
Codex CLILimited/skills then aiox-<agent-id>
CursorLimited@agent + synced rules
GitHub CopilotLimitedchat modes + repo instructions
AntiGravityLimitedworkflow-driven activation
  • Works: Fully recommended for new users
  • Limited: Usable with documented workarounds

​
Troubleshooting

​
Installation Issues

# Check Node.js version
node --version  # Should be >= 18.0.0

# Run diagnostics
npx aiox-core doctor

# Auto-fix common issues
npx aiox-core doctor --fix

​
Agent Not Responding

  1. Verify your IDE is supported
  2. Run npm run sync:ide to refresh agent files
  3. Restart your IDE/CLI session

​
Sync Issues

# Preview what would change
npm run sync:ide -- --dry-run

# Force re-sync
npm run sync:ide

# Validate after sync
npm run validate:parity

​
Common Workflows

​
Typical Development Flow

1. @pm creates a PRD          → *create-epic
2. @sm drafts stories          → *draft
3. @po validates stories       → *validate-story-draft
4. @dev implements             → (works from story file)
5. @qa reviews                 → *review STORY-ID
6. @devops pushes              → *push
7. @po closes story            → *close-story STORY-ID

​
Quick Bug Fix

1. @sm creates bug story       → *draft
2. @dev fixes bug              → *develop
3. @qa validates fix           → *review STORY-ID
4. @devops pushes              → *push

​
Architecture Decision

1. @architect analyzes         → *analyze-impact
2. @architect proposes         → *create-doc
3. @qa reviews proposal        → *review-proposal
4. @dev implements             → *develop

​
Next Steps

​
Immediate Actions

  1. Create your first story - Practice the story-driven workflow
  2. Explore agents - Try activating different agents and using their commands
  3. Run quality gates - See the 3-layer quality system in action

​
Learning Resources

  • User Guide - Complete workflow documentation
  • Development Workflow - In-depth guide to story-driven development
  • Git Workflow - Learn the multi-layer validation system
  • Squads Guide - Extend AIOX to any domain

​
Advanced Topics

  • Quality Gates configuration
  • Custom workflow creation
  • Squad development
  • Multi-repo strategies

Build docs developers (and LLMs) love

Get started for freeTalk to us