Skip to content

Latest commit

 

History

History
311 lines (221 loc) · 8.99 KB

getting-started.md

File metadata and controls

311 lines (221 loc) · 8.99 KB

Getting Started with Synkra AIOX

EN | PT | ES

Welcome to Synkra AIOX. This guide is optimized for first-value in 10 minutes.

Table of Contents

  1. 10-Minute Quick Path
  2. Installation
  3. Your First Project
  4. Basic Commands
  5. IDE Compatibility
  6. Brownfield: Existing Projects
  7. Advanced Path
  8. Troubleshooting
  9. Next Steps

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 docs/ide-integration.md

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

Your First Project

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. To verify your installation:

npx aiox-core doctor

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, refactoring
@qa Quinn Testing, quality gates, code review
@architect Aria System design, technical decisions
@pm Bob PRDs, strategy, roadmap
@po Pax Backlog, story validation, prioritization
@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

Typical Workflow

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 (only agent with push authority)
7. @po closes story            → *close-story STORY-ID

IDE Compatibility

Not all IDEs support AIOX features equally. See the full comparison at docs/ide-integration.md.

Summary:

IDE/CLI Overall Status How to Activate
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.

Brownfield: Existing Projects

Already have a codebase? AIOX handles brownfield projects with a dedicated workflow.

Quick Brownfield Setup

# Navigate to your existing project
cd my-existing-project

# Install AIOX (non-destructive, preserves your config)
npx aiox-core install

# Run doctor to verify compatibility
npx aiox-core doctor

What Happens on First Run

When you first activate an AIOX agent in an existing project:

  1. Detection: AIOX detects code but no AIOX docs
  2. Offer: "I can analyze your codebase. This takes 4-8 hours."
  3. Discovery: Multi-agent technical debt assessment (optional)
  4. Output: System architecture docs + technical debt report

Brownfield Workflow Options

Your Situation Recommended Workflow
Add major feature to existing project @pm → *create-doc brownfield-prd
Audit legacy codebase brownfield-discovery.yaml (full workflow)
Quick enhancement @pm → *brownfield-create-epic
Single bug fix @pm → *brownfield-create-story

Safety Guarantees

  • Non-destructive: AIOX creates files, never overwrites existing
  • Rollback: git checkout HEAD~1 -- . restores pre-AIOX state
  • Config preservation: Your .eslintrc, tsconfig.json, etc. stay intact

Resources

Advanced Path

For experienced users who want to go deeper:

Sync and Validation

# Sync agents to all configured IDEs
npm run sync:ide

# Validate cross-IDE parity
npm run validate:parity

# Run all quality checks
npm run lint && npm run typecheck && npm test

Story-Driven Development

All AIOX development follows stories in docs/stories/. Each story contains:

  • Acceptance criteria with checkboxes
  • Tasks mapped to specific ACs
  • CodeRabbit integration for automated review
  • Quality gate assignments

See the User Guide for the complete workflow.

Squad Expansions

Squads extend AIOX beyond software development into any domain. See Squads Guide.

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 (see IDE Compatibility).
  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

Next Steps

Synkra AIOX Getting Started Guide v4.2.11