Synkra AIOX FAQ

🌐 EN | PT | ES

Version: 2.1.0 Last Updated: 2025-01-24

Installation Questions
Updates & Maintenance
Offline & Air-Gapped Usage
IDE & Configuration
Agents & Workflows
Squads
Advanced Usage

Installation Questions

Q1: Why npx instead of npm install -g?

Answer: We recommend npx aiox-core install over global installation for several reasons:

Always Latest Version: npx fetches the latest version automatically
No Global Pollution: Doesn't add to your global npm packages
Project Isolation: Each project can have its own version
No Permission Issues: Avoids common global npm permission problems
CI/CD Friendly: Works seamlessly in automated pipelines

If you prefer global installation:

npm install -g aiox-core
aiox-core install

Q2: What are the system requirements?

Answer:

Component	Minimum	Recommended
Node.js	18.0.0	20.x LTS
npm	9.0.0	10.x
Disk Space	100 MB	500 MB
RAM	2 GB	8 GB
OS	Windows 10, macOS 12, Ubuntu 20.04	Latest versions

Check your system:

node --version  # Should be 18+
npm --version   # Should be 9+

Q3: Can I install AIOX in an existing project?

Answer: Yes! AIOX is designed for both greenfield and brownfield projects.

For existing projects:

cd /path/to/existing-project
npx aiox-core install

The installer will:

Create .aiox-core/ directory (framework files)
Create IDE configuration (.claude/, .cursor/, etc.)
NOT modify your existing source code
NOT overwrite existing documentation unless you choose to

Important: If you have an existing .claude/ or .cursor/ directory, the installer will ask before modifying.

Q4: How long does installation take?

Answer:

Scenario	Time
First-time install	2-5 minutes
Update existing	1-2 minutes
Starter squad only	30-60 seconds

Factors affecting installation time:

Internet connection speed
npm cache status
Number of IDEs selected
Starter squads selected

Q5: What files does AIOX create in my project?

Answer: AIOX creates the following structure:

your-project/
├── .aiox-core/                 # Framework core (200+ files)
│   ├── agents/                 # 11+ agent definitions
│   ├── tasks/                  # 60+ task workflows
│   ├── templates/              # 20+ document templates
│   ├── checklists/             # Validation checklists
│   ├── scripts/                # Utility scripts
│   └── core-config.yaml        # Framework configuration
│
├── .claude/                    # Claude Code (if selected)
│   └── commands/AIOX/agents/   # Agent slash commands
│
├── .cursor/                    # Cursor (if selected)
│   └── rules/                  # Agent rules
│
├── docs/                       # Documentation structure
│   ├── stories/                # Development stories
│   ├── architecture/           # Architecture docs
│   └── prd/                    # Product requirements
│
└── Squads/            # (if installed)
    └── hybrid-ops/             # HybridOps pack

Updates & Maintenance

Q6: How do I update AIOX to the latest version?

Answer:

# Update via npx (recommended)
npx aiox-core update

# Or reinstall latest
npx aiox-core install --force-upgrade

# Check current version
npx aiox-core status

What gets updated:

.aiox-core/ files (agents, tasks, templates)
IDE configurations
Starter squads (if installed)

What is preserved:

Your custom modifications in core-config.yaml
Your documentation (docs/)
Your source code

Q7: How often should I update?

Answer: We recommend:

Update Type	Frequency	Command
Security patches	Immediately	`npx aiox-core update`
Minor updates	Monthly	`npx aiox-core update`
Major versions	Quarterly	Review changelog first

Check for updates:

npm show aiox-core version
npx aiox-core status

Q8: Can I rollback to a previous version?

Answer: Yes, several options:

Option 1: Reinstall specific version

npx aiox-core@1.1.0 install --force-upgrade

Option 2: Use Git to restore

# If .aiox-core is tracked in git
git checkout HEAD~1 -- .aiox-core/

Option 3: Restore from backup

# Installer creates backups
mv .aiox-core .aiox-core.failed
mv .aiox-core.backup .aiox-core

Offline & Air-Gapped Usage

Q9: Can I use AIOX without internet?

Answer: Yes, with some preparation:

Initial setup (requires internet):

# Install once with internet
npx aiox-core install

# Package for offline use
tar -czvf aiox-offline.tar.gz .aiox-core/ .claude/ .cursor/

On air-gapped machine:

# Extract the package
tar -xzvf aiox-offline.tar.gz

# AIOX agents work without internet
# (They don't require external API calls)

Limitations without internet:

Cannot update to new versions
MCP integrations (ClickUp, GitHub) won't work
Cannot fetch library documentation (Context7)

Q10: How do I transfer AIOX to an air-gapped environment?

Answer:

On connected machine:

# Install and package
npx aiox-core install
cd your-project
tar -czvf aiox-transfer.tar.gz .aiox-core/ .claude/ .cursor/ docs/

Transfer the archive via USB, secure transfer, etc.

On air-gapped machine:

cd your-project
tar -xzvf aiox-transfer.tar.gz

Configure IDE manually if needed (paths may differ)

IDE & Configuration

Q11: Which IDEs does AIOX support?

Answer:

IDE	Status	Agent Activation
Claude Code	Full Support	`/dev`, `/qa`, etc.
Cursor	Full Support	`@dev`, `@qa`, etc.
Gemini CLI	Full Support	Mention in prompt
GitHub Copilot	Full Support	Chat modes

Adding support for a new IDE: Open a GitHub issue with the IDE's agent/rules specification.

Q12: Can I configure AIOX for multiple IDEs?

Answer: Yes! Select multiple IDEs during installation:

Interactive:

? Which IDE(s) do you want to configure?
❯ ◉ Cursor
  ◉ Claude Code

Command line:

Each IDE gets its own configuration directory:

.cursor/rules/ for Cursor
.claude/commands/ for Claude Code

Q13: How do I configure AIOX for a new team member?

Answer:

If .aiox-core/ is committed to your repository:

# New team member just clones
git clone your-repo
cd your-repo

# Optionally configure their preferred IDE
npx aiox-core install --ide cursor

If .aiox-core/ is not committed:

git clone your-repo
cd your-repo
npx aiox-core install

Best practice: Commit .aiox-core/ to share consistent agent configurations.

Agents & Workflows

Q14: What agents are included?

Answer: AIOX includes 11+ specialized agents:

Agent	Role	Best For
`dev`	Full-Stack Developer	Code implementation, debugging
`qa`	QA Engineer	Testing, code review
`architect`	System Architect	Design, architecture decisions
`pm`	Project Manager	Planning, tracking
`po`	Product Owner	Backlog, requirements
`sm`	Scrum Master	Facilitation, sprint management
`analyst`	Business Analyst	Requirements analysis
`ux-expert`	UX Designer	User experience design
`data-engineer`	Data Engineer	Data pipelines, ETL
`devops`	DevOps Engineer	CI/CD, deployment
`db-sage`	Database Architect	Schema design, queries

Q15: How do I create a custom agent?

Answer:

Copy an existing agent:

cp .aiox-core/agents/dev.md .aiox-core/agents/my-agent.md

Edit the YAML frontmatter:

agent:
  name: MyAgent
  id: my-agent
  title: My Custom Agent
  icon: 🔧

persona:
  role: Expert in [your domain]
  style: [communication style]

Add to IDE configuration:
```
npx aiox-core install --ide claude-code
```
Activate: /my-agent or @my-agent

Q16: What is "yolo mode"?

Answer: Yolo mode is autonomous development mode where the agent:

Implements story tasks without step-by-step confirmation
Makes decisions autonomously based on story requirements
Logs all decisions in .ai/decision-log-{story-id}.md
Can be stopped at any time

Enable yolo mode:

/dev
*develop-yolo docs/stories/your-story.md

When to use:

For well-defined stories with clear acceptance criteria
When you trust the agent's decision-making
For repetitive tasks

When NOT to use:

For complex architectural changes
When requirements are ambiguous
For production-critical code

Squads

Q17: What are Squads?

Answer: Starter squads are optional add-ons that extend AIOX capabilities:

Pack	Features
hybrid-ops	ClickUp integration, process automation, specialized workflows

Install an Squad:

npx aiox-core install --Squads hybrid-ops

List available packs:

npx aiox-core install

Q18: Can I create my own Squad?

Answer: Yes! Starter squads follow this structure:

my-expansion/
├── pack.yaml           # Pack manifest
├── README.md           # Documentation
├── agents/             # Custom agents
│   └── my-agent.md
├── tasks/              # Custom tasks
│   └── my-task.md
├── templates/          # Custom templates
│   └── my-template.yaml
└── workflows/          # Custom workflows
    └── my-workflow.yaml

pack.yaml example:

name: my-expansion
version: 1.0.0
description: My custom Squad
dependencies:
  aiox-core: ">=1.0.0"
agents:
  - my-agent
tasks:
  - my-task

Advanced Usage

Q19: How do I integrate AIOX with CI/CD?

Answer:

GitHub Actions example:

name: CI with AIOX
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
      - run: npx aiox-core install --full --ide claude-code
      - run: npm test

GitLab CI example:

test:
  image: node:18
  script:
    - npx aiox-core install --full
    - npm test

Q20: How do I customize core-config.yaml?

Answer: The core-config.yaml file controls framework behavior:

# Document sharding
prd:
  prdSharded: true
  prdShardedLocation: docs/prd

# Story location
devStoryLocation: docs/stories

# Files loaded by dev agent
devLoadAlwaysFiles:
  - docs/framework/coding-standards.md
  - docs/framework/tech-stack.md

# Git configuration
git:
  showConfigWarning: true
  cacheTimeSeconds: 300

# Project status in agent greetings
projectStatus:
  enabled: true
  showInGreeting: true

After editing, restart your IDE to apply changes.

Q21: How do I contribute to AIOX?

Answer:

Fork the repository: https://github.com/SynkraAI/aiox-core
Create a feature branch:
```
git checkout -b feature/my-feature
```
Make changes following coding standards:
- Read docs/framework/coding-standards.md
- Add tests for new features
- Update documentation
Submit a pull request:
- Describe your changes
- Link to related issues
- Wait for review

Types of contributions welcome:

Bug fixes
New agents
Documentation improvements
Starter squads
IDE integrations

Q22: Where can I get help?

Answer:

Resource	Link
Documentation	`docs/` in your project
Troubleshooting	troubleshooting.md
GitHub Issues	https://github.com/SynkraAI/aiox-core/issues
Source Code	https://github.com/SynkraAI/aiox-core

Before asking for help:

Check this FAQ
Check the Troubleshooting Guide
Search existing GitHub issues
Include system info and error messages in your question

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Synkra AIOX FAQ

Table of Contents

Installation Questions

Q1: Why npx instead of npm install -g?

Q2: What are the system requirements?

Q3: Can I install AIOX in an existing project?

Q4: How long does installation take?

Q5: What files does AIOX create in my project?

Updates & Maintenance

Q6: How do I update AIOX to the latest version?

Q7: How often should I update?

Q8: Can I rollback to a previous version?

Offline & Air-Gapped Usage

Q9: Can I use AIOX without internet?

Q10: How do I transfer AIOX to an air-gapped environment?

IDE & Configuration

Q11: Which IDEs does AIOX support?

Q12: Can I configure AIOX for multiple IDEs?

Q13: How do I configure AIOX for a new team member?

Agents & Workflows

Q14: What agents are included?

Q15: How do I create a custom agent?

Q16: What is "yolo mode"?

Squads

Q17: What are Squads?

Q18: Can I create my own Squad?

Advanced Usage

Q19: How do I integrate AIOX with CI/CD?

Q20: How do I customize core-config.yaml?

Q21: How do I contribute to AIOX?

Q22: Where can I get help?

Related Documentation

FilesExpand file tree

faq.md

Latest commit

History

faq.md

File metadata and controls

Synkra AIOX FAQ

Table of Contents

Installation Questions

Q1: Why npx instead of npm install -g?

Q2: What are the system requirements?

Q3: Can I install AIOX in an existing project?

Q4: How long does installation take?

Q5: What files does AIOX create in my project?

Updates & Maintenance

Q6: How do I update AIOX to the latest version?

Q7: How often should I update?

Q8: Can I rollback to a previous version?

Offline & Air-Gapped Usage

Q9: Can I use AIOX without internet?

Q10: How do I transfer AIOX to an air-gapped environment?

IDE & Configuration

Q11: Which IDEs does AIOX support?

Q12: Can I configure AIOX for multiple IDEs?

Q13: How do I configure AIOX for a new team member?

Agents & Workflows

Q14: What agents are included?

Q15: How do I create a custom agent?

Q16: What is "yolo mode"?

Squads

Q17: What are Squads?

Q18: Can I create my own Squad?

Advanced Usage

Q19: How do I integrate AIOX with CI/CD?

Q20: How do I customize core-config.yaml?

Q21: How do I contribute to AIOX?

Q22: Where can I get help?

Related Documentation