Your First Project

Step-by-step guide to creating and working with your first AIOX project

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

Agent	Name	Focus
@dev	Dex	Code implementation, bug fixes
@qa	Quinn	Testing, quality gates, code review
@architect	Aria	System design, technical decisions
@pm	Bob	PRDs, strategy, roadmap
@po	Pax	Backlog, story validation
@sm	River	Story creation, sprint planning
@analyst	Alex	Research, competitive analysis
@data-engineer	Dara	Database design, migrations
@ux-design-expert	Uma	UI/UX design, accessibility
@devops	Gage	Git 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/CLI	Status	Activation Method
Claude Code	Works	/agent-name commands
Gemini CLI	Works	/aiox-menu then /aiox-<agent>
Codex CLI	Limited	/skills then aiox-<agent-id>
Cursor	Limited	@agent + synced rules
GitHub Copilot	Limited	chat modes + repo instructions
AntiGravity	Limited	workflow-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