Skip to content

user-guide.md

Latest commit

 

History

History
452 lines (317 loc) · 11.8 KB

user-guide.md

File metadata and controls

452 lines (317 loc) · 11.8 KB
Raw

Guia de Usuario AIOX

ES | EN

Guia completa para usar Synkra AIOX - el Sistema Orquestado por IA para Desarrollo Full Stack.

Version: 2.1.0 Ultima Actualizacion: 2026-01-28

Inicio Rapido

Prerrequisitos

Antes de usar AIOX, asegurate de tener:

  • Node.js version 18.0.0 o superior
  • npm version 8.0.0 o superior
  • Git para control de versiones
  • Una clave API de proveedor de IA (Anthropic, OpenAI, o compatible)

Instalacion

# Nuevo proyecto (Greenfield)
npx aiox-core init my-project

# Proyecto existente (Brownfield)
cd existing-project
npx aiox-core install

Primeros Pasos

# Navegar a tu proyecto
cd my-project

# Listar agentes disponibles
aiox agents list

# Activar un agente
@dev

# Obtener ayuda
*help

Conceptos Fundamentales

Filosofia

"La Estructura es Sagrada. El Tono es Flexible."

AIOX proporciona estructura orquestada mientras permite flexibilidad en la comunicacion. Esto significa:

  • Fijo: Posiciones de plantillas, orden de secciones, formatos de metricas, estructura de archivos, workflows
  • Flexible: Mensajes de estado, eleccion de vocabulario, uso de emojis, personalidad, tono

La Diferencia AIOX

Desarrollo IA Tradicional AIOX
Agentes no coordinados 11 agentes especializados con roles claros
Resultados inconsistentes Workflows estructurados con quality gates
Contexto perdido entre sesiones Memoria persistente y aprendizaje
Reinventar la rueda Tasks, workflows y squads reutilizables

Agentes

AIOX incluye 11 agentes especializados, cada uno con un rol y personalidad distintos:

Agente ID Arquetipo Responsabilidad
Dex @dev Constructor Implementacion de codigo
Quinn @qa Guardian Aseguramiento de calidad
Aria @architect Arquitecto Arquitectura tecnica
Nova @po Visionario Backlog del producto
Kai @pm Equilibrador Estrategia del producto
River @sm Facilitador Facilitacion de procesos
Zara @analyst Explorador Analisis de negocio
Dara @data-engineer Arquitecto Ingenieria de datos
Felix @devops Optimizador CI/CD y operaciones
Uma @ux-expert Creador Experiencia de usuario
Pax @aiox-master Orquestador Orquestacion del framework

Activacion de Agentes

# Activar un agente usando sintaxis @
@dev                # Activar Dex (Desarrollador)
@qa                 # Activar Quinn (QA)
@architect          # Activar Aria (Arquitecto)
@aiox-master        # Activar Pax (Orquestador)

# Comandos de agentes usan prefijo *
*help               # Mostrar comandos disponibles
*task <name>        # Ejecutar task especifica
*exit               # Desactivar agente

Contexto del Agente

Cuando un agente esta activo:

  • Seguir la persona y experiencia especifica de ese agente
  • Usar los patrones de workflow designados del agente
  • Mantener la perspectiva del agente durante toda la interaccion

Tasks

Las Tasks son el punto de entrada principal en AIOX. Todo es una task.

Arquitectura Task-First

User Request --> Task --> Agent Execution --> Output
                  |
             Workflow (si multi-paso)

Ejecutando Tasks

# Ejecutar una task especifica
*task develop-story --story=1.1

# Listar tasks disponibles
aiox tasks list

# Obtener ayuda de task
*task --help

Categorias de Tasks

Categoria Ejemplos
Desarrollo develop-story, code-review, refactor
Calidad run-tests, validate-code, security-scan
Documentacion generate-docs, update-readme
Workflow create-story, manage-sprint

Workflows

Los workflows orquestan multiples tasks y agentes para operaciones complejas.

Workflows Disponibles

Workflow Caso de Uso Agentes Involucrados
greenfield-fullstack Nuevo proyecto full-stack Todos los agentes
brownfield-integration Agregar AIOX a existente dev, architect
fork-join Ejecucion de tasks en paralelo Multiples
organizer-worker Ejecucion delegada po, dev
data-pipeline Workflows ETL data-engineer, qa

Ejecutando Workflows

# Iniciar un workflow
aiox workflow greenfield-fullstack

# Con parametros
aiox workflow brownfield-integration --target=./existing-project

Squads

Los Squads son equipos modulares de agentes IA que extienden la funcionalidad de AIOX.

Que es un Squad?

Un squad es un paquete autocontenido que contiene:

Componente Proposito
Agents Personas IA especificas del dominio
Tasks Workflows ejecutables
Workflows Orquestaciones multi-paso
Config Estandares de codigo, tech stack
Templates Plantillas de generacion de documentos
Tools Integraciones de herramientas personalizadas

Niveles de Distribucion

Nivel 1: LOCAL        --> ./squads/           (Privado)
Nivel 2: AIOX-SQUADS  --> github.com/SynkraAI (Publico/Gratis)
Nivel 3: SYNKRA API   --> api.synkra.dev      (Marketplace)

Usando Squads

# Listar squads disponibles
aiox squads list

# Descargar un squad
aiox squads download etl-squad

# Crear tu propio squad
@squad-creator
*create-squad my-custom-squad

Squads Oficiales

Squad Descripcion
etl-squad Recoleccion y transformacion de datos
creator-squad Utilidades de generacion de contenido

Uso Basico

Estructura del Proyecto

my-project/
├── .aiox-core/                # Configuracion del framework
│   ├── development/agents/    # Definiciones de agentes
│   ├── development/tasks/     # Workflows de tasks
│   ├── product/templates/     # Plantillas de documentos
│   └── product/checklists/    # Checklists de validacion
├── docs/
│   ├── stories/               # Stories de desarrollo
│   ├── architecture/          # Arquitectura del sistema
│   └── guides/                # Guias de usuario
├── squads/                    # Squads locales
└── src/                       # Codigo fuente de la aplicacion

Comandos Comunes

# Comandos de AIOX Master
*help                # Mostrar comandos disponibles
*create-story        # Crear nueva story
*task {name}         # Ejecutar task especifica
*workflow {name}     # Ejecutar workflow

# Comandos de Desarrollo
npm run dev          # Iniciar desarrollo
npm test             # Ejecutar tests
npm run lint         # Verificar estilo de codigo
npm run build        # Construir proyecto

Desarrollo Basado en Stories

  1. Crear una story - Usar *create-story para definir requisitos
  2. Trabajar desde stories - Todo desarrollo comienza con una story en docs/stories/
  3. Actualizar progreso - Marcar checkboxes cuando las tasks completen: [ ] --> [x]
  4. Rastrear cambios - Mantener la seccion File List en la story
  5. Seguir criterios - Implementar exactamente lo que los criterios de aceptacion especifican

Configuracion

Archivo de Configuracion Principal

La configuracion principal esta en .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

Variables de Entorno

# Configuracion del Proveedor de IA
ANTHROPIC_API_KEY=your-anthropic-api-key
# o
OPENAI_API_KEY=your-openai-api-key

# Configuraciones del Framework
NODE_ENV=development
AIOX_DEBUG=false

Integracion con IDE

AIOX soporta multiples IDEs. La configuracion se sincroniza a traves de:

  • Claude Code (.claude/)
  • Cursor (.cursor/)
  • VS Code (.vscode/)
# Sincronizar agentes a tu IDE
npm run sync:ide

Solucion de Problemas

Problemas Comunes

El agente no se activa

# Verificar que el agente existe
ls .aiox-core/development/agents/

# Verificar configuracion
aiox doctor

La ejecucion de task falla

# Verificar definicion de task
cat .aiox-core/development/tasks/{task-name}.md

# Ejecutar con salida detallada
*task {name} --verbose

Problemas de memoria/contexto

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

# Reconstruir indice
aiox rebuild

Obteniendo Ayuda

Proximos Pasos

Ruta de Aprendizaje

  1. Inicio Rapido - Seguir esta guia para comenzar
  2. Referencia de Agentes - Aprender sobre las capacidades de cada agente: Guia de Referencia de Agentes
  3. Arquitectura - Entender el sistema: Vision General de Arquitectura
  4. Squads - Extender funcionalidad: Guia de Squads

Temas Avanzados

Mejores Practicas

1. Comenzar con Stories

Siempre crear una story antes de implementar funcionalidades:

@aiox-master
*create-story

2. Usar el Agente Correcto

Elegir el agente apropiado para cada task:

Task Agente
Escribir codigo @dev
Revisar codigo @qa
Disenar sistema @architect
Definir requisitos @po

3. Seguir Quality Gates

AIOX implementa quality gates de 3 capas:

  1. Capa 1 (Local): Pre-commit hooks, linting, verificacion de tipos
  2. Capa 2 (CI/CD): Tests automatizados, review de CodeRabbit
  3. Capa 3 (Humano): Review de arquitectura, aprobacion final

4. Mantener Contexto

Mantener contexto a traves de sesiones mediante:

  • Usar desarrollo basado en stories
  • Actualizar checkboxes de progreso
  • Documentar decisiones en stories

5. Aprovechar Squads

No reinventar la rueda - verificar squads existentes:

aiox squads search {keyword}

Documentacion Relacionada

Guia de Usuario Synkra AIOX v4.0